unitbob 0.7.13 → 0.7.15

package/README.md

@@ -35,7 +35,7 @@ Codex:
 ```
 codex plugin marketplace add sergeygershun/unitbob-connector
 codex plugin add unitbob@unitbob
-npx -y unitbob@0.7.13 codex-install
+npx -y unitbob@0.7.15 codex-install
 ```
 
 Then start a new chat. A chat opened before the install does not know about
@@ -79,8 +79,8 @@ Do steps 1 and 2 above first. Then, in the chat, in this order:
 | 1. Name it | `I want to add <feature>` | Unitbob writes down what you want and which parts of the map it may touch. You get a link to the feature's page. |
 | 2. Talk it through | `Let's talk through <feature>` | The assistant asks a few numbered questions about how the feature should behave — in plain words, with options and a recommendation. Answer with a letter, a word, or `do as you recommend`. Then it shows you the list of things that will be true when the feature is done and asks: is this it? Say `yes`. |
 | 3. Write the checks | `Write the checks for <feature>` | Each item from that list becomes a check. They are all red now — on purpose, the feature is not built yet. |
-| 4. Build it | `Build <feature>` | Ordinary work in the same chat. Say `Run the checks` at any time to see how many of the feature's checks already pass, and whether anything else broke. |
-| 5. Wrap up | `I'm done with <feature>` | The checks run once more, a second assistant reads them over, and you get the link to the feature's page. |
+| 4. Build it | `Build <feature>` | Ordinary work in the same chat. Say `Run the checks` at any time to see how many of the feature's checks already pass, and whether anything else broke. The moment they all pass, a second assistant reads them over on its own and you get the link to the feature's page. |
+| 5. Wrap up | `I'm done with <feature>` | Only if step 4 did not end on that link: the checks run once more, the second assistant reads them over, and you get the link. |
 | 6. Finish | Press **Finish this feature** on that page | Only you can press it, and only when everything is green. The feature gets its own lamp on the map, already green. |
 
 Good to know:

package/dist/cli.js

@@ -153,9 +153,13 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'accept-worker-plan':
                 await acceptWorkerPlan(await linked(), args);
                 return 0;
-            case 'validate-worker-checkpoints':
-                await validateWorkerCheckpoints(await linked(), args);
-                return 0;
+            case 'validate-worker-checkpoints': {
+                // Spec 55-1, §3. Non-zero for an invalid slice, so a workflow that
+                // only reads the exit code still stops — but the verdict is per slice
+                // and printed, never thrown.
+                const verdict = await validateWorkerCheckpoints(await linked(), args);
+                return verdict.invalid_workers.length > 0 ? 1 : 0;
+            }
             case 'put-suite-build':
                 return await publishAndRun(await linked(), args);
             case 'fix-prepare':

package/dist/files/behavioral.js

@@ -2,6 +2,7 @@ import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rm
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
+import { looksLikeNext } from "../surfaces/nextRoutes.js";
 // The behavioral suite lives under its own root: the main `.feature` plus its
 // step definitions and any helper files, all under `.unitbob/behavioral/`
 // (spec 32). Nothing here is ever written into the project's own `spec/`,
@@ -10,7 +11,7 @@ import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
 // blob only so `check` can execute it locally.
 export const BEHAVIORAL_DIR = '.unitbob/behavioral';
 export const BEHAVIORAL_WORLD_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.rb`;
-const BEHAVIORAL_WORLD_JS_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.js`;
+export const BEHAVIORAL_WORLD_JS_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.js`;
 // A level above "step_definitions/", and deliberately. pytest loads every
 // conftest.py from the rootdir down to the directory it collects, so this one is
 // loaded — and the host's own "step_definitions/conftest.py", which the step
@@ -197,6 +198,180 @@ net.Socket.prototype.connect = function unitbobGuardedConnect(...args) {
   return unitbobConnect.apply(this, args);
 };
 `;
