@norskvideo/ctl-dev-kit 0.2.60 → 0.2.62

package/build/flake.sdk-app.nix

@@ -8,7 +8,9 @@
   #
   # Unlike the Studio-product flake this does NOT fetch the norsk-ctl daemon —
   # an sdk-app's dev loop is its own SDK app plus a Norsk engine, not a
-  # ctl-launched product container. Decision: bun for tooling (install / build /
+  # ctl-launched product container. It still PINS one: `ctlVersion` below is the
+  # norsk-ctl the product's CI tiers (smoke) launch it with, read from here so a
+  # result belongs to a commit, and moved nightly by upgrade-latest. Decision: bun for tooling (install / build /
   # test), Node for the shipped runtime (the SDK's blessed runtime).
   #
   # nixpkgs is pinned to the same rev the Studio flake uses, so bun matches the
@@ -27,6 +29,8 @@
 
   outputs = { self, nixpkgs, nixpkgs-biome }:
     let
+      # The norsk-ctl CI runs (see above); upgrade-latest moves it to `latest`.
+      ctlVersion = "0.1.0-2026-09-15-81bbde8";
       systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
       forAllSystems = f: builtins.listToAttrs (map (s: { name = s; value = f s; }) systems);
     in {

package/conventions/CLAUDE.core.md

@@ -84,6 +84,12 @@
   same as this core block and `nix/ctl-shell.nix`; `check:drift` fails CI if a copy
   diverges. Only the `product:` key is per-repo. Never hand-edit the copy — edit
   the dev-kit source and re-sync.
+- **CI runs the norsk-ctl this repo pins** (`flake.nix` `ctlVersion`), never S3's
+  moving `latest`; only a `ctl-candidate` run tests a channel (`rc`). The bump bots
+  (`upgrade-latest`, `sync-dev-kit`, `sync-ctl-packages`) never push to main: each
+  opens a PR, and `bot-prs` merges it once checks, smoke, integration and the
+  guides gate (build-image) are green on it. A red bot PR is the alarm for a bad
+  upstream change; main stays green.
 - **A config-driven workflow needs a parity-checked invariant contract.** If this
   product emits its Studio graph dynamically from config, its load-bearing rules
   are documented as stable-ID statements (`INV-<AREA>-<NNN>`) in an

package/conventions/bot-prs.yml

@@ -1,25 +1,37 @@
 # Land the pin bots' green PRs; put the red ones on the product dashboard.
 #
-# Three bots keep a product fresh: upgrade-latest (the Norsk nightly line),
-# sync-dev-kit (this package) and sync-ctl-packages (the ctl-* / moq-* npm
-# family). The first two land on main when their gate is green and open a PR
-# when it is not; sync-ctl-packages ALWAYS opens a PR, because its gate cannot
-# run the smoke tier its packages drive. Nothing then acted on those PRs: green
+# Three bots keep a product fresh: upgrade-latest (the Norsk nightly line and
+# the norsk-ctl pin), sync-dev-kit (this package) and sync-ctl-packages (the
+# ctl-* / moq-* npm family). All three ALWAYS open a PR and never push to main
+# (ci-workflows docs/dashboard/ci-fragility.md, proposal B): a bot's own gate
+# is lint, typecheck and unit tests, and the tiers that break on an upstream
+# change -- smoke, integration and the guides that gate build-image's publish
+# -- run on the PR. This workflow is what lands them. Nothing used to act on
+# those PRs: green
 # ones sat unmerged (studio's ctl-sdk was twenty releases behind on 2026-10-03,
 # its PR open since 09-03) and red ones were invisible, because the bot that
 # opened them reports success. With a product count that only goes up, "someone
 # will notice" is not a process.
 #
 # So, for every open PR whose branch a bot owns:
-#   - every check on its head has passed and it merges cleanly -> squash-merge it
-#     (the PR's checks + smoke ARE the verdict; integration then runs on main);
+#   - every check on its head has passed, every TIER that runs on a bot PR has a
+#     green run on that head, and it merges cleanly -> squash-merge it. The
+#     tiers are checks, smoke, integration and build-image (whose gate-guides
+#     job runs the guides): each of those the head carries whose workflow runs
+#     on pull_request. integration and build-image run on bot branches only, so
+#     human PRs do not pay for them. A hand-owned integration.yml that runs on
+#     push alone cannot gate, and still runs on main after the merge. "Nothing
+#     failed yet" is not enough: a slow tier that has not started has no check
+#     run at all, so bot-prs used to merge before integration had begun;
 #   - it conflicts with main -> re-run the bot that owns the branch, ONCE per
 #     head, so it rebuilds the branch from today's main (see below);
 #   - a check failed, it still conflicts after that rebuild, or it is a draft
 #     (the bot's own gate was red) -> list it, and report this repo's `bot-prs`
 #     cell RED on the product dashboard, which is the Discord message people
 #     actually read;
-#   - checks still running -> leave it for the next trigger.
+#   - checks or a tier still running -> leave it for the next trigger; a tier
+#     that has not started an hour after checks finished never will (its
+#     workflow is broken, or does not run on PRs), so that is red too.
 # The cell goes green again once nothing is red.
 #
 # Why the conflict rebuild: the three bots fire within minutes of each other
@@ -28,13 +40,12 @@
 # bot only rebuilds its branch on its next DAILY run -- so on 2026-10-09
 # commentary, probe and reuters each had a sync-ctl-packages PR "needing a
 # human" that a re-run of sync-ctl-packages fixed outright. Every bot rebuilds
-# from main when run: sync-ctl-packages force-pushes a fresh branch, and
-# upgrade-latest / sync-dev-kit either land on main and close the PR they
-# superseded, or force-push their branch. The marker comment caps it at one
+# from main when run: each force-pushes its branch from today's main and
+# closes any older PR of its own family. The marker comment caps it at one
 # rebuild per head, so a rebuild that still conflicts goes to a human instead
 # of looping every hour.
 #
-# Runs when a PR's checks or smoke finish (the prompt path), hourly as a sweep,
+# Runs when any gating tier finishes (the prompt path), hourly as a sweep,
 # and on demand. No checkout: it only talks to the GitHub API, so it needs none
 # of the runner-workspace steps the building workflows carry.
 #
@@ -46,7 +57,7 @@ name: bot-prs
 
 on:
   workflow_run:
-    workflows: [checks, smoke]
+    workflows: [checks, smoke, integration, build-image]
     types: [completed]
   schedule:
     - cron: "23 * * * *"
@@ -56,8 +67,13 @@ permissions:
   contents: read
   checks: read
   pull-requests: read
-  # The rebuild dispatch and its marker comment go through the PAT (WRITE_TOKEN),
-  # like the merges; this token only reads.
+  # Reads which gating tiers have passed on a PR's head, and writes Actions:
+  # re-running a cancelled tier and dispatching a bot's workflow to rebuild a
+  # conflicting PR. Those went through the PAT, which has no Actions write, and
+  # failed with HTTP 403 in every repo (2026-10-10). A workflow_dispatch made
+  # with this token does start a run (exempt from the recursion guard). Merges,
+  # branch deletes and comments stay on the PAT (WRITE_TOKEN).
+  actions: write
 
 concurrency:
   # One at a time per repo, and never cancelled: a merge half-done by a run that
@@ -86,6 +102,9 @@ jobs:
           curl_as() { local tok="$1"; shift; curl -sS --retry 3 --retry-all-errors -H "Authorization: Bearer $tok" -H "Accept: application/vnd.github+json" "$@"; }
           gh_api() { curl_as "$READ_TOKEN" "$@"; }
           gh_write() { curl_as "$WRITE_TOKEN" "$@"; }
+          # Actions writes (re-run a tier, dispatch a bot's workflow) use the
+          # job token, which permissions grant actions: write; the PAT cannot.
+          gh_actions() { curl_as "$READ_TOKEN" "$@"; }
           # An API error is a JSON object with a message; say what it was rather
           # than letting jq fail later on a missing field.
           expect() {
@@ -103,6 +122,88 @@ jobs:
                  | select(.head.ref | test("^(upgrade-latest/|sync-dev-kit/|chore/sync-ctl-packages$)"))
                  | {number, ref: .head.ref, sha: .head.sha, draft, url: .html_url}]' <<<"$pulls")"
 
+          # Does this workflow (on stdin) run on pull_request? Only its `on:` block
+          # counts. The convention integration.yml and build-image.yml do, on bot
+          # branches only; a hand-owned integration.yml that runs on push alone
+          # cannot gate a PR.
+          gates_bot_prs() {
+            awk '/^on:/ { on = 1; next } on && /^[^ #]/ { on = 0 } on && /^  pull_request:/ { found = 1 } END { exit !found }'
+          }
+
+          # The tiers a bump must pass on its head before it reaches main: each
+          # of these workflows the HEAD carries that runs on a bot PR. Read from
+          # the head, not main, so a dev-kit sync that brings a tier gates on it.
+          # Each file is read whole BEFORE it is judged: piped straight into
+          # gates_bot_prs under pipefail, a file larger than the pipe buffer
+          # failed the pipeline whenever the reader finished first, and
+          # build-image.yml read as "does not run on bot PRs" (commentary #36).
+          tiers_for() {
+            local sha="$1" listing f text
+            listing="$(gh_api "$api/contents/.github/workflows?ref=$sha")"
+            expect "listing the workflows at $sha" 'type == "array"' "$listing"
+            for f in checks.yml smoke.yml integration.yml build-image.yml; do
+              jq -e --arg f "$f" 'any(.[]; .name == $f)' >/dev/null <<<"$listing" || continue
+              # A tier it cannot read must not silently stop gating: fail instead.
+              text="$(curl -fsS --retry 3 --retry-all-errors -H "Authorization: Bearer $READ_TOKEN" \
+                -H "Accept: application/vnd.github.raw" "$api/contents/.github/workflows/$f?ref=$sha")" ||
+                { echo "::error::could not read $f at $sha" >&2; return 1; }
+              if gates_bot_prs <<<"$text"; then
+                echo "$f"
+              else
+                echo "${f%.yml} does not run on bot PRs at ${sha:0:8}, so it does not gate the merge" >&2
+              fi
+            done
+          }
+
+          # tier_verdict REQUIRED RUNS NOW -> "ok", "wait <why>", "rerun <run ids>"
+          # or "red <why>". REQUIRED: workflow files, one per line. RUNS: the
+          # head's actions/runs listing. The newest pull_request run of each
+          # counts, so a re-run after a red is honoured. A tier with no run yet is
+          # waited for, unless checks finished over an hour ago: then it never
+          # will start. A CANCELLED tier is re-run, up to its third attempt: the
+          # guides queue on one concurrency group per repo and GitHub keeps one
+          # pending run per group, cancelling the older, so three bot PRs opening
+          # within the hour can cancel a guides run with nothing wrong in it.
+          tier_verdict() {
+            local required="$1" runs="$2" now="$3" f run status conclusion checks_age
+            local -a waiting=() failed=() rerun=()
+            checks_age="$(jq -r --argjson now "$now" '
+              [.workflow_runs[] | select((.path | split("@")[0]) == ".github/workflows/checks.yml"
+                and .event == "pull_request" and .status == "completed")] | max_by(.id)
+              | if . == null then "" else ($now - (.updated_at | fromdateiso8601)) end' <<<"$runs")"
+            while IFS= read -r f; do
+              [ -n "$f" ] || continue
+              run="$(jq -c --arg p ".github/workflows/$f" '
+                [.workflow_runs[] | select((.path | split("@")[0]) == $p and .event == "pull_request")] | max_by(.id) // empty' <<<"$runs")"
+              if [ -z "$run" ]; then
+                if [ -n "$checks_age" ] && [ "$checks_age" -gt 3600 ]; then
+                  failed+=("${f%.yml} never ran on this head (does its workflow run on bot PRs?)")
+                else
+                  waiting+=("${f%.yml} has not started")
+                fi
+                continue
+              fi
+              status="$(jq -r .status <<<"$run")"
+              conclusion="$(jq -r '.conclusion // ""' <<<"$run")"
+              if [ "$status" != "completed" ]; then
+                waiting+=("${f%.yml} $status")
+              elif [ "$conclusion" = "cancelled" ] && [ "$(jq -r '.run_attempt // 1' <<<"$run")" -lt 3 ]; then
+                rerun+=("$(jq -r .id <<<"$run")")
+              elif [ "$conclusion" != "success" ]; then
+                failed+=("${f%.yml} $conclusion")
+              fi
+            done <<<"$required"
+            if [ "${#failed[@]}" -gt 0 ]; then
+              printf 'red %s\n' "$(printf '%s; ' "${failed[@]}" | sed 's/; $//')"
+            elif [ "${#rerun[@]}" -gt 0 ]; then
+              echo "rerun ${rerun[*]}"
+            elif [ "${#waiting[@]}" -gt 0 ]; then
+              printf 'wait %s\n' "$(printf '%s; ' "${waiting[@]}" | sed 's/; $//')"
+            else
+              echo ok
+            fi
+          }
+
           # The workflow that owns each bot branch, i.e. the one that rebuilds it.
           producer() {
             case "$1" in
@@ -127,6 +228,22 @@ jobs:
             if [ -n "$failed" ]; then red+=("#$n $ref: failing $failed"); continue; fi
             if [ "$(jq -r .draft <<<"$pr")" = "true" ]; then red+=("#$n $ref: draft (its bot's gate was red)"); continue; fi
             if [ "$pending" -gt 0 ] || [ "$passed" -eq 0 ]; then echo "#$n $ref: checks not finished; next time"; continue; fi
+            # Every tier that runs on a bot PR must have PASSED on this head.
+            required="$(tiers_for "$sha")"
+            wf_runs="$(gh_api "$api/actions/runs?head_sha=$sha&per_page=100")"
+            expect "reading workflow runs for #$n" '.workflow_runs | type == "array"' "$wf_runs"
+            verdict="$(tier_verdict "$required" "$wf_runs" "$(date +%s)")"
+            case "$verdict" in
+              ok) ;;
+              red\ *) red+=("#$n $ref: ${verdict#red }"); continue ;;
+              rerun\ *)
+                for id in ${verdict#rerun }; do
+                  code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/runs/$id/rerun")"
+                  echo "#$n $ref: a gating tier (run $id) was cancelled; re-running it (HTTP $code)"
+                done
+                continue ;;
+              *) echo "#$n $ref: ${verdict#wait }; next time"; continue ;;
+            esac
             # GitHub computes mergeability lazily; ask until it has an answer.
             mergeable=null
             for _ in 1 2 3 4 5; do
