@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/commands/dev.mjs

@@ -147,11 +147,11 @@ export async function run(argv, ctx) {
 }
 
 /**
- * Standalone-checkout entrypoint: native runtime by default (F3 — no Docker
+ * Standalone-checkout entrypoint: native runtime by default (no Docker
  * prerequisite), Docker on explicit request, and Docker as an automatic
  * fallback when the native artifact can't be fetched (e.g. the MCP's
  * dev_renderer_artifact isn't configured on this deployment yet) — so `tot dev`
- * keeps working through the WS3 rollout instead of hard-failing.
+ * keeps working instead of hard-failing.
  */
 async function runStandalone(workspace, args, ctx) {
   if (args.docker) return runContainer(workspace, args, ctx);
@@ -266,7 +266,7 @@ function runMonorepo(ctx, argv) {
  * Thrown when the native runtime can't be used for a reason that's about the
  * artifact/service, not the developer's checkout — runStandalone catches this
  * specifically and falls back to Docker instead of hard-failing. Exported so
- * `tot start` (C1/F3 integration) can catch it too and fall back the same way.
+ * `tot start` can catch it too and fall back the same way.
  */
 export class NativeArtifactUnavailableError extends Error {}
 
@@ -326,7 +326,7 @@ export function bootNative(runnerDir, workspace, port, url, args) {
   const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "piped", env: bridgeEnv });
   streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL) });
 
-  // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
+  // Heartbeat the hosted cockpit with the CLI version + this live localhost
   // URL while the runner runs — CLI-side, using the SAME bridge credential the
   // runner's file-save path uses (no-op in --sample, which threads no credential).
   // `cwd` (the checkout root) lets the cockpit show the FULL path to edit.
