@turri-dev/cli 0.1.3-next.26f08c5 → 0.1.3-next.420ce7e

package/dist/regenerate/test-scripts.js

@@ -335,7 +335,15 @@ async function runScript(cwd, script, args, logDir, options = {}) {
     const noted = withScriptLineNote(text, script);
     // Its failures, counts and end are what the agent is shown; the whole is kept, a read_output away.
     const log = keepTestOutput(logDir, basename(script), noted);
-    return { command: shown(script), exitCode: timedOut === true ? 124 : exitCode, output: shownTestOutput(noted, log), timedOut: timedOut === true, timeoutMs, ...(log !== undefined ? { log } : {}) };
+    return {
+        command: shown(script),
+        exitCode: timedOut === true ? 124 : exitCode,
+        output: shownTestOutput(noted, log),
+        timedOut: timedOut === true,
+        timeoutMs,
+        elapsedMs: Date.now() - started,
+        ...(log !== undefined ? { log } : {}),
+    };
 }
 /** What bash says when a line of the script itself cannot run: a command or file that is not there, or not runnable. */
 const OWN_LINE_FAILURE = /: (No such file or directory|command not found|Permission denied)$/;
@@ -589,6 +597,19 @@ function loopNotice(loop) {
         "the failure with fresh eyes, and you will be given what it finds.",
     ].join("\n");
 }
+/**
+ * How long a run took against its time limit, in a line: for whoever judges it or works out its cause - so a run that
+ * ended on its own is never taken for one the limit stopped, nor the other way.
+ */
+export function runTiming(run) {
+    const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+    const limit = seconds(run.timeoutMs);
+    if (run.timedOut === true) {
+        return `The time limit stopped this run: it had run ${seconds(run.elapsedMs ?? run.timeoutMs)} of the ${limit} a test run may take, and had not finished.`;
+    }
+    const took = run.elapsedMs !== undefined ? `after ${seconds(run.elapsedMs)} of the ${limit} a test run may take` : `well within the ${limit} a test run may take`;
+    return `This run ended on its own - exit ${run.exitCode}, ${took}. The time limit did not stop it and played no part in how it ended.`;
+}
 /** A run the time limit stopped: failed, and what most often keeps a test run from ending. */
 function timedOutFailure(run, what) {
     const limit = Math.round(run.timeoutMs / 1000);
@@ -609,19 +630,34 @@ function timedOutFailure(run, what) {
         `the same ${limit} seconds, and a skipped or deleted test does not count as a fix.`,
     ].join("\n");
 }