@@ -145,7 +262,7 @@ jobs:
               elif jq -e --arg m "$marker" 'any(.[]; .body | contains($m))' >/dev/null <<<"$comments"; then
                 red+=("#$n $ref: still does not merge cleanly with main after $wf rebuilt it")
               else
-                code="$(gh_write -o /dev/null -w '%{http_code}' -X POST "$api/actions/workflows/$wf/dispatches" -d '{"ref":"main"}')"
+                code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/workflows/$wf/dispatches" -d '{"ref":"main"}')"
                 if [ "$code" = "204" ]; then
                   body="$marker -- it conflicted with main (another bot landed first), so $wf was re-run to rebuild it from today's main. If the rebuilt branch conflicts too, this PR is reported for a human."
                   gh_write -o /dev/null -X POST "$api/issues/$n/comments" -d "$(jq -nc --arg b "$body" '{body:$b}')" || true

package/conventions/build-docs.yml

@@ -164,12 +164,16 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
-      - name: Download the released norsk-ctl binary (latest channel)
+      # The norsk-ctl this commit pins (flake.nix ctlVersion, moved by
+      # upgrade-latest's bump PR), never S3's moving `latest`: a guide run is then
+      # a real repeat, and a red belongs to a commit (ci-fragility proposal A).
+      - name: Download the pinned norsk-ctl binary (flake.nix ctlVersion)
         run: |
           set -euo pipefail
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
-          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/latest")"
-          echo "norsk-ctl latest channel -> $ver"
+          ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
+          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+          echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver"
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"
           "$RUNNER_TEMP/norsk-ctl" --version || true

