@turri-dev/cli 0.1.3-next.2babf06 → 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

@@ -1695,22 +1695,17 @@ function registerJobTools(pi, jobs, cwd) {
             },
         });
     };
-    // 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),
@@ -1785,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",

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/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/docs/regenerating.md

@@ -577,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,7 +127,7 @@ 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 -

package/package.json

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