ucode-agent 1.56.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.56.0",
+  "version": "1.58.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA, Cohere and Nex AGI models.",
   "type": "module",
   "main": "ucode.js",

package/src/core/loop.js

@@ -13,6 +13,7 @@
 
 import path from 'node:path';
 import os from 'node:os';
+import { pathToFileURL } from 'node:url';
 import { appendFileSync, existsSync } from 'node:fs';
 import { readFile, readdir, access, mkdir } from 'node:fs/promises';
 import { testRunnerFor, relatedCommand, summariseFailures } from './tests.js';
@@ -306,6 +307,9 @@ export function lean(messages, keep = 3) {
   });
 }
 
+/** One spelling per file for the read counts: "./a/b.js", "a\b.js" and "a/b.js" are one file. */
+const fileKey = (p) => { const k = path.normalize(String(p)).split(path.sep).join('/'); return process.platform === 'win32' || process.platform === 'darwin' ? k.toLowerCase() : k; };
+
 /** Tools that write whole files, whose sizes are remembered for the turn. */
 const WHOLE_WRITES = new Set(['write_file', 'batch_write', 'create_app']);
 
@@ -781,8 +785,9 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '  Next.js, Vite, anything with an npm run dev - start it and leave it up when you',
     '  finish. ucode opens it in the browser for the user as soon as it is ready, so a',
     '  build that ends with the server stopped ends with nothing to look at. A one-page',
-    '  app with no server needs none of this: the file is the app.',
-    '  name, handles keys and returns the live link. Build locally first.',
+    '  app with no server needs none of this: the file is the app. Write all of it in',
+    '  create_app\'s files, then stop: ucode opens the page itself and hands it to the',
+    '  user the moment it works. Do not start a server, curl it or re-read it to check.',
     '- Nothing you run has a keyboard. Pass the non-interactive flag to anything that',
     '  would ask a question, or it fails instead of waiting: create-next-app --yes,',
     '  npx shadcn@latest init -d -y, npx shadcn@latest add <names> -y, npm init -y.',
@@ -1181,13 +1186,9 @@ export class Agent {
       const message = skillMessage(skill, { automatic: true, short: true });
       this.loaded.add(skill.name);
       if (message.short) this.short.add(skill.name);
+      // Nothing on screen: which rules the model was handed is bookkeeping,
+      // and the only text a build should leave is the answer at the end.
       this.push(message);
-      this.ui.note(`${skill.name} skill loaded for this${message.short ? ' (short form)' : ''}`);
-      // A clear row under it. This is bookkeeping about the turn, not part of
-      // it, and against the first line of thinking the two read as one block —
-      // the notice looks like the opening of the answer rather than a note
-      // about how the answer is being reached.
-      this.ui.blank();
     }
   }
 
