unitbob 0.3.6 → 0.4.1

package/README.md

@@ -20,15 +20,31 @@ Add the Unitbob plugin marketplace: sergeygershun/unitbob-connector
 Install the unitbob plugin
 ```
 
-**With commands (in the terminal):**
+**Claude Code (in the terminal):**
 ```
 claude plugin marketplace add sergeygershun/unitbob-connector
 claude plugin install unitbob@unitbob
 ```
 
-Restart the session so the commands load.
+**Codex (in the terminal):**
+```
+codex plugin marketplace add sergeygershun/unitbob-connector
+codex plugin add unitbob@unitbob
+npx -y unitbob@0.4.1 codex-install
+```
 
-In Codex it is the same — the same install, and the same phrasings below.
+Start a new Claude Code or Codex thread so the installed skill and named agents
+load. After setup, the phrasings and Unitbob flow below are the same on both
+hosts.
+
+Codex compatibility: version 0.145.0 accepts the Unitbob custom-agent TOML files,
+but its experimental rollout budget is shared by the root and subagents rather
+than enforced separately for each named agent. No Codex version is currently
+qualified by Unitbob for a native per-agent ceiling. Before the first bounded
+role, Unitbob therefore asks whether to continue this invocation without that
+mechanical ceiling; approval is never persisted. The definitions keep the native
+budget values so a future Codex release can be qualified without introducing a
+Unitbob supervisor.
 
 ---
 

package/dist/cli.js

@@ -25,6 +25,9 @@ import { validateBuild } from "./verbs/validateBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
+import { validateWorkerPlan } from "./verbs/validateWorkerPlan.js";
+import { validateWorkerCheckpoints } from "./verbs/validateWorkerCheckpoints.js";
+import { installCodexAgents } from "./verbs/codexInstall.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
 Usage: unitbob [--project-root <dir>] <verb> [args]
@@ -36,6 +39,7 @@ Options:
 
 Verbs:
   init                 Link this project to Unitbob (also happens automatically).
+  codex-install        Install the bounded Unitbob worker definitions for Codex.
   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.
@@ -47,6 +51,9 @@ Verbs:
   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.
+  validate-worker-plan Internal: validate the exact request-bound worker plan before fan-out.
+  validate-worker-checkpoints
+                       Internal: validate every worker checkpoint before assembly or repair.
   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.
   run-local [branch]   Internal: run the suite you just wrote, before publishing it, with the same runner
@@ -81,6 +88,9 @@ export async function main(argv, deps = { ensureLinked }) {
     const linked = () => deps.ensureLinked(parsed.root);
     try {
         switch (verb) {
+            case 'codex-install':
+                installCodexAgents(args);
+                return 0;
             case 'init':
                 await init(args);
                 return 0;
@@ -108,6 +118,12 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'validate-build':
                 await validateBuild(await linked(), args);
                 return 0;
+            case 'validate-worker-plan':
+                await validateWorkerPlan(await linked(), args);
+                return 0;
+            case 'validate-worker-checkpoints':
+                await validateWorkerCheckpoints(await linked(), args);
+                return 0;
             case 'put-suite-build':
                 return await publishAndRun(await linked(), args);
             case 'fix-prepare':

package/dist/files/behavioral.js

@@ -9,6 +9,87 @@ import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
 // runs the suite to green before upload; the connector materializes the stored
 // 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`;
+// The Ruby/Cucumber harness is connector-owned. Host agents own business steps;
+// this file owns only the stable Rails integration seam they build on.
+export const BEHAVIORAL_WORLD = `# Generated by Unitbob. DO NOT EDIT: suite materialization restores this file.
+repo_root = ENV.fetch('UNITBOB_REPO_ROOT')
+ENV['RAILS_ENV'] ||= 'test'
+require File.join(repo_root, 'config', 'environment')
+require 'action_dispatch/testing/integration'
+require 'rspec/expectations'
+require 'rspec/mocks'
+
+module UnitbobWorld
+  include RSpec::Matchers
+  include RSpec::Mocks::ExampleMethods
+
+  attr_reader :unitbob_session
+
+  def unitbob_get(path, **options)
+    unitbob_session.get(path, **options)
+  end
+
+  def unitbob_post(path, **options)
+    unitbob_session.post(path, **options)
+  end
+
+  def unitbob_patch(path, **options)
+    unitbob_session.patch(path, **options)
+  end
+
+  def unitbob_put(path, **options)
+    unitbob_session.put(path, **options)
+  end
+
+  def unitbob_delete(path, **options)
+    unitbob_session.delete(path, **options)
+  end
+
+  def unitbob_expect_status(status)
+    unitbob_session.assert_response(status)
+  end
+
+  def unitbob_expect_redirect_to(location)
+    unitbob_session.assert_redirected_to(location)
+  end
+end
+
+World(UnitbobWorld)
+
+Before do
+  @unitbob_time_zone = Time.zone
+  @unitbob_locale = I18n.locale
+  @unitbob_connection = ActiveRecord::Base.connection
+  @unitbob_connection.begin_transaction(joinable: false)
+  RSpec::Mocks.setup
+
+  @unitbob_session = ActionDispatch::Integration::Session.new(Rails.application)
+  @unitbob_session.singleton_class.class_eval { attr_accessor :assertions }
+  @unitbob_session.assertions = 0
+end
+
+After do
+  mock_error = nil
+  begin
+    RSpec::Mocks.verify
+  rescue Exception => error # rubocop:disable Lint/RescueException
+    mock_error = error
+  ensure
+    RSpec::Mocks.teardown
+    @unitbob_connection.rollback_transaction if @unitbob_connection&.transaction_open?
+    Time.zone = @unitbob_time_zone
+    I18n.locale = @unitbob_locale
+  end
+  raise mock_error if mock_error
+end
+`;
+export function materializeBehavioralWorld(projectRoot) {
+    const worldPath = join(projectRoot, BEHAVIORAL_WORLD_PATH);
+    mkdirSync(dirname(worldPath), { recursive: true });
+    writeFileSync(worldPath, BEHAVIORAL_WORLD);
+    return worldPath;
+}
 // Write a behavioral artifact envelope (main file + support files) under the
 // behavioral root, after checking every path is safe. Stale suite artifacts are
 // removed while the separately provisioned runner environment is preserved.
