@turri-dev/cli 0.1.2 → 0.1.3-next.162a2c3

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
@@ -495,20 +504,23 @@ scripts are not linked from the specs; a link to one is ignored.
 They are required: a build with no unit testing script, or with conformance on and no conformance
 testing script, stops before it starts and says which skill adds it.
 
-**The prepare script** is codeplain's, and optional: turri never writes one, and runs one the project has -
+**The prepare script** is optional: turri never writes one, and runs one the project has -
 `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
@@ -685,7 +707,7 @@ change to the code brings that module's code in, so the codebase stops: it has t
 and conformance tests taken out, committed so its history keeps them, and the chain built again from the
 bottom. That is never done unasked. In the chat the model asks the person, saying why, and calls
 `regenerate` with `from_scratch` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
-`--start-over` agrees in advance - with no terminal and no flag, nothing more is built there.
+`--start-over` agrees in advance - with no terminal and no flag, the run stops there, exit 1, saying so.
 
 ## Conformance tests
 
@@ -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.
 

package/docs/using.md

@@ -13,8 +13,10 @@ banner - the jellyfish it is named after, swimming until the conversation fills
 terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn in text in any other, tmux
 included - swimming a stroke a loop, its tentacles following its bell, frames `scripts/jellyfish-frames.mjs`
 writes -
-where commands will run, the rules and skills loaded - rather than pi's startup header
-and resource list; `turri --verbose` shows those too. Talk to it: ask it to start a
+turri's version (and, run from a clone, the commit it is on, and whether the clone has changes), where commands
+will run, the rules and skills loaded - rather than pi's startup header and resource list; `turri --verbose` shows
+those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never
+touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to start a
 project, add a feature, render a module, fix a spec. It decides which skill or tool applies - but
 not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the
 gates and the judges (see [skills and gates](skills-and-gates.md)).
@@ -125,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.
 
@@ -212,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.

package/genome/skills/implement-conformance-testing-script/SKILL.md

@@ -36,7 +36,7 @@ bash run_conformance_tests_<lang>.sh <build_folder> <conformance_tests_folder>
 
 Both arguments are absolute paths: `<build_folder>` is the module's generated code (`plain_modules/<module>/code`), and `<conformance_tests_folder>` is the folder holding the whole suite. The harness runs the script on the person's machine - macOS, Linux or WSL, with its toolchains, in the person's own environment - and its exit code alone decides whether the conformance tests pass.
 
-Every conformance script is self-contained: toolchain check, argument validation, stage the build into `<temp>/<lang>_<basename of $1>`, install dependencies there in isolation, check the tests in `$2` statically, run the suite in `$2` against it, clean up on exit. Nothing is prepared ahead of time by another script - unless the project already has a `prepare_environment*.sh` (codeplain's prepare script, or one `prepare-environment-script:` names): turri runs it on the same build before every run of the conformance script, so keep it, and let the conformance script rely on what it sets up rather than doing it again. Never write a prepare script yourself.
+Every conformance script is self-contained: toolchain check, argument validation, stage the build into `<temp>/<lang>_<basename of $1>`, install dependencies there in isolation, check the tests in `$2` statically, run the suite in `$2` against it, clean up on exit. Nothing is prepared ahead of time by another script - unless the project already has a `prepare_environment*.sh` (a prepare script the project brought, or one `prepare-environment-script:` names): turri runs it on the same build before every run of the conformance script, so keep it, and let the conformance script rely on what it sets up rather than doing it again. Never write a prepare script yourself.
 
 ## How conformance scripts differ from unit-test scripts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.2",
+  "version": "0.1.3-next.162a2c3",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,8 +33,8 @@
     "grammar:sync": "node scripts/sync-plyn-grammar.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@langchain/langgraph": "1.4.15",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.2",