@turri-dev/cli 0.1.3-next.17f0f7f → 0.1.3-next.2babf06

package/dist/cli-options.js

@@ -0,0 +1,82 @@
+import { conformanceOption, overrideConfig, reviewOption, splitModelSpec } from "./config.js";
+/**
+ * The command line of turri's commands: their words, and the options that stand for the config's own keys - kept apart
+ * from the commands that use them, so a light one (doctor) reads them as a regenerate does without loading it.
+ */
+/**
+ * A command's arguments: the positional ones, `--flag`s and `--name value` options (`--name=value` too) -
+ * `--coding-model` is `--model`. An option it does not take is refused, rather than taking the word after it, and so is an
+ * option with no value - the end of the words, or another option where its value should be.
+ */
+export function parseArgs(argv, flags, usage, valued = []) {
+    const positional = [];
+    const options = {};
+    const takes = new Set(["--model", ...valued]);
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+        const option = name === "--coding-model" ? "--model" : name;
+        if (arg === "-h" || arg === "--help") {
+            console.log(usage);
+            process.exit(0);
+        }
+        else if (flags.includes(option) && inline === undefined)
+            options[option.slice(2)] = "yes";
+        else if (takes.has(option)) {
+            // Its value is the next word - never another option, which would be taken as the value and lost.
+            const value = inline ?? argv[i + 1];
+            if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+                console.error(`${usage}\n\n${name} needs a value${value !== undefined ? `, not the option ${value}` : ""} - ${name}=<value> gives one that starts with --.`);
+                process.exit(1);
+            }
+            if (inline === undefined)
+                i += 1;
+            options[option.slice(2)] = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`${usage}\n\nNo such option: ${name}.`);
+            process.exit(1);
+        }
+        else
+            positional.push(arg);
+    }
+    return { positional, options };
+}
+/** An option's value, as parseArgs left it: refused when it was given with none. */
+export function optionValue(options, name) {
+    const value = options[name];
+    if (name in options && (value === undefined || value.trim() === ""))
+        failOption(`--${name} needs a value`);
+    return value;
+}
+/**
+ * The options that stand for the config's own keys - `--harness-model`, `--coding-model` (`--model`), `--judge-model`
+ * and, as asked, `--review` and `--conformance-tests` - read as if config.turri.yaml had them, in their place in the
+ * order the config resolves them in (overrideConfig): a run, or doctor, with them is the same as one with them in the
+ * file. Exits on a value it cannot read.
+ */
+export function configKeyOptions(options, take = {}) {
+    const tests = take.conformance === true ? optionValue(options, "conformance-tests") : undefined;
+    const setting = tests !== undefined ? conformanceOption(tests) : undefined;
+    if (tests !== undefined && setting === undefined)
+        failOption(`--conformance-tests takes all, chosen, module or false, not ${tests}`);
+    const reviewed = take.review === true ? optionValue(options, "review") : undefined;
+    const review = reviewed !== undefined ? reviewOption(reviewed) : undefined;
+    if (reviewed !== undefined && review === undefined)
+        failOption(`--review takes true or false, not ${reviewed}`);
+    const model = (name, key) => {
+        const spec = optionValue(options, name);
+        return spec !== undefined ? { [key]: splitModelSpec(spec) } : {};
+    };
+    overrideConfig({
+        ...model("harness-model", "harnessModel"),
+        ...model("model", "codingModel"),
+        ...model("judge-model", "judgeModel"),
+        ...(setting !== undefined ? { conformanceTests: setting } : {}),
+        ...(review !== undefined ? { review } : {}),
+    });
+}
+function failOption(message) {
+    console.error(message);
+    process.exit(1);
+}

package/dist/conform-cli.js

@@ -1,4 +1,5 @@
-import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri conform <file.plain> [frid ...] [options]
 
 Writes and runs the black-box conformance tests of a module's functional specs - those named, or

package/dist/environment.js

@@ -68,3 +68,22 @@ export function turriOnPath() {
     const found = which.status === 0 ? which.stdout.trim().split("\n")[0] : undefined;
     return found === "" ? undefined : found;
 }