@@ -17,6 +98,9 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     const files = [artifact, ...(artifact.support_files ?? [])];
     for (const file of files)
         assertUnitbobPath(file.path, BEHAVIORAL_DIR);
+    if (files.some((file) => file.path === BEHAVIORAL_WORLD_PATH)) {
+        throw new Error(`${BEHAVIORAL_WORLD_PATH} is the connector-owned World and cannot be supplied by the host artifact.`);
+    }
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     mkdirSync(behavioralRoot, { recursive: true });
@@ -33,6 +117,9 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
         if (file === artifact)
             mainPath = dest;
     }
+    if (runner === 'cucumber') {
+        materializeBehavioralWorld(projectRoot);
+    }
     return { mainPath };
 }
 // Everything under the behavioral root that the next materialization will
@@ -49,7 +136,11 @@ export function filesLostOnMaterialize(projectRoot, artifact, runner) {
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     if (!existsSync(behavioralRoot))
         return [];
-    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const listed = new Set([
+        artifact.path,
+        ...(artifact.support_files ?? []).map((file) => file.path),
+        ...(runner === 'cucumber' ? [BEHAVIORAL_WORLD_PATH] : []),
+    ]);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     return readdirSync(behavioralRoot)
         .filter((entry) => !runnerEntries.has(entry) && !CONNECTOR_RUN_ARTIFACTS.has(entry))

package/dist/files/suiteBuild.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 import { readBudget, RUN_BUDGET } from "./budget.js";
+import { readWorkerPlan, validateWorkerPlanFiles, workerPlanDigest, workerPlanPath } from "./workerPlan.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
 }
@@ -42,6 +43,28 @@ export function writeBehavioralReviewRequest(projectRoot, output, candidateRun,
             ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
         } : {}),
     };
+    const workerPlanDigestInMetadata = metadata?.worker_plan_digest;
+    if (workerPlanDigestInMetadata === undefined && existsSync(workerPlanPath(projectRoot))) {
+        throw new Error('behavioral test_metadata.worker_plan_digest is required when a local worker-plan.json exists.');
+    }
+    if (workerPlanDigestInMetadata !== undefined) {
+        if (typeof workerPlanDigestInMetadata !== 'string' || !/^[a-f0-9]{64}$/.test(workerPlanDigestInMetadata)) {
+            throw new Error('behavioral test_metadata.worker_plan_digest must be a SHA-256 string.');
+        }
+        const planErrors = validateWorkerPlanFiles(projectRoot);
+        if (planErrors.length > 0)
+            throw new Error(`Cannot review an invalid worker plan:\n- ${planErrors.join('\n- ')}`);
+        const digest = workerPlanDigest(projectRoot);
+        if (workerPlanDigestInMetadata !== digest) {
+            throw new Error('behavioral test_metadata.worker_plan_digest does not match the exact local worker-plan.json bytes.');
+        }
+        const buildRequest = readSuiteBuildRequest(projectRoot);
+        const assignment = buildRequest.branches.find((branch) => branch.suite_kind === 'behavioral')?.assignment;
+        const items = readWorkerPlan(projectRoot).workers.filter((item) => item.branch === 'behavioral');
+        request.behavioral_assignment = assignment;
+        request.worker_plan = items;
+        request.plan_digest = digest;
+    }
     writeArtifact(reviewRequestPath(projectRoot), request);
     return request;
 }
