@ultimat3/cli 20.2.1 → 22.0.0

package/src/island-bundle.ts

@@ -3,6 +3,13 @@
 // byte-deterministic), plus the resolver that turns a page's `src` specifier into the URL its
 // `data-x-entry` carries. One entry point per island is axiom 6 made mechanical — the page's graph
 // never reaches an island, so a `site/` document stays at 0kb whatever the island imports.
+//
+// No page-client bootstrap is prepended (plan 101, decided 2026-09-22): the handle is one
+// `globalThis` object created lazily by the first transport call or realtime hook. Measured before
+// that decision on `examples/dummy`, a core-importing wrapper cost contact-sales 875 → 8,827 B.
+// What IS prepended is the realtime install, and only where the island's graph reaches
+// `@ultimat3/realtime` (`island-realtime.ts`). Measured on a fixture, As of 2026-09-22: a Solid
+// island reading `useConnection` 64,964 → 65,067 B (+103 B); an island not reaching realtime +0.
 
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
@@ -11,6 +18,7 @@ import { frameworkVersion, renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
+import { islandRealtimePlugin, REALTIME_ISLAND_ENTRY, reachesRealtime } from './island-realtime';
 import { solidDedupePlugin } from './island-solid-dedupe';
 import { islandStylesPlugin } from './island-styles';
 import { hasPathSegment } from './path-segments';
@@ -75,10 +83,18 @@ export async function discoverIslands(root: string): Promise<readonly string[]>
 async function buildOne(root: string, file: string): Promise<IslandChunk> {
   // `Bun.build` REJECTS on a failed bundle, it does not answer `success: false` — so the catch is
   // the real path here and the `success` test below is the belt for a future default.
+  // Only an island whose own graph reaches `@ultimat3/realtime` is wrapped (`island-realtime.ts`);
+  // every other one is built from its own file, byte for byte what it was.
+  // Inside the refusal too: the realtime probe PARSES the island's graph, and a file that will not
+  // parse rejected with a raw `AggregateError: Failed to scan imports` — out of the web boot, with
+  // no code, no file and no fix — before `Bun.build` ever ran to raise the one below.
+  const realtime = await reachesRealtime(root, file).catch((error: unknown) => {
+    throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
+  });
   let built: Awaited<ReturnType<typeof Bun.build>>;
   try {
     built = await Bun.build({
-      entrypoints: [join(root, file)],
+      entrypoints: [realtime ? REALTIME_ISLAND_ENTRY : join(root, file)],
       target: 'browser',
       format: 'esm',
       splitting: false,
@@ -96,7 +112,12 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // The dedupe goes FIRST: it answers `solid-js` specifiers before either plugin loads a file,
       // so the `solid-js/web` helpers the JSX transform writes into a symlinked package resolve
       // to the app's one copy. See `island-solid-dedupe.ts` for the measurement.
-      plugins: [solidDedupePlugin(root), solidJsxPlugin, islandStylesPlugin],
+      plugins: [
+        ...(realtime ? [islandRealtimePlugin(root, file)] : []),
+        solidDedupePlugin(root),
+        solidJsxPlugin,
+        islandStylesPlugin,
+      ],
       // The third one, and it is a `define` rather than the plugin this used to be: Bun selects
       // the `development`/`production` export condition from the BUILD PROCESS's own `NODE_ENV`,
       // and a defined `process.env.NODE_ENV` overrides it. Measured on 1.4.0, `solid-js` plus
@@ -138,9 +159,8 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
     // The FIRST bytes this process emitted for these inputs, so a URL served `immutable` answers
     // one byte string for as long as the process lives. Without it `x dev` re-mints the chunk on
     // every watcher tick and a browser holding the previous one under `max-age=31536000` has two
-    // different files at one address.
-    code: stableCode(file, hash, code),
-    bytes: new TextEncoder().encode(code).byteLength,
+    // different files at one address. `bytes` is measured on THAT code, never on this build's.
+    ...stableChunk(file, hash, code),
   };
 }
 
@@ -153,7 +173,7 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
  */
 const DEBUG_ID_COMMENT = '\n//# debugId=';
 
-function stripDebugId(code: string): string {
+export function stripDebugId(code: string): string {
   const at = code.lastIndexOf(DEBUG_ID_COMMENT);
   return at === -1 ? code : code.slice(0, at);
 }
@@ -185,7 +205,7 @@ function stripDebugId(code: string): string {
  * measured at 193,590 bytes against 131,649, +47% raw and +20% gzipped, on every island of every
  * app. Delete this the day `Bun.build` is deterministic.
  */
-function graphHash(file: string, map: string): string {
+export function graphHash(file: string, map: string): string {
   const parsed: unknown = JSON.parse(map);
   const contents = sourcesContentOf(parsed);
   if (contents === undefined) {
@@ -236,11 +256,18 @@ export function clearIslandChunkCache(): void {
  * value called `hash` is a digest an attacker may be probing. This one is a build input's
  * identity — the same reason `pr-threads.ts` calls a review state `wanted`.
  */
-function stableCode(file: string, graph: string, code: string): string {
+export function stableChunk(
+  file: string,
+  graph: string,
+  code: string,
+): { readonly code: string; readonly bytes: number } {
   const hit = emitted.get(file);
-  if (hit !== undefined && hit.graph === graph) return hit.code;
-  emitted.set(file, { graph, code });
-  return code;
+  const served = hit !== undefined && hit.graph === graph ? hit.code : code;
+  if (served === code) emitted.set(file, { graph, code });
+  // Measured on the code that is SERVED. It was measured on this build's output, which under a
+  // minifier that renames differently between builds is a second size for one URL in one process
+  // — and a budget weighed on bytes no browser receives.
+  return { code: served, bytes: new TextEncoder().encode(served).byteLength };
 }
 
 /**

package/src/island-capture.ts

@@ -5,10 +5,10 @@
 // why: no Bun native joins a path; `Bun.write` takes one already joined.
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
-import type { CaptureClip, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
-import { systemScrapeClock } from '@ultimat3/scraping';
 import type { IslandShotTarget, IslandViewport } from '@ultimat3/testing';
 import { islandStatesFile } from '@ultimat3/testing';
+import type { CaptureClip, ShotDriver, ShotSession } from './browser-launcher-port';
+import { systemShotClock } from './cdp-shot-clock';
 import { ISLAND_HARNESS_PATH } from './island-harness';
 import { readinessProbe } from './island-harness-script';
 import { IslandRequestUnstubbedError, IslandUnphotographableError } from './island-shot-errors';
@@ -43,7 +43,7 @@ export const ISLAND_CROP_MARGIN_PX = 8;
  * takes the viewport as a LAUNCH option (`LocalBrowserOptions.options`) and a state declares its
  * own — so "photograph this state at 480x320" is a different browser, not a different call.
  */
-export type IslandBrowser = (viewport: IslandViewport) => Promise<ScrapeDriver>;
+export type IslandBrowser = (viewport: IslandViewport) => Promise<ShotDriver>;
 
 interface Refusal {
   readonly reason: string;
@@ -181,13 +181,13 @@ export async function captureIslandState(
   floor: number,
 ): Promise<IslandStateShot> {
   const url = new URL(`${ISLAND_HARNESS_PATH}${target.query}`, server.url).toString();
-  let session: ScrapeSession | undefined;
+  let session: ShotSession | undefined;
   try {
     const driver = await options.driver(target.viewport);
     session = await driver.open({
       name: 'x shot --island',
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
-      clock: systemScrapeClock,
+      clock: systemShotClock,
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
@@ -237,7 +237,7 @@ export async function captureIslandState(
     // around, and which nothing passed until 2026-08-26 (issue #338).
     //
     // The clip ALONE. `fullPage: false` beside it is accepted — `assertCaptureFraming` refuses only
-    // `=== true`, and `cdp-target.ts` sends `{ clip }` and nothing else either way — but it is a
+    // `=== true`, and `cdp-shot-page.ts` sends `{ clip }` and nothing else either way — but it is a
     // field that says nothing: the two are exclusive, and spelling out the default of the one you
     // did not ask for reads as a choice.
     // `??` screens null and undefined and NOTHING else, so `cropMarginPx: NaN` reached `clipFor`,

package/src/island-harness-script.ts

@@ -147,12 +147,16 @@ Intl.DateTimeFormat=ShotDTF;
 
 /**
  * Ready is quiet, not idle. Fonts first — a picture taken mid-swap photographs the fallback face —
- * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled.
+ * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled, counted only
+ * once the island has MOUNTED or FAILED (#474): an `idle` island mounts in idle time, after frames
+ * that were quiet only because nothing had started yet. A page with no island host is not waited on.
  */
 const readyScript = (): string => `
 var last=-1;var still=0;
+function answered(){var h=document.querySelector("[data-x-island]");
+return !h||h.hasAttribute("data-x-mounted")||h.hasAttribute("data-x-failed")}
 function tick(){var seen=W.activity;
-if(seen===last)still+=1;else{still=0;last=seen}
+if(!answered()){still=0;last=seen}else if(seen===last)still+=1;else{still=0;last=seen}
 if(still>=${QUIET_FRAMES}){W.ready=true;return}
 requestAnimationFrame(tick)}
 (document.fonts?document.fonts.ready:Promise.resolve()).then(function(){requestAnimationFrame(tick)});

package/src/island-realtime.ts

@@ -0,0 +1,98 @@
+// Realtime installed for the author, on exactly the islands that use it: an island whose own import
+// graph reaches `@ultimat3/realtime` is built from a virtual entry that first calls
+// `installRealtime({ signal: createSignal })` with THIS bundle's solid-js, then re-exports the
+// island whole. Every other island is built from its own file and pays nothing (plan 101 slice 14).
+
+// why: Bun ships no path API; the entry is joined to the root and resolved from its directory.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { firstInGraph } from './live-routes';
+
+/** What `Bun.build` is handed for a realtime island; resolved by `islandRealtimePlugin`. */
+export const REALTIME_ISLAND_ENTRY = 'ultimate:island-entry';
+
+const REALTIME = '@ultimat3/realtime';
+const NAMESPACE = 'ultimate-island';
+const INSTALL = 'ultimate:island-realtime';
+const MODULE = 'ultimate:island-module';
+
+/**
+ * Whether the island's own graph value-imports realtime. Relative specifiers only, which is the
+ * one blind spot: a PACKAGE importing realtime for the island is not seen, and a hook it calls
+ * then throws `X_REALTIME_UNINSTALLED` by name — loud, never silent.
+ */
+export async function reachesRealtime(root: string, file: string): Promise<boolean> {
+  const found = await firstInGraph(root, file, (source, path) => {
+    // The transpiler, not a regex: it erases `import type` and reads a re-export as an import.
+    const scanned = new Bun.Transpiler({ loader: path.endsWith('x') ? 'tsx' : 'ts' }).scanImports(
+      source,
+    );
+    return scanned.some((entry) => entry.path === REALTIME) ? true : undefined;
+  });
+  // Recorded with the answer, so the document renderer can ask it of a page's islands without a
+  // second graph walk per request. Every build re-asks, so an edit that drops realtime drops it.
+  if (found === true) realtimeIslands.add(file);
+  else realtimeIslands.delete(file);
+  return found === true;
+}
+
+/** App-root-relative island files whose graph reaches realtime, as the last build answered. */
+const realtimeIslands = new Set<string>();
+
+/**
+ * The islands (app-root-relative POSIX paths) the last build found reaching realtime. A page needs
+ * realtime's page boot only if one of ITS islands does — `settings` paid 34.9 kB of boot script
+ * for an island that never touched a record.
+ */
+export function realtimeIslandFiles(): ReadonlySet<string> {
+  return realtimeIslands;
+}
+
+/**
+ * `export *` and never a named list: the hydration runtime reads `mount` off the module, and the
+ * wrapper must not decide which of an island's names survive. The install is imported FIRST, so it
+ * has run before the island's module body — and every hook the island calls — does.
+ */
+const ENTRY_SOURCE = `import '${INSTALL}';\nexport * from '${MODULE}';\n`;
+
+/**
+ * The install names `@ultimat3/realtime` BARE, and `islandRealtimePlugin` resolves it from the
+ * ISLAND's own directory — the resolution the island itself gets — so the bundle holds one copy
+ * and the signal lands where the hooks read it. Never the resolved absolute path spliced in: this
+ * source is part of the chunk's `sourcesContent`, which is what `graphHash` names the URL from, so
+ * a path in it gave the same island a different URL in every checkout and every image build.
+ * `solid-js` goes through `island-solid-dedupe.ts` like every other import in the graph.
+ */
+const INSTALL_SOURCE =
+  `import { installRealtime } from '${REALTIME}';\n` +
+  `import { createSignal } from 'solid-js';\n` +
+  `installRealtime({ signal: createSignal });\n`;
+
+export function islandRealtimePlugin(root: string, file: string): BunPlugin {
+  const island = join(root, file);
+  return {
+    name: 'ultimate-island-realtime',
+    setup(build) {
+      build.onResolve({ filter: /^ultimate:island-entry$/ }, () => ({
+        path: 'entry',
+        namespace: NAMESPACE,
+      }));
+      build.onResolve({ filter: /^ultimate:island-realtime$/ }, () => ({
+        path: 'install',
+        namespace: NAMESPACE,
+      }));
+      build.onResolve({ filter: /^ultimate:island-module$/ }, () => ({ path: island }));
+      // Every bare `@ultimat3/realtime` in this build, the virtual install's included — a virtual
+      // module has no directory to resolve from. The island's directory for all of them, which is
+      // what the island itself would get, and one copy in the bundle is the requirement anyway:
+      // the signal the install sets is only read by hooks from the same module instance.
+      build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({
+        path: Bun.resolveSync(REALTIME, dirname(island)),
+      }));
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
+        contents: args.path === 'entry' ? ENTRY_SOURCE : INSTALL_SOURCE,
+        loader: 'js',
+      }));
+    },
+  };
+}

package/src/island-shot.ts

@@ -8,6 +8,8 @@
 // and the index are written, and only then does the missing-picture gate turn the reasons into a
 // non-zero exit. One island that will not mount must not cost a reader the other nineteen.
 
+// why: Bun has no file delete that tolerates an absent file.
+import { rm } from 'node:fs/promises';
 // why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
@@ -95,6 +97,9 @@ export async function runIslandSweep(options: IslandSweepRun): Promise<IslandSwe
       // for each one it cannot, and the missing-shot gate below is what turns those reasons into
       // a non-zero exit.
       try {
+        // Deleted FIRST: the missing-shot gate reads the disk, and a picture an earlier run left
+        // there made a capture that failed today read as taken.
+        await rm(join(options.outDir, target.file), { force: true });
         shots.push(await captureIslandState(options, server, target, floor));
       } catch (error) {
         failures.push(error);

package/src/island-store.ts

@@ -0,0 +1,131 @@
+// The island chunks a container serves, built ONCE by `x build --target docker` into
+// `.x/islands/` and read back at boot. Without it every role's boot ran `Bun.build` — Babel, the
+// JSX transform, a minifier — for every island, in the image, on every start, and a chunk whose
+// URL is a hash of its sources was rebuilt from sources that could not have changed.
+//
+// Load-and-VERIFY, never load-and-trust: a store written by another framework or Bun version, one
+// that names a different set of islands than the app has, or a chunk whose bytes do not hash to
+// what the index recorded is refused, and the boot builds instead — with the reason logged.
+
+import { join } from 'node:path'; // why: Bun ships no path-join primitive.
+import { frameworkVersion, logger } from '@ultimat3/core';
+import { contentHash } from '@ultimat3/render/server';
+import type { IslandBundle, IslandChunk } from './island-bundle';
+import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
+
+/** App-root-relative: `COPY . .` carries it into the image with the rest of `.x/`. */
+export const ISLAND_STORE_DIR = '.x/islands';
+const INDEX = 'index.json';
+
+interface StoredChunk {
+  readonly file: string;
+  readonly moduleId: string;
+  readonly url: string;
+  readonly identity: string;
+}
+
+interface StoreIndex {
+  readonly framework: string;
+  readonly bun: string;
+  readonly chunks: readonly StoredChunk[];
+}
+
+const chunkFile = (url: string): string => url.slice(url.lastIndexOf('/') + 1);
+
+/** Writes every chunk and the index that verifies them. Answers the files written, app-relative. */
+export async function writeIslandStore(
+  root: string,
+  bundle: IslandBundle,
+): Promise<readonly string[]> {
+  const dir = join(root, ISLAND_STORE_DIR);
+  const chunks: StoredChunk[] = [];
+  const written: string[] = [];
+  for (const chunk of bundle.chunks) {
+    await Bun.write(join(dir, chunkFile(chunk.url)), chunk.code);
+    written.push(`${ISLAND_STORE_DIR}/${chunkFile(chunk.url)}`);
+    chunks.push({
+      file: chunk.file,
+      moduleId: chunk.moduleId,
+      url: chunk.url,
+      identity: contentHash(chunk.code),
+    });
+  }
+  const index: StoreIndex = { framework: frameworkVersion(), bun: Bun.version, chunks };
+  await Bun.write(join(dir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+  return [...written, `${ISLAND_STORE_DIR}/${INDEX}`];
+}
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+/** The index, narrowed field by field — a file on disk is input, never a trusted shape. */
+function parseIndex(value: unknown): StoreIndex | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  const chunks = record['chunks'];
+  if (!isString(record['framework']) || !isString(record['bun']) || !Array.isArray(chunks)) {
+    return undefined;
+  }
+  const parsed: StoredChunk[] = [];
+  for (const entry of chunks) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    const chunk = entry as Record<string, unknown>;
+    const { file, moduleId, url, identity } = chunk;
+    if (!isString(file) || !isString(moduleId) || !isString(url) || !isString(identity))
+      return undefined;
+    parsed.push({ file, moduleId, url, identity });
+  }
+  return { framework: record['framework'], bun: record['bun'], chunks: parsed };
+}
+
+/** A verified store, or the one sentence saying why it cannot be served. */
+export type StoreRead =
+  | { readonly bundle: IslandBundle; readonly stale?: undefined }
+  | { readonly bundle?: undefined; readonly stale: string };
+
+export async function readIslandStore(root: string): Promise<StoreRead> {
+  const dir = join(root, ISLAND_STORE_DIR);
+  const file = Bun.file(join(dir, INDEX));
+  if (!(await file.exists())) return { stale: `no ${ISLAND_STORE_DIR}/${INDEX}` };
+  const index = parseIndex(await file.json().catch(() => undefined));
+  if (index === undefined) return { stale: `${ISLAND_STORE_DIR}/${INDEX} does not parse` };
+  if (index.framework !== frameworkVersion() || index.bun !== Bun.version) {
+    return {
+      stale: `built by framework ${index.framework} on Bun ${index.bun}, serving ${frameworkVersion()} on Bun ${Bun.version}`,
+    };
+  }
+  const stored = index.chunks.map((chunk) => chunk.file).sort();
+  const present = [...(await discoverIslands(root))];
+  if (stored.join('\n') !== present.join('\n')) {
+    return { stale: 'the stored islands are not the islands this app has' };
+  }
+  const chunks: IslandChunk[] = [];
+  for (const entry of index.chunks) {
+    const bytes = Bun.file(join(dir, chunkFile(entry.url)));
+    const code = (await bytes.exists()) ? await bytes.text() : undefined;
+    if (code === undefined || contentHash(code) !== entry.identity) {
+      return { stale: `${entry.url} is missing or does not match its recorded hash` };
+    }
+    chunks.push({
+      file: entry.file,
+      moduleId: entry.moduleId,
+      url: entry.url,
+      code,
+      bytes: new TextEncoder().encode(code).byteLength,
+    });
+  }
+  return { bundle: islandBundle(chunks) };
+}
+
+/**
+ * The container's islands: the verified store, or a build when there is none to trust. A build is
+ * correct and only slower, so a stale store is a warning with its reason, never a refusal.
+ */
+export async function loadOrBuildIslands(root: string): Promise<IslandBundle> {
+  const read = await readIslandStore(root);
+  if (read.bundle !== undefined) return read.bundle;
+  logger.warn('islands built at boot', {
+    reason: read.stale,
+    fix: 'x build --target docker',
+  });
+  return buildIslands(root);
+}

package/src/island-verdict.ts

@@ -5,8 +5,8 @@
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { t, validate } from '@ultimat3/schema';
-import type { ConsoleLine, PageError } from '@ultimat3/scraping';
 import type { IslandShotTarget } from '@ultimat3/testing';
+import type { ConsoleLine, PageError } from './browser-launcher-port';
 import { msg } from './messages';
 import type { JsonValue } from './output';
 
@@ -57,7 +57,7 @@ export interface IslandReadiness {
   /**
    * `"WS <url>"` / `"SSE <url>"` for every socket a component constructed — recorded, never
    * gating. The harness's stand-in is inert (constructs, never opens, `close()` is a no-op), so
-   * a component dialing `@ultimat3/realtime`'s `LiveClient.connect()` does not fail the state it
+   * a component whose page socket dials `/_x/sync` (`@ultimat3/realtime`) does not fail the state it
    * is mounted in; this is the fact a picture cannot carry about that.
    */
   readonly sockets: readonly string[];

package/src/job-registration.ts

@@ -0,0 +1,42 @@
+// The `manifest` step's job half: a job or a task still carrying the positional name `job()` or
+// `task()` minted (`anonymous-job-2`) was never handed to `defineApi`. That name is what the queue
+// row, `x.manifest.json`, `x jobs show` and every dead-letter trace carry, and it moves whenever the
+// import order does — so a retry scheduled under one deploy's name lands on another deploy's job.
+
+import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
+import type { AppLoader } from './app-permissions';
+import type { Finding } from './output';
+
+/** What `job()` and `task()` name a declaration nobody named (`packages/jobs/src/job.ts`). */
+const POSITIONAL = /^anonymous-(job|task)-\d+$/;
+
+/** Every registered job and task still under its positional name. */
+export function positionalNames(
+  names: readonly string[] = [...registeredJobs(), ...registeredTasks()].map((one) => one.name),
+): readonly string[] {
+  return names.filter((name) => POSITIONAL.test(name)).sort();
+}
+
+export function unregisteredJobFinding(name: string): Finding {
+  const kind = name.startsWith('anonymous-task-') ? 'tasks' : 'jobs';
+  return {
+    code: 'X_JOB_UNREGISTERED',
+    cause: `${name} is a ${kind === 'tasks' ? 'task' : 'job'} no defineApi() call names, so it carries the positional name ${kind === 'tasks' ? 'task()' : 'job()'} minted — on the queue row, in the manifest and in every dead-letter trace, and it moves when the import order does`,
+    fix: `add import * as <module> from its file and <module> to ${kind}: [...] in apps/web/api/index.ts, then x manifest`,
+    at: 'apps/web/api/index.ts',
+  };
+}
+
+/**
+ * The step's answer. Loads the app the way every other gate step does — the registries are only
+ * whole after the scan — and says nothing when the load failed: a short registry is the load's
+ * finding, reported by the step that loaded it.
+ */
+export async function unregisteredJobFindings(
+  root: string,
+  load: AppLoader = loadApp,
+): Promise<readonly Finding[]> {
+  if ((await load(root)).findings.length > 0) return [];
+  return positionalNames().map(unregisteredJobFinding);
+}

package/src/jobs-driver.ts

@@ -5,9 +5,9 @@
 import type { JobDriver } from '@ultimat3/jobs';
 import { jobDriver } from '@ultimat3/jobs';
 import type { CommandContext } from './command';
-import { startQueue } from './dev-queue';
-import { resolveServices } from './dev-services';
 import type { CommandResult } from './output';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
 
 /**
  * `x jobs` needs the app's real driver. Reuse an already-running one first — inside `x dev` or