@ultimat3/cli 20.1.2 → 20.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.1.2",
+  "version": "20.1.3",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "20.1.2",
-    "@ultimat3/admin": "20.1.2",
-    "@ultimat3/ai": "20.1.2",
-    "@ultimat3/auth": "20.1.2",
-    "@ultimat3/cache": "20.1.2",
-    "@ultimat3/core": "20.1.2",
-    "@ultimat3/db": "20.1.2",
-    "@ultimat3/entity": "20.1.2",
-    "@ultimat3/flags": "20.1.2",
-    "@ultimat3/http": "20.1.2",
-    "@ultimat3/i18n": "20.1.2",
-    "@ultimat3/jobs": "20.1.2",
-    "@ultimat3/mail": "20.1.2",
-    "@ultimat3/manifest": "20.1.2",
-    "@ultimat3/mcp": "20.1.2",
-    "@ultimat3/money": "20.1.2",
-    "@ultimat3/notify": "20.1.2",
-    "@ultimat3/policy": "20.1.2",
-    "@ultimat3/pwa": "20.1.2",
-    "@ultimat3/query": "20.1.2",
-    "@ultimat3/realtime": "20.1.2",
-    "@ultimat3/render": "20.1.2",
-    "@ultimat3/schema": "20.1.2",
-    "@ultimat3/scraping": "20.1.2",
-    "@ultimat3/seo": "20.1.2",
-    "@ultimat3/storage": "20.1.2",
-    "@ultimat3/testing": "20.1.2",
-    "@ultimat3/time": "20.1.2",
+    "@ultimat3/action": "20.1.3",
+    "@ultimat3/admin": "20.1.3",
+    "@ultimat3/ai": "20.1.3",
+    "@ultimat3/auth": "20.1.3",
+    "@ultimat3/cache": "20.1.3",
+    "@ultimat3/core": "20.1.3",
+    "@ultimat3/db": "20.1.3",
+    "@ultimat3/entity": "20.1.3",
+    "@ultimat3/flags": "20.1.3",
+    "@ultimat3/http": "20.1.3",
+    "@ultimat3/i18n": "20.1.3",
+    "@ultimat3/jobs": "20.1.3",
+    "@ultimat3/mail": "20.1.3",
+    "@ultimat3/manifest": "20.1.3",
+    "@ultimat3/mcp": "20.1.3",
+    "@ultimat3/money": "20.1.3",
+    "@ultimat3/notify": "20.1.3",
+    "@ultimat3/policy": "20.1.3",
+    "@ultimat3/pwa": "20.1.3",
+    "@ultimat3/query": "20.1.3",
+    "@ultimat3/realtime": "20.1.3",
+    "@ultimat3/render": "20.1.3",
+    "@ultimat3/schema": "20.1.3",
+    "@ultimat3/scraping": "20.1.3",
+    "@ultimat3/seo": "20.1.3",
+    "@ultimat3/storage": "20.1.3",
+    "@ultimat3/testing": "20.1.3",
+    "@ultimat3/time": "20.1.3",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/browser-launcher.ts

@@ -13,7 +13,7 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
-import { CHROME_CANDIDATES } from './cdp-launch';
+import { CHROME_CANDIDATES, CONTAINER_CHROME_ARGS } from './cdp-launch';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -231,8 +231,15 @@ export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriv
     ...(options.executablePath === undefined ? {} : { executablePath: options.executablePath }),
     // `LocalBrowserOptions.options` is passed through to `launch()` untouched, which is the seam
     // that lets the CLI size a browser without `@ultimat3/scraping` naming a puppeteer type.
-    ...(options.viewport === undefined
-      ? {}
-      : { options: { defaultViewport: { ...options.viewport } } }),
+    //
+    // `args` carries `CONTAINER_CHROME_ARGS` on EVERY local launch, viewport or not — the same
+    // `--no-sandbox` / `--disable-dev-shm-usage` `cdp-launch.ts`'s e2e driver already needed for
+    // this container, read from the one export rather than restated. Before this, `x shot` was the
+    // only browser-launching command in the tree with neither, so a box where the e2e gate ran
+    // green could not run `x shot` at all — Chrome exits "No usable sandbox".
+    options: {
+      args: [...CONTAINER_CHROME_ARGS],
+      ...(options.viewport === undefined ? {} : { defaultViewport: { ...options.viewport } }),
+    },
   });
 }

package/src/cdp-launch.ts

@@ -36,6 +36,19 @@ export async function findChrome(
   return undefined;
 }
 