@@ -1196,6 +1197,10 @@ export class Agent {
     // /undo can put the whole turn back.
     beginTurn();
     this.lookedThisTurn = false;
+    this.lookAgain = null;
+    this.handOverPending = false;
+    this.appName = null;
+    this.appTemplate = null;
     this.reads = new Map();
     this.declines = 0;
     this.apps = [];
@@ -1203,6 +1208,11 @@ export class Agent {
     forgetReviews(); // a new request: its apps get a fresh design review
     setRequest(input); // create_app checks this before choosing a starter
     const images = await this.attachImages(input);
+    // The skill goes in ahead of the request, so the request is the last
+    // thing the model reads. After it, a page of house rules was what the
+    // model answered: asked for a dark mode toggle on its second turn, a live
+    // run re-read two files and repeated its first turn's summary instead.
+    this.autoLoad(input);
     this.push(images.length
       ? { role: 'user', content: input, images }
       : { role: 'user', content: input });
@@ -1210,8 +1220,6 @@ export class Agent {
     if (!this.session.title || this.session.title === 'Untitled') {
       this.session.title = titleFrom(input);
     }
-
-    this.autoLoad(input);
     // What the model is told about the project, fresh for this turn.
     [this.map, this.memory] = await Promise.all([
       projectMap(this.cwd).catch(() => ''),
@@ -1552,6 +1560,24 @@ export class Agent {
       const badArgs = await this.runCalls(reply.toolCalls);
       if (this.abort.signal.aborted) return;
 
+      // The app is written: see whether it works, and if it does, that is the
+      // answer. Waiting for the model to decide it is finished was most of the
+      // time a build took (see handOver).
+      const handed = badArgs ? null : await this.handOver(reply.toolCalls);
+      if (handed?.done) return;
+      if (handed?.problems && fixRounds < MAX_FIX_ROUNDS) {
+        fixRounds++;
+        this.push({
+          role: 'user',
+          content:
+            `ucode opened the app and found errors (round ${fixRounds} of ${MAX_FIX_ROUNDS}). Fix all ` +
+            'of them with the smallest edits that do it. Change nothing else. As soon as it works, ' +
+            `ucode hands it to the user.\n\n${handed.problems}`,
+        });
+        await this.persist();
+        continue;
+      }
+
       // Malformed arguments go back to the model, but only so many times.
       if (badArgs) {
         argRetries++;
@@ -1613,7 +1639,7 @@ export class Agent {
 
       const noted = (call) => {
         if (FILE_WRITES.has(call.name)) {
-          for (const p of pathsOf(call)) { this.touched.add(p); this.sinceCheck.add(p); }
+          for (const p of pathsOf(call)) { this.touched.add(p); this.sinceCheck.add(p); this.forgetReads(p); }
         }
         if (call.name === 'run_command' || call.name === 'run_commands') this.ranSomething = true;
       };
@@ -1791,6 +1817,8 @@ export class Agent {
     if (call.name === 'create_app' && call.args?.folder) {
       const made = path.resolve(this.cwd, String(call.args.folder));
       if (!(this.apps ??= []).includes(made)) this.apps.push(made);
+      if (call.args.name) this.appName = String(call.args.name);
+      this.appTemplate = String(call.args.template || 'plain-html');
     }
 
     if (call.name === 'look_at_app') {
@@ -1882,7 +1910,7 @@ export class Agent {
       .map((f) => ({ abs: path.resolve(this.cwd, f.path), size: f.content.length, path: f.path }));
   }
 
-  async dispatch(call) {
+  async dispatch(call, offered = this.offering) {
     // The model emitted arguments that were not valid JSON. Hand the parser's
     // own complaint straight back so it can correct itself next step.
     if (call.parseError) {
@@ -1899,12 +1927,13 @@ export class Agent {
     // tool that writes, and a new project is not sent the ones that look code
     // up — and a model naming one from memory was, until this check, executing
     // it. A withheld tool has to be refused, not just left out of the menu.
-    if (!this.offering?.has(call.name)) {
+    // A worker is checked against its own, narrower list, not the lead's.
+    if (!offered?.has(call.name)) {
       throw new ToolFailure({
         kind: 'no_such_tool',
         attempted: `calling ${call.name}`,
         failed: `${call.name} is not available${this.ui.mode === 'plan' ? ' in plan mode' : ' in this project'}.`,
-        fix: `Use one of the tools you were given: ${[...this.offering ?? []].join(', ')}.`,
+        fix: `Use one of the tools you were given: ${[...offered ?? []].join(', ')}.`,
       });
     }
 
@@ -1921,14 +1950,24 @@ export class Agent {
     // usually a fair re-check after an edit. Only the third is a loop. And it
     // is keyed on the file being untouched since — the moment anything writes
     // to it, the count starts again and a real re-read goes through.
+    //
+    // Counted per page, not per file: paging through a long file with offset
+    // is new text every time, and a live run was refused four pages in a row
+    // of a 900-line file it had only ever seen the start of.
+    //
+    // A write starts the count again (forgetReads). It used to be skipped only
+    // while the file sat in sinceCheck, which the checks empty every fix round:
+    // after round one, every read of a file the model had just edited was
+    // refused as "unchanged", and a live build spent sixty steps being told so.
     if (call.name === 'read_file' && call.args?.path) {
-      const key = String(call.args.path);
+      const file = String(call.args.path);
+      const key = `${fileKey(file)}#${Number(call.args.offset) || 1}:${Number(call.args.limit) || 0}`;
       const seen = (this.reads ??= new Map()).get(key) ?? 0;
-      if (seen >= 2 && !this.sinceCheck?.has(key)) {
+      if (seen >= 2) {
         this.reads.set(key, seen + 1);
         return {
-          content: `You have already read ${key} ${seen} times this turn and nothing has written to it since, ` +
-          'so its contents are unchanged and already above. Use what is there. If you need a part ' +
+          content: `You have already read that part of ${file} ${seen} times this turn and nothing has written ` +
+          'to it since, so it is unchanged and already above. Use what is there. If you need a part ' +
           'you have lost, say which and read the files you still need together in one read_files.',
           summary: 'unchanged since you last read it',
         };
@@ -2031,9 +2070,9 @@ export class Agent {
   }
 
   /** Run a call and settle to { out } or { err } — never throws. */
-  execute(call) {
+  execute(call, offered = this.offering) {
     const started = Date.now();
-    return this.dispatch(call).then(
+    return this.dispatch(call, offered).then(
       (out) => { trace({ kind: 'tool', name: call.name, ms: Date.now() - started }); countTool(this.stats, call, out); return { out }; },
       (err) => { trace({ kind: 'tool', name: call.name, ms: Date.now() - started, err: err?.kind }); countTool(this.stats, call, null, err); return { err }; }
     );
@@ -2048,6 +2087,12 @@ export class Agent {
     return { content: `Plan updated: ${done} of ${list.length} done.`, summary: `${done}/${list.length}` };
   }
 
+  /** A file was written: every page of it read so far is news again. */
+  forgetReads(file) {
+    const prefix = `${fileKey(file)}#`;
+    for (const key of this.reads?.keys() ?? []) if (key.startsWith(prefix)) this.reads.delete(key);
+  }
+
   /** File writes from parallel workers take turns, so two never interleave. */
   fileLock(fn) {
     const run = (this.lockChain ?? Promise.resolve()).then(fn, fn);
@@ -2079,7 +2124,7 @@ export class Agent {
       touched: [],
     }))));
 
-    for (const r of results) for (const f of r.touched) { this.touched.add(f); this.sinceCheck.add(f); }
+    for (const r of results) for (const f of r.touched) { this.touched.add(f); this.sinceCheck.add(f); this.forgetReads(f); }
 
     // A worker that wrote nothing has not done its part, whatever it said.
     // The lead builds those itself rather than leaving holes in the app.
@@ -2111,6 +2156,7 @@ export class Agent {
       { role: 'user', content: String(task.instructions) },
     ];
     const available = this.toolsNow().filter((t) => !WORKER_EXCLUDED.has(t.name));
+    const offered = new Set(available.map((t) => t.name));
     const wanted = process.env.UCODE_WORKER_MODEL;
     let workerModel = wanted && MODELS[wanted] ? wanted : model();
     const tried = new Set([workerModel]);
@@ -2172,8 +2218,8 @@ export class Agent {
         const exclusive =
           FILE_WRITES.has(call.name) || call.name === 'run_command' || call.name === 'run_commands';
         const { out, err } = exclusive
-          ? await this.fileLock(() => this.execute(call))
-          : await this.execute(call);
+          ? await this.fileLock(() => this.execute(call, offered))
+          : await this.execute(call, offered);
         if (err) {
           if (!(err instanceof ToolFailure)) throw err;
           this.ui.toolFailed(`${name}: ${err.kind}: ${err.failed}`);
@@ -2430,12 +2476,97 @@ export class Agent {
    * Never throws. A browser that will not start is a reason to skip the look,
    * never a reason to fail the turn that built the app.
    */
-  async lookOnceThisTurn(root, changed) {
-    if (this.lookedThisTurn) return null;
+  /**
+   * Hand a plain-page app over the moment it works.
+   *
+   * Traced: a tip calculator was on disk and complete 60 seconds in, and the
+   * turn ran to 270 — re-reading the files it had just written, starting
+   * servers to look at a page that needs none, rewriting it to "verify". The
+   * user waited three and a half minutes for an app that was already there.
+   *
+   * So right after a step that writes the app — create_app with its files, a
+   * batch of files, or any write while earlier problems are being fixed —
+   * ucode opens the page itself. No console errors, no failed requests, and
+   * it responds when used: the turn ends there with where to find it. If it
+   * is broken, the problems go straight back, and the next write checks again.
+   * Plain pages only: a framework app is checked when the model says it is
+   * done, since its build and server take their own time.
+   *
+   * Returns { done: true }, { problems }, or null when there was nothing to check.
+   */
+  async handOver(calls) {
+    if (this.ui.mode === 'plan' || !this.apps?.length) return null;
+    const app = this.apps.at(-1);
+    // Plain by the starter it came from, not by what is in the folder: a model
+    // that adds a package.json to a one-page app still made a one-page app, and
+    // judging by the file sent a stopwatch on a 22-step, six-minute detour.
+    if (this.appTemplate !== 'plain-html' || !(await exists(path.join(app, 'index.html')))) return null;
+
+    const inApp = (p) => {
+      const rel = path.relative(app, path.resolve(this.cwd, String(p)));
+      return !rel.startsWith('..') && !path.isAbsolute(rel);
+    };
+    const writes = calls.filter((c) => FILE_WRITES.has(c.name) && pathsOf(c).some(inApp));
+    const whole = writes.some((c) => (c.name === 'create_app' || c.name === 'batch_write') && pathsOf(c).length > 0);
+    if (!writes.length || (!whole && !this.handOverPending)) return null;
+
+    const show = path.relative(this.cwd, app).split(path.sep).join('/') || '.';
+    let out;
+    try {
+      const { lookAtApp, withStaticServer } = await import('../tools/browser.js');
+      this.ui.startSpinner(`opening ${show} to check it works`);
+      out = await withStaticServer(app, (url) => lookAtApp({ url, review: false }));
+    } catch {
+      return null; // no browser: the check at the end of the turn still runs
+    } finally {
+      this.ui.stopSpinner();
+    }
 
-    const pages = [...changed].filter((f) => PAGE.test(f));
+    const content = String(out?.content ?? '');
+    if (/Console errors|Failed requests|NOTHING HAPPENS|does not parse/i.test(content)) {
+      this.handOverPending = true;
+      this.ui.runStat?.('needs a fix');
+      return { problems: `I opened the app and looked at it:\n\n${content}` };
+    }
+
+    this.handOverPending = false;
+    // "Tip Calculator is done", with the page as a link the terminal can open.
+    const made = calls.find((c) => c.name === 'create_app' && c.args?.name)?.args.name ?? this.appName;
+    const name = String(made ?? path.basename(app)).trim();
+    this.appName = name;
+    const link = pathToFileURL(path.join(app, 'index.html')).href;
+    const text = `${name} is done. Open it here: ${link}\n\n(or open \`${show}/index.html\` in your browser)`;
+    this.push({ role: 'assistant', content: text });
+    this.ui.assistant(text, { closing: true });
+    await this.persist();
+    return { done: true };
+  }
+
+  async lookOnceThisTurn(root, changed) {
+    // A look that found problems is taken again after the fix round, even if
+    // the fix only touched the page's script. Looking once a turn let a live
+    // build report "Failed to load module script" on its first look, fail to
+    // fix it, and finish as done with a page whose script never ran — nothing
+    // opened the page again. The fix rounds bound how often this repeats.
+    const again = this.lookAgain;
+    if (this.lookedThisTurn && !again) return null;
+
+    let pages = [...changed].filter((f) => PAGE.test(f));
+    // A plain page's script changed and its index.html did not — the usual
+    // shape of a build on the HTML starter, whose page comes from the starter
+    // while the model writes app.js. The page is still the thing to open: a
+    // live build whose "Add" button threw on every click finished as done
+    // because nothing with .html in its name had changed, so nobody looked.
+    if (!pages.length) {
+      for (const f of changed) {
+        const page = path.join(path.dirname(f), 'index.html');
+        if (/\.m?js$/i.test(f) && (await exists(path.resolve(root, page)))) { pages = [page]; break; }
+      }
+    }
+    if (!pages.length && again) pages = [again];
     if (!pages.length) return null;
     this.lookedThisTurn = true;
+    this.lookAgain = null;
 
     try {
       const { lookAtApp, withStaticServer } = await import('../tools/browser.js');
@@ -2448,6 +2579,7 @@ export class Agent {
         const out = await lookAtApp({ url, review: false });
         const found = /^(\d+) problem/.exec(out.summary ?? '');
         this.ui.runStat?.(found ? `${found[1]} to fix` : 'clean');
+        if (found) this.lookAgain = pages.find((f) => /\.html?$/i.test(f)) ?? pages[0];
         return found ? `I opened the app and looked at it:\n\n${out.content}` : null;
       };
 

package/src/core/skills.js

@@ -172,7 +172,7 @@ export function autoLoadFor(skills, text) {
 export function skillMessage(skill, { automatic = false, short = false } = {}) {
   const digest = short && skill.digest ? skill.digest : null;
   const why = automatic
-    ? `The "${skill.name}" skill was loaded automatically because this request is the kind it covers.`
+    ? `The "${skill.name}" skill was loaded automatically because the request that follows is the kind it covers.`
     : `The "${skill.name}" skill was loaded for this task.`;
   return {
     role: 'system',

package/src/tools/files.js

@@ -7,14 +7,14 @@
  * coding agent can do, because everything after it is built on a lie.
  */
 
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync } from 'node:fs';
 import { remember } from '../core/undo.js';
 import path from 'node:path';
 import { ToolFailure } from '../core/failure.js';
 import {
   resolveIn, guard, result, fsFailure, looksBinary, toLines, bytes,
   changedRegion, renderDiff, renderNewFile, READ_LINES, MAX_FILE_OUTPUT,
-  noteFile, writeTracked, assertUnchanged,
+  noteFile, writeTracked, assertUnchanged, getRoot,
 } from './shared.js';
 import { packageJsonWritten } from './shell.js';
 import { fuzzyReplace } from './fuzzy.js';
@@ -196,6 +196,44 @@ const brokenNote = (show, problem) => {
     `a structure you have lost track of.`;
 };
 
+/**
+ * A module in a page with no build step that imports a stylesheet or an image.
+ *
+ * A bundler would take it; a browser refuses the whole module ("Failed to
+ * load module script ... MIME type text/css"), so none of the app's script
+ * runs and every button is dead. The syntax is fine, so nothing else notices
+ * until the page is opened — a live build shipped exactly this as done.
+ */
+const ASSET_IMPORT = /^[ \t]*import\s+(?:[\w$*{}\s,]+?\s+from\s+)?['"]([^'"]+\.(?:css|scss|sass|less|svg|png|jpe?g|gif|webp))['"](?!\s*(?:with|assert)\s*\{)/m;
+
+export function assetImport(abs, text) {
+  if (!/\.m?js$/i.test(abs)) return null;
+  // An import quoted inside a block comment is not an import.
+  const hit = ASSET_IMPORT.exec(String(text).replace(/\/\*[\s\S]*?\*\//g, ''));
+  if (!hit) return null;
+  // Anything with a package.json above it, up to the project root, may well be
+  // bundled. path.relative, not a string prefix: "ucode2" starts with "ucode",
+  // and Windows paths differ in case from one shell to the next.
+  const top = getRoot();
+  const within = (dir) => {
+    const rel = path.relative(top, dir);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  };
+  for (let dir = path.dirname(abs); ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, 'package.json'))) return null;
+    if (!within(dir) || path.relative(top, dir) === '' || path.dirname(dir) === dir) break;
+  }
+  return `imports ${hit[1]}, which a page with no build step cannot do: the browser refuses the ` +
+    'whole module, so none of its script runs. Remove that import and load it from the page ' +
+    'instead — <link rel="stylesheet" href="…"> for a stylesheet, an <img> or a plain URL for an image.';
+}
+
+/** The note for that, appended to a write's result like a parse problem is. */
+const pageNote = (target, text) => {
+  const problem = assetImport(target.abs, text);
+  return problem ? `\n\n⚠ ${target.show} ${problem}` : '';
+};
+
 /** A file this short comes back whole after an edit; longer ones show the part around the change. */
 const SHOW_WHOLE = 250;
 const AROUND = 15;
@@ -349,6 +387,7 @@ async function put(target, content, { diffMax = 16 } = {}) {
     lineCount,
     diff,
     problem: syntaxProblem(target.abs, content),
+    note: pageNote(target, content),
     line: `${existed ? 'Overwrote' : 'Created'} ${target.show} ` +
       `(${lineCount} lines, ${bytes(Buffer.byteLength(content))})`,
   };
@@ -368,7 +407,7 @@ export async function writeFile({ path: p, content }) {
 
   const written = await put(target, content);
   const out = result(
-    `${written.line}.${parseNote(target.show, written.problem)}`,
+    `${written.line}.${parseNote(target.show, written.problem)}${written.note}`,
     `${written.existed ? 'overwrote' : 'created'} · ${written.lineCount} lines${written.problem ? ' · does not parse' : ''}`
   );
   out.diff = written.diff;
@@ -414,7 +453,7 @@ export async function batchWrite({ files }) {
     // would bury the reply under three hundred lines of gutter.
     const written = await put(target, content, { diffMax: 6 });
     if (!written.existed) created++;
-    lines.push(written.line + parseNote(target.show, written.problem));
+    lines.push(written.line + parseNote(target.show, written.problem) + written.note);
     if (written.problem) broken++;
     diff.push(`~${target.show}`, ...written.diff);
   }
@@ -632,7 +671,7 @@ export async function editFile({ path: p, old_string, new_string, replace_all })
   const span = toLines(new_string).length;
   const out = result(
     `Replaced ${where} (${change}${matched}).` +
-      parseNote(target.show, syntaxProblem(target.abs, text)) +
+      parseNote(target.show, syntaxProblem(target.abs, text)) + pageNote(target, text) +
       nowReads(target.show, text, at, span),
     `${count > 1 ? `${count} changes from line` : '1 change at line'} ${at} · ${change}` +
       `${how ? ' · whitespace-tolerant' : ''}${syntaxProblem(target.abs, text) ? ' · does not parse' : ''}`,
@@ -705,7 +744,7 @@ export async function multiEdit({ path: p, edits }) {
 
   const out = result(
     `Applied ${edits.length} edits to ${target.show} (${change}).` +
-      parseNote(target.show, syntaxProblem(target.abs, text)) +
+      parseNote(target.show, syntaxProblem(target.abs, text)) + pageNote(target, text) +
       nowReads(target.show, text, 1, toLines(text).length),
     `${edits.length} edits · ${change}`,
     MAX_FILE_OUTPUT
@@ -795,7 +834,7 @@ export async function editFiles({ files }) {
     planned.map((p) => {
       const problem = syntaxProblem(p.target.abs, p.text);
       return `Edited ${p.target.show} (${p.count} change${p.count === 1 ? '' : 's'})` +
-        parseNote(p.target.show, problem);
+        parseNote(p.target.show, problem) + pageNote(p.target, p.text);
     }).join('\n'),
     `${planned.length} files · ${edits} edits`
   );

package/src/tools/shared.js

@@ -408,12 +408,19 @@ export const WALK_WIDTH = 32;
  */
 const known = new Map();
 
+/**
+ * One key per file. Windows and macOS do not care about case, so "App.js" and
+ * "app.js" are the same file there — and keyed apart, ucode's own write under
+ * one spelling read as somebody else's edit under the other.
+ */
+const stampKey = (abs) => (process.platform === 'win32' || process.platform === 'darwin' ? abs.toLowerCase() : abs);
+
 /** Record a file as ucode now knows it. Never throws: a missing stamp only costs the check. */
 export async function noteFile(abs) {
   try {
-    known.set(abs, (await fs.stat(abs)).mtimeMs);
+    known.set(stampKey(abs), (await fs.stat(abs)).mtimeMs);
   } catch {
-    known.delete(abs);
+    known.delete(stampKey(abs));
   }
 }
 
@@ -431,7 +438,7 @@ export async function writeTracked(abs, data, encoding = 'utf8') {
 
 /** Forget a file, so the next write to it goes through unchallenged. */
 export function forgetFile(abs) {
-  known.delete(abs);
+  known.delete(stampKey(abs));
 }
 
 /**
@@ -444,7 +451,7 @@ export function forgetFile(abs) {
  * clobber.
  */
 export async function assertUnchanged(abs, show) {
-  const seen = known.get(abs);
+  const seen = known.get(stampKey(abs));
   if (seen === undefined) return;
 
   let now;
@@ -457,7 +464,7 @@ export async function assertUnchanged(abs, show) {
   // costs nothing and stops a same-second write reading as someone else's.
   if (Math.abs(now - seen) < 1) return;
 
-  known.delete(abs);
+  known.delete(stampKey(abs));
   throw new ToolFailure({
     kind: 'changed_on_disk',
     attempted: `overwriting ${show}`,

package/src/tools/shell.js

@@ -14,7 +14,7 @@ import { openSync, closeSync, readFileSync, mkdirSync, statSync } from 'node:fs'
 import os from 'node:os';
 import path from 'node:path';
 import { ToolFailure } from '../core/failure.js';
-import { resolveIn, guard, result, getRoot, MAX_OUTPUT } from './shared.js';
+import { resolveIn, guard, confirm, result, getRoot, MAX_OUTPUT } from './shared.js';
 
 const DEFAULT_TIMEOUT = 120_000;
 const MAX_TIMEOUT = 600_000;
@@ -28,6 +28,19 @@ const LIVE_LINES = 200;
 const LOOKS_LIKE_SERVER =
   /(\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|preview|watch)\b|\b(?:vite|next dev|next start|nuxt dev|astro dev|webpack serve|svelte-kit dev|serve)\b|\buvicorn\b|\bgunicorn\b|\bflask run\b|\bdjango[\w-]* runserver\b|\bmanage\.py runserver\b|\brails server\b|\bhttp\.server\b|\bhttp-server\b|\blive-server\b)/i;
 
+/**
+ * Does some part of this command actually run a server? A segment that only
+ * searches for or lists one does not: `ps aux | grep http-server` was
+ * backgrounded as a server and reported as having died before it was ready.
+ */
+const INSPECTS = /^(?:grep|egrep|findstr|find|ps|echo|cat|type|tasklist|netstat|curl|wget|ls|dir|which|where|head|tail|less|more)\b/i;
+export function startsServer(command) {
+  return String(command).replace(/"[^"]*"|'[^']*'/g, '""').split(/&&|\|\||[;|&]/).some((part) => {
+    const segment = part.trim();
+    return !INSPECTS.test(segment) && LOOKS_LIKE_SERVER.test(segment);
+  });
+}
+
 /** A foreground server that was explicitly asked for still gets a short leash. */
 const SERVER_TIMEOUT = 30_000;
 
@@ -41,6 +54,20 @@ const INSTALL_TIMEOUT = 600_000;
 const LOOKS_LIKE_INSTALL =
   /(\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|ci|create)\b|\bnpx\s+(?:create-|degit\b|shadcn)|\bpip3?\s+install\b|\bpoetry\s+(?:install|add)\b|\bcargo\s+(?:build|install|fetch)\b|\bgo\s+(?:mod\s+download|get)\b|\bbundle\s+install\b|\bcomposer\s+(?:install|require)\b|\bgit\s+clone\b)/i;
 
+/** Opening a file or URL in the desktop browser: start, open, xdg-open, explorer. */
+const OPENS_BROWSER = /^\s*(?:cd\s+[^&;|]+&&\s*)?(?:start(?:\s+"")?|open|xdg-open|explorer(?:\.exe)?|cmd(?:\.exe)?\s+\/c\s+start)\s+\S+\.html?\b|^\s*(?:start|open|xdg-open)\s+https?:\/\//i;
+
+/**
+ * Any kill by program name rather than by process number.
+ *
+ * `taskkill /F /IM python.exe` in a live build ended six Python processes on
+ * the machine, most of them nothing to do with the app. Every process ucode
+ * starts comes back with its PID, so the narrow kill is always available;
+ * the broad one is the user's call, and is asked about.
+ */
+const KILLS_BY_NAME =
+  /(\btaskkill\b[^|;&]*\/IM\b|\b(?:killall|pkill)\b|\b(?:Stop-Process|spps)\b[^|;&]*-(?:N(?:a(?:me?)?)?|ProcessName)\b|\bGet-Process\b[^;&]*\|\s*(?:Stop-Process|spps|kill)\b|\bwmic\b[^|;&]*\bprocess\b[^|;&]*\b(?:delete|call\s+terminate)\b|\bkill\b[^;&]*\$\(\s*pgrep\b|\bpgrep\b[^;&]*\|\s*xargs\s+(?:-\S+\s+)*kill\b)/i;
+
 /**
  * Commands that kill a whole class of process rather than one process.
  *
@@ -73,6 +100,10 @@ const KILLS_EVERYTHING =
  *   NEXT_TELEMETRY      Next skips its telemetry notice and ping
  *   NO_COLOR            output comes back as text rather than escape codes,
  *                       which the model would otherwise have to read past
+ *   PYTHONUNBUFFERED    Python writes as it goes instead of holding output
+ *                       until a buffer fills: `python -m http.server` said
+ *                       "Serving HTTP" to a log that stayed empty, and each
+ *                       start waited out the full 45 seconds as "still starting"
  */
 export function childEnv(base = process.env) {
   return {
@@ -89,6 +120,7 @@ export function childEnv(base = process.env) {
     NEXT_TELEMETRY_DISABLED: '1',
     NO_COLOR: '1',
     FORCE_COLOR: '0',
+    PYTHONUNBUFFERED: '1',
   };
 }
 
@@ -630,13 +662,44 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
     });
   }
 
+  // Opening a page in the user's browser is ucode's job, once the app works.
+  // Run by the model, `start index.html` hands the pipe to the browser, which
+  // never closes it: a live build sat on it for the full two-minute timeout.
+  if (OPENS_BROWSER.test(command)) {
+    return result(
+      'Not run: ucode opens the app for the user itself once it works. There is no need to open it.',
+      'not needed — ucode shows the app',
+    );
+  }
+
+  if (KILLS_BY_NAME.test(command)) {
+    const attempted = `running \`${command.trim().slice(0, 80)}\``;
+    try {
+      await confirm(
+        `stop every matching process: ${command.trim().slice(0, 120)}`,
+        'That kills every process with that name on this computer, not only the ones ucode started.',
+        'command',
+      );
+    } catch (err) {
+      if (err?.kind !== 'cannot_ask') throw err;
+      throw new ToolFailure({
+        kind: 'broad_kill',
+        attempted,
+        failed: 'That kills every process with that name on this computer, not only the ones ucode ' +
+          'started, and there is nobody here to approve it.',
+        fix: 'Stop the one process by its PID: every server ucode starts reports its PID and the exact ' +
+          'command to stop it.',
+      });
+    }
+  }
+
   const workdir = cwd
     ? resolveIn(cwd, 'run_command', 'cwd')
     : { abs: getRoot(), inside: true, show: '.' };
   await guard(workdir, `run a command in ${workdir.abs}`);
 
   const env = childEnv();
-  const server = LOOKS_LIKE_SERVER.test(command);
+  const server = startsServer(command);
 
   // Anything run where a background install is still going waits for it —
   // two installs in one folder corrupt node_modules, and a build before the

package/src/ui/plain.js

@@ -200,11 +200,10 @@ export class Plain {
     if (first.trim()) this.output.write(`\n${blue('›')} ${first}\n`);
   }
 
+  /** Said beside a tool call, so not the answer: it moves the spinner and is not printed. */
   narrate(text) {
     const line = asLabel(text);
-    if (!line) return;
-    this.stopSpinner();
-    this.write(dim(`  ⋮ ${line}`));
+    if (line) this.updateSpinner(line);
   }
 
   progress(lines) {