+// Spec 56-1, §2. On Next.js the JavaScript harness is the network guard above
+// *and* a door into the application. Rails gets its door from the connector
+// too — `ActionDispatch::Integration` in the Ruby World; Nest brings its own
+// (`supertest`); Next has no framework test client, and without this every
+// coordinator wrote the same two hundred lines of shims and, on the appartment
+// run, called the route handler directly — which walks past `proxy.ts` and
+// turned a 307 on production into a green "this address is public".
+//
+// The door is the one the spike proved (requirements, "Спайк"): Next's own
+// programmatic API in this process, in dev mode, so the handler, the page and
+// `proxy.ts` run here, where a step can replace `globalThis.fetch` and see
+// what the application sent out. Nothing of the project's is changed: it
+// compiles into `.next/` as `next dev` would (and, on Next 16, takes the same
+// `.next/dev/lock`), and touches no source, config or env file.
+//
+// What is deliberately not here: signing in, fixtures, seeding, the test
+// database. Those stay in host-owned shared steps, as on every other stack.
+// The one thing this file says about the database is "no": a `DATABASE_URL`
+// whose database is not named like a test one does not get a door.
+const NEXT_DOOR_JS = `
+// ---------------------------------------------------------------------------
+// The door into this Next.js application (spec 56-1).
+//
+// Before the first scenario the application is started here, in this process,
+// through Next's own API in dev mode (it compiles into \`.next/\` on demand, as
+// \`next dev\` would). Every request then takes the same road as under
+// \`next start\`: \`proxy.ts\` / \`middleware.ts\`, the router, the handler.
+// Every scenario gets
+// \`this.unitbobFetch(path, init)\`: a fetch against that server with a cookie
+// jar of its own (a Set-Cookie from one response goes out with the next
+// request of the same scenario, and is forgotten at the scenario boundary) and
+// \`redirect: 'manual'\`, so a 307 from the gate is seen as a 307.
+//
+// Do not import a route handler and call it. That walks past the gate, and a
+// green "this address is public" from such a scenario is a lie.
+//
+// Because the application runs in this process, the network guard above holds
+// for its outgoing calls too, and a step may replace \`globalThis.fetch\` in a
+// \`Before\` hook of the project's own steps to read what the application sent
+// out — that hook runs after the warm-up request below, which is what keeps
+// the replacement alive through the first compilation on Next 15.
+//
+// Signing in, fixtures, seeding and the test database are not here; they are
+// host-owned shared steps. This file says exactly one thing about the
+// database: it refuses to open the door on one that is not named like a test
+// database.
+const http = require('node:http');
+const path = require('node:path');
+const { AfterAll, Before, BeforeAll } = require('@cucumber/cucumber');
+
+// This file lives in .unitbob/behavioral/step_definitions/; the project root
+// is three levels up. \`next\` is the project's own — resolved from there, past
+// the sidecar's node_modules, which holds only cucumber.
+const unitbobRoot = path.resolve(__dirname, '..', '..', '..');
+
+// The fetch this process started with, taken before Next wraps the global one
+// and before any step replaces it: the door must keep working while a
+// scenario has \`globalThis.fetch\` stubbed to watch the application's calls.
+const unitbobRealFetch = globalThis.fetch;
+
+let unitbobApp = null;
+let unitbobServer = null;
+let unitbobOrigin = null;
+
+function unitbobProjectRequire(name, from) {
+  return require(require.resolve(name, { paths: [from] }));
+}
+
+// The database a URL names: the path's last segment, before any query string.
+// Percent-decoded when the URL parses; taken as text when it does not.
+function unitbobDatabaseName(url) {
+  try {
+    return decodeURIComponent(new URL(url).pathname.split('/').pop() || '');
+  } catch {
+    return String(url).split('?')[0].split('/').pop() || '';
+  }
+}
+
+BeforeAll({ timeout: 180000 }, async function () {
+  // The runner already sets NODE_ENV=test; kept here so Next reads .env.test
+  // even when this file is loaded some other way.
+  process.env.NODE_ENV = process.env.NODE_ENV || 'test';
+
+  // .env* through the loader Next itself uses (\`@next/env\`, found beside the
+  // project's \`next\`), so the guard below sees what the application will
+  // see: process.env, then .env.test.local, .env.test, .env — and a variable
+  // already in the environment wins over every file.
+  try {
+    const nextPackage = path.dirname(require.resolve('next/package.json', { paths: [unitbobRoot] }));
+    unitbobProjectRequire('@next/env', nextPackage).loadEnvConfig(unitbobRoot, true);
+  } catch {
+    // Next loads the files itself at prepare(); only the guard below is left
+    // reading the shell's environment alone.
+  }
+
+  if (process.env.DATABASE_URL) {
+    const name = unitbobDatabaseName(process.env.DATABASE_URL);
+    if (!/test/i.test(name)) {
+      const refusal =
+        '[unitbob] Unitbob will not run scenarios against "' + name + '": it does not look like a test database. ' +
+        'Put a test DATABASE_URL in .env.test';
+      // Printed as a line of its own before it is thrown: cucumber-js reports a
+      // BeforeAll failure as "a BeforeAll hook errored" with the cause folded
+      // under it, and the one line that matters is this one.
+      console.error(refusal);
+      throw new Error(refusal);
+    }
+  }
+
+  const next = unitbobProjectRequire('next', unitbobRoot);
+  unitbobApp = next({ dev: true, dir: unitbobRoot });
+  await unitbobApp.prepare();
+  const handle = unitbobApp.getRequestHandler();
+  unitbobServer = http.createServer((req, res) => handle(req, res));
+  await new Promise((resolve, reject) => {
+    unitbobServer.once('error', reject);
+    unitbobServer.listen(0, '127.0.0.1', resolve);
+  });
+  unitbobOrigin = 'http://127.0.0.1:' + unitbobServer.address().port;
+
+  // One warm-up request: the first compilation happens now, not inside the
+  // first scenario's timeout, and a \`fetch\` replaced by a step afterwards
+  // survives it.
+  try {
+    await (await unitbobRealFetch(unitbobOrigin + '/', { redirect: 'manual' })).arrayBuffer();
+  } catch {
+    // A first page that fails is the scenarios' business, not the door's.
+  }
+});
+
+Before(function () {
+  const jar = new Map();
+  this.unitbobFetch = async function unitbobFetch(target, init) {
+    if (!unitbobOrigin) throw new Error('[unitbob] The application is not running: BeforeAll did not open the door.');
+    const options = Object.assign({}, init);
+    const headers = new Headers(options.headers || {});
+    if (jar.size > 0 && !headers.has('cookie')) {
+      headers.set('cookie', Array.from(jar, ([name, value]) => name + '=' + value).join('; '));
+    }
+    options.headers = headers;
+    options.redirect = options.redirect || 'manual';
+
+    const response = await unitbobRealFetch(new URL(target, unitbobOrigin), options);
+    // A test jar, not a browser's: Path, Domain and Secure are not honoured —
+    // every cookie goes back to the one origin the door serves. An empty value,
+    // Max-Age=0 or a past Expires forgets the cookie.
+    for (const cookie of response.headers.getSetCookie()) {
+      const [pair, ...attributes] = cookie.split(';');
+      const eq = pair.indexOf('=');
+      if (eq === -1) continue; // not a name=value pair; nothing to remember
+      const name = pair.slice(0, eq).trim();
+      const value = pair.slice(eq + 1).trim();
+      const expires = attributes.map((a) => /^\\s*expires=(.+)$/i.exec(a)).find(Boolean);
+      const maxAge = attributes.map((a) => /^\\s*max-age=(-?\\d+)$/i.exec(a)).find(Boolean);
+      const gone = value === '' || (maxAge && Number(maxAge[1]) <= 0) || (expires && new Date(expires[1]).getTime() <= Date.now());
+      if (gone) jar.delete(name);
+      else jar.set(name, value);
+    }
+    return response;
+  };
+});
+
+AfterAll({ timeout: 60000 }, async function () {
+  if (unitbobServer) {
+    // Keep-alive sockets from the scenarios' fetches would keep close() waiting.
+    if (typeof unitbobServer.closeAllConnections === 'function') unitbobServer.closeAllConnections();
+    await new Promise((resolve) => unitbobServer.close(() => resolve()));
+  }
+  if (unitbobApp) await unitbobApp.close().catch(() => {});
+  // A dev-mode Next keeps watchers open, so the process does not end on its own
+  // — the connector runs cucumber-js with \`--exit\` for that.
+});
+`;
+const BEHAVIORAL_WORLD_NEXT_JS = BEHAVIORAL_WORLD_JS + NEXT_DOOR_JS;
 // The Python peer. pytest reads the connector's own ini through \`-c\`, so the
 // project's pytest settings do not apply, and only the conftest.py files on the
 // path from the repository root down to the collected directory are loaded —