package/conventions/build-image.yml

@@ -21,6 +21,16 @@
 # (rc -> latest promotion) lands, flip the push default to `nightly` and let the
 # promotion gate move `latest`.
 #
+# BOT PRs: on a pull request from a bot branch (upgrade-latest/*,
+# sync-dev-kit/*, chore/sync-ctl-packages) the workflow builds both arches and
+# runs the guides gate exactly as a push would, and publishes, records and
+# reports nothing. A bump reaches main only once that has passed on it, and
+# bot-prs merges on it (ci-workflows docs/dashboard/ci-fragility.md, proposal
+# B): a dev-kit sync that brought a newer copy of THIS file broke
+# oracle-reasoning's build on main on 2026-10-09, after a green unit gate
+# landed it. A human PR does not pay for the build; gate-checks is skipped on a
+# PR because the PR's own checks run already covers it.
+#
 # Repo-local for now; to be hoisted into id3as/ci-workflows as a reusable
 # workflow (RFC 0001 Workstream E).
 name: build-image
@@ -28,6 +38,7 @@ name: build-image
 on:
   push:
     branches: [main]
+  pull_request:
   workflow_dispatch:
     inputs:
       channel:
@@ -57,6 +68,7 @@ jobs:
   # Compute the immutable label ONCE, so both arch builds and the manifest share
   # it (a per-job `date` could straddle midnight and disagree).
   label:
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && (startsWith(github.head_ref, 'upgrade-latest/') || startsWith(github.head_ref, 'sync-dev-kit/') || github.head_ref == 'chore/sync-ctl-packages')) }}
     runs-on: x64
     outputs:
       label: ${{ steps.gen.outputs.label }}