@@ -80,6 +103,7 @@ const POST_CANDIDATE_METADATA_KEYS = [
     'known_defect_context',
     'candidate_run',
     'fixed_candidate_run',
+    'selection_review',
 ];
 export function readBehavioralReview(projectRoot, output) {
     const metadata = output.test_metadata;
@@ -98,6 +122,7 @@ export function readBehavioralReview(projectRoot, output) {
     if (!('bdd_quality_review' in review) || !('known_defect_probe' in review)) {
         throw new Error(`${path} must contain bdd_quality_review and known_defect_probe.`);
     }
+    validateSelectionReview(review, metadata);
     const evidence = readCandidateRunEvidence(projectRoot, output);
     return {
         ...review,
@@ -105,6 +130,40 @@ export function readBehavioralReview(projectRoot, output) {
         ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
     };
 }
+function validateSelectionReview(review, metadata) {
+    const digest = metadata?.worker_plan_digest;
+    if (digest === undefined)
+        return;
+    const selection = review.selection_review;
+    if (!selection || selection.plan_digest !== digest || !Array.isArray(selection.capability_reviews)) {
+        throw new Error('The behavioral review must contain selection_review bound to worker_plan_digest.');
+    }
+    const expected = Array.isArray(metadata?.capabilities)
+        ? metadata.capabilities.flatMap((entry) => {
+            const id = entry?.capability_id;
+            return typeof id === 'string' && id ? [id] : [];
+        })
+        : [];
+    const entries = selection.capability_reviews;
+    const actual = entries.map((entry) => entry?.capability_id);
+    for (const id of expected) {
+        if (actual.filter((candidate) => candidate === id).length !== 1) {
+            throw new Error(`selection_review must contain exactly one verdict for capability ${id}.`);
+        }
+    }
+    for (const [index, entry] of entries.entries()) {
+        if (!expected.includes(entry?.capability_id)) {
+            throw new Error(`selection_review.capability_reviews[${index}] names an unassigned capability.`);
+        }
+        if (!['pass', 'does_not_pass'].includes(entry?.verdict)) {
+            throw new Error(`selection_review.capability_reviews[${index}].verdict must be pass or does_not_pass.`);
+        }
+        if (entry.verdict === 'does_not_pass' &&
+            (typeof entry.reviewer_objection_text !== 'string' || !entry.reviewer_objection_text.trim())) {
+            throw new Error(`selection_review.capability_reviews[${index}] must include reviewer_objection_text.`);
+        }
+    }
+}
 // Why a review does not bind — two different mistakes with one symptom.
 //
 // The likelier one, now that a branch may answer with a bare `{ path }`: the

package/dist/files/workerPlan.js

@@ -0,0 +1,170 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertUnitbobPath } from "./artifactPath.js";
+export function workerPlanPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
+}
+function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
+}
+export function checkpointPath(projectRoot, item) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'checkpoints', `${item.branch}-${item.worker_id}.json`);
+}
+export function exactFileDigest(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+export function requestDigest(projectRoot) {
+    return exactFileDigest(requestPath(projectRoot));
+}
+export function workerPlanDigest(projectRoot) {
+    return exactFileDigest(workerPlanPath(projectRoot));
+}
+export function readWorkerPlan(projectRoot) {
+    const path = workerPlanPath(projectRoot);
+    if (!existsSync(path))
+        throw new Error(`${path} not found — write the complete worker plan before fan-out.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    return parsed;
+}
+export function validateWorkerPlanFiles(projectRoot) {
+    const errors = [];
+    const plan = readWorkerPlan(projectRoot);
+    let request;
+    try {
+        request = JSON.parse(readFileSync(requestPath(projectRoot), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${requestPath(projectRoot)} is not valid JSON: ${error.message}`);
+    }
+    if (!plan || typeof plan !== 'object')
+        return ['worker plan must be an object'];
+    if (plan.request_digest !== requestDigest(projectRoot))
+        errors.push('request_digest does not match the exact request.json bytes');
+    if (!Array.isArray(plan.workers) || plan.workers.length === 0)
+        return [...errors, 'workers must be a non-empty array'];
+    const branches = Array.isArray(request.branches) ? request.branches : [];
+    const expectedByBranch = new Map(branches.map((branch) => [
+        branch.suite_kind,
+        assignmentIds(branch.assignment),
+    ]));
+    const budget = request.budget;
+    const workerCeiling = typeof budget?.workers === 'number' ? budget.workers : Number.POSITIVE_INFINITY;
+    const seenWorkers = new Set();
+    const seenPaths = new Map();
+    for (const [index, item] of plan.workers.entries()) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            errors.push(`workers[${index}]: worker plan item must be an object`);
+            continue;
+        }
+        const label = workerLabel(item, index);
+        if (!isNonEmptyString(item?.branch) || !expectedByBranch.has(item.branch))
+            errors.push(`${label}: branch is not in the request`);
+        if (!isNonEmptyString(item?.worker_id) || !/^[a-zA-Z0-9_-]+$/.test(item.worker_id))
+            errors.push(`${label}: worker_id must be a stable filename-safe id`);
+        else if (seenWorkers.has(item.worker_id))
+            errors.push(`${label}: worker_id ${item.worker_id} appears more than once`);
+        else
+            seenWorkers.add(item.worker_id);
+        for (const field of ['capability_ids', 'promises', 'planned_cases', 'source_paths', 'owned_paths']) {
+            if (!Array.isArray(item?.[field]) || item[field].length === 0)
+                errors.push(`${label}: ${field} must be non-empty`);
+        }
+        for (const field of ['capability_ids', 'promises', 'source_paths', 'owned_paths']) {
+            if (Array.isArray(item?.[field]) && item[field].some((value) => !isNonEmptyString(value))) {
+                errors.push(`${label}: ${field} must contain non-empty strings`);
+            }
+        }
+        if (Array.isArray(item?.planned_cases) && item.planned_cases.some((value) => !(isNonEmptyString(value) || (value !== null && typeof value === 'object')))) {
+            errors.push(`${label}: planned_cases must contain non-empty intents`);
+        }
+        if (!isNonEmptyString(item?.done_when))
+            errors.push(`${label}: done_when must be non-empty`);
+        if (!isNonEmptyString(item?.harness_path))
+            errors.push(`${label}: harness_path must be non-empty`);
+        const expectedHarness = item?.branch === 'behavioral'
+            ? '.unitbob/behavioral/step_definitions/00_unitbob_world.rb'
+            : item?.branch === 'structural' ? '.unitbob/structural/unitbob_helper.rb' : null;
+        if (expectedHarness && item.harness_path !== expectedHarness) {
+            errors.push(`${label}: harness_path must name the connector-owned ${expectedHarness}`);
+        }
+        if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
+            errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
+        }
+        if (!Number.isInteger(item?.limits?.fact_finder_lookups) || item.limits.fact_finder_lookups < 0 || item.limits.fact_finder_lookups > 8) {
+            errors.push(`${label}: limits.fact_finder_lookups must be an integer from 0 to 8`);
+        }
+        for (const ownedPath of Array.isArray(item?.owned_paths) ? item.owned_paths : []) {
+            if (!isNonEmptyString(ownedPath)) {
+                errors.push(`${label}: owned path must be a non-empty string`);
+                continue;
+            }
+            try {
+                assertUnitbobPath(ownedPath, `.unitbob/${item.branch}`);
+            }
+            catch (error) {
+                errors.push(`${label}: ${error.message}`);
+            }
+            const owner = seenPaths.get(ownedPath);
+            if (owner)
+                errors.push(`${label}: owned path ${ownedPath} is also owned by ${owner}`);
+            else
+                seenPaths.set(ownedPath, label);
+        }
+    }
+    for (const [branch, expected] of expectedByBranch) {
+        const items = plan.workers.filter((item) => item && typeof item === 'object' && !Array.isArray(item) && item.branch === branch);
+        if (expected.length > 0 && items.length === 0)
+            errors.push(`${branch}: no worker slice was planned`);
+        if (items.length > Math.min(workerCeiling, expected.length)) {
+            errors.push(`${branch}: worker count ${items.length} exceeds min(budget.workers, capability count)`);
+        }
+        const assigned = items.flatMap((item) => Array.isArray(item.capability_ids) ? item.capability_ids : []);
+        for (const id of expected) {
+            const count = assigned.filter((candidate) => candidate === id).length;
+            if (count === 0)
+                errors.push(`${branch}: assigned capability ${id} is missing from the plan`);
+            if (count > 1)
+                errors.push(`${branch}: assigned capability ${id} appears more than once`);
+        }
+        for (const id of assigned.filter((id) => !expected.includes(id)))
+            errors.push(`${branch}: capability ${id} was not assigned by the request`);
+        const sizes = items.map((item) => Array.isArray(item.planned_cases) ? item.planned_cases.length : 0).filter((size) => size > 0);
+        if (sizes.length > 1 && Math.max(...sizes) / Math.min(...sizes) > 1.5) {
+            errors.push(`${branch}: planned case slice ratio exceeds 1.5`);
+        }
+    }
+    return errors;
+}
+function assignmentIds(value) {
+    const assignment = value;
+    if (Array.isArray(assignment?.capabilities)) {
+        return assignment.capabilities.flatMap((entry) => idFrom(entry, 'capability_id'));
+    }
+    if (!Array.isArray(assignment?.blocks))
+        return [];
+    return assignment.blocks.flatMap((block) => {
+        const record = block;
+        return Array.isArray(record.interfaces)
+            ? record.interfaces.flatMap((entry) => idFrom(entry, 'interface_id'))
+            : [];
+    });
+}
+function idFrom(value, field) {
+    const id = value?.[field];
+    return isNonEmptyString(id) ? [id] : [];
+}
+function workerLabel(item, index) {
+    return item && isNonEmptyString(item.branch) && isNonEmptyString(item.worker_id)
+        ? `${item.branch}:${item.worker_id}`
+        : `workers[${index}]`;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}

