unitbob 0.4.0 → 0.4.2

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.2 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

@@ -27,6 +27,7 @@ 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]
@@ -38,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.
@@ -86,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;

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/validateWorkerCheckpoints.js

@@ -74,14 +74,25 @@ function validateCompactFacts(value, label, errors) {
         return;
     }
     for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            errors.push(`${label}: $.facts[${index}] must be an object with fact and source_refs; got ${jsonType(entry)}`);
+            continue;
+        }
         const fact = entry;
-        if (!fact || typeof fact.fact !== 'string' || !fact.fact.trim())
+        if (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())) {
+        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 ?? {})) {
+        if ('source' in fact || 'transcript' in fact || 'suite' in fact) {
             errors.push(`${label}: facts[${index}] may not embed source, transcript, or suite copies`);
         }
     }
 }
+function jsonType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "unitbob",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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"

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,33 @@
+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. The normative JSON shape of one facts entry is:
+```json
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+```
+Every facts entry is an object in that shape, never a string. Before handoff,
+make one final read of the checkpoint and confirm every `facts` entry is an
+object in the normative shape above. 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,50 @@
+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. The normative JSON shape of one facts entry is:
+```json
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+```
+Every facts entry is an object in that shape, never a string. 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. During that final read, confirm every `facts` entry
+is an object in the normative shape above and correct the checkpoint if it is
+not. 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]