santos/dev: crew family, Pareto crewing and the Model Pool, custom connections

.gitignore

@@ -37,3 +37,4 @@ internal/manual/pages.pack.gz
 # at the root is what the next lane's `git add -A` sweeps up: two of these were
 # committed that way on #1173 and had to be taken back out.
 .furrow/
+bench/idle-surface/runs/

Makefile

@@ -2,7 +2,7 @@
 # anywhere else — so a stale copy can't shadow a fresh one.
 BINARY := bin/codeaf
 
-.PHONY: all build build-check debug demo-home embed manual-pack-law furrow test test-focus test-report test-quick test-touched test-touched-preflight pr-ready test-laws fmt-check test-packed-manual manual-gates test-remote test-e2e test-e2e-tui vet check size clean \
+.PHONY: all build build-check build-cross debug demo-home embed manual-pack-law furrow test test-focus test-report test-quick test-touched test-touched-preflight pr-ready test-laws fmt-check test-packed-manual manual-gates test-remote test-e2e test-e2e-tui vet check size clean \
         changelog changelog-new changelog-check changelog-preview
 
 # What the shipped binary is allowed to weigh, in bytes, checked in beside the
@@ -91,6 +91,7 @@ furrow:
 # then to PATH — which is what it does here.
 build: furrow embed
 	go build -tags=$(MANUAL_TAG) -trimpath -ldflags="-s -w $(BUILD_STAMP)" -o $(BINARY) ./cmd/codeaf
+	go build -trimpath -ldflags="-s -w $(BUILD_STAMP)" -o bin/plandb ./cmd/plandb
 
 debug: furrow embed
 	go build -tags=$(MANUAL_TAG) -trimpath -ldflags="$(BUILD_STAMP)" -o $(BINARY) ./cmd/codeaf
@@ -185,6 +186,9 @@ test-touched-preflight:
 		exit 2; \
 	fi
 
+# A directory under its own go.mod is another module — a bench fixture the
+# task door edits, not a package of this one — and `go test ./that/dir` from
+# here answers "does not contain package". The walk skips those.
 test-touched: test-touched-preflight
 	@set -eu; \
 	base="$${BASE:-origin/dev}"; \
@@ -197,6 +201,12 @@ test-touched: test-touched-preflight
 		done | sort -u)"; \
 		pkgs=""; \
 		for dir in $$dirs; do \
+			nested=0; walk="$$dir"; \
+			while test "$$walk" != "." && test "$$walk" != "/"; do \
+				if test -f "$$walk/go.mod"; then nested=1; break; fi; \
+				walk="$$(dirname "$$walk")"; \
+			done; \
+			if test "$$nested" = 1; then continue; fi; \
 			if ls "$$dir"/*.go >/dev/null 2>&1; then pkgs="$$pkgs ./$$dir"; fi; \
 		done; \
 	fi; \
@@ -339,7 +349,24 @@ size: build
 
 # The end-of-change ritual in one word: prove it, then ship the binary, then
 # weigh it.
-check: vet fmt-check test test-packed-manual size
+# Read the release workflow so this gate follows the shipped platform list.
+# The six builds share the normal GOCACHE, so a warm box pays far less than a
+# cold one; the printed duration is the whole step, cold or warm.
+build-cross:
+	@set -eu; started=$$(date +%s%N); \
+	targets="$$(awk '/^[[:space:]]*targets=\($$/ { in_targets=1; next } in_targets && /^[[:space:]]*\)/ { exit } in_targets { gsub(/"/, ""); if (NF == 2) print $$1 "/" $$2 }' .github/workflows/release.yml)"; \
+	test -n "$$targets"; \
+	for target in $$targets; do \
+		goos=$${target%/*}; goarch=$${target#*/}; \
+		printf 'build-cross: %s/%s\n' "$$goos" "$$goarch"; \
+		if ! CGO_ENABLED=0 GOOS="$$goos" GOARCH="$$goarch" go build ./...; then \
+			printf 'build-cross: FAILED building %s/%s\n' "$$goos" "$$goarch" >&2; exit 1; \
+		fi; \
+	done; \
+	finished=$$(date +%s%N); \
+	printf 'build-cross: total duration %ss (rounded up, an upper bound on the added time)\n' "$$(( (finished - started + 999999999) / 1000000000))"
+
+check: vet fmt-check test test-packed-manual size build-cross
 
 # ── the changelog ───────────────────────────────────────────────────────────
 #