@@ -241,14 +253,14 @@ jobs:
           '
 
       - name: Log in to Docker Hub
-        if: ${{ env.PUBLISH_IMAGE != '' }}
+        if: ${{ env.PUBLISH_IMAGE != '' && github.event_name != 'pull_request' }}
         uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
         with:
           username: norskvideo
           password: ${{ secrets.DOCKER_PAT }}
 
       - name: Push the per-arch image to Docker Hub
-        if: ${{ env.PUBLISH_IMAGE != '' }}
+        if: ${{ env.PUBLISH_IMAGE != '' && github.event_name != 'pull_request' }}
         run: docker push "$IMAGE_TAG"
       - name: Reap the containers this job launched
         # Whatever the tests did. A teardown cut short by a test timeout leaves
@@ -276,6 +288,7 @@ jobs:
   # tests shipped a probe whose preview was broken for four days, while the one
   # test that knew sat red in a nightly nobody saw (task 57).
   gate-checks:
+    if: ${{ github.event_name != 'pull_request' }}
     uses: ./.github/workflows/checks.yml
     with:
       report: false
@@ -388,13 +401,17 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
-      - name: Download the released norsk-ctl binary (latest channel)
+      # The norsk-ctl this commit pins (flake.nix ctlVersion, moved by
+      # upgrade-latest's bump PR), never S3's moving `latest`: a guide run is then
+      # a real repeat, and a red belongs to a commit (ci-fragility proposal A).
+      - name: Download the pinned norsk-ctl binary (flake.nix ctlVersion)
         if: ${{ steps.plan.outputs.guides == 'run' }}
         run: |
           set -euo pipefail
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
-          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/latest")"
-          echo "norsk-ctl latest channel -> $ver"
+          ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
+          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+          echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver"
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"
           "$RUNNER_TEMP/norsk-ctl" --version || true