+/** turri's version, and the commit when it runs from a clone. */
+export function turriIdentity() {
+    let version = null;
+    try {
+        version = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? null;
+    }
+    catch {
+        /* no package.json: left out */
+    }
+    if (!existsSync(join(PACKAGE_ROOT, ".git")))
+        return { version, git_commit: null, git_dirty: null };
+    const commit = spawnSync("git", ["-C", PACKAGE_ROOT, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const status = spawnSync("git", ["-C", PACKAGE_ROOT, "status", "--porcelain", "--untracked-files=no"], { encoding: "utf8" });
+    return {
+        version,
+        git_commit: commit.status === 0 ? commit.stdout.trim() : null,
+        git_dirty: status.status === 0 ? status.stdout.trim() !== "" : null,
+    };
+}

package/dist/extension.js

@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { conversationCommand, conversationSettled, conversationWriting } from "./regenerate/conversation-writes.js";
 import { fileURLToPath } from "node:url";
-import { allocateImageId, Box, compositeTuiLine, getCapabilities, getPngDimensions, isKeyRelease, isKeyRepeat, matchesKey, renderImage, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { allocateImageId, Box, getCapabilities, getPngDimensions, isKeyRelease, isKeyRepeat, matchesKey, renderImage, Text, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { CODING_MODEL_ENV } from "./chat-models.js";
@@ -31,6 +31,8 @@ import { whyFailed } from "./regenerate/diagnose-job.js";
 import { createWorkLoop, describeModules, isUpToDate, previewJobs } from "./regenerate/loop.js";
 import { brandBlue, plainPaint } from "./regenerate/plain-palette.js";
 import { createJobPanel, didNotPass, keyPressed, PANEL_KEY, spinner } from "./regenerate/job-panel.js";
+import { clickToFocus, dockedWidth, narrowChat } from "./regenerate/panel-dock.js";
+import { overPictureRow, PICTURE_AT } from "./picture-row.js";
 import { skillAboutLine, skillProgressLine } from "./skill-progress.js";
 import { createSidePanel } from "./regenerate/side-panel.js";
 import { createSpecMapSource, defaultMapFiles } from "./regenerate/spec-map.js";
@@ -52,6 +54,7 @@ import { registerStacks } from "./stacks.js";
 import { catalogueLine, discoverSkills, leftOutNote } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
 import { TURRI_IDENTITY } from "./identity.js";
+import { turriIdentity } from "./environment.js";
 import { conformanceChooser } from "./regenerate/choose-conformance.js";
 import { answerSideQuestion, askWithAsides, BTW_HOW, runningSkill, skillRunStarted, skillSessionText, transcriptOf } from "./btw.js";
 import { createJobRegistry, defaultParallelJobs, describeJob, formatDuration, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
@@ -1467,9 +1470,17 @@ function registerJobTools(pi, jobs, cwd) {
             return { content: [{ type: "text", text }], details: {} };
         },
     });
-    // The side panel: the regeneration - and the pulses behind p - over the whole screen. Its key (PANEL_KEY) opens it; the
-    // key again, or esc, closes it and goes back to the chat. While it shows, every key is its own.
+    // The side panel: the regeneration - and the pulses behind p - over the whole screen, or beside the chat (s, from one to
+    // the other). Its key (PANEL_KEY) opens it; the key again closes it and goes back to the chat, as esc does over the
+    // screen - beside the chat, esc gives the chat its keys back and the panel stays, and the key gives them to the panel.
+    // While the panel has the keys, every key is its own.
     let panel;
+    // Beside the chat or over it: as the person last left it, for the conversation.
+    let panelDocked = false;
+    // The terminal the panel is drawn on, for its width: set as it opens.
+    let panelTerminal;
+    /** The columns the panel takes beside the chat - 0 over the whole screen, or when the terminal is too narrow to share. */
+    const panelBeside = () => (panelDocked && panelTerminal !== undefined ? dockedWidth(panelTerminal.columns) : 0);
     // What is open in the pulse list and the map, and where their cursors are: the conversation's, as left each time it opens.
     const jobsTree = createJobsTreeState();
     const mapState = createSpecMapState();
@@ -1497,13 +1508,51 @@ function registerJobTools(pi, jobs, cwd) {
         needsLooking.delete(jobs);
         if (panel !== undefined) {
             panel.handle?.setHidden(false);
+            panel.keys = true;
             panel.handle?.focus();
             return;
         }
         // Not awaited: the panel lives on while the jobs it shows run.
         void ctx.ui.custom((tui, theme, _keybindings, done) => {
             const close = () => done(undefined);
+            panelTerminal = tui.terminal;
             let component;
+            // Beside the chat: the chat drawn narrower, on the left, and a click on either side giving it the keys - undone
+            // when the panel goes over the screen, or closes.
+            let undock;
+            const layOut = () => {
+                if (panelDocked && undock === undefined) {
+                    const widen = narrowChat(tui, panelBeside);
+                    const unwatch = clickToFocus(tui, () => tui.terminal.columns - panelBeside(), (side) => {
+                        if (panelBeside() === 0)
+                            return;
+                        if (side === "chat")
+                            toChat();
+                        else
+                            toPanel();
+                    });
+                    undock = () => {
+                        unwatch();
+                        widen();
+                    };
+                }
+                else if (!panelDocked && undock !== undefined) {
+                    undock();
+                    undock = undefined;
+                }
+            };
+            // Beside the chat, back to it: the chat has the keys, the panel stays.
+            const toChat = () => {
+                entry.keys = false;
+                entry.handle?.unfocus();
+                tui.requestRender();
+            };
+            const toPanel = () => {
+                entry.keys = true;
+                entry.handle?.focus();
+                tui.requestRender();
+            };
+            const back = () => (panelBeside() > 0 ? toChat() : close());
             // Opened, it reads the files again at once: they may have changed while it was closed.
             specMap.refresh();
             const view = createSidePanel({
@@ -1513,6 +1562,14 @@ function registerJobTools(pi, jobs, cwd) {
                 mapState,
                 rows: () => tui.terminal.rows,
                 key: PANEL_KEY,
+                dock: {
+                    docked: () => panelBeside() > 0,
+                    toggle: () => {
+                        panelDocked = panelBeside() === 0;
+                        layOut();
+                        tui.requestRender();
+                    },
+                },
                 style: {
                     heading: (text) => theme.bold(theme.fg("accent", text)),
                     muted: (text) => theme.fg("muted", text),
@@ -1527,22 +1584,25 @@ function registerJobTools(pi, jobs, cwd) {
                     // What conformance tests show does what its spec says: brand blue.
                     conforms: brandBlue(theme),
                 },
-                back: close,
+                back,
                 close,
                 // A module that needs the person: the chat takes it up with them, in their words - what went wrong, and what now.
                 discuss: (page) => {
-                    close();
+                    back();
                     const why = page.codebase?.stuck?.why;
                     pi.sendUserMessage(`regen says ${page.module} needs me: ${page.status}. What went wrong, and what do we do about it?${why !== undefined ? `\n\n(turri's reason: ${why})` : ""}`, { deliverAs: "followUp" });
                 },
                 // Something took the keys' focus while the panel showed - a question in the chat - and waits there.
                 waiting: () => {
+                    if (!entry.keys)
+                        return false;
                     const focused = tui.getFocusedComponent?.() ?? null;
                     return focused !== null && focused !== component;
                 },
             });
-            const entry = { view, close };
+            const entry = { view, close, keys: true };
             panel = entry;
+            layOut();
             // Every key goes to the panel while it shows, whatever has the focus: a question the chat model asks in the
             // background takes the focus, but no key reaches it - an enter never answers it unseen. It waits in the chat
             // until the panel closes, and has the keys then. Mouse events are the screen's, before this sees them.
@@ -1564,6 +1624,11 @@ function registerJobTools(pi, jobs, cwd) {
                 }
                 if (!state)
                     return undefined;
+                // Beside the chat, with the chat's keys: they are the chat's - PANEL_KEY among them, for the shortcut that gives
+                // them to the panel. A click on the panel gives it the focus, and the keys with it.
+                if (!entry.keys && entry.handle?.isFocused() !== true)
+                    return undefined;
+                entry.keys = true;
                 // A terminal on the Kitty keyboard protocol reports a key's release, and listeners are given it: the release of
                 // the ctrl+h that opened the panel would close it again at once, and every arrow would move twice. Only
                 // presses count - and ctrl+h held down, repeating, does not open and close it over and over.
@@ -1590,7 +1655,8 @@ function registerJobTools(pi, jobs, cwd) {
             }, WATCH_REDRAW_MS);
             timer.unref?.();
             component = {
-                render: (width) => view.render(width),
+                // Beside the chat, a rule down its left edge between them.
+                render: (width) => (panelBeside() > 0 ? view.render(width - 2).map((line) => `${theme.fg("borderMuted", "│")} ${line}`) : view.render(width)),
                 // Reached only if the listener above is gone: the same, so the panel never passes a key on.
                 handleInput: (data) => {
                     if (isKeyRepeat(data) && matchesKey(data, PANEL_KEY))
@@ -1606,6 +1672,7 @@ function registerJobTools(pi, jobs, cwd) {
                 dispose: () => {
                     unlisten();
                     clearInterval(timer);
+                    undock?.();
                     if (panel === entry)
                         panel = undefined;
                 },
@@ -1613,8 +1680,15 @@ function registerJobTools(pi, jobs, cwd) {
             return component;
         }, {
             overlay: true,
-            // The whole screen: the panel or the chat, one at a time.
-            overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 },
+            // The whole screen, or the columns on the right beside the chat - read at each frame, so it follows the terminal.
+            overlayOptions: {
+                get width() {
+                    return panelBeside() > 0 ? panelBeside() : "100%";
+                },
+                maxHeight: "100%",
+                anchor: "top-right",
+                margin: 0,
+            },
             onHandle: (handle) => {
                 if (panel !== undefined)
                     panel.handle = handle;
@@ -1640,7 +1714,7 @@ function registerJobTools(pi, jobs, cwd) {
     panelOpeners.set(jobs, (ctx) => openPanel(ctx));
     questionPeek = {
         open: (ctx) => openPanel(ctx),
-        shown: () => panel !== undefined,
+        shown: () => panel !== undefined && panel.keys,
     };
     pi.registerShortcut(PANEL_KEY, {
         description: "Peek at regen and the pulses - a question waiting in the chat waits for you - or go back to it",
@@ -2158,7 +2232,8 @@ function registerBranding(pi, ruleCount, skills) {
         if (data === undefined)
             return undefined;
         const lines = [
-            `${theme.fg("accent", "turri")}  ${theme.fg("muted", `v${data.version}`)}`,
+            `${theme.fg("accent", "turri")}  ${theme.fg("muted", `v${data.version}`)}` +
+                (data.commit !== undefined ? theme.fg("dim", `  from a clone, ${data.commit}${data.changed ? " with changes" : ""}`) : ""),
             theme.fg("text", "regenerative software - the code is regenerated from the spec"),
             theme.fg("muted", `${data.rules} rules · ${data.skills} skill${data.skills === 1 ? "" : "s"}` +
                 (data.projectSkills !== undefined && data.projectSkills > 0 ? ` (${data.projectSkills} the project's)` : "") +
@@ -2180,8 +2255,11 @@ function registerBranding(pi, ruleCount, skills) {
         if (ctx.hasUI)
             animateJellyfish(ctx);
         try {
+            const identity = turriIdentity();
             pi.appendEntry(BANNER_ENTRY, {
-                version: packageVersion(),
+                version: identity.version ?? "0.0.0",
+                commit: identity.git_commit?.slice(0, 7),
+                changed: identity.git_dirty === true,
                 rules: ruleCount,
                 skills: skills.skills.length,
                 projectSkills: skills.skills.filter((skill) => skill.origin !== "turri").length,
@@ -2234,8 +2312,6 @@ function animateJellyfish(ctx) {
     }, { placement: "belowEditor" });
 }
 const JELLYFISH_CLOCK_KEY = "turri-jellyfish";
-/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column. */
-const PICTURE_AT = "\x1b[2G";
 /** The columns the banner's picture takes from the left edge, while it shows one; 0 when it does not. */
 let pictureRight = 0;
 /**
@@ -2250,14 +2326,7 @@ function drawOverlaysBesidePicture(tui) {
         return;
     target.turriPicture = true;
     const original = target.compositeLineAt.bind(tui);
-    target.compositeLineAt = (base, overlay, col, width, total) => {
-        const at = base.lastIndexOf(PICTURE_AT);
-        const picture = at === -1 ? "" : base.slice(at + PICTURE_AT.length);
-        if (!/^(\x1b\[\d+A)?(\x1b_G|\x1b\]1337;File=)/.test(picture))
-            return original(base, overlay, col, width, total);
-        const drawn = compositeTuiLine(base.slice(0, at), overlay, col, width, total);
-        return col >= pictureRight ? `${drawn}${PICTURE_AT}${picture}` : drawn;
-    };
+    target.compositeLineAt = (base, overlay, col, width, total) => overPictureRow(base, overlay, col, width, total, pictureRight) ?? original(base, overlay, col, width, total);
 }
 /** Columns between the jellyfish and the lines beside it. */
 const JELLYFISH_GAP = 3;
@@ -2289,7 +2358,8 @@ class Banner {
         const art = this.art;
         const placed = art?.kind === "image" ? this.placeImage(art, Math.max(JELLYFISH_ROWS, this.lines.length), width - 2 - JELLYFISH_GAP - BANNER_TEXT_MIN) : art?.kind === "text" && art.columns <= width - 2 - JELLYFISH_GAP - BANNER_TEXT_MIN ? art : undefined;
         const left = placed !== undefined ? 1 + placed.columns + JELLYFISH_GAP : 1;
-        const text = this.lines.map((line) => truncateToWidth(line, Math.max(1, width - 1 - left)));
+        // Wrapped in the columns beside the picture, never cut short - the chat beside the docked panel is narrow.
+        const text = this.lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width - 1 - left)));
         const height = Math.max(text.length, placed?.rows ?? 0);
         const above = Math.floor((height - text.length) / 2);
         const drawn = placed?.kind === "text" ? placed.frames[jellyfishFrame % placed.frames.length] : undefined;
@@ -2361,12 +2431,3 @@ function jellyfishArt(appearance, ink) {
         return undefined;
     }
 }
-function packageVersion() {
-    try {
-        const raw = readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8");
-        return JSON.parse(raw).version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}

package/dist/loop-cli.js

@@ -1,7 +1,7 @@
 import { sweepOrphanedGroups } from "./regenerate/shell.js";
 import { createInterface } from "node:readline/promises";
 import { resolve, sep } from "node:path";
-import { configForSpec, conformanceOption, reviewOption, inheritModel, modelOnly, modelSpec, overrideConfig, projectModels, readProjectConfig, roleModel, ROLE_THINKING, splitModelSpec, } from "./config.js";
+import { configForSpec, inheritModel, modelOnly, modelSpec, projectModels, readProjectConfig, roleModel, ROLE_THINKING, splitModelSpec, } from "./config.js";
 import { PACKAGE_ROOT } from "./environment.js";
 import { c } from "./module-report.js";
 import { tryItCommand } from "./regenerate/delivery.js";
@@ -13,6 +13,7 @@ import { MODULES_DIR, projectDirOf } from "./regenerate/paths.js";
 import { exportModule } from "./regenerate/release.js";
 import { listFiles } from "./regenerate/testing.js";
 import { startRunReport } from "./run-report.js";
+import { configKeyOptions, optionValue } from "./cli-options.js";
 /**
  * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
@@ -235,83 +236,15 @@ function reportModels(project, model) {
 }
 /**
  * The options every command that regenerates takes for a headless run: `--report` and `--build-dir`, and the config's
- * own keys - `--harness-model`, `--coding-model` (`--model`), `--judge-model`, `--review` and, where `conformance` is
- * true, `--conformance-tests` - read as if config.turri.yaml had them, the config's order of them kept (overrideConfig).
- * Exits on a value it cannot read.
+ * own keys (configKeyOptions) - `--harness-model`, `--coding-model` (`--model`), `--judge-model`, `--review` and, where
+ * `conformance` is true, `--conformance-tests` - read as if config.turri.yaml had them. Exits on a value it cannot read.
  */
 export function headlessOptions(options, conformance) {
-    const given = (name) => {
-        const value = options[name];
-        if (name in options && (value === undefined || value.trim() === ""))
-            failOption(`--${name} needs a value`);
-        return value;
-    };
-    const tests = conformance ? given("conformance-tests") : undefined;
-    const setting = tests !== undefined ? conformanceOption(tests) : undefined;
-    if (tests !== undefined && setting === undefined)
-        failOption(`--conformance-tests takes all, chosen, module or false, not ${tests}`);
-    const reviewed = given("review");
-    const review = reviewed !== undefined ? reviewOption(reviewed) : undefined;
-    if (reviewed !== undefined && review === undefined)
-        failOption(`--review takes true or false, not ${reviewed}`);
-    const model = (name) => {
-        const spec = given(name);
-        return spec !== undefined ? { [name === "model" ? "codingModel" : name === "harness-model" ? "harnessModel" : "judgeModel"]: splitModelSpec(spec) } : {};
-    };
-    overrideConfig({
-        ...model("harness-model"),
-        ...model("model"),
-        ...model("judge-model"),
-        ...(setting !== undefined ? { conformanceTests: setting } : {}),
-        ...(review !== undefined ? { review } : {}),
-    });
-    const report = given("report");
-    const buildDir = given("build-dir");
+    configKeyOptions(options, { conformance, review: true });
+    const report = optionValue(options, "report");
+    const buildDir = optionValue(options, "build-dir");
     return { ...(report !== undefined ? { report } : {}), ...(buildDir !== undefined ? { buildDir } : {}) };
 }
-function failOption(message) {
-    console.error(message);
-    process.exit(1);
-}
-/**
- * A command's arguments: the positional ones, `--flag`s and `--name value` options (`--name=value` too) -
- * `--coding-model` is `--model`. An option it does not take is refused, rather than taking the word after it, and so is an
- * option with no value - the end of the words, or another option where its value should be.
- */
-export function parseArgs(argv, flags, usage, valued = []) {
-    const positional = [];
-    const options = {};
-    const takes = new Set(["--model", ...valued]);
-    for (let i = 0; i < argv.length; i += 1) {
-        const arg = argv[i];
-        const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
-        const option = name === "--coding-model" ? "--model" : name;
-        if (arg === "-h" || arg === "--help") {
-            console.log(usage);
-            process.exit(0);
-        }
-        else if (flags.includes(option) && inline === undefined)
-            options[option.slice(2)] = "yes";
-        else if (takes.has(option)) {
-            // Its value is the next word - never another option, which would be taken as the value and lost.
-            const value = inline ?? argv[i + 1];
-            if (value === undefined || (inline === undefined && value.startsWith("--"))) {
-                console.error(`${usage}\n\n${name} needs a value${value !== undefined ? `, not the option ${value}` : ""} - ${name}=<value> gives one that starts with --.`);
-                process.exit(1);
-            }
-            if (inline === undefined)
-                i += 1;
-            options[option.slice(2)] = value;
-        }
-        else if (arg.startsWith("-")) {
-            console.error(`${usage}\n\nNo such option: ${name}.`);
-            process.exit(1);
-        }
-        else
-            positional.push(arg);
-    }
-    return { positional, options };
-}
 /** Yes or no at the terminal - or undefined when there is none, and so no one to ask. */
 async function askAtTerminal(title, body) {
     if (process.stdin.isTTY !== true)

package/dist/pi-launch.js

@@ -9,19 +9,28 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { main, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { ProcessTerminal } from "@earendil-works/pi-tui";
 import "./terminal-images.js";
 /**
  * pi, started the way its own CLI starts it, for `turri`.
  *
- * The one difference: pi's startup header - its version, key hints and the list of every
- * loaded skill, extension and theme - is left out, because turri shows its own. pi only
- * takes that from the `quietStartup` setting, and a setting would quiet every `pi` on the
- * machine, so it is answered for this run instead. `--verbose` still shows it.
+ * What differs is pi's own branding, because turri shows its own: its startup header - its
+ * version, key hints and the list of every loaded skill, extension and theme - its update notice
+ * and its tab title. pi only takes the header from the `quietStartup` setting, and a setting would
+ * quiet every `pi` on the machine, so it is answered for this run instead. `--verbose` still shows it.
  */
 const args = process.argv.slice(2);
 if (!args.includes("--verbose")) {
     SettingsManager.prototype.getQuietStartup = () => true;
 }
+// pi's "Update Available" notice is left out: the pi turri runs is its pinned dependency, which `pi update`
+// does not touch - it moves when turri does.
+process.env.PI_SKIP_VERSION_CHECK = "1";
+// The terminal's tab title: pi writes `π - <folder>` (its APP_TITLE, a constant), turri a jellyfish and its name.
+const setTitle = ProcessTerminal.prototype.setTitle;
+ProcessTerminal.prototype.setTitle = function (title) {
+    setTitle.call(this, title.replace(/^π(?= |$)/, "🪼 turri"));
+};
 // pi's own keys stand: a new line is shift+enter or ctrl+j. turri's side panel is on ctrl+h (job-panel.ts PANEL_KEY).
 // What pi's CLI does before main: the process title, pi's environment markers, the HTTP
 // dispatcher. Not exported, so loaded from the file - beside pi's entry point, wherever npm put it.

package/dist/picture-row.js

@@ -0,0 +1,21 @@
+import { compositeTuiLine } from "@earendil-works/pi-tui";
+/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column. */
+export const PICTURE_AT = "\x1b[2G";
+/** The picture's escape sequence, as the banner writes it after PICTURE_AT: Kitty's, in chunks, or iTerm2's - climbing first on iTerm2. */
+const PICTURE = /^(?:\x1b\[\d+A)?(?:(?:\x1b_G[^\x1b]*\x1b\\)+|\x1b\]1337;File=[^\x07]*\x07)/;
+/**
+ * The banner's picture row with an overlay drawn over its text, the picture after it - left out while the overlay
+ * reaches over the picture, `pictureRight` columns from the left edge. Undefined for a row that holds no picture.
+ *
+ * What follows the picture - the padding a row narrower than the screen is given, the chat's beside the docked panel -
+ * is the row's text: written after the picture, from the picture's column, it would blank the row.
+ */
+export function overPictureRow(base, overlay, col, width, total, pictureRight) {
+    const at = base.lastIndexOf(PICTURE_AT);
+    const picture = at === -1 ? null : PICTURE.exec(base.slice(at + PICTURE_AT.length));
+    if (picture === null)
+        return undefined;
+    const after = base.slice(at + PICTURE_AT.length + picture[0].length);
+    const drawn = compositeTuiLine(`${base.slice(0, at)}${after}`, overlay, col, width, total);
+    return col >= pictureRight ? `${drawn}${PICTURE_AT}${picture[0]}` : drawn;
+}

package/dist/regenerate/panel-dock.js

@@ -0,0 +1,57 @@
+import { HStack } from "@earendil-works/pi-tui";
+/**
+ * The side panel beside the chat rather than over it: the chat drawn on the left in what the panel leaves it, the panel
+ * laid over the columns on the right.
+ *
+ * pi draws its screen one of two ways, and the chat is narrowed in each as it is drawn: full screen (pi's default), a
+ * layout - its root put in a row beside a filler as wide as the panel; the regular screen, the lines its render gives -
+ * asked for in fewer columns.
+ */
+/** Narrower than this, the chat and the panel have no room side by side: the panel takes the whole screen. */
+const SHARED_FROM = 100;
+/** The columns the panel takes beside the chat - 0 when the terminal is too narrow to share. */
+export function dockedWidth(columns) {
+    return columns < SHARED_FROM ? 0 : Math.max(48, Math.floor(columns * 0.45));
+}
+/**
+ * The chat narrowed by `panelWidth()` columns, read at each frame - 0 gives it the whole width. Returns what gives it the
+ * whole width back for good.
+ */
+export function narrowChat(tui, panelWidth) {
+    const screen = tui;
+    if (typeof screen.setLayoutRoot === "function" && screen.layoutRoot !== undefined) {
+        const root = screen.layoutRoot;
+        // A line as wide as the panel: the row gives the filler what it measures, the chat the rest.
+        const filler = { render: () => [" ".repeat(panelWidth())], invalidate() { } };
+        screen.setLayoutRoot(new HStack([{ component: root, basis: 0, grow: 1 }, { component: filler }]));
+        return () => screen.setLayoutRoot(root);
+    }
+    // Read from the prototype: the screen's own render, not one laid over it.
+    const render = Object.getPrototypeOf(tui).render;
+    screen.render = function (width) {
+        return render.call(this, Math.max(1, width - panelWidth()));
+    };
+    return () => {
+        screen.render = render;
+    };
+}
+/**
+ * A press of a mouse button, as pi's full screen takes it - `side` told whether it was in the chat, left of `chatWidth()`
+ * columns, or in the panel - before the press goes on as it would have. Motion and the wheel are not presses. pi's
+ * regular screen reads no mouse: nothing is done there. Returns what takes the watch off.
+ */
+export function clickToFocus(tui, chatWidth, side) {
+    const screen = tui;
+    const handle = screen.handleMouseEvent;
+    if (typeof handle !== "function")
+        return () => { };
+    screen.handleMouseEvent = function (raw) {
+        // 32: motion; 64: the wheel.
+        if (raw.release !== true && (raw.button & (32 | 64)) === 0)
+            side(raw.x < chatWidth() ? "chat" : "panel");
+        return handle.call(this, raw);
+    };
+    return () => {
+        screen.handleMouseEvent = handle;
+    };
+}

package/dist/regenerate/side-panel.js

@@ -12,6 +12,12 @@ export function createSidePanel(options) {
     let drawnTree = { rows: [], rowStarts: [], lineCount: 0 };
     let drawnMap = { rows: [], rowStarts: [], lineCount: 0 };
     let pages = [];
+    /** The keys back to the chat - and `s`, from over the screen to beside the chat and back. */
+    const backKeys = () => {
+        if (options.dock === undefined)
+            return [`esc or ${options.key} back to the chat`];
+        return options.dock.docked() ? ["s full screen", "esc to the chat", `${options.key} close`] : ["s beside the chat", `esc or ${options.key} back to the chat`];
+    };
     const waitingNote = () => 
     // A question asked while it showed waits in the chat, unanswered: the person is told it is there.
     options.waiting?.() === true ? `   ${style.warning?.("your question is waiting") ?? style.accent("your question is waiting")} - ${options.key} or esc to answer it, as you left it` : "";
@@ -59,7 +65,7 @@ export function createSidePanel(options) {
     /** The rule under the top. */
     const rule = (width) => style.muted("─".repeat(Math.max(1, width)));
     const renderPulses = (width, rows) => {
-        const keys = ["↑↓ move", "enter open/close", "←→", "o/c all", "pgup pgdn scroll", ...(options.map !== undefined ? ["p regen"] : []), `esc or ${options.key} back to the chat`];
+        const keys = ["↑↓ move", "enter open/close", "←→", "o/c all", "pgup pgdn scroll", ...(options.map !== undefined ? ["p regen"] : []), ...backKeys()];
         const top = topBlock([`${style.heading("pulses")}${waitingNote()}`], keys, width);
         // Under the top: the rule, and a line of space - as the map has.
         const bodyHeight = Math.max(3, rows - top.length - 2);
@@ -77,7 +83,7 @@ export function createSidePanel(options) {
         pages = options.map();
         const now = Date.now();
         if (pages.length === 0) {
-            const top = topBlock([`${style.heading("regen")}${waitingNote()}`], ["p pulses", `esc or ${options.key} back to the chat`], width);
+            const top = topBlock([`${style.heading("regen")}${waitingNote()}`], ["p pulses", ...backKeys()], width);
             lastBodyHeight = Math.max(3, rows - top.length - 1);
             drawnMap = { rows: [], rowStarts: [], lineCount: 0 };
             const body = [style.muted("  No .plain file to map: name one to regenerate, or set module: in config.turri.yaml."), ...new Array(Math.max(0, lastBodyHeight - 1)).fill("")];
@@ -87,7 +93,7 @@ export function createSidePanel(options) {
         const tabbed = pages.length > 1;
         const page = shownPage(pages, map);
         const discuss = page.stuck && options.discuss !== undefined ? [`${DISCUSS_KEY} talk it through in the chat`] : [];
-        const keys = [...discuss, "↑↓ move", "enter open/close", ...(tabbed ? ["←→ module"] : []), "o/c all", "pgup pgdn", "p pulses", `esc or ${options.key} back to the chat`];
+        const keys = [...discuss, "↑↓ move", "enter open/close", ...(tabbed ? ["←→ module"] : []), "o/c all", "pgup pgdn", "p pulses", ...backKeys()];
         // The legend's box in the upper right corner, over what is under it; too narrow a panel has none.
         const box = width >= 60 ? legendBox(legendLines(page, style)) : [];
         const room = box.length > 0 ? width - visibleWidth(box[0]) - 1 : width;
@@ -210,7 +216,7 @@ export function createSidePanel(options) {
             }
             catch (error) {
                 // A frame that throws is never drawn - nor is anything after it: the screen would freeze. What failed is shown instead.
-                const top = topBlock([`${style.heading(map.view === "map" ? "regen" : "pulses")}${waitingNote()}`], [...(options.map !== undefined ? ["p the other view"] : []), `esc or ${options.key} back to the chat`], width);
+                const top = topBlock([`${style.heading(map.view === "map" ? "regen" : "pulses")}${waitingNote()}`], [...(options.map !== undefined ? ["p the other view"] : []), ...backKeys()], width);
                 const lines = (error instanceof Error ? (error.stack ?? error.message) : String(error)).split("\n").slice(0, Math.max(1, rows - top.length - 1));
                 return [
                     ...top,
@@ -225,6 +231,10 @@ export function createSidePanel(options) {
                 options.back();
                 return;
             }
+            if (options.dock !== undefined && data === "s") {
+                options.dock.toggle();
+                return;
+            }
             if (options.map !== undefined && data === "p") {
                 if (map.view === "map")
                     toPulses();

package/dist/regenerate/test-scripts.js

@@ -609,19 +609,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-cli.js

@@ -1,5 +1,6 @@
 import { CONFIG_FILE, readProjectConfig } from "./config.js";
-import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri regenerate [file.plain] [frid ...] [options]
 
 Regenerates the module's code from its spec as it is now, and everything it requires, bottom first, as

package/dist/run-report.js

@@ -1,7 +1,6 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { PACKAGE_ROOT } from "./environment.js";
+import { turriIdentity } from "./environment.js";
 import { onModelEvent } from "./regenerate/activity.js";
 /**
  * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
@@ -57,25 +56,6 @@ function sumTotals(a, b) {
 function rounded(totals) {
     return { ...totals, cost_usd: Math.round(totals.cost_usd * 1e6) / 1e6, model_seconds: Math.round(totals.model_seconds * 10) / 10 };
 }
-/** turri's version, and the commit when it runs from a clone. */
-function turriIdentity() {
-    let version = null;
-    try {
-        version = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? null;
-    }
-    catch {
-        /* no package.json: left out */
-    }
-    if (!existsSync(join(PACKAGE_ROOT, ".git")))
-        return { version, git_commit: null, git_dirty: null };
-    const commit = spawnSync("git", ["-C", PACKAGE_ROOT, "rev-parse", "HEAD"], { encoding: "utf8" });
-    const status = spawnSync("git", ["-C", PACKAGE_ROOT, "status", "--porcelain", "--untracked-files=no"], { encoding: "utf8" });
-    return {
-        version,
-        git_commit: commit.status === 0 ? commit.stdout.trim() : null,
-        git_dirty: status.status === 0 ? status.stdout.trim() !== "" : null,
-    };
-}
 const pulseKind = (job) => (job.kind === "regenerate" ? "code" : job.kind);
 const firstLines = (text) => {
     const trimmed = text?.trim();

package/dist/setup.js

@@ -6,6 +6,7 @@ import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { globalExtensionFile, MIN_NODE, nodeVersionOk, PACKAGE_ROOT, turriOnPath } from "./environment.js";
 import { sandboxAvailable } from "./regenerate/os-sandbox.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
+import { configKeyOptions, parseArgs } from "./cli-options.js";
 import { hasProjectConfig, readProjectConfig, stackOf } from "./config.js";
 import { checkModels, modelsInUse, piModelAccess } from "./model-check.js";
 import { brand } from "./brand.js";
@@ -151,7 +152,7 @@ function checkGlobal() {
 export async function checkProjectModels(project, access) {
     const used = modelsInUse(readProjectConfig(project, stackOf(project)));
     if (used.length === 0) {
-        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models" }];
+        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models - or name them here: --harness-model, --coding-model" }];
     }
     let verdicts;
     try {
@@ -167,16 +168,17 @@ export async function checkProjectModels(project, access) {
             : { level: "missing", name, detail: verdict.spec, more: [verdict.problem], fix: verdict.fix };
     });
 }
+/** `modelsGiven`: models named on the command line - checked wherever doctor runs, a project or not. */
 async function allChecks(options = {}) {
     const checks = [checkNode(), checkShell(), checkGit(), checkSandbox(), await checkProvider(), checkPath(), ...checkGlobal()];
     // In a project: what it needs of this machine, and whether its models answer.
     const project = process.cwd();
-    if (hasProjectConfig(project) || existsSync(join(project, "plain_modules"))) {
+    const inProject = hasProjectConfig(project) || existsSync(join(project, "plain_modules"));
+    if (inProject)
         checks.push(...checkProject(project));
-        if (options.models !== false && hasProjectConfig(project)) {
-            console.log(brand.muted("Asking each model the config names for a word..."));
-            checks.push(...(await checkProjectModels(project)));
-        }
+    if (options.models !== false && (hasProjectConfig(project) || options.modelsGiven === true)) {
+        console.log(brand.muted("Asking each model the config names for a word..."));
+        checks.push(...(await checkProjectModels(project)));
     }
     return checks;
 }
@@ -235,21 +237,27 @@ function removeGlobalExtension() {
     rmSync(file, { force: true });
     console.log(`  removed ${file}`);
 }
+const USAGE = [
+    "usage: turri doctor [--harness-model <m>] [--coding-model <m>] [--judge-model <m>] [--no-models] [--yes]",
+    "",
+    "Check everything turri needs - in a project, what its modules need of this machine too, and that",
+    "each model its config names answers with this machine's credentials (one short request a model;",
+    "--no-models skips it). The model options are read as the config's keys, as turri regenerate reads them:",
+    "a headless run's models can be checked before it starts, with no config.turri.yaml.",
+    "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to",
+    "plain pi. --yes answers yes.",
+].join("\n");
 export async function main(args) {
-    if (args.includes("--help") || args.includes("-h")) {
-        console.log("usage: turri doctor [--no-models] [--yes]\n\nCheck everything turri needs - in a project, what its modules need of this machine too, and that\n" +
-            "each model its config names answers with this machine's credentials (one short request a model;\n--no-models skips it).\n" +
-            "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to\n" +
-            "plain pi. --yes answers yes.");
-        return 0;
-    }
+    const { options } = parseArgs(args, ["--no-models", "--yes", "-y"], USAGE, ["--harness-model", "--judge-model"]);
+    configKeyOptions(options);
     console.log(brand.bold(brand.accent("Checking what turri needs.")));
     if (!nodeVersionOk())
         return report([checkNode()]);
-    const code = report(await allChecks({ models: !args.includes("--no-models") }));
+    const modelsGiven = ["harness-model", "model", "judge-model"].some((name) => options[name] !== undefined);
+    const code = report(await allChecks({ models: options["no-models"] === undefined, modelsGiven }));
     // turri and pi are kept apart: a plain pi does not start turri. An older turri's file that made it do so goes, asked.
     const global = globalExtensionFile();
-    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, args.includes("--yes") || args.includes("-y")))) {
+    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, options.yes !== undefined || args.includes("-y")))) {
         removeGlobalExtension();
     }
     return code;

package/dist/spec-diff-cli.js

@@ -2,7 +2,8 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
-import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
 
 Applies a change to the specs, given as a git diff of the .plain files, and builds it: the headless

package/docs/development.md

@@ -18,6 +18,12 @@ which tests reach which mutant (`vitest.stryker.config.ts`, the suite without th
 mutant against those tests. `scripts/mutation.mjs` sets two things in Stryker's vitest runner the suite needs - forked
 workers, and a test-name filter that matches vitest 5's names - again after every `npm install`.
 
+The `mutation` workflow (`.github/workflows/mutation.yml`) runs it on GitHub, started by hand: Actions, mutation, Run
+workflow. It takes the parts to run, space-separated (empty for every part), each a job of its own side by side, on
+four cores (`TURRI_MUTATION_CONCURRENCY`; six here). Each part's `mutation.html` and `mutation.json` are uploaded as an
+artifact, `mutation-<part>`, and summed up on the run's page. Stryker's incremental file is cached from run to run, so
+a run tests again only the mutants whose code or tests changed; tick `fresh` to test every one again.
+
 Working on turri itself, `npm link` points the global `turri` at this clone, so edits
 take effect immediately. `npm run chat` starts pi with the extension loaded from `src/`.
 
@@ -69,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

@@ -14,7 +14,8 @@ Everything marked `✗` stops the run, so fix those first. Two more things matte
   a module's implementation reqs name that this machine lacks.
 - **The models.** In a project, `turri doctor` sends each model `config.turri.yaml` names one short request, as turri's
   agents will - so a key the provider refuses, a model pi does not know or an account without access to it shows now,
-  not an hour into the run.
+  not an hour into the run. Models the run is given on the command line are given to doctor the same way -
+  `--harness-model`, `--coding-model`, `--judge-model`, read as the config's keys - and are checked with the config's.
 - **Credentials that do not expire mid-run.** An API key in the environment
   (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...) or pi's saved login - whatever
   `doctor` shows as the model provider.
@@ -260,9 +261,16 @@ turri regenerate app.plain --harness-model amazon-bedrock/eu.anthropic.claude-op
 - **What it needs:** Node 22.19 or newer, `bash`, `git` (each module's history, and the spec diffs
   the work is planned from), `/bin/sh` with `kill` and `sleep`, a writable `HOME` (pi keeps
   `~/.pi/agent/auth.json` there, even with no login - or set `PI_CODING_AGENT_DIR`) and `TMPDIR`, and
-  the toolchains the project's testing scripts and implementation reqs name. `turri doctor --no-models`
-  in the project checks them; `--no-models` because a `config.yaml` written for another tool names no models, and
-  doctor would count that against it.
+  the toolchains the project's testing scripts and implementation reqs name. `turri doctor` in the project, given
+  the run's models, checks them all and that each model answers - at the start of the task's log, not when a pulse
+  fails:
+
+  ```bash
+  turri doctor --harness-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+    --coding-model amazon-bedrock/eu.anthropic.claude-sonnet-5-5 --judge-model amazon-bedrock/eu.anthropic.claude-opus-5-5
+  ```
+
+  It exits 1 on anything marked `✗`.
 - **Without bubblewrap:** a container that cannot make user namespaces - no
   `--security-opt seccomp=unconfined` - has no OS sandbox. turri runs anyway, the command check and the
   audit holding alone under the agents' commands; `turri doctor` shows it as `!`, not `✗`. Installing

package/docs/installation.md

@@ -68,7 +68,7 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 | --- | --- |
 | each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
-| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--no-models` skips it |
+| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 
 Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a
 terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks;

package/docs/regenerating.md

@@ -218,7 +218,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
@@ -507,8 +507,10 @@ your own environment with this machine's toolchains, turri's model providers' AP
 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 +564,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.
 

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)).
@@ -128,7 +130,10 @@ come waits for a free slot, and says so.
   says `ctrl+h shows this pulse`; **`/regen`** on regen, **`/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 45% 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,11 @@ 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 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3-next.17f0f7f",
+  "version": "0.1.3-next.2babf06",
   "license": "MIT",
   "type": "module",
   "repository": {