unitbob 0.5.0 → 0.6.0

package/dist/runner/pytestBddPlugin.js

@@ -14,6 +14,15 @@ import os
 _UNITBOB_REPORT = {"version": 1, "scenarios": []}
 _UNITBOB_CURRENT = {}
 
+# Resolved once, at import, and never again. The connector passes this path
+# relative to the project root — a relative path means the same thing whether the
+# run happens on this machine or inside a container, and an absolute host path
+# would name a directory the run cannot see. The working directory is the project
+# root when the plugin loads, so a fixture that changes directory later cannot
+# move the report out from under us.
+_UNITBOB_OUT = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
+_UNITBOB_OUT = os.path.abspath(_UNITBOB_OUT) if _UNITBOB_OUT else None
+
 
 def pytest_bdd_before_scenario(request, feature, scenario):
     _UNITBOB_CURRENT[id(scenario)] = {
@@ -55,8 +64,7 @@ def pytest_bdd_after_scenario(request, feature, scenario):
 
 
 def pytest_sessionfinish(session, exitstatus):
-    out = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
-    if out:
-        with open(out, "w") as handle:
+    if _UNITBOB_OUT:
+        with open(_UNITBOB_OUT, "w") as handle:
             json.dump(_UNITBOB_REPORT, handle)
 `;

package/dist/runner/rspec.js

@@ -1,8 +1,8 @@
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { locateRunner } from "./toolchain.js";
-import { readReport } from "./types.js";
+import { clearReport, readFreshReport } from "./types.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
 // green→red flip can never come from run-order nondeterminism. It does not inherit
@@ -18,13 +18,15 @@ export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // corrupt it.
 //
 // `suitePaths` is every file of the branch in the suite blob's own
-// project-relative form (spec 42, §6.5). Named one by one rather than as a
+// project-relative form (spec 43, §6.5). Named one by one rather than as a
 // directory: the artifact already says exactly which files it is, while a
 // directory would also collect whatever else happens to be sitting under the
 // root.
 export async function runRspecSuite(projectRoot, suitePaths) {
     const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
-    const { result, command, args } = await invokeRspec(projectRoot, [
+    const reportPath = join(projectRoot, RSPEC_RESULT_FILE);
+    const survivor = clearReport(reportPath);
+    const run = await invokeRspec(projectRoot, [
         ...suitePaths,
         '--options',
         optionsPath,
@@ -38,11 +40,9 @@ export async function runRspecSuite(projectRoot, suitePaths) {
         RSPEC_RESULT_FILE,
     ]);
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: RSPEC_RESULT_FILE,
-        report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
+        report: readFreshReport(reportPath, survivor),
     };
 }
 // Which rspec — the sidecar Unitbob installed, the project's own `bin/rspec`
@@ -54,10 +54,12 @@ async function invokeRspec(projectRoot, rspecArgs) {
     const located = locateRunner(projectRoot, 'rspec');
     const command = located?.command ?? 'bundle';
     const args = [...(located?.args ?? ['exec', 'rspec']), ...rspecArgs];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    return runInProject(projectRoot, command, args, {
         timeoutMs: RSPEC_TIMEOUT_MS,
-        env: { ...process.env, ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: {
+            ...located?.env,
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+        },
     });
-    return { result, command, args };
 }

package/dist/runner/toolchain.js

@@ -1,7 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { executable } from "../proc.js";
+import { commandSucceedsInProject } from "./place.js";
 // Where Unitbob keeps a test runner it had to install for itself, together with
 // whatever that runner needs to load the project.
 //
@@ -15,8 +15,42 @@ export const SIDECAR_DIR = '.unitbob/runners';
 export function sidecarPath(projectRoot, ...segments) {
     return join(projectRoot, SIDECAR_DIR, ...segments);
 }
+// The stop that means "nothing here can start this project's test runner"
+// (spec 36, §7.1).
+//
+// It carries no new wording — the four places that throw it say exactly what
+// they said before. All it adds is a name, so that one place at the top can tell
+// this stop apart from "the server did not answer" and "your token was refused",
+// and offer the one piece of advice that only fits this one. Hanging that advice
+// on the individual failure sites instead would have given it to Ruby alone: a
+// pytest project in a container stops somewhere else, with different words, and
+// a vitest one somewhere else again.
+export class ToolchainUnavailableError extends Error {
+    projectRoot;
+    constructor(message, projectRoot) {
+        super(message);
+        this.name = 'ToolchainUnavailableError';
+        this.projectRoot = projectRoot;
+    }
+}
+// The file a command names, on the host's own filesystem.
+//
+// A command that names a file we own is written relative to the project root, so
+// that it means the same thing wherever it is started (spec 36, §4.2). Asking
+// whether that file exists is a different question and is always the host's:
+// under the invariant the connector's files are on the host, and the place sees
+// the very same ones. A command with no path in it — `bundle`, `python3` — is
+// resolved by the place through its own PATH and is returned unchanged.
+export function commandFileOnHost(projectRoot, command) {
+    if (isAbsolute(command) || !command.includes('/'))
+        return command;
+    return join(projectRoot, command);
+}
+// Asked of the place the run will happen in, never of this machine by default
+// (spec 36, §3). `cwd` is the project root at every call site, which is what
+// says which place that is.
 export const defaultToolDeps = {
-    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+    commandSucceeds: (command, args, cwd) => commandSucceedsInProject(cwd, command, args),
 };
 // How to invoke `runner` in this project, or null when nothing here can.
 //
@@ -78,8 +112,9 @@ function locatePytest(projectRoot, deps) {
     // behind. Trusting the file made provisioning report success and the boot
     // check then say "No module named pytest" about an environment we had just
     // built. Found on a Flask project, 2026-08-12.
-    const venvPython = sidecarPath(projectRoot, '.venv', 'bin', 'python');
-    if (executable(venvPython) && deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
+    const venvPython = `${SIDECAR_DIR}/.venv/bin/python`;
+    if (executable(commandFileOnHost(projectRoot, venvPython)) &&
+        deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
         return { command: venvPython, args: ['-m', 'pytest'], source: 'sidecar' };
     }
     for (const python of ['python3', 'python']) {
@@ -94,11 +129,11 @@ function locatePytest(projectRoot, deps) {
 // checks that must not install anything. The vitest runner keeps `npx` as its
 // own last resort, which is the behaviour it has always had.
 function locateVitest(projectRoot) {
-    const sidecar = sidecarPath(projectRoot, 'node_modules', '.bin', 'vitest');
-    if (executable(sidecar))
+    const sidecar = `${SIDECAR_DIR}/node_modules/.bin/vitest`;
+    if (executable(commandFileOnHost(projectRoot, sidecar)))
         return { command: sidecar, args: [], source: 'sidecar' };
-    const project = join(projectRoot, 'node_modules', '.bin', 'vitest');
-    if (executable(project))
+    const project = 'node_modules/.bin/vitest';
+    if (executable(commandFileOnHost(projectRoot, project)))
         return { command: project, args: [], source: 'project' };
     return null;
 }
@@ -115,8 +150,11 @@ function locateRspec(projectRoot) {
             source: 'sidecar',
         };
     }
-    const binstub = join(projectRoot, 'bin', 'rspec');
-    if (executable(binstub))
+    // Relative, and the slash is not decoration: `spawn` resolves a command
+    // against the working directory only when it has one, and a bare `rspec` would
+    // go looking on PATH — a different command altogether.
+    const binstub = 'bin/rspec';
+    if (executable(commandFileOnHost(projectRoot, binstub)))
         return { command: binstub, args: [], source: 'project' };
     return { command: 'bundle', args: ['exec', 'rspec'], source: 'project' };
 }

package/dist/runner/types.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
 // Read a report file back verbatim. A missing or unreadable file is a clean
 // empty string, not a throw: the caller reports a structured suite error.
 export function readReport(path) {
@@ -9,3 +9,47 @@ export function readReport(path) {
         return '';
     }
 }
+// Clear the report before a run, and hand back whatever survived the attempt
+// (spec 36, criterion 9).
+//
+// The report is written to a fixed path with no run marker on it, and — once the
+// run happens in a container — into a folder both sides share. A run we gave up
+// on can leave a process alive inside that container, and that process finishes
+// and writes the report after we stopped waiting. The next run would then read a
+// file belonging to a run nobody watched, and report a green result nobody
+// earned. Having no result at all is the better of the two.
+//
+// What comes back is the modification time of a file that would not delete —
+// a read-only mount, a permission we do not have — so the read below can tell
+// "the same file, still there" from "a new one the run just wrote". Nothing is
+// compared against this machine's clock: both stamps come from whoever wrote the
+// file, so a container whose clock differs from the host's cannot make a good
+// report look stale.
+export function clearReport(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Could not remove it. That is exactly the case the stamp below covers.
+    }
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// The report of *this* run, or nothing. `survivor` is what `clearReport`
+// returned before the run started.
+export function readFreshReport(path, survivor) {
+    if (survivor !== null) {
+        try {
+            if (statSync(path).mtimeMs === survivor)
+                return '';
+        }
+        catch {
+            return '';
+        }
+    }
+    return readReport(path);
+}

package/dist/runner/vitest.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { locateRunner } from "./toolchain.js";
-import { readReport } from "./types.js";
+import { clearReport, readFreshReport } from "./types.js";
 export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
 // A connector-owned Vitest config, written next to .unitbob/ before a run when
@@ -37,7 +37,7 @@ const PROJECT_CONFIGS = [
 // file of the branch in `include`, and the positional filters keep the run to
 // exactly those files.
 //
-// Named files rather than a directory glob, since spec 42, §6.5 made a branch
+// Named files rather than a directory glob, since spec 43, §6.5 made a branch
 // several files: the artifact already says which files it is, and a glob would
 // have to guess a naming convention nothing enforces. `include` is written even
 // when the project has no config of its own — Vitest's default include only
@@ -63,17 +63,16 @@ export async function runVitestSuite(projectRoot, suitePaths) {
         '--reporter=json',
         `--outputFile=${VITEST_RESULT_FILE}`,
     ];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const reportPath = join(projectRoot, VITEST_RESULT_FILE);
+    const survivor = clearReport(reportPath);
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: VITEST_TIMEOUT_MS,
-        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...located?.env, UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: VITEST_RESULT_FILE,
-        report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
+        report: readFreshReport(reportPath, survivor),
     };
 }
 // Returns the `--config` args to add, writing the config first. Always written:

package/dist/runner/worldProbe.js

@@ -1,36 +1,35 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
 import { BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
+import { BEHAVIORAL_GEMFILE } from "./bdd.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
 const PROBE_ROOT = '.unitbob/suite-build/world-probe';
 export async function probeBehavioralWorld(projectRoot, deps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        env: options.env,
-        timeoutMs: PROVISION_TIMEOUT_MS,
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: PROVISION_TIMEOUT_MS }),
 }) {
+    // Written on the host, named to the run relative to the project root — the
+    // same shape `bdd.ts` has always had, and the reason nothing here needs a path
+    // rewritten when the run happens somewhere else (spec 36, §4.2).
+    const feature = `${PROBE_ROOT}/world.feature`;
+    const steps = `${PROBE_ROOT}/world_steps.rb`;
     const probeRoot = join(projectRoot, PROBE_ROOT);
-    const feature = join(probeRoot, 'world.feature');
-    const steps = join(probeRoot, 'world_steps.rb');
     mkdirSync(probeRoot, { recursive: true });
-    writeFileSync(feature, PROBE_FEATURE);
-    writeFileSync(steps, PROBE_STEPS);
+    writeFileSync(join(projectRoot, feature), PROBE_FEATURE);
+    writeFileSync(join(projectRoot, steps), PROBE_STEPS);
     try {
         const result = await deps.runCmd('bundle', [
             'exec', 'cucumber', feature,
-            '--require', join(projectRoot, BEHAVIORAL_WORLD_PATH),
+            '--require', BEHAVIORAL_WORLD_PATH,
             '--require', steps,
             '--format', 'progress',
         ], {
             cwd: projectRoot,
             env: {
-                ...process.env,
                 RAILS_ENV: 'test',
                 CUCUMBER_PUBLISH_QUIET: 'true',
-                UNITBOB_REPO_ROOT: projectRoot,
-                BUNDLE_GEMFILE: join(projectRoot, '.unitbob', 'behavioral', 'Gemfile'),
+                UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+                BUNDLE_GEMFILE: BEHAVIORAL_GEMFILE,
             },
         });
         if (result.code === 0)
@@ -52,6 +51,9 @@ const PROBE_FEATURE = `Feature: Unitbob World profile
 
   Scenario: supported state is clean at the next scenario boundary
     Then the second World probe scenario sees clean state and fresh mocks
+
+  Scenario: outgoing HTTP does not leave the machine
+    Then the World probe cannot reach the network
 `;
 const PROBE_STEPS = `PROBE_VERSION = "unitbob-world-probe-#{Process.pid}"
 PROBE_TIME_ZONE = Time.zone
@@ -84,6 +86,16 @@ Then('its integration assertion counter advances') do
   expect(unitbob_session.assertions).to be > 0
 end
 
+# Spec 35-1, criterion 2. Checked here rather than trusted, because the failure
+# it guards against is invisible from inside: a suite whose WebMock never came on
+# passes exactly the same way, and only the other end of the wire ever finds out.
+Then('the World probe cannot reach the network') do
+  require 'net/http'
+  expect {
+    Net::HTTP.get(URI('http://unitbob-world-probe.invalid/'))
+  }.to raise_error(WebMock::NetConnectNotAllowedError)
+end
+
 Then('the second World probe scenario sees clean state and fresh mocks') do
   quoted = @unitbob_connection.quote(PROBE_VERSION)
   count = @unitbob_connection.select_value("SELECT COUNT(*) FROM schema_migrations WHERE version = #{quoted}").to_i

package/dist/surfaces/routeInventory.js

@@ -1,18 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { runProcess } from "../proc.js";
+import { executable } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
+import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.js";
 import { detectStructuralRunner } from "../runner/precheck.js";
 import { graphPath } from "../files/mapBuild.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
 const ROUTES_TIMEOUT_MS = 120_000;
+// The router is the application's own, so asking it is a project command and
+// goes where the project's dependencies live (spec 36, §5). Unlike every other
+// caller this one is allowed to fail: silence is already a normal answer here,
+// so a project whose container is misconfigured loses its route inventory and
+// nothing else.
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        timeoutMs: ROUTES_TIMEOUT_MS,
-        env: { ...process.env, ...options.env },
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: ROUTES_TIMEOUT_MS, env: options.env }),
 };
 export function routeInventoryPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'map-build', 'route_inventory.json');
