@ultimat3/cli 21.0.0 → 22.1.0

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';
 

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

package/src/load-findings.ts

@@ -0,0 +1,51 @@
+// One cause, one step. A module that will not import was reported by up to four steps at once —
+// `contract-diff`, `budgets`, `policy` and `manifest` all load the app, and each carried the load's
+// findings — so one syntax error read as four red steps and four copies of one line (plan 101
+// slice 11 i). The `manifest` step owns them: it runs in every repo, and "does the projection
+// describe the code?" is the question a module that will not import answers first.
+
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import type { StepOutcome, VerifyStepName } from './verify-step';
+
+/** The step that reports the app's load failures. Every other step points at it. */
+export const LOAD_OWNER: VerifyStepName = 'manifest';
+
+/** What the app load reports, as the step sees it. */
+export type LoadProbe = (root: string) => Promise<{ readonly findings: readonly Finding[] }>;
+
+const keyOf = (finding: Finding): string =>
+  [finding.code, finding.at ?? '', finding.cause].join('\u0000');
+
+/**
+ * `findings` without the ones the app load raised, and an `output` line saying where they went.
+ * The step's own verdict stands on what is left: a budget the broken module left unmeasured is
+ * still this step's finding, only its cause moved.
+ */
+export async function withoutLoadFindings(
+  root: string,
+  findings: readonly Finding[],
+  load: LoadProbe = loadApp,
+): Promise<StepOutcome> {
+  const loaded = new Set((await load(root)).findings.map(keyOf));
+  const kept = findings.filter((finding) => !loaded.has(keyOf(finding)));
+  const moved = findings.length - kept.length;
+  return {
+    ok: kept.length === 0,
+    findings: kept,
+    ...(moved === 0
+      ? {}
+      : { output: `skipped: ${moved} module-load finding(s) — see ${LOAD_OWNER}` }),
+  };
+}
+
+/** The owner's half: every load finding exactly once, beside what the step found itself. */
+export async function withLoadFindings(
+  root: string,
+  findings: readonly Finding[],
+  load: LoadProbe = loadApp,
+): Promise<readonly Finding[]> {
+  const own = (await load(root)).findings;
+  const seen = new Set(own.map(keyOf));
+  return [...own, ...findings.filter((finding) => !seen.has(keyOf(finding)))];
+}

package/src/mcp-db-target.ts

@@ -10,7 +10,7 @@ import { tryResolveEnvironment } from '@ultimat3/core';
 import { pgliteDataDir } from '@ultimat3/db';
 import type { DatabaseTarget } from '@ultimat3/mcp';
 import { branchNameOf, pgliteBranchName } from './db-branch';
