chamba 0.6.0 → 0.7.0

package/templates/webterm/server.js

@@ -6,7 +6,7 @@
 // The window renders the live TUI (xterm.js) and forwards keystrokes; a rich composer uploads
 // pasted images to /tmp/uploads and injects the composed message as one bracketed paste.
 // Sessions belong to the server, not to the socket: see sessions.js for what that buys.
-// Every route that carries the relay is gated by the key the URL holds (?k=), minted fresh at every start.
+// Every route that carries the relay is gated by the key the URL holds (?k=), created fresh at every start.
 // Auth and sandbox are inherited: the spawned CLI sees the same agent config dirs and the same
 // container isolation it has in the terminal. Nothing here touches credentials.
 
@@ -46,7 +46,11 @@ import {
     MAX_PANE_BYTES,
     MAX_PANE_FILES,
     MAX_SESSIONS,
+    MAX_SPECS_BYTES,
+    MAX_SPECS_LINE_LENGTH,
+    MAX_SPECS_LINES_PER_SESSION,
     MAX_UPLOAD_BYTES,
+    PANE_APPS_CLIENT_DIR,
     PANE_DIR,
     PANE_SCAN_MS,
     PASTE_END,
@@ -54,6 +58,11 @@ import {
     PORT,
     RESUME_STAMP,
     resolveWorkspacePath,
+    SPECS_KEY,
+    SPECS_LINE_MIN_INTERVAL_MS,
+    SPECS_NEW_SESSION_DELAY_MS,
+    SPECS_RAW_TOKEN,
+    SPECS_ROOT,
     STATE_FILE,
     STATUS_SCAN_MS,
     STOP_ANNOUNCE_MS,
@@ -72,6 +81,9 @@ import { isSelfOrDescendant, processStart } from "./proc.js";
 import { resumeArgvFor } from "./resume.js";
 import { createRegistry, WORK_TICK_MS } from "./sessions.js";
 import { statusFor, writesSnapshots } from "./snapshot.js";
+import { CLIENT_PREFIX, createSpecsModule, mountSpecs, SPECS_AGENT_PATH, SPECS_KEYS_PATH, SPECS_PREFIX } from "./specs.js";
+import { documentPolicy, toolDocumentFor, withNonce } from "./tool-document.js";
+import { framedLine, reduceLine } from "./typed-line.js";
 
 // node-pty is a native CommonJS addon; load it through createRequire under ESM.
 const require = createRequire(import.meta.url);
@@ -176,7 +188,7 @@ function publishAgent() {
  * The directories the picker offers. Bounded on purpose (see DIR_SCAN_* in config.js): a deep walk of a
  * real workspace is slow and the list would be unreadable anyway. Dot directories and the skip list are
  * never descended into, and neither are symlinks - a link out of the workspace would list paths that the
- * picker then refuses. Breadth-first, so a cap that bites drops the deepest entries rather than a whole
+ * picker then refuses. Breadth-first, so a limit that bites drops the deepest entries rather than a whole
  * branch, and it reports the cut so the caller can say the list is partial.
  */
 function scanDirs() {
@@ -213,7 +225,7 @@ function scanDirs() {
 // --- The key gate ------------------------------------------------------------------------------------------------------------------------
 
 // Publish the live key where the things that print the URL can read it: the `webterm` launcher, the
-// container greeting, and chamba on the host before it probes /status. Called once the port is bound and
+// container greeting, and chamba on the host before it checks /status. Called once the port is bound and
 // never before - a second server that loses the bind must not leave its key behind as if it had won.
 // Owner-only, and chmod'ed after the write because the mode above applies to a file being created rather
 // than to one that already exists.
@@ -346,8 +358,66 @@ app.use("/vendor/xterm", express.static(join(import.meta.dirname, "node_modules"
 app.use("/vendor/xterm", express.static(join(import.meta.dirname, "node_modules", "@xterm", "xterm", "lib")));
 app.use("/vendor/xterm-fit", express.static(join(import.meta.dirname, "node_modules", "@xterm", "addon-fit", "lib")));
 
+// The pane's tool clients, built elsewhere and baked beside this directory. Open like the statics above, and
+// CORS-readable on top of it: a tool renders in a frame with an opaque origin, so it fetches its own module
+// scripts cross-origin and a browser will not run them without being told they may be read. Nothing here is
+// secret and nothing here drives anything - the data behind a tool is gated separately, in specs.js.
+//
+// `frame-ancestors` is the one thing that is not open. A tool's document is only ever framed by this
+// interface, and framed by it inside a sandbox; a page somewhere else could otherwise frame the same document
+// without one and run it as an ordinary document on this origin.
+//
+// The document of a tool is served ahead of the statics, under a policy of its own: it is the one file here
+// that runs anything, and the frame it runs in has an opaque origin, where a policy written with `'self'`
+// names nobody. See tool-document.js.
+// Which origin the policy names has to come from the request. The browser reaches this server through a
+// port the host published, and the container is not told which one, so `Host` is the only place the origin
+// the document actually loaded from is written down. That makes it the caller's word, and it goes into a
+// response header, so it is taken only in the shape an authority has: a host and an optional port, and
+// nothing that could end the header or name a scheme. Anything else falls back to the address inside the
+// container, which names no outside origin and so grants nothing.
+const AUTHORITY = /^[A-Za-z0-9._-]+(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+
+function originOf(req) {
+    const host = req.get("host") ?? "";
+    return AUTHORITY.test(host) ? `http://${host}` : `http://127.0.0.1:${PORT}`;
+}
+
+// The wildcard is express 4's, which is what this directory's package.json pins. Express 5 spells the same
+// thing `/*splat`, and that spelling compiles here to a route that ends in the literal word - it matches
+// nothing anyone loads, and the document falls through to the statics below with no policy on it at all.
+// The failure is silent, which is why a test issues a real request through a real express instead of
+// reading this line.
+app.get(`${CLIENT_PREFIX}/*`, (req, res, next) => {
+    const document = toolDocumentFor(req.path);
+    if (!document) return next();
+    let html;
+    try {
+        html = readFileSync(join(PANE_APPS_CLIENT_DIR, document), "utf8");
+    } catch {
+        return next();
+    }
+    const nonce = randomBytes(16).toString("base64");
+    res.set("Access-Control-Allow-Origin", "*");
+    res.set("Content-Security-Policy", documentPolicy(nonce, originOf(req)));
+    res.set("X-Content-Type-Options", "nosniff");
+    // A nonce is good for one response, so the document it sits in is never a document to keep.
+    res.set("Cache-Control", "no-store");
+    res.type("html").send(withNonce(html, nonce));
+});
+
+app.use(
+    CLIENT_PREFIX,
+    express.static(PANE_APPS_CLIENT_DIR, {
+        setHeaders: (res) => {
+            res.set("Access-Control-Allow-Origin", "*");
+            res.set("Content-Security-Policy", "frame-ancestors 'self'");
+        },
+    }),
+);
+
 // Accept a raw image body (the client POSTs the pasted/dropped blob with its Content-Type).
-// Reject non-image types up front; cap the size so a bad request cannot fill the disk.
+// Reject non-image types up front; limit the size so a bad request cannot fill the disk.
 app.post("/upload", requireKey, express.raw({ type: () => true, limit: MAX_UPLOAD_BYTES }), (req, res) => {
     const contentType = String(req.headers["content-type"] || "")
         .split(";")[0]
@@ -489,7 +559,14 @@ function paneSessions() {
         const session = registry.get(entry.id);
         const pid = Number(session?.term?.pid);
         if (!session || !Number.isInteger(pid)) continue;
-        live.push({ sid: session.id, agent: session.agent, cwd: session.cwd, pid, since: session.createdAt });
+        live.push({
+            sid: session.id,
+            agent: session.agent,
+            cwd: session.cwd,
+            pid,
+            since: session.createdAt,
+            resumedFrom: resumedBy.get(pid) ?? null,
+        });
     }
     return live;
 }
@@ -542,6 +619,25 @@ function sessionForPid(pid) {
     return null;
 }
 
+// --- The Specs tool ----------------------------------------------------------------------------------------------------------------------
+//
+// The first of the pane's tools, mounted the way the pane store is: something built elsewhere is handed what
+// only this process can give it - where to look, and who to tell when the disk moves - and its answers are
+// registered behind gates it does not hold itself. It is not a process and not a port: a failure inside it is
+// one request answered with a status, and every terminal in this container carries on.
+
+const specs = mountSpecs({
+    module: createSpecsModule({ root: SPECS_ROOT, onChange: (change) => broadcastSpecs(change) }),
+    key: SPECS_KEY,
+    rawToken: SPECS_RAW_TOKEN,
+});
+
+// A spec directory moved. Every window hears it, not one: a spec belongs to the repository rather than to a
+// session, and two windows reading the same spec both need to know.
+function broadcastSpecs(change) {
+    for (const client of clients) send(client, { t: "specs", change });
+}
+
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
 //
 // A claude session's own numbers, above the composer: the model, the context it is holding, what is left of
@@ -799,6 +895,185 @@ function nudge(session, title, path) {
     pasteToSession(session, `[web pane] Feedback submitted on "${quoted}" - read ${homeLabel(path)}`);
 }
 
+// --- Specs routes ------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * The scoped credentials, for the shell alone. It holds the master key already, so nothing new is exposed by
+ * telling it these; what matters is where they go next - the shell posts the key into the tool's frame once,
+ * and the frame presents it as a header. Behind the pane's gate, which is the master key in a header and
+ * never in a URL, because a URL that carries it is a URL a document can read itself out of.
+ */
+app.get(SPECS_KEYS_PATH, requirePaneKey, (_req, res) => {
+    res.json({ key: SPECS_KEY, raw: specs.rawBase });
+});
+
+/**
+ * The `specs` helper's door: the agent's half of the coordination channel.
+ *
+ * The gate is the master key, which every helper route takes and which nothing outside the container has.
+ * The session behind it is a claim rather than a second gate: the helper sends its own pid, this walks up
+ * the process tree to see whether it lands in a session this server started, and any process in the
+ * container could send another process's pid instead - the same rule `webpane` publishes under, and its
+ * docstring says the same of itself. What that buys is a helper run outside a web session getting a clear
+ * answer rather than a silent one, and it is not asked to buy more: the session is used for nothing else,
+ * because a verb moves files in a spec directory, which belongs to the repository rather than to a terminal.
+ */
+app.post(SPECS_AGENT_PATH, requirePaneKey, express.json({ limit: MAX_SPECS_BYTES }), (req, res) => {
+    const session = sessionForPid(Number(req.headers["x-specs-pid"]));
+    if (!session) {
+        res.status(409).json({ error: "not running inside a web session - there is no pane to tell" });
+        return;
+    }
+    const body = req.body && typeof req.body === "object" ? req.body : {};
+    const answer = specs.agent({ verb: body.verb, entry: body.spec, payload: body.payload });
+    res.status(answer.status).json(answer.body);
+});
+
+// The body of a Specs request, read only for a request the mount says may carry one. Reading it is itself
+// something a caller gets to make this process do - hold the bytes, decode them - so it sits behind the same
+// key as the route, rather than in front of it where every other body route in this file would not put it.
+const specsBody = express.text({ type: () => true, limit: MAX_SPECS_BYTES });
+
+/**
+ * Everything else the tool answers. One delegation and no decision: specs.js takes the request as plain data
+ * and gives back the status, the headers and the body, and it never throws, so a Specs failure is a view that
+ * says so rather than a process that went down.
+ */
+app.all(
+    `${SPECS_PREFIX}/*`,
+    (req, res, next) => {
+        if (specs.takesBody(req.method, req.path, req.headers)) specsBody(req, res, next);
+        else next();
+    },
+    (req, res) => {
+        const answer = specs.handle({
+            method: req.method,
+            path: req.path,
+            query: req.query,
+            headers: req.headers,
+            body: req.body,
+        });
+        res.status(answer.status).set(answer.headers);
+        if (answer.body === null) {
+            res.end();
+            return;
+        }
+        // A workspace file goes out as its own bytes, under the type the tool decided; the rest is JSON.
+        if (Buffer.isBuffer(answer.body)) res.send(answer.body);
+        else res.json(answer.body);
+    },
+);
+
+// --- The Specs delivery ------------------------------------------------------------------------------------------------------------------
+//
+// Everything the pane sends the agent lands as a file plus one typed line. The file is written through the
+// data routes above, by the tool; this is the line. It rides the window's own socket, so the session it
+// reaches is the session that window is driving - the tool never names one, and there is no id on the frame
+// for it to name.
+//
+// The words of the line are this server's. The event is a key into the table below, so a tool picks which of
+// a few sentences is typed and never what it says; the detail is the one part that came from somewhere else
+// and is reduced before it goes anywhere near a terminal; and the path has to be a file the tool itself
+// wrote, which the mount decides.
+
+// What a delivery may say it is. A key that is not here is not a delivery.
+const SPECS_EVENTS = {
+    annotations: "Annotations sent",
+    intake: "A new spec was filed",
+    answers: "A round of answers was submitted",
+    gate: "A gate was answered",
+    brief: "Pick up this spec",
+};
+
+// The gap and the total, per session, for as long as this container runs. Held here rather than in the
+// registry because they are about this one channel: a session that is closed and gone takes its count with
+// it, which is the same span the resume marker uses.
+const lastSpecsLine = new Map();
+const specsLineCount = new Map();
+
+/** Whether this session has had as much of this channel as it may have, and why. */
+function specsLimited(sid) {
+    const now = Date.now();
+    if (now - (lastSpecsLine.get(sid) ?? 0) < SPECS_LINE_MIN_INTERVAL_MS) {
+        return "that was just delivered - give it a moment";
+    }
+    if ((specsLineCount.get(sid) ?? 0) >= MAX_SPECS_LINES_PER_SESSION) {
+        return `this session has had the ${MAX_SPECS_LINES_PER_SESSION} deliveries it may have`;
+    }
+    return null;
+}
+
+function specsDelivered(sid) {
+    lastSpecsLine.set(sid, Date.now());
+    specsLineCount.set(sid, (specsLineCount.get(sid) ?? 0) + 1);
+}
+
+/**
+ * Type one Specs line into a session, or say why not.
+ *
+ * The length is checked before the reduction, so an over-limit detail is refused with a reason rather than
+ * cut into half a sentence - which is the one thing a silent trim would make unreadable.
+ *
+ * `after` is for a session this delivery has just started: the line waits for the agent to be there to read
+ * it, and the delivery is answered now, because the session did start and the line will follow.
+ */
+function typeSpecsLine(session, msg, after = 0) {
+    const event = SPECS_EVENTS[typeof msg.event === "string" ? msg.event : ""];
+    if (!event) return { ok: false, error: "that is not something the Specs tool delivers" };
+    const detail = typeof msg.detail === "string" ? msg.detail : "";
+    if (detail.length > MAX_SPECS_LINE_LENGTH) {
+        return { ok: false, error: `that message is longer than the ${MAX_SPECS_LINE_LENGTH} characters a delivery may carry` };
+    }
+    const limited = specsLimited(session.id);
+    if (limited) return { ok: false, error: limited };
+    // A path is optional - a briefing names no file - and one that is not a file this tool wrote is dropped
+    // rather than refused: the line still reads, and it names nothing that is not there.
+    const absolute = msg.path ? specs.fileFor(msg.path) : null;
+    const line = framedLine({
+        tag: "specs",
+        event,
+        detail: reduceLine(detail, MAX_SPECS_LINE_LENGTH),
+        path: absolute === null ? "" : homeLabel(absolute),
+    });
+    specsDelivered(session.id);
+    if (after > 0) {
+        // Only if that session is still there when the wait is over.
+        setTimeout(() => {
+            const still = registry.get(session.id);
+            if (still) pasteToSession(still, line);
+        }, after).unref();
+    } else {
+        pasteToSession(session, line);
+    }
+    console.log(`[webterm] specs: delivered to session "${session.name || session.label}"`);
+    return { ok: true };
+}
+
+/**
+ * A delivery from the Specs tool, arriving over the shell's own socket.
+ *
+ * With no session on this window there is nobody to tell, and the tool has already asked the user whether to
+ * start one: `create` is that answer, and the briefing becomes the first line the new agent reads.
+ */
+function deliverSpecs(ws, msg) {
+    const session = registry.sessionFor(ws);
+    if (session) {
+        send(ws, { t: "specs:delivered", ...typeSpecsLine(session, msg) });
+        return;
+    }
+    if (msg.create !== true) {
+        send(ws, { t: "specs:delivered", ok: false, error: "no-session" });
+        return;
+    }
+    newSession(ws);
+    const started = registry.sessionFor(ws);
+    if (!started) {
+        send(ws, { t: "specs:delivered", ok: false, error: "a session could not be started" });
+        return;
+    }
+    send(ws, { t: "specs:delivered", ...typeSpecsLine(started, msg, SPECS_NEW_SESSION_DELAY_MS) });
+}
+
 // --- Resume, once per container start ----------------------------------------------------------------------------------------------------
 
 // PID 1 is CONTAINER_KEEP_ALIVE, so it starts when the container does and its start time is a different
@@ -865,13 +1140,19 @@ function resumeArgv(agent, cwd) {
 // auth flows through. The first session after a container start continues the most recent conversation;
 // every later session starts fresh, which is what the user wants once mid-work.
 // AGENT_ARGS belong to the agent the launcher named, so any other agent is spawned bare.
+// Which conversation id a session's agent was told to resume, by the PTY leader's pid. Claude gives a
+// resumed conversation a fresh id and records no link back to the old one, so the command built here is the
+// only witness - the pane reads this to carry the old id's pages into the new one. One resume per container
+// start, so this holds at most one entry that matters.
+const resumedBy = new Map();
+
 function spawnAgent({ cwd, agent }) {
     const resume = resumeArgv(agent, cwd);
     const [spawnCmd, ...baseArgs] = resume ?? [agent, ...(agent === DEFAULT_AGENT ? AGENT_ARGS : [])];
     if (resume) console.log(`[webterm] resuming most recent conversation: ${resume.join(" ")}`);
     // Append the browser-awareness flag for claude (fresh or resumed); every other agent is untouched.
     const spawnArgs = agentSpawnArgv(spawnCmd, baseArgs);
-    return pty.spawn(spawnCmd, spawnArgs, {
+    const term = pty.spawn(spawnCmd, spawnArgs, {
         name: "xterm-256color",
         cols: 80,
         rows: 24,
@@ -882,6 +1163,9 @@ function spawnAgent({ cwd, agent }) {
         // var is the one answer all three can read.
         env: { ...process.env, CHAMBA_WEB_SESSION: "1" },
     });
+    // Only a resume-by-id names a conversation to carry pages from; "--continue" style resumes name nothing.
+    if (resume?.[1] === "--resume" && typeof resume[2] === "string") resumedBy.set(term.pid, resume[2]);
+    return term;
 }
 
 // --- Frames from a window ----------------------------------------------------------------------------------------------------------------
@@ -1021,7 +1305,7 @@ function handleFrame(ws, msg) {
             greet(ws, sid, msg.fresh === true);
             return;
         case "ping":
-            // Liveness probe from a window that just woke up: an answer proves the socket really works,
+            // Liveness check from a window that just woke up: an answer proves the socket really works,
             // so it can reconnect at once instead of waiting for TCP to give up.
             send(ws, { t: "pong" });
             return;
@@ -1094,6 +1378,11 @@ function handleFrame(ws, msg) {
         case "paste":
             if (typeof msg.data === "string") paste(ws, msg.data);
             return;
+        case "specs:deliver":
+            // The pane's tool telling the agent something arrived. Like the pane's own frames, it reaches
+            // the session this window is driving, and the frame carries no id for it to reach another.
+            deliverSpecs(ws, msg);
+            return;
         case "resize":
             resize(ws, msg.cols, msg.rows);
             return;
@@ -1141,16 +1430,16 @@ setInterval(checkUploads, CHECK_INTERVAL_MS).unref();
 // actually changed.
 setInterval(() => registry.tick(), WORK_TICK_MS).unref();
 
-// The pane's own sweep, on the same principle: one pass over the live sessions asks the two questions that
+// The pane's own scan, on the same principle: one pass over the live sessions asks the two questions that
 // are about time rather than about an event - has this agent written down which conversation it is having
 // yet, and has anything been written into its pane directory that did not come through the publish route.
 setInterval(() => pane.sweep(), PANE_SCAN_MS).unref();
 
-// The strip's sweep, for the same reason: a snapshot file is written by a shell script into a bind mount, so
+// The strip's scan, for the same reason: a snapshot file is written by a shell script into a bind mount, so
 // the only way to know it moved is to look.
 setInterval(() => sweepStatus(), STATUS_SCAN_MS).unref();
 
-// Keepalive sweep. A window that stops answering is terminated, which releases the session it was
+// Keepalive pass. A window that stops answering is terminated, which releases the session it was
 // driving so the window that comes back can pick it up without a takeover prompt. Sessions themselves
 // are never touched here - a dead socket says nothing about whether a conversation is worth keeping.
 setInterval(() => {
@@ -1185,7 +1474,7 @@ server.listen(PORT, "0.0.0.0", () => {
     if (defaultCwdRefused) {
         console.warn(`[webterm] ignored WEBTERM_CWD="${WEBTERM_CWD_RAW}": not a directory inside ${WORKSPACE_ROOT}`);
     }
-    // Publish the default agent for the `webterm` launcher: a port probe proves something is listening, not
+    // Publish the default agent for the `webterm` launcher: a port check proves something is listening, not
     // what it runs. Written after listen so the file only exists once the port is really bound.
     publishAgent();
 });

package/templates/webterm/sessions.js

@@ -88,7 +88,7 @@ export const WORK_TICK_MS = 300;
 export const MAX_NAME_LENGTH = 40;
 
 // Turn a raw name from the client into what gets stored: control characters (newlines, tabs, the lot)
-// stripped so a name is always one clean line, trimmed, and cut to the cap. An empty result means
+// stripped so a name is always one clean line, trimmed, and cut to the length limit. An empty result means
 // "no name" - the session falls back to its default label. Filtering by code point rather than a regex
 // keeps the source free of literal control characters.
 export function cleanName(raw) {
@@ -115,8 +115,8 @@ function isOpen(socket) {
  * Create the session registry.
  *
  * - `spawn({ cwd })` returns a PTY-like object: { onData, onExit, write, resize, kill }.
- * - `maxSessions` caps how many agents may be alive at once. This is about memory, not correctness.
- * - `maxBuffer` caps the replay buffer kept per session (bytes).
+ * - `maxSessions` limits how many agents may be alive at once. This is about memory, not correctness.
+ * - `maxBuffer` limits the replay buffer kept per session (bytes).
  * - `onEvent(event)` is called with { t: "replay" | "out" | "taken" | "exit" | "changed", ... }.
  *   Events that target one window carry that window's socket as `client`; "changed" means the session
  *   list moved and every window needs to hear about it.
@@ -305,9 +305,9 @@ export function createRegistry({ spawn, maxSessions, maxBuffer, onEvent }) {
     /**
      * Move every session's working state on by one step, and raise the alert on the ones that just stopped.
      * Called on a timer by the server rather than driven by a timer per session: the state is a function of
-     * "how long output has been running", so one sweep answers it for every session, and a registry with no
+     * "how long output has been running", so one pass answers it for every session, and a registry with no
      * timers of its own stays testable by calling this by hand. Every flip is announced here, so the whole
-     * sweep costs at most one broadcast however many sessions moved.
+     * pass costs at most one broadcast however many sessions moved.
      *
      * Every ending raises the alert, whoever is watching and whatever they were doing a moment ago. Whether it
      * is also worth a sound is settled afterwards, by whether anyone touches the session - see "Are you there?".
@@ -372,7 +372,7 @@ export function createRegistry({ spawn, maxSessions, maxBuffer, onEvent }) {
      * and how one is written for the browser belong to the server, and the registry only carries the values -
      * the command and path to the PTY, the labels to the bar.
      *
-     * { ok: true, session } or { ok: false, error: "cap" } when the limit is reached.
+     * { ok: true, session }, or a refusal with the session-limit error code when the limit is reached.
      */
     function create({ cwd, cwdLabel, agent } = {}) {
         if (sessions.size >= maxSessions) return { ok: false, error: "cap" };
@@ -384,7 +384,7 @@ export function createRegistry({ spawn, maxSessions, maxBuffer, onEvent }) {
             // Named after what it runs, since the bar can hold several different agents at once.
             label: `${agent} ${seq}`,
             // A user-chosen label, or null to fall back to `label`. The number in `label` is always kept,
-            // so clearing the name shows "claude 7" again and the tooltip can still surface it.
+            // so clearing the name shows "claude 7" again and the tooltip can still show it.
             name: null,
             agent,
             colorIndex: (seq - 1) % PALETTE_SIZE,

package/templates/webterm/snapshot.js

@@ -28,7 +28,7 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isSameProcess, isSelfOrDescendant } from "./proc.js";
 
-// The largest a snapshot can be and still be read. The script writes a few hundred bytes; the cap only keeps
+// The largest a snapshot can be and still be read. The script writes a few hundred bytes; the limit only keeps
 // an unrelated file that happens to sit in the directory from being pulled into memory.
 const MAX_SNAPSHOT_BYTES = 64 * 1024;
 
@@ -45,7 +45,7 @@ export function writesSnapshots(agent) {
     return agent === "claude";
 }
 
-/** The snapshot files in `dir`, newest first and capped. A directory that is not there contributes nothing. */
+/** The snapshot files in `dir`, newest first and limited in number. A directory that is not there contributes nothing. */
 function snapshotFiles(dir) {
     let entries;
     try {