unitbob 0.4.5 → 0.5.1

package/dist/runner/pytest.js

@@ -2,6 +2,7 @@ import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const PYTEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
@@ -11,19 +12,34 @@ export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
 // never part of the suite digest.
 export const PYTEST_INI_FILE = join('.unitbob', 'pytest.ini');
 export const PYTEST_INI = '[pytest]\naddopts =\n';
-// Run the materialised Unitbob guardrail suite with pytest in the current
-// Python environment (spec 30) — no guessing at Poetry/uv/virtualenv wrappers.
-// Only the guardrail file runs; the JUnit XML report goes to --junit-xml, not
-// stdout. The command is connector-owned: the suite artifact never carries a
-// command string.
-export async function runPytestSuite(projectRoot, suitePath) {
+// Run the materialised Unitbob guardrail suite with pytest (spec 30) — no
+// guessing at Poetry/uv/virtualenv wrappers. Only the guardrail files run; the
+// JUnit XML report goes to --junit-xml, not stdout. The command is
+// connector-owned: the suite artifact never carries a command string.
+//
+// Every file of the branch is named positionally (spec 42, §6.5) — a branch is
+// one file per assignment now, and pytest takes as many paths as it is given.
+//
+// Which pytest is a single question answered in one place (`locateRunner`), so
+// the precheck, the boot check and this run can never end up talking about
+// different interpreters. `python` is the last resort when nothing was found:
+// spawning it produces the honest "No module named pytest" rather than a silent
+// no-op, and the checks upstream have already had their chance to say so first.
+export async function runPytestSuite(projectRoot, suitePaths) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
-    const command = await pickPython(projectRoot);
-    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, suitePath, `--junit-xml=${PYTEST_RESULT_FILE}`];
+    const located = locateRunner(projectRoot, 'pytest');
+    const command = located?.command ?? 'python';
+    const args = [
+        ...(located?.args ?? ['-m', 'pytest']),
+        '-c',
+        PYTEST_INI_FILE,
+        ...suitePaths,
+        `--junit-xml=${PYTEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: PYTEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -33,14 +49,3 @@ export async function runPytestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, PYTEST_RESULT_FILE)),
     };
 }
-// The interpreter that can actually run pytest: `python3` when pytest imports
-// there (macOS/Linux ship no bare `python`), else `python`. Probing `-m pytest`
-// rather than just `--version` keeps this in step with pytestPrecheck, so the
-// run uses the same interpreter the precheck confirmed.
-async function pickPython(projectRoot) {
-    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
-        cwd: projectRoot,
-        timeoutMs: 10_000,
-    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
-    return probe.code === 0 ? 'python3' : 'python';
-}

package/dist/runner/rspec.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
+import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } 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
@@ -8,17 +9,23 @@ export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // the project's random ordering.
 export const RSPEC_SEED = '1';
 export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
-// Run the materialised Unitbob guardrail suite (spec 26). Only this file runs —
+// Run the materialised Unitbob guardrail suite (spec 26). Only these files run —
 // never the project's full suite — under RAILS_ENV=test with a fixed order/seed.
 // --options points at the materialized empty file so the project's own .rspec
 // (a --require of a helper we replaced, an extra stdout formatter) can neither
 // break the boot nor corrupt the JSON output. The JSON report goes to `--out`
 // (a file), not stdout, so the app's own stdout writes during the run can never
-// corrupt it. `suitePath` is the suite blob's own project-relative path.
-export async function runRspecSuite(projectRoot, suitePath) {
+// 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
+// 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, [
-        suitePath,
+        ...suitePaths,
         '--options',
         optionsPath,
         '--order',
@@ -38,18 +45,19 @@ export async function runRspecSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
     };
 }
-// Prefer the project's own `bin/rspec`; fall back to `bundle exec rspec`. Every
+// Which rspec — the sidecar Unitbob installed, the project's own `bin/rspec`
+// binstub, or `bundle exec rspec` — is decided once, in `locateRunner`, so this
+// run and the checks that predicted it always mean the same installation. Every
 // run sets RAILS_ENV=test so guardrails execute against the Rails test
 // environment the project's `rails_helper` configures.
 async function invokeRspec(projectRoot, rspecArgs) {
-    const localRspec = join(projectRoot, 'bin', 'rspec');
-    const hasLocalRspec = executable(localRspec);
-    const command = hasLocalRspec ? localRspec : 'bundle';
-    const args = hasLocalRspec ? rspecArgs : ['exec', 'rspec', ...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,
         timeoutMs: RSPEC_TIMEOUT_MS,
-        env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     });
     return { result, command, args };
 }

package/dist/runner/toolchain.js

@@ -0,0 +1,122 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { executable } from "../proc.js";
+// Where Unitbob keeps a test runner it had to install for itself, together with
+// whatever that runner needs to load the project.
+//
+// Deliberately not `.unitbob/structural/`: `materializeGuardrails` deletes that
+// directory before every suite write, so an environment installed there would be
+// rebuilt on every single run. Deliberately not the project's own dependency
+// files either — the whole point is that a vibecoder's repository looks exactly
+// the same after Unitbob has run as it did before. `.unitbob/` is already in
+// their .gitignore (see `ensureUnitbobIgnored`).
+export const SIDECAR_DIR = '.unitbob/runners';
+export function sidecarPath(projectRoot, ...segments) {
+    return join(projectRoot, SIDECAR_DIR, ...segments);
+}
+export const defaultToolDeps = {
+    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+};
+// How to invoke `runner` in this project, or null when nothing here can.
+//
+// The sidecar wins when it exists, and that order is deliberate. A sidecar is
+// only ever built because the project could not supply the runner itself, so
+// preferring it keeps every later run on the same environment the build was
+// prepared against. The alternative — asking the project first, every time —
+// lets a stray `pip install pytest` between two runs move the suite to a
+// different interpreter without anybody choosing that, and a guardrail suite
+// whose meaning is "green means fine" cannot afford a silent environment flip.
+export function locateRunner(projectRoot, runner, deps = defaultToolDeps) {
+    switch (runner) {
+        case 'pytest':
+            return locatePytest(projectRoot, deps);
+        case 'vitest':
+            return locateVitest(projectRoot);
+        case 'rspec':
+            return locateRspec(projectRoot);
+        default:
+            return null;
+    }
+}
+// Is a runner available at all — from the project or from a sidecar?
+export function runnerAvailable(projectRoot, runner, deps = defaultToolDeps) {
+    return locateRunner(projectRoot, runner, deps) !== null;
+}
+// Does the project supply this runner on its own, with no help from us? This is
+// the question provisioning asks before it builds anything: a project that is
+// already set up is left completely alone.
+//
+// Ruby answers from the Gemfile rather than from `locateRspec`, which always has
+// a `bundle exec rspec` to offer whether or not the gem behind it exists.
+export function projectProvidesRunner(projectRoot, runner, deps = defaultToolDeps) {
+    if (runner === 'rspec') {
+        return hasGemfileWith(projectRoot, /\brails\b/) && hasGemfileWith(projectRoot, /\brspec-rails\b/);
+    }
+    return locateRunner(projectRoot, runner, deps)?.source === 'project';
+}
+// Does one of the project's Gemfiles mention this? Shared by the Ruby precheck
+// and by the question above, so "is this a Rails project" is answered the same
+// way wherever it is asked.
+export function hasGemfileWith(projectRoot, pattern) {
+    for (const name of ['Gemfile', 'gems.rb']) {
+        const path = join(projectRoot, name);
+        if (existsSync(path) && pattern.test(readFileSync(path, 'utf8')))
+            return true;
+    }
+    return false;
+}
+// Python: an interpreter that can actually import pytest. The sidecar venv is
+// checked by file, the project's interpreters by asking them — `python3 -m
+// pytest --version` is the same question the run itself asks, so the two can
+// never disagree about which interpreter is usable.
+function locatePytest(projectRoot, deps) {
+    // The sidecar interpreter is asked the same question as any other, rather
+    // than trusted because the file is there. A virtualenv can exist and still
+    // have no pytest in it — `uv venv` creates one with no pip at all, so an
+    // install into it can fail while leaving a perfectly good `bin/python`
+    // 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)) {
+        return { command: venvPython, args: ['-m', 'pytest'], source: 'sidecar' };
+    }
+    for (const python of ['python3', 'python']) {
+        if (deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot)) {
+            return { command: python, args: ['-m', 'pytest'], source: 'project' };
+        }
+    }
+    return null;
+}
+// JS/TS: a vitest binary we can spawn. `npx` is not offered here — it would
+// install a package to answer a question, and this function's callers include
+// 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))
+        return { command: sidecar, args: [], source: 'sidecar' };
+    const project = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    if (executable(project))
+        return { command: project, args: [], source: 'project' };
+    return null;
+}
+// Ruby: bundler decides what "rspec" means, so the sidecar is selected by
+// pointing BUNDLE_GEMFILE at the sidecar Gemfile rather than by a different
+// binary. The project's own `bin/rspec` binstub is preferred over `bundle exec`
+// when it is there, exactly as the rspec runner has always preferred it.
+function locateRspec(projectRoot) {
+    if (existsSync(sidecarPath(projectRoot, 'Gemfile'))) {
+        return {
+            command: 'bundle',
+            args: ['exec', 'rspec'],
+            env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile` },
+            source: 'sidecar',
+        };
+    }
+    const binstub = join(projectRoot, 'bin', 'rspec');
+    if (executable(binstub))
+        return { command: binstub, args: [], source: 'project' };
+    return { command: 'bundle', args: ['exec', 'rspec'], source: 'project' };
+}

package/dist/runner/vitest.js

@@ -1,7 +1,8 @@
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+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 { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
@@ -28,27 +29,44 @@ const PROJECT_CONFIGS = [
     'vite.config.cjs',
 ];
 // Run the materialised Unitbob guardrail suite with the project's own Vitest
-// (spec 30). Only the guardrail file runs — the path argument filters the run.
+// (spec 30). Only the guardrail files run — the path arguments filter the run.
 //
-// A bare `vitest run <file>` treats the path as a filter that is intersected
+// A bare `vitest run <file>` treats each path as a filter that is intersected
 // with the project's `test.include`, so a project whose include does not cover
-// `.unitbob/` would collect no tests. When the project has its own config we
-// therefore write a tiny config that merges it and adds the guardrail file to
-// `include`; the positional filter still narrows the run to that one file. With
-// no project config, Vitest's default include already covers `.unitbob/`, so
-// the bare command is correct and we write nothing.
+// `.unitbob/` would collect no tests. So the config Unitbob writes names every
+// 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
+// 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
+// covers `.unitbob/` for a file that happens to be named `*.test.ts`, which is a
+// trap set for whoever names a slice after its capability.
 //
 // The JSON report goes to --outputFile, not stdout, so app logging can never
 // corrupt it. The command is connector-owned: the suite artifact never carries
 // a command string.
-export async function runVitestSuite(projectRoot, suitePath) {
-    const configArgs = writeMergedConfig(projectRoot, suitePath);
-    const command = 'npx';
-    const args = ['vitest', 'run', suitePath, ...configArgs, '--reporter=json', `--outputFile=${VITEST_RESULT_FILE}`];
+export async function runVitestSuite(projectRoot, suitePaths) {
+    const configArgs = writeMergedConfig(projectRoot, suitePaths);
+    // An installed vitest — the sidecar's, else the project's — is spawned by
+    // path. `npx` stays as the last resort it has always been: it is the only
+    // option that can conjure a runner out of nothing, which is right here at the
+    // end and wrong everywhere else (see `locateRunner`, which does not offer it).
+    const located = locateRunner(projectRoot, 'vitest');
+    const command = located?.command ?? 'npx';
+    const args = [
+        ...(located ? located.args : ['vitest']),
+        'run',
+        ...suitePaths,
+        ...configArgs,
+        '--reporter=json',
+        `--outputFile=${VITEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: VITEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -58,31 +76,47 @@ export async function runVitestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
     };
 }
-// Returns the `--config` args to add, writing the merge config first. When the
-// project has no config of its own there is nothing to inherit and nothing to
-// override (defaults already cover .unitbob/), so we return no args.
-function writeMergedConfig(projectRoot, suitePath) {
+// Returns the `--config` args to add, writing the config first. Always written:
+// the branch's files have to be in `include` or nothing is collected, and the
+// names a worker gives its slice are not something to bet a whole run on.
+function writeMergedConfig(projectRoot, suitePaths) {
     const projectConfig = PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
-    if (!projectConfig)
-        return [];
-    writeFileSync(join(projectRoot, VITEST_CONFIG_FILE), mergedConfigSource(projectConfig, suitePath));
+    const path = join(projectRoot, VITEST_CONFIG_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, configSource(projectConfig, suitePaths));
     return ['--config', VITEST_CONFIG_FILE];
 }
 // The .unitbob/ config sits one level below the project root, so the project
-// config is a `../` import. `mergeConfig` concatenates `include`, so the
-// guardrail file joins the project's patterns instead of replacing them; the
-// positional filter then isolates it. A function-form config is resolved first.
-function mergedConfigSource(projectConfig, suitePath) {
-    return `// Written by the unitbob connector before each vitest run — do not edit.
-import { mergeConfig } from 'vitest/config';
+// config is a `../` import. A function-form config is resolved first, and
+// everything the project set — plugins, aliases, setup files, environment — is
+// carried through; only `test.include` is replaced, with exactly this branch's
+// files. Replacing rather than concatenating is the point: the run must be these
+// files and no others, and the positional filters then say the same thing twice.
+//
+// Nothing is imported from `vitest` itself, and that is deliberate. Vite
+// re-imports this generated file from a temporary module beside it, so every
+// bare `import` here resolves by walking up from `.unitbob/` — while a project
+// whose only vitest is the one Unitbob installed keeps it at
+// `.unitbob/runners/node_modules`, which is not on that path. An
+// `import { mergeConfig } from 'vitest/config'` there dies with
+// ERR_MODULE_NOT_FOUND before a single test is collected, on exactly the
+// projects the sidecar exists for. A spread does the same job with no import,
+// and `defineConfig` is a typing helper that buys a generated file nothing.
+function configSource(projectConfig, suitePaths) {
+    const include = `include: ${JSON.stringify(suitePaths)}`;
+    const header = '// Written by the unitbob connector before each vitest run — do not edit.';
+    if (!projectConfig) {
+        return `${header}
+export default { test: { ${include} } };
+`;
+    }
+    return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
 
-export default mergeConfig(base, {
-  test: { include: [${JSON.stringify(suitePath)}] },
-});
+export default { ...base, test: { ...(base.test ?? {}), ${include} } };
 `;
 }

package/dist/surfaces/routeInventory.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { dirname, join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.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.
@@ -20,7 +21,7 @@ export function routeInventoryPath(projectRoot) {
 // records why Django, FastAPI and Flask come next and why Express cannot follow
 // at all (its addresses are registered by arbitrary code at run time).
 export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
-    if (!looksLikeRails(projectRoot))
+    if (!canAskTheRouter(projectRoot))
         return silent(projectRoot, 'unsupported_stack');
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
@@ -150,8 +151,19 @@ function becauseOf(result) {
 function plural(count, one, many) {
     return count === 1 ? one : many;
 }
-function looksLikeRails(projectRoot) {
-    return existsSync(join(projectRoot, 'config', 'routes.rb'));
+// Which stack this is, is not this module's question — one answer to it already
+// exists and this file now asks it. `config/routes.rb` stays as a second-level
+// condition inside the Ruby branch, because a Rails application without a route
+// file has no router to ask.
+//
+// It used to be the whole test, which made it a fourth independent way of
+// deciding "is this Rails?" — and one that was wrong at both edges: a Rails app
+// that keeps its routes elsewhere was refused, and any project that happens to
+// carry a `config/routes.rb` was asked to boot Rails. There are still several
+// stack detectors in this package; this removes the one that had a single caller
+// and no excuse.
+function canAskTheRouter(projectRoot) {
+    return (detectStructuralRunner(projectRoot) === 'rspec' && existsSync(join(projectRoot, 'config', 'routes.rb')));
 }
 // The question, asked of the router object rather than of the `rails routes`
 // command line. `--expanded` was the earlier reading, and it cost this project

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'];
+// 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 43, §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';
 }