@norskvideo/ctl-dev-kit 0.2.63 → 0.2.65

package/conventions/check-drift.ts

@@ -5,8 +5,10 @@
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
 //     product with tests/demo.spec.ts is asked for it), publish-docs-site.yml
 //     (only a repo with a docs site may carry it, and never a turnkey)
-//   - masked per-repo line: checks.yml, upgrade-latest.yml, publish-docs.yml
-//     and the other dispatching workflows (`product:` key)
+//   - masked per-repo line: checks.yml, bump.yml, publish-docs.yml and the
+//     other dispatching workflows (`product:` key)
+//   - retired: upgrade-latest.yml, sync-dev-kit.yml, sync-ctl-packages.yml,
+//     which bump.yml replaced; carrying one is drift
 //   - base + sanctioned extension block: dprint.json (repo-specific excludes)
 //   - must import the shared module: flake.nix (otherwise the product's own)
 //   - structural: root tsconfig.json (shape-dependent includes stay free),
@@ -262,14 +264,13 @@ export interface CanonicalBytes {
   /** build/ctl-shell.nix — the shared dev-shell module, gated verbatim at
    *  nix/ctl-shell.nix for every shape. */
   ctlShell: string;
-  upgradeLatest: string;
-  syncDevKit: string;
-  /** conventions/sync-ctl-packages.yml — the ctl-* pin freshness PR. No per-repo
-   *  line at all, so it is verbatim and sync-drift creates it where absent. */
-  syncCtlPackages: string;
-  /** conventions/bot-prs.yml -- merges the pin bots' green PRs and reports red
-   *  ones. Verbatim (it reads its dashboard key at run time), so sync-drift
-   *  creates it where absent, like sync-ctl-packages. */
+  /** conventions/bump.yml -- the one nightly bump (dev-kit, ctl-* and moq-*,
+   *  then the engine/Studio/norsk-ctl pins) and its one PR. Masked like
+   *  checks.yml; required, and sync-drift creates it where absent. */
+  bump: string;
+  /** conventions/bot-prs.yml -- merges the bump's green PR and reports a red
+   *  one. Verbatim (it reads its dashboard key at run time), so sync-drift
+   *  creates it where absent. */
   botPrs: string;
   publishDocs: string;
   /** conventions/build-docs.yml — the embedded docs variant (bundle -> image, no upload). */
@@ -305,10 +306,10 @@ export interface CanonicalBytes {
    *  Studio licence step removed (it reads shared/src/version.ts +
    *  product-template.ts). Optional for the same reason as flakeSdkApp. */
   checksSdkApp?: string;
-  /** conventions/upgrade-latest.sdk-app.yml — the upgrade-latest.yml variant for
-   *  an sdk-app: no Studio pair or manifest.seed.json, the norsk family bumped off
-   *  the SDK nightly. Optional for the same reason as flakeSdkApp. */
-  upgradeLatestSdkApp?: string;
+  /** conventions/bump.sdk-app.yml — the bump.yml variant for an sdk-app: its
+   *  pins step has no Studio pair or manifest.seed.json, and bumps the norsk
+   *  family off the SDK nightly. Optional for the same reason as flakeSdkApp. */
+  bumpSdkApp?: string;
 }
 
 // 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
@@ -514,6 +515,16 @@ export function resolveRepoName(repoRoot: string, env: NodeJS.ProcessEnv = proce
 const PUBLIC_DOCS_REPO = /^norsk-ctl-product-/;
 const TURNKEY_REPO = /^norsk-ctl-turnkey-/;
 
+/** The one nightly bump (ci-fragility proposal B2). */
+export const BUMP_WORKFLOW = ".github/workflows/bump.yml";
+
+/** The three bump bots bump.yml replaced, removed from a product by sync-drift. */
+export const RETIRED_BUMP_WORKFLOWS = [
+  ".github/workflows/upgrade-latest.yml",
+  ".github/workflows/sync-dev-kit.yml",
+  ".github/workflows/sync-ctl-packages.yml",
+] as const;
+
 /** The docs site's publish workflow, where a repo carries one. */
 export const DOCS_SITE_WORKFLOW = ".github/workflows/publish-docs-site.yml";
 
@@ -657,7 +668,7 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   // checks.yml is REQUIRED — it is the CI entry point that runs this very gate
   // (plus the shared quality jobs), so a repo without it never re-converges.
   // Only the `product:` dispatch key is per-repo; it is masked like
-  // upgrade-latest.yml's.
+  // bump.yml's.
   const checksPath = join(repoRoot, ".github", "workflows", "checks.yml");
   const checksRel = ".github/workflows/checks.yml";
   const checksCanon = shape === "sdk-app" ? canonical.checksSdkApp : canonical.checks;
@@ -702,52 +713,35 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     }
   }
 
