@turri-dev/cli 0.1.3-next.26f08c5 → 0.1.3-next.6fab174

package/README.md

@@ -212,7 +212,7 @@ It runs the interview skill, asks you about the problem, the stack and the produ
   model and cost - and the queue behind it;
 - ask to try it at any time - "let me try it" - and **`release`** puts what is built so far in
   `dist/<module>` and **`activate`** starts it, installing what it needs - nothing to approve;
-- the **side panel** (`ctrl+h`) takes the screen and opens on **regen** (`/regen`) - \*\*\*plain, every item marked planned, working, regenerated, validating, conform or needs you - and `p` turns it to the **pulses** (`/pulses`) - every pulse, running, queued and finished, and what each regenerates; what its agents did is in each pulse's log in `.turri/jobs/`;
+- the **side panel** (`ctrl+h`) takes the screen and opens on **regen** - \*\*\*plain, every item marked planned, working, regenerated, validating, conform or needs you - and `p` turns it to the **pulses** (`/pulses`) - every pulse, running, queued and finished, and what each regenerates; what its agents did is in each pulse's log in `.turri/jobs/`;
 - **`/halt`** halts a pulse, **`/lineage`** shows every generation of a
   module, and the **`drift`** tool says what is left to regenerate;
 - **`/btw <question>`** asks turri something on the side - answered at once, even in the middle of a skill's interview

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";
@@ -1468,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();
@@ -1498,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({
@@ -1514,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),
@@ -1528,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.
@@ -1565,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.
@@ -1591,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))
@@ -1607,6 +1672,7 @@ function registerJobTools(pi, jobs, cwd) {
                 dispose: () => {
                     unlisten();
                     clearInterval(timer);
+                    undock?.();
                     if (panel === entry)
                         panel = undefined;
                 },
@@ -1614,34 +1680,36 @@ 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;
             },
         });
     };
-    // The side panel's two views: /regen opens it on regen - the spec, with how far the code has been regenerated into it
-    // - and /pulses on every pulse, regenerating, planned and finished, and what each regenerates. What the agents did is
-    // in each pulse's log.
-    for (const [name, description, view] of [
-        ["regen", `regen, in the side panel: every item of the spec, built, regenerating, planned or waiting. ${PANEL_KEY} opens the panel too.`, "map"],
-        ["pulses", `The pulses, in the side panel: every pulse, regenerating, planned and finished, and what each regenerates. ${PANEL_KEY} opens the panel too.`, "pulses"],
-    ]) {
-        pi.registerCommand(name, {
-            description,
-            handler: async (_args, ctx) => {
-                if (!ctx.hasUI)
-                    return;
-                openPanel(ctx, view);
-            },
-        });
-    }
+    // /pulses opens the side panel on every pulse, regenerating, planned and finished, and what each regenerates; regen -
+    // the spec, with how far the code has been regenerated into it - is PANEL_KEY's, no command of its own beside
+    // /regenerate. What the agents did is in each pulse's log.
+    pi.registerCommand("pulses", {
+        description: `The pulses, in the side panel: every pulse, regenerating, planned and finished, and what each regenerates. ${PANEL_KEY} opens the panel too.`,
+        handler: async (_args, ctx) => {
+            if (!ctx.hasUI)
+                return;
+            openPanel(ctx, "pulses");
+        },
+    });
     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",