@@ -274,11 +449,20 @@ const BEHAVIORAL_WORLDS = {
     'cucumber-js': { path: BEHAVIORAL_WORLD_JS_PATH, content: BEHAVIORAL_WORLD_JS },
     'pytest-bdd': { path: BEHAVIORAL_WORLD_PY_PATH, content: BEHAVIORAL_WORLD_PY },
 };
-export function behavioralWorldFor(runner) {
-    return BEHAVIORAL_WORLDS[runner];
+// The table is by runner; the project is the one exception, and it is named
+// here rather than hidden in the table: on Next.js (spec 56-1) the cucumber-js
+// harness carries the door into the application as well as the network guard.
+// Same path — everything that reasons about *where* the harness is stays a
+// function of the runner alone.
+export function behavioralWorldFor(runner, projectRoot) {
+    const world = BEHAVIORAL_WORLDS[runner];
+    if (world && runner === 'cucumber-js' && projectRoot !== undefined && looksLikeNext(projectRoot)) {
+        return { path: world.path, content: BEHAVIORAL_WORLD_NEXT_JS };
+    }
+    return world;
 }
 export function materializeBehavioralWorld(projectRoot, runner = 'cucumber') {
-    const world = behavioralWorldFor(runner);
+    const world = behavioralWorldFor(runner, projectRoot);
     if (!world)
         return null;
     const worldPath = join(projectRoot, world.path);

package/dist/files/packets.js

@@ -51,7 +51,13 @@ export function readPacketIndex(projectRoot) {
 // written, and before any plan exists: the entrypoints are known from the
 // request, the workers are not, so a packet belongs to an entrypoint and two
 // entrypoints in one file share one packet.
-export function writeSuitePackets(projectRoot, request) {
+//
+// Spec 55-1, §1: the packets agree with the probe. A structural file the
+// runner cannot load gets no packet and a note, for the same reason the probe
+// leaves it out — a worker handed the file would write an import of it and
+// meet the same failure one step later, at `run-local`. `runner` is null when
+// no structural runner was found, and then nothing is filtered.
+export function writeSuitePackets(projectRoot, request, runner = null) {
     const targets = resolveTargets(projectRoot, request);
     const notes = new Map();
     // Regenerated whole, every run. A packet left over from a previous assignment
@@ -67,6 +73,11 @@ export function writeSuitePackets(projectRoot, request) {
             count(notes, 'did not resolve to one file');
             continue;
         }
+        if (target.branch === 'structural' && !isRunnerFile(runner, sourceFile)) {
+            target.note = `not a ${runner} file — left out of the code-structure suite, as the boot check leaves it out`;
+            count(notes, 'not a file this runner can load');
+            continue;
+        }
         // Two entrypoints in one file get one packet, written once, referenced twice.
         if (!written.has(sourceFile) && !refused.has(sourceFile)) {
             const copied = copyPacket(projectRoot, sourceFile);
@@ -122,6 +133,21 @@ function resolveTargets(projectRoot, request) {
     }
     return targets;
 }
+// Spec 55-1, §1. What each structural runner can load: a file with any other
+// extension is not this stack's, whatever the map says about it. Vite fails at
+// import-analysis on the first `.py`, before any setup file runs; pytest and
+// rspec have no reading of a `.ts` at all. The extension lists are the
+// runners' own, not a table of languages: nothing here says what a project is
+// written in, only what one probe can `import`.
+export const RUNNER_EXTENSIONS = {
+    vitest: ['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs'],
+    pytest: ['.py'],
+    rspec: ['.rb'],
+};
+export function isRunnerFile(runner, file) {
+    const extensions = runner ? RUNNER_EXTENSIONS[runner] : undefined;
+    return !extensions || extensions.some((extension) => file.endsWith(extension));
+}
 // Spec 38, criterion 2. The source files the structural guardrails of this
 // request will import — the list the boot check loads instead of the project's
 // own tests. Computed from two artifacts already on this machine, so it costs no
@@ -130,8 +156,15 @@ function resolveTargets(projectRoot, request) {
 // A name nothing answered to is simply absent. That gap is already a visible
 // number — "the source behind N of M entrypoints" — and turning it into a
 // refusal would stop a run over a hole in the graph (see В3 of the requirements).
-export function structuralSourceFiles(projectRoot, request) {
+//
+// Spec 55-1, §1: a file the runner cannot load is not absent but *left out*,
+// and returned as such. On repo 139 the map named Python tools beside a Next.js
+// app, the vitest probe imported them, vite fell over at import-analysis and
+// the vibecoder was sent to repair their code and rebuild the map. One list for
+// the probe and the packets, filtered once, here.
+export function structuralSourceFiles(projectRoot, request, runner) {
     const files = [];
+    const leftOut = [];
     for (const target of resolveTargets(projectRoot, request)) {
         if (target.branch !== 'structural' || !target.source_file)
             continue;
@@ -152,10 +185,11 @@ export function structuralSourceFiles(projectRoot, request) {
             continue;
         if (!existsSync(join(projectRoot, target.source_file)))
             continue;
-        if (!files.includes(target.source_file))
-            files.push(target.source_file);
+        const list = isRunnerFile(runner, target.source_file) ? files : leftOut;
+        if (!list.includes(target.source_file))
+            list.push(target.source_file);
     }
-    return files;
+    return { files, leftOut };
 }
 // The two names a request carries. Structural interfaces name methods
 // (`User#get_token`); behavioral capabilities name addresses (`POST /api/tokens`).

package/dist/files/workerPlan.js

@@ -21,6 +21,29 @@ export function requestDigest(projectRoot) {
 export function workerPlanDigest(projectRoot) {
     return exactFileDigest(workerPlanPath(projectRoot));
 }
+// Spec 55-1, §2. The fingerprint of one slice: its plan item as canonical JSON
+// (keys sorted at every depth, arrays in order), hashed. `plan_digest` covers
+// the whole file and answers "is this the plan on disk"; this one answers "is
+// this still the same job", which is what a finished checkpoint is bound to.
+//
+// Every field counts, `worker_id` and `owned_paths` included: a checkpoint
+// says which files it wrote and which worker wrote them, so a slice that moved
+// its paths or took a new id is a different slice even when its promises are
+// word for word the same. Reordering the workers in the file, or editing a
+// neighbour, changes nothing here.
+export function sliceDigest(item) {
+    return createHash('sha256').update(canonicalJson(item)).digest('hex');
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 // The addresses the request handed to each capability, indexed by id. The
 // checkpoint gate needs them for one question only: was this address given to
 // this slice at all (spec 41, criterion 1). What a slice *left* is not worked out
@@ -48,6 +71,34 @@ export function assignedSurfaces(projectRoot) {
     }
     return byId;
 }
+// Spec 55-1, §4. The marker the request minted for each capability and each
+// structural interface, by id — the `@ubc_…` tag a Scenario must carry and the
+// `[ubc_…]` a structural test names. This is the one reader of markers in
+// `src/`, and it answers one question: which markers were this slice's. What a
+// marker *means* on the map is the server's, and nothing here goes near it.
+export function assignedMarkers(projectRoot) {
+    const request = readRequest(projectRoot);
+    const byId = new Map();
+    for (const branch of Array.isArray(request.branches) ? request.branches : []) {
+        const assignment = branch.assignment;
+        for (const entry of Array.isArray(assignment?.capabilities) ? assignment.capabilities : []) {
+            markerOf(entry, 'capability_id', byId);
+        }
+        for (const block of Array.isArray(assignment?.blocks) ? assignment.blocks : []) {
+            const interfaces = block?.interfaces;
+            for (const entry of Array.isArray(interfaces) ? interfaces : [])
+                markerOf(entry, 'interface_id', byId);
+        }
+    }
+    return byId;
+}
+function markerOf(entry, idField, into) {
+    const record = entry;
+    const id = record?.[idField];
+    const marker = record?.case_marker;
+    if (isNonEmptyString(id) && isNonEmptyString(marker))
+        into.set(id, marker);
+}
 // The task, read as loosely typed JSON.
 //
 // `readSuiteBuildRequest` in `suiteBuild.ts` returns the same file typed, and is
@@ -83,25 +134,38 @@ export function seedWorkerCheckpoints(projectRoot) {
     const plan_digest = workerPlanDigest(projectRoot);
     const written = [];
     const kept = [];
+    const carried = [];
     const superseded = [];
     for (const item of plan.workers) {
         const path = checkpointPath(projectRoot, item);
         const label = `${item.branch}:${item.worker_id}`;
         // Left alone when it already belongs to this plan: the coordinator's facts
         // and a worker's finished slice both live in this file, and a run costs
-        // hours.
-        if (belongsToPlan(path, plan_digest)) {
+        // hours. One field may be added: a checkpoint from before slice digests
+        // existed lacks its own, and the plan it belongs to is its slice.
+        const existing = readCheckpoint(path);
+        if (existing?.plan_digest === plan_digest) {
+            if (existing.slice_digest === undefined) {
+                writeFileSync(path, `${JSON.stringify({ ...existing, slice_digest: sliceDigest(item) }, null, 2)}\n`);
+            }
             kept.push(label);
             continue;
         }
+        // Spec 55-1, §2. A checkpoint from an earlier plan whose own slice did not
+        // change is the same job, finished or not, and it stays. Only the file
+        // digest it is bound to is rewritten; everything a worker or the coordinator
+        // put in it is left as it is. On repo 139 a replan sent 43 of 43 checkpoints
+        // aside for one edited promise, and the copying back fell to a human.
+        if (existing && existing.request_digest === request_digest && existing.slice_digest === sliceDigest(item)) {
+            writeFileSync(path, `${JSON.stringify({ ...existing, plan_digest }, null, 2)}\n`);
+            carried.push(label);
+            continue;
+        }
         // Everything else needs a fresh seed — but the file being replaced is not
-        // necessarily worthless. `plan_digest` is a digest of the whole
-        // `worker-plan.json`, so editing one slice invalidates every checkpoint at
-        // once, including finished ones; and replanning after the first slice comes
-        // back is a documented, ordinary move. Overwriting in place would have made
-        // this verb the one thing in the build that destroys hours of work, on the
-        // most ordinary path there is. Moved for the same reason `suite-prepare`
-        // moves the previous run rather than deleting it.
+        // necessarily worthless: the slice changed, and what was done for the old
+        // one may still be worth reading. Overwriting in place would have made this
+        // verb the one thing in the build that destroys hours of work. Moved for the
+        // same reason `suite-prepare` moves the previous run rather than deleting it.
         if (existsSync(path)) {
             const aside = join(dirname(path), SUPERSEDED_DIR, `${item.branch}-${item.worker_id}.json`);
             mkdirSync(dirname(aside), { recursive: true });
@@ -113,23 +177,26 @@ export function seedWorkerCheckpoints(projectRoot) {
         writeFileSync(path, `${JSON.stringify(seedFor(item, request_digest, plan_digest), null, 2)}\n`);
         written.push(label);
     }
-    return { written, kept, superseded };
+    return { written, kept, carried, superseded };
 }
-function belongsToPlan(path, planDigest) {
+// A checkpoint on disk, or nothing: a missing file and a file that is not a JSON
+// object are the same answer to every question asked here.
+function readCheckpoint(path) {
     if (!existsSync(path))
-        return false;
+        return null;
     try {
         const parsed = JSON.parse(readFileSync(path, 'utf8'));
-        return parsed?.plan_digest === planDigest;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
     }
     catch {
-        return false;
+        return null;
     }
 }
 function seedFor(item, request_digest, plan_digest) {
     return {
         request_digest,
         plan_digest,
+        slice_digest: sliceDigest(item),
         branch: item.branch,
         worker_id: item.worker_id,
         // Every promise starts unresolved: the slice has not been worked yet, and

package/dist/runner/bdd.js

@@ -5,6 +5,7 @@ import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { commandFileOnHost } from "./toolchain.js";
 import { clearReport, readFreshReport } from "./types.js";
 import { PYTEST_BDD_PLUGIN } from "./pytestBddPlugin.js";
+import { looksLikeNext } from "../surfaces/nextRoutes.js";
 export const BDD_TIMEOUT_MS = 10 * 60 * 1000;
 // The behavioral suite lives under one root; the report is written inside it so
 // the app under test cannot pollute it and it travels with the suite.
@@ -44,6 +45,12 @@ const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, PYTEST_INI_NAME);
 const PYTEST_INI = '[pytest]\naddopts =\n';
 // Load order is a fact about both Cucumbers and about neither pytest — pytest
 // picks `conftest.py` up itself, so there is no trap to work around there.
+// Spec 55-1, §7. A step text with a path in it — `I open /start` — is read by
+// both cucumbers as a Cucumber Expression, where `/` is alternation; the
+// expression fails to compile and the runner dies before the first scenario.
+// One line where the worker reads what the runner requires.
+const CUCUMBER_SLASH = '`/` inside a Cucumber Expression means "or"; escape it as `\\/` or use a regular expression for a ' +
+    'step whose text carries a path.';
 const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file is not special to the runner — `account_access` ' +
     'loads before `shared`. Open each capability file with an explicit require of the shared one rather ' +
     'than trusting the alphabet.';
@@ -63,6 +70,7 @@ const BDD_STRATEGIES = {
                 'The connector points `--require` at `step_definitions/`, so every `.rb` file there is loaded. ' +
                     'That explicit `--require` also switches off Cucumber\'s automatic loading of `features/support/`: ' +
                     'a World or helper parked there is never evaluated, and every step then fails on a bare object.',
+                CUCUMBER_SLASH,
                 CUCUMBER_LOAD_ORDER,
             ],
         },
@@ -79,6 +87,7 @@ const BDD_STRATEGIES = {
                 'The connector registers no TypeScript loader, so a `.ts` file cannot compile itself. If you want ' +
                     'one, register the compiler from the file that sorts first — and remember the file registering it ' +
                     'is itself loaded as plain JavaScript.',
+                CUCUMBER_SLASH,
                 CUCUMBER_LOAD_ORDER,
             ],
         },
@@ -177,6 +186,7 @@ async function runCucumberJs(projectRoot, filter) {
         steps,
         '--format',
         `message:${CUCUMBER_REPORT}`,
+        ...cucumberJsExitArgs(projectRoot),
         ...tagArgs(filter, '--tags', '@'),
     ];
     const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
@@ -186,6 +196,15 @@ async function runCucumberJs(projectRoot, filter) {
     });
     return finalize(run, projectRoot, CUCUMBER_REPORT, survivor);
 }
+// Spec 56-1. On Next.js the World starts the application in dev mode inside
+// the cucumber-js process, and a dev Next keeps its watchers open after
+// `close()` — the process would sit there after the last scenario, until the
+// timeout. `--exit` has cucumber-js end it once the report is written. Only on
+// Next: anywhere else nothing is left running, and the flag would only hide a
+// step that leaked a handle. The world probe passes the same flag.
+export function cucumberJsExitArgs(projectRoot) {
+    return looksLikeNext(projectRoot) ? ['--exit'] : [];
+}
 // Python: pytest driving pytest-bdd, with the connector's reporter plugin. The
 // plugin writes the JSON report; `-c` isolates the run from the project's own
 // addopts. The runner command is connector-owned.

package/dist/runner/bootcheck.js

@@ -4,6 +4,7 @@ import { executable } from "../proc.js";
 import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { commandFileOnHost, locateRunner } from "./toolchain.js";
 import { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
+import { isRunnerFile } from "../files/packets.js";
 import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
 import { VITEST_BOOT_CONFIG_FILE, vitestBootConfigSource } from "./vitest.js";
@@ -279,7 +280,13 @@ async function withProbe(projectRoot, files, ask) {
 // `globals: true` in the config we write is what lets it be named without an
 // import (see `writeVitestBootConfig`).
 function vitestProbeSource(sourceFiles) {
-    const imports = sourceFiles.map((file) => `import ${JSON.stringify(`../../${file}`)};`).join('\n');
+    // Belt and braces with `structuralSourceFiles`, which already left these
+    // out: a file vite cannot parse is our resolution falling short, never this
+    // project's code (spec 55-1, §1), and the pytest probe below has kept the
+    // same silence since spec 38.
+    const imports = sourceFiles
+        .filter((file) => isRunnerFile('vitest', file))
+        .map((file) => `import ${JSON.stringify(`../../${file}`)};`).join('\n');
     return `// Written by the unitbob connector before the boot check — do not edit.
 ${imports}
 
@@ -365,12 +372,27 @@ function classify(projectRoot, runner, result, verdict) {
     if (outcome === 'runner_could_not_answer')
         return { status: 'not_checked', reason: 'runner_could_not_answer' };
     const output = `${result.stdout}\n${result.stderr}`.trim();
-    return {
-        status: 'broken',
-        cause: causeOf(output, projectRoot, runner),
-        message: firstErrorLine(output),
-        detail: output.length > DETAIL_LIMIT ? `${output.slice(0, DETAIL_LIMIT)}\n…` : output,
-    };
+    const message = firstErrorLine(output);
+    const detail = output.length > DETAIL_LIMIT ? `${output.slice(0, DETAIL_LIMIT)}\n…` : output;
+    const file = foreignFileParsed(output, projectRoot, runner);
+    if (file)
+        return { status: 'broken', cause: 'harness', file, message, detail };
+    return { status: 'broken', cause: causeOf(output, projectRoot, runner), message, detail };
+}
+// Spec 55-1, §1. Vite's import-analysis stopped on a file this runner has no
+// reading of — a `.py` the map named, say. That file got to vite through our
+// list and nowhere else, so the answer is about the list. Only vite says this;
+// the other runners never see such a file (their probes skip it) and their
+// parse errors mean what they say.
+const FOREIGN_PARSE = /vite:import-analysis|Failed to parse source for import analysis/;
+const REPORTED_FILE = /^\s*File:\s*(\S+?)(?::\d+)*\s*$/m;
+function foreignFileParsed(output, projectRoot, runner) {
+    if (runner !== 'vitest' || !FOREIGN_PARSE.test(output))
+        return null;
+    const file = REPORTED_FILE.exec(output)?.[1];
+    if (!file || isRunnerFile(runner, file))
+        return null;
+    return file.startsWith(`${projectRoot}/`) ? file.slice(projectRoot.length + 1) : file;
 }
 // One concept, not a catalogue of known errors — the lesson spec 32-2 drew from
 // the over-fitted regex scanner of 32-3. "A name that does not resolve to a file
@@ -468,7 +490,11 @@ const SOURCE_FRAME = /([\w.\-/\\]+\.(?:py|rb|ts|tsx|js|jsx|mjs|cjs)):\d+/g;
 // router), and one rule for quoting a failed load is better than two.
 export function firstErrorLine(output) {
     const lines = output.split('\n').map((line) => line.trim()).filter(Boolean);
-    const looksLikeError = /(^|[^A-Za-z])(error|exception|traceback)|:\d+:in |^E\s|\(.*Error\)/i;
+    // `ReferenceError:`, `TypeError:` — a JavaScript error class is one word,
+    // so the letter before `Error` is not a boundary there. `⨯` is the glyph
+    // Next.js opens its own error lines with ("⨯ Another next dev server is
+    // already running").
+    const looksLikeError = /(^|[^A-Za-z])(error|exception|traceback)|:\d+:in |^E\s|\(.*Error\)|^\w*Error:|^\s*⨯ /i;
     return lines.find((line) => looksLikeError.test(line)) ?? lines[0] ?? 'the runner exited without output';
 }
 // The one repair this check performs. A test database is not a repository file