-import type { DevServices, Env } from './dev-services';
+import type { DevServices, Env } from './runtime-bindings';
 import { safeUrlLabel } from './safe-url-label';
 
 /**

package/src/mcp-errors.ts

@@ -54,7 +54,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # the package-shape finding carries the dependency line to add',
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
-  X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  X_SHOT_BROWSER_MISSING: 'export CHROME_PATH=/usr/bin/google-chrome',
   X_UI_SHOT_ROUTE_UNKNOWN:
     'x routes --json   # then call the ui.* tool with one of its path values',
   X_UI_SHOT_ROUTE_UNBUDGETED:
@@ -69,6 +69,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x routes --json   # then resend ui.interact with steps that stay on one of its paths',
   X_UI_INTERACT_STEP_FAILED:
     'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_HOST_REFUSED: 'x shot /route --allow-hosts cdn.example.com --json',
+  X_SHOT_ELEMENT_MISSING:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_ELEMENT_UNREADY:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_KEY_INVALID: 'x help shot --json   # a chord is modifiers then one key: Meta+K',
   // The three `ui.diff` codes. Every capture it can compare was written by `x shot` or a `ui.*`
   // tool under `.x/shot/`, so the runnable half is the command that writes one there.
   X_UI_DIFF_PATH_OUTSIDE:
@@ -88,30 +94,6 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x help shot --json   # the cause lists every request the state must answer under routes',
   X_SHOT_ISLAND_MISSING:
     'x help shot --json   # every absent picture carries its own named refusal in the run above',
-  // The six e2e-driver codes. Every one of them is raised inside a running suite, so the runnable
-  // half is the command that re-runs that suite — the cause already names the closure, the locator
-  // call or the budget, and no `x` command can edit a test for its author.
-  X_E2E_EVALUATE_UNSUPPORTED:
-    'x test e2e --json   # the cause quotes the closure; page.evaluate takes a zero-parameter arrow',
-  X_E2E_EVALUATE_CAPTURED:
-    'x test e2e --json   # the fix line names the binding to inline into the closure',
-  X_E2E_EVALUATE_THREW:
-    'x dev --json   # then run the expression the cause quotes in the browser console; the throw is the page\u2019s',
-  X_E2E_LOCATOR_EMPTY:
-    'x test e2e --json   # the fix line carries the toBeVisible() assertion to await first',
-  X_E2E_LOCATOR_AMBIGUOUS:
-    'x test e2e --json   # the fix line carries the same call with .first() on it',
-  X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
-  X_E2E_APP_FAILED: 'x dev --json',
-  // The four raw-CDP codes. `x doctor` for the missing browser, because that is the command whose
-  // whole job is reporting what this machine does not have; the other three are raised inside a
-  // running suite, so the runnable half is the command that re-runs it.
-  X_CDP_BROWSER_MISSING:
-    'x doctor --json   # or set CHROME_PATH to a Chrome binary; unset, the browser-backed suite skips',
-  X_CDP_LAUNCH_FAILED:
-    'x test e2e --json   # the cause carries the last lines of the browser\u2019s own stderr',
-  X_CDP_CALL_FAILED: 'x test e2e --json   # the cause names the DevTools call the browser refused',
-  X_CDP_TIMEOUT: 'x test e2e --json   # the cause names the call that never answered',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
@@ -126,7 +108,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_ERROR_CODE_UNTHROWN:
     'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
   X_CLI_UNEXPECTED: 'x doctor --json',
-  X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
+  // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
+  X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',
   X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
   // The same two edits `vanishedSuiteFinding` names, verbatim, so both surfaces of this code hand
@@ -182,6 +165,10 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PORT_INVALID: 'docker run -e PORT=3000 my-app:latest',
   X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
   X_GENERATE_CONFLICT: 'x g route posts --force --json',
+  X_APP_NAME_EMPTY:
+    'x new my-app --json   # a name with letters or digits; it becomes the directory',
+  X_APP_EMPTY:
+    'x doctor --json   # then check the app root: no module under apps/ or packages/ loaded',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   X_DEV_ALREADY_RUNNING:
     'x dev --json   # after stopping the x dev that already owns this checkout',
@@ -221,8 +208,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // consent and stays in the cause: it is the answer only for a container with a fixed argv.
   X_SEED_ENVIRONMENT:
     'x db seed --dry-run --json   # then name the tier: x db seed <name> --tier dev --json',
+  // The finding's own `fix:` is the concrete edit (`boundary-findings.ts`): the file and the import.
   X_BOUNDARY_SITE_TO_APP:
-    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+    'x verify --only boundaries --json   # each finding names the import to delete, and where',
   X_BOUNDARY_SHARED_LEAF:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_APP_TO_API:
@@ -231,6 +219,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_SERVICE_TO_HTTP:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SURFACE_IMPORT:
+    'x verify --only boundaries --json   # then move the imported code into shared/',
   // The app's own guards. All three are reported by the gate and by nothing else, so the runnable
   // half is the gate — the narrowing behind the `#` is the edit, because only the finding knows
   // which file in `guards/` is the one to open.
@@ -245,6 +235,17 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
   // resolved to, and `x g island` is what puts that file where the page already says it is.
   X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
+  // The four slice-11 codes: generated code that passed the gate and failed at runtime.
+  X_PERMISSION_UNGRANTED:
+    'x verify --only policy --json   # then add the permission to a role in apps/web/shared/roles.ts',
+  X_JOB_UNREGISTERED:
+    'x manifest --json   # after listing the module under jobs: [...] in apps/web/api/index.ts',
+  X_FEATURE_UNKNOWN:
+    'x entities --json   # then x g resource <feature> for the one the cause names',
+  X_BUDGET_PARAMS_UNDECLARED:
+    'x build --target static --json   # after adding prerender() with one real path to the route',
+  X_ROUTE_ASYNC_PAGE:
+    'x verify --only budgets --json   # after moving each await in Page into export const load',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -34,12 +34,8 @@ import { loadApp } from './app-load';
 import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
 import { declareDevEnvironment } from './dev-environment';
-import type { RunningServices } from './dev-runtime';
-import { startServices } from './dev-runtime';
-import type { DevServices, Env } from './dev-services';
-import { resolveServices } from './dev-services';
 import { loadCodeFixes } from './error-fixes';
-import { CliNotImplementedError } from './errors';
+import { BadFlagError, CliNotImplementedError } from './errors';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
@@ -48,6 +44,10 @@ import { parseBunTest } from './mcp-test-output';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import type { DevServices, Env } from './runtime-bindings';
+import { resolveServices } from './runtime-bindings';
+import type { RunningServices } from './runtime-services';
+import { startServices } from './runtime-services';
 import { testEnvOverrides } from './test-dotenv';
 
 export interface DevHostInput {
@@ -180,6 +180,24 @@ export async function readOnlyRows(
   return { columns, rows: kept.map((row) => columns.map((column) => row[column])), guards };
 }
 
+/**
+ * `bun test`'s argv for a `test.run` filter. A filter is a PATH, and one starting with `-` is a
+ * `bun test` flag — `--preload ./x.ts` loads a module into the child — so it is refused rather
+ * than forwarded: a filter is a path, and no path this suite has starts with `-`.
+ */
+export function testRunArgv(filter: string | undefined): readonly string[] {
+  if (filter === undefined) return ['bun', 'test'];
+  if (filter.trimStart().startsWith('-')) {
+    throw new BadFlagError({
+      flag: 'filter',
+      command: 'mcp serve',
+      reason: `test.run's filter "${filter}" starts with "-", which bun test would read as its own flag`,
+      fix: 'call test.run with a path filter such as packages/cli/src, or with no filter',
+    });
+  }
+  return ['bun', 'test', filter];
+}
+
 function capabilities(
   input: DevHostInput,
   lazy: LazyServices,
@@ -249,13 +267,10 @@ function capabilities(
       // Same leak the CLI's own `x test`/`x verify` had: `.env.development` auto-loaded into
       // THIS process must not ride along into the `bun test` child the dev MCP server spawns.
       const envOverrides = testEnvOverrides(root, env);
-      const result = await runner(
-        filter === undefined ? ['bun', 'test'] : ['bun', 'test', filter],
-        {
-          cwd: root,
-          ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
-        },
-      );
+      const result = await runner(testRunArgv(filter), {
+        cwd: root,
+        ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+      });
       return parseBunTest(execOutput(result), result.durationMs);
     },
 

package/src/mcp-ui-diff.ts

@@ -81,6 +81,32 @@ async function readCapture(root: string, relative: string, field: string): Promi
   return file.bytes();
 }
 
