From d7fdcf7fc8a2a0283dc4ad4848e171e83792c176 Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Fri, 18 Sep 2026 18:05:52 +0800
Subject: [PATCH] =?UTF-8?q?fix(worker-deploy):=20a=20deploy=20runs=20once?=
 =?UTF-8?q?=20=E2=80=94=20no=20step=20retries,=20step=20timeout=20above=20?=
 =?UTF-8?q?the=20exec's?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The exec step passes explicit StepOpts: `retries: 0` and a step timeout of
the exec timeout + 120s. Without them it inherits the Workflows defaults
(600s step timeout, platform retries), so a deploy over ten minutes ran
again in the same container and published every Worker twice.

- `worker-deploy.timeoutSec:<repo>` sets the webhook-mode exec timeout
  (dispatch value → KV → 900).
- `checkLabel` names a second deploy of one commit
  `flare-dispatch/worker-deploy:<label>`; a command-less labelled dispatch
  reads only `worker-deploy.command:<repo>:<label>`.
- The Action folds `inputs.checkLabel` into its `Idempotency-Key`, so two
  labelled dispatches of one run and commit stay two executions.
- Header comments: the Action and webhook ids never collapsed, and the
  checkout's origin carries no credential.
---
 actions/flare-dispatch-action/README.md       |   2 +
 actions/flare-dispatch-action/dispatch.bats   |  22 +++
 actions/flare-dispatch-action/dispatch.sh     |  21 ++-
 apps/dispatcher/src/index.test.ts             |  29 +++
 .../runtime-cf/src/step-runner-cf.test.ts     |   9 +
 runs/README.md                                |  69 +++++++
 runs/worker-deploy.test.ts                    | 142 ++++++++++++++-
 runs/worker-deploy.ts                         | 171 ++++++++++++++----
 8 files changed, 426 insertions(+), 39 deletions(-)

diff --git a/actions/flare-dispatch-action/README.md b/actions/flare-dispatch-action/README.md
index 86d0774..1357d26 100644
--- a/actions/flare-dispatch-action/README.md
+++ b/actions/flare-dispatch-action/README.md
@@ -60,6 +60,8 @@ branch protection can't gate it. The action reads `pull_request.head.sha` from
 the event payload so the verdict lands on the commit the author pushed, falling
 back to `GITHUB_SHA` for push events. The same head SHA keys the
 `Idempotency-Key`, so a step re-run collapses onto one execution per head commit.
+An `inputs.checkLabel` joins the key (`<run>-<label>-<repo>-<sha12>`), so two
+steps dispatching one run with different labels stay two executions.
 
 ## Collecting signals (`collect-command`)
 
diff --git a/actions/flare-dispatch-action/dispatch.bats b/actions/flare-dispatch-action/dispatch.bats
index dd2e7f1..fbc8a96 100644
--- a/actions/flare-dispatch-action/dispatch.bats
+++ b/actions/flare-dispatch-action/dispatch.bats
@@ -100,3 +100,25 @@ setup() {
     bash -c 'source "$SCRIPT"; set +o pipefail; printf "%s" "$J" | signals_invalid_reason'
   [[ "$output" == *'source exceeds 120 chars'* ]]
 }
+
+# --- compute_targets: idempotency key ----------------------------------------
+
+@test "compute_targets keys an unlabelled dispatch as run-repo-sha12" {
+  run env GITHUB_REPOSITORY=owner/name INPUT_RUN=worker-deploy ENDPOINT=https://d.example \
+    bash -c 'source "$SCRIPT"; SHA=0123456789abcdef; INPUTS="{\"repo\":\"owner/name\"}"; compute_targets; echo "$IDEMPOTENCY_KEY"'
+  [ "$status" -eq 0 ]
+  [ "$output" = "worker-deploy-owner_name-0123456789ab" ]
+}
+
+@test "compute_targets folds checkLabel into the key so labelled dispatches stay distinct" {
+  run env GITHUB_REPOSITORY=owner/name INPUT_RUN=worker-deploy ENDPOINT=https://d.example \
+    bash -c 'source "$SCRIPT"; SHA=0123456789abcdef; INPUTS="{\"checkLabel\":\"containers\"}"; compute_targets; echo "$IDEMPOTENCY_KEY"'
+  [ "$status" -eq 0 ]
+  [ "$output" = "worker-deploy-containers-owner_name-0123456789ab" ]
+}
+
+@test "compute_targets ignores a non-string checkLabel" {
+  run env GITHUB_REPOSITORY=owner/name INPUT_RUN=check ENDPOINT=https://d.example \
+    bash -c 'source "$SCRIPT"; SHA=0123456789abcdef; INPUTS="{\"checkLabel\":7}"; compute_targets; echo "$IDEMPOTENCY_KEY"'
+  [ "$output" = "check-owner_name-0123456789ab" ]
+}
diff --git a/actions/flare-dispatch-action/dispatch.sh b/actions/flare-dispatch-action/dispatch.sh
index 0b67c40..47afd3f 100755
--- a/actions/flare-dispatch-action/dispatch.sh
+++ b/actions/flare-dispatch-action/dispatch.sh
@@ -9,7 +9,7 @@
 #
 #   POST ${endpoint}/v1/dispatch/${run}
 #     X-FlareDispatch-Signature: sha256=<hex over the RAW body bytes>