@@ -474,7 +491,7 @@ jobs:
   # a dry run.
   publish:
     needs: [label, build, gate-checks, gate-guides]
-    if: ${{ needs.label.outputs.publish == 'true' && !inputs.dry_run }}
+    if: ${{ needs.label.outputs.publish == 'true' && !inputs.dry_run && github.event_name != 'pull_request' }}
     runs-on: x64
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base
@@ -583,7 +600,7 @@ jobs:
   # exists this warns and records nothing, rather than failing a publish.
   record:
     needs: [label, gate-guides, publish]
-    if: ${{ needs.publish.result == 'success' }}
+    if: ${{ needs.publish.result == 'success' && github.event_name != 'pull_request' }}
     runs-on: x64
     permissions:
       contents: read
@@ -717,7 +734,7 @@ jobs:
   # still reports.
   notify:
     needs: [label, build, gate-checks, gate-guides, publish, record]
-    if: ${{ !cancelled() }}
+    if: ${{ !cancelled() && github.event_name != 'pull_request' }}
     runs-on: x64
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base

package/conventions/check-drift.ts

@@ -70,8 +70,8 @@ export const PUBLISH_IMAGE_LINE = /^(\s*PUBLISH_IMAGE:\s*).*$/gm;
 
 // integration.yml (04c s9 #1) is universally present and was hand-owned in six
 // shapes, so on the day it joined the conventions set the gate could not demand
-// the canonical of every copy: sync-dev-kit commits straight to main when
-// checks are green, and would have rewritten six tiers before the hooks their
+// the canonical of every copy: sync-dev-kit then committed straight to main
+// when checks were green, and would have rewritten six tiers before the hooks their
 // suites need existed. A copy therefore declares itself converged by carrying
 // the canonical's own first line; one without it is hand-owned and ungated
 // until its repo converges deliberately. When every repo carries the marker,

package/conventions/integration.yml

