unitbob 0.2.8 → 0.3.0

package/README.md

@@ -7,7 +7,8 @@ Works with Ruby on Rails (RSpec), JavaScript/TypeScript (Vitest), and Python
 (pytest) projects — the guardrail tests are generated in your project's own
 language and run with its native test runner.
 
-You work through Claude Code. You need: Node 18+, Python 3.10+.
+You work through a coding agent — Claude Code or Codex both work. You need:
+Node 18+, Python 3.10+.
 
 ---
 
@@ -27,6 +28,8 @@ claude plugin install unitbob@unitbob
 
 Restart the session so the commands load.
 
+In Codex it is the same — the same install, and the same phrasings below.
+
 ---
 
 ## Full cycle
@@ -36,15 +39,21 @@ Just type it in the chat. There is nothing to memorise and no command to get rig
 | Step | Say this |
 |------|----------|
 | 1. Build the map | `Build my Unitbob map` |
-| 2. Generate tests | `Generate the guardrail tests` |
-| 3. Run the checks | `Run the checks` |
-| 4. Fix a red lamp | `Fix guardrail <id>` |
-| 5. Open the map | `Open my Unitbob map` |
+| 2. Generate the tests | `Generate the guardrail tests` |
+| 3. Fix a red lamp | `Fix guardrail <id>` |
+| 4. Open the map | `Open my Unitbob map` |
+
+Step 2 lights the lamps by itself: generating the tests also runs them and sends
+the results. You do not have to ask for a run to see the first result.
+
+Say `Run the checks` later, whenever you want the lamps refreshed against your
+current code — or to finish the job if a generation was interrupted after the
+tests were saved but before they ran.
 
-There are also `/unitbob:map`, `/unitbob:suite` and friends, but they work only
-inside a Claude Code terminal, and only in a session started after the plugin was
-installed — in a browser or desktop window they are not recognised at all. The
-phrasings above work everywhere, so they are the ones documented here.
+In Claude Code there are also `/unitbob:map`, `/unitbob:suite` and friends, but
+they work only in a terminal session started after the plugin was installed — in
+a browser or desktop window they are not recognised at all. The phrasings above
+work everywhere, so they are the ones documented here.
 
 ---
 
@@ -52,5 +61,5 @@ phrasings above work everywhere, so they are the ones documented here.
 
 - **Green lamp** — the behavior works.
 - **Red lamp** — something the structure relied on broke. Copy its `id` and run
-  step 4.
+  step 3.
 - The project links itself by folder name — nothing to set up by hand.

package/dist/cli.js

@@ -8,30 +8,44 @@
 // into a single user operation, so `publishAndRun` at the bottom of this file
 // holds that sequence and the exit code it implies (spec 32-4). Every other verb
 // keeps its whole flow in its own module under `verbs/`.
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
 import { run, runOnly } from "./verbs/run.js";
 import { init } from "./verbs/init.js";
 import { mapPrepare } from "./verbs/mapPrepare.js";
+import { extractSurfaces } from "./verbs/extractSurfaces.js";
 import { putMapBuild } from "./verbs/putMapBuild.js";
 import { suitePrepare } from "./verbs/suitePrepare.js";
 import { classifyPublication, putSuiteBuild } from "./verbs/putSuiteBuild.js";
+import { validateBuild } from "./verbs/validateBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
-Usage: unitbob <verb> [args]
+Usage: unitbob [--project-root <dir>] <verb> [args]
+
+Options:
+  --project-root <dir> Run against this project instead of the current folder.
+                       Without it, an already-linked project is found by walking
+                       up from where you are, so a subfolder works too.
 
 Verbs:
   init                 Link this project to Unitbob (also happens automatically).
   recipe <name>        Fetch and print a recipe from the server.
   show                 Print the link to this project's map.
   map-prepare          Internal: keylessly update the graph (no API key) and write the host map-build request.
+  extract-surfaces     Internal: write the addresses this project's own router declares, when the stack
+                       can be asked for them. Says nothing when it cannot, which is a normal answer;
+                       map-prepare runs it for you.
   put-map-build        Internal: upload the host-built map and graph.
   suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
   suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