package/dist/runner/worldProbe.js

@@ -0,0 +1,89 @@
+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 { 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,
+    }),
+}) {
+    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);
+    try {
+        const result = await deps.runCmd('bundle', [
+            'exec', 'cucumber', feature,
+            '--require', join(projectRoot, BEHAVIORAL_WORLD_PATH),
+            '--require', steps,
+            '--format', 'progress',
+        ], {
+            cwd: projectRoot,
+            env: {
+                ...process.env,
+                RAILS_ENV: 'test',
+                UNITBOB_REPO_ROOT: projectRoot,
+                BUNDLE_GEMFILE: join(projectRoot, '.unitbob', 'behavioral', 'Gemfile'),
+            },
+        });
+        if (result.code === 0)
+            return { status: 'ok' };
+        const detail = [result.stderr, result.stdout].find((text) => text.trim())?.trim() ?? `exit ${result.code}`;
+        return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe failed: ${detail}` };
+    }
+    catch (error) {
+        return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe could not run: ${String(error)}` };
+    }
+    finally {
+        rmSync(probeRoot, { recursive: true, force: true });
+    }
+}
+const PROBE_FEATURE = `Feature: Unitbob World profile
+  Scenario: request, assertion counter, mocks, and state mutation
+    Given the first World probe scenario mutates supported state
+    Then its integration assertion counter advances
+
+  Scenario: supported state is clean at the next scenario boundary
+    Then the second World probe scenario sees clean state and fresh mocks
+`;
+const PROBE_STEPS = `PROBE_VERSION = "unitbob-world-probe-#{Process.pid}"
+PROBE_TIME_ZONE = Time.zone
+PROBE_OTHER_TIME_ZONE = PROBE_TIME_ZONE&.name == 'UTC' ? 'Hawaii' : 'UTC'
+PROBE_LOCALE = I18n.locale
+PROBE_RECEIVER = Object.new
+
+Given('the first World probe scenario mutates supported state') do
+  @unitbob_connection.execute("INSERT INTO schema_migrations (version) VALUES ('#{PROBE_VERSION}')")
+  Time.zone = PROBE_OTHER_TIME_ZONE
+  alternate_locale = (I18n.available_locales - [PROBE_LOCALE]).first
+  I18n.locale = alternate_locale if alternate_locale
+  expect(PROBE_RECEIVER).to receive(:unitbob_probe).once.and_return(:mocked)
+  expect(PROBE_RECEIVER.unitbob_probe).to eq(:mocked)
+  unitbob_get('/__unitbob_world_probe__')
+  unitbob_expect_status(:success)
+  unitbob_get('/__unitbob_world_probe_redirect__')
+  unitbob_expect_redirect_to('/__unitbob_world_probe_target__')
+end
+
+Then('its integration assertion counter advances') do
+  expect(unitbob_session.assertions).to be > 0
+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
+  expect(count).to eq(0)
+  expect(Time.zone).to eq(PROBE_TIME_ZONE)
+  expect(I18n.locale).to eq(PROBE_LOCALE)
+  expect(PROBE_RECEIVER).not_to respond_to(:unitbob_probe)
+  probe = double('fresh-world-probe')
+  expect(probe).to receive(:call).once
+  probe.call
+end
+`;

