@norskvideo/ctl-dev-kit 0.2.31 → 0.2.33

package/build/flake.sdk-app.nix

@@ -48,8 +48,7 @@
             pkgs.git
             ffmpegFull # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
           ] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.chromium ];
-        in {
-          default = pkgs.mkShell {
+          shell = pkgs.mkShell {
             BIOME_BINARY = "${biome}/bin/biome";
             buildInputs = tools;
             shellHook = ''
@@ -59,6 +58,14 @@
               export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
             '';
           };
+        in {
+          # One shell under every name the canonical workflows and the Studio
+          # flake use: `build` is what CI enters (`nix develop .#build`). An
+          # sdk-app fetches no norsk-ctl binary, so there is no leaner shell to
+          # keep apart for builds.
+          default = shell;
+          dev = shell;
+          build = shell;
         });
     };
 }

package/conventions/biome.base.json

@@ -31,6 +31,7 @@
       "**/*.js",
       "**/*.json",
       "!**/node_modules",
+      "!**/vendor",
       "!**/dist",
       "!**/generated",
       "!**/_gen",

package/conventions/check-drift.ts

@@ -290,6 +290,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;
 }
 
 // 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
@@ -650,15 +654,20 @@ 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.
+  // 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",
-        "conventions/upgrade-latest.yml",
+        shape === "sdk-app" ? "conventions/upgrade-latest.sdk-app.yml" : "conventions/upgrade-latest.yml",
         readFileSync(workflowPath, "utf8"),
-        canonical.upgradeLatest,
+        upgradeCanon,
       ),
     );
   }