@@ -1712,8 +1780,12 @@ export const JOB_FINISHED_REACTION = [
     "A pulse that stopped on its environment - \"stopped: turri's sandbox kept its agents from…\" or \"stopped: the",
     "environment lacks…\" - stops the same way again until that is fixed: never regenerate it before. Heal it, then regenerate the",
     "module to resume:",
-    "- turri's sandbox kept the agents from a folder on this machine: nothing is missing. Add the folder its report names to",
-    "  `toolchains:` in config.turri.yaml - a list, keeping what is there - say so in a line, and resume.",
+    "- turri's sandbox kept the agents from reading a folder on this machine: nothing is missing. Add the folder its report",
+    "  names to `toolchains:` in config.turri.yaml - a list, keeping what is there - say so in a line, and resume.",
+    "- turri's sandbox kept the agents from writing a file - a lock a build tool takes, say: no setting lets them, and",
+    "  `toolchains:` does not - never add it there, and never resume before the fix. Do what the report says if it is the",
+    "  project's to change - a tool told to use `$HOME` in the build's own files - say so, and resume; otherwise tell the",
+    "  person, in a line or two, what the report says and that \"resume\" picks it up once it is done.",
     "- the machine lacks a toolchain or a tool - a JDK, Maven, Gradle, Go, uv, Node, a system library: first find out, in your",
     "  shell, whether it is installed somewhere off the PATH (`command -v`, Homebrew's opt folders, /Library/Java/",
     "  JavaVirtualMachines, a version manager the person uses - mise, asdf, sdkman, nvm). Then ask the person with ask_user",
@@ -2239,8 +2311,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;
 /**
@@ -2255,14 +2325,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;
@@ -2294,7 +2357,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;

package/dist/identity.js

@@ -25,7 +25,7 @@ export const TURRI_IDENTITY = [
     "- A pulse is one unit of work regenerating the code - a spec diff regenerated in a codebase, or its conformance",
     "  tests. It was called a job, and still is in places: the job_id a tool takes is a pulse's id, and parallel-jobs and",
     "  allow-to-stop-jobs in config.turri.yaml are about pulses. \"Job\" in what you read is a pulse; say pulse.",
-    "- regen is the side panel (/regen, or ctrl+h): the spec with each functionality and item marked built, regenerating,",
+    "- regen is the side panel (ctrl+h): the spec with each functionality and item marked built, regenerating,",
     "  planned or waiting - and behind it the pulses (/pulses), every pulse regenerating, planned and finished. Say regen,",
     "  lowercase. It was the regeneration, the job queue, or the job panel.",
     "- mutate, in a skill's activity, is write_spec_diff: a spec change written and regenerated in one step.",

package/dist/loop-tools.js

@@ -73,7 +73,7 @@ export async function loopReply(loop, statuses, wait) {
 export function stopJob(jobs, named, reason) {
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
     if (matches.length === 0)
-        return `No pulse ${named}. /regen shows them.`;
+        return `No pulse ${named}. /pulses shows them.`;
     if (matches.length > 1)
         return `'${named}' matches ${matches.map((job) => job.id).join(", ")}. Give more of the id.`;
     const target = matches[0];

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

@@ -188,6 +188,7 @@ export function sandboxNote(fence) {
         const report = fence.environmentTool !== undefined
             ? `report it as an environment error with ${fence.environmentTool}`
             : "say so plainly - what is missing and what needs it - and end your turn";
+        lines.push("- A command refused a file outside your folder - `Operation not permitted`, `Permission denied`, a lock it could not", `  take - is these walls, not the code, and nothing you change gets past them: ${report} at once, naming the file`, "  and the command that wanted it.");
         lines.push(fence.write.length > 0
             ? "- The project's dependencies are yours: declare them in the build manifest, and let the build tools fetch them."
             : "- You install nothing.", `${fence.write.length > 0 ? "  Installing anything else is not" : "  Nor is installing anything on the machine yours"}: no toolchains, system packages, drivers, global packages or \`sudo\`. If the`, `  machine lacks something the code needs, ${report}, name what is missing, and go no further with what depends on it.`, "  The person decides.", "- Ports and processes: you may stop only what you started. If a port is taken by something else, use another port.", "  `ps` may show nothing but what you started: check a server you started with `kill -0 $!`, its log, or a request to it.", "- Temporary files go in `$TMPDIR`: `/tmp` is outside your walls.");

package/dist/regenerate/environment-error.js

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, sep } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -35,7 +36,7 @@ export class EnvironmentError extends Error {
     sandbox;
     constructor(details) {
         super(details.sandbox !== undefined
-            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.paths[0]}, which is on this machine.`
+            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.access === "write" ? "writing" : "reading"} ${details.sandbox.paths[0]}, which is on this machine.`
             : `${details.moduleName} stopped: the environment lacks ${details.missing}.`);
         this.name = "EnvironmentError";
         this.moduleName = details.moduleName;
@@ -50,6 +51,10 @@ export class EnvironmentError extends Error {
             this.sandbox = details.sandbox;
     }
 }
+/** A file's name that says it is a lock: `lockfile`, `x.lock`, `x.lck`, `.lock-x`, `x.lock.y`. */
+const LOCK_FILE = /(?:^|[._-])(?:lock|lck|lockfile)(?:$|[._-])/i;
+/** What says the sandbox refused a write, not a read: writing, creating, a lock not taken - not a name with "lock" in it. */
+const WRITE_REFUSED = /\b(?:writ(?:e|es|ing|able)|creat(?:e|es|ing)|acquir(?:e|ing)|(?:take|obtain|get) (?:a |the )?lock|locking|read-only file system)\b/i;
 /** A folder named for a version - `24.16.0`, `v22.3.0`, `3.12.4` - the root of a version manager's install. */
 const VERSION = /^v?\d+\.\d+/;
 /** The parts of an install below its root, where the root ends: `…/24.16.0/lib/node_modules/…` ends before `lib`. */
@@ -74,27 +79,59 @@ export function sandboxGapOf(text, options = {}) {
     const system = (options.platform ?? process.platform) === "darwin" ? MACOS_MACHINE : LINUX_MACHINE;
     const within = (path, root) => path === root || path.startsWith(`${root}/`);
     const named = [...text.matchAll(/(?:^|[\s'"`(=:])(\/[^\s'"`()<>,;]+)/g)].map((match) => match[1].replace(/[.:]+$/, ""));
-    const paths = [...new Set(named)].filter((path) => path.split("/").length > 3 && exists(path) && !system.some((root) => within(path, root)) && (options.project === undefined || !within(path, options.project)));
-    return paths.length > 0 ? { paths, folder: toolchainFolder(paths[0]) } : undefined;
+    const isLock = (path) => LOCK_FILE.test(basename(path));
+    // A lock file the tool could not create is not there: its folder is.
+    const found = [...new Set(named)].filter((path) => path.split("/").length > 3 &&
+        (exists(path) || (isLock(path) && exists(dirname(path)))) &&
+        !system.some((root) => within(path, root)) &&
+        (options.project === undefined || !within(path, options.project)));
+    if (found.length === 0)
+        return undefined;
+    // The lock first: it is what the build could not take.
+    const paths = [...found.filter(isLock), ...found.filter((path) => !isLock(path))];
+    const lock = isLock(paths[0]);
+    return { paths, folder: toolchainFolder(paths[0]), access: lock || WRITE_REFUSED.test(text) ? "write" : "read", ...(lock ? { lock } : {}) };
 }
 /**
  * What the person is told, in the chat, at the end of `turri regenerate`, and in the job's log. `rerun`: the command that runs
  * the work again, as the pulse knows it - the spec the person ran; without it, the module's own spec by its name.
  */
 export function describeEnvironmentError(error, rerun) {
-    if (error.sandbox !== undefined) {
+    const again = `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`;
+    const needed = `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`;
+    const gap = error.sandbox;
+    if (gap?.access === "write") {
+        const what = gap.lock === true ? `the lock file \`${gap.paths[0]}\`, which the build takes as it runs` : `\`${gap.paths[0]}\``;
+        const home = homedir();
+        const inHome = gap.paths[0] === home || gap.paths[0].startsWith(`${home}/`);
+        return [
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from writing ${what} - it is on this machine; nothing is missing, and nothing needs installing.**`,
+            needed,
+            "An agent's commands write only their module's folders, their own home and temporary folder, and the package caches turri " +
+                "points the build tools at - no setting lets them write anywhere else, and `toolchains:` lets them read a folder, not write it.",
+            inHome
+                ? "To fix: it is in your home, not the agents' own - the tool found your home without `$HOME`, as a JVM does for `user.home`, " +
+                    "or a setting of yours points it there. Have it use `$HOME` instead - for a JVM tool, `-Duser.home=$HOME` where the build " +
+                    "starts its JVM - and the agents' own home takes it."
+                : `To fix: it is in a toolchain's own install, \`${gap.folder}\`, which the build writes into as it runs - and the agents may ` +
+                    "not change a toolchain. Have the build keep it elsewhere if the tool has a setting for it, or install a copy of the " +
+                    "toolchain that keeps its writes in its cache.",
+            again,
+        ].join("\n");
+    }
+    if (gap !== undefined) {
         return [
-            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${error.sandbox.paths[0]}\` - it is on this machine; nothing is missing.**`,
-            `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
-            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.yaml, keeping what is there: \`toolchains: [${error.sandbox.folder}]\`. Nothing needs installing.`,
-            `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${gap.paths[0]}\` - it is on this machine; nothing is missing.**`,
+            needed,
+            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.turri.yaml, keeping what is there: \`toolchains: [${gap.folder}]\`. Nothing needs installing.`,
+            again,
         ].join("\n");
     }
     return [
         `**${error.moduleName} stopped: the environment lacks ${error.missing}.**`,
         `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
         `To fix: ${error.fix ?? "provide it on this machine, then run it again."}`,
-        `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+        again,
     ].join("\n");
 }
 /** The name agents know the tool by - their wall text names it. */

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/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/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.
 
@@ -575,10 +577,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

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 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.
 
@@ -214,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.26f08c5",
+  "version": "0.1.3-next.6fab174",
   "license": "MIT",
   "type": "module",
   "repository": {