@magland/gentl 0.1.0 → 0.1.1

package/README.md

@@ -33,16 +33,17 @@ Options:
 
 - `--image IMG`: the Docker image for the sandbox. The default is built on first use from [sandbox/Dockerfile](sandbox/Dockerfile) and tagged by its content (`gentl-sandbox:<hash>`).
 - `--host`: run on this machine in a fresh temp directory instead of Docker, for software that can't run in a container (for example a licensed MATLAB).
+- `--matlab-on-host`: `--host` set up for the MATLAB installed on this machine; see Host mode.
 - `--confirm`: ask before each action. This is the default with `--host`; Docker runs are unattended unless you pass it.
 - `--yes`: with `--host`, run actions without asking.
 - `--model M`: the agent's model, default `anthropic/claude-haiku-5.5`.
 - `--evaluator-model M`: the evaluator's model, same default.
-- `--upload`: upload each finished run to the hub its task came from.
+- `--upload`: upload each run that finishes, reaches the turn limit or is aborted to the hub its task came from.
 - `--yes`: don't ask before running a hub task (and, with `--host`, before each action).
 - `--backend B`: `openrouter` (default) or `claude-code`; see Backends.
 - `--local` / `--remote`: serve clones of the task's repo from your checkout (the default inside a git repo), or clone the published repo; see Local copy.
 - `--base-url URL`: any OpenAI-compatible endpoint (default `https://openrouter.ai/api/v1`). The key in `OPENROUTER_API_KEY` is sent to it.
-- `--max-turns N`: default 50.
+- `--max-turns N`: default 250.
 - `--repeat N`: run each task N times; see Repeated runs.
 - `--keep`: keep the container or temp workspace instead of deleting it.
 
@@ -68,13 +69,19 @@ The image and its id are recorded in `summary.json`.
 
 The agent works in `work/` inside a fresh temp directory, with `HOME` set to a sibling `home/` so it does not see your git config, caches or credentials. Only a few environment variables are passed through (`PATH`, locale, proxies); API keys and tokens are not. Each command runs in a fresh bash shell in its own process group, with no input and a 300 s timeout. The workspace is deleted at the end unless `--keep` is given.
 
-The agent can still reach anything on your machine that you can, so by default gentl shows each action and asks `ok? [y/n]` before running it. On `n` you can give a reason, which is passed back to the agent. Ctrl-C while a command runs stops that command (the agent is told); Ctrl-C at any other time ends the run, and the run directory is still written. This applies to Docker runs too.
+The agent can still reach anything on your machine that you can, so by default gentl shows each action and asks `ok? [y/n]` before running it. On `n` you can give a reason, which is passed back to the agent.
+
+Some licensed software keeps its licensing state in your home directory, which the agent's empty HOME does not have. `--share-home PATH` (repeatable) links that part of your real home directory into the agent's HOME, read and write, leaving the rest hidden; `--pass-env NAME` (repeatable) passes one more environment variable through. Both are printed at the start and recorded in `summary.json`. For MATLAB there is a shortcut, `--matlab-on-host`: it implies `--host` and shares `.matlab`, `.MathWorks` and `.MATLABConnector` (those that exist), which MATLAB's licensing needs (tested with R2025b and online licensing; without them MATLAB fails with licensing error 5201). It warns if there is no `matlab` command on your PATH. As with `--host`, add `--yes` to run without confirming each action:
+
+```
+gentl run TASK --matlab-on-host --yes
+```
 
 Host mode also inherits whatever is installed on your machine (compilers, Python packages, uv), so setup steps can succeed without the docs being followed, and reading effort is not comparable with Docker runs.
 
 ### Suites
 
-`gentl run DIR` runs every `*.md` file in the directory, in name order, skipping `README.md` and files starting with `_`. The task name is the file name. Runs go to `runs/<timestamp>-<suite>/<run>/`, and at the end gentl prints a results table (verdict, self-report, turns, read tokens, notes max, questions, cost) and writes it to `results.md` and `results.json` in the suite directory. Ctrl-C that ends a run skips the remaining runs.
+`gentl run DIR` runs every `*.md` file in the directory, in name order, skipping `README.md` and files starting with `_`. The task name is the file name. Runs go to `runs/<timestamp>-<suite>/<run>/`, and at the end gentl prints a results table (verdict, self-report, turns, read tokens, notes max, questions, cost) and writes it to `results.md` and `results.json` in the suite directory. Aborting a run with Ctrl-C skips the remaining runs.
 
 ### Repeated runs
 
