@norskvideo/ctl-test-harness 0.1.69 → 0.1.71

package/daemon.d.ts

@@ -31,6 +31,9 @@ export interface DaemonProcess {
     exited: Promise<number | null>;
 }
 export interface StartDaemonOptions {
+    /** The port the daemon binds. 0 lets the kernel choose — only against a ctl
+     *  that publishes it (see {@link ctlSupportsEphemeralPorts}); the daemon's
+     *  `running` says which it got. */
     port?: number;
     env?: Record<string, string>;
     /** Spawn in its own process group so a caller can group-kill the whole
@@ -41,7 +44,42 @@ export interface StartDaemonOptions {
      *  from a virgin store, so they turn this off. Default true. */
     seedConfig?: boolean;
     readyTimeoutMs?: number;
+    /** The CLI to run `serve` from. Default: the resolved norsk-ctl (cli-command.ts). */
+    command?: readonly string[];
 }
+/** What a started daemon turned out to be answering on. */
+export interface RunningDaemon {
+    daemonPort: number;
+    /** Its proxy's host port, when the daemon published one (`proxy.port`). An
+     *  older ctl publishes none. */
+    proxyPort?: number;
+}
+export interface StartedDaemon {
+    daemon: DaemonProcess;
+    ready: Promise<void>;
+    /** Resolves once ready, with the ports the daemon actually answers on. */
+    running: Promise<RunningDaemon>;
+}
+/** Files a daemon publishes into its store once it knows them (ctl's
+ *  backend/src/lib/daemon-port.ts). */
+export declare const DAEMON_PORT_FILE = "daemon.port";
+export declare const PROXY_PORT_FILE = "proxy.port";
+/** A port a daemon published into its store, or undefined when it has not. */
+export declare function readPortFile(storeDir: string, name: string): number | undefined;
+/** The named daemon capability (ctl's shared/src/daemon-capabilities.ts):
+ *  NORSK_CTL_PORT=0 and proxyPort 0 run on system-assigned ports, published as
+ *  daemon.port and proxy.port. */
+export declare const EPHEMERAL_PORTS_CAPABILITY = "ephemeral-ports";
+/** Whether `command` advertises the ephemeral-ports capability, asked of the
+ *  binary itself — the daemon does not exist yet when the answer is needed.
+ *  A ctl that predates `norsk-ctl capabilities` fails the command, which reads
+ *  as no. NORSK_CTL_PORT points at nothing: an older ctl probes the daemon for
+ *  product commands when it does not know the first word, and the developer's
+ *  daemon has no part in this answer. */
+export declare function probeEphemeralPorts(command: readonly string[]): Promise<boolean>;
+/** Whether the resolved norsk-ctl runs its daemon and proxy on system-assigned
+ *  ports. Memoised: one spawn per process. */
+export declare function ctlSupportsEphemeralPorts(): Promise<boolean>;
 /** Root the instance working directory under the store dir (itself under
  *  TEST_TMP_BASE) rather than the daemon default ~/norsk-runtime. The launcher
  *  bind-mounts the workdir as /data and then mounts the stored template's
@@ -71,10 +109,7 @@ export declare function daemonSpawnEnv(o: {
     inherited: Record<string, string | undefined>;
     overrides?: Record<string, string>;
 }): Record<string, string | undefined>;
-export declare function startDaemon(storeDir: string, options?: StartDaemonOptions): {
-    daemon: DaemonProcess;
-    ready: Promise<void>;
-};
+export declare function startDaemon(storeDir: string, options?: StartDaemonOptions): StartedDaemon;
 /**
  * Tear down a daemon-based test: delete instances, stop proxy, stop daemon, kill
  * process, rm store. The teardown actions are injected as pre-bound thunks

package/daemon.js

@@ -120,6 +120,65 @@ function daemonHandle(proc) {
         exited,
     };
 }
+/** Files a daemon publishes into its store once it knows them (ctl's
+ *  backend/src/lib/daemon-port.ts). */
+export const DAEMON_PORT_FILE = "daemon.port";
+export const PROXY_PORT_FILE = "proxy.port";
+/** A port a daemon published into its store, or undefined when it has not. */
+export function readPortFile(storeDir, name) {
+    try {
+        const port = Number(readFileSync(join(storeDir, name), "utf-8").trim());
+        return Number.isInteger(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The named daemon capability (ctl's shared/src/daemon-capabilities.ts):
+ *  NORSK_CTL_PORT=0 and proxyPort 0 run on system-assigned ports, published as
+ *  daemon.port and proxy.port. */
+export const EPHEMERAL_PORTS_CAPABILITY = "ephemeral-ports";
+/** Whether `command` advertises the ephemeral-ports capability, asked of the
+ *  binary itself — the daemon does not exist yet when the answer is needed.
+ *  A ctl that predates `norsk-ctl capabilities` fails the command, which reads
+ *  as no. NORSK_CTL_PORT points at nothing: an older ctl probes the daemon for
+ *  product commands when it does not know the first word, and the developer's
+ *  daemon has no part in this answer. */
+export function probeEphemeralPorts(command) {
+    return new Promise((resolve) => {
+        const [cmd, ...args] = command;
+        const proc = spawn(cmd, [...args, "capabilities"], {
+            env: { ...process.env, NORSK_CTL_PORT: "1" },
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const out = [];
+        const timer = setTimeout(() => proc.kill("SIGKILL"), 30_000);
+        proc.stdout?.on("data", (d) => out.push(d));
+        proc.once("error", () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+        proc.once("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0)
+                return resolve(false);
+            try {
+                const body = JSON.parse(Buffer.concat(out).toString());
+                resolve(Array.isArray(body.daemonCapabilities) && body.daemonCapabilities.includes(EPHEMERAL_PORTS_CAPABILITY));
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    });
+}
+let ephemeralSupport;
+/** Whether the resolved norsk-ctl runs its daemon and proxy on system-assigned
+ *  ports. Memoised: one spawn per process. */
+export function ctlSupportsEphemeralPorts() {
+    ephemeralSupport ??= probeEphemeralPorts(cliCommand);
+    return ephemeralSupport;
+}
 /** Root the instance working directory under the store dir (itself under
  *  TEST_TMP_BASE) rather than the daemon default ~/norsk-runtime. The launcher
  *  bind-mounts the workdir as /data and then mounts the stored template's
@@ -173,13 +232,19 @@ export function daemonSpawnEnv(o) {
 }
 export function startDaemon(storeDir, options) {
     const port = options?.port ?? 8333;
-    // Before the spawn, so anything reaching for this daemon's ingress secret can
-    // find its store by the port it will answer on (daemon-stores.ts).
-    rememberDaemonStore(port, storeDir);
-    killProcessOnPort(port);
+    const command = options?.command ?? cliCommand;
+    // Whatever a previous daemon on this store published is not this one's.
+    for (const f of [DAEMON_PORT_FILE, PROXY_PORT_FILE])
+        rmSync(join(storeDir, f), { force: true });
+    if (port !== 0) {
+        // Before the spawn, so anything reaching for this daemon's ingress secret
+        // can find its store by the port it will answer on (daemon-stores.ts).
+        rememberDaemonStore(port, storeDir);
+        killProcessOnPort(port);
+    }
     if (options?.seedConfig !== false)
         seedDaemonConfig(storeDir);
-    const [cmd, ...cmdArgs] = cliCommand;
+    const [cmd, ...cmdArgs] = command;
     const proc = spawn(cmd, [...cmdArgs, "serve"], {
         stdio: "inherit",
         detached: options?.detached === true,
@@ -191,20 +256,33 @@ export function startDaemon(storeDir, options) {
         }),
     });
     const spawnFailed = new Promise((_, reject) => {
-        proc.once("error", (e) => reject(new Error(cliUnavailableMessage(cliCommand, e.message))));
+        proc.once("error", (e) => reject(new Error(cliUnavailableMessage(command, e.message))));
     });
-    const ready = Promise.race([
+    const timeoutMs = options?.readyTimeoutMs ?? DAEMON_READY_TIMEOUT_MS;
+    const bound = port !== 0
+        ? Promise.resolve(port)
+        : (async () => {
+            let published;
+            await pollUntil(async () => {
+                published = readPortFile(storeDir, DAEMON_PORT_FILE);
+                return published !== undefined;
+            }, { timeoutMs, intervalMs: 200, label: `Daemon published no ${DAEMON_PORT_FILE} in ${storeDir}` });
+            const p = published;
+            rememberDaemonStore(p, storeDir);
+            return p;
+        })();
+    const running = Promise.race([
         spawnFailed,
-        pollUntil(async () => {
-            const res = await fetch(`http://localhost:${port}/api/ready`, { signal: AbortSignal.timeout(1000) });
-            return res.ok;
-        }, {
-            timeoutMs: options?.readyTimeoutMs ?? DAEMON_READY_TIMEOUT_MS,
-            intervalMs: 500,
-            label: "Daemon did not become ready",
+        bound.then(async (daemonPort) => {
+            await pollUntil(async () => {
+                const res = await fetch(`http://localhost:${daemonPort}/api/ready`, { signal: AbortSignal.timeout(1000) });
+                return res.ok;
+            }, { timeoutMs, intervalMs: 500, label: "Daemon did not become ready" });
+            const proxyPort = readPortFile(storeDir, PROXY_PORT_FILE);
+            return { daemonPort, ...(proxyPort !== undefined ? { proxyPort } : {}) };
         }),
     ]);
-    return { daemon: daemonHandle(proc), ready };
+    return { daemon: daemonHandle(proc), ready: running.then(() => undefined), running };
 }
 function runningContainers(names) {
     const result = spawnSync("docker", ["ps", "--format", "{{.Names}}"], { encoding: "utf-8" });
@@ -238,7 +316,12 @@ export async function cleanupDaemon(opts) {
             console.error(`cleanup: delete ${id} failed: ${e}`);
         }
     }
-    if (opts.proxy)
+    // Stop the proxy unless the caller says it never ran one (`proxy: false`).
+    // It used to need `proxy: true`, and three callers passing a real stopProxy
+    // omitted it — so `shutdown --daemon-only` left their proxy pair running.
+    // On the shared ar-arm-vm runner a leftover pair then answered for the next
+    // job's proxy (2026-10-02, norsk-ctl Checks 37048720935).
+    if (opts.proxy ?? true)
         try {
             await opts.stopProxy();
         }

package/demo/cli.d.ts

@@ -24,7 +24,10 @@ export interface ResolvedSpecView {
     slug: string;
     instanceId: string;
     mode: string;
+    /** The band. With `portsAssignedAtStart` the daemon's and proxy's read 0:
+     *  the running daemon is given them, and the plan cannot know them. */
     ports: ReturnType<typeof demoPorts>;
+    portsAssignedAtStart?: true;
     dev: DemoSpec["dev"];
     image?: string;
     template: {
@@ -67,6 +70,7 @@ export declare function resolvedSpecView(spec: DemoSpec, opts: {
     mode: string;
     slug?: string;
     publicHost?: string;
+    ephemeralPorts?: boolean;
 }): ResolvedSpecView;
 /** Everything `demoMain` touches, injectable so the dispatch is unit-tested. */
 export interface DemoCliIo {
@@ -83,6 +87,9 @@ export interface DemoCliIo {
     devLoopDown(product: string): Promise<void>;
     /** Open the multiplexer on the rendered layout; returns its exit code. */
     launchUi(ui: DemoUi, layout: PaneLayout): number;
+    /** Does the resolved ctl run its daemon and proxy on system-assigned ports
+     *  (what `demo` then uses)? Absent = no. */
+    supportsEphemeralPorts?(): Promise<boolean>;
     /** For the standalone dirs (NORSK_DIR, STUDIO_DIR, TO, HOME). */
     env?: Record<string, string | undefined>;
     stdout(line: string): void;

package/demo/cli.js

@@ -24,6 +24,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // TypeScript module whose default export is `defineDemo({...})`. This runs
 // under bun only: the spec is TypeScript and so is every product's dev shell.
 import { resolve } from "node:path";
+import { ctlSupportsEphemeralPorts } from "../daemon.js";
 import { devLoopDown, runDevLoop } from "./dev-loop.js";
 import { runDemo } from "./harness.js";
 import { demoPaneList, devLoopPaneList, launchLayout, renderLayout, standaloneDirs, } from "./panes.js";
@@ -152,7 +153,9 @@ export function parseDemoArgs(argv) {
 export function resolvedSpecView(spec, opts) {
     const slug = opts.slug ?? demoSlug(spec.product);
     const instanceId = `demo-${slug}`;
-    const ports = demoPorts(slug);
+    const band = demoPorts(slug);
+    const ports = opts.ephemeralPorts ? { ...band, daemonPort: 0, proxyPort: 0 } : band;
+    const proxyPort = opts.ephemeralPorts ? "<assigned>" : String(ports.proxyPort);
     const host = opts.publicHost ?? "localhost";
     const pinned = spec.launch?.params?.STUDIO_HOST_PORT;
     const studioHostPort = pinned !== undefined ? Number(pinned) : ports.studioHostPort;
@@ -162,7 +165,7 @@ export function resolvedSpecView(spec, opts) {
         if ("control" in ref)
             return `http://${host}:${ports.backendPort}${ref.control}`;
         if ("proxy" in ref)
-            return `http://${host}:${ports.proxyPort}${ref.proxy.replaceAll("{id}", instanceId)}`;
+            return `http://${host}:${proxyPort}${ref.proxy.replaceAll("{id}", instanceId)}`;
         return `http://${host}:${studioHostPort}${ref.studio}`;
     };
     const t = spec.template;
@@ -175,6 +178,7 @@ export function resolvedSpecView(spec, opts) {
         instanceId,
         mode: opts.mode,
         ports,
+        ...(opts.ephemeralPorts ? { portsAssignedAtStart: true } : {}),
         dev: spec.dev,
         ...(spec.image !== undefined ? { image: spec.image } : {}),
         template,
@@ -259,7 +263,8 @@ export async function demoMain(argv, io) {
         }
         switch (args.action) {
             case "spec": {
-                const view = resolvedSpecView(spec, { mode, ...publicHost });
+                const ephemeralPorts = (await io.supportsEphemeralPorts?.()) === true;
+                const view = resolvedSpecView(spec, { mode, ...publicHost, ephemeralPorts });
                 io.stdout(args.json ? JSON.stringify(view, null, 2) : renderView(view));
                 return 0;
             }
@@ -299,7 +304,7 @@ export async function demoMain(argv, io) {
 function renderView(v) {
     const lines = [
         `${v.product} (${v.mode}) -> instance ${v.instanceId}`,
-        `  daemon :${v.ports.daemonPort}  dev backend :${v.ports.backendPort}  proxy :${v.ports.proxyPort}  studio :${v.ports.studioHostPort}`,
+        `  daemon :${v.portsAssignedAtStart ? "assigned" : v.ports.daemonPort}  dev backend :${v.ports.backendPort}  proxy :${v.portsAssignedAtStart ? "assigned" : v.ports.proxyPort}  studio :${v.ports.studioHostPort}`,
         `  template ${"name" in v.template ? v.template.name : `build ${v.template.build.name}`}`,
     ];
     if (v.image)
@@ -338,6 +343,7 @@ export function defaultDemoCliIo() {
         runDevLoop: (spec, opts) => runDevLoop(spec, opts),
         devLoopDown: (product) => devLoopDown(product),
         launchUi: (ui, layout) => launchLayout(ui, renderLayout(layout, ui), layout),
+        supportsEphemeralPorts: ctlSupportsEphemeralPorts,
         stdout: (line) => console.log(line),
         stderr: (line) => console.error(line),
         abort: controller.signal,

package/demo/dev-loop.js

@@ -121,6 +121,8 @@ export async function runDevLoop(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
     const common = {
         mode: "dev",
         daemon: "private",
+        // The loop's daemon is the driver's own; `refresh` finds it by the record.
+        ephemeralPorts: true,
         ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
         ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
     };
@@ -129,7 +131,11 @@ export async function runDevLoop(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         if (!state || !(await deps.daemonAnswers(state.daemonPort)) || !state.templateName) {
             throw new Error(`dev-loop '${spec.product}' is not up — run \`dev-loop up\` first (it holds; refresh from another pane)`);
         }
-        const s = new DemoSession(spec, slug, opts.cwd, deps, { ...common, storeDir: state.storeDir });
+        const s = new DemoSession(spec, slug, opts.cwd, deps, {
+            ...common,
+            storeDir: state.storeDir,
+            daemonPort: state.daemonPort,
+        });
         const workdir = state.workdir ?? dirs.workdir;
         const studioPort = await exportLoop(s, state.templateName, workdir, true);
         for (const line of describeLoop(s, { ...dirs, workdir }, studioPort))

package/demo/harness.d.ts

@@ -29,6 +29,11 @@ export interface ProductHarnessOptions {
     daemonEnv?: Record<string, string>;
     /** Containers teardown must also wait out — an overridden proxy's pair. */
     extraContainers?: string[];
+    /** Run the private daemon and its proxy on system-assigned ports where the
+     *  resolved ctl can. Off by default: turn it on only once every port this
+     *  harness's caller uses is read from `ports` (or a launch), never from its
+     *  own `demoPorts(slug)` copy — the daemon is not on the band any more. */
+    ephemeralPorts?: boolean;
     /** File every launched instance id is written to, one per line, BEFORE the
      *  launch — what the convention integration.yml's reap step reads after a
      *  cancelled run, when teardown never ran. Default `$NORSK_LAUNCHED_MANIFEST`;

package/demo/harness.js

@@ -54,6 +54,7 @@ export class ProductHarness {
             ...(opts.proxy !== undefined ? { proxy: opts.proxy } : {}),
             ...(opts.daemonEnv !== undefined ? { daemonEnv: opts.daemonEnv } : {}),
             ...(opts.extraContainers !== undefined ? { extraContainers: opts.extraContainers } : {}),
+            ...(opts.ephemeralPorts !== undefined ? { ephemeralPorts: opts.ephemeralPorts } : {}),
         });
     }
     /** Every CLI step this fixture ran, as a reader would type it, with its output. */
@@ -265,7 +266,7 @@ export class ProductHarness {
         if (n > EXTRA_STUDIO_PORTS) {
             throw new Error(`launch ${n + 1}: the band holds ${EXTRA_STUDIO_PORTS + 1} studio host ports — pass params.${STUDIO_HOST_PORT_PARAM}`);
         }
-        return this.ports.proxyPort + n;
+        return this.session.band.proxyPort + n;
     }
 }
 function urlResolver(o) {
@@ -366,6 +367,8 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
         ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
         ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+        // The driver owns every port of this run, so none can be left behind.
+        ephemeralPorts: true,
     });
     if (opts.action === "up") {
         await refuseIfUp(spec, h.session, deps);

package/demo/run.d.ts

@@ -1,6 +1,6 @@
 import { type ManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
 import { ensureRunnerOnNetwork } from "../container-net.js";
-import { type DaemonProcess, type StartDaemonOptions } from "../daemon.js";
+import { type DaemonProcess, type RunningDaemon, type StartDaemonOptions } from "../daemon.js";
 import { type BaseHarnessPorts } from "../harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "../source-pump.js";
 import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec, DemoTemplate } from "./spec.js";
@@ -53,7 +53,11 @@ export interface DemoDeps {
     startDaemon(storeDir: string, options: StartDaemonOptions): {
         daemon: DaemonProcess;
         ready: Promise<void>;
+        running?: Promise<RunningDaemon>;
     };
+    /** Does the resolved ctl run its daemon and proxy on system-assigned ports?
+     *  Optional so an existing custom-deps consumer keeps working; absent = no. */
+    supportsEphemeralPorts?(): Promise<boolean>;
     /** Does a daemon answer /api/ready on this port? (A stale state file otherwise.) */
     daemonAnswers(port: number): Promise<boolean>;
     cli(storeDir: string, argv: string[]): Promise<CliResult>;
@@ -219,6 +223,11 @@ export interface SessionOptions {
     daemonEnv?: Record<string, string>;
     /** Containers teardown must also wait out — an overridden proxy's pair. */
     extraContainers?: string[];
+    /** Private: run the daemon and its proxy on system-assigned ports where the
+     *  resolved ctl can (the band otherwise). Only for a caller that reads every
+     *  port from this session: one holding its own copy of the band would be
+     *  left pointing at nothing. */
+    ephemeralPorts?: boolean;
 }
 /** The host a demo's daemon-port URLs name.
  *
@@ -285,13 +294,19 @@ export declare class DemoSession {
     readonly deps: DemoDeps;
     readonly mode: DemoMode;
     readonly policy: DemoDaemonPolicy;
+    /** The ports this run uses. The daemon's and the proxy's are the band's
+     *  until a daemon with system-assigned ports says otherwise (attachDaemon). */
     readonly ports: DemoPorts;
+    /** The slug's band, as allocated: where every port this session does not
+     *  learn from the daemon comes from. */
+    readonly band: DemoPorts;
     readonly storeDir: string;
     /** The host every printed URL names. */
     readonly host: string;
     readonly publicHost: string | undefined;
-    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
-    readonly proxyBase: string;
+    private readonly proxyScheme;
+    private readonly proxyHost;
+    private readonly ephemeralPorts;
     daemon: DaemonProcess | null;
     dev: ProcessHandle | null;
     extras: string[];
@@ -302,6 +317,8 @@ export declare class DemoSession {
     private readonly daemonEnv;
     private readonly extraContainers;
     constructor(spec: DemoSpec, slug: string, cwd: string, deps: DemoDeps, opts: SessionOptions);
+    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
+    get proxyBase(): string;
     get devUrl(): string;
     templateDir(name: string): string;
     /** What this daemon's guard demands on `/api/*`. Read from the store, for

package/demo/run.js

@@ -31,7 +31,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { parseManifestSeed, repoOf } from "@norskvideo/ctl-sdk/manifest-seed";
 import { preserveInstanceContainerLogs } from "../container-logs.js";
 import { DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, netReachMode } from "../container-net.js";
-import { cleanupDaemon, requireLicenseFile, runCli, startDaemon, } from "../daemon.js";
+import { cleanupDaemon, ctlSupportsEphemeralPorts, PROXY_PORT_FILE, requireLicenseFile, runCli, startDaemon, } from "../daemon.js";
 import { hashSlot } from "../harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "../launch.js";
 import { pollUntil } from "../poll.js";
@@ -253,6 +253,7 @@ export function defaultDemoDeps(cwd) {
         },
         fileExists: (path) => existsSync(path),
         startDaemon,
+        supportsEphemeralPorts: ctlSupportsEphemeralPorts,
         daemonAnswers: async (port) => {
             try {
                 const r = await fetch(`http://localhost:${port}/api/ready`, { signal: AbortSignal.timeout(1000) });
@@ -392,13 +393,19 @@ export class DemoSession {
     deps;
     mode;
     policy;
+    /** The ports this run uses. The daemon's and the proxy's are the band's
+     *  until a daemon with system-assigned ports says otherwise (attachDaemon). */
     ports;
+    /** The slug's band, as allocated: where every port this session does not
+     *  learn from the daemon comes from. */
+    band;
     storeDir;
     /** The host every printed URL names. */
     host;
     publicHost;
-    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
-    proxyBase;
+    proxyScheme;
+    proxyHost;
+    ephemeralPorts;
     daemon = null;
     dev = null;
     extras = [];
@@ -420,19 +427,27 @@ export class DemoSession {
         this.host = host;
         // The proxy is a container even when the daemon is ours; see proxyUrlHost.
         const proxyHost = proxyUrlHost({ publicHost: opts.publicHost, inContainer: runningInContainer() });
+        this.proxyHost = proxyHost;
+        this.band = demoPorts(slug);
+        this.ephemeralPorts = opts.ephemeralPorts === true;
         if (opts.daemon === "reuse") {
             const daemonPort = opts.daemonPort ?? (Number(process.env.NORSK_CTL_PORT) || DEFAULT_DAEMON_PORT);
             this.storeDir = deps.realStoreDir();
             const proxy = parseProxyConfig(deps.readFile(join(this.storeDir, "config.yaml")));
-            this.ports = demoPorts(slug, { daemonPort, proxyPort: proxy.port });
-            this.proxyBase = `${proxy.scheme}://${proxyHost}:${proxy.port}`;
+            // A running daemon publishes its proxy's host port, which is the only
+            // answer when docker assigned it (proxyPort 0).
+            const published = Number(deps.readFile(join(this.storeDir, PROXY_PORT_FILE))?.trim());
+            const proxyPort = Number.isInteger(published) && published > 0 ? published : proxy.port;
+            this.ports = demoPorts(slug, { daemonPort, proxyPort });
+            this.proxyScheme = proxy.scheme;
         }
         else {
-            this.ports = demoPorts(slug);
+            // A recorded run's daemon is wherever it was when the run began.
+            this.ports = demoPorts(slug, opts.storeDir && opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {});
             this.storeDir = opts.storeDir ?? deps.storeDir(slug);
             // The private daemon is initialised without a cert source, so its proxy
             // speaks plain http (seen live: https:// gave 000, http:// served the page).
-            this.proxyBase = `http://${proxyHost}:${this.ports.proxyPort}`;
+            this.proxyScheme = "http";
         }
         this.proxyAuth = opts.proxy;
         this.daemonEnv = opts.daemonEnv ?? {};
@@ -443,6 +458,10 @@ export class DemoSession {
             readyMs: opts.timeouts?.readyMs ?? 180_000,
         };
     }
+    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
+    get proxyBase() {
+        return `${this.proxyScheme}://${this.proxyHost}:${this.ports.proxyPort}`;
+    }
     get devUrl() {
         return `http://localhost:${this.ports.backendPort}`;
     }
@@ -483,6 +502,13 @@ export class DemoSession {
             }
             return;
         }
+        // Ports nobody chose, where the ctl can: on a host docker daemon shared by
+        // every runner, the band is what two jobs collide on.
+        const assigned = this.ephemeralPorts && (await this.deps.supportsEphemeralPorts?.()) === true;
+        if (assigned) {
+            this.ports.daemonPort = 0;
+            this.ports.proxyPort = 0;
+        }
         await this.cliOk([
             "init",
             "--network-mode",
@@ -503,16 +529,22 @@ export class DemoSession {
             "--no-start-server",
             ...(this.publicHost ? ["--public-host", this.publicHost] : []),
         ]);
-        // The instance ports the daemon allocates come from this band too, so two
-        // products' fixtures on one box never share one (what every product
-        // harness passed by hand).
         const started = this.deps.startDaemon(this.storeDir, {
             port: this.ports.daemonPort,
             seedConfig: false,
-            env: { NORSK_CTL_INSTANCE_PORT_BASE: String(this.ports.instancePortBase), ...this.daemonEnv },
+            env: { ...this.daemonEnv },
         });
         this.daemon = started.daemon;
         await started.ready;
+        if (assigned) {
+            const running = await started.running;
+            if (running?.proxyPort === undefined) {
+                throw new Error(`the daemon came up without publishing ${PROXY_PORT_FILE} in ${this.storeDir} — did its proxy fail to start? (see the daemon log)`);
+            }
+            this.ports.daemonPort = running.daemonPort;
+            this.ports.proxyPort = running.proxyPort;
+            this.deps.log(`daemon :${this.ports.daemonPort}, proxy :${this.ports.proxyPort} (system-assigned)`);
+        }
         if (netReachMode() === "direct" && this.deps.ensureNetwork() === "failed") {
             throw new Error("could not join the runner to norsk-net for direct reach");
         }
@@ -755,6 +787,7 @@ export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd
     const s = new DemoSession(spec, slug, opts.cwd, deps, {
         mode: "dev",
         daemon: "private",
+        ephemeralPorts: true,
         ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
     });
     const exportDir = join(s.storeDir, "export");

package/harness-config.d.ts

@@ -14,5 +14,8 @@ export interface BaseHarnessPorts {
     daemonPort: number;
     backendPort: number;
     studioHostPort: number;
+    /** Still allocated because product harnesses read it; nothing in ctl ever
+     *  has (NORSK_CTL_INSTANCE_PORT_BASE was passed and ignored), and the
+     *  harness no longer passes it. */
     instancePortBase: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "type": "module",
   "exports": {
     ".": {

package/smoke.d.ts

@@ -1,5 +1,5 @@
 import { ensureRunnerOnNetwork, type StudioTarget } from "./container-net.js";
-import { type DaemonProcess, type StartDaemonOptions } from "./daemon.js";
+import { type DaemonProcess, type RunningDaemon, type StartDaemonOptions } from "./daemon.js";
 import { type BaseHarnessPorts } from "./harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "./source-pump.js";
 import { type ComponentsResponse, type StreamMappingEntry } from "./studio-state.js";
@@ -99,7 +99,9 @@ export interface SmokeSpec {
         observeMs?: number;
         clearedMs?: number;
     };
-    /** Override the banded ports (see smokePorts). */
+    /** Override the banded ports (see smokePorts). Against a ctl that assigns
+     *  its own daemon and proxy ports (supportsEphemeralPorts) those two come
+     *  from the daemon instead, whatever is given here. */
     ports?: Partial<SmokePorts>;
 }
 /** What the observation kinds read. Injected so the phase rule is tested
@@ -117,7 +119,12 @@ export interface SmokeDeps {
     startDaemon(storeDir: string, options: StartDaemonOptions): {
         daemon: DaemonProcess;
         ready: Promise<void>;
+        running?: Promise<RunningDaemon>;
     };
+    /** Does the resolved ctl run its daemon and proxy on system-assigned ports?
+     *  Optional so an existing custom-deps consumer keeps working; absent = no,
+     *  and the band decides both, as before. */
+    supportsEphemeralPorts?(): Promise<boolean>;
     cli(storeDir: string, argv: string[]): Promise<CliResult>;
     startSources(opts: {
         daemonPort: number;

package/smoke.js

@@ -21,7 +21,7 @@ import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dumpInstanceContainerLogs, preserveEngineLogs, preserveInstanceContainerLogs } from "./container-logs.js";
 import { ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "./container-net.js";
-import { cleanupDaemon, requireLicenseFile, runCli, startDaemon, } from "./daemon.js";
+import { cleanupDaemon, ctlSupportsEphemeralPorts, PROXY_PORT_FILE, requireLicenseFile, runCli, startDaemon, } from "./daemon.js";
 import { hashSlot } from "./harness-config.js";
 import { ctlSupportsNoPublish, ctlSupportsPublishDebugPorts, runnerContainerUser } from "./launch.js";
 import { pollUntil } from "./poll.js";
@@ -56,6 +56,7 @@ export const defaultSmokeDeps = {
     storeDir: (slug) => makeStoreDir(`norsk-smoke-${slug}-`),
     writeFile: (path, contents) => writeFileSync(path, contents),
     startDaemon,
+    supportsEphemeralPorts: ctlSupportsEphemeralPorts,
     cli: (storeDir, argv) => runCli(storeDir, ...argv),
     startSources: startSrtSources,
     stopSources: async (handles) => {
@@ -213,7 +214,10 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         return r;
     };
     const ctx = {
-        daemonPort: ports.daemonPort,
+        // A getter: with system-assigned ports the daemon's is known only once it is up.
+        get daemonPort() {
+            return ports.daemonPort;
+        },
         instanceId,
         storeDir,
         studio,
@@ -228,7 +232,14 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
     try {
         // The same zero point as the guides: `init` on a virgin store, not a seeded
         // config.yaml. No http redirect (port 80 needs root) and a banded proxy port
-        // (the default :9443 would meet a co-located integration run).
+        // (the default :9443 would meet a co-located integration run) — or, where
+        // the ctl can, ports nobody chose: the band is shared by every job on a
+        // host docker daemon, and only the system's own allocation is not.
+        const assigned = (await deps.supportsEphemeralPorts?.()) === true;
+        if (assigned) {
+            ports.daemonPort = 0;
+            ports.proxyPort = 0;
+        }
         await cliOk([
             "init",
             "--network-mode",
@@ -243,6 +254,15 @@ export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
         const started = deps.startDaemon(storeDir, { port: ports.daemonPort, seedConfig: false });
         daemon = started.daemon;
         await started.ready;
+        if (assigned) {
+            const running = await started.running;
+            if (running?.proxyPort === undefined) {
+                throw new Error(`the daemon came up without publishing ${PROXY_PORT_FILE} in ${storeDir} — did its proxy fail to start? (see the daemon log)`);
+            }
+            ports.daemonPort = running.daemonPort;
+            ports.proxyPort = running.proxyPort;
+            deps.log(`${slug}: daemon :${ports.daemonPort}, proxy :${ports.proxyPort} (system-assigned)`);
+        }
         if (mode === "direct") {
             // Say which verdict it was. "not-in-container" used to be the SILENT
             // outcome on every docker-outside-of-docker runner, because the cgroup-only