-#     Idempotency-Key: <run>-<repo>-<sha12>
+#     Idempotency-Key: <run>[-<checkLabel>]-<repo>-<sha12>
 #   202 { executionId, detailsUrl?, logsUrl? }   → outputs, success
 #   401                                           → HMAC drift, no retry
 #   400 / 404                                     → config bug, no retry
@@ -300,14 +300,25 @@ sign_body() {
 }
 
 # --- idempotency key + URL ---------------------------------------------------
-# {run}-{repo}-{sha12} so a re-run of the same step collapses onto one execution
-# at the receiver. Randomized fallback when repo/sha are absent (local act runs).
+# {run}[-{checkLabel}]-{repo}-{sha12} so a re-run of the same step collapses
+# onto one execution at the receiver, while two steps dispatching one run with
+# different `checkLabel`s stay two executions — the label names a separate
+# check-run, so collapsing them would leave the second check never posted.
+# Randomized fallback when repo/sha are absent (local act runs).
 # Sets $IDEMPOTENCY_KEY and $URL.
 
+# Print `-<checkLabel>` when the inputs JSON on stdin carries a string
+# `checkLabel`, else nothing. Pure.
+check_label_suffix() {
+  jq -r 'if (.checkLabel | type) == "string" and (.checkLabel | length) > 0
+         then "-\(.checkLabel)" else "" end'
+}
+
 compute_targets() {
   if [ -n "${GITHUB_REPOSITORY:-}" ] && [ -n "$SHA" ]; then
-    local repo_safe="${GITHUB_REPOSITORY//\//_}"
-    IDEMPOTENCY_KEY="${INPUT_RUN}-${repo_safe}-${SHA:0:12}"
+    local repo_safe="${GITHUB_REPOSITORY//\//_}" label
+    label="$(check_label_suffix <<<"${INPUTS:-null}")"
+    IDEMPOTENCY_KEY="${INPUT_RUN}${label}-${repo_safe}-${SHA:0:12}"
   else
     IDEMPOTENCY_KEY="${INPUT_RUN}-$(date +%s)-${RANDOM}"
   fi
diff --git a/apps/dispatcher/src/index.test.ts b/apps/dispatcher/src/index.test.ts
index 15b069e..a1f6c47 100644
--- a/apps/dispatcher/src/index.test.ts
+++ b/apps/dispatcher/src/index.test.ts
@@ -13,6 +13,7 @@
 // Plus the artifact endpoint (streams the R2 object) and /health.
 
 import { describe, expect, it } from "vitest";
+import { checkRunNameFor } from "./check-name";
 import { handleRequest } from "./router";
 import { fingerprint, sign } from "./hmac";
 import { makeFakeEnv, makeFakeKv, makeFakeR2, makeFakeWorkflow } from "./test-helpers";
@@ -651,6 +652,34 @@ describe("POST /v1/dispatch/:run — dedup", () => {
     expect(workflow.calls[0]!.id).toBe("check_owner_test-repo_abc123def456");
   });
 
+  it("a labelled worker-deploy dispatch keeps its label through decode — own check-run name, own execution", async () => {
+    // A second deploy of one commit (e.g. container Workers after an image
+    // build) must not post under the webhook deploy's `flare-dispatch/worker-deploy`.
+    // The label reaches the Workflow only if the run's schema declares it —
+    // an undeclared key is stripped by the decode, and the check-run would
+    // then be named as if unlabelled.
+    const { env, workflow } = fixture();
+    const bodyText = JSON.stringify({
+      ...validBody,
+      run: "worker-deploy",
+      inputs: {
+        repo: "owner/test-repo",
+        sha: "abc123def456",
+        command: "pnpm deploy:containers",
+        checkLabel: "containers",
+      },
+    });
+    const res = await handleRequest(await dispatchRequest("worker-deploy", bodyText), env);
+    expect(res.status).toBe(202);
+
+    const params = workflow.calls[0]!.params as { inputs: Record<string, unknown> };
+    expect(params.inputs.checkLabel).toBe("containers");
+    expect(checkRunNameFor("worker-deploy", params.inputs)).toBe(
+      "flare-dispatch/worker-deploy:containers",
+    );
+    expect(workflow.calls[0]!.id).toBe("worker-deploy_containers_owner_test-repo_abc123def456");
+  });
+
   it("without IDEMPOTENCY_KV bound, semantic id is still used — duplicate Workflow.create is the dedup", async () => {
     const { env, workflow } = fixture();
     const bodyText = JSON.stringify(validBody);
diff --git a/packages/runtime-cf/src/step-runner-cf.test.ts b/packages/runtime-cf/src/step-runner-cf.test.ts
index e671afa..4cc9973 100644
--- a/packages/runtime-cf/src/step-runner-cf.test.ts
+++ b/packages/runtime-cf/src/step-runner-cf.test.ts
@@ -45,6 +45,15 @@ describe("buildStepConfig", () => {
     });
   });
 
+  it("maps retries: 0 to limit 0 — a never-retry step does not fall back to CF's default retries", () => {
+    // `worker-deploy`'s exec step relies on this: a falsy check here would drop
+    // the policy and hand a deploy command CF's default retries.
+    expect(buildStepConfig({ timeoutSec: 1020, retries: 0 })).toEqual({
+      timeout: "1020 seconds",
+      retries: { limit: 0, delay: "5 seconds", backoff: "exponential" },
+    });
+  });
+
   it("treats timeoutSec: 0 as set (a deliberate zero timeout)", () => {
     // 0 !== undefined, so it is honored — a run that asks for 0 gets "0 seconds"
     // rather than silently falling back to CF's default.
diff --git a/runs/README.md b/runs/README.md
index f66ba0c..53e617e 100644
--- a/runs/README.md
+++ b/runs/README.md
@@ -400,3 +400,72 @@ Use it when the stages are independent (different feature unifications of one
 tree, say). Leave it at 1 when a later stage consumes an earlier one's output,
 which sharing a container is the only way to express. A value above the stage
 count is clamped to it.
+
+## `worker-deploy` — continuous deploy on default-branch push
+
+Webhook mode fires on `check_suite.requested` for the default branch, resolves
+everything a push payload cannot carry from CONFIG_KV, and posts
+`flare-dispatch/worker-deploy`. No command key → the run no-ops green.
+
+```bash
+wrangler kv key put --binding=CONFIG_KV \
+  "worker-deploy.command:owner/repo"    "pnpm build && pnpm exec wrangler deploy"
+wrangler kv key put --binding=CONFIG_KV \
+  "worker-deploy.secrets:owner/repo"    "CLOUDFLARE_API_TOKEN"   # Worker-secret NAMES
+wrangler kv key put --binding=CONFIG_KV \
+  "worker-deploy.timeoutSec:owner/repo" "1500"                   # positive integer
+```
+
+`timeoutSec` precedence is dispatch value → `worker-deploy.timeoutSec:<repo>` → 900. A malformed value degrades to 900.
+
+**A deploy is never step-retried.** The `exec` step runs with `retries: 0` and a
+Workflow step timeout of the exec timeout + 120s, so the sandbox's deadline —
+not the platform's 600s step default — ends a slow deploy, and a failure is
+reported once instead of re-publishing every Worker on a second attempt.
+
+### A second deploy of the same commit (`checkLabel`)
+
+A repo that deploys part of its stack after other CI work — container-backed
+Workers after an image build, say — dispatches `worker-deploy` a second time in
+Action mode with a `checkLabel`. It posts `flare-dispatch/worker-deploy:<label>`
+beside the webhook's check instead of overwriting it, and runs as its own
+execution (the label is part of both the Action's `Idempotency-Key` and the
+direct-dispatch instance id).
+
+A labelled dispatch without `command` reads only
+`worker-deploy.command:<repo>:<label>` — never the unlabelled key, which would
+re-run the webhook's deploy. `worker-deploy.timeoutSec:<repo>:<label>` falls
+back to the repo key.
+
+```yaml
+- uses: fractalboxdev/flare-dispatch/actions/flare-dispatch-action@<sha>
+  with:
+    run: worker-deploy
+    endpoint: ${{ vars.FLAREDISPATCH_ENDPOINT }}
+    hmac-secret: ${{ secrets.FLAREDISPATCH_HMAC }}
+    inputs: |
+      {
+        "repo": "${{ github.repository }}",
+        "sha": "${{ github.sha }}",
+        "checkLabel": "containers",
+        "failOnNonZeroExit": true
+      }
+```
+
+A webhook dispatch and an Action dispatch of one push are always two executions:
+the webhook's instance id is `worker-deploy_<repo_>_<sha12>`, the Action's is
+`worker-deploy[-<label>]-<repo_>-<sha12>`.
+
+### Deploy ordering
+
+Two rapid pushes deploy in completion order, not push order. A command that
+guards against an older push landing last compares `HEAD` to the branch tip —
+but the checkout's `origin` carries no credential (the sandbox scrubs it after
+the clone), so `git ls-remote origin` works only on a repo readable
+anonymously. Make the guard fail closed when the lookup fails, or a private repo
+skips every deploy green:
+
+```bash
+tip=$(git ls-remote origin refs/heads/main) && [ -n "$tip" ] || exit 1
+[ "${tip%%[[:space:]]*}" = "$(git rev-parse HEAD)" ] || exit 0
+```
diff --git a/runs/worker-deploy.test.ts b/runs/worker-deploy.test.ts
index b46c7c4..00ef904 100644
--- a/runs/worker-deploy.test.ts
+++ b/runs/worker-deploy.test.ts
@@ -18,6 +18,11 @@
 //                          a non-zero exit into `AcceptanceFailed`
 //   (f) trigger mapping — the `check_suite.requested` payload maps to inputs;
 //                          the gate admits only the default branch
+//   (g) step opts       — the exec step carries `retries: 0` and a step
+//                          timeout of the exec timeout + headroom
+//   (h) timeout key     — `worker-deploy.timeoutSec:<repo>` sets the webhook
+//                          exec timeout; a dispatched value wins
+//   (i) checkLabel      — a labelled dispatch reads only its labelled command
 //
 // Plus the standard determinism source guard.
 //
@@ -26,7 +31,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { it } from "@effect/vitest";
-import { Cause, Effect, Exit, Option } from "effect";
+import { Cause, Effect, Either, Exit, Option, Schema } from "effect";
 import { describe, expect } from "vitest";
 import { makeCFRuntimeTest } from "@fractalboxdev/flare-dispatch-core/testing";
 import { workerDeploy } from "./worker-deploy";
@@ -278,6 +283,141 @@ describe("worker-deploy", () => {
     },
   );
 
+  // --- exec StepOpts — a deploy is never step-retried --------------------------
+
+  const execStepOf = (steps: ReadonlyArray<{ name: string; metadata?: Record<string, unknown> }>) =>
+    steps.find((s) => s.name === "exec");
+
+  it.effect("exec StepOpts — retries 0 and a step timeout above the default exec timeout", () => {
+    const { layer, handles } = makeCFRuntimeTest({
+      sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+    });
+    return Effect.gen(function* () {
+      yield* workerDeploy.run(baseInput);
+      const exec = execStepOf(handles.executions.steps);
+      // Unset, the step inherits CF Workflows' 600s timeout + default
+      // retries, and a deploy over 600s publishes twice.
+      expect(exec?.metadata?.["stepOpts.retries"]).toBe(0);
+      expect(exec?.metadata?.["stepOpts.timeoutSec"]).toBe(900 + 120);
+      expect(exec?.metadata?.["stepOpts.retryOn"]).toBeUndefined();
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("exec StepOpts — the step timeout tracks a dispatched timeoutSec", () => {
+    const { layer, handles } = makeCFRuntimeTest({
+      sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+    });
+    return Effect.gen(function* () {
+      yield* workerDeploy.run({ ...baseInput, timeoutSec: 1500 });
+      const exec = execStepOf(handles.executions.steps);
+      expect(exec?.metadata?.["stepOpts.timeoutSec"]).toBe(1500 + 120);
+      expect(exec?.metadata?.["stepOpts.retries"]).toBe(0);
+      expect(handles.sandbox.execs.find((e) => e.command === DEPLOY_CMD)?.timeoutSec).toBe(1500);
+    }).pipe(Effect.provide(layer));
+  });
+
+  // --- worker-deploy.timeoutSec:<repo> — the webhook-mode timeout knob --------
+
+  const webhookInput = {
+    repo: "owner/name",
+    sha: "abc123",
+    secrets: [] as readonly string[],
+    install: false,
+    failOnNonZeroExit: true,
+  };
+
+  it.effect("timeoutSec — a webhook dispatch reads `worker-deploy.timeoutSec:<repo>`", () => {
+    const { layer, handles } = makeCFRuntimeTest({
+      sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+      config: {
+        "worker-deploy.command:owner/name": DEPLOY_CMD,
+        "worker-deploy.timeoutSec:owner/name": "1500",
+      },
+    });
+    return Effect.gen(function* () {
+      yield* workerDeploy.run(webhookInput);
+      expect(handles.sandbox.execs.find((e) => e.command === DEPLOY_CMD)?.timeoutSec).toBe(1500);
+      expect(execStepOf(handles.executions.steps)?.metadata?.["stepOpts.timeoutSec"]).toBe(
+        1500 + 120,
+      );
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("timeoutSec — a dispatched value wins over the config key", () => {
+    const { layer, handles } = makeCFRuntimeTest({
+      sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+      config: { "worker-deploy.timeoutSec:owner/name": "1500" },
+    });
+    return Effect.gen(function* () {
+      yield* workerDeploy.run({ ...baseInput, timeoutSec: 300 });
+      expect(handles.sandbox.execs.find((e) => e.command === DEPLOY_CMD)?.timeoutSec).toBe(300);
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("timeoutSec — a malformed config value degrades to the 900s default", () => {
+    const { layer, handles } = makeCFRuntimeTest({
+      sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+      config: {
+        "worker-deploy.command:owner/name": DEPLOY_CMD,
+        "worker-deploy.timeoutSec:owner/name": "25m",
+      },
+    });
+    return Effect.gen(function* () {
+      yield* workerDeploy.run(webhookInput);
+      expect(handles.sandbox.execs.find((e) => e.command === DEPLOY_CMD)?.timeoutSec).toBe(900);
+    }).pipe(Effect.provide(layer));
+  });
+
+  // --- checkLabel — a second deploy of one commit -----------------------------
+
+  it.effect(
+    "checkLabel — a command-less labelled dispatch reads ONLY its labelled command key",
+    () => {
+      const LABELLED_CMD = "pnpm deploy:containers";
+      const { layer, handles } = makeCFRuntimeTest({
+        sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 }, [LABELLED_CMD]: { exitCode: 0 } },
+        config: {
+          "worker-deploy.command:owner/name": DEPLOY_CMD,
+          "worker-deploy.command:owner/name:containers": LABELLED_CMD,
+          "worker-deploy.timeoutSec:owner/name": "1500",
+        },
+      });
+      return Effect.gen(function* () {
+        yield* workerDeploy.run({ ...webhookInput, checkLabel: "containers" });
+        expect(handles.sandbox.execs.map((e) => e.command)).toContain(LABELLED_CMD);
+        expect(handles.sandbox.execs.map((e) => e.command)).not.toContain(DEPLOY_CMD);
+        // The timeout, unlike the command, falls back to the repo key.
+        expect(handles.sandbox.execs.find((e) => e.command === LABELLED_CMD)?.timeoutSec).toBe(
+          1500,
+        );
+      }).pipe(Effect.provide(layer));
+    },
+  );
+
+  it.effect(
+    "checkLabel — no labelled command no-ops rather than re-running the unlabelled deploy",
+    () => {
+      const { layer, handles } = makeCFRuntimeTest({
+        sandboxProgram: { [DEPLOY_CMD]: { exitCode: 0 } },
+        config: { "worker-deploy.command:owner/name": DEPLOY_CMD },
+      });
+      return Effect.gen(function* () {
+        const result = yield* workerDeploy.run({ ...webhookInput, checkLabel: "containers" });
+        expect(result.skippedReason).toBe("not-configured");
+        expect(handles.sandbox.execs).toHaveLength(0);
+      }).pipe(Effect.provide(layer));
+    },
+  );
+
+  it("checkLabel — the input schema keeps a valid label and rejects a malformed one", () => {
+    const decode = Schema.decodeUnknownEither(workerDeploy.inputs);
+    const ok = decode({ repo: "owner/name", sha: "abc123", checkLabel: "containers" });
+    expect(Either.isRight(ok) && ok.right.checkLabel).toBe("containers");
+    expect(Either.isLeft(decode({ repo: "owner/name", sha: "abc123", checkLabel: "a b" }))).toBe(
+      true,
+    );
+  });
+
   // --- Webhook trigger — check_suite as the default-branch push signal --------
 
   const checkSuitePayload = (overrides: Record<string, unknown> = {}): Record<string, unknown> => ({
diff --git a/runs/worker-deploy.ts b/runs/worker-deploy.ts
index de0901a..dbfc7ca 100644
--- a/runs/worker-deploy.ts
+++ b/runs/worker-deploy.ts
@@ -56,13 +56,45 @@
 // `loadSecrets` resolves via the `secrets` capability (Worker string
 // bindings only — no CONFIG_KV). Commands + secret *names* stay in KV.
 //
+// --- A deploy is never step-retried -------------------------------------------
+//
+// The `exec` step carries explicit StepOpts: `retries: 0`, and a step timeout
+// of the exec timeout plus headroom. Left bare, the step inherits Cloudflare
+// Workflows' defaults — a 10-minute step timeout and several retries — so a
+// deploy command that outruns 600s is killed at the step boundary and run
+// AGAIN in the same container (its log lands as `exec-2.ndjson`), publishing
+// every Worker a second time. A deploy is not idempotent the way a test is:
+// each attempt ships a new version. So no failure class is retried here, not
+// even a platform `StepFailed` — a killed step may already have published.
+//
+// --- Several deploys of one commit: `checkLabel` ------------------------------
+//
+// A repo can deploy one SHA more than once with different work — the webhook
+// deploys its Workers, and an Action-mode dispatch deploys container-backed
+// Workers after a GHA image build. Both would post `flare-dispatch/worker-deploy`
+// and overwrite each other's verdict. A `checkLabel` names the second one
+// `flare-dispatch/worker-deploy:<label>` (apps/dispatcher/src/check-name.ts),
+// and folds into both the Action's `Idempotency-Key` and the direct-dispatch
+// instance id, so it stays its own execution.
+//
+// A labelled dispatch that omits `command` reads ONLY
+// `worker-deploy.command:<repo>:<label>` — never the unlabelled key. Unlike
+// `check`'s ladder, falling back would re-run the webhook's deploy under a
+// second name.
+//
 // --- Deploy ordering ----------------------------------------------------------
 //
 // Two rapid pushes dispatch two executions keyed by SHA; completion order is
 // not guaranteed, so the older push can in principle deploy last. A repo where
-// that matters guards inside its command — the checkout has an authenticated
-// `origin`, so a one-liner works (see recipes/worker-deploy/README.md):
-//   [ "$(git ls-remote origin refs/heads/main | cut -f1)" = "$(git rev-parse HEAD)" ] || exit 0
+// that matters guards inside its command. The checkout's `origin` is the
+// UNAUTHENTICATED `https://github.com/<owner>/<name>.git` — the sandbox scrubs
+// the clone credential (packages/runtime-cf/src/sandbox-cf.ts,
+// `scrubCloneCredential`) — so `git ls-remote origin` answers only for a repo
+// readable anonymously. On a private repo it fails, and a guard of the shape
+// `[ "$(git ls-remote …)" = "$(git rev-parse HEAD)" ] || exit 0` then skips
+// EVERY deploy green. A guard must fail closed when the lookup fails:
+//   tip=$(git ls-remote origin refs/heads/main) && [ -n "$tip" ] || exit 1
+//   [ "${tip%%[[:space:]]*}" = "$(git rev-parse HEAD)" ] || exit 0
 //
 // Spec: specs/02-runs.md § worker-deploy, specs/04-gha-integration.md
 // § Webhook mode.
@@ -91,6 +123,15 @@ const WorkerDeployInput = Schema.Struct({
    * No per-repo key → the run no-ops green (see header).
    */
   command: Schema.optional(Schema.String),
+  /**
+   * Names a second deploy of the same commit: the check-run posts as
+   * `flare-dispatch/worker-deploy:<label>` and a command-less dispatch reads
+   * `worker-deploy.command:<repo>:<label>` (see header). Same pattern as
+   * `check`'s label, so a malformed one is a 400 at dispatch.
+   */
+  checkLabel: Schema.optional(
+    Schema.String.pipe(Schema.pattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/)),
+  ),
   image: Schema.optional(Schema.String), // container image override
   /** Run the R2-cached dependency install after the clone. */
   install: Schema.optionalWith(Schema.Boolean, { default: () => false }),
@@ -117,7 +158,8 @@ const WorkerDeployInput = Schema.Struct({
    * removed with `secrets` at the substrate stage-2 exit (ADR-0006).
    */
   secretPrefix: Schema.optional(Schema.String),
-  timeoutSec: Schema.optional(Schema.Number), // default 900
+  /** `sandbox.exec` timeout. Omitted → `worker-deploy.timeoutSec:<repo>` → 900. */
+  timeoutSec: Schema.optional(Schema.Number),
   /**
    * Fail the run Effect (→ red check) on a non-zero exit. Webhook mode sets
    * this true — the check-run is the only signal a deploy failed. Action mode
@@ -142,14 +184,55 @@ const WorkerDeployOutput = Schema.Struct({
 /** Default `exec` timeout — a build + `wrangler deploy` fits comfortably. */
 const TIMEOUT_SEC_DEFAULT = 900;
 
-/** CONFIG_KV keys — all strictly per-repo (see header: no global fallback). */
-const commandKey = (repo: string): string => `worker-deploy.command:${repo}`;
+/**
+ * Headroom added to the exec timeout to derive the Workflow STEP timeout, so
+ * the sandbox's own deadline fires first (a clean `ExecTimeout` with the log
+ * so far) instead of the platform killing the step. Same constant as
+ * `offload-test` / `check`.
+ */
+const STEP_TIMEOUT_HEADROOM_SEC = 120;
+
+/** Decoded input — pins the trigger's `inputs` return to the full shape. */
+type WorkerDeployI = Schema.Schema.Type<typeof WorkerDeployInput>;
+
+/**
+ * CONFIG_KV keys — all strictly per-repo (see header: no global fallback). A
+ * labelled dispatch's command key is its own, with no unlabelled fallback.
+ */
+const commandKey = (repo: string, checkLabel?: string): string =>
+  checkLabel === undefined
+    ? `worker-deploy.command:${repo}`
+    : `worker-deploy.command:${repo}:${checkLabel}`;
 const secretsKey = (repo: string): string => `worker-deploy.secrets:${repo}`;
 const secretPrefixKey = (repo: string): string => `worker-deploy.secret-prefix:${repo}`;
 
+/**
+ * Per-repo exec timeout, for webhook dispatches — the trigger's `inputs` is
+ * sync + payload-only and cannot carry one, so without this key webhook mode
+ * is pinned to 900s:
+ *
+ *   wrangler kv key put --binding=CONFIG_KV "worker-deploy.timeoutSec:owner/repo" "1500"
+ *
+ * A labelled dispatch reads `…:<repo>:<label>` first and falls back to the
+ * repo key — a timeout, unlike a command, is safe to share. A dispatch that
+ * passes `timeoutSec` wins over both.
+ */
+const timeoutKeys = (repo: string, checkLabel: string | undefined): readonly string[] =>
+  checkLabel === undefined
+    ? [`worker-deploy.timeoutSec:${repo}`]
+    : [`worker-deploy.timeoutSec:${repo}:${checkLabel}`, `worker-deploy.timeoutSec:${repo}`];
+
+/** A positive integer, or `undefined` for absent/garbage — never `NaN`. */
+const parseIntConfig = (raw: string | undefined): number | undefined => {
+  const n = Number(raw?.trim());
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+};
+
 export const workerDeploy = defineRun({
   name: "worker-deploy",
-  version: "1.0.0",
+  // 1.1.0 — additive: `checkLabel`, `worker-deploy.timeoutSec:<repo>`, and
+  // explicit exec StepOpts (no step retries, step timeout ≥ exec timeout).
+  version: "1.1.0",
 
   // Webhook-mode trigger — `check_suite.requested` is GitHub's per-push signal
   // to checks-writing Apps (see header). Gated to the repo's default branch.
@@ -157,8 +240,12 @@ export const workerDeploy = defineRun({
     {
       event: "check_suite",
       actions: ["requested"],
-      // Semantic instanceId (`{run}:{repo_}:{sha12}`) — a webhook- and an
-      // Action-mode dispatch of the same push collapse to one execution.
+      // Instance id `worker-deploy_{repo_}_{sha12}` — dedups webhook
+      // redeliveries of one push. It does NOT collapse with an Action-mode
+      // dispatch: the Action sends `Idempotency-Key: worker-deploy-{repo_}-{sha12}`
+      // (hyphens, actions/flare-dispatch-action/dispatch.sh), a distinct id, so
+      // both deploys run. Only a direct dispatch WITHOUT that header lands on
+      // this id (routes/dispatch.ts `semanticInstanceId`).
       idempotencyKey: ({ payload }) =>
         `worker-deploy:${String(payload.repository?.full_name ?? "unknown/unknown").replace(
           /\//g,
@@ -167,7 +254,7 @@ export const workerDeploy = defineRun({
       gate: ({ payload }) =>
         typeof payload.check_suite?.head_branch === "string" &&
         payload.check_suite.head_branch === payload.repository?.default_branch,
-      inputs: ({ payload }) => ({
+      inputs: ({ payload }): WorkerDeployI => ({
         repo: String(payload.repository?.full_name ?? "unknown/unknown"),
         sha: String(payload.check_suite?.head_sha ?? ""),
         branch: String(payload.check_suite?.head_branch ?? ""),
@@ -189,13 +276,24 @@ export const workerDeploy = defineRun({
 
   run: (input) =>
     Effect.gen(function* () {
-      // resolve-config — the per-repo deploy command + secret key NAMES (never
-      // values: this step's return is checkpointed). Missing command → the
-      // repo hasn't opted in; no-op green rather than failing every push of
-      // every installed repo.
+      // resolve-config — the per-repo deploy command, exec timeout, and secret
+      // key NAMES (never values: this step's return is checkpointed). Missing
+      // command → the repo hasn't opted in; no-op green rather than failing
+      // every push of every installed repo.
+      const cmdKey = commandKey(input.repo, input.checkLabel);
       const cfg = yield* step("resolve-config", () =>
         Effect.gen(function* () {
-          const command = input.command ?? (yield* config.get(commandKey(input.repo)));
+          const command = input.command ?? (yield* config.get(cmdKey));
+          const timeoutSec =
+            input.timeoutSec ??
+            (yield* Effect.reduce(
+              timeoutKeys(input.repo, input.checkLabel),
+              undefined as number | undefined,
+              (found, key) =>
+                found !== undefined
+                  ? Effect.succeed(found)
+                  : config.get(key).pipe(Effect.map(parseIntConfig)),
+            ));
           const secretNames =
             input.secrets.length > 0
               ? [...input.secrets]
@@ -205,13 +303,13 @@ export const workerDeploy = defineRun({
                   .filter((s) => s.length > 0);
           const secretPrefix =
             input.secretPrefix ?? (yield* config.get(secretPrefixKey(input.repo)));
-          return { command, secretNames, secretPrefix };
+          return { command, timeoutSec, secretNames, secretPrefix };
         }),
       );
       if (cfg.command === undefined || cfg.command.trim().length === 0) {
         yield* io.log(
           "warn",
-          `worker-deploy: no \`${commandKey(input.repo)}\` in the config store — repo not opted in, skipping`,
+          `worker-deploy: no \`${cmdKey}\` in the config store — repo not opted in, skipping`,
         );
         return {
           deployed: false,
@@ -243,22 +341,29 @@ export const workerDeploy = defineRun({
 
       // exec — the deploy itself. A non-zero exit is a normal ExecResult here;
       // the failOnNonZeroExit branch below decides whether it reds the check.
-      const result = yield* step("exec", () =>
-        sandbox.exec({
-          cwd: dir,
-          container,
-          command,
-          // Per-dispatch `env` wins over a same-named config-store secret.
-          env: { ...secretEnv, ...input.env },
-          // Scrub secret VALUES from the captured log before it is persisted,
-          // in case the command echoes its env. Not hypothetical here: a deploy
-          // command is the one that carries a cloud provider's write-scoped API
-          // token, and `wrangler`-class tools print their environment on some
-          // error paths. The log lands in R2 on a stable path (artifact TTLs are
-          // not yet enforced), so a leak there is durable.
-          redactValues: Object.values(secretEnv),
-          timeoutSec: input.timeoutSec ?? TIMEOUT_SEC_DEFAULT,
-        }),
+      // StepOpts are explicit (see header § A deploy is never step-retried):
+      // `retries: 0`, and a step timeout above the exec's so the sandbox
+      // deadline, not the platform's 600s default, ends a long deploy.
+      const execTimeoutSec = cfg.timeoutSec ?? TIMEOUT_SEC_DEFAULT;
+      const result = yield* step(
+        "exec",
+        () =>
+          sandbox.exec({
+            cwd: dir,
+            container,
+            command,
+            // Per-dispatch `env` wins over a same-named config-store secret.
+            env: { ...secretEnv, ...input.env },
+            // Scrub secret VALUES from the captured log before it is persisted,
+            // in case the command echoes its env. Not hypothetical here: a deploy
+            // command is the one that carries a cloud provider's write-scoped API
+            // token, and `wrangler`-class tools print their environment on some
+            // error paths. The log lands in R2 on a stable path (artifact TTLs are
+            // not yet enforced), so a leak there is durable.
+            redactValues: Object.values(secretEnv),
+            timeoutSec: execTimeoutSec,
+          }),
+        { timeoutSec: execTimeoutSec + STEP_TIMEOUT_HEADROOM_SEC, retries: 0 },
       );
 
       // upload-log — the deploy log as a signed R2 artifact.