+  validate-build       Internal: check the host's suite answer against the request, locally, before
+                       uploading. Reports every problem at once; put-suite-build runs it too.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
                        then run every branch it published and report the server's results.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
@@ -51,45 +65,57 @@ host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify sk
 Config: .unitbob.json at your project root, created automatically: the first
 run registers the project on the server by its folder name (spec 28).`;
 export async function main(argv, deps = { ensureLinked }) {
-    const [verb, ...args] = argv;
+    const parsed = parseGlobalFlags(argv);
+    if (parsed.error) {
+        process.stderr.write(`${parsed.error}\n`);
+        return 1;
+    }
+    const [verb, ...args] = parsed.rest;
     if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
         process.stdout.write(`${USAGE}\n`);
         return verb ? 0 : 1;
     }
+    const linked = () => deps.ensureLinked(parsed.root);
     try {
         switch (verb) {
             case 'init':
                 await init(args);
                 return 0;
             case 'recipe':
-                await recipe(await deps.ensureLinked(), args);
+                await recipe(await linked(), args);
                 return 0;
             case 'show':
-                await show(await deps.ensureLinked());
+                await show(await linked());
                 return 0;
             case 'map-prepare':
-                await mapPrepare(await deps.ensureLinked(), args);
+                await mapPrepare(await linked(), args);
+                return 0;
+            case 'extract-surfaces':
+                await extractSurfaces(await linked(), args);
                 return 0;
             case 'put-map-build':
-                await putMapBuild(await deps.ensureLinked(), args);
+                await putMapBuild(await linked(), args);
                 return 0;
             case 'suite-prepare':
-                await suitePrepare(await deps.ensureLinked(), args);
+                await suitePrepare(await linked(), args);
                 return 0;
             case 'suite-review-prepare':
-                await suiteReviewPrepare(await deps.ensureLinked(), args);
+                await suiteReviewPrepare(await linked(), args);
+                return 0;
+            case 'validate-build':
+                await validateBuild(await linked(), args);
                 return 0;
             case 'put-suite-build':
-                return await publishAndRun(await deps.ensureLinked(), args);
+                return await publishAndRun(await linked(), args);
             case 'fix-prepare':
-                await fixPrepare(await deps.ensureLinked(), args);
+                await fixPrepare(await linked(), args);
                 return 0;
             case 'contract-prompt':
-                await contractPrompt(await deps.ensureLinked(), args);
+                await contractPrompt(await linked(), args);
                 return 0;
             case 'run':
             case 'check':
-                await run(await deps.ensureLinked(), args);
+                await run(await linked(), args);
                 return 0;
             default:
                 process.stderr.write(`Unknown verb "${verb}".\n\n${USAGE}\n`);
@@ -101,6 +127,42 @@ export async function main(argv, deps = { ensureLinked }) {
         return 1;
     }
 }
+// `--project-root` names the folder the verb runs in, for callers that cannot
+// change directory — an agent driving the CLI from a scratch directory, a hook,
+// a monorepo script. It is the explicit form of what `ensureLinked` already does
+// by walking up, and it accepts the `project_root` a request packet prints, so
+// the packet's own answer can be handed straight back.
+//
+// Parsed here rather than per verb: every verb resolves the same project, and a
+// flag that means one thing for `check` and another for `suite-prepare` is worse
+// than no flag.
+function parseGlobalFlags(argv) {
+    const rest = [];
+    let root;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === PROJECT_ROOT_FLAG) {
+            root = argv[index + 1];
+            index += 1;
+        }
+        else if (arg.startsWith(`${PROJECT_ROOT_FLAG}=`)) {
+            root = arg.slice(PROJECT_ROOT_FLAG.length + 1);
+        }
+        else {
+            rest.push(arg);
+        }
+        if (root !== undefined && !root)
+            return { rest, error: `${PROJECT_ROOT_FLAG} requires a path.` };
+    }
+    if (root === undefined)
+        return { rest };
+    const resolved = resolve(root);
+    if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+        return { rest, error: `${PROJECT_ROOT_FLAG} ${root} is not a directory.` };
+    }
+    return { root: resolved, rest };
+}
+const PROJECT_ROOT_FLAG = '--project-root';
 // Publishing a suite and running it the first time are one user operation
 // (spec 32-4). They used to be two commands, and the second one was a step the
 // host LLM could simply not take: the suite was stored, nothing had ever run it,
@@ -114,11 +176,17 @@ export async function main(argv, deps = { ensureLinked }) {
 // comes from the build response, and what the results are comes only from the
 // server's answer to the run.
 export async function publishAndRun(config, args, deps) {
+    // Resolved before the collaborators, so both halves of the command write to
+    // the same stream. Injecting `stdout` has to capture everything the command
+    // prints — publication lines and run summaries included — or a test can hold a
+    // fraction of the output and read it as the whole of it.
+    const stdout = deps?.stdout ?? process.stdout;
+    const stderr = deps?.stderr ?? process.stderr;
     const d = {
-        putSuiteBuild: (cfg, a) => putSuiteBuild(cfg, a),
-        runOnly: (cfg, digests) => runOnly(cfg, digests),
-        stdout: process.stdout,
-        stderr: process.stderr,
+        putSuiteBuild: (cfg, a) => putSuiteBuild(cfg, a, { stdout }),
+        runOnly: (cfg, digests) => runOnly(cfg, digests, { stdout }),
+        stdout,
+        stderr,
         ...deps,
     };
     const { digests, unpublished } = classifyPublication(await d.putSuiteBuild(config, args));

package/dist/config.js

@@ -1,11 +1,19 @@
 // Per-project config for the connector. Lives in `.unitbob.json` at the project
-// root: { "server": "http://…", "repo_id": 3 }. No secret — auth is deferred
-// (spec 15, decision #3). Linking is automatic (spec 28): every verb goes
+// root: { "server": "http://…", "repo_id": 3, "token": "…" }.
+//
+// The token is the project's key (spec 33): the brain mints it at register, every
+// wire call carries it, and this file is the only place a person has it. It is
+// gitignored — see ensureGitignored — because a committed token hands the project
+// to whoever reads the repository. Lose the file and the project is gone: there
+// is no recovery and no rotation, which is written down in the spec as accepted.
+//
+// Linking is automatic (spec 28): every verb goes
 // through `ensureLinked` (src/link.ts), which registers the project by folder
 // name when there is no working link. Only the project root's own file counts —
 // never a parent directory's (no walk-up).
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 export const CONFIG_FILE = '.unitbob.json';
 // The repo id stored at `cwd`, or null when there is no working link: file
 // missing, unreadable, malformed JSON, or repo_id absent / 0 / non-integer
@@ -22,6 +30,13 @@ export function readLocalServer(cwd) {
     const server = readConfigField(cwd, 'server');
     return typeof server === 'string' && /^https?:\/\//.test(server.trim()) ? server.trim() : null;
 }
+// The token stored at `cwd`, or null when there is none. A project linked
+// before spec 33 has an id and no token; its calls now 404, and the connector
+// says so in words rather than showing a bare status.
+export function readLocalToken(cwd) {
+    const token = readConfigField(cwd, 'token');
+    return typeof token === 'string' && token.length > 0 ? token : null;
+}
 function readConfigField(cwd, field) {
     const path = join(cwd, CONFIG_FILE);
     if (!existsSync(path))
@@ -35,6 +50,29 @@ function readConfigField(cwd, field) {
     }
     return parsed && typeof parsed === 'object' ? parsed[field] : undefined;
 }
+// The nearest directory at or above `cwd` that already carries a working link,
+// or null when there is none.
+//
+// This does not weaken the no-walk-up rule above — it is what makes it usable.
+// The rule exists so a parent's repo_id can never stand in for the directory
+// the verb is running in; a sub-package would silently report as its monorepo.
+// Relocating to the directory whose own file names the link keeps that intact:
+// the config still belongs to the root it sits in, and the verb runs there.
+// Without this, every command had to be run from exactly the right folder, and
+// the request packet's own `project_root` could not be used as a working
+// directory even though it names the answer.
+//
+// $HOME is the ceiling: a stray `.unitbob.json` in the home directory must not
+// adopt every project underneath it.
+export function locateLinkedRoot(cwd) {
+    const home = homedir();
+    for (let dir = cwd;; dir = dirname(dir)) {
+        if (readLocalRepoId(dir) !== null)
+            return dir;
+        if (dir === home || dirname(dir) === dir)
+            return null;
+    }
+}
 export function writeConfigFile(cwd, config) {
     writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);
 }

package/dist/files/behavioral.js

@@ -1,6 +1,7 @@
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
+import { BDD_RUN_ARTIFACTS } from "../runner/bdd.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/`,
@@ -51,7 +52,7 @@ export function filesLostOnMaterialize(projectRoot, artifact, runner) {
     const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     return readdirSync(behavioralRoot)
-        .filter((entry) => !runnerEntries.has(entry))
+        .filter((entry) => !runnerEntries.has(entry) && !CONNECTOR_RUN_ARTIFACTS.has(entry))
         .flatMap((entry) => filesUnder(projectRoot, `${BEHAVIORAL_DIR}/${entry}`))
         .filter((path) => !listed.has(path))
         .sort();
@@ -78,6 +79,13 @@ export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner)
         cpSync(source, target, { recursive: true });
     }
 }