package/dist/verbs/codexInstall.js

@@ -0,0 +1,28 @@
+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'];
+const bundledAgentsDir = fileURLToPath(new URL('../../plugin/codex/agents/', import.meta.url));
+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);
+    }
+    deps.stdout.write(`Installed 3 Unitbob Codex agent definitions in ${targetDir}. Start a new Codex thread before running Unitbob.\n`);
+}

package/dist/verbs/putSuiteBuild.js

@@ -129,6 +129,7 @@ function withReview(config, request, output) {
             ...qualityReview,
             candidate_digest: review.candidate_digest,
         },
+        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
         known_defect_probe: review.known_defect_probe,
         known_defect_context: request.known_defect_context,
         candidate_run: review.candidate_run,

package/dist/verbs/suitePrepare.js

@@ -1,10 +1,12 @@
 import { clearSpending } from "../files/budget.js";
 import { materializeHelper } from "../files/guardrails.js";
+import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
 import { anyStackPrecheck, detectBddRunner, detectStructuralRunner } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
 import { ensureRunner } from "../runner/provision.js";
+import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
 // produce one: the server offered no combination this stack matches, or the
@@ -60,6 +62,7 @@ export async function suitePrepare(config, args = [], deps) {
         precheck: anyStackPrecheck,
         bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
         ...deps,
@@ -104,6 +107,14 @@ export async function suitePrepare(config, args = [], deps) {
                 fixableNotices.push(`  Behavioral runner "${runner}" not installed: ${prov.message ?? ''}${steps}`);
                 continue;
             }
+            if (runner === 'cucumber') {
+                materializeBehavioralWorld(config.projectRoot);
+                const probe = await actual.worldProbe(config.projectRoot);
+                if (probe.status === 'fixable') {
+                    fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
+                    continue;
+                }
+            }
         }
         buildable.push({ packet, runner });
     }