+/**
+ * The symlink half for the one path this tool WRITES: `realpath` of the nearest directory that
+ * exists above `out`, held under the shot directory's real location — `readCapture`'s rule. The
+ * lexical check alone let `.x/shot/<link-to-elsewhere>/diff.png` write wherever the link pointed.
+ */
+async function assertWritable(root: string, path: string): Promise<void> {
+  let dir = dirname(path);
+  while (!(await exists(dir)) && dirname(dir) !== dir) dir = dirname(dir);
+  const real = await realpath(dir);
+  const shotDir = await realpath(resolve(root, SHOT_DIR));
+  if (!under(real, shotDir)) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_PATH_OUTSIDE',
+      cause: `out is under a link to ${real}, which is not inside ${shotDir}`,
+      fix: SHOT_FIX,
+      meta: { field: 'out', path, real, shotDir },
+    });
+  }
+}
+
+const exists = (dir: string): Promise<boolean> =>
+  realpath(dir).then(
+    () => true,
+    () => false,
+  );
+
 /**
  * The seam reads 8-bit RGBA and nothing else. A PNG in any other shape — Chrome's RGB when the page
  * is opaque, a palette from an optimiser — goes once through Bun's codecs, which always write the
@@ -126,6 +152,7 @@ export async function diffShots(deps: DiffDeps, input: UiDiffInput): Promise<UiD
   }
   const { width, height } = after;
   const result = diffPixels(before.pixels, after.pixels, width, height, input.threshold);
+  await assertWritable(root, diff);
   await Bun.write(diff, encodeImage({ width, height, pixels: result.diffRgba }));
   return {
     ok: true,

package/src/mcp-ui-inspect.ts

@@ -11,8 +11,8 @@
 import { join } from 'node:path';
 import type { UiInspectInput, UiInspectResult, UiInspectSelector } from '@ultimat3/mcp';
 import { UI_INSPECT_LIMITS } from '@ultimat3/mcp';
-import type { AxNode, ScrapeDriver, ScrapePage } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import type { AxNode, ShotDriver, ShotPage } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
 import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { ShotServer } from './shot-server';
 import type { ShotVerdict } from './shot-verdict';
@@ -23,7 +23,7 @@ export interface InspectDeps {
   readonly root: string;
   /** The memoised scratch server (or the running `x dev`), as `uiCapabilities` hands it out. */
   readonly boot: () => Promise<ShotServer>;