@@ -409,7 +409,7 @@ export function printSampleBanner({ url }, mode = "sample") {
  * Exported so sample/tests can drive the selection directly.
  * @param {ReturnType<typeof parseArgs>} args
  * @param {{ client?: any }} [opts] an already-authenticated MCP client (entitled path)
- * @returns {Promise<{kind:"public"|"entitled",version:string,url:string,strip:number,cacheKey:string}>}
+ * @returns {Promise<{kind:string,version:string,url:string,strip:number,cacheKey:string,integrity:string|null}>}
  */
 export async function resolveRendererSource(args, { client } = {}) {
   if (args.sample) return resolvePublicRendererSource(args);
@@ -427,15 +427,18 @@ export async function resolveRendererSource(args, { client } = {}) {
  * is keyed by version, upgrading the CLI busts the stale-runner cache automatically
  * (the 2026-07-14 "cached runner (prior tot dev)" staleness).
  *
- * EXACT-FIRST (the CLI requests its OWN version): with lockstep publishing the runner
- * is published at the SAME version as the CLI, so the exact match (step 2) is the normal
- * path. An explicit pin (`--renderer-version` / TOT_RUNNER_VERSION) always wins. When no
- * exact match exists we degrade ONLY DOWNWARD — a runner at or below the CLI's major.minor
- * (never ahead) — and NEVER to a floating dist-tag like `latest` (a channel can point at a
- * version this CLI doesn't expect; that floating-tag drift is the exact bug this avoids).
- * The caller emits a LOUD skew warning whenever the resolved version isn't the exact CLI
- * version, so a mismatch is visible, not silent. If nothing exact/minor/≤-ceiling is
- * published, we THROW — a release gap to fix by publishing the aligned runner, not paper over.
+ * STABLE PATCHES FLOAT within the CLI's own major.minor: a published patch is a
+ * compatible maintenance release, and is precisely how a bad runner artifact is
+ * replaced (npm tarballs are immutable). Therefore stable CLI 1.4.0 automatically
+ * takes runner 1.4.1 instead of remaining pinned forever to a broken 1.4.0 tarball.
+ * Prerelease CLIs still prefer their exact prerelease runner because stable-only
+ * patch selection deliberately excludes prereleases. An explicit pin
+ * (`--renderer-version` / TOT_RUNNER_VERSION) always wins.
+ *
+ * We still never cross the CLI's major.minor ceiling automatically and never use a
+ * floating dist-tag like `latest`: a newer minor can require a newer CLI contract.
+ * If no stable same-minor or lower compatible release exists, we THROW rather than
+ * silently running a too-new runner.
  *
  * PIN-DIRECTION DECISION (ADR 0011 — don't relitigate inline): the runner version
  * should be DECLARED BY THE PRODUCT, not derived from the CLI's identity. The
@@ -443,11 +446,9 @@ export async function resolveRendererSource(args, { client } = {}) {
  *   1. explicit flag/env pin        — developer intent, always wins
  *   2. declaredVersion              — the STORE's own `.tot/config.json#runnerVersion`
  *                                     (rust-toolchain.toml-style; the target state)
- *   3. exact CLI-version match      — TRANSITIONAL lockstep rung. Delete it (and the
- *                                     lockstep publish regime) once tenant_checkout
- *                                     stamps runnerVersion into every checkout —
- *                                     see ADR 0011 for the exit criteria.
- *   4. CLI-minor / ≤-ceiling        — degraded-but-safe fallbacks (never a floating tag)
+ *   3. exact prerelease match       — keeps an RC paired with its runner RC
+ *   4. newest stable CLI-minor patch — maintenance releases float within x.y
+ *   5. ≤-ceiling                    — degraded-but-safe fallback (never a floating tag)
  *
  * Pure (no I/O) for testability.
  * @param {any} meta npm packument (`dist-tags` + `versions`)
@@ -486,17 +487,19 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin, declaredVersi
     return { version: declaredVersion, reason: "declared by the store checkout (runnerVersion)" };
   }
 
-  // 2) EXACT CLI-version match — the primary path for a lockstep release: the runner
-  // is published at the SAME version as the CLI (incl. prereleases like 1.3.0-rc.0,
-  // which the stable-only minor match below deliberately skips). This is what makes
-  // `tot@1.3.0-rc.0` pull `runner@1.3.0-rc.0` instead of falling back to stale latest.
-  // (Same version ⇒ same major.minor ⇒ always within the ceiling.)
-  if (versions.includes(cliVersion)) {
+  // 2) EXACT PRERELEASE match. Stable releases intentionally continue to the
+  // same-minor maintenance selection below, where a corrected immutable artifact
+  // (runner 1.4.1 for CLI 1.4.0) can supersede a broken exact-version tarball.
+  // RCs cannot safely float across prerelease builds, so they remain exact-paired.
+  if (cliVersion.includes("-") && versions.includes(cliVersion)) {
     return { version: cliVersion, reason: "exact CLI-version match" };
   }
 
-  // 3) CLI-minor match: highest published <major>.<minor>.* (numeric patch order).
-  // Constrained to the CLI's exact minor, so this is within the ceiling by construction.
+  // 3) CLI-minor maintenance match: highest published stable <major>.<minor>.*
+  // (numeric patch order), INCLUDING patches newer than the CLI's own patch.
+  // Patch releases are compatibility fixes; allowing them to float is what lets us
+  // replace a broken immutable runner without asking every developer to know a pin.
+  // Constrained to the CLI's exact minor, so it stays within the ceiling.
   const m = /^(\d+)\.(\d+)\./.exec(cliVersion || "");
   if (m) {
     const prefix = `${m[1]}.${m[2]}.`;
@@ -520,11 +523,9 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin, declaredVersi
     return { version, reason: `highest ≤ CLI major.minor ${cliMM ? `${cliMM.major}.${cliMM.minor}` : "?"}` };
   }
   // NO floating-tag last resort. We deliberately do NOT fall back to the `latest`
-  // dist-tag: a channel can drift behind/ahead of what THIS CLI expects (the exact
-  // failure mode that shipped stale CLIs — see the copy-paste pin in the storefront
-  // cockpit). If nothing exact/minor/≤-ceiling is published, that's a release gap to
-  // fix by publishing the runner at the CLI's version — not something to paper over
-  // with whatever `latest` happens to point at.
+  // dist-tag: a channel can drift behind/ahead of what THIS CLI expects. If nothing
+  // stable within the CLI minor or below its ceiling is published, that's a release
+  // gap to fix — not something to paper over with whatever `latest` points at.
   throw new Error(
     `no runner version at or below the CLI's major.minor (${cliMM ? `${cliMM.major}.${cliMM.minor}` : cliVersion})`,
   );
@@ -536,7 +537,7 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin, declaredVersi
  * rust-toolchain.toml of the storefront: the PRODUCT (via tenant_checkout
  * stamping it server-side) owns which runtime the store runs; the CLI just
  * resolves it. Returns null when absent/malformed/not-semver — silence is
- * correct: an undeclared checkout falls back to the transitional lockstep rung.
+ * correct: an undeclared checkout falls back to the compatible CLI-minor rung.
  * Pure-ish (one file read) + exported for tests.
  * @param {string|null|undefined} workspaceDir
  * @returns {string|null}
@@ -576,6 +577,11 @@ function compareStableAsc(a, b) {
  * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
  * overridable via env for testing.
  */
+/**
+ * @param {any} args
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{ declaredVersion?: string|null }} [opts]
+ */
 export async function resolvePublicRendererSource(args, env = process.env, { declaredVersion = null } = {}) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
@@ -605,26 +611,47 @@ export async function resolvePublicRendererSource(args, env = process.env, { dec
           `using ${version} (${reason}). The store's runnerVersion needs a published release.`,
       );
     }
-  } else if (!explicitPin && version !== CLI_VERSION) {
-    // No declaration (transitional lockstep regime — ADR 0011): exact is the goal.
-    // Resolving something ELSE means CLI/runner releases are skewed — say so LOUDLY
-    // instead of silently running a mismatched runner.
+  } else if (!explicitPin && version !== CLI_VERSION && !isCompatibleMaintenancePatch(CLI_VERSION, version)) {
+    // A stable same-minor maintenance patch is the normal self-healing path, not
+    // skew. Anything else still deserves a loud warning: it means resolution had
+    // to leave the CLI's compatibility line.
     console.warn(
       `  ⚠ runner ${version} — no exact @${CLI_VERSION} published (${reason}). ` +
         `CLI/runner versions are SKEWED; publish the runner at ${CLI_VERSION} to align ` +
         `(or pin with --renderer-version to silence).`,
     );
   }
-  const tarball = meta?.versions?.[version]?.dist?.tarball;
-  if (!tarball) throw new Error(`no published ${pkg}@${version} on npm`);
-  return { kind: "public", version, url: tarball, strip: 1, cacheKey: `public-${version}` };
+  const dist = meta?.versions?.[version]?.dist;
+  if (!dist?.tarball) throw new Error(`no published ${pkg}@${version} on npm`);
+  // `integrity` is the artifact's CONTENT identity (npm dist.integrity, else the
+  // legacy shasum) — installRunnerTarball verifies the downloaded bytes against
+  // it and records it so a same-version corrected republish busts the cache.
+  return {
+    kind: "public",
+    version,
+    url: dist.tarball,
+    strip: 1,
+    cacheKey: `public-${version}`,
+    integrity: dist.integrity || dist.shasum || null,
+  };
+}
+
+/** Stable x.y patches share the runner/CLI contract; prereleases do not. */
+function isCompatibleMaintenancePatch(cliVersion, runnerVersion) {
+  if (!/^\d+\.\d+\.\d+$/.test(String(cliVersion)) || !/^\d+\.\d+\.\d+$/.test(String(runnerVersion))) {
+    return false;
+  }
+  const cliMM = majorMinor(cliVersion);
+  const runnerMM = majorMinor(runnerVersion);
+  return !!cliMM && !!runnerMM && cliMM.major === runnerMM.major && cliMM.minor === runnerMM.minor;
 }
 
 /**
  * ENTITLED source: the MCP's `dev_renderer_artifact` signed URL, gated on the
  * developer entitlement (same gate as the Docker pull token). Reuses an
- * already-authenticated `client` when provided (C1/F3), else establishes its own.
+ * already-authenticated `client` when provided, else establishes its own.
  */
+/** @param {any} args @param {{ client?: any }} [opts] */
 export async function resolveEntitledRendererSource(args, { client: providedClient } = {}) {
   const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = providedClient || createMcpClient(baseUrl);
@@ -637,7 +664,17 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
   if (!res?.url || !res?.version) {
     throw new Error(res?.error || "no renderer-artifact URL returned");
   }
-  return { kind: "entitled", version: res.version, url: res.url, strip: 0, cacheKey: res.version };
+  // Opportunistic content identity: recorded/verified when the MCP declares one
+  // (integrity/sha256); a server that doesn't is simply unverified (null), never
+  // an error — the cache then busts on version changes only, as before.
+  return {
+    kind: "entitled",
+    version: res.version,
+    url: res.url,
+    strip: 0,
+    cacheKey: res.version,
+    integrity: res.integrity || res.sha256 || null,
+  };
 }
 
 /**
@@ -649,11 +686,13 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
  * anything that should fall back to Docker (MCP unreachable, not entitled, not
  * configured, no corepack/pnpm on this host) rather than hard-failing `tot dev`.
  *
- * Exported + accepts an already-authenticated `client` (C1/F3 integration:
- * `tot start` reuses its own session and overlaps this with the checkout clone
+ * Exported + accepts an already-authenticated `client` (`tot start` reuses
+ * its own session and overlaps this with the checkout clone
  * instead of paying for a second client.initialize()+establishSession() — same
  * pattern as ensureRegistryLogin's `providedClient`). `tot dev` standalone
  * omits it and this establishes its own, as before.
+ * @param {any} args
+ * @param {{ client?: any }} [opts]
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
  */
 export async function ensureRendererArtifact(args, { client: providedClient } = {}) {
@@ -676,7 +715,12 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
 
   try {
     const runnerDir = await installRunnerTarball(
-      { source: credential.url, version: credential.version, isUrl: true },
+      {
+        source: credential.url,
+        version: credential.version,
+        isUrl: true,
+        integrity: credential.integrity || credential.sha256 || null,
+      },
       { log: (m) => console.error(m) },
     );
     setRunnerVersion(credential.version); // telemetry: stamp the entitled runner version, like ensureSampleRenderer
@@ -829,11 +873,11 @@ export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
  * @returns {Promise<string>} the runner tree's root directory (has scripts/tot-dev.mjs).
  */
 export async function ensureSampleRenderer(args, ctx, { env = process.env, cacheRoot = RENDERER_CACHE_ROOT } = {}) {
-  const src = resolveLocalRendererSource({
+  const src = /** @type {any} */ (resolveLocalRendererSource({
     env,
     mode: ctx?.mode,
     repoRoot: ctx?.repoRoot,
-  });
+  }));
 
   if (src.kind === "dir") {
     if (!existsSync(join(src.dir, "scripts", "tot-dev.mjs"))) {
@@ -851,24 +895,32 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
     console.error(`~ renderer: ${src.why}`);
     return installRunnerTarball(
       { source: src.source, version: sourceVersionKey(src.source), isUrl: src.isUrl },
-      { log: (m) => console.error(m) },
+      { log: (m) => console.error(m), cacheRoot },
     );
   }
 
   // kind === "none" — no override, not in the monorepo: fetch the PUBLIC runner
-  // from npm. Version = what the STORE declares (ADR 0011), else pinned to this
-  // CLI's version (transitional lockstep). No MCP, no entitlement, no login.
+  // from npm. Version = what the STORE declares (ADR 0011), else the newest stable
+  // maintenance patch in this CLI's major.minor. No MCP, no entitlement, no login.
   const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
   const declared = declaredRunnerVersion(args.workspace || ctx?.workspacePath);
   const wantVersion = declared || CLI_VERSION;
 
-  // Fully-offline fast path: when the WANTED version (declared, else lockstep) is
-  // already cached, reuse it without touching npm — honouring "don't hit npm when
-  // the RIGHT version is already cached" without ever reusing a version the
-  // resolution wouldn't choose. Safe because `public-<version>` only exists if a
-  // prior run fetched exactly that version. Skipped when an explicit pin is set
-  // (that must go through resolution).
-  if (!explicitPin) {
+  // Offline-safe fast path for a product-declared exact version: when that version
+  // is already cached, reuse it — honouring "don't hit npm when the RIGHT version
+  // is already cached" without reusing a version the declaration did not choose.
+  // Safe because `public-<version>` only exists if a prior run fetched exactly
+  // that version. Skipped when an explicit pin is set (that must go through
+  // resolution). One refinement over fully-offline: a QUICK, soft-fail registry
+  // probe (publishedRunnerIntegrity) revalidates the cached CONTENT identity when
+  // npm is reachable, so a corrected republish under the same version string is
+  // picked up automatically; offline/slow/unanswerable → trust the cache exactly
+  // as before (the probe can never block or fail the run).
+  // A store declaration is an exact product pin, so it is safe to reuse directly.
+  // Without a declaration, do not short-circuit on runner@CLI_VERSION: registry
+  // resolution may have a newer compatible patch that repairs an immutable bad
+  // artifact. The normal resolution path below still reuses its installed cache.
+  if (!explicitPin && declared) {
     const exact = pinnedPublicCacheDir(cacheRoot, wantVersion);
     if (exact) {
       // Trust-but-verify: a `public-<version>` dir SHOULD be a current runner,
@@ -878,21 +930,31 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
       // host's arch (rendererCacheHealthy) — a cache poisoned with the wrong-arch
       // bindings (npm/cli#4828) would otherwise be reused forever and crash astro
       // at boot with the swallowed "dev server didn't come up". When both hold,
-      // reuse it (fully offline-safe).
+      // reuse it (offline-safe).
       if (probeRunnerVersion(exact) && rendererCacheHealthy(exact)) {
+        const published = await publishedRunnerIntegrity(env, wantVersion);
+        const recorded = readCacheMarker(exact)?.integrity || null;
+        if (!published || !recorded || published === recorded) {
+          console.error(
+            `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+          );
+          setRunnerVersion(wantVersion);
+          prunePublicRunnerCache(cacheRoot, wantVersion);
+          return exact;
+        }
+        // Same version string, different published contents — a corrected
+        // republish. Fall through to resolution + a fresh install (which also
+        // verifies the new bytes against the new integrity).
+        console.error(`~ renderer: ${wantVersion} was republished with different contents — refetching the corrected artifact`);
+        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none matches what npm now publishes
+      } else {
         console.error(
-          `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+          rendererCacheHealthy(exact)
+            ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
+            : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
         );
-        setRunnerVersion(wantVersion);
-        prunePublicRunnerCache(cacheRoot, wantVersion);
-        return exact;
+        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
       }
-      console.error(
-        rendererCacheHealthy(exact)
-          ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
-          : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
-      );
-      prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
     }
   }
 
@@ -923,8 +985,8 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   // The store preview engine (public npm ${PUBLIC_RUNNER_PACKAGE}@${pub.version}) — kept
   // out of the user's way; the setup spinner below is the visible progress.
   const dir = await installRunnerTarball(
-    { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip },
-    { log: (m) => console.error(m) },
+    { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip, integrity: pub.integrity },
+    { log: (m) => console.error(m), cacheRoot },
   );
   setRunnerVersion(pub.version); // telemetry: the runner version running this session
   // The pinned version is now installed under public-<version> — drop any other
@@ -949,92 +1011,269 @@ function sourceVersionKey(source) {
  * authenticated (ensureRendererArtifact) and zero-login (ensureSampleRenderer)
  * paths so they cache identically.
  *
- * @param {{ source: string, version: string, isUrl?: boolean }} spec
- * @param {{ log?: (m: string) => void }} [opts]
+ * Cache-poisoning invariants (the 2026-08-18 first-run hardening):
+ *   • promote-on-success only — the install runs in a per-attempt staging dir and
+ *     is renamed into the canonical slot ONLY after it fully succeeds, so a failed
+ *     install can never become the cached artifact a later run resumes from.
+ *   • the completion marker is a manifest carrying the source's CONTENT identity
+ *     (`integrity`), so a corrected republish under the SAME version string is a
+ *     cache miss (rebuild), not a stale hit — no manual `rm -rf` ever required.
+ *   • a failed attempt auto-cleans and retries ONCE from a clean slate before
+ *     surfacing the error (transient blips heal themselves); deterministic
+ *     failures (`e.permanent`) skip the retry and fail loud immediately.
+ *
+ * @param {{ source: string, version: string, isUrl?: boolean, strip?: number, integrity?: string|null }} spec
+ *   `integrity` is the source artifact's content identity when the resolver knows
+ *   it (npm `dist.integrity`/`dist.shasum`); used to verify the downloaded bytes
+ *   and to bust a cached entry whose recorded identity no longer matches.
+ * @param {{ log?: (m: string) => void, cacheRoot?: string }} [opts]
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
  */
-export async function installRunnerTarball({ source, version, isUrl = true, strip = 0 }, { log = (m) => console.error(m) } = {}) {
-  const runnerDir = join(RENDERER_CACHE_ROOT, version);
-  const marker = join(runnerDir, ".tot-cache-complete");
-  if (existsSync(marker)) {
-    // Reuse ONLY if the cached tree carries native bindings for this host's arch.
-    // A cache poisoned with the wrong-arch binaries (npm/cli#4828 — e.g. darwin-x64
-    // on an arm64 Mac) is otherwise trusted forever, and astro crashes at boot with
-    // `Cannot find native binding`, swallowed as "the dev server didn't come up".
-    // Unhealthy → fall through and rebuild from the source below.
-    if (rendererCacheHealthy(runnerDir)) return runnerDir; // already downloaded + installed
-    log(`~ store preview engine cache is missing native bindings for ${process.platform}-${process.arch} — rebuilding it…`);
+export async function installRunnerTarball(
+  { source, version, isUrl = true, strip = 0, integrity = null },
+  { log = (m) => console.error(m), cacheRoot = RENDERER_CACHE_ROOT } = {},
+) {
+  const runnerDir = join(cacheRoot, version);
+  // Staging dirs from DEAD runs (crashed/killed installs) must not leak disk
+  // forever — reap them here, the one funnel every install path goes through.
+  sweepStaleStagingDirs(cacheRoot);
+
+  const localSource = isUrl ? null : resolveLocalTarball(source);
+  // The EXPECTED content identity of the source artifact. A local tarball with no
+  // caller-provided integrity is cheap to hash on every run, so a same-path
+  // republish (new contents, same file name) busts the cache too.
+  const expected = integrity || (isUrl ? null : fileIntegrity(localSource));
+
+  const cached = readCacheMarker(runnerDir);
+  if (cached) {
+    if (!rendererCacheHealthy(runnerDir)) {
+      // A cache poisoned with the wrong-arch binaries (npm/cli#4828 — e.g.
+      // darwin-x64 on an arm64 Mac) is otherwise trusted forever, and astro
+      // crashes at boot with `Cannot find native binding`, swallowed as "the dev
+      // server didn't come up". Fall through and rebuild from the source below.
+      log(`~ store preview engine cache is missing native bindings for ${process.platform}-${process.arch} — rebuilding it…`);
+    } else if (expected && cached.integrity && expected !== cached.integrity) {
+      // CONTENT-HASH BUST: same version string, different artifact contents — a
+      // corrected republish. The cached entry is stale by identity, not by label;
+      // rebuild from the corrected source instead of serving the stale cache.
+      log(`~ the preview engine's ${version} artifact changed upstream (same version, new contents) — rebuilding…`);
+    } else {
+      return runnerDir; // already downloaded + installed (and contents still match)
+    }
   }
 
   // First run only — set the expectation so the one-time cost doesn't read as a
   // hang: this downloads + installs the renderer once, then every later run of
   // this version is a no-network cache hit.
   log(`~ first run: setting up your store preview (~a minute, one-time — cached after this)…`);
-  const localSource = isUrl ? null : resolveLocalTarball(source);
-  const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`) : localSource;
-  try {
-    if (isUrl) {
-      // The fetch itself is otherwise silent (no per-byte output) and can run
-      // tens of seconds on a cold cache — tick a spinner so it never looks hung.
-      const spin = startProgress("downloading the store preview engine…");
+  // AUTO-CLEAN-AND-RETRY-ONCE: a transient failure (network blip mid-download, a
+  // registry hiccup mid-install) heals itself with one clean re-attempt instead
+  // of stopping a first run at an error only `rm -rf` folklore could clear.
+  // Bounded to one retry so a genuinely-broken source still fails loudly.
+  for (let attempt = 1; ; attempt++) {
+    const archivePath = /** @type {string} */ (isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource);
+    const stagingDir = `${runnerDir}.staging-${process.pid}`;
+    try {
+      if (isUrl) {
+        // The fetch itself is otherwise silent (no per-byte output) and can run
+        // tens of seconds on a cold cache — tick a spinner so it never looks hung.
+        const spin = startProgress("downloading the store preview engine…");
+        try {
+          await downloadFile(source, archivePath);
+        } finally {
+          spin.stop();
+        }
+      }
+      if (!existsSync(archivePath)) {
+        throw new Error(`renderer tarball not found: ${archivePath}`);
+      }
+      // Refuse to install bytes that don't match the source's declared identity —
+      // a truncated/corrupted download would otherwise be cached as if complete.
+      // (Transient by nature, so the retry above gets a fresh download.)
+      if (expected && !tarballMatchesIntegrity(archivePath, expected)) {
+        throw new Error(`the downloaded preview-engine tarball failed its integrity check (expected ${expected})`);
+      }
+      // The identity recorded in the completion manifest below — what future runs
+      // compare against to detect a same-version republish. Hash the actual bytes
+      // when the resolver couldn't tell us (e.g. the entitled signed-URL path).
+      const contentId = expected || fileIntegrity(archivePath);
+      rmSync(stagingDir, { recursive: true, force: true });
+      mkdirSync(stagingDir, { recursive: true });
+      extractTarball(archivePath, stagingDir, { strip });
+      // Pin the runner install to PUBLIC npm. The moat-free runner has only public
+      // deps, but the HOST's global ~/.npmrc may point `registry` at a private
+      // mirror (an internal proxy that 502s, or one an invited developer can't
+      // reach) — an invited dev's machine config must never decide where the
+      // runner's public deps come from. A project-level .npmrc wins over the user's.
+      writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
+      // The install is the long, noisy step — tick a spinner while its output goes
+      // to a log, so the terminal shows one clean line instead of the pnpm firehose.
+      // corepack setup logs to the SAME file so its failures aren't invisible (they
+      // were the silent cause of "couldn't set up the store preview engine").
+      const installLog = join(cacheRoot, `${version}.install.log`);
+      ensureCorepackPnpm(stagingDir, { logPath: installLog });
+      const installSpin = startProgress("installing the store preview engine…", {
+        stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
+      });
       try {
-        await downloadFile(source, archivePath);
+        await runPnpmInstall(stagingDir, { logPath: installLog });
       } finally {
-        spin.stop();
+        installSpin.stop();
       }
+      // Atomic-ish: only rename into the final, discoverable path once install
+      // succeeded, so a crashed/interrupted run never leaves a half-built cache
+      // entry that a later `tot dev` would treat as ready.
+      rmSync(runnerDir, { recursive: true, force: true });
+      renameSync(stagingDir, runnerDir);
+      // Fence a fresh install against npm/cli#4828: if the installer left the wrong
+      // arch's native bindings (or none) for this host, DON'T stamp the completion
+      // marker — an unmarked tree is never reused, so the next run reinstalls cleanly
+      // instead of caching the poison and crashing astro at boot. Fail loud + actionable
+      // rather than swallow it as "the dev server didn't come up". Permanent: the
+      // same installer on the same host would just produce the same result, so the
+      // auto-retry is skipped.
+      if (!rendererCacheHealthy(runnerDir)) {
+        await emitObstacle("renderer-native-bindings-missing");
+        const err = new CliError(
+          `the store preview engine installed but is missing its native components for ${process.platform}-${process.arch}`,
+          {
+            next: "install pnpm (`npm i -g pnpm`, or `corepack enable`) and re-run `tot start` — pnpm installs the platform-native bits npm can skip (npm/cli#4828)",
+            exitCode: 2,
+          },
+        );
+        /** @type {any} */ (err).permanent = true;
+        throw err;
+      }
+      writeCacheMarker(runnerDir, { version, integrity: contentId });
+      return runnerDir;
+    } catch (e) {
+      // A failed attempt must never survive on disk — not as staging debris, and
+      // (by promote-on-success) it never reached the canonical slot at all.
+      rmSync(stagingDir, { recursive: true, force: true });
+      if (e?.permanent === true || attempt >= 2) throw e;
+      log(`~ that didn't work (${String(e?.message || e).split("\n")[0]}) — retrying once from a clean slate…`);
+    } finally {
+      if (isUrl) rmSync(archivePath, { force: true });
     }
-    if (!existsSync(archivePath)) {
-      throw new Error(`renderer tarball not found: ${archivePath}`);
-    }
-    const stagingDir = `${runnerDir}.staging-${process.pid}`;
-    rmSync(stagingDir, { recursive: true, force: true });
-    mkdirSync(stagingDir, { recursive: true });
-    extractTarball(archivePath, stagingDir, { strip });
-    // Pin the runner install to PUBLIC npm. The moat-free runner has only public
-    // deps, but the HOST's global ~/.npmrc may point `registry` at a private
-    // mirror (an internal proxy that 502s, or one an invited developer can't
-    // reach) — an invited dev's machine config must never decide where the
-    // runner's public deps come from. A project-level .npmrc wins over the user's.
-    writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
-    // The install is the long, noisy step — tick a spinner while its output goes
-    // to a log, so the terminal shows one clean line instead of the pnpm firehose.
-    // corepack setup logs to the SAME file so its failures aren't invisible (they
-    // were the silent cause of "couldn't set up the store preview engine").
-    const installLog = join(RENDERER_CACHE_ROOT, `${version}.install.log`);
-    ensureCorepackPnpm(stagingDir, { logPath: installLog });
-    const installSpin = startProgress("installing the store preview engine…", {
-      stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
-    });
+  }
+}
+
+/**
+ * Read a cache entry's completion marker (`.tot-cache-complete`). Returns the
+ * manifest object (at least `{ integrity: string|null }`), or null when the
+ * marker is absent — i.e. the entry is incomplete/partial and must be treated
+ * as if it didn't exist. A legacy pre-manifest marker (a bare timestamp string)
+ * reads as complete-with-unknown-identity, so existing healthy caches survive
+ * the upgrade without a forced rebuild.
+ */
+export function readCacheMarker(dir) {
+  try {
+    const raw = readFileSync(join(dir, ".tot-cache-complete"), "utf8");
     try {
-      await runPnpmInstall(stagingDir, { logPath: installLog });
-    } finally {
-      installSpin.stop();
+      const m = JSON.parse(raw);
+      if (m && typeof m === "object") return { integrity: null, ...m };
+    } catch {
+      /* legacy timestamp-string marker */
     }
-    // Atomic-ish: only rename into the final, discoverable path once install
-    // succeeded, so a crashed/interrupted run never leaves a half-built cache
-    // entry that a later `tot dev` would treat as ready.
-    rmSync(runnerDir, { recursive: true, force: true });
-    renameSync(stagingDir, runnerDir);
-    // Fence a fresh install against npm/cli#4828: if the installer left the wrong
-    // arch's native bindings (or none) for this host, DON'T stamp the completion
-    // marker — an unmarked tree is never reused, so the next run reinstalls cleanly
-    // instead of caching the poison and crashing astro at boot. Fail loud + actionable
-    // rather than swallow it as "the dev server didn't come up".
-    if (!rendererCacheHealthy(runnerDir)) {
-      await emitObstacle("renderer-native-bindings-missing");
-      throw new CliError(
-        `the store preview engine installed but is missing its native components for ${process.platform}-${process.arch}`,
-        {
-          next: "install pnpm (`npm i -g pnpm`, or `corepack enable`) and re-run `tot start` — pnpm installs the platform-native bits npm can skip (npm/cli#4828)",
-          exitCode: 2,
-        },
-      );
+    return { integrity: null };
+  } catch {
+    return null; // no marker → never treat the entry as installed
+  }
+}
+
+/** Stamp a cache entry complete: version + source content identity + when. */
+function writeCacheMarker(dir, { version, integrity }) {
+  writeFileSync(
+    join(dir, ".tot-cache-complete"),
+    JSON.stringify({ version, integrity: integrity || null, completedAt: new Date().toISOString() }) + "\n",
+  );
+}
+
+/** sha512 SRI (`sha512-<base64>`, npm's `dist.integrity` format) of a file; null when unreadable. */
+function fileIntegrity(path) {
+  try {
+    return `sha512-${createHash("sha512").update(readFileSync(path)).digest("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Do the tarball's bytes match `expected` — an SRI string (`sha512-<b64>`, npm's
+ * `dist.integrity`) or npm's legacy `dist.shasum` (bare 40-hex sha1)? Unknown
+ * formats and probe errors return true: this check exists to catch corrupted
+ * bytes, never to block an install on a format we can't verify.
+ */
+export function tarballMatchesIntegrity(archivePath, expected) {
+  try {
+    const want = String(expected).trim();
+    const sri = /^(sha512|sha384|sha256|sha1)-([A-Za-z0-9+/=]+)$/.exec(want);
+    if (sri) {
+      return createHash(sri[1]).update(readFileSync(archivePath)).digest("base64") === sri[2];
     }
-    writeFileSync(marker, new Date().toISOString());
-  } finally {
-    if (isUrl) rmSync(archivePath, { force: true });
+    if (/^[0-9a-f]{40}$/i.test(want)) {
+      return createHash("sha1").update(readFileSync(archivePath)).digest("hex") === want.toLowerCase();
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Reap `<entry>.staging-<pid>` dirs left by DEAD processes — failed/killed
+ * installs used to accumulate one orphaned staging tree per attempt, leaking
+ * disk forever. A staging dir whose pid is still alive belongs to a concurrent
+ * `tot dev` mid-install and is left alone. Best-effort: never throws, and never
+ * touches this process's own staging dir (created fresh after this sweep).
+ */
+export function sweepStaleStagingDirs(cacheRoot, { pidAlive = processAlive } = {}) {
+  try {
+    if (!cacheRoot || !existsSync(cacheRoot)) return;
+    for (const name of readdirSync(cacheRoot)) {
+      const m = /\.staging-(\d+)$/.exec(name);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      if (pid === process.pid || pidAlive(pid)) continue;
+      rmSync(join(cacheRoot, name), { recursive: true, force: true });
+    }
+  } catch {
+    /* best-effort cache hygiene */
+  }
+}
+
+/** Is a pid a live process? (signal 0 probe; EPERM = alive but not ours.) */
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+
+/**
+ * The registry-declared content identity (`dist.integrity`, else `dist.shasum`)
+ * of the public runner at `version` — or null when npm can't answer QUICKLY
+ * (offline, slow, 4xx/5xx, malformed). Used by ensureSampleRenderer's cached
+ * fast path to detect a same-version republish without ever making the network
+ * a hard dependency: null means "can't verify right now — trust the cache",
+ * preserving the offline-reuse behavior exactly.
+ */
+export async function publishedRunnerIntegrity(env, version, { timeoutMs = 2000, fetchFn = fetch } = {}) {
+  try {
+    const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
+    const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
+    const res = await fetchFn(`${registry}/${pkg.replace("/", "%2f")}`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const dist = (await res.json())?.versions?.[version]?.dist;
+    return dist?.integrity || dist?.shasum || null;
+  } catch {
+    return null;
   }
-  return runnerDir;
 }
 
 /** Strip an optional file:// prefix from a local tarball path and resolve it absolute. */
@@ -1054,7 +1293,7 @@ async function downloadFile(url, destPath) {
   if (!res.ok || !res.body) {
     throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
   }
-  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+  await pipeline(Readable.fromWeb(/** @type {any} */ (res.body)), createWriteStream(destPath));
 }
 
 /**
@@ -1103,7 +1342,8 @@ export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } =
     for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
       const r = spawnFn("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
       if (fd !== null && (r.error || r.status !== 0)) {
-        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
+        const rerr = /** @type {any} */ (r.error);
+        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${rerr?.code || rerr?.message || `exit ${r.status}`}\n`);
       }
     }
   } finally {
@@ -1147,6 +1387,10 @@ function spawnAsyncResult(cmd, args, opts = {}) {
   });
 }
 
+/**
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any }} [opts]
+ */
 export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
@@ -1163,8 +1407,8 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
   // If a launcher isn't installed at all (ENOENT) we move on; a launcher that
   // RAN but whose install failed is the real error and stops the loop.
   // REQUIRES a runner >= 1.3.4-rc.2 — older runner tarballs still carry
-  // `workspace:*` deps npm rejects (harmless here: pickRunnerVersion pins the
-  // runner to this CLI's version, so this CLI never installs those).
+  // `workspace:*` deps npm rejects (harmless here: resolution stays on this
+  // CLI's compatible release line, whose runner artifacts are installable).
   const attempts = [
     { cmd: "pnpm", args: installArgs },
     { cmd: "corepack", args: ["pnpm", ...installArgs] },
@@ -1184,28 +1428,39 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
       });
       if (r.status === 0) return; // installed
-      if (r.error?.code === "ENOENT") {
+      if (/** @type {any} */ (r.error)?.code === "ENOENT") {
         // This launcher isn't on the machine — record it and try the next one.
         if (fd !== null) writeSync(fd, `[tot] ${cmd} not found (ENOENT) — trying the next launcher\n`);
         continue;
       }
       // The launcher ran; the install itself failed. That's the actionable error.
+      // installRunnerTarball retries transient failures once from a clean slate;
+      // deterministic broken-release 404s are marked permanent below and skip it.
       await emitObstacle("install-failed");
-      throw new CliError(
+      const brokenRelease = missingPackage404(logPath);
+      const err = new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
-        { next: "check the details log above, then re-run `tot start` (it resumes from the cache)" },
+        { next: "check the details log above, then re-run `tot start` (it retries from a clean slate — no cache to clear)" },
       );
+      // A package 404 is deterministic metadata baked into this immutable runner
+      // tarball. Retrying the same bytes wastes another full install; return at once
+      // so the caller can transparently fall back to the compatible public patch.
+      if (brokenRelease) err.permanent = true;
+      throw err;
     }
     // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
     // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
     // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    // Permanent: retrying can't conjure a launcher — skip the clean-slate retry.
     await emitObstacle("pnpm-missing");
-    throw new CliError(
+    const err = new CliError(
       "couldn't set up the store preview engine — pnpm isn't available on this machine" +
         (logPath ? `\n     details: ${logPath}` : ""),
       { next: "install pnpm with `npm i -g pnpm` (or `corepack enable`), then re-run `tot start`" },
     );
+    /** @type {any} */ (err).permanent = true;
+    throw err;
   } finally {
     if (fd !== null) closeSync(fd);
   }
@@ -1219,6 +1474,19 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
 function pnpmFailureHint(logPath) {
   if (!logPath) return " — is pnpm/corepack available on this host?";
   try {
+    // A 404 means the registry answered — a specific package/version doesn't
+    // exist there. Since installs now run from a clean slate every attempt
+    // (promote-on-success + auto-retry), this is a BROKEN RUNNER RELEASE (it
+    // references an unpublished package), not the user's cache — no `rm -rf`
+    // will help. Check this BEFORE the generic ERR_PNPM_FETCH match, since
+    // pnpm's 404 error text also contains "ERR_PNPM_FETCH".
+    const missing404 = missingPackage404(logPath);
+    if (missing404) {
+      return (
+        ` — the preview engine references a package that isn't published (${missing404});` +
+        " that's a broken preview-engine release, not your machine"
+      );
+    }
     const tail = readFileSync(logPath, "utf8").slice(-8000);
     if (/npm\.tokenoftrust\.com|ERR_PNPM_FETCH|502|ECONNREFUSED|ETIMEDOUT|ENOTFOUND/i.test(tail)) {
       return " — the Token of Trust package registry looks unreachable right now; check your connection and retry";
@@ -1229,12 +1497,27 @@ function pnpmFailureHint(logPath) {
   return "";
 }
 
+/** Return the missing package URL from a pnpm 404, else null. */
+function missingPackage404(logPath) {
+  if (!logPath) return null;
+  try {
+    const tail = readFileSync(logPath, "utf8").slice(-8000);
+    return tail.match(/ERR_PNPM_FETCH_404[^\n]*GET\s+(\S+)/i)?.[1] || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Run the cached runner's own scripts/tot-dev.mjs in standalone (--workspace)
  * mode — the exact code path the WS3 spike verified gives native, non-polled
  * fs-watch HMR. Returns a handle shaped like spawnDevContainer's, so run()'s
  * auto-open-browser logic works unchanged for either runtime. Exported (and
  * `stdio` overridable) so `tot start` can pipe the logs instead of inheriting.
+ * @param {string} runnerDir
+ * @param {string} workspace
+ * @param {string} port
+ * @param {{ stdio?: any, env?: Record<string, any> }} [opts]
  */
 export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit", env = {} } = {}) {
   const script = join(runnerDir, "scripts", "tot-dev.mjs");
@@ -1246,7 +1529,7 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
   // `env` (e.g. activityBridgeEnv()) merges OVER process.env — {} is a pure
   // passthrough, identical to the old no-env-key behavior. Append `--no-warnings`
   // to NODE_OPTIONS so the runner's Node process never emits the scary
-  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer (b4);
+  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer;
   // appended (not replaced) so any host-set NODE_OPTIONS is preserved.
   const mergedEnv = { ...process.env, ...env };
   mergedEnv.NODE_OPTIONS = `${mergedEnv.NODE_OPTIONS ? `${mergedEnv.NODE_OPTIONS} ` : ""}--no-warnings`;
@@ -1255,7 +1538,7 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
     [script, "--workspace", workspace, "--port", port],
     { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1289,7 +1572,7 @@ async function runContainer(workspace, args, ctx) {
   const handle = await spawnDevContainer(plan, args, { stdio: "piped" });
   streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(activityBridgeEnv().TOT_DEV_ACTIVITY_URL) });
 
-  // Heartbeat the hosted cockpit (G1) CLI-side while the container runs — the
+  // Heartbeat the hosted cockpit CLI-side while the container runs — the
   // container reports file-saves via the threaded env, but the CLI owns the
   // version + live URL. Same bridge credential (activityBridgeEnv), no-op absent.
   const stopHeartbeat = startHeartbeatFromEnv(activityBridgeEnv(), { url: plan.url, cwd: plan.workspace });
@@ -1314,7 +1597,7 @@ async function runContainer(workspace, args, ctx) {
 
 /**
  * Resolve the runner image ref the same way buildContainerPlan does — exported
- * so a caller (`tot start`, for C1) can know the image, and therefore prefetch
+ * so a caller (`tot start`) can know the image, and therefore prefetch
  * a registry login (below), before the checkout dir exists.
  */
 export function resolveDevImage(args, env = process.env) {
@@ -1410,9 +1693,9 @@ export async function spawnDevContainer(plan, args, { stdio = "inherit" } = {})
 
   const stdioArr =
     stdio === "piped" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"];
-  const child = spawn("docker", plan.dockerArgs, { stdio: stdioArr });
+  const child = spawn("docker", plan.dockerArgs, { stdio: /** @type {any} */ (stdioArr) });
 
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1448,10 +1731,11 @@ export function isPrivateRegistryImage(image) {
  * the session, or the tool isn't available yet, warn softly and continue (an
  * existing `docker login`, or the docker pull error, takes over).
  *
- * Exported + accepts an already-authenticated `client` (C1: `tot start` reuses
+ * Exported + accepts an already-authenticated `client` (`tot start` reuses
  * its own session and overlaps this with the checkout clone instead of paying
  * for a second client.initialize()+establishSession() serially afterward).
  * `tot dev` standalone omits it and this establishes its own, as before.
+ * @param {string} image @param {any} args @param {{ client?: any }} [opts]
  */
 export async function ensureRegistryLogin(image, args, { client: providedClient } = {}) {
   const registry = String(image).split("/")[0];
@@ -1501,7 +1785,7 @@ export function dockerAvailable() {
  * thing `open -a` can launch unattended; other platforms report false and
  * leave it to the caller's usual next-command message). Returns true once
  * Docker answers, false if it doesn't within the wait window. Shared by
- * `tot start`'s preflight and `tot doctor --fix` (F2).
+ * `tot start`'s preflight and `tot doctor --fix`.
  */
 export async function tryStartDocker() {
   if (process.platform !== "darwin") return false;