package/dist/verbs/validateBuild.js

@@ -18,10 +18,34 @@ export function collectBuildProblems(request, outputs, unreadable = []) {
         const add = (message) => { problems.push({ branch: output.suite_kind, message }); };
         checkRunnerManifest(branch, output, add);
         checkAssignment(branch, output, add);
+        if (output.suite_kind === 'behavioral')
+            checkDuplicateStepExpressions(output, add);
     }
     problems.push(...unansweredBranches(request, outputs, unreadable));
     return problems;
 }
+function checkDuplicateStepExpressions(output, add) {
+    const suite = output.suite_file;
+    const definitions = new Map();
+    for (const file of Array.isArray(suite?.support_files) ? suite.support_files : []) {
+        if (typeof file.path !== 'string' || typeof file.content !== 'string')
+            continue;
+        for (const line of file.content.split('\n')) {
+            const call = line.match(/^\s*(?:Given|When|Then|And|But)\s*\(\s*(['"`])(.*?)\1/);
+            const decorator = line.match(/^\s*@(given|when|then)\s*\(\s*(['"])(.*?)\2/i);
+            const expression = call?.[2] ?? decorator?.[3];
+            if (!expression)
+                continue;
+            definitions.set(expression, [...(definitions.get(expression) ?? []), file.path]);
+        }
+    }
+    for (const [expression, paths] of definitions) {
+        const uniquePaths = [...new Set(paths)];
+        if (paths.length > 1) {
+            add(`duplicate step expression "${expression}" appears in ${uniquePaths.join(', ')} — step expressions share one branch-global namespace.`);
+        }
+    }
+}
 // The branch that is not there at all. Every check above reads the answer and
 // asks whether it is well-formed; none of them can see a branch the answer never
 // mentions, because there is no entry to walk. So this one walks the request

package/dist/verbs/validateWorkerCheckpoints.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { checkpointPath, readWorkerPlan, requestDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
+export async function validateWorkerCheckpoints(config, _args = [], deps = { stdout: process.stdout }) {
+    const planErrors = validateWorkerPlanFiles(config.projectRoot);
+    if (planErrors.length > 0)
+        throw new Error(`Cannot validate checkpoints for an invalid worker plan:\n- ${planErrors.join('\n- ')}`);
+    const plan = readWorkerPlan(config.projectRoot);
+    const expectedRequestDigest = requestDigest(config.projectRoot);
+    const expectedPlanDigest = workerPlanDigest(config.projectRoot);
+    const errors = [];
+    for (const item of plan.workers) {
+        const label = `${item.branch}:${item.worker_id}`;
+        const path = checkpointPath(config.projectRoot, item);
+        if (!existsSync(path)) {
+            errors.push(`${label}: checkpoint is missing at ${path}`);
+            continue;
+        }
+        let checkpoint;
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                errors.push(`${label}: checkpoint must be an object`);
+                continue;
+            }
+            checkpoint = parsed;
+        }
+        catch (error) {
+            errors.push(`${label}: checkpoint is not valid JSON: ${error.message}`);
+            continue;
+        }
+        if (checkpoint.request_digest !== expectedRequestDigest)
+            errors.push(`${label}: request_digest is stale`);
+        if (checkpoint.plan_digest !== expectedPlanDigest)
+            errors.push(`${label}: plan_digest is stale`);
+        if (checkpoint.branch !== item.branch)
+            errors.push(`${label}: branch does not match its plan item`);
+        if (checkpoint.worker_id !== item.worker_id)
+            errors.push(`${label}: worker_id does not match its plan item`);
+        const completed = stringArray(checkpoint.completed_promises, `${label}: completed_promises`, errors);
+        const unresolved = stringArray(checkpoint.unresolved_promises, `${label}: unresolved_promises`, errors);
+        const accounted = [...completed, ...unresolved];
+        for (const promise of item.promises) {
+            const count = accounted.filter((candidate) => candidate === promise).length;
+            if (count !== 1)
+                errors.push(`${label}: promise ${promise} must appear exactly once across completed/unresolved promises`);
+        }
+        for (const promise of accounted.filter((candidate) => !item.promises.includes(candidate))) {
+            errors.push(`${label}: checkpoint names promise ${promise} outside its plan item`);
+        }
+        const writtenPaths = stringArray(checkpoint.written_paths, `${label}: written_paths`, errors);
+        for (const pathValue of writtenPaths.filter((candidate) => !item.owned_paths.includes(candidate))) {
+            errors.push(`${label}: written path ${pathValue} is not an owned path`);
+        }
+        validateCompactFacts(checkpoint.facts, label, errors);
+        stringArray(checkpoint.decisions, `${label}: decisions`, errors);
+        stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
+    }
+    if (errors.length > 0)
+        throw new Error(`Worker checkpoints are invalid:\n- ${errors.join('\n- ')}`);
+    const validWorkers = plan.workers.map((item) => `${item.branch}:${item.worker_id}`);
+    deps.stdout.write(`Worker checkpoints valid for ${validWorkers.join(', ')}.\n`);
+    return { valid_workers: validWorkers };
+}
+function stringArray(value, label, errors) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+        errors.push(`${label} must be an array of non-empty strings`);
+        return [];
+    }
+    return value;
+}
+function validateCompactFacts(value, label, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${label}: facts must be an array`);
+        return;
+    }
+    for (const [index, entry] of value.entries()) {
+        const fact = entry;
+        if (!fact || typeof fact.fact !== 'string' || !fact.fact.trim())
+            errors.push(`${label}: facts[${index}].fact must be non-empty`);
+        if (!Array.isArray(fact?.source_refs) || fact.source_refs.some((ref) => typeof ref !== 'string' || !ref.trim())) {
+            errors.push(`${label}: facts[${index}].source_refs must be compact source references`);
+        }
+        if ('source' in (fact ?? {}) || 'transcript' in (fact ?? {}) || 'suite' in (fact ?? {})) {
+            errors.push(`${label}: facts[${index}] may not embed source, transcript, or suite copies`);
+        }
+    }
+}

package/dist/verbs/validateWorkerPlan.js

@@ -0,0 +1,9 @@
+import { validateWorkerPlanFiles, workerPlanDigest } from "../files/workerPlan.js";
+export async function validateWorkerPlan(config, _args = [], deps = { stdout: process.stdout }) {
+    const errors = validateWorkerPlanFiles(config.projectRoot);
+    if (errors.length > 0)
+        throw new Error(`Worker plan is invalid:\n- ${errors.join('\n- ')}`);
+    const planDigest = workerPlanDigest(config.projectRoot);
+    deps.stdout.write(`Worker plan valid (${planDigest}). Fan-out may start.\n`);
+    return { plan_digest: planDigest };
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "unitbob",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {
     "unitbob": "dist/bin.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "plugin/codex/agents"
   ],
   "engines": {
     "node": ">=18"
@@ -16,6 +17,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
     "test": "node --test test/*.test.ts",
+    "test:world-profiles": "node scripts/test-world-profiles.mjs",
     "check:release": "node scripts/check-release.mjs"
   },
   "publishConfig": {

package/plugin/codex/agents/fact-finder.toml

@@ -0,0 +1,77 @@
+name = "fact-finder"
+description = "Answers one closed question about the analyzed project's source with exact, copyable facts. It does not decide what to test, write tests, or run anything."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+developer_instructions = '''
+You look things up in the source of the project being analyzed, and you report
+what you found. That is the whole job.
+
+A suite worker writes tests it is not allowed to run — the test database is
+shared and the coordinator owns every run — so it has to get the factory name,
+the required fields and the shape of the answer right on the first try. A fact
+it guesses becomes an assertion about something that does not exist, and the
+repair round that follows costs more than every lookup you will ever do. You
+are the alternative to that guess.
+
+## What a good answer looks like
+
+**Quote, don't summarise.** A signature, the exact keyword arguments a factory
+takes, the literal strings in an enum, the status a controller returns — copy the
+lines and name the file and line they came from. "The factory accepts a status"
+is not an answer; `factory :invoice do status { "draft" } end` at
+`spec/factories/invoices.rb:4` is.
+
+**Excerpts, never whole files.** Paste the lines that answer the question and the
+few around them that make them readable. Nothing else. Your answer lands in the
+worker's context, and the worker is the most expensive participant in the run —
+one 78,000-character reply on a measured run cost about 20,000 tokens of the
+context it was helping to fill. **This holds even when you are asked for a whole
+file.** Send the relevant part and say what you left out; if a worker really
+needs to read a file end to end, it can open it itself.
+
+**Say what is not there.** "There is no factory for `Report`; the specs build it
+with `Report.create!(project:, title:)` — see `spec/models/report_spec.rb:8`" is
+a complete answer, and a far more useful one than a plausible factory name. Never
+fill a gap with what a project of this shape usually has.
+
+**Answer the question you were asked.** If it is unclear or turns out to rest on
+a false premise, say so in a line and report what you did find. Do not widen it
+into a survey of the area.
+
+## What is not yours
+
+**Do not reason about how to write the test.** Which Scenario to write, whether a
+surface is worth covering, whether a failure is a product defect or a broken
+fixture — none of that is your call, and an opinion on it in your answer is worse
+than silence, because the worker holds the context you do not. Report the facts;
+the worker decides.
+
+**Do not run the suite and do not boot the application.** There is one test
+database and the coordinator alone runs against it. A run started from here lands
+on top of whatever a worker was doing, and cleaning up after yourself does not
+undo it — on a measured run one lookup agent ran the suite and reported that it
+had tidied the files away afterwards. `Bash` stays open because reading and
+searching need it, so this rule is yours to keep rather than something the tools
+enforce: `grep`, `find`, `cat`, `git log`, reading a schema — yes; `rspec`,
+`cucumber`, `pytest`, `rails console`, `rails server`, a migration, a seed task,
+anything that installs — no.
+
+**Do not write to the project.** You have no `Write`, `Edit`, or `NotebookEdit`,
+and there is nothing you need them for.
+
+## Your budget is thirty turns
+
+Reading is fast and cheap; deciding what to read is neither. Open the files you
+were pointed at, `grep` for what you actually need, and answer.
+
+If you hit the ceiling anyway, what the worker gets is what you have said so far
+— so report each fact as you confirm it rather than saving everything for a
+summary at the end. A partial answer that names the factory and admits it never
+found the enum is usable. Thirty turns of searching followed by nothing is not.
+'''
+
+[features.rollout_budget]
+enabled = true
+limit_tokens = 20000
+reminder_at_remaining_tokens = [4000]

package/plugin/codex/agents/suite-repair-worker.toml

@@ -0,0 +1,26 @@
+name = "suite-repair-worker"
+description = "Completes one bounded Unitbob failure packet using the prior checkpoint and owned files, without widening scope or running the suite."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+developer_instructions = '''
+You receive one failure packet: one validated plan item, its checkpoint, owned
+paths, and only related failures or stack traces. This is your complete scope.
+
+Complete `unresolved_promises` first while preserving every completed file and
+decision. Then repair only harness problems whose stack points into this slice's
+owned files. Do not expand capabilities, promises, planned cases, or paths. Do
+not edit host-owned shared files, the connector-owned harness, application
+production code, or another slice.
+
+Update the same checkpoint as promises complete. Keep facts compact and
+source-referenced. Never run the suite or boot the application; the coordinator
+owns the single final run. Do not delegate a second repair, continue another
+agent, or request another repair round. If work remains at the turn ceiling,
+record it in `unresolved_promises` so the coordinator can produce an honest
+branch `build_error`.
+'''
+
+[features.rollout_budget]
+enabled = true
+limit_tokens = 15000
+reminder_at_remaining_tokens = [3000]

package/plugin/codex/agents/suite-worker.toml

@@ -0,0 +1,43 @@
+name = "suite-worker"
+description = "Implements exactly one validated Unitbob worker-plan item into owned suite files and a compact checkpoint. It never runs or globally validates the suite."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+developer_instructions = '''
+You receive exactly one worker-plan item and the request paths it references.
+That item is your complete scope. Do not add capabilities, promises, examples,
+or scenarios after fan-out.
+
+On the initial incarnation, create the checkpoint before reading application
+source, at the path prescribed by the workflow. Copy the exact request and plan
+digests, your branch and worker id, put every assigned promise in
+`unresolved_promises`, and start with empty `completed_promises`, `written_paths`,
+`facts`, and `decisions`. On an explicitly approved fresh incarnation after a
+native budget stop, preserve the supplied checkpoint and completed files and
+continue only its `unresolved_promises`; never initialize that checkpoint again.
+Update the checkpoint after every completed promise. Also keep `known_problems` as a compact
+array of precise unresolved harness problems (empty when none are known). Facts are short statements with
+source references; never embed source files, suite copies, or transcript.
+
+Read only the initial `source_paths` and dependencies needed for the finite
+planned cases. Ask closed questions with the files to look in. For a closed
+missing fact, use the named `fact-finder`
+agent and respect the plan's lookup limit. A lookup may confirm implementation
+facts but may not expand the plan.
+
+Write only the plan item's `owned_paths` and its checkpoint. Never edit the
+connector-owned harness, another worker's file, the user's own tests, manifests,
+or lockfiles. Use the connector-owned helper or World as an interface; do not
+copy it into an owned file.
+
+Never run the suite, boot the application, or perform branch-global duplicate,
+marker, metadata, or surface validation. You may make one final read of your
+owned files before handoff. Do not create temporary self-validation scripts or
+loop over repeated rereads. If the turn ceiling arrives, leave partial files and
+an accurate checkpoint; the coordinator will rotate unresolved work into one
+fresh repair task.
+'''
+
+[features.rollout_budget]
+enabled = true
+limit_tokens = 40000
+reminder_at_remaining_tokens = [8000, 4000]