@@ -90,12 +97,15 @@ Each turn the model sees only the system prompt, the task, its notes, and its la
 {"notes_keep": false, "notes": "...", "notes_edit": {"old": "...", "new": "..."}, "notes_append": "...", "action": {...}}
 ```
 
-The notes are the agent's working memory, meant to mimic how much a person can hold in their head at once, so the agent is asked to keep them small. `notes_keep` and `action` are required. Each turn the agent either updates its notes (`notes_keep: false` with one or more of the operations, applied in order: rewrite, edit, append) or keeps them as they are (`notes_keep: true`). Making the choice explicit matters: without it, models often wrote the action first and skipped the notes, then forgot what they had learned. If a response makes no notes decision anyway, gentl asks again within the same turn, once, with a short reminder (counted as reading and recorded as `notes_reminders`).
+The notes are the agent's working memory and its record of what it has done. The prompt asks for generous, specific notes (each step and its outcome, what was read and what it said, exact commands that worked, what failed, the plan), grown with append and edit rather than rewritten, since agents with thin notes reread files and rerun commands in circles. The prompt gives a stable layout (Goal, Done, Learned, Commands, Plan) and a sense of size (several hundred to a couple of thousand words on a long task), and no longer tells the agent that notes are counted. When a rewrite shrinks notes of 100 tokens or more by over half, the next result says so (`notes_shrink_warnings`); `notes_tokens_max` shows how much the agent carried. (An earlier version asked for small notes, to mimic how much a person holds in their head; that may come back once the agent stays on course with less.) `notes_keep` and `action` are required. Each turn the agent either updates its notes (`notes_keep: false` with one or more of the operations, applied in order: rewrite, edit, append) or keeps them as they are (`notes_keep: true`). Making the choice explicit matters: without it, models often wrote the action first and skipped the notes, then forgot what they had learned. If a response makes no notes decision anyway, gentl asks again within the same turn, once, with a short reminder (counted as reading and recorded as `notes_reminders`).
+
+A memoryless agent can also go in circles, rereading the same sections because nothing tells it it has read them. Two things work against that. The prompt asks the agent to keep a short log in its notes of what it has read and what it gave, to check it before reading, and to act on a result in the turn it sees it (for code: read the whole region to change at once, then edit) rather than collecting a file piece by piece. And when the agent repeats an action it already took at any earlier turn, the result says so, naming those turns (counted as reading; `repeated_actions` in the summary).
 
 Actions:
 
-- `run {cmd, max_chars?}`: bash in the working directory. stdout and stderr are combined. Output longer than `max_chars` (default 2000, at most 20000) is cut in the middle, keeping the head and tail.
-- `write_file {path, content}` and `edit_file {path, old, new}` (`old` must occur exactly once).
+- `run {cmd, max_chars?}`: bash in the working directory. stdout and stderr are combined. Output longer than `max_chars` (default 4000, at most 20000) is cut in the middle, keeping the head and tail, and the result's first line says so.
+- `read_file {path, start_line?, end_line?}`: exactly the requested lines of a file, numbered, never cut in the middle; a range over 20000 characters stops at a line boundary and says where to go on. The prompt asks the agent to read files this way rather than with `cat` or `sed`, whose output, like any command's, is cut in the middle when long. Without it, an agent reading part of a file would get both ends of the range and not the middle, ask for the middle, lose the rest, and go round in circles.
+- `write_file {path, content}` and `edit_file {path, old, new}` (`old` must occur exactly once). When `old` does not match, the error says why if it can: a backslash sequence in the code (`\n` in a string) written in the JSON as a real line break, or else the file's lines closest to it.
 - `ask {question}`: no one answers. The question is recorded as a gap in the docs, and the agent is told to decide from the docs and code.
 - `finish {success, summary, friction?}`: the summary cites the evidence of success; `friction` is the agent's own account of what was missing or unclear in the docs.
 
@@ -108,9 +118,13 @@ gentl asks for structured output (a JSON schema) so responses parse reliably; if
 
 The backend is recorded in `summary.json`. Runs with different backends are not directly comparable.
 
+### Stopping a run
+
+Ctrl-C aborts the run wherever it is: a running command is killed and a model call cancelled. The run is recorded with stop reason `aborted`, evaluated (its verdict is always a failure, and the friction report covers what happened up to the abort), and, with `--upload`, reported to the hub. A second Ctrl-C during the evaluation skips it. The sandbox is removed in every case. A command that hangs is also stopped by the 300 s timeout, and the agent is told. SIGTERM and SIGHUP (the process killed, the terminal closed) end the run with stop reason `interrupted`, without an evaluation or upload; the run directory is still written.
+
 ## Evaluation
 
-After a run that finishes (or reaches the turn limit), gentl records the final state of the workspace: for each git repo, `git status`, the commits and `git diff` against its upstream, and untracked files; also any loose files in the working directory. Then an evaluator (one model call) reads the full log, with the parts of each result that the agent did not see marked as such, the questions asked, the agent's finish report and the final state. It writes:
+After a run that finishes, reaches the turn limit or is aborted, gentl records the final state of the workspace: for each git repo, `git status`, the commits and `git diff` against its upstream, and untracked files; also any loose files in the working directory. Then an evaluator (one model call) reads the full log, with the parts of each result that the agent did not see marked as such, the questions asked, the agent's finish report and the final state. It writes:
 
 - a verdict: did the agent actually accomplish the task, judged from the evidence rather than the agent's claim;
 - a friction report: docs used, what was missing or wrong, where the agent guessed, signs of prior knowledge (commands or APIs it used that never appeared in anything it read), and the questions it asked.
@@ -128,7 +142,7 @@ The evaluator's tokens are not counted as reading effort. Reading effort should
 A hub ([gentl-hub](https://github.com/magland/gentl-hub); the public one is https://gentl-hub.jeremy-magland.workers.dev) holds tasks with titles, shows the command to run each, and collects uploaded runs. gentl contacts a hub only when given a hub task URL or asked to upload.
 
 - `gentl run https://<hub>/tasks/<id>` fetches the task, prints its title and text, and asks before running it (`--yes` skips this). Hub tasks always clone the published repo, never a local copy, so uploaded results match public code.
-- `--upload` uploads each run that finished (or hit the turn limit) to that hub; `gentl upload runs/<id>` uploads one later, and `gentl upload runs/<batch>` uploads every run in a batch. A run goes only to the hub its task came from.
+- `--upload` uploads each run that finished, hit the turn limit or was aborted (Ctrl-C) to that hub; `gentl upload runs/<id>` uploads one later, and `gentl upload runs/<batch>` uploads every run in a batch. A run goes only to the hub its task came from.
 - The first upload to a hub asks for your name (shown with your runs) and the hub's passcode, and offers to remember them in `~/.config/gentl/hubs.json` (mode 0600). `GENTL_HUB_USER` and `GENTL_HUB_PASSCODE` override it.
 - The upload holds `summary.json`, `evaluation.json`, `final-state.md`, and each turn as the agent saw it (notes, action, shown result); full command output stays local.
 

package/dist/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { parseArgs } from "node:util";
 import { checkDocker, ensureDefaultImage } from "./docker.js";
 import { fetchHubTask, hubCredentials, parseHubTaskUrl, runDirsIn, runHub, uploadRun } from "./hub.js";
+import { resolveSharedHome } from "./host.js";
 import { findRepo, prepareLocalCopy, removeLocalCopy } from "./localcopy.js";
 import { evaluate, runTask } from "./run.js";
 import { runBatch, suiteTasks } from "./suite.js";