@@ -820,6 +829,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"),
   };
   const report = checkDrift(repoRoot, canonical, {
     repoName: resolveRepoName(repoRoot),

package/conventions/sync-drift.ts

@@ -296,7 +296,10 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: Pr
   writeIfChanged(join(repoRoot, "tsconfig.base.json"), canonical.tsconfigBase, "tsconfig.base.json", r.written);
 
   syncWorkflow(repoRoot, ".github/workflows/checks.yml", checksCanon, r);
-  syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
+  // upgrade-latest too: an sdk-app has no Studio pair, so it has its own variant
+  const upgradeCanon = shape === "sdk-app" ? canonical.upgradeLatestSdkApp : canonical.upgradeLatest;
+  if (upgradeCanon === undefined) throw new Error(`syncDrift: shape "${shape}" requires canonical.upgradeLatestSdkApp`);
+  syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", upgradeCanon, r);
   syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
   // No per-repo line to preserve, so it is written whole -- and CREATED where
   // absent, unlike syncWorkflow's copies. That is how a repo acquires the
@@ -369,6 +372,7 @@ if (import.meta.main) {
     demoShim: readFileSync(join(dir, "demo.sh"), "utf8"),
     flakeSdkApp: readFileSync(join(dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
+    upgradeLatestSdkApp: readFileSync(join(dir, "upgrade-latest.sdk-app.yml"), "utf8"),
   };
   const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot));
   if (report.written.length === 0) {

package/conventions/upgrade-latest.sdk-app.yml

@@ -0,0 +1,422 @@
+# The sdk-app variant of upgrade-latest.yml: keep a bespoke-SDK product (no
+# Studio -- norsk-relay) fresh against the Norsk "nightly" channel (RFC 0001 --
+# product version freshness). Kept in lockstep with upgrade-latest.yml outside
+# the bump step; check-drift holds an sdk-app repo's copy to THIS file.
+#
+# An sdk-app has no Studio, so no {engine, studio} pair to take from
+# norsk-studio's channel manifest and no manifest.seed.json to anchor on. Its
+# whole norsk family is ONE version string: the @norskvideo/norsk-sdk and
+# norsk-api npm packages and the norskvideo/norsk engine image are built from
+# one commit and published under one version. The product's own exact
+# norsk-sdk pin is the current value; the SDK's npm nightly is the new one, and
+# the step confirms norsk-api and the engine image exist at it BEFORE rewriting
+# anything. Then every occurrence of the old string moves, lockfile aside (bun
+# install regenerates it) -- including the engine image ref the product's
+# template launches, which an sdk-app pins in its own source.
+#
+# Nightly cron + on demand. The bump runs the product's own gate (lint,
+# typecheck, unit tests) BEFORE it lands, exactly as upgrade-latest.yml and
+# sync-dev-kit do: green lands on main, red opens a reconciliation PR and main
+# stays green. The push is made with CI_DISPATCH_TOKEN (a PAT), so the push to
+# main fires the product's own workflows -- a GITHUB_TOKEN push would fire
+# nothing. No norsk-ctl pin to refresh: the sdk-app flake carries none.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/upgrade-latest.sdk-app.yml)
+# and copied verbatim into each sdk-app product repo as
+# .github/workflows/upgrade-latest.yml; the check:drift gate fails CI if a copy
+# diverges. Only the `product:` value below is per-repo (set it to this repo's
+# dashboard key); everything else must match the dev-kit source. Never hand-edit
+# the copy — edit the dev-kit source and re-sync.
+name: upgrade-latest
+
+on:
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    runs-on: x64
+    outputs:
+      changed: ${{ steps.bump.outputs.changed }}
+      summary: ${{ steps.bump.outputs.summary }}
+    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
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          clean: true
+
+      - name: Resolve the SDK nightly and rewrite the norsk family
+        id: bump
+        run: |
+          set -euo pipefail
+          reg="https://registry.npmjs.org"
+          hub="https://hub.docker.com/v2/repositories/norskvideo/norsk/tags"
+          tag_re='^[0-9]+\.[0-9]+\.[0-9]+-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9a-f]+$'
+          changed=0
+          summary=""
+
+          # CURRENT: the product's exact norsk-sdk pin, wherever a tracked
+          # package.json carries it (deps, devDeps or overrides). It is the one
+          # string the family shares, so exactly one distinct value: none means
+          # nothing to anchor on, two means a rewrite would leave half behind.
+          old="$(git grep -hoE '"@norskvideo/norsk-sdk"[[:space:]]*:[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9a-f]+"' -- '*package.json' \
+            | sed -E 's/.*"([^"]+)"$/\1/' | sort -u || true)"
+          case "$(printf '%s' "$old" | grep -c .)" in
+            1) ;;
+            0) echo "::error::no exact @norskvideo/norsk-sdk nightly pin in any package.json: nothing to anchor the bump on"; exit 1 ;;
+            *) echo "::error::@norskvideo/norsk-sdk pins disagree across package.json files:"; echo "$old"; exit 1 ;;
+          esac
+
+          # NEW: the SDK's npm nightly. Not norsk-studio's channel manifest: that
+          # pairs the engine with a Studio image, and an sdk-app runs no Studio,
+          # so it would hold the product back whenever Studio's nightly stalls.
+          new="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$reg/@norskvideo%2Fnorsk-sdk" | jq -r '."dist-tags".nightly // empty')"
+          printf '%s' "$new" | grep -qE "$tag_re" || { echo "::error::the norsk-sdk npm nightly is not a dated nightly version: '$new'"; exit 1; }
+
+          # Everything resolved and checked BEFORE anything is rewritten, so a
+          # refusal never leaves the SDK moved and the API or the engine not.
+          api_has="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$reg/@norskvideo%2Fnorsk-api" | jq -r --arg v "$new" '.versions[$v] | if . == null then "" else "yes" end')"
+          [ "$api_has" = "yes" ] || { echo "::error::@norskvideo/norsk-api has no $new: the SDK nightly is not a whole family yet"; exit 1; }
+          curl -fsS --retry 3 --retry-delay 2 -o /dev/null "$hub/$new" ||
+            { echo "::error::the engine image norskvideo/norsk:$new is not published: not pinning an engine nobody can pull"; exit 1; }
+
+          # STRANDED: the rewrite below is a literal replace of the anchor, so a
+          # family pin that has drifted off it is invisible to this bump and to
+          # every later one, while the job reports success. Fail and name it
+          # rather than move it: a pin held back may be someone's decision.
+          stranded="$(git grep -hoE '"@norskvideo/norsk-(api|sdk|auto-manager|manager-sdk)"[[:space:]]*:[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9a-f]+"' -- '*package.json' \
+            | sed -E 's/.*"([^"]+)"$/\1/' | sort -u | grep -vxF "$old" | grep -vxF "$new" || true)"
+          if [ -n "$stranded" ]; then
+            echo "::error::npm norsk pins are stranded off the family: $(printf '%s' "$stranded" | tr '\n' ' ')"
+            echo "The family (api, sdk, auto-manager, manager-sdk) and the engine image share one version, so every pin"
+            echo "must read $new. These do not, and no later bump can reach them either. Set them to $new."
+            exit 1
+          fi
+
+          echo "norsk family: $old -> $new"
+          if [ "$old" != "$new" ]; then
+            git grep -lF "$old" -- . ':!bun.lock' | xargs -r sed -i "s|$old|$new|g"
+            changed=1
+            summary="media \`$new\`"
+          fi
+          {
+            echo "changed=$changed"
+            echo "summary=$summary"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Refresh the lockfile against the new pins
+        if: steps.bump.outputs.changed == '1'
+        # Per INSTALL ROOT: the rewrites above walk every tracked package.json,
+        # and a manifest outside the root workspace list owns a lockfile a
+        # root-only install never regenerates. See lockfile-reinstall.test.ts.
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            for lock in $(git ls-files "*bun.lock"); do
+              (cd "$(dirname "$lock")" && bun install)
+            done
+          '
+
+      - name: Run the product gate against the bumped pins
+        id: gate
+        if: steps.bump.outputs.changed == '1'
+        # continue-on-error so a red gate can open a PR below instead of failing
+        # the workflow -- which is why the steps after it read `outcome` and not
+        # `conclusion` (continue-on-error rewrites conclusion to success).
+        continue-on-error: true
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun run lint
+            bun run typecheck
+            bun run test:unit
+          '
+
+      - name: Land the bump on main (gate green)
+        if: steps.bump.outputs.changed == '1' && steps.gate.outcome == 'success'
+        env:
+          API_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+          # Through env, never pasted into the script (see the PR step below).
+          SUMMARY: ${{ steps.bump.outputs.summary }}
+        run: |
+          set -euo pipefail
+          # This bump is about to land, which makes any upgrade-latest/* PR an earlier
+          # red run opened obsolete. Left open they piled up -- nine were closed
+          # by hand on 2026-10-03 -- so close them once the push has landed.
+          # Best-effort: a failure here must not fail the landing.
+          close_superseded() {
+            api="https://api.github.com/repos/$GITHUB_REPOSITORY"
+            auth=(-H "Authorization: Bearer $API_TOKEN" -H "Accept: application/vnd.github+json")
+            for n in $(curl -sS "${auth[@]}" "$api/pulls?state=open&per_page=100" \
+                | jq -r --arg repo "$GITHUB_REPOSITORY" '.[] | select(.head.repo.full_name == $repo and (.head.ref | startswith("upgrade-latest/"))) | .number'); do
+              curl -sS -o /dev/null "${auth[@]}" -X POST "$api/issues/$n/comments" \
+                -d '{"body":"Superseded: a later upgrade-latest run landed its bump on main."}'
+              curl -sS -o /dev/null "${auth[@]}" -X PATCH "$api/pulls/$n" -d '{"state":"closed"}'
+              echo "closed superseded PR #$n"
+            done
+          }
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "chore: bump the Norsk family to the SDK nightly
+
+          ${SUMMARY}
+
+          The norsk-sdk / norsk-api pins and the engine image ref moved together
+          via a global version-string replace; lockfile regenerated."
+          # main can advance under a long bump (lockfile regen + registry
+          # lookups run for minutes); a bare push then loses a non-fast-forward
+          # race and reds the nightly. Rebase-and-retry so an unrelated commit
+          # landing mid-run does not fail the bump; a genuine content conflict
+          # still aborts loudly rather than force-pushing over other work.
+          for attempt in 1 2 3 4 5; do
+            if git push origin HEAD:main; then close_superseded || true; exit 0; fi
+            echo "push rejected (attempt $attempt) - rebasing onto latest origin/main"
+            # --unshallow, not a plain fetch: these runners keep their .git
+            # between jobs, and a commit an earlier job fetched at depth 1 stays
+            # recorded as parentless. A plain fetch does not re-fetch an object it
+            # already holds, so main's tip can look like an unrelated root and the
+            # rebase replays our base commit over it -- add/add conflicts on every
+            # file it touches (playout + studio, 2026-10-03). The fallback covers
+            # a repo that is already complete, where --unshallow is refused.
+            git fetch --unshallow origin main 2>/dev/null || git fetch origin main
+            git rebase origin/main || { git rebase --abort; echo "rebase hit a real conflict; aborting"; exit 1; }
+          done
+          echo "push still failing after 5 rebase attempts"; exit 1
+
+      - name: Open a reconciliation PR (gate red)
+        if: steps.bump.outputs.changed == '1' && steps.gate.outcome == 'failure'
+        env:
+          API_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+          # Through env, never pasted into the script: the summary wraps each
+          # version in backticks, and inside a double-quoted shell string those
+          # ran as commands ("1.3.1-...: command not found"), dropping every
+          # version from the commit message and PR body.
+          SUMMARY: ${{ steps.bump.outputs.summary }}
+        run: |
+          set -euo pipefail
+          branch="upgrade-latest/nightly"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add -A
+          git commit -m "chore: bump the Norsk family to the SDK nightly (needs reconciliation)
+
+          ${SUMMARY}"
+          git push -f origin "$branch"
+          title="Bump the Norsk family to the SDK nightly"
+          body="$(printf '%s\n' \
+            "Automated nightly pin bump: the Norsk nightly channel moved and the coupled" \
+            "pins came with it -- but the product gate is **red**, so this bump needs a" \
+            "human before it reaches main." \
+            "" \
+            "    ${SUMMARY}" \
+            "" \
+            "A red gate here usually means the new Norsk nightly is bad, or genuinely" \
+            "changed something the product depends on. Run it to see which:" \
+            "" \
+            "    bun run lint && bun run typecheck && bun run test:unit" \
+            "" \
+            "Fix it on this branch and merge, or close this PR to skip the bump -- the" \
+            "next nightly run reopens it against whatever the channel holds then.")"
+          # gh is not on the self-hosted runner PATH (it lives only inside
+          # `nix develop`, and this step runs outside it), so create/update the PR
+          # straight against the REST API with the same PAT that pushed the branch.
+          # The PAT (not GITHUB_TOKEN) is what lets the PR's own checks run, which
+          # is the whole point: the bump is judged before it lands, not after.
+          repo="${{ github.repository }}"; owner="${repo%%/*}"
+          api="https://api.github.com/repos/$repo/pulls"
+          curl_api=(--fail-with-body -sS -H "Authorization: Bearer $API_TOKEN" -H "Accept: application/vnd.github+json")
+          existing="$(curl "${curl_api[@]}" "$api?head=$owner:$branch&state=open" | jq -r '.[0].number // empty')"
+          if [ -n "$existing" ]; then
+            curl "${curl_api[@]}" -X PATCH "$api/$existing" \
+              --data "$(jq -nc --arg t "$title" --arg b "$body" '{title:$t, body:$b}')" > /dev/null
+            echo "updated PR #$existing"
+          else
+            curl "${curl_api[@]}" -X POST "$api" \
+              --data "$(jq -nc --arg t "$title" --arg b "$body" --arg h "$branch" \
+                '{title:$t, body:$b, head:$h, base:"main"}')" | jq -r '"opened PR #\(.number)"'
+          fi
+
+      - name: Report "already fresh"
+        if: steps.bump.outputs.changed != '1'
+        run: echo "Nightly pins already current — nothing to bump."
+      - 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
+        # conventions/workflow-shell.ts); everything this job launched mounts its
+        # own test-temp, so that is what goes.
+        if: always()
+        run: |
+          base="${NORSK_CTL_TEST_TMP:-}"
+          tt="$GITHUB_WORKSPACE/test-temp"
+          s=""
+          for c in $(docker ps -aq); do
+            src="$(docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null)" || continue
+            if { [ -n "$base" ] && grep -q "^$base/" <<<"$src"; } || grep -q "^$tt/" <<<"$src"; then s="$s $c"; fi
+          done
+          if [ -n "$s" ]; then
+            echo "::warning::removing containers this job left running:$s"
+            docker rm -f $s
+          fi
+
+  # Report the nightly bump result to the aggregated product CI dashboard
+  # (id3as/ci-workflows). !cancelled() so a failed bump shows a sad pony (a
+  # cancelled/superseded run must not false-red the board); the summary rides
+  # along as the cell detail.
+  notify:
+    needs: bump
+    if: ${{ !cancelled() }}
+    runs-on: x64
+    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
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+      - id: meta
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
+            echo "state=failure" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=success" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: ./.github/actions/ci-status-dispatch
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          product: __PRODUCT__
+          pipeline: nightly
+          status: ${{ steps.meta.outputs.state }}
+          detail: ${{ needs.bump.outputs.summary }}
+      - 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
+        # conventions/workflow-shell.ts); everything this job launched mounts its
+        # own test-temp, so that is what goes.
+        if: always()
+        run: |
+          base="${NORSK_CTL_TEST_TMP:-}"
+          tt="$GITHUB_WORKSPACE/test-temp"
+          s=""
+          for c in $(docker ps -aq); do
+            src="$(docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null)" || continue
+            if { [ -n "$base" ] && grep -q "^$base/" <<<"$src"; } || grep -q "^$tt/" <<<"$src"; then s="$s $c"; fi
+          done
+          if [ -n "$s" ]; then
+            echo "::warning::removing containers this job left running:$s"
+            docker rm -f $s
+          fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",