@norskvideo/ctl-test-harness 0.1.20 → 0.1.22

package/demo/run.js

@@ -1,13 +1,25 @@
-// The demo driver (fleet review 05-demo s4, s7 step 1): runs a DemoSpec on a
-// PRIVATE daemon — a makeStoreDir store on a banded port, exactly as the
-// product harnesses and the smoke tier do — registers the product from source
-// (`--mode dev`: the dev backend on a driver-chosen port, `product add
-// --dev-url`), launches the template, resolves every source's ingest port from
-// the instance, pumps, gates on `ready` while the sources run, runs `after`,
-// prints `open`, then either holds (`up`, released by Ctrl-C or `demo down`)
-// or tears down and exits (`check`, what CI runs). Teardown is a full
-// `shutdown` (instances, the proxy containers the private daemon created,
-// the daemon) because a demo runs on a developer's box, not a throwaway runner.
+// The demo driver (fleet review 05-demo s4, s7 steps 1-2): runs a DemoSpec on
+// a daemon, registers the product — `--mode dev`: the dev backend on a
+// driver-chosen port, `product add --dev-url`; `--mode image`: the built
+// product image, `product add --image`, the customer path — launches the
+// template, resolves every source's ingest port from the instance, pumps,
+// gates on `ready` while the sources run, runs `after`, prints `open`, then
+// either holds (`up`, released by Ctrl-C or `demo down`) or tears down and
+// exits (`check`, what CI runs).
+//
+// Whose daemon is a policy. `private` (the default, and always for `check`):
+// a makeStoreDir store on a banded port, exactly as the product harnesses and
+// the smoke tier do; teardown is a full `shutdown` (instances, the proxy
+// containers the private daemon created, the daemon) because a demo runs on a
+// developer's box, not a throwaway runner. `reuse`: the developer's listening
+// daemon and real store, where `product add` refuses an existing name and
+// stored templates are immutable — so the driver runs the mandatory sequence
+// (delete the instance, remove the product's templates and the product, drop
+// the control-plane container) before `product add`, verifies the re-rendered
+// template's image pins against manifest.seed.json (funke's iterate.sh pin
+// guard, generalised), pumps with the proxy secret, and at teardown removes
+// only the instance: the daemon, its store and the registration are the
+// developer's.
 //
 // Every side effect sits behind DemoDeps so the sequencing is unit-tested with
 // fakes; defaultDemoDeps wires the real harness. Argv, not Command: this