@@ -38,6 +38,13 @@
 # host siblings and the harness reaches them by compose name on norsk-net (the
 # topology step below says so in NORSK_TEST_HOST/NORSK_TEST_NET); the GPU box
 # is '["ARM64","nvidia"]'.
+#
+# On a pull request the suite runs for a BOT branch only (upgrade-latest/*,
+# sync-dev-kit/*, chore/sync-ctl-packages): a bump reaches main only once this
+# tier has passed on it, and bot-prs merges on that (ci-workflows
+# docs/dashboard/ci-fragility.md, proposal B). A human PR does not pay for the
+# slow tier; it runs on main after the merge, as before. A PR's result is the
+# PR's, so it is not reported as the product's integration cell.
 name: integration
 
 on:
@@ -45,12 +52,13 @@ on:
     types: [ctl-candidate]
   push:
     branches: [main]
+  pull_request:
   workflow_dispatch:
     inputs:
       ctl_channel:
-        description: "norsk-ctl S3 channel to test against (release-gate dispatches 'rc' to validate a candidate before promoting latest)."
+        description: "norsk-ctl S3 channel to test against in place of the repo's pin (flake.nix ctlVersion). Empty runs the pin; release-gate dispatches 'rc' to validate a candidate before promoting latest."
         type: string
-        default: latest
+        default: ""
 
 permissions:
   contents: read
@@ -83,6 +91,7 @@ concurrency:
 
 jobs:
   integration:
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && (startsWith(github.head_ref, 'upgrade-latest/') || startsWith(github.head_ref, 'sync-dev-kit/') || github.head_ref == 'chore/sync-ctl-packages')) }}
     strategy:
       matrix:
         include:
@@ -277,18 +286,34 @@ jobs:
       # Pick the binary for THIS runner's architecture: the GPU box is aarch64,
       # the x64 pool is x86_64, and the wrong one dies with "Exec format error"
       # deep in the suite. No `|| true` on --version: a bad binary must fail here.
-      - name: Download the released norsk-ctl binary
+      #
+      # WHICH binary: the version this commit pins, flake.nix ctlVersion -- the
+      # daemon the dev shell launches, moved by upgrade-latest's bump PR. It used
+      # to be S3's moving `latest`, read at run time, so a result could change
+      # with no product commit and a re-run was never a real repeat (funke went
+      # red and green again on 2026-10-09 without a commit either time;
+      # ci-workflows docs/dashboard/ci-fragility.md, proposal A). A ctl-candidate
+      # dispatch still tests its payload's channel (rc) -- that is what it is
+      # for -- and a by-hand ctl_channel may too. ctl-pinned-in-repo.test.ts.
+      - name: Download the pinned norsk-ctl binary
+        env:
+          CTL_CHANNEL: ${{ github.event.client_payload.channel || inputs.ctl_channel }}
         run: |
           set -euo pipefail