@@ -25,6 +27,11 @@ options:
   --image IMG         Docker image for the sandbox (default: built from gentl's sandbox/Dockerfile)
   --host              run in a fresh temp directory on this machine instead of Docker
   --confirm           ask before each action (the default with --host)
+  --share-home PATH   with --host, link this part of your home directory (e.g. .matlab) into the
+                      agent's otherwise empty HOME; repeatable
+  --pass-env NAME     with --host, pass this environment variable through as well; repeatable
+  --matlab-on-host    use the MATLAB installed on this machine: implies --host and shares the
+                      home folders MATLAB's licensing needs (.matlab, .MathWorks, .MATLABConnector)
   --yes               don't ask: run a hub task without confirming it, and with --host, run actions
                       without asking
   --upload            upload each finished run to the hub its task came from
@@ -34,7 +41,7 @@ options:
                       claude-code (your Claude Code login, via claude -p); default from
                       GENTL_BACKEND, else openrouter
   --base-url URL      OpenAI-compatible endpoint (default ${DEFAULT_BASE_URL})
-  --max-turns N       stop after N turns (default 50)
+  --max-turns N       stop after N turns (default 250)
   --repeat N          run each task N times and report the success rate and median read tokens
   --local             serve clones of the task's repo from your checkout, uncommitted changes included
                       (the default when the task file, suite or current directory is in a git repo)
@@ -43,6 +50,11 @@ options:
 
 The API key is read from OPENROUTER_API_KEY, in the environment or in ./.env.
 Runs are written to ./runs/<id>/.`;
+/** The home folders a licensed MATLAB keeps its licensing state in (R2025b, online licensing). */
+const MATLAB_HOME_DIRS = [".matlab", ".MathWorks", ".MATLABConnector"];
+function onPath(cmd) {
+    return (process.env.PATH ?? "").split(path.delimiter).some((d) => d && fs.existsSync(path.join(d, cmd)));
+}
 /** A variable from the environment, or from ./.env. */
 function envValue(name) {
     if (process.env[name])
@@ -71,13 +83,16 @@ async function run(argv) {
             confirm: { type: "boolean" },
             yes: { type: "boolean" },
             local: { type: "boolean" },
+            "share-home": { type: "string", multiple: true },
+            "matlab-on-host": { type: "boolean" },
+            "pass-env": { type: "string", multiple: true },
             upload: { type: "boolean" },
             remote: { type: "boolean" },
             model: { type: "string", default: DEFAULT_MODEL },
             "evaluator-model": { type: "string", default: DEFAULT_MODEL },
             backend: { type: "string" },
             "base-url": { type: "string", default: DEFAULT_BASE_URL },
-            "max-turns": { type: "string", default: "50" },
+            "max-turns": { type: "string", default: "250" },
             repeat: { type: "string", default: "1" },
             keep: { type: "boolean" },
             help: { type: "boolean", short: "h" },
@@ -89,6 +104,12 @@ async function run(argv) {
     }
     if ((values.task === undefined) === (positionals.length !== 1))
         fail("give one task: a task file or -t TEXT");
+    // --matlab-on-host is --host plus MATLAB's home folders; set host first, since confirmation depends on it.
+    if (values["matlab-on-host"]) {
+        if (values.image)
+            fail("--matlab-on-host runs on this machine, so --image does not apply");
+        values.host = true;
+    }
     if (values.host && values.image)
         fail("--image applies to the Docker sandbox, not --host");
     if (values.confirm && values.yes)
@@ -106,8 +127,24 @@ async function run(argv) {
         fail("--repeat must be a positive integer");
     const modelFor = modelConfig(values.backend, values["base-url"]);
     let sandbox;
+    const shareHome = [...(values["share-home"] ?? []),
+        ...(values["matlab-on-host"] ? MATLAB_HOME_DIRS.filter((d) => fs.existsSync(path.join(os.homedir(), d))) : [])];
+    if (values["matlab-on-host"] && !onPath("matlab")) {
+        console.log("warning: --matlab-on-host, but there is no matlab command on your PATH, so the agent will not find one either");
+    }
+    const passEnv = values["pass-env"] ?? [];
+    if (!values.host && (shareHome.length || passEnv.length))
+        fail("--share-home and --pass-env apply only with --host");
+    for (const p of shareHome) {
+        try {
+            resolveSharedHome(p);
+        }
+        catch (e) {
+            fail(e.message);
+        }
+    }
     if (values.host) {
-        sandbox = { kind: "host" };
+        sandbox = { kind: "host", shareHome, passEnv };
         if (!confirm)
             console.log("warning: host mode without confirmation; the agent's commands run on this machine unchecked");
     }

package/dist/evaluate.js

@@ -52,6 +52,8 @@ function formatActionForEvaluator(a) {
     switch (a.type) {
         case "run":
             return `run:\n${fence(String(a.cmd), "bash")}`;
+        case "read_file":
+            return `read_file ${a.path}${a.start_line !== undefined || a.end_line !== undefined ? ` lines ${a.start_line ?? 1}-${a.end_line ?? "end"}` : ""}`;
         case "write_file":
             return `write_file ${a.path}:\n${fence(clip(String(a.content), RESULT_CAP))}`;
         case "edit_file":
@@ -91,7 +93,9 @@ export function buildEvaluatorInput(runDir) {
     const asks = (summary.asks ?? []);
     const finish = summary.finished
         ? `success: ${summary.self_reported_success}\nsummary: ${summary.self_report_summary}\nfriction: ${summary.self_report_friction ?? "(none given)"}`
-        : `The agent did not finish (stop reason: ${summary.stop_reason}).`;
+        : summary.stop_reason === "aborted"
+            ? `The person running gentl aborted the run (Ctrl-C) after turn ${summary.turns}, before the agent finished. The verdict is therefore a failure; write the reasons and the friction report from what happened up to that point.`
+            : `The agent did not finish (stop reason: ${summary.stop_reason}).`;
     const lc = summary.local_copy
         ? ` Clones of ${summary.local_copy.origin} were served from the maintainer's local working copy (with any uncommitted changes), so the agent's clone may differ from the published repo and its origin URL is a local file:// path; this is intended, not a problem with the run.`
         : "";
@@ -111,8 +115,12 @@ export async function evaluateRun(runDir, cfg, signal, log) {
     catch {
         throw new Error(`could not parse the evaluator's response: ${reply.text.slice(0, 300)}`);
     }
+    // An aborted run is a failure whatever the evaluator says; its reasons and friction report still stand.
+    const aborted = JSON.parse(fs.readFileSync(path.join(runDir, "summary.json"), "utf8")).stop_reason === "aborted";
+    const reasons = String(parsed.reasons ?? "");
     const ev = {
-        model: cfg.model, success: parsed.success, reasons: String(parsed.reasons ?? ""),
+        model: cfg.model, success: aborted ? false : parsed.success,
+        reasons: aborted ? `Aborted by the person running gentl before the agent finished. ${reasons}` : reasons,
         friction_report: String(parsed.friction_report ?? ""), structured_output: client.structured,
         usage: reply.usage, cost_usd: Number(reply.usage.cost ?? 0), input_chars: input.length, created: new Date().toISOString(),
     };

package/dist/host.js

@@ -17,27 +17,51 @@ function killGroup(pid) {
         // already gone
     }
 }
+/** A --share-home path: relative to HOME, inside it, and existing. Returns the absolute path or throws. */
+export function resolveSharedHome(p) {
+    const home = os.homedir();
+    const abs = path.resolve(home, p.replace(/^~\//, ""));
+    if (abs === home || !abs.startsWith(home + path.sep))
+        throw new Error(`--share-home ${p}: give a path inside your home directory, such as .matlab`);
+    if (!fs.existsSync(abs))
+        throw new Error(`--share-home ${p}: ${abs} does not exist`);
+    return abs;
+}
 export class HostSandbox extends Sandbox {
+    opts;
     kind = "host";
     root;
     workdir;
     env = {};
     groups = new Set(); // process groups of all commands, killed on remove()
-    constructor() {
+    links = []; // links into the real HOME, removed before the workspace is deleted
+    constructor(opts = { shareHome: [], passEnv: [] }) {
         super();
+        this.opts = opts;
         this.root = fs.mkdtempSync(path.join(os.tmpdir(), "gentl-"));
         this.workdir = path.join(this.root, "work");
         const home = path.join(this.root, "home");
         fs.mkdirSync(this.workdir);
         fs.mkdirSync(home);
-        for (const k of PASSTHROUGH_ENV)
+        // Shared parts of the real HOME are linked in, not copied, so programs that keep state there (MATLAB's
+        // licensing) see and update the real thing. Everything else in the real HOME stays out of reach.
+        for (const p of opts.shareHome) {
+            const real = resolveSharedHome(p);
+            const link = path.join(home, path.relative(os.homedir(), real));
+            fs.mkdirSync(path.dirname(link), { recursive: true });
+            fs.symlinkSync(real, link);
+            this.links.push(link);
+        }
+        for (const k of [...PASSTHROUGH_ENV, ...opts.passEnv])
             if (process.env[k] !== undefined)
                 this.env[k] = process.env[k];
         Object.assign(this.env, { HOME: home, TERM: "dumb", NO_COLOR: "1", PAGER: "cat", GIT_PAGER: "cat",
             GIT_TERMINAL_PROMPT: "0" });
     }
     describe() {
-        return `host, workspace ${this.root}`;
+        const shared = this.opts.shareHome.length ? `, sharing ~/${this.opts.shareHome.join(", ~/")} from your home` : "";
+        const env = this.opts.passEnv.length ? `, passing ${this.opts.passEnv.join(", ")}` : "";
+        return `host, workspace ${this.root}${shared}${env}`;
     }
     start(cmd) {
         const child = spawn("bash", ["-c", cmd], { cwd: this.workdir, env: this.env, detached: true,
@@ -52,6 +76,9 @@ export class HostSandbox extends Sandbox {
     remove() {
         for (const pid of this.groups)
             killGroup(pid);
+        // Unlink the shared parts of the real HOME first, so nothing below can reach into them.
+        for (const link of this.links)
+            fs.rmSync(link, { force: true });
         try {
             fs.rmSync(this.root, { recursive: true, force: true });
         }

package/dist/protocol.js

@@ -1,7 +1,8 @@
 // What the agent sees and how its responses are parsed.
-export const ACTION_TYPES = ["run", "write_file", "edit_file", "ask", "finish"];
+export const ACTION_TYPES = ["run", "read_file", "write_file", "edit_file", "ask", "finish"];
+export const READ_MAX_CHARS = 20000; // a read_file result stops at a line boundary before this
 export const ASK_RESULT = "No one is available to answer. Your question is recorded as a gap in the docs. Decide from the docs and code as best you can.";
-export const DEFAULT_MAX_CHARS = 2000;
+export const DEFAULT_MAX_CHARS = 4000;
 export const MAX_MAX_CHARS = 20000;
 export const CMD_TIMEOUT_S = 300;
 export function systemPrompt(workdir, platform) {
@@ -9,18 +10,34 @@ export function systemPrompt(workdir, platform) {
 
 Treat the software as unfamiliar. Go by its docs and code, not by what you remember about it, since the version here may differ.
 
-This is a test of how readable the software and its docs are. We count the tokens you read (every result you see, plus your notes each turn) as a proxy for the effort a human newcomer would need, and we collect what was missing or unclear. So read in a targeted way (grep, sed -n, head, --help) rather than dumping whole files or long pages. When the docs and code don't answer something you need, don't keep searching or guess silently: use the ask action, then make a reasonable decision and move on. A gap in the docs is useful feedback, not a failure on your part.
+This is a test of how readable the software and its docs are. We count the tokens of the results you read as a proxy for the effort a human newcomer would need, and we collect what was missing or unclear. So read in a targeted way (grep, sed -n, head, --help) rather than dumping whole files or long pages. When the docs and code don't answer something you need, don't keep searching or guess silently: use the ask action, then make a reasonable decision and move on. A gap in the docs is useful feedback, not a failure on your part.
 
-You have no memory between turns. Each turn you see only the task, your notes, and your last action with its result. The result is shown once and is gone on the next turn; your notes are all you carry forward. They are your working memory, like what a person can hold in their head at once. They start empty.
+You have no memory between turns. Each turn you see only the task, your notes, and your last action with its result. The result is shown once and is gone on the next turn; your notes are all you carry forward. They are your working memory and your record of what you have done. They start empty.
 
-So every turn has two steps. First, update your notes: if the result (or the task, on the first turn) tells you something you will need later, such as a fact, a path, a command that worked, what is done or what is next, record it and set "notes_keep": false. Only if nothing is worth keeping, set "notes_keep": true. Second, choose the action. Keep the notes small, with only what you still need; they are counted every turn.
+So every turn has two steps. First, update your notes with what the result (or the task, on the first turn) told you, and set "notes_keep": false; almost every result is worth at least a line (what you ran and what came of it), so set "notes_keep": true only if the result told you nothing worth keeping. Second, choose the action.
+
+Be generous with notes. Forgetting is what costs: an agent with thin notes rereads files and reruns commands, and goes in circles. Notes of several hundred to a couple of thousand words are normal on a long task; a short note that forces you to read something again is the expensive choice. Record, specifically:
+- each step you have taken and its outcome, as soon as the result confirms it (for example: "edit 1 applied to +pkg/list.m: added the --json flag at line 23; verified");
+- what you have read and what it told you: file and line range or doc section, the key facts, and any exact snippets you will need again (a function signature, the lines you will edit);
+- commands that worked, written out exactly, with the key part of their output; commands that failed, and why;
+- your plan and the next step.
+A layout that stays the same from turn to turn makes this easy, with new lines appended under each heading:
+Goal: ...
+Done: (each step and its outcome)
+Learned: (file:lines and what they say; exact snippets)
+Commands: (exact commands that worked, with key output; failures and why)
+Plan: ...
+Before acting, check whether your notes say it is already done or already read. Grow the notes with "notes_append" and "notes_edit" rather than rewriting them from scratch, so that nothing you still need is lost; rewrite only to reorganize, and remove things only once they are finished and will not be needed again.
+
+You cannot hold a whole file in your notes, so don't collect one piece by piece. Instead, act on a result in the turn you see it: to change code, read the whole region you need at once and make the edit in your response to that result, copying the exact text to replace from it.
 
 Each turn, respond with one JSON object and nothing else:
 {"notes_keep": false, "notes": "...", "notes_edit": {"old": "...", "new": "..."}, "notes_append": "...", "action": {...}}
 "notes_keep" and "action" are required. With "notes_keep": false, give at least one of "notes" (replaces your notes), "notes_edit" (replaces text that occurs exactly once in them) and "notes_append" (adds a line at the end); they are applied in that order. "notes_keep": true leaves your notes as they are.
 
 Actions:
-- {"type": "run", "cmd": "..."}: run with bash in your working directory. Each command starts a fresh shell (cd and exported variables do not persist) with no input. stdout and stderr are combined; output longer than ${DEFAULT_MAX_CHARS} characters is cut in the middle (add "max_chars": N, at most ${MAX_MAX_CHARS}, to see more). Timeout ${CMD_TIMEOUT_S} s.
+- {"type": "run", "cmd": "..."}: run with bash in your working directory. Each command starts a fresh shell (cd and exported variables do not persist) with no input. stdout and stderr are combined; output longer than ${DEFAULT_MAX_CHARS} characters is cut in the middle, keeping its start and end, and the result's first line says so (add "max_chars": N, at most ${MAX_MAX_CHARS}, to see more). Timeout ${CMD_TIMEOUT_S} s.
+- {"type": "read_file", "path": "...", "start_line": N, "end_line": M}: show lines N to M of a file, numbered (both optional: the whole file, or from N to the end). It shows exactly the lines asked for and is never cut in the middle; a range over ${READ_MAX_CHARS} characters stops early and says where to go on. Use it, not cat or sed, to read files.
 - {"type": "write_file", "path": "...", "content": "..."}: create or overwrite a file. Relative paths are under your working directory.
 - {"type": "edit_file", "path": "...", "old": "...", "new": "..."}: replace text that occurs exactly once in the file.
 - {"type": "ask", "question": "..."}: ask the maintainers something the docs and code don't tell you. No one will answer during this test; the question is recorded as feedback on the docs.
@@ -41,6 +58,7 @@ export const RESPONSE_SCHEMA = obj({
     action: {
         anyOf: [
             obj({ type: actionType("run"), cmd: str, max_chars: { type: "integer" } }, ["type", "cmd"]),
+            obj({ type: actionType("read_file"), path: str, start_line: { type: "integer" }, end_line: { type: "integer" } }, ["type", "path"]),
             obj({ type: actionType("write_file"), path: str, content: str }, ["type", "path", "content"]),
             obj({ type: actionType("edit_file"), path: str, old: str, new: str }, ["type", "path", "old", "new"]),
             obj({ type: actionType("ask"), question: str }, ["type", "question"]),
@@ -156,6 +174,14 @@ export function validateAction(a) {
             if (a.max_chars !== undefined && typeof a.max_chars !== "number")
                 return '"max_chars" must be a number';
             return null;
+        case "read_file":
+            if (!str("path"))
+                return 'read_file needs "path" (string)';
+            for (const k of ["start_line", "end_line"]) {
+                if (a[k] !== undefined && !(Number.isInteger(a[k]) && a[k] >= 1))
+                    return `"${k}" must be a whole number, at least 1`;
+            }
+            return null;
         case "write_file":
             return str("path") && str("content") ? null : 'write_file needs "path" and "content" (strings)';
         case "edit_file":
@@ -177,6 +203,8 @@ export function describeAction(a) {
     switch (a.type) {
         case "run":
             return a.max_chars !== undefined && a.max_chars !== DEFAULT_MAX_CHARS ? `run (max_chars ${a.max_chars}): ${a.cmd}` : `run: ${a.cmd}`;
+        case "read_file":
+            return `read_file: ${a.path}${a.start_line !== undefined || a.end_line !== undefined ? ` (lines ${a.start_line ?? 1}-${a.end_line ?? "end"})` : ""}`;
         case "write_file":
         case "edit_file":
             return `${a.type}: ${a.path}`;

package/dist/run.js

@@ -18,6 +18,8 @@ function formatAction(a) {
     switch (a.type) {
         case "run":
             return `### Action: run${a.max_chars !== undefined ? ` (max_chars ${a.max_chars})` : ""}\n${fence(String(a.cmd), "bash")}`;
+        case "read_file":
+            return `### Action: read_file \`${a.path}\`${a.start_line !== undefined || a.end_line !== undefined ? ` lines ${a.start_line ?? 1}-${a.end_line ?? "end"}` : ""}\n`;
         case "write_file":
             return `### Action: write_file \`${a.path}\`\n${fence(String(a.content))}`;
         case "edit_file":
@@ -45,6 +47,7 @@ function formatSummary(s) {
             `${s.parse_errors} / ${s.invalid_actions} / ${s.repeated_actions} / ${s.declined_actions}`],
         ["Questions asked", s.asks.length],
         ["Notes reminders (responses without a notes decision)", s.notes_reminders],
+        ["Notes shrink warnings (a rewrite lost over half the notes)", s.notes_shrink_warnings],
         ["Cost", `$${s.cost_usd.toFixed(4)}${s.backend === "claude-code" ? " (notional; Claude Code subscription)" : ""}`],
         ["Duration", `${Math.round(s.duration_s)} s`],
     ];
@@ -105,6 +108,8 @@ function actionLine(a) {
     switch (a.type) {
         case "run":
             return `run: ${firstLine(String(a.cmd), 90)}`;
+        case "read_file":
+            return `read_file: ${a.path}${a.start_line !== undefined || a.end_line !== undefined ? ` ${a.start_line ?? 1}-${a.end_line ?? "end"}` : ""}`;
         case "write_file":
         case "edit_file":
             return `${a.type}: ${a.path}`;
@@ -128,20 +133,23 @@ export async function runTask(opts) {
     const sb = opts.sandbox.kind === "docker"
         // The random suffix keeps names unique when two gentl processes start the same task in the same second.
         ? new DockerSandbox(`gentl-${runId.toLowerCase().replace(/[^a-z0-9_.-]/g, "-")}-${randomBytes(3).toString("hex")}`, opts.sandbox.image, lc ? [{ host: lc.mirrorDir, container: MIRROR_MOUNT }] : [])
-        : new HostSandbox();
+        : new HostSandbox({ shareHome: opts.sandbox.shareHome, passEnv: opts.sandbox.passEnv });
     // Signal handlers go in as soon as the sandbox exists, so no signal can leave it behind.
-    // Ctrl-C stops the running command, or cancels the model call and ends the run.
-    // SIGTERM and SIGHUP end the run wherever it is; the run directory is still completed.
-    // During cleanup further signals are ignored, so a second Ctrl-C cannot leave the sandbox behind.
+    // Ctrl-C aborts the run wherever it is (a running command is killed, a model call cancelled); the run is
+    // then evaluated as a failure and, with --upload, reported. SIGTERM and SIGHUP end it without either.
+    // The run directory is completed in every case. During cleanup further signals are ignored, so a
+    // second Ctrl-C cannot leave the sandbox behind.
     let abortModel = null;
-    let stopRequested = false;
+    let abortRequested = false; // Ctrl-C
+    let stopRequested = false; // SIGTERM, SIGHUP
     let cleaningUp = false;
     const onSigint = () => {
         if (cleaningUp)
             return console.log("     still cleaning up (removing the sandbox); please wait");
-        if (sb.interrupt())
-            return;
-        stopRequested = true;
+        if (!abortRequested)
+            console.log("\n     aborting the run (Ctrl-C); it will be evaluated as a failure and, with --upload, reported");
+        abortRequested = true;
+        sb.interrupt();
         abortModel?.abort();
     };
     const onTerm = () => {
@@ -176,11 +184,13 @@ export async function runTask(opts) {
         base_url: opts.model.backend === "openrouter" ? opts.model.baseUrl : null,
         sandbox: sb.kind, image: sb instanceof DockerSandbox ? sb.image : null,
         image_id: sb instanceof DockerSandbox ? sb.imageId : null, confirm: opts.confirm,
+        host_share_home: opts.sandbox.kind === "host" ? opts.sandbox.shareHome : [],
+        host_pass_env: opts.sandbox.kind === "host" ? opts.sandbox.passEnv : [],
         local_copy: lc && !localCopyError ? localCopyInfo(lc) : null, structured_output: true, started: started.toISOString(), ended: "", duration_s: 0,
         system_prompt: system, overhead_tokens: ntok(system) + ntok(opts.task), turns: 0,
         read_tokens_total: 0, notes_tokens_total: 0, notes_tokens_max: 0, result_tokens_total: 0, result_tokens_max: 0,
         model_output_tokens: 0, provider_prompt_tokens: 0, provider_completion_tokens: 0, cost_usd: 0,
-        parse_errors: 0, invalid_actions: 0, repeated_actions: 0, declined_actions: 0, notes_reminders: 0, asks: [],
+        parse_errors: 0, invalid_actions: 0, repeated_actions: 0, declined_actions: 0, notes_reminders: 0, notes_shrink_warnings: 0, asks: [],
         stop_reason: null, error: null, finished: false,
         self_reported_success: null, self_report_summary: null, self_report_friction: null, final_repos: null,
     };
@@ -203,10 +213,10 @@ export async function runTask(opts) {
         backend: opts.model.backend, base_url: s.base_url, sandbox: sb.kind, sandbox_description: sb.describe(), workdir: sb.workdir, confirm: opts.confirm, system_prompt: system });
     let notes = "";
     let last = null;
-    let lastActionJson = null;
+    const seen = new Map(); // action key -> turns it was taken
     try {
         for (let turn = 1; turn <= opts.maxTurns; turn++) {
-            if (stopRequested)
+            if (stopRequested || abortRequested)
                 throw new Interrupted();
             let user = `# Task\n${opts.task}\n\n# Your notes\n${notes || "(empty)"}\n`;
             if (last)
@@ -274,8 +284,16 @@ export async function runTask(opts) {
                 emit({ ...ev, parse_error: msg });
                 continue;
             }
+            const notesBefore = notesTok;
             const n = applyNotes(notes, parsed);
             notes = n.notes;
+            // A rewrite that loses much of the notes is pointed out on the next turn: details dropped in a careless
+            // rewrite are the commonest reason an agent redoes work.
+            const notesAfter = ntok(notes);
+            if (n.ops.includes("rewritten") && notesBefore >= 100 && notesAfter < notesBefore / 2) {
+                s.notes_shrink_warnings++;
+                n.feedback.push(`note: your notes went from ${notesBefore} to ${notesAfter} tokens with this rewrite; check that nothing you still need was lost (grow the notes with notes_append and notes_edit rather than rewriting them).`);
+            }
             const a = parsed.action;
             const line = actionLine(a);
             console.log(prefix + line);
@@ -291,13 +309,16 @@ export async function runTask(opts) {
                 emit(ev);
                 break;
             }
+            // An action the agent already took, at any earlier turn, is pointed out: rereading the same thing in a
+            // cycle is the commonest way a memoryless agent gets stuck.
             const notices = [];
-            const actionJson = JSON.stringify(a);
-            if (actionJson === lastActionJson) {
+            const key = a.type === "run" ? `run ${String(a.cmd).replace(/\s+/g, " ").trim()}` : JSON.stringify(a);
+            const earlier = seen.get(key) ?? [];
+            if (earlier.length) {
                 s.repeated_actions++;
-                notices.push("note: this action is identical to your previous one.");
+                notices.push(`note: you already ran this exact ${a.type === "run" ? "command" : "action"} at turn${earlier.length > 1 ? "s" : ""} ${earlier.join(", ")}. If you are rereading, act on what your notes hold, or record what you need from it this time.`);
             }
-            lastActionJson = actionJson;
+            seen.set(key, [...earlier, turn]);
             let full;
             let shown;
             if (invalid) {
@@ -323,6 +344,9 @@ export async function runTask(opts) {
                     Object.assign(ev, { truncation: r.truncation ?? undefined, exit_code: r.exitCode, signal: r.signal, cmd_seconds: r.seconds, timed_out: r.timedOut,
                         interrupted: r.interrupted });
                 }
+                else if (a.type === "read_file") {
+                    full = shown = sb.readFile(String(a.path), a.start_line, a.end_line);
+                }
                 else if (a.type === "write_file") {
                     full = shown = sb.writeFile(String(a.path), String(a.content));
                 }
@@ -340,8 +364,10 @@ export async function runTask(opts) {
             s.stop_reason = "max_turns";
     }
     catch (e) {
+        // Ctrl-C at a confirmation prompt arrives as Interrupted without a signal, so anything not SIGTERM or
+        // SIGHUP counts as the person's abort.
         if (e instanceof Interrupted)
-            s.stop_reason = "interrupted";
+            s.stop_reason = stopRequested ? "interrupted" : "aborted";
         else {
             s.stop_reason = "error";
             s.error = e.message;
@@ -380,14 +406,15 @@ export async function runTask(opts) {
         console.log(`Agent's summary: ${s.self_report_summary}\n`);
     if (s.self_report_friction)
         console.log(`Agent's friction report: ${s.self_report_friction}\n`);
-    if (s.stop_reason === "finish" || s.stop_reason === "max_turns") {
+    const evaluable = s.stop_reason === "finish" || s.stop_reason === "max_turns" || s.stop_reason === "aborted";
+    if (evaluable) {
         const ev = await evaluate(runDir, opts.evaluatorModel);
         if (ev)
             s.evaluation = { model: ev.model, success: ev.success, reasons: ev.reasons, cost_usd: ev.cost_usd };
     }
     console.log(`Run directory: ${runDir}`);
     if (opts.upload) {
-        if (s.stop_reason === "finish" || s.stop_reason === "max_turns") {
+        if (evaluable) {
             try {
                 console.log(`Uploaded: ${await uploadRun(runDir, opts.upload)}`);
             }

package/dist/sandbox.js

@@ -1,7 +1,7 @@
 // Where the agent's actions run. A sandbox runs commands with a timeout in their own process group, writes and
 // edits files, and runs short commands for gentl itself (e.g. to record the final state).
 import { spawnSync } from "node:child_process";
-import { CMD_TIMEOUT_S, countOccurrences, DEFAULT_MAX_CHARS, MAX_MAX_CHARS } from "./protocol.js";
+import { CMD_TIMEOUT_S, countOccurrences, DEFAULT_MAX_CHARS, MAX_MAX_CHARS, READ_MAX_CHARS } from "./protocol.js";
 const CAPTURE_HEAD = 1 << 20; // bytes of output kept from the start of a command
 const CAPTURE_TAIL = 1 << 20; // and from the end
 /** Keep the head and tail, with a note on what was cut and how to see more. */
@@ -76,8 +76,10 @@ export class Sandbox {
                 if (classified.keep)
                     cap.add(Buffer.from(classified.keep));
                 const out = cap.text();
-                const status = cur.interrupted ? "stopped by the person running gentl (Ctrl-C)"
+                let status = cur.interrupted ? "stopped by the person running gentl (Ctrl-C)"
                     : timedOut ? `timed out after ${CMD_TIMEOUT_S} s` : code !== null ? `exit code ${code}` : `killed by ${signal}`;
+                if (out.length > maxChars)
+                    status += `; output cut in the middle (${out.length - Math.floor((maxChars * 3) / 5) - Math.floor((maxChars * 2) / 5)} of ${out.length} chars left out)`;
                 const truncation = out.length > maxChars
                     ? { head: status.length + 1 + Math.floor((maxChars * 3) / 5), tail: Math.floor((maxChars * 2) / 5) } : null;
                 resolve({ exitCode: code, signal, full: `${status}\n${out}`, shown: `${status}\n${truncate(out, maxChars)}`,
@@ -109,17 +111,76 @@ export class Sandbox {
         const r = this.exec(["sh", "-c", 'mkdir -p "$(dirname "$1")" && cat > "$1"', "sh", p], undefined, content);
         return r.ok ? `wrote ${p}` : `error: ${r.out.trim()}`;
     }
+    /** Lines `start` to `end` of a file, numbered; never cut in the middle, stopped at a line boundary if too long. */
+    readFile(p, start, end) {
+        const r = this.exec(["cat", "--", p]);
+        if (!r.ok)
+            return `error: ${r.out.trim()}`;
+        if (r.out.includes("\0"))
+            return `error: ${p} is a binary file`;
+        const lines = r.out.split("\n");
+        if (lines.length && lines[lines.length - 1] === "")
+            lines.pop();
+        const total = lines.length;
+        const from = Math.max(1, start ?? 1);
+        const to = Math.min(total, end ?? total);
+        if (from > total)
+            return `${p} has ${total} lines; nothing at line ${from}`;
+        const width = String(to).length;
+        let body = "";
+        let last = from - 1;
+        for (let i = from; i <= to; i++) {
+            const line = `${String(i).padStart(width)}  ${lines[i - 1]}\n`;
+            if (body.length + line.length > READ_MAX_CHARS && i > from)
+                break;
+            body += line;
+            last = i;
+        }
+        const head = `${p}: lines ${from}-${last} of ${total}`;
+        const more = last < to ? `\n[stopped at line ${last} to stay under ${READ_MAX_CHARS} chars; read on with "start_line": ${last + 1}]` : "";
+        return `${head}\n${body}${more}`;
+    }
     editFile(p, old, replacement) {
         const r = this.exec(["cat", "--", p]);
         if (!r.ok)
             return `error: ${r.out.trim()}`;
         const n = countOccurrences(r.out, old);
-        if (n !== 1)
-            return `error: the old text occurs ${n} times in ${p}; it must occur exactly once`;
+        if (n > 1)
+            return `error: the old text occurs ${n} times in ${p}; it must occur exactly once (include more of the surrounding lines)`;
+        if (n === 0)
+            return `error: the old text occurs 0 times in ${p}; it must occur exactly once${editHint(r.out, old)}`;
         const w = this.exec(["sh", "-c", 'cat > "$1"', "sh", p], undefined, r.out.replace(old, () => replacement));
         return w.ok ? `edited ${p}` : `error: ${w.out.trim()}`;
     }
 }
+/**
+ * Why an edit's old text may not have matched, for the error message: the commonest cause is a backslash
+ * sequence in the code (a \\n inside a string) written in JSON as a real line break or tab; otherwise the
+ * file's lines that come closest to the old text's first line, so the agent can copy them exactly.
+ */
+export function editHint(text, old) {
+    const unescaped = old.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+    for (const candidate of [old.replace(/\t/g, "\\t"), unescaped]) {
+        if (candidate !== old && countOccurrences(text, candidate) === 1) {
+            return ". It would match if a line break or tab inside the old text were the two characters \\n or \\t, as the file has them: in JSON, write a backslash in the code as \\\\ (\\n in the code is \"\\\\n\")";
+        }
+    }
+    const first = old.split("\n").map((l) => l.trim()).find((l) => l.length >= 3);
+    if (!first)
+        return "";
+    const lines = text.split("\n");
+    const words = first.split(/\W+/).filter((w) => w.length >= 3);
+    const scored = lines.map((l, i) => {
+        const t = l.trim();
+        const score = t === first ? 1000 : t.includes(first) ? 500 : words.filter((w) => t.includes(w)).length;
+        return { i, l, score };
+    }).filter((x) => x.score > 0 && (x.score >= 500 || x.score >= Math.max(2, Math.ceil(words.length / 2))));
+    scored.sort((a, b) => b.score - a.score || a.i - b.i);
+    if (!scored.length)
+        return "";
+    const shown = scored.slice(0, 3).sort((a, b) => a.i - b.i).map((x) => `${x.i + 1}: ${x.l}`).join("\n");
+    return `. The file's lines closest to the old text's first line (copy the old text exactly, including indentation; read_file shows the lines around them):\n${shown}`;
+}
 /** spawnSync wrapper returning stdout (plus stderr on failure). */
 export function execLocal(cmd, args, opts) {
     const p = spawnSync(cmd, args, { ...opts, encoding: "utf8", maxBuffer: 64 << 20 });

package/dist/suite.js

@@ -91,8 +91,8 @@ export async function runBatch(name, tasks, repeat, base) {
                 const out = await runTask({ ...base, task: t.task, taskName: repeat > 1 ? `${t.taskName}-r${rep}` : t.taskName,
                     taskSource: t.taskSource, runsDir: batchDir });
                 rows.push(rowFor(t.taskName, rep, batchDir, out.runDir, out.summary));
-                if (out.summary.stop_reason === "interrupted") {
-                    console.log("\nRun interrupted; skipping the remaining runs.");
+                if (out.summary.stop_reason === "interrupted" || out.summary.stop_reason === "aborted") {
+                    console.log(`\nRun ${out.summary.stop_reason}; skipping the remaining runs.`);
                     stopped = true;
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magland/gentl",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A readability test for codebases: a memoryless agent carries out a newcomer task and gentl measures how much it had to read.",
   "license": "Apache-2.0",
   "author": "Jeremy Magland",
@@ -32,7 +32,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\" && tsc",
+    "build": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\" && tsc && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
     "prepare": "npm run build"
   },
   "dependencies": {