+// Written into the behavioral root by the connector's own BDD run: the machine
+// report and the pytest-bdd harness it drives the run with. They are regenerated
+// by the next run, so materialization is right to clear them — but warning about
+// them names the connector's own files as the user's loss. It made the warning
+// fire on every single review, which is how a real forgotten step file learns to
+// look like noise. Taken from the runner that writes them, never re-typed here.
+const CONNECTOR_RUN_ARTIFACTS = new Set(BDD_RUN_ARTIFACTS);
 const EMPTY_ENTRIES = new Set();
 const RUNNER_ENVIRONMENT_ENTRIES = {
     cucumber: new Set(['.bundle', 'Gemfile', 'Gemfile.lock']),

package/dist/files/mapBuild.js

@@ -28,13 +28,14 @@ export function readFreshGraph(projectRoot) {
     parseJson(rawGraphJson, path);
     return rawGraphJson;
 }
-export function writeMapBuildRequest(projectRoot, recipes) {
+export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath) {
     const packet = {
         project_root: projectRoot,
         graph_path: graphPath(projectRoot),
         output_path: outputPath(projectRoot),
         surfaces_path: surfacesPath(projectRoot),
         surface_output_path: surfaceOutputPath(projectRoot),
+        ...(routeInventoryPath ? { route_inventory_path: routeInventoryPath } : {}),
         recipes,
     };
     const path = requestPath(projectRoot);

package/dist/files/suiteBuild.js

@@ -222,6 +222,39 @@ function readKnownDefectContext(value, path) {
 // build_error, which the connector relays. Anything unparseable throws and
 // nothing is uploaded.
 export function readHostSuiteOutputs(path, request) {
+    const { entries, rootFor } = openAnswer(path, request);
+    return entries.map((entry) => readBranch(entry, rootFor, path, request.project_root));
+}
+// The same read, but one branch's bad entry does not hide the next branch's.
+//
+// Spec 32-6, after review: the throwing form above stops at the first problem,
+// so an unsafe path in one branch concealed every remaining problem in its peer
+// — and the promise this validation was built on is that all problems are named
+// in one pass. It also sank a finished peer branch, which is the exact rule spec
+// 32-5 Phase 4 established against.
+//
+// What still throws is the answer as a whole: a file that is missing, is not
+// JSON, or carries no branches array has no second problem to go and find,
+// because there is no document left to read.
+export function readHostSuiteOutputsPerBranch(path, request) {
+    const { entries, rootFor } = openAnswer(path, request);
+    const outputs = [];
+    const unreadable = [];
+    for (const entry of entries) {
+        try {
+            outputs.push(readBranch(entry, rootFor, path, request.project_root));
+        }
+        catch (err) {
+            const kind = entry?.suite_kind;
+            unreadable.push({
+                suite_kind: typeof kind === 'string' && kind ? kind : 'unknown branch',
+                message: err.message,
+            });
+        }
+    }
+    return { outputs, unreadable };
+}
+function openAnswer(path, request) {
     if (!existsSync(path)) {
         throw new Error(`${path} not found — the host suite builder did not write its output.`);
     }
@@ -230,8 +263,10 @@ export function readHostSuiteOutputs(path, request) {
     if (!branches) {
         throw new Error(`${path} is malformed: expected a branches array, one entry per contract system.`);
     }
-    const rootFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root]));
-    return branches.map((entry) => readBranch(entry, rootFor, path, request.project_root));
+    return {
+        entries: branches,
+        rootFor: new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root])),
+    };
 }
 function readBranch(entry, rootFor, path, projectRoot) {
     if (!entry || typeof entry !== 'object') {

package/dist/link.js

@@ -5,29 +5,42 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
-import { CONFIG_FILE, readLocalRepoId, readLocalServer, writeConfigFile } from "./config.js";
+import { CONFIG_FILE, locateLinkedRoot, readLocalRepoId, readLocalServer, readLocalToken, writeConfigFile, } from "./config.js";
 import { registerRepo, WireError } from "./wire.js";
 // Public Unitbob brain used by default. A `server` in `.unitbob.json` (or an
 // explicit argument) overrides it — see resolution order in ensureLinked.
 export const DEFAULT_SERVER = 'https://unitbob-73a4082838d3.herokuapp.com';
 export async function ensureLinked(cwd = process.cwd(), server, out = process.stdout) {
-    const resolvedServer = server ?? readLocalServer(cwd) ?? DEFAULT_SERVER;
-    const fileId = readLocalRepoId(cwd); // only cwd's own file — no walk-up
-    const name = projectName(cwd);
-    // Refuse before touching the server, so a stray run can't mint a junk repo.
-    if (fileId === null)
-        assertProjectRoot(cwd);
-    const authId = await registerRepo(resolvedServer, name);
-    if (fileId === null) {
-        writeConfigFile(cwd, { server: resolvedServer, repo_id: authId });
-        ensureGitignored(cwd, out);
-        out.write(`Linked this project to Unitbob as ${name}.\n`);
-    }
-    else if (fileId !== authId) {
-        throw new WireError(`${CONFIG_FILE} points at repo ${fileId}, but "${name}" is repo ${authId} on the server. ` +
-            `Fix or remove ${CONFIG_FILE} before continuing.`);
+    // An already-linked project answers from its own root, wherever the command
+    // was typed. Nothing is linked yet? Then `cwd` is the candidate root and every
+    // guard below applies to it unchanged.
+    const root = locateLinkedRoot(cwd) ?? cwd;
+    const resolvedServer = server ?? readLocalServer(root) ?? DEFAULT_SERVER;
+    const fileId = readLocalRepoId(root); // only the root's own file — no walk-up
+    const name = projectName(root);
+    if (fileId !== null) {
+        const token = readLocalToken(root);
+        if (token === null) {
+            // Linked before the project had a key of its own. There is no way to mint
+            // one for an existing project — that would be a door into it — so the only
+            // honest instruction is to link again.
+            throw new WireError(`${CONFIG_FILE} has no project token. It was written by an older Unitbob, and the ` +
+                `server now requires one. Delete ${CONFIG_FILE} to link this project again ` +
+                '(the old project, along with its map and checks, stays where it is).');
+        }
+        // Checked on every command, not only at linking: the file holds the only key
+        // the project has, and a `.gitignore` rewritten since is how that key ends
+        // up in a public repository. Costs nothing when the entry is already there.
+        ensureGitignored(root, out);
+        return { server: resolvedServer, repoId: fileId, token, projectRoot: root };
     }
-    return { server: resolvedServer, repoId: authId, projectRoot: cwd };
+    // Refuse before touching the server, so a stray run can't mint a junk repo.
+    assertProjectRoot(root);
+    const { id, token } = await registerRepo(resolvedServer, name);
+    writeConfigFile(root, { server: resolvedServer, repo_id: id, token });
+    ensureGitignored(root, out);
+    out.write(`Linked this project to Unitbob as ${name}.\n`);
+    return { server: resolvedServer, repoId: id, token, projectRoot: root };
 }
 // The linking name is the *project's* name, not the checkout's (spec 29). A
 // `.git` directory means cwd is the main checkout; a `.git` file is a worktree

package/dist/links.js

@@ -0,0 +1,24 @@
+// `destination` is where the person should end up: an absolute URL the server
+// handed back (`map_url`), or a path. Only its path and query travel on; the
+// server checks that it stays inside this project before honouring it.
+export function enterUrl(config, destination) {
+    const next = pathOf(destination) ?? `/repos/${config.repoId}`;
+    const query = `?next=${encodeURIComponent(next)}`;
+    return `${config.server}/repos/${config.repoId}/enter${query}#t=${config.token}`;
+}
+// The console, in a given tab.
+export function consoleUrl(config, tab) {
+    const base = `/repos/${config.repoId}`;
+    return enterUrl(config, tab ? `${base}?tab=${tab}` : base);
+}
+function pathOf(destination) {
+    if (destination.startsWith('/'))
+        return destination;
+    try {
+        const url = new URL(destination);
+        return `${url.pathname}${url.search}`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/proc.js

@@ -2,8 +2,22 @@
 // captures stdout/stderr/exit code and hands them back untouched — shaping or
 // interpreting that output is the caller's (and ultimately Rails') job.
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+// Can this path actually be spawned? A binstub that exists but has lost its
+// executable bit is a real state — checkouts over a filesystem with no
+// permission bits, an archive unpacked without them — and `spawn` answers it
+// with an EACCES `error` event, which arrives as a thrown exception rather than
+// an exit code. Callers that pick "the project's own binstub, else the global
+// tool" have to ask this before choosing, or the fallback never gets its turn.
+export function executable(path) {
+    try {
+        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
 export const GRAPHIFY_TIMEOUT_MS = 10 * 60 * 1000;
 export function runProcess(command, args = [], options = {}) {
     return new Promise((resolve, reject) => {

package/dist/runner/bdd.js

@@ -1,16 +1,31 @@
-import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
+import { executable, runProcess } from "../proc.js";
 import { readReport } from "./types.js";
 import { PYTEST_BDD_PLUGIN } from "./pytestBddPlugin.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.
 const BEHAVIORAL_ROOT = '.unitbob/behavioral';
-const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, 'cucumber_messages.ndjson');
-const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, 'pytest_bdd_report.json');
-const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, 'unitbob_pytest_bdd_plugin.py');
-const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, 'pytest.ini');
+const CUCUMBER_REPORT_NAME = 'cucumber_messages.ndjson';
+const PYTEST_BDD_REPORT_NAME = 'pytest_bdd_report.json';
+const PYTEST_BDD_PLUGIN_NAME = 'unitbob_pytest_bdd_plugin.py';
+const PYTEST_INI_NAME = 'pytest.ini';
+// Everything a run writes into that root, listed once here — where it is
+// written. The review's "these files will be lost" warning reads this list to
+// stay quiet about them (see `files/behavioral.ts`). A second hand-kept copy
+// drifts the moment a strategy gains a file, and the warning goes back to
+// shouting about the connector's own output.
+export const BDD_RUN_ARTIFACTS = [
+    CUCUMBER_REPORT_NAME,
+    PYTEST_BDD_REPORT_NAME,
+    PYTEST_BDD_PLUGIN_NAME,
+    PYTEST_INI_NAME,
+];
+const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, CUCUMBER_REPORT_NAME);
+const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, PYTEST_BDD_REPORT_NAME);
+const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, PYTEST_BDD_PLUGIN_NAME);
+const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, PYTEST_INI_NAME);
 const PYTEST_INI = '[pytest]\naddopts =\n';
 // The connector-owned BDD strategy table (spec 32): the `runner` enum names one
 // of these; the connector never executes a host-provided command string. Each
@@ -126,11 +141,3 @@ async function pickPython(projectRoot) {
     }
     throw missingRunner('pytest-bdd');
 }
-function executable(path) {
-    try {
-        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
-    }
-    catch {
-        return false;
-    }
-}