-          channel="${{ github.event.client_payload.channel || inputs.ctl_channel || 'latest' }}"
           case "$(uname -m)" in
             x86_64) arch=linux-x64 ;;
             aarch64 | arm64) arch=linux-arm64 ;;
             *) echo "unsupported runner arch: $(uname -m)" >&2; exit 1 ;;
           esac
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
-          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$channel")"
-          echo "norsk-ctl $channel channel -> $ver ($arch)"
+          if [ -n "${CTL_CHANNEL:-}" ]; then
+            ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$CTL_CHANNEL")"
+            echo "norsk-ctl $CTL_CHANNEL channel -> $ver ($arch), in place of the repo pin"
+          else
+            ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
+            [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+            echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver ($arch)"
+          fi
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-$arch" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"
           "$RUNNER_TEMP/norsk-ctl" --version
@@ -435,7 +460,7 @@ jobs:
   # would false-red the board. Candidate validations report to ctl instead.
   notify:
     needs: integration
-    if: ${{ !cancelled() && github.event_name != 'repository_dispatch' }}
+    if: ${{ !cancelled() && github.event_name != 'repository_dispatch' && github.event_name != 'pull_request' }}
     runs-on: x64
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base

package/conventions/publish-docs.yml

@@ -174,12 +174,16 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
-      - name: Download the released norsk-ctl binary (latest channel)
+      # The norsk-ctl this commit pins (flake.nix ctlVersion, moved by
+      # upgrade-latest's bump PR), never S3's moving `latest`: a guide run is then
+      # a real repeat, and a red belongs to a commit (ci-fragility proposal A).
+      - name: Download the pinned norsk-ctl binary (flake.nix ctlVersion)
         run: |
           set -euo pipefail
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
-          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/latest")"
-          echo "norsk-ctl latest channel -> $ver"
+          ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
+          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+          echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver"
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"
           "$RUNNER_TEMP/norsk-ctl" --version || true

package/conventions/smoke.yml

@@ -30,9 +30,9 @@ on:
   workflow_dispatch:
     inputs:
       ctl_channel:
-        description: "norsk-ctl S3 channel to test against (release-gate dispatches 'rc' to validate a candidate before promoting latest)."
+        description: "norsk-ctl S3 channel to test against in place of the repo's pin (flake.nix ctlVersion). Empty runs the pin; release-gate dispatches 'rc' to validate a candidate before promoting latest."
         type: string
-        default: latest
+        default: ""
 
 permissions:
   contents: read
@@ -196,18 +196,34 @@ jobs:
       # Pick the binary for THIS runner's architecture: the GPU box is aarch64,
       # the x64 pool is x86_64, and the wrong one dies with "Exec format error"
       # deep in the suite. No `|| true` on --version: a bad binary must fail here.
-      - name: Download the released norsk-ctl binary
+      #
+      # WHICH binary: the version this commit pins, flake.nix ctlVersion -- the
+      # daemon the dev shell launches, moved by upgrade-latest's bump PR. It used
+      # to be S3's moving `latest`, read at run time, so a result could change
+      # with no product commit and a re-run was never a real repeat (funke went
+      # red and green again on 2026-10-09 without a commit either time;
+      # ci-workflows docs/dashboard/ci-fragility.md, proposal A). A ctl-candidate
+      # dispatch still tests its payload's channel (rc) -- that is what it is
+      # for -- and a by-hand ctl_channel may too. ctl-pinned-in-repo.test.ts.
+      - name: Download the pinned norsk-ctl binary
+        env:
+          CTL_CHANNEL: ${{ github.event.client_payload.channel || inputs.ctl_channel }}
         run: |
           set -euo pipefail
-          channel="${{ github.event.client_payload.channel || inputs.ctl_channel || 'latest' }}"
           case "$(uname -m)" in
             x86_64) arch=linux-x64 ;;
             aarch64 | arm64) arch=linux-arm64 ;;
             *) echo "unsupported runner arch: $(uname -m)" >&2; exit 1 ;;
           esac
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
-          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$channel")"
-          echo "norsk-ctl $channel channel -> $ver ($arch)"
+          if [ -n "${CTL_CHANNEL:-}" ]; then
+            ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$CTL_CHANNEL")"
+            echo "norsk-ctl $CTL_CHANNEL channel -> $ver ($arch), in place of the repo pin"
+          else
+            ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
+            [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+            echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver ($arch)"
+          fi
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-$arch" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"
           "$RUNNER_TEMP/norsk-ctl" --version

package/conventions/sync-ctl-packages.yml

@@ -18,11 +18,12 @@
 # nothing that morning. It is picked up the next time any pin moves, which for
 # this family is most days.
 #
-# Unlike sync-dev-kit this NEVER pushes to main. Its gate is drift + lint +
-# typecheck + unit, and a bump to the test harness changes the code that drives
-# smoke and integration -- neither of which that gate runs, because both need
-# Docker and a licence. A green gate therefore proves strictly less here than it
-# does for a conventions bump, so the bump goes to a human as a PR. A red gate
+# This NEVER pushes to main -- and since ci-fragility proposal B neither do
+# upgrade-latest or sync-dev-kit, which once landed on a green gate. Its gate
+# is drift + lint + typecheck + unit, and a bump to the test harness changes
+# the code that drives smoke and integration -- neither of which that gate
+# runs, because both need Docker and a licence; the PR's own tiers do, and
+# bot-prs merges it only once they pass. A red gate
 # still opens one, as a draft: adopting a breaking change is real engineering,
 # not a copy-paste, and the PR is where that work belongs.
 #
@@ -116,7 +117,7 @@ jobs:
           set -euo pipefail
           reg="https://registry.npmjs.org"
           # The conventions package is deliberately absent: sync-dev-kit owns it,
-          # lands it straight to main, and re-syncs the copied files with it.
+          # bumps it in its own PR, and re-syncs the copied files with it.
           # The moq-* members are the @norskvideo fork of moq-dev/moq that the
           # dashboards play through. They pin each other at one version, so all
           # nine move together, including the ones a product only gets