-  // upgrade-latest.yml is OPTIONAL — a product may ship without a nightly bump
-  // (e.g. until it has an integration tier). But when present it is the shared,
-  // single-sourced workflow and must not diverge. Shape-selected like checks.yml:
-  // an sdk-app has no Studio pair to bump, so it carries its own variant.
-  const workflowPath = join(repoRoot, ".github", "workflows", "upgrade-latest.yml");
-  if (existsSync(workflowPath)) {
-    const upgradeCanon = shape === "sdk-app" ? canonical.upgradeLatestSdkApp : canonical.upgradeLatest;
-    if (upgradeCanon === undefined) {
-      throw new Error(`checkDrift: shape "${shape}" requires canonical.upgradeLatestSdkApp`);
-    }
-    push(
-      workflowProblem(
-        ".github/workflows/upgrade-latest.yml",
-        shape === "sdk-app" ? "conventions/upgrade-latest.sdk-app.yml" : "conventions/upgrade-latest.yml",
-        readFileSync(workflowPath, "utf8"),
-        upgradeCanon,
-      ),
-    );
-  }
-
-  // sync-dev-kit.yml is OPTIONAL for the same reason as upgrade-latest.yml — a
-  // product may not carry it yet — but when present it is the shared,
-  // single-sourced workflow that keeps this repo's dev-kit pin fresh, and must
-  // not diverge. Only its `product:` dispatch key is per-repo.
-  const syncPath = join(repoRoot, ".github", "workflows", "sync-dev-kit.yml");
-  if (existsSync(syncPath)) {
-    push(
-      workflowProblem(
-        ".github/workflows/sync-dev-kit.yml",
-        "conventions/sync-dev-kit.yml",
-        readFileSync(syncPath, "utf8"),
-        canonical.syncDevKit,
-      ),
+  // bump.yml is REQUIRED: the one nightly bump (ci-fragility proposal B2), and
+  // sync-drift creates it. Shape-selected like checks.yml: an sdk-app has no
+  // Studio pair to bump, so it carries its own variant. Only its `product:`
+  // dispatch keys are per-repo.
+  const bumpPath = join(repoRoot, BUMP_WORKFLOW);
+  const bumpCanon = shape === "sdk-app" ? canonical.bumpSdkApp : canonical.bump;
+  const bumpRef = shape === "sdk-app" ? "conventions/bump.sdk-app.yml" : "conventions/bump.yml";
+  if (bumpCanon === undefined) {
+    throw new Error(`checkDrift: shape "${shape}" requires canonical.bumpSdkApp`);
+  } else if (!existsSync(bumpPath)) {
+    problems.push(
+      `${BUMP_WORKFLOW} not found (${bumpPath}). It is this repo's one nightly bump: \`bun run sync:drift\` creates it from @norskvideo/ctl-dev-kit ${bumpRef}, keeping this repo's dashboard key.`,
     );
+  } else {
+    push(workflowProblem(BUMP_WORKFLOW, bumpRef, readFileSync(bumpPath, "utf8"), bumpCanon));
   }
 
-  // sync-ctl-packages.yml is OPTIONAL until a repo has been synced once — it is
-  // NEW, and sync-drift creates it. Unlike its neighbours it carries no per-repo
-  // line (it dispatches to no dashboard), so the whole file is canonical.
-  const syncCtlPath = join(repoRoot, ".github", "workflows", "sync-ctl-packages.yml");
-  if (existsSync(syncCtlPath) && readFileSync(syncCtlPath, "utf8") !== canonical.syncCtlPackages) {
-    push(`.github/workflows/sync-ctl-packages.yml differs from conventions/sync-ctl-packages.yml. ${RESYNC}`);
+  // The three bots bump.yml replaced. One left beside it would run a second
+  // bump that conflicts with the first and is tested alone -- what B2 ended.
+  for (const rel of RETIRED_BUMP_WORKFLOWS) {
+    if (existsSync(join(repoRoot, rel))) {
+      problems.push(
+        `${rel} is retired: ${BUMP_WORKFLOW} does its job now, in the one nightly bump. Delete it (\`bun run sync:drift\` removes it once ${BUMP_WORKFLOW} exists).`,
+      );
+    }
   }
 
-  // bot-prs.yml: the same shape -- optional until a repo's first sync creates
-  // it, verbatim once present.
+  // bot-prs.yml: optional until a repo's first sync creates it, verbatim once
+  // present.
   const botPrsPath = join(repoRoot, ".github", "workflows", "bot-prs.yml");
   if (existsSync(botPrsPath) && readFileSync(botPrsPath, "utf8") !== canonical.botPrs) {
     push(`.github/workflows/bot-prs.yml differs from conventions/bot-prs.yml. ${RESYNC}`);
@@ -879,9 +873,7 @@ if (import.meta.main) {
     core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
     ctlShell: readFileSync(join(import.meta.dir, "..", "build", "ctl-shell.nix"), "utf8"),
-    upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
-    syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
-    syncCtlPackages: readFileSync(join(import.meta.dir, "sync-ctl-packages.yml"), "utf8"),
+    bump: readFileSync(join(import.meta.dir, "bump.yml"), "utf8"),
     botPrs: readFileSync(join(import.meta.dir, "bot-prs.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
@@ -899,7 +891,7 @@ if (import.meta.main) {
     demoShim: readFileSync(join(import.meta.dir, "demo.sh"), "utf8"),
     flakeSdkApp: readFileSync(join(import.meta.dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(import.meta.dir, "checks.sdk-app.yml"), "utf8"),
-    upgradeLatestSdkApp: readFileSync(join(import.meta.dir, "upgrade-latest.sdk-app.yml"), "utf8"),
+    bumpSdkApp: readFileSync(join(import.meta.dir, "bump.sdk-app.yml"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical, {
     repoName: resolveRepoName(repoRoot),

package/conventions/checks.sdk-app.yml

@@ -127,6 +127,9 @@ jobs:
 
   quality:
     runs-on: x64
+    outputs:
+      quarantined: ${{ steps.quarantine.outputs.quarantined }}
+      quarantine_failed: ${{ steps.quarantine.outputs.quarantine_failed }}
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base
       # out of the workspace for every later step in this job, and clears whatever
@@ -200,7 +203,11 @@ jobs:
             bun install --frozen-lockfile
             bun run lint
             bun run typecheck
-            bun run test:unit
+            # Known-flaky tests (.github/quarantine.json) leave the gating run
+            # here and run on their own in the next step (conventions/quarantine.ts).
+            q=node_modules/@norskvideo/ctl-dev-kit/conventions/quarantine.ts
+            bun "$q" check
+            BUN_OPTIONS="$(bun "$q" bun-options)" bun run test:unit
             bun run docs:check
             # The tree must resolve ONE zod 4 (conventions/zod-singleton.ts).
             # studio guards this in-repo but never shipped the guard; products
@@ -208,6 +215,16 @@ jobs:
             # in here and breaks a schema handed across the instance boundary.
             bun node_modules/@norskvideo/ctl-dev-kit/conventions/zod-singleton.ts
           '
+      # The quarantined tests, each run on its own and reported: a summary
+      # table, a warning per failure, and counts for the checks cell's detail.
+      # It never fails the job -- that is what quarantine means -- and it runs
+      # even when the gate is red, so the flake's record has no holes. Nothing
+      # listed, nothing run.
+      - name: Quarantined tests (run and reported, not gating)
+        id: quarantine
+        if: ${{ !cancelled() }}
+        continue-on-error: true
+        run: nix develop .#build --command bun node_modules/@norskvideo/ctl-dev-kit/conventions/quarantine.ts run
       # licenseTemplate.json records the entry a licence is minted from: this
       # product at the image CI builds. One naming another image mints a licence
       # that entitles nothing, first seen as a refused launch at the customer.
@@ -335,6 +352,8 @@ jobs:
           product: __PRODUCT__
           pipeline: checks
           status: ${{ steps.meta.outputs.state }}
+          # Quarantined tests leave the gate, never the board: say how many.
+          detail: "${{ needs.quality.outputs.quarantined > 0 && format('quarantined: {0} test(s), {1} not passing this run (not gating; .github/quarantine.json)', needs.quality.outputs.quarantined, needs.quality.outputs.quarantine_failed) || '' }}"
       - name: Reap the containers this job launched
         # Whatever the tests did. A teardown cut short by a test timeout leaves
         # its instance running on the shared Docker daemon (see JOB_REAP_STEP in

package/conventions/checks.yml

@@ -130,6 +130,9 @@ jobs:
 
   quality:
     runs-on: x64
+    outputs:
+      quarantined: ${{ steps.quarantine.outputs.quarantined }}
+      quarantine_failed: ${{ steps.quarantine.outputs.quarantine_failed }}
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base
       # out of the workspace for every later step in this job, and clears whatever
@@ -203,7 +206,11 @@ jobs:
             bun install --frozen-lockfile
             bun run lint
             bun run typecheck
-            bun run test:unit
+            # Known-flaky tests (.github/quarantine.json) leave the gating run
+            # here and run on their own in the next step (conventions/quarantine.ts).
+            q=node_modules/@norskvideo/ctl-dev-kit/conventions/quarantine.ts
+            bun "$q" check
+            BUN_OPTIONS="$(bun "$q" bun-options)" bun run test:unit
             bun run docs:check
             # The tree must resolve ONE zod 4 (conventions/zod-singleton.ts).
             # studio guards this in-repo but never shipped the guard; products
@@ -211,6 +218,16 @@ jobs:
             # in here and breaks a schema handed across the instance boundary.
             bun node_modules/@norskvideo/ctl-dev-kit/conventions/zod-singleton.ts
           '
+      # The quarantined tests, each run on its own and reported: a summary
+      # table, a warning per failure, and counts for the checks cell's detail.
+      # It never fails the job -- that is what quarantine means -- and it runs
+      # even when the gate is red, so the flake's record has no holes. Nothing
+      # listed, nothing run.
+      - name: Quarantined tests (run and reported, not gating)
+        id: quarantine
+        if: ${{ !cancelled() }}
+        continue-on-error: true
+        run: nix develop .#build --command bun node_modules/@norskvideo/ctl-dev-kit/conventions/quarantine.ts run
 
       # The two halves of one licence guarantee, run together because they only
       # work as a pair: check-template asserts this repo RECORDS the entitlement
@@ -356,6 +373,8 @@ jobs:
           product: __PRODUCT__
           pipeline: checks
           status: ${{ steps.meta.outputs.state }}
+          # Quarantined tests leave the gate, never the board: say how many.
+          detail: "${{ needs.quality.outputs.quarantined > 0 && format('quarantined: {0} test(s), {1} not passing this run (not gating; .github/quarantine.json)', needs.quality.outputs.quarantined, needs.quality.outputs.quarantine_failed) || '' }}"
       - name: Reap the containers this job launched
         # Whatever the tests did. A teardown cut short by a test timeout leaves
         # its instance running on the shared Docker daemon (see JOB_REAP_STEP in

package/conventions/ctl-pin-agreement.ts

@@ -6,9 +6,8 @@
 // a different copy from the one the root was moved to, and nothing says so:
 // playout's tests/ pinned the dev-kit ^0.1.57 while the root moved to 0.2, its
 // guides ran a guide proxy that built the wrong Studio prefix, and first-light
-// failed every night from 2026-09-07. sync-dev-kit.yml and
-// sync-ctl-packages.yml now move every pin; this keeps a hand edit (or a new
-// nested package) from splitting them again.
+// failed every night from 2026-09-07. bump.yml now moves every pin; this keeps
+// a hand edit (or a new nested package) from splitting them again.
 import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 
@@ -61,7 +60,7 @@ export function ctlPinProblems(repoRoot: string): string[] {
     if (byRange.size < 2) continue;
     const where = [...byRange].flatMap(([range, files]) => files.map((f) => `${f} ${range}`)).join(", ");
     problems.push(
-      `${name} is pinned at ${byRange.size} different ranges (${where}). A nested package then runs a different copy from the root's; pin it at one range everywhere (sync-dev-kit / sync-ctl-packages move every pin).`,
+      `${name} is pinned at ${byRange.size} different ranges (${where}). A nested package then runs a different copy from the root's; pin it at one range everywhere (the nightly bump.yml moves every pin).`,
     );
   }
   return problems;

package/conventions/docs-site.md

@@ -132,7 +132,7 @@ reaches every product's manual at once.
   shared workflows — the clause is conditional on `website/astro.config.mjs`
   existing, so a repo without a site is not asked for one.
 - `bun run sync:drift` rewrites the copies from the installed dev-kit. The
-  nightly `sync-dev-kit.yml` runs it after bumping the pin, so a theme change
+  nightly `bump.yml` runs it after bumping the pin, so a theme change
   rolls out hands-free and only a change that genuinely breaks the site goes red.
 
 **Keeping the copies at exactly those paths is load-bearing**, not tidiness:
@@ -246,11 +246,11 @@ that branch (`--branch` is the ref that ran), never over production.
 Two steps, once a dev-kit carrying the workflow is published:
 
 ```
-bun update @norskvideo/ctl-dev-kit   # bump the pin (or let sync-dev-kit.yml do it)
+bun update @norskvideo/ctl-dev-kit   # bump the pin (or let bump.yml do it)
 bun run sync:drift                   # writes .github/workflows/publish-docs-site.yml
 ```
 
-Commit the result; `bun run check:drift` passes. The nightly `sync-dev-kit.yml`
+Commit the result; `bun run check:drift` passes. The nightly `bump.yml`
 does both hands-free, so a product with a site acquires the workflow on its
 next sync without anyone touching the repo. Then create the Pages project, set
 the two secrets and the variable, and the next push to `main` publishes.

package/conventions/integration-testing.md

@@ -265,7 +265,7 @@ converge: move the repo's bespoke steps into the hooks above, replace the
 workflow with the canonical (product and runner filled in), and prove it with
 `gh workflow run integration.yml --ref <branch>` before merging — the tier
 only fires on `main` and on dispatch, so a PR's checks never run it. Once the
-marker is in, `sync-dev-kit` keeps the copy current and `check:drift` names any
+marker is in, the nightly `bump.yml` keeps the copy current and `check:drift` names any
 hand edit.
 
 **Why the pipe is shaped the way it is.** The suite runs inside a shell

package/conventions/integration.yml

@@ -39,8 +39,9 @@
 # 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
+# On a pull request the suite runs for a BOT branch only (bump/nightly, and the
+# retired bots' upgrade-latest/*, sync-dev-kit/* and chore/sync-ctl-packages,
+# which the PR that brings bump.yml rides on): 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
@@ -91,7 +92,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')) }}
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && (github.head_ref == 'bump/nightly' || startsWith(github.head_ref, 'upgrade-latest/') || startsWith(github.head_ref, 'sync-dev-kit/') || github.head_ref == 'chore/sync-ctl-packages')) }}
     strategy:
       matrix:
         include:
@@ -283,12 +284,37 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
+      # Every norsk-ctl daemon starts the node MoQ relay (norsk-moq-relay) unless
+      # told not to, and nothing removes it: it is a node singleton, and the reap
+      # step only takes containers that mount this job's test-temp. So the first
+      # test daemon on a shared runner left one, and every later one adopted it
+      # (probe's smoke ran in relay mode on 2026-10-10; relay's smoke lost 4443
+      # to it). This job's daemons run without the node relay and discovery, so
+      # they neither start nor adopt one, and whatever is already on the host is
+      # named here. It reports and never fails: the leftover may be someone's.
+      - name: Isolate this job from node singletons other jobs left on this host
+        run: |
+          set -uo pipefail
+          echo "NORSK_CTL_MOQ_RELAY_ENABLE=0" >> "$GITHUB_ENV"
+          echo "NORSK_CTL_DISCOVERY_ENABLE=0" >> "$GITHUB_ENV"
+          left="$(docker ps -a --filter label=norsk-ctl.role --format '{{.Names}} {{.Label "norsk-ctl.role"}} {{.Status}} (created {{.CreatedAt}})' 2>/dev/null || true)"
+          if [ -z "$left" ]; then echo "no norsk-ctl containers on this host"; exit 0; fi
+          echo "norsk-ctl containers already on this host (other jobs' running instances are expected):"
+          echo "$left"
+          while IFS= read -r line; do
+            role="$(awk '{print $2}' <<<"$line")"
+            case "$role" in
+              moq-relay|discovery)
+                echo "::warning title=node singleton left on this host::$line -- left by an earlier job (a daemon's auto-start, or a run killed before its reap). This job's daemons run without it and will not adopt it; remove it with docker rm -f if nothing on this host needs it." ;;
+            esac
+          done <<<"$left"
+
       # 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.
       #
       # 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
+      # daemon the dev shell launches, moved by bump.yml's nightly 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;
@@ -311,7 +337,7 @@ jobs:
             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; }
+            [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (the nightly bump.yml 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"

package/conventions/publish-docs.yml

@@ -22,6 +22,9 @@
 #
 # Nightly-only by design: a guide's engine tier stands up real instances (slow,
 # and subject to teardown flakes), so it does not ride every push. The
+# deterministic tiers decide this workflow's result; the engine tier reports
+# without failing it (norsk-ctl task 57), and a failed engine tier keeps
+# yesterday's manual rather than publishing one with gaps. The
 # licensed-runner setup mirrors integration.yml — ctl comes from the released
 # binary via NORSK_CTL_BINARY, Docker is used directly on the x64 pool.
 name: publish-docs
@@ -46,6 +49,8 @@ concurrency:
 jobs:
   publish:
     runs-on: x64
+    outputs:
+      engine: ${{ steps.engine.outcome }}
     # One guide run per repo at a time, nightly and publish gate alike: both
     # launch the same instance ids on the x64 pool's shared docker daemon, and
     # ctl names each compose project after its instance id. Queue, never cancel.
@@ -174,15 +179,40 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
+      # Every norsk-ctl daemon starts the node MoQ relay (norsk-moq-relay) unless
+      # told not to, and nothing removes it: it is a node singleton, and the reap
+      # step only takes containers that mount this job's test-temp. So the first
+      # test daemon on a shared runner left one, and every later one adopted it
+      # (probe's smoke ran in relay mode on 2026-10-10; relay's smoke lost 4443
+      # to it). This job's daemons run without the node relay and discovery, so
+      # they neither start nor adopt one, and whatever is already on the host is
+      # named here. It reports and never fails: the leftover may be someone's.
+      - name: Isolate this job from node singletons other jobs left on this host
+        run: |
+          set -uo pipefail
+          echo "NORSK_CTL_MOQ_RELAY_ENABLE=0" >> "$GITHUB_ENV"
+          echo "NORSK_CTL_DISCOVERY_ENABLE=0" >> "$GITHUB_ENV"
+          left="$(docker ps -a --filter label=norsk-ctl.role --format '{{.Names}} {{.Label "norsk-ctl.role"}} {{.Status}} (created {{.CreatedAt}})' 2>/dev/null || true)"
+          if [ -z "$left" ]; then echo "no norsk-ctl containers on this host"; exit 0; fi
+          echo "norsk-ctl containers already on this host (other jobs' running instances are expected):"
+          echo "$left"
+          while IFS= read -r line; do
+            role="$(awk '{print $2}' <<<"$line")"
+            case "$role" in
+              moq-relay|discovery)
+                echo "::warning title=node singleton left on this host::$line -- left by an earlier job (a daemon's auto-start, or a run killed before its reap). This job's daemons run without it and will not adopt it; remove it with docker rm -f if nothing on this host needs it." ;;
+            esac
+          done <<<"$left"
+
       # 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
+      # bump.yml's nightly 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="$( { 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; }
+          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (the nightly bump.yml 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"
@@ -204,13 +234,15 @@ jobs:
             ./scripts/doc-guide/prepull-extra.sh
           fi
 
-      # Rebuild every workspace the manual depends on (a guide's engine tier packs
-      # the freshly-built dashboard + frontend dist into the launched template),
-      # then run the product's doc-guide tiers and assemble the manual.
-      # regen-manual.sh owns the slug list and which tiers run; with-display.sh
-      # wraps the whole run in an X display for headless chromium (the engine tier
-      # drives a raw chromium that needs one).
-      - name: Regenerate the illustrated manual (all tiers)
+      # The deterministic tiers (fixture and frontend: no daemon, no instances),
+      # then the manual assembled from what they captured. These gate. The engine
+      # tier runs on its own below: it stands up real instances, is known-flaky
+      # on container DNS (norsk-ctl task 57), and reports without gating until
+      # that is fixed (ci-workflows docs/dashboard/ci-fragility.md, proposal E).
+      # regen-manual.sh owns the slug list and honours SKIP_ENGINE; it rebuilds
+      # every workspace the manual depends on first, and with-display.sh gives
+      # headless chromium an X display.
+      - name: Regenerate the illustrated manual (deterministic tiers)
         env:
           NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
           NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
@@ -223,6 +255,7 @@ jobs:
           # them binding no host ports — so concurrent doc-guide instances can't
           # collide on the product's deterministic host-port bands.
           NORSK_TEST_NET: direct
+          SKIP_ENGINE: "1"
         run: |
           nix develop .#build --command bash -c '
             set -euo pipefail
@@ -237,11 +270,71 @@ jobs:
             bash scripts/with-display.sh scripts/doc-guide/regen-manual.sh
           '
 
+      # The engine tier: real instances, driven in a browser. Reported, not
+      # gating (see the deterministic step). A non-zero exit is forgiven only
+      # when the tier's own results say a teardown hook timed out after every
+      # guide's test passed (doc-guide/engine-verdict.ts), as regen-manual.sh
+      # forgives it. A product with no docs:guides:engine script has no engine
+      # tier. Runs on the workspaces the step before it installed and built.
+      - name: Run the engine-tier guides (reported, not gating)
+        id: engine
+        continue-on-error: true
+        env:
+          NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
+          NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
+          # This runner launches Studio as a HOST sibling (DooD), so the harness
+          # reaches host-published ports via the host-gateway alias, not
+          # localhost — same as the integration suite.
+          NORSK_TEST_HOST: host.docker.internal
+          # Reach launched instances over norsk-net by service DNS (as the
+          # integration tier already does) AND, on a ctl that supports it, launch
+          # them binding no host ports — so concurrent doc-guide instances can't
+          # collide on the product's deterministic host-port bands.
+          NORSK_TEST_NET: direct
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            if ! jq -e ".scripts[\"docs:guides:engine\"]" package.json >/dev/null; then
+              echo "no docs:guides:engine script: this product has no engine tier"
+              exit 0
+            fi
+            export DOCS_GENERATE=1
+            log="$(mktemp)"
+            if bash scripts/with-display.sh bun run docs:guides:engine >"$log" 2>&1; then
+              cat "$log"
+            else
+              cat "$log"
+              verdict="$(bun -e "console.log(Bun.resolveSync(\"@norskvideo/ctl-dev-kit/doc-guide/engine-verdict\", process.cwd()))")"
+              bun "$verdict" "$log"
+            fi
+          '
+
+      # Only after a passing engine tier: the deterministic step assembled a
+      # manual with the engine pages as gaps.
+      - name: Assemble the manual with the engine captures
+        if: ${{ steps.engine.outcome == 'success' }}
+        run: nix develop .#build --command bun run docs:manual
+
+      # Said three ways, so a failure is never silent: a warning on the run, a
+      # line in its summary, and the cell's detail (the notify job).
+      - name: Report the engine tier (not gating)
+        if: ${{ !cancelled() }}
+        env:
+          OUTCOME: ${{ steps.engine.outcome }}
+        run: |
+          case "$OUTCOME" in
+            success) echo "engine-tier guides passed (or this product has none)" ;;
+            failure)
+              echo "::warning title=engine-tier guides failed (not gating)::the engine tier does not gate until norsk-ctl task 57 is fixed. The manual was not republished: yesterday's stays. See the engine step's log."
+              printf '### Engine-tier guides: failed (not gating)\n\nThe deterministic guide tiers gate; the engine tier only reports until its container networking is fixed (norsk-ctl task 57). The manual was not republished: yesterday's stays. See the step log.\n' >> "$GITHUB_STEP_SUMMARY" ;;
+            *) echo "engine tier: ${OUTCOME:-not run}" ;;
+          esac
+
       # Publish the assembled manual as the moving docs-latest release asset.
       # gh is on PATH inside the nix shell; `upload --clobber` replaces the
       # same-named asset in place, so the release stays latest-only.
       - name: Publish manual.html to the moving docs-latest release
-        if: ${{ github.event_name != 'workflow_dispatch' || inputs.publish }}
+        if: ${{ steps.engine.outcome == 'success' && (github.event_name != 'workflow_dispatch' || inputs.publish) }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -290,7 +383,7 @@ jobs:
       # exports map, so this works whether ctl-dev-kit is the published package or
       # a workspace link (scripts/set-ctl-source.ts local mode).
       - name: Publish the versioned docs bundle and move the pointer
-        if: ${{ github.event_name != 'workflow_dispatch' || inputs.publish }}
+        if: ${{ steps.engine.outcome == 'success' && (github.event_name != 'workflow_dispatch' || inputs.publish) }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # How many bundles to keep on the release, the current one included.
@@ -325,7 +418,7 @@ jobs:
       # key through ci-workflows' registry, so a new product needs no new mapping
       # here. Not wrapped in nix -- plain curl, and the quoting stays readable.
       - name: Tell norsk-ctl a new bundle is published
-        if: ${{ github.event_name != 'workflow_dispatch' || inputs.publish }}
+        if: ${{ steps.engine.outcome == 'success' && (github.event_name != 'workflow_dispatch' || inputs.publish) }}
         env:
           DISPATCH_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
         run: |
@@ -437,6 +530,8 @@ jobs:
           product: __PRODUCT__
           pipeline: docs
           status: ${{ steps.meta.outputs.state }}
+          # The engine tier reports, never gates; a failure keeps yesterday's manual.
+          detail: "${{ needs.publish.outputs.engine == 'failure' && 'engine-tier guides failed (not gating; norsk-ctl task 57): the manual was not republished' || '' }}"
       - name: Reap the containers this job launched
         # Whatever the tests did. A teardown cut short by a test timeout leaves
         # its instance running on the shared Docker daemon (see JOB_REAP_STEP in