+/** A command `timeout` could not start, or a shell could not find - on a line of its own. */
+const COULD_NOT_RUN = /^(?:[^:]*: )?failed to run command [‘'`"]?([\w.+-]+)[’'`"]?: No such file or directory$/;
+const NOT_FOUND = /^(?:[^:]*: )?(?:line \d+: )?([\w.+-]+): command not found$/;
 /**
  * What a failed run says is not installed where it ran - the command, when its output names it - or undefined when
- * the run failed for another reason. Exit 69 is the testing scripts' own way to say a toolchain is missing; exit 127,
- * or a shell or `timeout` that could not find the command, says it as well.
+ * the run failed for another reason. A missing command is the cause only on evidence that it ended the run: exit 69,
+ * the testing scripts' own way to say a toolchain is missing, or 127, what a shell or `timeout` gives for a command it
+ * could not find - else a command not found on the last line the run printed, nothing having run after it. Earlier in
+ * the output it is a warning, not the failure: a shell profile's, an optional tool probed for, a fallback taken - and a
+ * run that failed for its own reasons is the agent's to fix, not a stop for the person.
  */
 export function missingToolchain(run) {
-    const named = /failed to run command [‘'`"]?([\w.+-]+)[’'`"]?: No such file or directory/.exec(run.output) ??
-        /(?:^|\n)(?:[^\n:]*: )?(?:line \d+: )?([\w.+-]+): command not found/.exec(run.output);
-    if (named !== null)
-        return { command: named[1] };
-    if (run.exitCode === 69 || run.exitCode === 127)
+    if (run.exitCode === 0)
+        return undefined;
+    const lines = run.output.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+    const named = (line) => COULD_NOT_RUN.exec(line)?.[1] ?? NOT_FOUND.exec(line)?.[1];
+    if (run.exitCode === 69 || run.exitCode === 127) {
+        // The command is the last one named: the one the run stopped on.
+        for (let at = lines.length - 1; at >= 0; at -= 1) {
+            const command = named(lines[at]);
+            if (command !== undefined)
+                return { command };
+        }
         return {};
-    return undefined;
+    }
+    const last = lines.at(-1);
+    const command = last !== undefined ? named(last) : undefined;
+    return command !== undefined ? { command } : undefined;
 }
 /** Where `command` is on this machine's PATH, or undefined when it is not there. */
 export function onThisMachine(command) {

package/dist/regenerate/unit-review.js

@@ -63,6 +63,17 @@ export function unitReviewTask(options) {
         options.spec.trim(),
         "</specification>",
         "",
+        ...(options.testingScript !== undefined
+            ? [
+                "The harness runs the unit tests with this script, and it decides whether they pass. Read it for which tests it",
+                "runs and how: a test it never reaches - a file it does not pick up, a folder it does not look in - is not run, and",
+                "checks nothing.",
+                `<unit testing script path="${options.testingScript.path}">`,
+                options.testingScript.content.trimEnd(),
+                "</unit testing script>",
+                "",
+            ]
+            : []),
         ...(options.cases !== undefined ? [...codeReviewCasesBlock(options.cases), ""] : []),
         // A job that touches no functional spec is held only to that: the checks of behaviour are not its.
         ...(mechanical ? [] : ["Check that the code does what the specification states for this work:"]),

package/dist/regenerate-cli.js

@@ -19,7 +19,7 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
-  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --judge-model <p/id>     its judge-model: the judge and the test review
   --review <true|false>    its review: whether the code and its tests are reviewed once they pass

package/dist/resume-line.js

@@ -0,0 +1,4 @@
+/** pi's line on the way out that says how to resume the session, with turri in place of pi as the command to run. */
+export function resumeLine(text) {
+    return text.replace(/^((?:\x1b\[[0-9;]*m)*To resume this session:(?:\x1b\[[0-9;]*m)*\s+)pi(?= )/m, "$1turri");
+}

package/dist/spec-tools.js

@@ -1,8 +1,8 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata } from "./plain/parser.js";
+import { plainFileParser } from "./plain/parser.js";
+import { importingModules, isImportModule } from "./regenerate/requires.js";
 import { resolveTemplateDirs } from "./regenerate/paths.js";
 import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
 import { MissingFunctionalitiesError } from "./plain/errors.js";
@@ -62,24 +62,12 @@ export function createSpecDiffTools(options) {
             // file that cannot be parsed. A module with no functional specs yet is not broken. An import
             // module - definitions only, say - is not a module of its own: it is parsed as the modules
             // that import it read it, the one the change is built for among them.
-            const importers = (file) => {
-                const name = basename(file, ".plain");
-                const dir = dirname(resolve(cwd, file));
-                return readdirSync(dir)
-                    .filter((entry) => entry.endsWith(".plain"))
-                    .map((entry) => join(dir, entry))
-                    .filter((path) => {
-                    try {
-                        return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-            };
-            const imported = importedNames(resolveTemplateDirs(resolve(cwd, params.plain_file)));
             const toParse = [
-                ...new Set([params.plain_file, ...touched].flatMap((file) => imported.has(basename(file, ".plain")) ? importers(file).filter((path) => !imported.has(basename(path, ".plain"))) : [resolve(cwd, file)])),
+                ...new Set([params.plain_file, ...touched].flatMap((file) => {
+                    const path = resolve(cwd, file);
+                    const importing = isImportModule(path) ? importingModules(path) : [];
+                    return importing.length > 0 ? importing : [path];
+                })),
             ];
             for (const path of toParse) {
                 const file = relative(cwd, path);
@@ -129,27 +117,3 @@ export function createSpecDiffTools(options) {
         },
     };
 }
-/** The module names some .plain file in these folders imports: import modules, not codebases. */
-export function importedNames(dirs) {
-    const names = new Set();
-    for (const dir of dirs) {
-        let entries;
-        try {
-            entries = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            try {
-                const imports = readPlainSourceMetadata(readFileSync(join(dir, entry), "utf8")).metadata[IMPORT_DIRECTIVE];
-                for (const name of imports ?? [])
-                    names.add(name);
-            }
-            catch {
-                // A file that does not read imports nothing.
-            }
-        }
-    }
-    return names;
-}

package/docs/authoring-plain.md

@@ -196,18 +196,21 @@ the reading that fits the rest of the spec, and marks each such decision in its
 code, environment and turri problems to the builds, and stops when a functionality keeps
 struggling after the spec was clarified, when two cycles change nothing, or after twenty.
 
-For an existing project, `bud` works the same way, scoped to one feature: intent → scope →
-product → review. After a short feature-intent interview it asks product questions one at a time -
-a trigger and its outcome, an edge case, a rule - and every answer is one spec change, a git diff
-written with `write_spec_diff` and built the moment it is written. A change to something already
+For an existing project, `bud` works the same way, scoped to one feature: intent → scope → product.
+It first asks how many questions the product phase may ask - light, medium, thorough or best
+judgement, as `brood` does - then a short feature-intent interview, then product questions - a
+trigger and its outcome, an edge case, a rule - and every answer is a spec change, a git diff
+written with `write_spec_diff` and built the moment it is written, before the next question. What
+the questions leave open it decides itself, a spec change each. A change to something already
 specified, built or still to build, is put to the user first and is a spec diff too: what is left to
-build is worked out again from the spec.
+build is worked out again from the spec. It ends on the person's confirmation of a short summary of
+the feature's changes.
 
 What keeps the interview honest is the harness, not the interviewer:
 
 - **Every question offers choices** (`ask_user` refuses a question without them), and each
   answer maps to one spec change.
-- **Every answer is written before the next question.** In `brood`'s product phase `ask_user` refuses
+- **Every answer is written before the next question.** In the product phase of `brood` and `bud`, `ask_user` refuses
   a new question until the last answer is a spec change - see [skills and gates](skills-and-gates.md).
 - **Each phase ends on the person's confirmation** of a short summary, not on the interviewer's word.
 

package/docs/config.md

@@ -122,7 +122,7 @@ models:                              # each agent role's model, thinking and tur
 | key | what it sets | left out |
 | --- | --- | --- |
 | `module` | the `.plain` file `turri regenerate` and the chat's `regenerate` build when none is named, from the project root | a file has to be named |
-| `harness-model` | the model `turri` starts on - the one you talk to - the one that diagnoses a job that failed for good, and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
+| `harness-model` | the model `turri` starts on - the one you talk to - and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
 | `coding-model` | every render: functionalities, spec diffs, conformance tests, repairs, planning spec diffs, the explorer | `harness-model` |
 | `judge-model` | the judge and the test review of a conformance run | `coding-model` |
 | `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
@@ -158,7 +158,8 @@ wrong type, as if it were not there. `model:`, from before there were separate m
 | --- | --- |
 | `default` | every role not named below - but the conversation's side |
 | `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
-| `chooser`, `planner`, `diagnosis` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents, the diagnosis of a failed job. Unnamed, the chat's model |
+| `chooser`, `planner` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents. Unnamed, the chat's model |
+| `diagnosis` | the diagnosis of a job that failed for good: why it did not land, and what to do. Unnamed, the coding model the job ran on, thinking medium |
 | `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |
 | `coding` | the coding agent, the code fixer of a conformance run and the repair agent - the same as `coding-model`, which it wins over. `--model` on the command line, or a model chosen in the conversation (`engine`), wins over both |
 | `conformance` | the conformance agent |

package/docs/development.md

@@ -75,6 +75,7 @@ trust `turri-oss/turri`, the workflow `publish.yml` and the environment `npm`. R
 | `src/regenerate/confine.ts`, `src/regenerate/agent-shell.ts`, `src/regenerate/command-check.ts`, `src/regenerate/os-sandbox.ts`, `src/regenerate/audit.ts`, `src/regenerate/agent-env.ts`, `src/regenerate/shell.ts` | the file-tool fence and the walls around every agent command: the check, the OS sandbox, the audit, the module's environment, the host runner - see [sandbox](sandbox.md) |
 | `src/regenerate/engine.ts` | choosing and resolving render models |
 | `src/regenerate/job-panel.ts`, `src/regenerate/transcript-view.ts`, `src/regenerate/diff-view.ts` | the job panel, the side panel's colours, and a spec diff as they show it - highlighted and banded |
+| `src/regenerate/side-panel.ts`, `src/regenerate/panel-dock.ts` | the side panel, and the chat narrowed beside it when it is docked |
 | `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
 | `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
 | `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |

package/docs/headless.md

@@ -81,7 +81,7 @@ Useful options - `turri regenerate --help` lists all of them:
 
 | | |
 | --- | --- |
-| `--harness-model <provider/id>` | `harness-model`: the planner, the conformance chooser, the diagnosis of a failed pulse |
+| `--harness-model <provider/id>` | `harness-model`: the planner and the conformance chooser |
 | `--coding-model <provider/id>` | `coding-model` (`--model` too): the agents that build - with `:level` for how hard it thinks (`provider/id:high`); not given, the harness model's |
 | `--judge-model <provider/id>` | `judge-model`: the judge and the test review; not given, the coding model |
 | `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
@@ -151,7 +151,7 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
   "conformance_tests": "all",                                                       // all | chosen | module | false
   "review": false,
   "models": {
-    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser, the diagnosis
+    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser
     "coding":  { "model": "…", "thinking": "low" },
     "judge":   { "model": "…", "thinking": "medium" },
     "observed": { "coding": ["provider/id:low"], "planner": ["provider/id:medium"] }  // what each role really ran on

package/docs/regenerating.md

@@ -112,6 +112,10 @@ the planner's, the spec-steps agent's, the conformance agents' - is laid out in
 A module that `requires` another inherits its functional specs; one that `import`s another
 inherits its definitions, implementation reqs and test reqs.
 
+An import module - one a `.plain` file imports, or one kept in a `template/` folder - is no codebase of its own. A
+change to it is built in the modules that import it, through any import modules between, whose code is started; when
+none is, nothing is built, and the change goes in with the first of them built.
+
 Template search order: the plain file's own directory, then a sibling `template/`, then
 `--template-dir`, then `PLAIN_TEMPLATE_DIRS`.
 
@@ -160,6 +164,10 @@ runs the unit testing script itself**, and only that run counts (see
   tried. An agent circles a cause it has not thought of - an in-memory database every connection opens
   empty, a test runner that leaves the code off its path - and this is the way out. The rounds go on as
   before, up to 20; should the same failure come round three times again, the debugger looks again.
+  **A run the time limit stopped** is looked at by the debugger at once, told how long the run had and that the limit
+  stopped it: it finds what hangs - the root cause and the fix, as above - or that nothing does, the run getting on up
+  to the limit and needing more time than a test run may take. Then the pulse stops, rolled back and not retried, and
+  the person is told to raise `TURRI_COMMAND_TIMEOUT` or make the suite faster.
 - **It goes round in circles in its own runs.** An agent stuck on a failure can try the same few changes in
   turn - three signatures of a stand-in function, say - and run the tests after each, dozens of times in one
   turn. Its own `run_unit_tests` runs are watched (`createLoopWatch` in `test-scripts.ts`): the code folder back
@@ -218,7 +226,7 @@ and the `implement-unit-testing-script` and `implement-conformance-testing-scrip
 - **The formatting is the agents'.** The harness formats nothing: the scripts check, and leave their inputs as they
   found them. Every agent that writes code or tests is told to run, in its shell, the formatter its script checks with,
   on the files it changes, before the final run.
-- **A toolchain missing** where the checks run - exit 69, 127, `command not found` - stops the pulse as it does for the
+- **A toolchain missing** where the checks run - exit 69, 127, a `command not found` the run ended on - stops the pulse as it does for the
   tests: the person installs it, the agents install nothing.
 
 ### Checking its own work
@@ -262,7 +270,8 @@ Passing unit tests prove only what they check, and a coding agent is quick to wr
 next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code
 that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script
 passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It
-reviews both halves. The review is off by default - `review: false`, or the key left out - and so is the
+reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is
+not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the
 conformance tests' review: the work goes on once its tests pass.
 
 - **The code.** Every behaviour, edge case, validation rule and error the spec states for this work
@@ -499,16 +508,19 @@ testing script, stops before it starts and says which skill adds it.
 `prepare-environment-script:` in the config, else the one `prepare_environment*.sh` at the root, else in
 `test_scripts/` - on the build, before every run of the conformance testing script: the harness's own, and the agents'
 `run_conformance_tests`. Both get the same build folder - the code in place, or the same fresh copy - so what it sets up
-for that build, the conformance testing script finds. With conformance off it is not run. The conformance agents are
-shown it, before the conformance testing script.
+for that build, the conformance testing script finds. With conformance off it is not run. Every agent shown the
+conformance testing script - the explorer, the conformance agent, the judge, the code fixer and the repair agent - is
+shown it too, before the conformance testing script.
 
 **Where they run.** On this machine, as you would run them: unfenced - no sandbox, no command check, no audit - in
 your own environment with this machine's toolchains, turri's model providers' API keys alone left out. They are yours,
 and whatever they do is your doing. That is the only way the two scripts are ever run: the harness's own runs, and the
 agents' `run_unit_tests` and `run_conformance_tests`, which run them exactly as the harness does - through the host
 runner, in a process group of their own, so the time limit and a stopped job end the script and all it started. A
-toolchain the script needs and this machine lacks - exit 69, exit 127, or a `command not found` / `failed to run
-command` in its output (`missingToolchain`) - is yours to install, never the agent's: the agent is told to report it
+toolchain the script needs and this machine lacks - exit 69, exit 127, or a run that ended on a `command not found` /
+`failed to run command`, the last line it printed (`missingToolchain`) - is yours to install. Only on that evidence: a
+`command not found` earlier in the output, the run going on after it and failing for its own reasons, is a warning -
+a shell profile's, an optional tool probed for - and the failure is the agent's to fix. A missing toolchain is yours to install, never the agent's: the agent is told to report it
 with `report_environment_error` rather than work around it, and the pulse stops at the harness's first run of either
 script - unit or conformance - that cannot find it, rolled back, saying what to install (see
 [when the environment lacks something](#when-the-environment-lacks-something)). The code and the tests an agent wrote run unfenced inside the script too: what an agent runs with its own
@@ -562,7 +574,7 @@ It is raised two ways:
   is shown its output once, and a report made again after that stands. A report that stands ends its turn, the pulse
   stops, and what it said goes to you as it is;
 - **by the harness itself**: a testing script - the unit or the conformance one, in a code pulse, a conformance pulse or
-  the whole-suite run - that cannot find its toolchain (exit 69 or 127, `command not found`), or
+  the whole-suite run - that cannot find its toolchain (exit 69 or 127, a `command not found` the run ended on), or
   a credential `agent-env:` names that is not there when the pulse starts - before any agent does. What the harness
   found it works out at once - the diagnosis, not after a second failure - to say how to fix it on this machine.
 
@@ -575,10 +587,20 @@ not an install:
 > **lunch stopped: turri's sandbox kept its agents from reading `…/mise/installs/node/24.16.0/lib/node_modules/npm/bin/npm-cli.js` - it is on this machine; nothing is missing.**
 > To fix: let the agents read that toolchain - add its folder to `toolchains:` in config.turri.yaml, keeping what is there: `toolchains: [/Users/…/mise/installs/node/24.16.0]`. Nothing needs installing.
 
+A write the sandbox refused is told apart from a read - a report naming a lock file (`*.lock`, `*.lck`, `lockfile`, even
+one never made), or saying a write, a create or a lock not taken. No setting lets the agents write outside their
+module's folders, their own home and temporary folder and the package caches, and `toolchains:` only lets them read; so
+the stop names the lock and what fixes it instead. In your home - a tool that found it without `$HOME`, as a JVM does for
+`user.home` - it is having the tool use `$HOME` (`-Duser.home=$HOME` where the build starts its JVM); in a toolchain's own
+install, it is a setting of the tool's that keeps the write elsewhere, or a copy of the toolchain that keeps its writes in
+its cache. The agents are told such a refusal is the sandbox's, to report at once - not to work around it for half an
+hour.
+
 **The conversation heals it.** Told of the stop, it never regenerates the module again before the cause is fixed - a pulse
 stopped on its environment stops the same way again - and fixes what it can:
 
-- **hidden by the sandbox**: it adds the folder to `toolchains:` itself, says so in a line, and resumes;
+- **hidden by the sandbox**: it adds the folder to `toolchains:` itself, says so in a line, and resumes - a refused
+  write, which no setting fixes, it fixes in the project's own files when it can, and otherwise tells you what to do;
 - **a toolchain or a tool missing** - a JDK, Maven, Go, uv: it looks first for one installed off the PATH - Homebrew's opt
   folders, `/Library/Java/JavaVirtualMachines`, mise, asdf, sdkman, nvm - then asks you, with the exact command for this
   machine (`brew install openjdk@21`, `mise use -g java@21`), and on your yes runs it in its shell, checks the command is
@@ -820,7 +842,8 @@ coding agent that fixes the code is told the same of the tests: it can read them
 Before the test author starts, an explorer - an agent in
 the code's folder with the file tools alone: it reads the code, runs nothing and changes nothing - hands over everything
 the author needs, in parts: how to build and run it; how the conformance tests reach it as the project's
-conformance testing script runs them - the explorer is given the script, and says what it builds or
+conformance testing script runs them - the explorer is given the script, and the prepare script before it where there
+is one, and says what they build or
 installs and what the tests depend on or start (a package, a module, an entry point, by its exact name);
 how each functionality is reached from outside
 (the command, or the route, method and the request and response fields); what it needs around it; and
@@ -894,10 +917,17 @@ agent is told that a failure of the software itself - it does not build or start
 spec says it must not - is not the tests' to work around. When it fails, a judge - an agent that reads
 the code and the tests, changes neither, and holds both to the spec - decides which is wrong. It has the
 file tools and the web (`web_search`, `web_fetch`), to look up what a service the code calls answers - no shell: it
-judges from the code, the tests, the spec and the failing run's output, and its file tools write nothing:
+judges from the code, the tests, the spec, the conformance testing script word for word and the failing run's output,
+and its file tools write nothing. The explorer's account of how the code is invoked is in its prompt too, marked as
+written before the run and possibly wrong: the judge checks what it uses of it against the script and the files, and
+gives in `evidence` what it found itself. The script is fixed - neither agent can change it - so it is never the
+culprit: what it does with the tests, the tests fit; what it needs of the build, the code provides.
 
 - **the code:** the coding agent - in the code's folder, reading the tests but never changing them - fixes it,
-  and keeps its unit tests passing;
+  and keeps its unit tests passing. The judge quotes the spec's own words the code does not meet, or the testing
+  script's for what it needs of the build (`script_needs`: a build output, an entry point, a module) - each checked
+  by the harness against the text it quotes. The acceptance tests are in that text, labelled as their tests are:
+  for a spec change, those of every functional spec it touches, not only the last one's;
 - **the tests:** the conformance agent corrects them to what the spec says;
 - **the spec:** two functional specs cannot both hold, whatever the code does;
 - **the environment:** neither the code nor the tests can fix it - only the person can, in what the run is given:
@@ -939,16 +969,41 @@ spending the rest of its 20 attempts on it. Two failures are the same once what
 taken out of their lines - numbers, times, paths, colour codes, and the ids a service makes up for each
 response, a UUID or a correlation id. Nothing changes either when the agent sent to fix the code or the tests
 changes no file: two such fixes in a row, and the run stops. The conformance agent has the testing script in its prompt,
-and is told to fit the tests' own build to it.
+and is told to fit the tests' own build to it. The code fixer has the testing scripts its fixes are run by - the
+conformance testing script, the prepare script before it, and the unit testing script - word for word in its task:
+what the conformance testing script needs of the build, it reads there, not only in the judge's quote of it.
+
+**Escalation.** A failure judged the tests' goes to the conformance agent first: it owns the tests. When the run then
+fails the same way - the fix changed nothing, or nothing that mattered - the judge is asked again, now whether the
+failure belongs to the code rather than the tests: the run failing on something the code is meant to produce (a build
+output, an entry point, a module the testing script needs), or the tests running and the behaviour itself being
+wrong. Its verdict, either way, has to rest on evidence it gathered: each piece from a file it opened (the harness
+keeps track of what it read, listed and searched), the testing script or the failing run - and not the run alone.
+A verdict without it is sent back; a verdict of code still without it is taken as the tests'. Judged the tests'
+again, the failure stays with the conformance agent, and a fix that changes nothing counts towards stopping as
+before. Judged the code's, it is escalated to the coding agent, handed the script's error, the conformance tests as
+they stand and the judge's reason and evidence (`the script runs dist/cli.js; the build emits dist/src/cli.js`). Its
+fix has to build and pass the unit tests, then the suite runs again. Should the run still fail the same way - or the
+fix change nothing - the run stops there, with the judge's reasoning and evidence in what the person is told. Each of
+these runs is one of the run's 20 attempts, so a failure neither agent can fix stops in three of them.
 
 Every attempt is written into the working notes' pitfalls by the harness as cause and effect - what
 the run failed with, how it was judged, and which files the agent sent to fix it changed; the next
 attempt's line says what came of it - and each judge reads them first, so it does not send a
 failure the way that already failed. A run that does not pass is undone whole, its notes with it.
 
-Then the suite runs again. A run stopped by its time limit goes back to the conformance agent without a judge: the
-tests' environment is its. So does a run that exits 80 - the tests pass and only their static checks do not (see
-[the static checks](#the-static-checks)): the findings are the tests'. A run whose script cannot find its
+Then the suite runs again. A run that exits 80 goes back to the conformance agent without a judge - the tests pass and
+only their static checks do not (see [the static checks](#the-static-checks)): the findings are the tests'.
+
+**Timing.** Every run is shown to the judge, the debugger and whoever fixes it with how long it ran against its time
+limit (`runTiming` in `test-scripts.ts`): `This run ended on its own - exit 1, after 37.2s of the 120.0s a test run
+may take`, or `The time limit stopped this run: it had run 120.0s of the 120.0s ...` - so none takes a run that
+ended on its own for one the limit stopped, or the other way. A run the time limit stopped is judged like any other,
+and the judge is told what keeps a run from finishing: the code hangs (it waits on input, keeps a server in the
+foreground, never exits) - the code's; a test waits for what never comes - the tests'; or nothing hangs, the output
+showing the run getting on up to the limit, and it needs more time than a test run may take - the environment. That
+verdict stops the pulse at once, rolled back and not retried, and the person is told to raise `TURRI_COMMAND_TIMEOUT`
+or make the suite faster - no agent can give a run more time. A run whose script cannot find its
 toolchain stops the pulse instead - see [when the environment lacks something](#when-the-environment-lacks-something).
 Unit tests failing after the suite passes go to the coding agent. It goes round up to 20 times; still failing, the work is undone.
 
@@ -1022,8 +1077,7 @@ both. Each set goes where its folder goes - copied up the chain, committed, roll
 | --- | --- |
 | Where things are | entry points, layout, where each functionality lives |
 | How to build, run and test | the commands that work, what had to be installed |
-| Assumptions | what an agent assumed where the spec is silent - a format, a default, a choice it leaves open |
-| Spec gaps | what the spec should say and does not - a behaviour the person would want to decide, as the question it leaves |
+| Assumptions | what an agent assumed where the spec is silent - a format, a default, a choice it leaves open - and the tests that assert it, when any do; one no test asserts is written down all the same |
 | Pitfalls | what went wrong and what fixed it - and what the debugger found, filed by turri itself |
 | Pulses | written by turri alone, as each pulse ends: the last ten, a line each |
 
@@ -1040,9 +1094,14 @@ it landed, a commit of its own (`pulse 3 rolled back: …`) when it did not - so
 commit, keeps it. `update_notes` refuses the section. What the debugger finds is filed in the pitfalls the moment it
 finds it, not left to the coding agent to write down.
 
-The spec gaps a pulse's agents add are said in its report - "Spec gaps its agents met ... Put each to the user" - so
-the conversation asks you, and writes the ones you decide into the spec; the gaps stay in the notes, for the agents
-after, until then.
+A spec gap - what the spec should say and does not, a behaviour you would want to decide - is not a note: the notes
+are the next agent's, and a gap is yours. An agent reports one with `report_spec_gap`, giving the question it leaves
+and the assumption it made meanwhile; turri writes that assumption into the notes' assumptions, so the code built on
+it is known for what it is. The gaps a pulse's agents report are said in its report - "Spec gaps its agents met ... Put
+each to the user", each with its assumption - so the conversation asks you, and writes the ones you decide into the
+spec; the pulse that builds the answer finds the assumption it replaces in the notes, and the tests it names. However many gaps a pulse's agents report, they
+are put to you - never a reason to stop the pulse; the tool is guarded like any other. A notes
+file from before keeps no spec gaps section: its lines are dropped as it is read.
 
 Stubborn on the specs, flexible on the assumptions: the spec is never an assumption and never
 copied into the notes, and where the two disagree the spec wins. An agent builds on the assumptions
@@ -1065,8 +1124,8 @@ Leaving notes is required, and only through the `update_notes` tool. The file to
 notes file, and a change made to it any other way - from the shell, by a script - is undone. An agent
 that finishes without calling `update_notes` is asked again, up to three times; if it still has not,
 the activity log says so. The turn that asks is for the notes alone: the work is done - its testing script's run
-passed, and the agent is told so first, so its notes speak of work that succeeded - so every tool but `update_notes` is
-refused, and an agent that keeps calling them has its turn stopped. What
+passed, and the agent is told so first, so its notes speak of work that succeeded - so every tool but `update_notes` and
+`report_spec_gap` is refused, and an agent that keeps calling the refused ones has its turn stopped. What
 landed is what the harness checked; nothing changes after it. Only work that lands is asked: a job whose code or tests do not pass - or whose
 testing script cannot run - is rolled back, notes and all, so its agent is not asked to leave any.
 

package/docs/skills-and-gates.md

@@ -52,7 +52,7 @@ last one - one answer, one change, as an interview writes them. `spawn` is unpac
 each change to write the next at once, not to carry on with an interview it does not have.
 
 `questioning:` under `metadata:` names the steps the questioning level caps (`src/questioning.ts`) - `brood`'s
-`[stack, product]`. When there are any and someone to ask, the harness itself asks the first question of the first
+`[stack, product]`, `bud`'s `[product]`. When there are any and someone to ask, the harness itself asks the first question of the first
 step: how many questions those steps may ask - light (3), medium (5), thorough (10) or best judgement - and tells the
 agent the answer beside each step's instructions, with how broad each question is to be: broad at light, a whole area
 at once, narrow at thorough, an edge case at a time. Every level covers the same ground, in less or more depth. In a
@@ -63,7 +63,7 @@ questions each step has asked, are kept in the run's `run.json`, so a resumed ru
 or a run with nobody to ask, is not capped.
 
 `spec-diff-per-answer:` under `metadata:` names the steps where every answer is a spec change - `brood`'s
-`[product]`, at every questioning level. There `ask_user` refuses the next question until the last answer is written
+and `bud`'s `[product]`, at every questioning level. There `ask_user` refuses the next question until the last answer is written
 with `write_spec_diff` (a confirmation, or a question dismissed, owes nothing), and `write_spec_diff` no longer waits
 for an answer before a change: the agent writes as many as the step needs, those it decides itself included. The
 level limits the questions, never the spec changes.

package/docs/using.md

@@ -127,10 +127,13 @@ come waits for a free slot, and says so.
   as GitHub names a hunk's function: each section is named once.
 - **The side panel** (`ctrl+h`, as it was left - but on the pulse that last failed, stopped or did not pass, when one has
   since it was last opened: the live panel that showed it is gone with the last pulse, and its announcement in the chat
-  says `ctrl+h shows this pulse`; **`/regen`** on regen, **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty
+  says `ctrl+h shows this pulse`; **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty
   keyboard protocol sends as a line feed, the same as `shift+enter`, and which a dialog takes for
   `enter`; both stay pi's new-line keys. `ctrl+h` is the byte old terminals sent for backspace; a
-  terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time.
+  terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time -
+  or, `s`, sits beside the chat: the chat on the left, the panel in the right half of the screen, and `s` again
+  over the whole screen. It opens as it was last left, for the conversation; a terminal under 100 columns has
+  no room for both and shows the panel over the whole screen.
   It opens on **regen**: the spec itself, in full, with how much of it the code has been regenerated from drawn
   onto it.
 
@@ -214,7 +217,13 @@ come waits for a free slot, and says so.
   closes when it moves to another section. What is open is kept while the panel is closed. What the agents
   said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
 
-  `ctrl+h` again, or `esc`, closes it and goes back to the chat. While it shows, every key is the panel's,
+  `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, a click decides which side has
+  the keys - the chat or the panel, the one clicked, or the one `⌥⌘←` / `⌥⌘→` points at (on a
+  terminal that passes ⌘ on, over the Kitty keyboard protocol - Ghostty, kitty, WezTerm, iTerm2; not Apple's Terminal);
+  the other is drawn faint - and `esc` gives the chat the keys too, the panel staying and
+  following the pulses; `ctrl+h` gives the panel the keys again, and from the panel closes it. (pi's regular screen,
+  `--tui-mode regular`, reads no mouse: there it is the keys alone.)
+  While the panel has the keys, every key is the panel's,
   whatever else happens: a question the chat model asks in the background (`ask_user`) waits in the chat,
   unanswered - an `enter` in the panel never answers it - and the panel's top line says "the chat is waiting
   for your answer". Back in the chat, the question is there, with the keys.