@@ -202,16 +204,16 @@ end`;
 // `default` means we leave RAILS_ENV alone and take whatever the project's own
 // setup chooses.
 async function askRouterOnce(projectRoot, deps, environment) {
-    const local = join(projectRoot, 'bin', 'rails');
-    const [command, args] = existsSync(local)
-        ? [local, ['runner', ROUTES_SCRIPT]]
+    const [command, args] = executable(join(projectRoot, 'bin', 'rails'))
+        ? ['bin/rails', ['runner', ROUTES_SCRIPT]]
         : ['bundle', ['exec', 'rails', 'runner', ROUTES_SCRIPT]];
+    const repoRoot = projectRootAsSeenByThePlace(projectRoot);
     try {
         return await deps.runCmd(command, args, {
             cwd: projectRoot,
             env: environment === 'test'
-                ? { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot }
-                : { UNITBOB_REPO_ROOT: projectRoot },
+                ? { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: repoRoot }
+                : { UNITBOB_REPO_ROOT: repoRoot },
         });
     }
     catch {
@@ -415,7 +417,7 @@ export function inventoryProblems(inventory, surfaces) {
 // either printed by the router or copied out of the graph. A blank is not a gap
 // to be helpfully filled — an invented `source_file` is the same failure as an
 // invented address, one field over, and a `handler_symbol` swapped for another
-// node that happens to exist passes the host's check while sending spec 36's
+// node that happens to exist passes the host's check while sending spec 38's
 // trace into the wrong code.
 const LINK_FIELDS = ['source_file', 'handler_symbol'];
 // Not a link and nothing downstream reads it — but spec 32-7 took the authoring

package/dist/verbs/codexInstall.js

@@ -2,27 +2,62 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
+// The four named roles, in one place. Everything that counts them counts this
+// list — see the message at the bottom, which used to carry the number as a
+// literal and spent a release saying "Installed 3" beside four names.
+export const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
 const bundledAgentsDir = fileURLToPath(new URL('../../plugin/codex/agents/', import.meta.url));
+const LABEL = {
+    created: 'created:        ',
+    updated: 'updated:        ',
+    current: 'already current:',
+};
+// Install (or refresh) the bounded Codex role definitions in the user's agent
+// directory.
+//
+// This used to refuse when an installed file differed from the bundled one, to
+// protect a definition the user had edited by hand. The case it actually met was
+// the ordinary one: an upgrade from an older release, where every file differs
+// and every install therefore failed. Spec 44, §1.6.
+//
+// The refusal became actively harmful once the workflows started asking a role
+// whether this session can see it. A stale role answers that question exactly
+// like a current one, so an update nobody could apply reads as "fully equipped"
+// — the check would pass and the run would proceed on last release's
+// instructions. So the file is overwritten, and what changed is said out loud
+// rather than left for the user to discover.
 export function installCodexAgents(args, deps = { home: homedir(), stdout: process.stdout }) {
     if (args.length > 0)
         throw new Error('codex-install accepts no arguments.');
     const targetDir = join(deps.home, '.codex', 'agents');
-    const files = AGENT_NAMES.map((name) => ({
-        source: join(bundledAgentsDir, `${name}.toml`),
-        target: join(targetDir, `${name}.toml`),
-    }));
-    for (const file of files) {
-        if (!existsSync(file.target))
-            continue;
-        if (readFileSync(file.target, 'utf8') === readFileSync(file.source, 'utf8'))
-            continue;
-        throw new Error(`Refusing to overwrite existing Codex agent definition: ${file.target}`);
-    }
     mkdirSync(targetDir, { recursive: true });
-    for (const file of files) {
-        if (!existsSync(file.target))
-            copyFileSync(file.source, file.target);
+    const byOutcome = { created: [], updated: [], current: [] };
+    for (const name of AGENT_NAMES) {
+        const source = join(bundledAgentsDir, `${name}.toml`);
+        const target = join(targetDir, `${name}.toml`);
+        const outcome = outcomeFor(source, target);
+        if (outcome !== 'current')
+            copyFileSync(source, target);
+        byOutcome[outcome].push(`${name}.toml`);
     }
-    deps.stdout.write(`Installed 3 Unitbob Codex agent definitions in ${targetDir}. Start a new Codex thread before running Unitbob.\n`);
+    const changes = ['created', 'updated', 'current']
+        .filter((outcome) => byOutcome[outcome].length > 0)
+        .map((outcome) => `  ${LABEL[outcome]} ${byOutcome[outcome].join(', ')}`);
+    // The reason is attached only when something actually changed, and it is
+    // worded to be true of both ways it can change. "A thread open before these
+    // files existed" is true of a first install and false of an upgrade, where the
+    // files did exist — and the upgrade is the case that matters most, because a
+    // thread holding last release's definition answers a readiness check exactly
+    // like a current one.
+    const changed = byOutcome.created.length + byOutcome.updated.length > 0;
+    const why = changed
+        ? ' — a thread already open is running the definitions it read when it started, not these'
+        : '';
+    deps.stdout.write(`${AGENT_NAMES.length} Unitbob Codex agent definitions in ${targetDir}:\n${changes.join('\n')}\n` +
+        `Start a new Codex thread before running Unitbob${why}.\n`);
+}
+function outcomeFor(source, target) {
+    if (!existsSync(target))
+        return 'created';
+    return readFileSync(target, 'utf8') === readFileSync(source, 'utf8') ? 'current' : 'updated';
 }

package/dist/verbs/mapPrepare.js

@@ -1,4 +1,4 @@
-import { ensureUnitbobIgnored, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
+import { ensureUnitbobIgnored, ignoreExclusions, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
 import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
 import { Wire } from "../wire.js";
@@ -10,9 +10,20 @@ export async function mapPrepare(config, _args = [], deps) {
         runGraphifyExtractKeyless,
         extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
+        stdout: process.stdout,
         ...deps,
     };
     actual.ensureUnitbobIgnored(config.projectRoot);
+    // Said before the graph is built, because after it there is nothing left to
+    // see: whatever these patterns matched never becomes a node, and a subsystem
+    // that is missing from the map looks exactly like a subsystem that was never
+    // written. One line per pattern that actually took something; a pattern that
+    // matched nothing is not news (spec 35-1, criterion 1).
+    const exclusions = ignoreExclusions(config.projectRoot);
+    if (exclusions.length > 0) {
+        actual.stdout.write('Kept out of the graph by .graphifyignore — nothing below can appear on the map:\n' +
+            exclusions.map((entry) => `  ${entry.pattern} — ${entry.files} file${entry.files === 1 ? '' : 's'}\n`).join(''));
+    }
     await actual.requireGraphify();
     // Keyless: refresh the one canonical graph in place. No inference secret and no
     // graph flags — semantic enrichment is host-LLM work, not a keyed LLM here.
@@ -31,7 +42,7 @@ export async function mapPrepare(config, _args = [], deps) {
     // Said out loud first, because asking a router means booting the application
     // and that can take a minute or two with nothing on the screen. Silence from
     // us there reads as a hang.
-    process.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
+    actual.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
     const inventory = await actual.extractRouteInventory(config.projectRoot);
     const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
         actual.getRecipe('decompose'),
@@ -45,9 +56,9 @@ export async function mapPrepare(config, _args = [], deps) {
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
     }, inventory.status === 'written' ? inventory.path : undefined);
-    process.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
-    process.stdout.write(`${describeRouteInventory(inventory)}\n`);
-    process.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
+    actual.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
+    actual.stdout.write(`${describeRouteInventory(inventory)}\n`);
+    actual.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
         `${packet.output_path} (recipes.decompose, recipes.relate), and the surface map at ` +
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
         'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');

package/dist/verbs/putSuiteBuild.js

@@ -1,4 +1,5 @@
 import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { placeProblem } from "../runner/place.js";
 import { collectBuildProblems } from "./validateBuild.js";
 import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.js";
 import { Wire } from "../wire.js";
@@ -20,6 +21,12 @@ import { Wire } from "../wire.js";
 // Returns the server's per-branch results so the caller can compose the first run
 // on top of them (spec 32-4) without parsing the lines printed here.
 export async function putSuiteBuild(config, _args = [], deps) {
+    // Spec 36, criterion 7. Publishing is followed immediately by a first run, so
+    // a place that cannot be used is not something to discover after the suite is
+    // stored on the server.
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was uploaded.`);
     const request = readSuiteBuildRequest(config.projectRoot);
     // Spec 32-6: read branch by branch, so one unreadable entry neither hides the
     // next branch's problems nor sinks a peer that is finished and correct.