README.md

@@ -253,6 +253,22 @@ when the hosted relay does. [How it works](docs/REMOTE.md).
 | how long it lasts | one session | conversations, tasks and standing orders that outlive the window |
 | without you | it stops | headless, standing orders, a phone in your pocket |
 
+## Performance benchmark
+
+One Go binary, 53 MB on disk: up to 21x smaller than the field.
+
+|                          | CodeAF  | claude         | heaviest rival measured |
+| ------------------------ | ------- | -------------- | ----------------------- |
+| On disk                  | 53 MB   | 224 MB, 4x     | 1.1 GB, 21x (omp)       |
+| RAM per added session    | 27 MB   | 216 MB, 8x     | 653 MB, 24x (opencode)  |
+| 16 idle sessions         | 507 MB  | 3.5 GB, 7x     | 10.5 GB, 21x (opencode) |
+| Peak during one turn     | 122 MB  | 421 MB, 3.4x   | 1.0 GB, 8x (opencode)   |
+| Resume a 50-turn session | 145 ms  | 392 ms, 2.7x   | 3.0 s, 20x (opencode)   |
+
+Sixteen of ours fit in half a gigabyte; claude's fourth tab alone needs more.
+
+Harness, method and every table: [docs/benchmarks/performance](docs/benchmarks/performance/).
+
 ## Docs
 
 - `codeaf manual`, or `alt+.` for the key map. The manual ships in the binary and the chat reads it too.

bench/bashloop/BASHLOOP-DO-DOOR.md