-  readonly driver: (viewport: UiInspectInput['viewport']) => Promise<ScrapeDriver>;
+  readonly driver: (viewport: UiInspectInput['viewport']) => Promise<ShotDriver>;
 }
 
 /** What the page answered before the parser had a say — `null` selectors when it answered nothing. */
@@ -45,7 +45,7 @@ export type InspectSpecInput = Pick<
  * a page that refuses evaluation is a page with no facts, and the verdict — not a throw here — is
  * what says why. Shared by `ui.inspect` and `ui.interact`, so both read the same facts.
  */
-export async function readInspect(page: ScrapePage, spec: InspectSpecInput): Promise<Seen> {
+export async function readInspect(page: ShotPage, spec: InspectSpecInput): Promise<Seen> {
   const expression = inspectExpression({
     selectors: spec.selectors,
     styles: spec.styles,

package/src/mcp-ui-interact.ts

@@ -14,8 +14,8 @@ import { join } from 'node:path';
 import { isUltimateError, toUltimateError, UltimateError } from '@ultimat3/core';
 import type { UiInteractInput, UiInteractResult, UiInteractStepResult } from '@ultimat3/mcp';
 import { UI_INTERACT_LIMITS } from '@ultimat3/mcp';
-import type { ScrapePage } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import type { ShotPage } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
 import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { InspectDeps, Seen } from './mcp-ui-inspect';
 import { readInspect, selectorsOf } from './mcp-ui-inspect';
@@ -130,7 +130,7 @@ const describe = (step: InteractStep): string => {
 };
 
 async function perform(
-  page: ScrapePage,
+  page: ShotPage,
   step: InteractStep,
   sleep: (ms: number) => Promise<void>,
 ): Promise<void> {
@@ -153,19 +153,25 @@ async function perform(
  * Before any keystroke: a password field's value would land in the PNG, the verdict's console and
  * an agent's transcript. The read is the driver's own `query`, so the fake answers it offline.
  */
-async function refuseSecretField(
-  page: ScrapePage,
-  step: InteractStep,
-  index: number,
-): Promise<void> {
-  if (step.kind !== 'type') return;
-  const [first] = await page.query(step.selector);
-  if (first?.attrs['type'] !== 'password') return;
+/** The `type` of the focused element — what a `press` step's key lands in. */
+export const ACTIVE_FIELD_TYPE =
+  '(function(){var a=document.activeElement;return a&&a.getAttribute?a.getAttribute("type"):null})()';
+
+async function refuseSecretField(page: ShotPage, step: InteractStep, index: number): Promise<void> {
+  if (step.kind !== 'type' && step.kind !== 'press') return;
+  // A `press` goes to whatever has focus: `focus` a password field, then eleven presses, typed
+  // the password the `type` guard refused — so the focused element is asked before each key.
+  const secret =
+    step.kind === 'type'
+      ? (await page.query(step.selector))[0]?.attrs['type'] === 'password'
+      : (await page.evaluate(ACTIVE_FIELD_TYPE)) === 'password';
+  if (!secret) return;
+  const target = step.kind === 'type' ? JSON.stringify(step.selector) : 'the focused element';
   throw new UltimateError({
     code: 'X_UI_INTERACT_SECRET_FIELD',
-    cause: `step ${index} would type into ${JSON.stringify(step.selector)}, an <input type="password">`,
+    cause: `step ${index} would type into ${target}, an <input type="password">`,
     fix: FIX.secret,
-    meta: { step: index, selector: step.selector },
+    meta: { step: index, ...(step.kind === 'type' ? { selector: step.selector } : {}) },
   });
 }
 
@@ -177,11 +183,11 @@ export interface StepsRun {
 
 /**
  * The steps in order, each followed by a settle and one poll interval, each checked against the
- * origin. A scraping error is wrapped, never passed through: the agent needs to know WHICH step,
+ * origin. A driver error is wrapped, never passed through: the agent needs to know WHICH step,
  * and the fix is a selector `ui.inspect` reports rather than whatever the driver's fix names.
  */
 export async function runSteps(
-  page: ScrapePage,
+  page: ShotPage,
   steps: readonly InteractStep[],
   settle: () => Promise<IslandCount | null>,
   origin: string,