+/**
+ * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
+ * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
+ * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
+ * a default container, which crashes the renderer on any real page.
+ *
+ * Exported so `browser-launcher.ts`'s `appBrowser` — a DIFFERENT launch path, `puppeteer-core`'s
+ * own `launch()` rather than the `Bun.spawn` below — passes the SAME two, rather than a second
+ * list that agrees today and drifts the next time either changes. `x shot` had neither before this
+ * export existed, so a box where `x verify`'s e2e gate ran green could not run `x shot` at all.
+ */
+export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
+
 /**
  * The flags, and every one of them earns its line.
  *
@@ -43,16 +56,12 @@ export async function findChrome(
  * asks the OS for a free port, so two suites on one machine never collide — the port is read back
  * off stderr, which is the only place Chrome states the one it took. A throwaway `--user-data-dir`
  * because a run sharing a profile with a real browser inherits its cookies and locks its files.
- * `--no-sandbox` and `--disable-dev-shm-usage` are the two a container needs: the sandbox needs
- * privileges CI does not grant, and `/dev/shm` is 64 MB in a default container, which crashes the
- * renderer on any real page.
  */
 const flags = (profileDir: string): readonly string[] => [
   '--headless=new',
   '--remote-debugging-port=0',
   `--user-data-dir=${profileDir}`,
-  '--no-sandbox',
-  '--disable-dev-shm-usage',
+  ...CONTAINER_CHROME_ARGS,
   '--disable-gpu',
   // Nothing here should reach the network on its own account, and a first-run bubble or an update
   // check is a page load the test did not ask for.

package/src/cmd-dev.ts

@@ -24,6 +24,7 @@ import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { declareDevEnvironment } from './dev-environment';
 import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
@@ -374,6 +375,9 @@ export const devCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('dev', ctx.cwd).dir;
+    // BEFORE `startDev` imports a single app module — see `dev-environment.ts` for why this must
+    // run this early, and why it mutates the real `process.env` rather than `startDev`'s `env`.
+    declareDevEnvironment(ctx.env);
     // Validated, not `parseInt`'d: `x dev --port abc` handed `NaN` to `Bun.serve`, which binds an
     // arbitrary port — a dev server reachable at an address nothing printed.
     const port = intFlagOr(

package/src/cmd-generate.ts

@@ -72,12 +72,19 @@ export const generateCommand: CliCommand = {
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
-    const sliceErrors = await readSliceErrors(root, kind, sliceDir(surface, featureFlag ?? name));
+    const slice = sliceDir(surface, featureFlag ?? name);
+    const sliceErrors = await readSliceErrors(root, kind, slice);
+    // Same reason again: whether `job`/`task` may assume the tenant-scoped shape is a fact about
+    // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
+    const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
+    const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
     const files = generate({
       kind,
       name,
       ...(featureFlag === undefined ? {} : { feature: featureFlag }),
       ...(sliceErrors === undefined ? {} : { sliceErrors }),
+      ...(sliceEntity === undefined ? {} : { sliceEntity }),
+      ...(sliceRepo === undefined ? {} : { sliceRepo }),
       ...(at === undefined ? {} : { at }),
       ...(permission === undefined ? {} : { permission }),
       surface,
@@ -157,3 +164,19 @@ async function readSliceErrors(
   const file = containedPath(root, `${slice}/errors.ts`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
+
+/**
+ * `job` and `task` only: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
+ * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
+ * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
+ */
+async function readSliceFile(
+  root: string,
+  kind: Generator,
+  slice: string,
+  name: 'entity.ts' | 'repo.ts',
+): Promise<string | undefined> {
+  if (kind !== 'job' && kind !== 'task') return undefined;
+  const file = containedPath(root, `${slice}/${name}`);
+  return existsSync(file) ? await Bun.file(file).text() : undefined;
+}

package/src/cmd-test.ts

@@ -197,6 +197,7 @@ export const testCommand: CliCommand = {
     const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
+      env: ctx.env,
       files,
       workers,
       ...(only === undefined ? {} : { only }),

package/src/cmd-verify.ts

@@ -59,6 +59,7 @@ export const verifyCommand: CliCommand = {
     return runVerify(VERIFY_STEPS, {
       root,
       runner: ctx.runner,
+      env: ctx.env,
       ...(workers === undefined ? {} : { workers }),
       ...(only === undefined ? {} : { only }),
     });

package/src/dev-environment.ts

@@ -0,0 +1,42 @@
+// Single responsibility: whether `x dev` must declare `ULTIMATE_ENV` for the app it is about to
+// boot, and the one-liner side effect that declares it. Split out of `cmd-dev.ts` (which the
+// filesize gate holds to ~500 lines) rather than folded into it — this is one decision with one
+// consumer, and keeping it separate is what lets a test pin the decision without paying for a
+// whole app boot.
+
+import { ENVIRONMENT_KEY } from '@ultimat3/core';
+
+/**
+ * Whether `x dev` must declare `ULTIMATE_ENV` for the app it is about to boot: true only when
+ * NEITHER key `@ultimat3/core`'s `resolveEnvironment` reads is set to a real value. Empty-string
+ * matches that reader's own rule (`packages/core/src/environment.ts`'s `readEnvironment`):
+ * `ULTIMATE_ENV=''` is treated as unset, so "already set" here means non-empty, exactly as there.
+ *
+ * `NODE_ENV=ci` (or any other non-`Environment` value) counts as "already set" and is left alone
+ * even though `resolveEnvironment` would still fall through it to `DEFAULT_ENVIRONMENT` — an
+ * operator who set SOMETHING gets no override from this process, only a process that named
+ * NEITHER key does.
+ */
+export function needsDevEnvironmentDeclaration(
+  env: Readonly<Record<string, string | undefined>>,
+): boolean {
+  const declared = env[ENVIRONMENT_KEY];
+  const nodeEnv = env['NODE_ENV'];
+  return (declared === undefined || declared === '') && (nodeEnv === undefined || nodeEnv === '');
+}
+
+/**
+ * The one-liner side effect, split from the decision so a test can pin either without paying for
+ * a whole app boot: `process.env[ENVIRONMENT_KEY] = 'development'`, and only when
+ * `needsDevEnvironmentDeclaration` says neither key was set.
+ *
+ * Mutates the real `process.env`, not a copy: `cmd-dev.ts`'s `run` passes `ctx.env`, which IS
+ * `Bun.env` (probed on 1.4.2 — `Bun.env === process.env`), and it is `process.env` that
+ * `resolveEnvironment`'s default reader (no explicit `env` passed) and every app module loaded
+ * in-process actually consult. The call has to land before `startDev` imports a single app
+ * module — see `cmd-dev.ts`'s `run` for why that means the top of the command, not inside
+ * `startDev` itself, which stays a pure function of the `env` it is handed.
+ */
+export function declareDevEnvironment(env: Readonly<Record<string, string | undefined>>): void {
+  if (needsDevEnvironmentDeclaration(env)) process.env[ENVIRONMENT_KEY] = 'development';
+}

package/src/exec.ts

@@ -21,7 +21,16 @@ export interface ExecResult {
 
 export interface ExecOptions {
   readonly cwd: string;
-  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Overlaid onto `Bun.env`, key by key: a string sets/overrides it for the child, and
+   * `undefined` UNSETS it — the child does not inherit it at all, even though the parent has it.
+   * The delete case exists for one caller (`test-dotenv.ts`'s `testEnvOverrides`, spent by
+   * `test-shards.ts`/`verify-tests.ts`/`verify-test-run.ts`/`mcp-host.ts`): a `bun test` child
+   * must not inherit a key that reached the parent only through Bun auto-loading
+   * `.env.development`. A merge that only ever adds or overrides (`{ ...Bun.env, ...env }`) cannot
+   * express that — `Bun.env` is always the base, so a key just absent from `env` survives from it.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
   readonly stdin?: string;
 }
 
@@ -48,12 +57,34 @@ const now = (): number => performance.now();
  *
  * The return type is inferred so this stays one statement of `Bun.spawn`'s own shape.
  */
+/**
+ * `Bun.env` overlaid with `overrides`, an `undefined` value deleting the key rather than setting
+ * it to the string `"undefined"` — see `ExecOptions.env`'s own comment for why a delete has to be
+ * expressible here at all.
+ */
+function mergedEnv(
+  overrides: Readonly<Record<string, string | undefined>>,
+): Record<string, string> {
+  // A `Map`, not an object indexed by `key`: the keys are DATA (environment variable names), and
+  // a plain-object table read or deleted by a computed key is the `Object.prototype` hazard
+  // `scripts/proto-index.ts` ratchets. `Object.fromEntries` builds the record once, at the end.
+  const merged = new Map<string, string>();
+  for (const [key, value] of Object.entries(Bun.env)) {
+    if (value !== undefined) merged.set(key, value);
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) merged.delete(key);
+    else merged.set(key, value);
+  }
+  return Object.fromEntries(merged);
+}
+
 function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
   const [head = '', ...rest] = command;
   try {
     return Bun.spawn([head, ...rest], {
       cwd: options.cwd,
-      env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+      env: options.env === undefined ? Bun.env : mergedEnv(options.env),
       stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
       stdout: 'pipe',
       stderr: 'pipe',

package/src/generate-files.ts

@@ -55,6 +55,16 @@ export interface GenerateOptions {
    * import of a class the app never declared. Read at `sliceDir(surface, feature)/errors.ts`.
    */
   readonly sliceErrors?: string;
+  /**
+   * `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when the feature has no
+   * entity yet. Supplied by `run` for `sliceErrors`'s reason — whether the feature is
+   * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
+   * `repo.byId`/`repo.listByOrg` calls into a feature whose entity names no tenant column. Read at
+   * `sliceDir(surface, feature)/entity.ts`.
+   */
+  readonly sliceEntity?: string;
+  /** `job` and `task`: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -110,9 +120,21 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
     case 'query':
       return dedupe(queryFiles(options.name, { ...target, live: options.live === true }));
     case 'job':
-      return dedupe(jobFiles(options.name, target));
+      return dedupe(
+        jobFiles(options.name, {
+          ...target,
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
+        }),
+      );
     case 'task':
-      return dedupe(taskFiles(options.name, target));
+      return dedupe(
+        taskFiles(options.name, {
+          ...target,
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
+        }),
+      );
     case 'island':
       return dedupe(islandFiles(options.name, { dir: options.at ?? `${surfaceDir}/${feature}` }));
     // No `--at`, no surface, no feature: `guards/` is the one directory the gate discovers, and a

package/src/island-capture.ts

@@ -267,6 +267,7 @@ export async function captureIslandState(
       box: seen?.box ?? { x: 0, y: 0, width: 0, height: 0 },
       mounted: seen?.mounted === true,
       unstubbed: seen?.unstubbed ?? [],
+      sockets: seen?.sockets ?? [],
       console: page.console(),
       pageErrors: page.pageErrors(),
       overflow: seen?.overflow ?? { x: false, y: false },

package/src/island-harness-script.ts

@@ -65,10 +65,54 @@ var method=(init&&init.method)||(typeof input==='object'&&input&&input.method)||
 var path=pathOf(url);var k=method.toUpperCase()+' '+path;
 var respond=stubFor(method,path);bump();
 return answer(respond,k).then(function(r){bump();return r},function(e){bump();throw e})};
-// A socket and an event stream have no stub vocabulary at all, so both are refused outright and
-// recorded: a live component that opened one would otherwise sit in its loading branch forever.
-window.WebSocket=function(url){W.unstubbed.push('WS '+url);throw refuse('WS '+url)};
-window.EventSource=function(url){W.unstubbed.push('SSE '+url);throw refuse('SSE '+url)};
+// A socket or an event stream needs no stub, because a SNAPSHOT of an island does not need a
+// LIVE one: every state's fixture already rides \`props\`/\`routes\`, so the component's own
+// realtime layer has nothing to tell it that the fetch/XHR seal does not already say. Refusing
+// the construction outright — as this did until the defect that made every live island
+// unphotographable — fails a component for opening a channel whose data this harness was never
+// asked to carry, in EVERY state, because \`mount()\` dials it unconditionally.
+//
+// So the stand-in is INERT rather than refused: no real dial, no network, no message and no error
+// ever delivered. \`close()\`/\`send()\` are no-ops. Recorded on \`W.sockets\`, never on
+// \`W.unstubbed\` — a real unanswered fetch still fails the run (the refusal above is unchanged),
+// but a socket a component merely opened and heard nothing from is not the same fact as a request
+// nobody stubbed, and \`stateShotOk\` must not conflate the two; neither field is hidden from the
+// verdict, both ride \`--json\` plainly, so this is not a candidate for \`ISLAND_BLIND_SPOTS\` —
+// that list is for a fact a PICTURE cannot show, and a socket's inertness is a fact this JSON
+// already states.
+//
+// \`readyState\` DOES leave CONNECTING, on a zero-delay timer, once: a component whose \`mount()\`
+// awaits the socket's own \`open\` before it renders anything — never true of the reference app's
+// \`LiveClient\`, whose \`connect()\` registers callbacks and returns, but not a fact this harness
+// may assume of every app — would otherwise hang the mount forever, trading one impossible
+// \`X_SHOT_ISLAND_UNSTUBBED_REQUEST\` fix for an unreachable \`--settle\` deadline, the same defect
+// under a different name. So \`onopen\`/an \`'open'\` listener fires exactly once; \`onmessage\` and
+// \`onerror\` never do, because this is a channel that opened and then heard nothing, not one that
+// received data no fixture could have supplied.
+function inertSocket(kind,url){
+W.sockets.push(kind+' '+url);
+var listeners={};
+var self={
+readyState:0,url:String(url),
+addEventListener:function(type,fn){(listeners[type]=listeners[type]||[]).push(fn)},
+removeEventListener:function(type,fn){var l=listeners[type];if(!l)return;
+var i=l.indexOf(fn);if(i>=0)l.splice(i,1)},
+dispatchEvent:function(){return true},
+send:function(){},
+close:function(){},
+onopen:null,onmessage:null,onerror:null,onclose:null};
+setTimeout(function(){
+self.readyState=1;
+var ev={type:'open',target:self};
+if(typeof self.onopen==='function')self.onopen(ev);
+var handlers=listeners['open'];
+if(handlers)for(var i=0;i<handlers.length;i+=1)handlers[i](ev)},0);
+return self}
+window.WebSocket=function(url){return inertSocket('WS',url)};
+window.WebSocket.CONNECTING=0;window.WebSocket.OPEN=1;
+window.WebSocket.CLOSING=2;window.WebSocket.CLOSED=3;
+window.EventSource=function(url){return inertSocket('SSE',url)};
+window.EventSource.CONNECTING=0;window.EventSource.OPEN=1;window.EventSource.CLOSED=2;
 var RealXHR=window.XMLHttpRequest;
 window.XMLHttpRequest=function(){var xhr=new RealXHR();var open=xhr.open;
 xhr.open=function(method,url){W.unstubbed.push(String(method).toUpperCase()+' '+pathOf(url));
@@ -117,7 +161,7 @@ requestAnimationFrame(tick)}
 /** The whole prelude, in the one order that works: state, seal, clock, then the readiness watch. */
 export function harnessScript(options: HarnessScriptOptions): string {
   return [
-    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[]};`,
+    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[],sockets:[]};`,
     sealScript(options.stubs),
     clockScript(options.now, options.timeZone),
     readyScript(),
@@ -138,6 +182,11 @@ export const readinessProbe = (selector: string): string =>
   'var r=box?box.getBoundingClientRect():{width:0,height:0,x:0,y:0};' +
   'return{harness:W.harness===true,ready:W.ready===true,' +
   'unstubbed:(W.unstubbed||[]).slice(),' +
+  // Recorded beside `unstubbed`, never merged into it: a socket a component opened and never
+  // heard back from is not the same fact as a request nobody stubbed, and `stateShotOk` reads
+  // neither — a component may legitimately hold an open, silent channel in a state that is
+  // otherwise clean.
+  'sockets:(W.sockets||[]).slice(),' +
   'attached:host!==null&&document.body.contains(host),' +
   'mounted:host!==null&&host.hasAttribute("data-x-mounted"),' +
   'failed:host&&host.hasAttribute("data-x-failed")?host.getAttribute("data-x-failed"):null,' +

package/src/island-verdict.ts

@@ -54,6 +54,13 @@ export interface IslandReadiness {
   readonly harness: boolean;
   readonly ready: boolean;
   readonly unstubbed: readonly string[];
+  /**
+   * `"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
+   * is mounted in; this is the fact a picture cannot carry about that.
+   */
+  readonly sockets: readonly string[];
   readonly attached: boolean;
   readonly mounted: boolean;
   readonly failed: string | null;
@@ -86,6 +93,7 @@ const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
   harness: t.boolean,
   ready: t.boolean,
   unstubbed: t.array(t.string),
+  sockets: t.array(t.string),
   attached: t.boolean,
   mounted: t.boolean,
   failed: t.nullable(t.string),
@@ -115,6 +123,8 @@ export interface IslandStateShot {
   readonly box: IslandBox;
   readonly mounted: boolean;
   readonly unstubbed: readonly string[];
+  /** See `IslandReadiness.sockets` — recorded, and read by neither `stateShotOk` nor the gate. */
+  readonly sockets: readonly string[];
   readonly console: readonly ConsoleLine[];
   readonly pageErrors: readonly PageError[];
   /**
@@ -184,6 +194,7 @@ const shotJson = (shot: IslandStateShot): JsonValue => ({
   warnings: stateShotWarnings(shot).length,
   overflow: { x: shot.overflow.x, y: shot.overflow.y },
   unstubbed: [...shot.unstubbed],
+  sockets: [...shot.sockets],
   console: shot.console.map((line) => ({ level: line.level, text: line.text, at: line.at })),
   pageErrors: shot.pageErrors.map((error) => ({
     message: error.message,

package/src/mcp-host.ts

@@ -46,6 +46,7 @@ import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import { testEnvOverrides } from './test-dotenv';
 
 export interface DevHostInput {
   readonly root: string;
@@ -178,7 +179,7 @@ export async function readOnlyRows(
 }
 
 function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
-  const { root, runner } = input;
+  const { root, runner, env } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
   // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
   // resolution is not an answer: `??=` kept the rejection, so a statement timeout on the DDL
@@ -239,10 +240,14 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
 
     // `bun test <filter>` matches on the test path, the same rule `x test`'s `discoverTests` uses.
     async runTests(filter: string | undefined) {
+      // 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 }),
         },
       );
       return parseBunTest(execOutput(result), result.durationMs);

package/src/scaffold-fixture.ts

@@ -21,6 +21,31 @@ export const HANDWRITTEN_ERRORS = `import { UltimateError } from '@ultimat3/core
 export class LedgerClosedError extends UltimateError {}
 `;
 
+/**
+ * A feature slice whose entity is NOT tenant-scoped — the shape `x g entity`'s own comment
+ * describes for a single-tenant app, and never a shape the generator writes itself. The
+ * generator's INPUT only, the same way `HANDWRITTEN_ERRORS` above is: `x g job`/`x g task` read
+ * this from a real `entity.ts`, and a fixture that never exercised it compiled only the shape
+ * that never failed.
+ */
+export const HANDWRITTEN_ENTITY_NO_TENANT = `import { entity, text, uuid } from '@ultimat3/entity';
+
+export const shortLink = entity('short_links', {
+  columns: { id: uuid().primaryKey(), url: text({ max: 2000 }) },
+});
+
+export type ShortLink = typeof shortLink.$row;
+`;
+
+/** The paired `repo.ts`: no `byId`, no `listByOrg` — nothing this slice's job may call. */
+export const HANDWRITTEN_REPO_NO_TENANT = `import { db, sql } from '@ultimat3/db';
+import type { ShortLink } from './entity';
+
+export async function list(limit = 50): Promise<readonly ShortLink[]> {
+  return db().query<ShortLink>(sql\`select * from short_links order by url limit \${limit}\`);
+}
+`;
+
 /**
  * One realistic invocation of every generator, on top of `x new --example`. Names differ from
  * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
@@ -47,6 +72,23 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
   { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
   { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
+  // The other shape both templates have: a feature whose entity names no tenant column, so the
+  // job/task must not assume one — compiled here beside the tenant-scoped pair above, exactly as
+  // `ping-invoice`/`touch-invoice` compile the action's other shape beside `send-invoice`.
+  {
+    kind: 'job',
+    name: 'purge-orphans',
+    feature: 'short-link',
+    sliceEntity: HANDWRITTEN_ENTITY_NO_TENANT,
+    sliceRepo: HANDWRITTEN_REPO_NO_TENANT,
+  },
+  {
+    kind: 'task',
+    name: 'nightly-purge',
+    feature: 'short-link',
+    sliceEntity: HANDWRITTEN_ENTITY_NO_TENANT,
+    sliceRepo: HANDWRITTEN_REPO_NO_TENANT,
+  },
   { kind: 'route', name: 'pricing', surface: 'site' },
   { kind: 'route', name: 'billing', surface: 'app' },
   // `--at`, pointed at the `site/` route above: an island's whole reason to exist is a 0kb page

package/src/templates/index.ts

@@ -12,7 +12,8 @@ export { entityFiles } from './entity';
 export { guardCode, guardFiles } from './guard';
 export type { IslandOptions } from './island';
 export { islandFiles } from './island';
-export { jobFiles, taskFiles } from './job';
+export type { JobOptions } from './job';
+export { isTenantScopedSlice, jobFiles, taskFiles } from './job';
 export { CATALOG_ROOT, catalogPath, DEFAULT_LOCALES, resolveLocales } from './locales';
 // All three members of the `GeneratedFile` union, not two: the barrel exported the union and the
 // foundation variant only, so a consumer could hold a `GeneratedFile` and had no name to narrow it

package/src/templates/job.ts

@@ -3,10 +3,11 @@
 // both; the generated test pins them through a real driver, because a key that is not stable is a
 // job that runs twice and a tenant that is not declared is a job that reads the wrong org's rows.
 
+import { stripComments } from '../ts-scan';
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceFoundation } from './slice-foundation';
+import { sliceExports, sliceFoundation } from './slice-foundation';
 
 const jobSource = (
   name: NameSet,
@@ -39,6 +40,42 @@ export const ${name.camel} = job({
 });
 `;
 
+/**
+ * The other shape: this feature's own `entity.ts` names no tenant column (or names `'none'`), or
+ * its `repo.ts` does not export the `byId`/`listByOrg` pair the tenant-scoped body above calls —
+ * checked by `isTenantScopedSlice` against what is actually on the app's disk, never assumed. The
+ * body imports neither `../entity` nor `../repo`, so it compiles whether this feature has an
+ * entity yet or has one with no tenant, and `tenant: 'none'` is stated rather than defaulted so a
+ * reviewer sees the decision instead of an absence.
+ */
+const neutralJobSource = (
+  name: NameSet,
+): string => `// ${name.camel}: multi-step durable work with no tenant behind it. Each step is retried
+// independently and its result is stored under its name — step names are stable identifiers, not
+// labels. \`t\` comes from @ultimat3/jobs, not @ultimat3/schema: a job file imports one package.
+
+import { job, t } from '@ultimat3/jobs';
+
+export const ${name.camel} = job({
+  input: t.object({ id: t.uuid }),
+  // This feature has no tenant column to derive an org from — either it has no entity yet, or its
+  // entity names none. \`tenant: 'none'\` STRIPS the org from the run rather than leaving one
+  // behind, so a tenant-scoped read added later fails closed with X_TENANCY_ACTOR_ORG_REQUIRED
+  // instead of reading whichever org the enqueuer happened to hold. Once this feature's entity
+  // declares \`tenant: 'orgId'\` and its repo exports \`byId\`/\`listByOrg\`, the next \`x g job\` in
+  // this slice scaffolds the tenant-scoped shape above instead.
+  tenant: 'none',
+  idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
+  retry: { attempts: 5, backoff: 'exponential' },
+  async run({ step }) {
+    await step.run('process', async () => {
+      // TODO: this job's own work.
+    });
+    return { processed: true };
+  },
+});
+`;
+
 const taskSource = (
   name: NameSet,
   jobName: NameSet,
@@ -65,6 +102,25 @@ export const ${name.camel} = task({
 });
 `;
 
+/** The task's other shape: enqueues the neutral job above, so its payload carries no `orgId`. */
+const neutralTaskSource = (
+  name: NameSet,
+  jobName: NameSet,
+): string => `// ${name.camel}: a scheduled trigger. Tasks only enqueue jobs — the work itself is durable and
+// retryable, and the schedule carries an explicit IANA time zone.
+
+import { task } from '@ultimat3/jobs';
+import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
+
+export const ${name.camel} = task({
+  cron: '0 3 * * *',
+  tz: 'UTC',
+  // No org in the payload: the job this enqueues declares \`tenant: 'none'\`, because this
+  // feature's entity names no tenant column (or has none yet).
+  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+});
+`;
+
 const jobTest = (
   name: NameSet,
 ): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
@@ -121,6 +177,63 @@ jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
 });
 `;
 
+/** The job test's other shape: no `orgId` anywhere, and a `tenantFor` that reads `undefined`. */
+const neutralJobTest = (
+  name: NameSet,
+): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
+// are the framework's, so what this pins is that THIS job's steps run and are idempotent.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '00000000-0000-4000-8000-000000000001';
+const input = { id };
+// The key this job owes, spelled once. Named rather than inlined so the assertion below carries
+// the job's own name and still fits the formatter width the app's \`lint\` step enforces.
+const expectedKey = \`${name.kebab}:\${id}\`;
+
+// The driver is process-global, so it is installed and released around this file rather than
+// left behind for whichever test happens to run next.
+beforeAll(() => {
+  setJobDriver(createMemoryDriver());
+});
+afterAll(resetJobDriver);
+
+jobTest('${name.camel} declares a key and a retry policy', () => {
+  expect(${name.camel}.kind).toBe('job');
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(expectedKey);
+  expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
+});
+
+jobTest('${name.camel} derives the same key for the same input', () => {
+  const key = ${name.camel}.idempotencyKeyFor(input);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(key);
+});
+
+jobTest('${name.camel} declares no tenant', () => {
+  // This feature's entity names no tenant column (or has none yet) — \`tenant: 'none'\` is the
+  // declaration for that, and it strips one rather than inheriting the worker's, which is what
+  // stands between a read added here later and X_TENANCY_ACTOR_ORG_REQUIRED, or worse, another
+  // org's rows if this ever gains one.
+  expect(${name.camel}.tenantFor(input)).toBeUndefined();
+});
+
+jobTest('${name.camel} projects itself into the manifest', () => {
+  const described = ${name.camel}.describe();
+  expect(described.queue).toBe('default');
+  expect(described.retry.attempts).toBe(5);
+});
+
+jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
+  // The whole point of the key: an at-least-once caller may enqueue twice and the work still
+  // happens once. \`.enqueue()\` is the one queue path — a job is never run inline.
+  const first = await ${name.camel}.enqueue(input);
+  expect(first.deduped).toBe(false);
+  const again = await ${name.camel}.enqueue(input);
+  expect(again.deduped).toBe(true);
+});
+`;
+
 const taskTest = (
   name: NameSet,
   jobName: NameSet,
@@ -163,28 +276,75 @@ jobTest('${name.camel} fires its declared entries', async () => {
 });
 `;
 
-export function jobFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+export interface JobOptions extends FeatureTarget {
+  /**
+   * This feature's own `entity.ts` as it stands on disk, or absent when the feature has none yet.
+   * Supplied by `run` for the same reason `ActionOptions.sliceErrors` is: whether the slice is
+   * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
+   * `repo.byId`/`repo.listByOrg` calls into a feature whose repo never declared them —
+   * `x g task purgeOrphans --feature links` on a `links` slice with no `orgId` produced files that
+   * did not compile.
+   */
+  readonly sliceEntity?: string;
+  /** This feature's own `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
+}
+
+/**
+ * Whether `x g job`/`x g task` may assume the tenant-scoped shape: an `entity.ts` this feature
+ * does not have yet is about to be scaffolded fresh by `sliceFoundation` below, tenant-scoped by
+ * default — so absent counts as scoped. One that exists is trusted over that default: it declares
+ * a real, non-`'none'` `tenant`, AND its `repo.ts` actually exports the `byId`/`listByOrg` pair the
+ * tenant-scoped body calls. Both have to hold — an entity that still names `tenant: 'orgId'` after
+ * an author trimmed `listByOrg` out of `repo.ts` (or never generated one) is not a slice this job
+ * can read through either.
+ */
+export function isTenantScopedSlice(
+  sliceEntity: string | undefined,
+  sliceRepo: string | undefined,
+): boolean {
+  if (sliceEntity === undefined) return true;
+  const declaresTenant = /\btenant\s*:\s*'(?!none')[^']+'/.test(stripComments(sliceEntity));
+  if (!declaresTenant) return false;
+  if (sliceRepo === undefined) return true;
+  return sliceExports(sliceRepo, 'byId') && sliceExports(sliceRepo, 'listByOrg');
+}
+
+export function jobFiles(rawName: string, target: JobOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const dir = `${target.surfaceDir}/${target.feature}/jobs`;
+  const scoped = isTenantScopedSlice(target.sliceEntity, target.sliceRepo);
   return [
     // The job's steps read through `../repo`, which carries `../entity` for its row type. No
     // policy: a job has no request behind it and evaluates none, so a generated one would be a
     // file nobody asked for. `x g task` inherits this by composing `jobFiles` below.
-    ...sliceFoundation(target, ['entity']),
-    { path: `${dir}/${name.kebab}.ts`, contents: jobSource(name) },
+    // Only for the tenant-scoped shape: the neutral job below reads neither module, and a slice
+    // this feature does not own the tenancy of is not this generator's to scaffold an entity into.
+    ...(scoped ? sliceFoundation(target, ['entity']) : []),
+    {
+      path: `${dir}/${name.kebab}.ts`,
+      contents: scoped ? jobSource(name) : neutralJobSource(name),
+    },
     // `.job.test.ts`, because the gate types a test by its FILENAME: a `jobTest` in a plain
     // `<name>.test.ts` runs under `unit`, and `x test job` answers X_TEST_NO_FILES in an app that
     // is full of them. Same lesson `x g route` already carries for `page.e2e.test.ts`.
-    { path: `${dir}/${name.kebab}.job.test.ts`, contents: jobTest(name) },
+    {
+      path: `${dir}/${name.kebab}.job.test.ts`,
+      contents: scoped ? jobTest(name) : neutralJobTest(name),
+    },
   ];
 }
 
-export function taskFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+export function taskFiles(rawName: string, target: JobOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const jobName = names(`${rawName}-job`);
   const dir = `${target.surfaceDir}/${target.feature}/tasks`;
+  const scoped = isTenantScopedSlice(target.sliceEntity, target.sliceRepo);
   return [
-    { path: `${dir}/${name.kebab}.ts`, contents: taskSource(name, jobName) },
+    {
+      path: `${dir}/${name.kebab}.ts`,
+      contents: scoped ? taskSource(name, jobName) : neutralTaskSource(name, jobName),
+    },
     // A task's test is a `jobTest` too — it drives a queue — so it takes the same suffix.
     { path: `${dir}/${name.kebab}.job.test.ts`, contents: taskTest(name, jobName) },
     ...jobFiles(`${rawName}-job`, target),

package/src/templates/scaffold-auth.ts

@@ -23,9 +23,13 @@ const devActor = (
 // \`X_CONFIG_INVALID\` — which is what a scaffolded app did on its very first \`x dev\`.
 //
 // DEVELOPMENT ONLY, and the guard is the point: a viewer that followed this to staging would sign
-// every visitor in as an admin. \`bun test\` sets \`NODE_ENV=test\`, so it does not install there
-// either — a fixture mints its own actor, and a second one arriving from a cookie would decide
-// which actor a test is about.
+// every visitor in as an admin. FAILS CLOSED (\`fallback: 'production'\`) rather than trusting
+// \`tryResolveEnvironment\`'s own default: that default is \`development\`, so a process that named
+// NEITHER \`ULTIMATE_ENV\` nor \`NODE_ENV\` would otherwise read as development too — indistinguishable
+// from the one this file exists to allow. \`x dev\` declares \`ULTIMATE_ENV=development\` for exactly
+// this reason (whenever neither key is already set), so a bare \`x dev\` still installs this viewer;
+// \`bun test\` sets \`NODE_ENV=test\`, so it does not install there either — a fixture mints its own
+// actor, and a second one arriving from a cookie would decide which actor a test is about.
 //
 // REPLACE IT with the real thing: resolve a session cookie to a row, and return that actor.
 // Everything downstream — pages, policies, live subscribers, MCP tools — reads what this returns.
@@ -78,7 +82,7 @@ export const devActorFor = (role: DevRole): Actor => ({
 export function installDevAuthenticator(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): boolean {
-  if (tryResolveEnvironment({ env }) !== 'development') return false;
+  if (tryResolveEnvironment({ env, fallback: 'production' }) !== 'development') return false;
   configureAuthenticator((request) => devActorFor(devRoleFrom(request.header('cookie'))));
   logger.warn('every request is answered as a development viewer', {
     role: DEFAULT_DEV_ROLE,
@@ -133,6 +137,11 @@ unitTest('it installs in development and in no other environment', () => {
 
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'production' })).toBe(false);
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'staging' })).toBe(false);
+  // FAILS CLOSED: a process naming NEITHER key is production here, never the default-development
+  // a bare \`tryResolveEnvironment({ env })\` would answer. \`x dev\` is what makes a real \`x dev\`
+  // still install this viewer — it declares \`ULTIMATE_ENV=development\` before this module loads,
+  // for exactly the process this call simulates having none of.
+  expect(installDevAuthenticator({})).toBe(false);
   expect(configuredAuthenticator()).toBeUndefined();
 
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);

package/src/templates/slice-foundation.ts

@@ -115,8 +115,12 @@ const listedExports = (code: string): readonly string[] =>
  */
 export function sliceExports(source: string, name: string): boolean {
   const code = stripComments(source);
+  // `(?:async\s+)?` before `function`: an `export async function byId` — every repo function
+  // `x g entity` scaffolds — matched neither this nor `listedExports`, so a caller checking for
+  // `byId`/`listByOrg` on a real repo.ts always read `false`. `async` has no meaning before
+  // `class`/`const`/`let`/`var`/`enum`, so it is scoped to `function` only.
   const declared = new RegExp(
-    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|function|enum)\\s+${name}\\b`,
+    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
   return declared.test(code) || listedExports(code).includes(name);
 }

package/src/test-dotenv.ts

@@ -0,0 +1,125 @@
+// Single responsibility: which env keys reached THIS `x` process only because Bun auto-loaded
+// `.env.development` / `.env.development.local` at startup — so a `bun test` child this process
+// spawns (`test-shards.ts`, `verify-tests.ts`, `verify-test-run.ts`, `mcp-host.ts`'s `runTests`)
+// does not inherit a key a bare `bun test` would never have seen.
+//
+// PROBED ON BUN 1.4.2, and the probe decided the rule: an ambient env var SHADOWS a dotenv file's
+// own value for the same key (`FOO=dev bun test` with a fixture `.env.test` declaring `FOO=test`
+// still read `FOO=dev` inside the test). So a leaked key is never made safe by a legitimate test
+// file (`.env`, `.env.test`, …) also declaring it — if we left it in place, the leaked value would
+// go on shadowing that file's own value exactly as it shadows `.env.test` above. The only question
+// worth asking is the one `devOnlyLeakedKeys` answers: does this process's CURRENT value match
+// what `.env.development`/`.env.development.local` would have set? If yes, delete it and let the
+// child's own dotenv load (or absence of one) answer instead. If the current value differs, this
+// process's env holds something dotenv did not put there — a real export, CI, `.env.local` — and
+// deleting it is not this function's call to make.
+//
+// KNOWN LIMITATION, stated rather than hidden: a real ambient value that happens to COINCIDE with
+// the dev file's value is indistinguishable from a leak from here — there is no pre-dotenv
+// snapshot to compare against. This function resolves that ambiguity toward closing the leak.
+//
+// A SECOND PARSER, not a call to `env-example.ts`'s `parseEnvKeys`: that function is deliberately
+// keys-only ("half of them are placeholders" — it feeds `.env.example` rendering, where a secret's
+// value must never appear), and widening it to return values would change what a template
+// generator ships. This one exists to COMPARE values, a different job with a different file.
+
+import { readFileSync } from 'node:fs'; // why: Bun ships no synchronous file read with a graceful-missing return.
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+
+/** Bun's own grammar, matched against `env-example.ts`'s `ENV_KEY_RE` (kept separate: see header). */
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * One dotenv file's key/value pairs. A `Map`, not an object literal: a key of `constructor` or
+ * `__proto__` passes `ENV_KEY_RE` and reads back as a function on `Object.prototype`, the exact
+ * defect this repo's `verify-tests.ts` header names thirteen instances of.
+ *
+ * Quoting: a value opening with `"` or `'` runs to its closing quote (or end of value if the
+ * dotenv file never closes it), `#` included — Bun does not stop a quoted value at an internal
+ * `#`. An unquoted value stops at the first `#`, which is where an inline comment starts.
+ */
+export function parseDotenvValues(text: string): ReadonlyMap<string, string> {
+  const values = new Map<string, string>();
+  for (const raw of text.split('\n')) {
+    const line = raw.trim().replace(/^export\s+/, '');
+    if (line === '' || line.startsWith('#')) continue;
+    const separator = line.indexOf('=');
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    if (!ENV_KEY_RE.test(key)) continue;
+    const rest = line.slice(separator + 1).trim();
+    const quote = rest.startsWith('"') || rest.startsWith("'") ? rest[0] : undefined;
+    if (quote === undefined) {
+      const hash = rest.indexOf('#');
+      values.set(key, (hash >= 0 ? rest.slice(0, hash) : rest).trim());
+      continue;
+    }
+    const closing = rest.indexOf(quote, 1);
+    values.set(key, closing >= 0 ? rest.slice(1, closing) : rest.slice(1));
+  }
+  return values;
+}
+
+export interface DevOnlyLeakInput {
+  /** `.env.development`'s text, or `''` when the file does not exist. */
+  readonly devText: string;
+  /** `.env.development.local`'s text, or `''` — wins over `devText` for a shared key, Bun's own precedence. */
+  readonly devLocalText: string;
+  /** This process's environment, as `exec.ts` would spawn a child with it (before any override). */
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * The pure decision, no filesystem: every key `.env.development`/`.env.development.local` would
+ * set, where `env`'s CURRENT value for that key is exactly what the file would have set. See this
+ * file's header for why a legitimate test file declaring the same key does not exempt it.
+ */
+export function devOnlyLeakedKeys(input: DevOnlyLeakInput): readonly string[] {
+  const merged = new Map(parseDotenvValues(input.devText));
+  for (const [key, value] of parseDotenvValues(input.devLocalText)) merged.set(key, value);
+  const leaked: string[] = [];
+  for (const [key, devValue] of merged) {
+    // `Object.hasOwn` FIRST: `key` is data (a name out of a dotenv file), and `env['constructor']`
+    // on a plain object answers `Object.prototype`'s member, not `undefined` — the rule
+    // `scripts/proto-index.ts` ratchets, with its own sanctioned repair.
+    if (Object.hasOwn(input.env, key) && input.env[key] === devValue) leaked.push(key);
+  }
+  return leaked;
+}
+
+/** A missing dotenv file is the common case (no `.env.development.local` in most checkouts). */
+function readIfPresent(path: string): string {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The env override a `bun test` child spawned FROM `root` should get: every dev-only leaked key
+ * deleted. `exec.ts`'s `ExecOptions.env` reads an `undefined` value as "unset for this child,
+ * even though the parent has it" — see that file for why the merge could not otherwise express
+ * a deletion.
+ *
+ * `root` is the app/repo root the caller already resolved — NOT necessarily `process.cwd()`, which
+ * is what Bun actually auto-loaded `.env.development` relative to at this process's own startup.
+ * The two agree for every command that boots from the repo/app root, which is every one of them
+ * today; a future command invoked from a subdirectory would fail SAFE here (the file this reads
+ * would differ from the one Bun loaded, values would not match, and nothing gets stripped) rather
+ * than stripping the wrong key.
+ */
+export function testEnvOverrides(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Readonly<Record<string, string | undefined>> {
+  const leaked = devOnlyLeakedKeys({
+    devText: readIfPresent(join(root, '.env.development')),
+    devLocalText: readIfPresent(join(root, '.env.development.local')),
+    env,
+  });
+  const overrides: Record<string, string | undefined> = {};
+  for (const key of leaked) overrides[key] = undefined;
+  return overrides;
+}

package/src/test-shards.ts

@@ -40,6 +40,7 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
+import { testEnvOverrides } from './test-dotenv';
 import { testPasses } from './test-passes';
 import type { TestFile } from './test-select';
 import type { TestType } from './verify-tests';
@@ -165,6 +166,13 @@ export interface RunShardsOptions {
   readonly affected?: AffectedSelection;
   /** Everything after the caller's `--`, forwarded to every pass and printed in the reproduce. */
   readonly passthrough?: readonly string[];
+  /**
+   * This process's own environment, as `exec.ts` would otherwise hand it whole to the spawned
+   * child. Optional and defaulted to `Bun.env`: every real caller's is `Bun.env` already (`x
+   * test`/`x verify` read `CommandContext.env`, itself `Bun.env`), so the default is not a
+   * fallback so much as a seam this file's own tests use to hand it a fixture instead.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
 }
 
 /**
@@ -219,6 +227,11 @@ export const failureOf = (code: number, files: number, plan: ReproduceOptions):
  */
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {
   const only = options.only;
+  // Computed ONCE per invocation, never per pass: every pass spawns from the same `root` and the
+  // same parent env, so the leaked-key set cannot differ pass to pass.
+  const envOverrides: Record<string, string | undefined> = {
+    ...testEnvOverrides(options.root, options.env ?? Bun.env),
+  };
   const passes = testPasses({
     files: options.files,
     workers: options.workers,
@@ -241,7 +254,14 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
       }),
       {
         cwd: options.root,
-        ...(only === undefined ? {} : { env: { ULTIMATE_TEST_WORKER: String(only) } }),
+        ...(Object.keys(envOverrides).length === 0 && only === undefined
+          ? {}
+          : {
+              env: {
+                ...envOverrides,
+                ...(only === undefined ? {} : { ULTIMATE_TEST_WORKER: String(only) }),
+              },
+            }),
       },
     );
     const plan = planOf(options, pass);

package/src/verify-step.ts

@@ -65,6 +65,13 @@ export type HostCheck = (root: string) => Promise<readonly Finding[]>;
 export interface VerifyContext {
   readonly root: string;
   readonly runner: Runner;
+  /**
+   * This process's own environment. Optional and defaulted to `Bun.env` at every reader
+   * (`verify-tests.ts`'s `runSerial`/`runType`): every real caller's IS `Bun.env` already
+   * (`cmd-verify.ts` passes `ctx.env`, itself `Bun.env`), so the default only matters to a test
+   * that constructs a `VerifyContext` fixture and never mentions `env`.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
   readonly hostChecks?: Partial<Record<VerifyStepName, HostCheck>>;
   /**
    * How wide the parallel test steps go. Absent means `defaultWorkers()` — a knob, never a

package/src/verify-test-run.ts

@@ -6,6 +6,7 @@ import type { Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
 import { countsOf } from './test-counts';
+import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { failureOf, testArgs } from './test-shards';
 import type { StepOutcome } from './verify-step';
@@ -20,6 +21,8 @@ export interface ParallelRunOptions {
   readonly workers: number;
   /** Carried into the `fix:` so a failure reproduces as `x test <type> --workers N`. */
   readonly type: TestType;
+  /** This process's own environment. Optional and defaulted to `Bun.env` — see `VerifyContext.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
 }
 
 /**
@@ -38,7 +41,11 @@ export interface ParallelRunOptions {
 export async function runParallel(options: ParallelRunOptions): Promise<StepOutcome> {
   const files = options.files.map((file) => file.path);
   const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
-  const result = await options.runner(testArgs({ files, workers }), { cwd: options.root });
+  const envOverrides = testEnvOverrides(options.root, options.env ?? Bun.env);
+  const result = await options.runner(testArgs({ files, workers }), {
+    cwd: options.root,
+    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+  });
   // `failureOf` is `x test`'s own, imported rather than restated: the two paths report the SAME
   // failed `bun test`, so a second literal here is two `cause:` strings and two `fix:` lines free
   // to drift — and the one that drifts is the gate's, which is the one an agent reads first.

package/src/verify-tests.ts

@@ -15,6 +15,7 @@ import { TEST_TYPES } from '@ultimat3/testing';
 import { checkEvalBaselines, checkEvalCoverage, checkEvalRecording } from './app-evals';
 import { APP_CONFIG_FILE } from './app-root';
 import { countsOf } from './test-counts';
+import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
 import { defaultWorkers } from './test-workers';
@@ -201,7 +202,11 @@ export const resetTestDiscovery = (): void => discovered.clear();
 
 const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
   const command = testStepCommand(type);
-  const result = await ctx.runner(command, { cwd: ctx.root });
+  const envOverrides = testEnvOverrides(ctx.root, ctx.env ?? Bun.env);
+  const result = await ctx.runner(command, {
+    cwd: ctx.root,
+    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+  });
   return {
     ...fromExec(result, {
       code: 'X_TEST_FAILED',
@@ -223,6 +228,7 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
     files,
     workers: ctx.workers ?? defaultWorkers(),
     type,
+    ...(ctx.env === undefined ? {} : { env: ctx.env }),
   });
 };