@@ -0,0 +1,141 @@
+# The do door — the six cells through `codeaf do`, and what stopped them
+
+*2026-09-17. The companion report to the task-door grid — the same six cells,
+the same two arms, the same pinned model (`deepseek/deepseek-v4-flash`), the
+same fixtures, graders and reading discipline, driven through the product's
+adaptive-run door instead of the engine's task door.*
+
+**The headline first: the grid was not spent, because the arming gate failed.
+On the do door the two arms are the same arm by every observable the door
+itself keeps — no belt fingerprint appears in arm B's workers — and the brief's
+own law says two identical arms are not a comparison. What ran is the arming
+probe: a c1 pair and a c5 pair, both arms, n=1 each. Their rows are below. The
+other four cells are recorded as not run, at the stage that stopped them.**
+
+## The door, the flag, the dry run
+
+The driver carries `-door task|do` (default `task`). Door `do` launches the
+built binary as a subprocess, the rig's own shape
+([bench/deepswe/run.sh](../deepswe/run.sh)):
+
+```sh
+codeaf do -w <fixture> -model deepseek/deepseek-v4-flash -plan-model deepseek/deepseek-v4-flash \
+  -db <home>/graph.db -keep -timeout 1800s -yes-spend -json < <brief>
+```
+
+with `CODEAF_HOME` and `HOME` on the throwaway home and `CODEAF_TASK_BELT`
+unset for arm A, `=bash` for arm B — the only byte that differs between the
+arms. The dry run prints every invocation for both doors; the driver's tests
+prove the two doors' blocks and that the arms differ only in the belt variable
+(`driver_test.go`).
+
+The door's exit ladder, in its own words: **0** done · **1** could-not-run ·
+**2** ran-not-finished · **3** limit-stopped · **4** needed-answer · **124**
+the driver's wall fired first. `stdout` is one JSON envelope; `stderr` is the
+stream, kept as `run.log` beside each row.
+
+## The rows that ran (the arming probe)
+
+Read off the door's own store, the home's `graph.db` — cost and models from
+`usage` (the door's per-call ledger, the same per-response accounting the task
+door's `v3/usage.jsonl` keeps), steps from the transcript's finished tool calls
+(the task door's `took` unit), the diagnostics from the tool results, the
+family shape from `nodes`:
+
+| cell | arm | n | pass | rate | ending (exit) | med steps | med $ | med wall | invalid | trunc | idiom | parts | changed |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| c1 | A | 1 | 1 | 1.00 | done (0) | 5 | $0.0053 | 110s | 0 | 0 | 0 | 0/0 | 29 |
+| c1 | B | 1 | 1 | 1.00 | done (0) | 21 | $0.0188 | 265s | 0 | 0 | 0 | 0/0 | 31 |
+| c5 | A | 1 | 0 | 0.00 | ran-not-finished (2) | 87 | $0.0400 | 487s | 0 | 0 | 0 | 0/0 | 43 |
+| c5 | B | 1 | 1 | 1.00 | ran-not-finished (2) | 93 | $0.0696 | 922s | 0 | 0 | 0 | 2/3 | 45 |
+
+Over the graded passes: arm A (n=1) — 5 steps · $0.0053 · 110s. Arm B (n=2) —
+medians 57 steps · $0.0442 · 594s. Both arms graded pass on c1 (the c5 grader
+passed arm B's work: suite green, 2 of 3 parts landed as their own work, one
+node failed — `task-2-x2`, read straight off the `nodes` table). Arm A's c5 ran
+the four packages green and still graded no: the family never left one pair of
+hands, and the run ended exit 2. The wall column is the envelope's own seconds
+(`wall_source=node`); the driver's backstop never fired.
+
+The cells not run, with the stage that stopped them:
+
+| cell | arm | reading |
+| --- | --- | --- |
+| c2, c3, c4, c6 | A and B | not run — the grid was withheld at the belt-arming gate (below); spending four cells on one arm would have been the wrong answer the brief names |
+
+## The arming gate, and how it was checked
+
+The fix this branch carries (`36a689926`) arms the belt on the do door's run
+leaves: `orchestrate.go`'s `newChild` now builds its `Config` with
+`bashBelt: bashBeltAsked()` (`InTask` was already true, and
+`Config.mayBashBelt` is `InTask && bashBelt`). The task door's workers take the
+same flag at `task_run.go`'s worker construction. That wiring is real, and it
+is where the task door's arming is enough — its workers do the work themselves.
+
+The do door is built differently: a run leaf's file work is done by the
+subharness's own executor, not by the leaf agent's own hands. So the probe
+looked for the belt in the three places the brief names, using only the door's
+own records:
+
+1. **The worker's own trace** — the store's `transcript` table, per node. Both
+   arms' workers called the same executor toolset: c5 arm A `sh`×73, `edit`×5,
+   `read`×4, `share`×2, `write`×3; c5 arm B `sh`×80, `edit`×6, `read`×2,
+   `share`×1, `write`×4 (c1 the same shape, smaller). Arm B carries **zero**
+   calls of a bash-belt hand (`bash` — the belt's own shell, `branchBash` — is
+   a different name than the linear executor's `sh`), and the belt's tool
+   composition (`bashBelt()`: branch bash, document, jobs, manual)
+   appears nowhere.
+2. **The composed page** — per-node first-turn `prompt_tokens` off
+   `usage_turns`: arm A 4640/6468/6667, arm B 4663/6714/6552/6771 (c1's three
+   and four nodes). Within a percent either way. The belt swaps whole pages
+   (`bashworker.md` in place of the fan-out page, belt facts into the frame);
+   a page swap that moves nothing measurable is not there.
+3. **The belt's own diagnostics** — the one-action envelope's rejections
+   ("no action executed") and the plan CLI's name (`plandb`, which the
+   bashworker page teaches): **zero** in every transcript body and event
+   payload on both arms. On the task door arm B's rows carried 1–17 invalid
+   actions each; here the envelope never armed, which is itself the fingerprint
+   of absence.
+
+One behavioral divergence between the arms did show — c5 arm B spliced a
+family (2 of 3 root children done) where arm A stayed single-handed and graded
+no — but nothing in that run's trace names the belt, and at n=1 a family-shape
+difference is run noise as far as the switch is concerned. The belt cannot be
+credited with it and the grid cannot be built on it.
+
+**Verdict: the belt does not reach the do door's workers.** The flag arms the
+leaf's `Config` and stops there: the leaf's file work is executed by the
+subharness executor, which is built without the belt, and the leaf's own prompt
+is composed without the belt's pages. This is the DeepSWE finding one seam
+deeper — the switch now reaches the process *and* the leaf `Config`, and still
+arms nothing the door's records can see. `planSeed`'s store never seeds on this
+door either (it runs from `TaskGraph.admit`; the do door registers and does not
+admit), so the plan-CLI path has no purchase here either.
+
+## The two sentences the brief asks for
+
+The do door does not change the task-door verdict, because it cannot re-measure
+it: with the belt invisible on this door, both arms are one arm, and the honest
+do-door reading is "unmeasured", not "agree" or "disagree". The doors diverge
+structurally — the task door builds workers at `newTaskAgentOn` whose toolbelt
+and pages the belt composes, while the do door builds run leaves at
+`orchestrate.go`'s `newChild` and hands the actual work to the subharness's own
+executor, so the belt stops at the leaf's `Config` and nothing downstream of
+that seam ever reads it.
+
+## Where the readings live
+
+Raw, beside this report, in `bench-results/bashloop-do-door/` — per results
+root (`bashloop-do-pair2` = the c1 pair, `bashloop-do-c5probe` = the c5 probe,
+`bashloop-do-pair` = the first pair, run before the store reader existed, whose
+rows read hollow: `steps=0 $0.0000`, the defect that forced the reader): the
+driver's `bashloop.csv`, each run's JSON envelope (`do.json`), its stderr
+stream (`run.log`), and the home's own `graph.db` and `logs/calls.jsonl`.
+On the Spark the full run directories (fixtures and all) are
+`/home/santosh/work/bashloop-do/bench-results/`.
+
+The first pair also earned the one driver change this report rides with: the
+do door keeps its numbers in the store, not in the `v3` ledger-and-journals
+layout the task door writes, so `door.go` reads the store read-only (same
+helpers, same units, one new reader) and the row now carries the family shape
+the c5 grader needs.

bench/bashloop/README.md

@@ -0,0 +1,109 @@
+# bashloop — the arm bench for the bash-only task loop
+
+Wave 3 of the bash-task-loop experiment
+([DESIGN.md](../../docs/design/bash-task-loop/DESIGN.md)): the same briefs run
+on both belts — arm A with `CODEAF_TASK_BELT` unset (the belt as shipped),
+arm B with `CODEAF_TASK_BELT=bash` — n replicates, cells interleaved so the
+arms share the day. Every cell is graded by code: the fixture's own suite, a
+mechanical diff, or a document's presence and coverage. No LLM judges
+anything, per [bench/README.md](../README.md).
+
+An arm is named by belt AND seats. `-seats one` (the default) runs the one
+`-model` on every seat — arms `A-one` and `B-one`, the grid as it was before a
+crew arm existed. `-seats crew` runs the five seat rows the machine's own
+profile holds instead, arms `A-crew` and `B-crew` — so the grid can answer
+whether a person on the tuned crew is better off beside the one-model
+comparison. `-arms` selects any subset by name. A crew arm's rows quote every
+model the run billed — the crew's worker, planner and auxiliary seats — which
+is what its `models` column and `seats` column carry.
+
+## Dry run first
+
+```sh
+go run ./bench/bashloop -dry-run          # every invocation: arm, cell, replicate, env, brief
+go run ./bench/bashloop -mode pair -dry-run   # the same-question pair
+go run ./bench/bashloop -dry-run -arms A-crew,B-crew   # a crew arm prints its five seat rows
+```
+
+The dry run composes every invocation — arm, cell, replicate, env, model,
+wall, brief, and where its record lands — and executes nothing. A crew arm
+adds its five seat rows, one per tier, named with the model and the rung the
+machine's own profile filled it with. The dry run is the check
+bench/README.md's honest-wiring rule asks for; the test `driver_test.go`
+proves it (every invocation printed, the arms differing only in the belt
+variable, the default grid unchanged, and a crew arm differing from its
+twin only in the seat rows).
+
+## Live grid
+
+```sh
+go run ./bench/bashloop                       # grid: 6 cells × 2 arms × 3 replicates
+go run ./bench/bashloop -mode pair            # one brief, both arms, n=1 — the first smoke
+go run ./bench/bashloop -cells c1,c3          # a subset
+go run ./bench/bashloop -out bench-results/bashloop/manual-run
+go run ./bench/bashloop -door do              # the same grid through the product's do door
+go run ./bench/bashloop -seats crew            # both belts on the profile's crew seats
+```
+
+Each invocation seeds its own fixture repo from `fixtures/` (committed, so
+the diff is measurable), works in a throwaway `CODEAF_HOME`, starts one task
+through the engine's own task door, waits on the landing through the event
+lane, and is read back off the disk the engine wrote: cost from the home's
+usage ledger, steps from the family journals' `took` lines, the ending and
+the wall from the task notice, the fan-out shape from the graph checkpoint.
+
+## The second door
+
+`-door do` runs the same cells, arms, fixtures, homes, readings and graders
+through the product's adaptive-run door instead of the engine's task door:
+the driver launches the built binary as a subprocess, the way
+[bench/deepswe/run.sh](../deepswe/run.sh) drives it —
+
+```sh
+codeaf do -w <fixture> -model <pinned> -plan-model <pinned> \
+  -db <home>/graph.db -keep -timeout <seconds> -yes-spend -json < <brief>
+```
+
+with `CODEAF_HOME` and `HOME` pointed at the throwaway home and the arm's
+belt switch in the environment. The door's own exit ladder reads
+0 done · 1 could not run · 2 ran and did not finish · 3 a limit stopped it ·
+4 needed an answer · 124 the driver's wall fired first, and the ending word
+in the row is that word. The dry run prints the exact invocation for this
+door too. The door edits the fixture in place (`-w`), so the grader reads
+the seeded fixture directory itself, and the numbers are read from the
+door's own run store — the home's `graph.db`: cost and models from the
+`usage` table (the door's per-call ledger), steps from the transcript's
+finished tool calls, the diagnostics from the tool results, the family
+shape from the `nodes` table. The belt must be seen armed in the do door's
+own trace (a belted worker's shell hand is named `bash`, where the linear
+subharness's own executor names it `sh`; the envelope rejections and the
+plan-CLI's name are the other fingerprints) before its rows are worth
+reading — the do-door report names that check.
+
+## The cells
+
+| cell | shape | graded by |
+| --- | --- | --- |
+| c1 | small fix — one failing suite | the suite green, tests untouched |
+| c2 | feature — a new package + tests | suite green, package present, existing files untouched |
+| c3 | multi-file refactor — reads-heavy | suite green, one copy of the math, public surface unchanged |
+| c4 | report from a document corpus | REPORT.md present, four sections, grounded |
+| c5 | wide job — four independent packages | suite green, children landed in the graph, INTEGRATION.md |
+| c6 | kept-tool image | the image exists and is referenced |
+
+The medians the design doc quotes — steps, cost, wall over the graded
+passes, per arm and cell, plus the branch-only diagnostics — are printed by
+the driver into the run's CSV (`bashloop.csv`). The summary table groups by
+cell and arm name and adds a `models` column; the CSV carries the arm's
+seats (`one` or `crew`) beside its belt letter. The verdict words stay in
+the design document.
+
+## Reading the rows
+
+`cost_usd` is the home's own ledger sum — the provider's per-response
+accounting, the only honest source on a shared key (bench/README.md's cost
+rule). `unbilled` counts the rows whose receipt the provider never returned;
+a cost that reads low says so in that column. `ending` is the engine's own
+state word; a row with `ending=setup-failed` never started. Wall is the
+node's own record when it kept one and the driver's clock otherwise, and
+`wall_source` says which.