@@ -39,7 +46,7 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
-    // Since spec 42 that check is exactly one question, and it is about a branch
+    // Since spec 43 that check is exactly one question, and it is about a branch
     // the answer has *no* entry for: everything else it used to ask is now asked
     // of the server, by a dry run, before this command runs at all. So its
     // problems can never land on a branch this loop visits, and they are reported
@@ -122,7 +129,7 @@ function printResult(result) {
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
     return (`${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.` + printDowngrades(result));
 }
-// Spec 42, §7. A capability every one of whose Scenarios the review objected to
+// Spec 43, §7. A capability every one of whose Scenarios the review objected to
 // is stored `unguarded` by the publish. The run is standing right here when that
 // is decided, so it is told here, in the server's own words — finding it on the
 // map afterwards is how a run finishes believing it published a guarantee it did

package/dist/verbs/run.js

@@ -1,5 +1,7 @@
 import { materializeGuardrails } from "../files/guardrails.js";
 import { materializeBehavioral } from "../files/behavioral.js";
+import { placeProblem } from "../runner/place.js";
+import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite } from "../runner/vitest.js";
@@ -28,7 +30,7 @@ function resolve(config, deps) {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
-        // since spec 42, §6, and picking `path` and `content` out of it here was
+        // since spec 43, §6, and picking `path` and `content` out of it here was
         // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
@@ -44,6 +46,12 @@ function resolve(config, deps) {
     };
 }
 async function execute(config, d, only) {
+    // Spec 36, criterion 7. Before the first suite is fetched: a run that cannot
+    // happen where this project's dependencies live has nothing honest to file,
+    // and the whole batch would go up as suite errors describing the wrong thing.
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was run and no results were filed.`);
     const suites = await d.getSuites();
     const ready = suites.filter((item) => item.status === 'ready');
     const selected = only === null ? ready : select(ready, only);
@@ -137,7 +145,7 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     }
 }
 // Every file of the branch, in the order the envelope carries them. A structural
-// branch is one file per assignment since spec 42, §6, and running only the main
+// branch is one file per assignment since spec 43, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
 function artifactPaths(file) {
     return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];