@@ -16,19 +28,27 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom } from "../container-net.js";
+import { parseManifestSeed, repoOf } from "@norskvideo/ctl-sdk/manifest-seed";
+import { DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "../container-net.js";
 import { cleanupDaemon, requireLicenseFile, runCli, startDaemon, } from "../daemon.js";
 import { hashSlot } from "../harness-config.js";
 import { ctlSupportsNoPublish, runnerContainerUser } from "../launch.js";
 import { pollUntil } from "../poll.js";
 import { startSrtSources } from "../source-pump.js";
 import { makeStoreDir } from "../temp-dir.js";
+import { DemoGateFailure } from "./gates.js";
 const DEMO_PORT_BASE = 35000;
 const DEMO_BAND_WIDTH = 20;
 const DEMO_BANDS = 50;
+const DEFAULT_DAEMON_PORT = 8333;
+const DEFAULT_PROXY_PORT = 443;
 const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
 const NUKE_IMAGE = "alpine:3";
 const DEFAULT_DEV_READY_PATH = "/manifest.json";
+const SEED_FILE = "manifest.seed.json";
+const TEMPLATES_DIR = "product-templates";
+const PROXY_SECRET_FILE = "proxy-secret";
+const EXTRA_LABEL = "norsk-ctl.demo";
 /** Per-slug port band above the smoke tier's (33000-34000), so a demo and a
  *  smoke run of the same product never meet. */
 export function demoPorts(slug, overrides = {}) {
@@ -114,6 +134,29 @@ export function resolveIngestPort(ingest, rows, t = NO_PARAMS) {
     }
     return row.port;
 }
+/** Image pins are read, never typed (05-demo s4): for every repo the seed's
+ *  `latest` names (studio, media), the stored compose must pin the same ref.
+ *  A repo the compose does not name is not a mismatch — the guard is about a
+ *  stale snapshot, not template completeness. */
+export function checkTemplatePins(composeText, seed) {
+    const stored = [...composeText.matchAll(/^\s*image:\s*["']?([^\s"'#]+)/gm)].map((m) => m[1]);
+    const out = [];
+    for (const expected of [seed.latest.studio, seed.latest.media]) {
+        const repo = repoOf(expected);
+        const actual = stored.find((ref) => repoOf(ref) === repo);
+        if (actual !== undefined && actual !== expected)
+            out.push({ repo, stored: actual, seed: expected });
+    }
+    return out;
+}
+/** The two config.yaml scalars the proxy URL needs; a regex, not a YAML
+ *  parser, because that is all the driver reads from a store it does not own. */
+export function parseProxyConfig(configText) {
+    const text = configText ?? "";
+    const port = Number(/^proxyPort:\s*(\d+)/m.exec(text)?.[1]);
+    const tls = /^certSource:\s*\S+/m.test(text);
+    return { scheme: tls ? "https" : "http", port: Number.isInteger(port) && port > 0 ? port : DEFAULT_PROXY_PORT };
+}
 function parseJson(r, what) {
     try {
         return JSON.parse(r.stdout);
@@ -153,11 +196,11 @@ export function findBrokenSymlinks(dir) {
  *  consumer's repo, where `down` from another shell can find it. */
 export function fileStateStore(cwd) {
     const dir = join(cwd, "test-temp", "demo");
-    const path = (product) => join(dir, `${product}.json`);
+    const path = (product, kind) => join(dir, `${product}${kind === "dev-loop" ? ".dev-loop" : ""}.json`);
     return {
-        read: (product) => {
+        read: (product, kind) => {
             try {
-                return JSON.parse(readFileSync(path(product), "utf8"));
+                return JSON.parse(readFileSync(path(product, kind), "utf8"));
             }
             catch {
                 return null;
@@ -165,9 +208,9 @@ export function fileStateStore(cwd) {
         },
         write: (state) => {
             mkdirSync(dir, { recursive: true });
-            writeFileSync(path(state.product), `${JSON.stringify(state, null, 2)}\n`);
+            writeFileSync(path(state.product, state.kind), `${JSON.stringify(state, null, 2)}\n`);
         },
-        remove: (product) => rmSync(path(product), { force: true }),
+        remove: (product, kind) => rmSync(path(product, kind), { force: true }),
     };
 }
 /** SIGTERM a process group (a pid startProcess spawned detached leads its
@@ -183,11 +226,26 @@ export function killGroup(pid) {
     }
     catch { }
 }
+/** Both naming schemes: compose's `<id>-<service>-1` on the released ctl,
+ *  `norsk-inst-<id>-<service>` before it. Teardown waits on whichever exists. */
+function instanceContainerNames(id) {
+    return [`${id}-studio-1`, `${id}-media-1`, `norsk-inst-${id}-studio`, `norsk-inst-${id}-media`];
+}
 export function defaultDemoDeps(cwd) {
     return {
         licenseFile: () => requireLicenseFile({ missing: "throw" }),
         storeDir: (slug) => makeStoreDir(`norsk-demo-${slug}-`),
+        realStoreDir: () => process.env.NORSK_CTL_STORE_DIR ?? join(homedir(), ".norsk-ctl"),
         writeFile: (path, contents) => writeFileSync(path, contents),
+        removeFile: (path) => rmSync(path, { force: true }),
+        readFile: (path) => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
         fileExists: (path) => existsSync(path),
         startDaemon,
         daemonAnswers: async (port) => {
@@ -223,6 +281,10 @@ export function defaultDemoDeps(cwd) {
                 exited,
             };
         },
+        docker: (argv) => {
+            const r = spawnSync("docker", argv, { encoding: "utf8" });
+            return { stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? ""), exitCode: r.status ?? 1 };
+        },
         fetch: (url, init) => fetch(url, { signal: AbortSignal.timeout(5000), ...init }),
         startSources: startSrtSources,
         stopSources: async (handles) => {
@@ -265,35 +327,70 @@ export function defaultDemoDeps(cwd) {
         log: (line) => console.log(`[demo] ${line}`),
     };
 }
-/** The pieces of a run that both `runDemo` and `runExportCheck` share: the
- *  private daemon on its band, the dev backend on the driver's port, the
- *  registration, and the template (built or chosen). */
-class DemoSession {
+/** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
+ *  share: the daemon (private on its band, or the developer's), the dev
+ *  backend on the driver's port, the registration, and the template (built
+ *  or chosen). */
+export class DemoSession {
     spec;
     slug;
     cwd;
     deps;
+    mode;
+    policy;
     ports;
     storeDir;
+    /** The host every printed URL names. */
+    host;
+    publicHost;
+    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
+    proxyBase;
     daemon = null;
     dev = null;
+    extras = [];
     timeouts;
-    constructor(spec, slug, cwd, deps, timeouts) {
+    constructor(spec, slug, cwd, deps, opts) {
         this.spec = spec;
         this.slug = slug;
         this.cwd = cwd;
         this.deps = deps;
-        this.ports = demoPorts(slug);
-        this.storeDir = deps.storeDir(slug);
+        this.mode = opts.mode;
+        this.policy = opts.daemon;
+        this.publicHost = opts.publicHost;
+        const host = opts.publicHost ?? process.env.NORSK_TEST_HOST ?? "localhost";
+        this.host = host;
+        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}://${host}:${proxy.port}`;
+        }
+        else {
+            this.ports = demoPorts(slug);
+            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://${host}:${this.ports.proxyPort}`;
+        }
         this.timeouts = {
-            devReadyMs: timeouts?.devReadyMs ?? 120_000,
-            healthyMs: timeouts?.healthyMs ?? 180_000,
-            readyMs: timeouts?.readyMs ?? 180_000,
+            devReadyMs: opts.timeouts?.devReadyMs ?? 120_000,
+            healthyMs: opts.timeouts?.healthyMs ?? 180_000,
+            readyMs: opts.timeouts?.readyMs ?? 180_000,
         };
     }
     get devUrl() {
         return `http://localhost:${this.ports.backendPort}`;
     }
+    templateDir(name) {
+        return join(this.storeDir, TEMPLATES_DIR, name);
+    }
+    /** What the real daemon's proxy demands on `/api/*`; absent on a private daemon. */
+    proxySecret() {
+        if (this.policy !== "reuse")
+            return undefined;
+        return this.deps.readFile(join(this.storeDir, PROXY_SECRET_FILE))?.trim() || undefined;
+    }
     cli = async (argv, opts = {}) => this.deps.cli(this.storeDir, [
         "--port",
         String(this.ports.daemonPort),
@@ -307,7 +404,15 @@ class DemoSession {
         }
         return r;
     };
-    async startDaemon() {
+    /** Private: init a virgin store and start a daemon on the band. Reuse: the
+     *  developer's daemon must already answer. */
+    async attachDaemon() {
+        if (this.policy === "reuse") {
+            if (!(await this.deps.daemonAnswers(this.ports.daemonPort))) {
+                throw new Error(`no daemon answers on :${this.ports.daemonPort} — start one with \`norsk-ctl serve\`, or drop --daemon reuse for a private one`);
+            }
+            return;
+        }
         await this.cliOk([
             "init",
             "--network-mode",
@@ -318,6 +423,7 @@ class DemoSession {
             String(this.ports.proxyPort),
             "--no-http-redirect",
             "--no-start-server",
+            ...(this.publicHost ? ["--public-host", this.publicHost] : []),
         ]);
         const started = this.deps.startDaemon(this.storeDir, { port: this.ports.daemonPort, seedConfig: false });
         this.daemon = started.daemon;
@@ -337,8 +443,35 @@ class DemoSession {
             return r.ok;
         }, { timeoutMs: this.timeouts.devReadyMs, intervalMs: 1000, label: `dev backend did not answer at ${url}` });
     }
+    /** The reuse policy's mandatory sequence: `product add` refuses an existing
+     *  name and stored templates are immutable, so the instance, every template
+     *  the product publishes (plus the spec's built one), the product and its
+     *  control-plane container all go first. Each step tolerates absence. */
+    async resetRegistration(instanceId) {
+        await this.cli(["instance", "delete", instanceId, "--purge"]);
+        const listed = await this.cli(["template", "list"], { output: "json" });
+        const names = listed.exitCode === 0
+            ? (parseJson(listed, "template list").productTemplates ?? [])
+                .filter((x) => x.source?.productName === this.spec.product)
+                .map((x) => x.name)
+            : [];
+        const t = this.spec.template;
+        if (t && "build" in t)
+            names.push(t.build.name ?? `${this.spec.product}-demo`);
+        for (const name of new Set(names))
+            await this.cli(["template", "remove", name]);
+        await this.cli(["product", "remove", this.spec.product]);
+        this.deps.docker(["rm", "-f", `norsk-product-${this.spec.product}`]);
+        this.deps.log(`reuse: removed instance ${instanceId}, templates [${[...new Set(names)].join(", ")}], product ${this.spec.product}`);
+    }
     async register(opts) {
-        const argv = ["product", "add", "--dev-url", this.devUrl];
+        const argv = ["product", "add"];
+        if (this.mode === "image") {
+            argv.push("--image", this.spec.image);
+        }
+        else {
+            argv.push("--dev-url", this.devUrl);
+        }
         if (opts.licence)
             argv.push("--license-file", this.deps.licenseFile());
         const added = parseJson(await this.cliOk(argv, { output: "json" }), "product add");
@@ -348,8 +481,7 @@ class DemoSession {
     }
     /** The template to launch: built from the spec's input, or a name the
      *  product publishes (its first default when the spec names none). */
-    async resolveTemplate() {
-        const t = this.spec.template;
+    async resolveTemplate(t = this.spec.template) {
         if (t && "build" in t) {
             const name = t.build.name ?? `${this.spec.product}-demo`;
             let inputPath;
@@ -379,6 +511,42 @@ class DemoSession {
             throw new Error(`${this.spec.product} publishes no default template; name one with template: { build }`);
         return first;
     }
+    /** Funke's iterate.sh pin guard for every product: the stored compose must
+     *  pin what manifest.seed.json declares. Image mode, and any reuse — a
+     *  private dev-mode daemon renders the template fresh from source, so there
+     *  is nothing stale to catch there. */
+    async pinGuard(templateName) {
+        if (this.mode !== "image" && this.policy !== "reuse")
+            return;
+        const seedPath = join(this.cwd, SEED_FILE);
+        const seedText = this.deps.readFile(seedPath);
+        if (seedText === null) {
+            this.deps.log(`no ${SEED_FILE} in ${this.cwd} — pin guard skipped`);
+            return;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(seedText);
+        }
+        catch (e) {
+            throw new Error(`${seedPath} is not JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const seed = parseManifestSeed(raw);
+        if (seed.status !== "ok")
+            throw new Error(`${seedPath}: ${seed.error}`);
+        const composePath = join(this.templateDir(templateName), "compose.yml");
+        const compose = this.deps.readFile(composePath);
+        if (compose === null)
+            throw new Error(`stored template '${templateName}' has no compose at ${composePath}`);
+        const mismatches = checkTemplatePins(compose, seed.value);
+        if (mismatches.length) {
+            const lines = mismatches.map((m) => `  ${m.repo}: stored ${m.stored}, seed ${m.seed}`).join("\n");
+            throw new Error(`stored template '${templateName}' pins ${mismatches.map((m) => m.stored).join(", ")} but ${SEED_FILE} says ${mismatches
+                .map((m) => m.seed)
+                .join(", ")} — the stored template did not refresh:\n${lines}\n  (product reload re-fetches only the manifest; delete the instance, remove the template and the product, add again)`);
+        }
+        this.deps.log(`template '${templateName}' pins match ${SEED_FILE}`);
+    }
     /** name -> stringified default, from `template show`. */
     async declaredParams(templateName) {
         const shown = await this.cli(["template", "show", templateName], { output: "json" });
@@ -387,6 +555,34 @@ class DemoSession {
         const parameters = parseJson(shown, "template show").parameters ?? [];
         return new Map(parameters.map((p) => [p.name, p.default]));
     }
+    startExtras(instanceId) {
+        for (const e of this.spec.extras ?? []) {
+            this.deps.docker(["rm", "-f", e.name]);
+            const r = this.deps.docker([
+                "run",
+                "-d",
+                "--name",
+                e.name,
+                "--network",
+                DOCKER_NETWORK_NAME,
+                "--label",
+                `${EXTRA_LABEL}=${instanceId}`,
+                ...(e.args ?? []),
+                e.image,
+                ...(e.command ?? []),
+            ]);
+            this.extras.push(e.name);
+            if (r.exitCode !== 0) {
+                throw new Error(`extra '${e.name}' failed to start (exit ${r.exitCode}): ${(r.stderr || r.stdout).trim()}`);
+            }
+            this.deps.log(`extra ${e.name}: ${e.image}`);
+        }
+    }
+    stopExtras() {
+        for (const name of this.extras)
+            this.deps.docker(["rm", "-f", name]);
+        this.extras = [];
+    }
     async waitRunning(instanceId) {
         await pollUntil(async () => {
             const r = await this.cli(["instance", "list"], { output: "json" });
@@ -396,6 +592,12 @@ class DemoSession {
             return inst?.status === "running" || inst?.status === "healthy";
         }, { timeoutMs: this.timeouts.healthyMs, intervalMs: 1000, label: `instance ${instanceId} never reported running` });
     }
+    async instanceListed(instanceId) {
+        const r = await this.cli(["instance", "list"], { output: "json" });
+        if (r.exitCode !== 0)
+            return false;
+        return (parseJson(r, "instance list").instances?.some((i) => i.id === instanceId) ?? false);
+    }
     async ingestPorts(instanceId) {
         const r = await this.cliOk(["instance", "describe", instanceId], { output: "json" });
         return parseJson(r, "instance describe").ingestPorts ?? [];
@@ -403,10 +605,22 @@ class DemoSession {
     gateTimeout(ms) {
         return ms ?? this.timeouts.readyMs;
     }
-    /** Tear down in reverse: sources, instance, daemon (with its proxy), dev backend, store. */
+    /** Tear down in reverse: sources, instance, then — private only — the
+     *  daemon (with its proxy), the dev backend, the store. Reuse leaves the
+     *  developer's daemon, store and registration as they are. */
     async teardown(opts) {
         if (opts.handles.length)
             await this.deps.stopSources(opts.handles).catch(() => { });
+        if (this.policy === "reuse") {
+            for (const id of opts.instances) {
+                const r = await this.cli(["instance", "delete", id, "--purge"]);
+                if (r.exitCode !== 0)
+                    this.deps.log(`instance delete ${id}: ${(r.stderr || r.stdout).trim()}`);
+            }
+            this.stopExtras();
+            this.dev?.kill();
+            return;
+        }
         try {
             await this.deps.cleanup({
                 deleteInstance: (id) => this.cli(["instance", "delete", id, "--purge"]),
@@ -414,28 +628,27 @@ class DemoSession {
                 instances: opts.instances,
                 daemon: this.daemon,
                 storeDir: this.storeDir,
-                containers: opts.instances.flatMap((id) => [`norsk-inst-${id}-studio`, `norsk-inst-${id}-media`]),
+                containers: opts.instances.flatMap(instanceContainerNames),
             });
         }
         catch (e) {
             this.deps.log(`cleanup could not remove the store itself (${e instanceof Error ? e.message : String(e)}); nuking as root`);
         }
+        this.stopExtras();
         this.dev?.kill();
         this.deps.nukeStoreAsRoot(this.storeDir);
     }
 }
 function urlResolver(o) {
-    const host = process.env.NORSK_TEST_HOST ?? "localhost";
+    const host = o.host;
     const mode = netReachMode();
     return (ref) => {
         if ("url" in ref)
             return ref.url;
         if ("control" in ref)
-            return `http://localhost:${o.ports.backendPort}${ref.control}`;
-        // The private daemon is initialised without a cert source, so its proxy
-        // speaks plain http (reuse mode, 05-demo s7 step 2, will read the real one).
+            return `http://${host}:${o.ports.backendPort}${ref.control}`;
         if ("proxy" in ref)
-            return `http://${host}:${o.ports.proxyPort}${ref.proxy.replaceAll("{id}", o.instanceId)}`;
+            return `${o.proxyBase}${ref.proxy.replaceAll("{id}", o.instanceId)}`;
         return `${studioBaseFrom({ instanceId: o.instanceId, studioHostPort: o.studioHostPort }, host, mode)}${ref.studio}`;
     };
 }
@@ -454,6 +667,27 @@ function gateName(gate, ctx) {
         return gate.label ?? "custom gate";
     return `${ctx.url(gate.http)} -> ${gate.status ?? 200}${gate.bodyIncludes ? ` containing '${gate.bodyIncludes}'` : ""}`;
 }
+/** Poll a gate until it holds — or stop at once when it declares its failure
+ *  final (DemoGateFailure), which pollUntil would otherwise keep retrying. */
+async function awaitGate(gate, ctx, timeoutMs) {
+    const name = gateName(gate, ctx);
+    let fatal;
+    await pollUntil(async () => {
+        try {
+            return await gateHolds(gate, ctx);
+        }
+        catch (e) {
+            if (e instanceof DemoGateFailure) {
+                fatal = e;
+                return true;
+            }
+            throw e;
+        }
+    }, { timeoutMs, intervalMs: 1000, label: `ready gate never held: ${name}` });
+    if (fatal)
+        throw new Error(`ready gate failed: ${name}: ${fatal.message}`);
+    return name;
+}
 async function resolveOpen(spec, ctx) {
     const out = [];
     for (const o of spec.open ?? []) {
@@ -473,35 +707,75 @@ async function resolveOpen(spec, ctx) {
     }
     return out;
 }
+/** `up` refuses to run beside a live earlier run of the same demo. Private:
+ *  its daemon still answers. Reuse: the daemon always answers, so the record
+ *  is live only while its instance still exists. A dead record is forgotten. */
+async function refuseIfUp(spec, s, deps) {
+    const prev = deps.state.read(spec.product);
+    if (!prev)
+        return;
+    const answers = await deps.daemonAnswers(prev.daemonPort);
+    const live = prev.daemon === "reuse"
+        ? answers && prev.instanceId !== undefined && (await s.instanceListed(prev.instanceId))
+        : answers;
+    if (live) {
+        throw new Error(`demo '${spec.product}' is already up (daemon :${prev.daemonPort}, store ${prev.storeDir}) — run \`demo down\` first`);
+    }
+    deps.log(`forgetting a stale record of a run on :${prev.daemonPort} (nothing of it is left)`);
+    deps.state.remove(spec.product);
+}
 export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
     const slug = opts.slug ?? demoSlug(spec.product);
     const instanceId = `demo-${slug}`;
+    const policy = opts.daemon ?? "private";
+    if (opts.mode === "image" && !spec.image) {
+        throw new Error(`--mode image needs the spec's \`image\` (the built product image) — ${spec.product} declares none`);
+    }
+    const s = new DemoSession(spec, slug, opts.cwd, deps, {
+        mode: opts.mode,
+        daemon: policy,
+        ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
+        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+    });
     if (opts.action === "up") {
-        const prev = deps.state.read(spec.product);
-        if (prev) {
-            if (await deps.daemonAnswers(prev.daemonPort)) {
-                throw new Error(`demo '${spec.product}' is already up (daemon :${prev.daemonPort}, store ${prev.storeDir}) — run \`demo down\` first`);
-            }
-            deps.log(`forgetting a stale record of a run on :${prev.daemonPort} (nothing answers there)`);
-            deps.state.remove(spec.product);
-        }
+        await refuseIfUp(spec, s, deps);
         for (const p of spec.prerequisites ?? []) {
             const path = expandHome(p.path);
             if (!deps.fileExists(path))
                 throw new Error(`prerequisite missing: ${path}\n  make it with: ${p.hint}`);
         }
     }
-    const s = new DemoSession(spec, slug, opts.cwd, deps, opts.timeouts);
     let launched = false;
     let handles = [];
     let recorded = false;
     let result;
     let journeyError;
     try {
-        await s.startDaemon();
-        await s.startDev();
+        await s.attachDaemon();
+        if (opts.mode === "dev")
+            await s.startDev();
+        if (policy === "reuse")
+            await s.resetRegistration(instanceId);
         await s.register({ licence: true });
         const templateName = await s.resolveTemplate();
+        await s.pinGuard(templateName);
+        const launchCtx = {
+            action: opts.action,
+            mode: opts.mode,
+            daemon: policy,
+            product: spec.product,
+            instanceId,
+            daemonPort: s.ports.daemonPort,
+            storeDir: s.storeDir,
+            templateName,
+            templateDir: s.templateDir(templateName),
+            cli: s.cli,
+            log: deps.log,
+        };
+        s.startExtras(instanceId);
+        if (spec.beforeLaunch)
+            await spec.beforeLaunch(launchCtx);
         const declared = await s.declaredParams(templateName);
         const specParams = spec.launch?.params ?? {};
         const studioHostPort = specParams[STUDIO_HOST_PORT_PARAM] !== undefined
@@ -541,29 +815,24 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
             ...(src.streamId !== undefined ? { streamId: src.streamId } : {}),
         }));
         const ctx = {
-            action: opts.action,
-            product: spec.product,
-            instanceId,
-            daemonPort: s.ports.daemonPort,
-            storeDir: s.storeDir,
-            url: urlResolver({ instanceId, ports: s.ports, studioHostPort }),
-            cli: s.cli,
+            ...launchCtx,
+            url: urlResolver({ instanceId, ports: s.ports, studioHostPort, proxyBase: s.proxyBase, host: s.host }),
             fetch: deps.fetch,
-            log: deps.log,
         };
         // Sources first: a gate such as "the switcher is composing" or "the probe
         // is analysing" can only hold with something on the wire.
         if (targets.length) {
-            handles = await deps.startSources({ daemonPort: s.ports.daemonPort, instanceId, targets });
+            const secret = s.proxySecret();
+            handles = await deps.startSources({
+                daemonPort: s.ports.daemonPort,
+                instanceId,
+                targets,
+                ...(secret !== undefined ? { proxySecret: secret } : {}),
+            });
             deps.log(`sources: ${targets.map((t) => `${t.name} -> :${t.port}`).join(", ")}`);
         }
         for (const gate of spec.ready ?? []) {
-            const name = gateName(gate, ctx);
-            await pollUntil(() => gateHolds(gate, ctx), {
-                timeoutMs: s.gateTimeout(gate.timeoutMs),
-                intervalMs: 1000,
-                label: `ready gate never held: ${name}`,
-            });
+            const name = await awaitGate(gate, ctx, s.gateTimeout(gate.timeoutMs));
             deps.log(`ready: ${name}`);
         }
         if (spec.after)
@@ -580,6 +849,8 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
                 storeDir: s.storeDir,
                 daemonPort: s.ports.daemonPort,
                 instanceId,
+                daemon: policy,
+                ...(s.extras.length ? { extras: [...s.extras] } : {}),
                 ...(s.dev?.pid !== undefined ? { devPid: s.dev.pid } : {}),
             });
             recorded = true;
@@ -595,8 +866,9 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         deps.state.remove(spec.product);
     if (journeyError !== undefined)
         throw journeyError;
-    if (deps.storeExists(s.storeDir))
+    if (policy === "private" && deps.storeExists(s.storeDir)) {
         throw new Error(`store ${s.storeDir} still present after the root-container nuke`);
+    }
     return result;
 }
 /** `demo check --mode standalone --export-only` (05-demo s4): build the
@@ -606,27 +878,19 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
  *  path that rotted (05-demo s1) and it is cheap enough to gate every push. */
 export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
     const slug = opts.slug ?? demoSlug(spec.product);
-    const s = new DemoSession(spec, slug, opts.cwd, deps, opts.timeouts);
+    const s = new DemoSession(spec, slug, opts.cwd, deps, {
+        mode: "dev",
+        daemon: "private",
+        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+    });
     const exportDir = join(s.storeDir, "export");
     let journeyError;
     try {
-        await s.startDaemon();
+        await s.attachDaemon();
         await s.startDev();
         await s.register({ licence: false });
         const templateName = await s.resolveTemplate();
-        const argv = ["template", "export-workdir", templateName, "--to", exportDir];
-        for (const [k, v] of Object.entries(spec.standalone?.params ?? {}))
-            argv.push("--param", `${k}=${v}`);
-        for (const [pkg, path] of Object.entries(spec.standalone?.links ?? {})) {
-            argv.push("--link-component", `${pkg}=${resolve(opts.cwd, path)}`);
-        }
-        if (spec.standalone?.dashboards)
-            argv.push("--link-dashboards", resolve(opts.cwd, spec.standalone.dashboards));
-        await s.cliOk(argv);
-        const broken = deps.brokenSymlinks(exportDir);
-        if (broken.length) {
-            throw new Error(`exported workdir has ${broken.length} broken symlink(s):\n  ${broken.join("\n  ")}`);
-        }
+        await exportStandaloneWorkdir(s, templateName, exportDir);
         deps.log(`export ok: ${templateName} -> ${exportDir}, every symlink resolves`);
     }
     catch (e) {
@@ -637,6 +901,24 @@ export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd
         throw journeyError;
     return { exportDir };
 }
+/** `template export-workdir` with the spec's live-source links and params,
+ *  then the check that rotted (05-demo s1): every symlink resolves. */
+export async function exportStandaloneWorkdir(s, templateName, to) {
+    const { spec, cwd, deps } = s;
+    const argv = ["template", "export-workdir", templateName, "--to", to];
+    for (const [k, v] of Object.entries(spec.standalone?.params ?? {}))
+        argv.push("--param", `${k}=${v}`);
+    for (const [pkg, path] of Object.entries(spec.standalone?.links ?? {})) {
+        argv.push("--link-component", `${pkg}=${resolve(cwd, path)}`);
+    }
+    if (spec.standalone?.dashboards)
+        argv.push("--link-dashboards", resolve(cwd, spec.standalone.dashboards));
+    await s.cliOk(argv);
+    const broken = deps.brokenSymlinks(to);
+    if (broken.length) {
+        throw new Error(`exported workdir has ${broken.length} broken symlink(s):\n  ${broken.join("\n  ")}`);
+    }
+}
 /** `demo down`: tear down the run `up` recorded, from any shell. */
 export async function demoDown(product, deps = defaultDemoDeps(process.cwd())) {
     const state = deps.state.read(product);
@@ -645,24 +927,34 @@ export async function demoDown(product, deps = defaultDemoDeps(process.cwd())) {
         return;
     }
     const cli = (argv) => deps.cli(state.storeDir, ["--port", String(state.daemonPort), ...argv]);
-    try {
-        await deps.cleanup({
-            deleteInstance: (id) => cli(["instance", "delete", id, "--purge"]),
-            stopDaemon: () => cli(["shutdown"]),
-            instances: state.instanceId ? [state.instanceId] : [],
-            daemon: null,
-            storeDir: state.storeDir,
-            containers: state.instanceId
-                ? [`norsk-inst-${state.instanceId}-studio`, `norsk-inst-${state.instanceId}-media`]
-                : [],
-        });
+    if (state.daemon === "reuse") {
+        if (state.instanceId) {
+            const r = await cli(["instance", "delete", state.instanceId, "--purge"]);
+            if (r.exitCode !== 0)
+                deps.log(`instance delete ${state.instanceId}: ${(r.stderr || r.stdout).trim()}`);
+        }
     }
-    catch (e) {
-        deps.log(`cleanup: ${e instanceof Error ? e.message : String(e)}; nuking the store as root`);
+    else {
+        try {
+            await deps.cleanup({
+                deleteInstance: (id) => cli(["instance", "delete", id, "--purge"]),
+                stopDaemon: () => cli(["shutdown"]),
+                instances: state.instanceId ? [state.instanceId] : [],
+                daemon: null,
+                storeDir: state.storeDir,
+                containers: state.instanceId ? instanceContainerNames(state.instanceId) : [],
+            });
+        }
+        catch (e) {
+            deps.log(`cleanup: ${e instanceof Error ? e.message : String(e)}; nuking the store as root`);
+        }
     }
+    for (const name of state.extras ?? [])
+        deps.docker(["rm", "-f", name]);
     if (state.devPid !== undefined)
         deps.killPid?.(state.devPid);
-    deps.nukeStoreAsRoot(state.storeDir);
+    if (state.daemon !== "reuse")
+        deps.nukeStoreAsRoot(state.storeDir);
     deps.state.remove(product);
-    deps.log(`${product} demo torn down`);
+    deps.log(`${product} demo torn down${state.daemon === "reuse" ? " (your daemon and its registration are untouched)" : ""}`);
 }