ucode-agent 1.62.3 → 1.62.5

package/README.md

@@ -27,7 +27,7 @@ corner:
          add a dark mode toggle that remembers the choice
 
 
-                                                                           v1.62.3
+                                                                           v1.62.5
 ```
 
 A light crosses the wordmark once as it opens, and the three lines under the box

package/package.json

@@ -1,63 +1,63 @@
-{
-  "name": "ucode-agent",
-  "version": "1.62.3",
-  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
-  "type": "module",
-  "main": "ucode.js",
-  "bin": {
-    "ucode": "ucode.js"
-  },
-  "files": [
-    "ucode.js",
-    "src/",
-    "skills/",
-    "templates/",
-    "THIRD_PARTY_NOTICES.md"
-  ],
-  "scripts": {
-    "start": "node ucode.js",
-    "test": "node test/run.js",
-    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
-    "hooks": "node scripts/install-hooks.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sppideey/ucode-agent.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sppideey/ucode-agent/issues"
-  },
-  "homepage": "https://github.com/sppideey/ucode-agent#readme",
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "agent",
-    "cli",
-    "terminal",
-    "coding-agent",
-    "llm",
-    "gemini",
-    "google-gemini",
-    "ai"
-  ],
-  "author": "om dixit",
-  "license": "MIT",
-  "dependencies": {
-    "@babel/parser": "^7.29.9",
-    "chalk": "^6.0.0",
-    "dotenv": "^18.0.3",
-    "jsonrepair": "^3.15.0",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "openai": "^7.23.0",
-    "playwright-core": "^1.63.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.2",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "ucode-agent",
+  "version": "1.62.5",
+  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
+  "type": "module",
+  "main": "ucode.js",
+  "bin": {
+    "ucode": "ucode.js"
+  },
+  "files": [
+    "ucode.js",
+    "src/",
+    "skills/",
+    "templates/",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "start": "node ucode.js",
+    "test": "node test/run.js",
+    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
+    "hooks": "node scripts/install-hooks.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sppideey/ucode-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sppideey/ucode-agent/issues"
+  },
+  "homepage": "https://github.com/sppideey/ucode-agent#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "terminal",
+    "coding-agent",
+    "llm",
+    "gemini",
+    "google-gemini",
+    "ai"
+  ],
+  "author": "om dixit",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "chalk": "^6.0.0",
+    "dotenv": "^18.0.3",
+    "jsonrepair": "^3.15.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "openai": "^7.23.0",
+    "playwright-core": "^1.63.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/build-app/DIGEST.md

@@ -1,145 +1,154 @@
-# Building something from nothing — the short form
-
-The failure mode is not bad code. It is a folder of files that has never been
-run, handed over as if it works.
-
-## 1. Decide the shape before any file exists
-
-One line each: **what it does**, **the core loop** (the one path that must work
-perfectly), **the stack**, **the file list**.
-
-| Need | Choose |
-| --- | --- |
-| One page, no secrets, no server | `create_app` with `plain-html` |
-| Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
-| Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
-| An API on its own | Node (Hono/Express) or Python (FastAPI) |
-
-Pick the smallest one that does the job and mean it: a tasks app, a
-calculator, a timer, a game, a visualisation — all one page. Next.js costs an
-install and a build, minutes the user waits through, and buys nothing an app
-with no server needs.
-
-## 2. Start from the starter — and finish in the same call
-
-`create_app` takes `files`, so for a one-page app the scaffold and the whole
-app are one call:
-
-```
-create_app({ folder: "tide", name: "Tide", files: [
-  { path: "tide/index.html", content: "…" },
-  { path: "tide/styles.css", content: "…" },
-  { path: "tide/app.js",     content: "…" },
-]})
-```
-
-Every round trip is ten to forty seconds of the user's time, so one call
-instead of four is most of how long the build takes.
-
-- `plain-html` is the default: three files, no install, no build. Its files
-  come back in full inside the result — **never read them back**.
-- `next-shadcn` installs in the background; commands in that folder wait for
-  it on their own, so start writing components at once. Re-tint `globals.css`
-  for the app's direction rather than shipping the slate default.
-- Never run `create-next-app` or `shadcn init`. Nothing you run has a
-  keyboard: every scaffolder needs its answers as flags up front.
-
-## 2a. Paths in `files` are not the paths in the page
-
-The two are relative to different things, and getting them confused is the
-commonest way a finished build comes up as bare markup. `files` paths are
-relative to the **project root**, so they carry the app folder. A link inside a
-page is relative to **that page**, so it must not.
-
-```
-create_app({ folder: "tide", name: "Tide", files: [
-  { path: "tide/index.html", content: "... <link rel=stylesheet href=\"styles.css\">
-                                            <script type=module src=\"app.js\"></script> ..." },
-  { path: "tide/styles.css", content: "..." },
-  { path: "tide/app.js",     content: "..." },
-]})
-```
-
-Wrong, and it 404s: `href="tide/styles.css"` inside `tide/index.html` — the
-browser resolves that to `tide/tide/styles.css`, so no stylesheet and no script
-load, and the page is unstyled markup with dead buttons.
-
-## 2b. Look before you create
-
-`create_app` refuses a folder that already has something in it unless you pass
-the app in `files` — and a folder you half-made on an earlier attempt counts.
-One `list_dir` in front of it costs a second and tells you whether you are
-starting or resuming. The same goes for any command that makes a directory.
-
-## 2c. Do not type what already exists
-
-`add_block` has the pieces every app needs, written for whichever starter this
-one uses: a list you can add to, tick off, rename and remove; a filter row; a
-localStorage store; a dialog; toasts; a theme toggle; a table; an empty state.
-Call it before writing any of those by hand. Each is a hundred lines you skip,
-and typing is the slowest part of a build — a page assembled from blocks is
-done minutes before the same page typed out. Call `add_block` with no name to
-see what fits this app.
-
-## 3. Structure
-
-One component per file, named for what it is, not a 600-line `page.tsx`. In
-Next.js: `src/app` (routes, `globals.css`, `api/<name>/route.ts`),
-`src/components/<feature>/`, `src/lib/` for outside services and schemas.
-Server components by default, `"use client"` only where it is interactive.
-Types at every boundary; parse external data rather than trusting its shape.
-
-## 4. Secrets and outside services
-
-- **A key never reaches the browser.** It lives in a server route. Anything
-  imported by a `"use client"` file ships to every visitor, including a
-  "hardcoded for now" key — put it in a server-only module and say where.
-- Every outbound call gets a timeout (`AbortSignal.timeout(60_000)`), a status
-  check, and an error that says what failed — surfaced as a real message,
-  never a silent `catch {}`.
-- Calling a model: ask for JSON and parse it defensively (extract the first
-  `{...}`, validate, clamp numbers), put the judgement rules in the prompt
-  explicitly, and make the route timeout longer than the model takes.
-
-## 5. Build order
-
-Skeleton and design tokens first, so everything after is styled correctly the
-first time; then the server route with the real integration; then the core
-loop UI wired to it; then every state — empty, loading, success, error,
-invalid input; then polish: motion, responsive, copy, title and metadata.
-
-## 5a. It has to look finished
-
-People judge the app in the first second it is on screen, before they click
-anything. Before handing it over, check:
-
-- A real title and one line saying what it is for — never "Welcome to…".
-- The main action is visible without scrolling and is the most prominent button.
-- Every button and input has hover and focus states; nothing is left browser-default.
-- An empty list says what to do next ("No tasks yet — add one above"), never blank.
-- It fits a 375px phone with no sideways scroll; tap targets are at least 44px.
-- The number that matters (a score, a total, a timer) is big — several times body text.
-
-## 5b. Tests, where there is a runner
-
-`next-shadcn` ships vitest and one passing test, so `npm test` works from
-the first minute — add cases for the core loop as you build it, not after, and
-ucode will run the ones that touch whatever you change. Assert behaviour: that
-adding an item puts it in the list, that the total is right, that an empty
-input is refused.
-
-`plain-html` has no runner and installs nothing, by design. Its test is the
-browser check: ucode opens the app, types into the first field, presses Enter
-and clicks the button that submits. Make sure that path is the one that works.
-
-## 6. Prove it works, then report
-
-`npm run build` type-checks and lints — a build that fails is not done. Start
-it (`npm run dev` backgrounds itself and returns the URL; do not start it
-twice), then `look_at_app` on every page. A clean build proves it compiles,
-not that it works. Fix what you find and check again.
-
-Done means: the core loop works end to end, no TODO, no placeholder copy, no
-dead buttons, no console errors, every async action has its states, secrets
-server-side, build passes. Then say what you built, how to run it, and — in
-one sentence — anything you did not finish or could not test.
+# Building something from nothing — the short form
+
+The failure mode is not bad code. It is a folder of files that has never been
+run, handed over as if it works.
+
+## 1. Decide the shape before any file exists
+
+One line each: **what it does**, **the core loop** (the one path that must work
+perfectly), **the stack**, **the file list**.
+
+| Need | Choose |
+| --- | --- |
+| One page, no secrets, no server | `create_app` with `plain-html` |
+| Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
+| Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
+| An API on its own | Node (Hono/Express) or Python (FastAPI) |
+
+**Scope: complete, not sprawling.** Build what was asked, and build all of it
+well: every feature someone using that kind of app expects on first use — a
+tasks app adds, edits, ticks off, deletes, filters and remembers across a
+reload; a quiz has questions, scoring, feedback and a restart; a game has
+rules, a score, win and lose, and play again. Nothing from a different app: no
+timer, calendar or analytics dashboard bolted onto a tasks app, no accounts on
+a quiz. Features nobody named cost minutes and are where builds break — if one
+is worth it, offer it in one line at the end instead of building it.
+
+Pick the smallest stack that does the job and mean it: a tasks app, a
+calculator, a timer, a game, a visualisation — all one page. Next.js costs an
+install and a build, minutes the user waits through, and buys nothing an app
+with no server needs.
+
+## 2. Start from the starter — and finish in the same call
+
+`create_app` takes `files`, so for a one-page app the scaffold and the whole
+app are one call:
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "…" },
+  { path: "tide/styles.css", content: "…" },
+  { path: "tide/app.js",     content: "…" },
+]})
+```
+
+Every round trip is ten to forty seconds of the user's time, so one call
+instead of four is most of how long the build takes.
+
+- `plain-html` is the default: three files, no install, no build. Its files
+  come back in full inside the result — **never read them back**.
+- `next-shadcn` installs in the background; commands in that folder wait for
+  it on their own, so start writing components at once. Re-tint `globals.css`
+  for the app's direction rather than shipping the slate default.
+- Never run `create-next-app` or `shadcn init`. Nothing you run has a
+  keyboard: every scaffolder needs its answers as flags up front.
+
+## 2a. Paths in `files` are not the paths in the page
+
+The two are relative to different things, and getting them confused is the
+commonest way a finished build comes up as bare markup. `files` paths are
+relative to the **project root**, so they carry the app folder. A link inside a
+page is relative to **that page**, so it must not.
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "... <link rel=stylesheet href=\"styles.css\">
+                                            <script type=module src=\"app.js\"></script> ..." },
+  { path: "tide/styles.css", content: "..." },
+  { path: "tide/app.js",     content: "..." },
+]})
+```
+
+Wrong, and it 404s: `href="tide/styles.css"` inside `tide/index.html` — the
+browser resolves that to `tide/tide/styles.css`, so no stylesheet and no script
+load, and the page is unstyled markup with dead buttons.
+
+## 2b. Look before you create
+
+`create_app` refuses a folder that already has something in it unless you pass
+the app in `files` — and a folder you half-made on an earlier attempt counts.
+One `list_dir` in front of it costs a second and tells you whether you are
+starting or resuming. The same goes for any command that makes a directory.
+
+## 2c. Do not type what already exists
+
+`add_block` has the pieces every app needs, written for whichever starter this
+one uses: a list you can add to, tick off, rename and remove; a filter row; a
+localStorage store; a dialog; toasts; a theme toggle; a table; an empty state.
+Call it before writing any of those by hand. Each is a hundred lines you skip,
+and typing is the slowest part of a build — a page assembled from blocks is
+done minutes before the same page typed out. Call `add_block` with no name to
+see what fits this app.
+
+## 3. Structure
+
+One component per file, named for what it is, not a 600-line `page.tsx`. In
+Next.js: `src/app` (routes, `globals.css`, `api/<name>/route.ts`),
+`src/components/<feature>/`, `src/lib/` for outside services and schemas.
+Server components by default, `"use client"` only where it is interactive.
+Types at every boundary; parse external data rather than trusting its shape.
+
+## 4. Secrets and outside services
+
+- **A key never reaches the browser.** It lives in a server route. Anything
+  imported by a `"use client"` file ships to every visitor, including a
+  "hardcoded for now" key — put it in a server-only module and say where.
+- Every outbound call gets a timeout (`AbortSignal.timeout(60_000)`), a status
+  check, and an error that says what failed — surfaced as a real message,
+  never a silent `catch {}`.
+- Calling a model: ask for JSON and parse it defensively (extract the first
+  `{...}`, validate, clamp numbers), put the judgement rules in the prompt
+  explicitly, and make the route timeout longer than the model takes.
+
+## 5. Build order
+
+Skeleton and design tokens first, so everything after is styled correctly the
+first time; then the server route with the real integration; then the core
+loop UI wired to it; then every state — empty, loading, success, error,
+invalid input; then polish: motion, responsive, copy, title and metadata.
+
+## 5a. It has to look finished
+
+People judge the app in the first second it is on screen, before they click
+anything. Before handing it over, check:
+
+- A real title and one line saying what it is for — never "Welcome to…".
+- The main action is visible without scrolling and is the most prominent button.
+- Every button and input has hover and focus states; nothing is left browser-default.
+- An empty list says what to do next ("No tasks yet — add one above"), never blank.
+- It fits a 375px phone with no sideways scroll; tap targets are at least 44px.
+- The number that matters (a score, a total, a timer) is big — several times body text.
+
+## 5b. Tests, where there is a runner
+
+`next-shadcn` ships vitest and one passing test, so `npm test` works from
+the first minute — add cases for the core loop as you build it, not after, and
+ucode will run the ones that touch whatever you change. Assert behaviour: that
+adding an item puts it in the list, that the total is right, that an empty
+input is refused.
+
+`plain-html` has no runner and installs nothing, by design. Its test is the
+browser check: ucode opens the app, types into the first field, presses Enter
+and clicks the button that submits. Make sure that path is the one that works.
+
+## 6. Prove it works, then report
+
+`npm run build` type-checks and lints — a build that fails is not done. Start
+it (`npm run dev` backgrounds itself and returns the URL; do not start it
+twice), then `look_at_app` on every page. A clean build proves it compiles,
+not that it works. Fix what you find and check again.
+
+Done means: the core loop works end to end, no TODO, no placeholder copy, no
+dead buttons, no console errors, every async action has its states, secrets
+server-side, build passes. Then say what you built, how to run it, and — in
+one sentence — anything you did not finish or could not test.

package/skills/build-app/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build-app
 description: Take an app from nothing to running and finished — stack choice, non-interactive scaffolding, project structure, secrets, AI and API integration, error handling, and proving it works before saying it does.
-auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app, full stack, fullstack, saas, mvp
+auto: scaffold, new project, from scratch, build an app, make an app, create an app, make me a, make me an, build me an, create me a, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app, full stack, fullstack, saas, mvp
 ---
 
 # Building something from nothing
@@ -32,6 +32,15 @@ One line each:
 
 - **The file list** — the whole tree, before creating any of it.
 
+**Scope: complete, not sprawling.** Build what was asked, and build all of it
+well: every feature someone using that kind of app expects on first use — a
+tasks app adds, edits, ticks off, deletes, filters and remembers across a
+reload; a quiz has questions, scoring, feedback and a restart; a game has
+rules, a score, win and lose, and play again. Nothing from a different app: no
+timer, calendar or analytics dashboard bolted onto a tasks app, no accounts on
+a quiz. Features nobody named cost minutes and are where builds break — if one
+is worth it, offer it in one line at the end instead of building it.
+
 If there is a user interface, the `ui-ux` skill is already loaded. Decide the
 design direction now, not after the logic works. If the app calls a model,
 load `ai-features`; if it has accounts, keys or uploads, load `security`.

package/src/core/loop.js

@@ -50,6 +50,9 @@ import { Failure, ToolFailure, Declined } from './failure.js';
 import { StuckWatch, eventFor, describeHit } from './stuck.js';
 import { serversReadySince } from '../tools/shell.js';
 import { formatDuration } from '../ui/activity.js';
+import { MAX_FILE_OUTPUT } from '../tools/shared.js';
+import { openInBrowser } from './opener.js';
+import { withScope } from './scope.js';
 import { runDoctor } from './doctor.js';
 import { JS_LOGIC } from './jslogic.js';
 import { deploy } from '../tools/deploy.js';
@@ -109,6 +112,12 @@ const SILENT = new Set(['update_plan']);
 /** How many rounds of "the type check found errors, fix them" one turn may take. */
 const MAX_FIX_ROUNDS = 3;
 
+/** A file up to this many lines is sent whole on its first read, whatever slice was asked for. */
+const WHOLE_READ_LINES = 1500;
+
+/** Lookups in a row, during a fix round with nothing changed, before ucode says to stop reading. */
+const LOOKUP_NUDGE = 5;
+
 /** Files worth checking after they change. */
 /** A file with a page in it — something a browser can be pointed at. */
 const PAGE = /\.(?:html?|tsx|jsx)$/i;
@@ -621,6 +630,15 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     'already contains it. Do not re-check work the checks have already reported on.',
     'Fast is not sloppy: it is the same work with the waiting taken out.',
     '',
+    'BUILD WHAT WAS ASKED - ALL OF IT, AND NOTHING ELSE. A short request ("a tasks',
+    'app", "a quiz", "a snake game") still gets a complete, well-made app: every',
+    'feature someone using that kind of app expects on first use. A tasks app adds,',
+    'edits, ticks off, deletes, filters and remembers across a reload. It does NOT',
+    'also get a pomodoro timer, a calendar, an analytics dashboard, stats charts or a',
+    'shortcuts panel - those are other apps. Extra views are where builds break, and',
+    'each one costs the user minutes. One screen that does its job perfectly beats',
+    'four that half work. An extra worth having: offer it in one line at the end.',
+    '',
     'DESIGN IT BEFORE YOU TYPE IT. Fast means fewer round trips. It does not mean a',
     'default theme, and an app that goes out in the palette its starter came with is',
     'not a fast build, it is an undesigned one. There is no design pass after the',
@@ -632,7 +650,7 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '  - An ACCENT that is not the one the starter shipped with.',
     '  - ONE memorable thing this app has that other apps do not: a colour, a type',
     '    move, a texture, one interaction. Exactly one. It is the difference between',
-    '    a design and a theme.',
+    '    a design and a theme - a design choice, never an extra feature or view.',
     'Name the tone and the accent in your opening line, so they are settled before any',
     'file exists: "I will build Tide - a tasks app in one HTML file, calm, warm grey',
     'with a single amber accent." That is not narrating a plan, that is the decision.',
@@ -1205,6 +1223,9 @@ export class Agent {
     this.appName = null;
     this.appTemplate = null;
     this.reads = new Map();
+    this.fixing = false;
+    this.lookups = 0;
+    this.nudgedAt = 0;
     this.declines = 0;
     this.apps = [];
     this.wrote = new Map();
@@ -1216,9 +1237,8 @@ export class Agent {
     // 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 });
+    const request = images.length ? { role: 'user', content: input, images } : { role: 'user', content: input };
+    this.push(request);
 
     if (!this.session.title || this.session.title === 'Untitled') {
       this.session.title = titleFrom(input);
@@ -1231,6 +1251,7 @@ export class Agent {
     // Nothing to look up in an empty folder, so those tools do not go out with
     // the request. Decided per turn: the moment there is code, they are back.
     this.fresh = !hasCode(this.map);
+    request.content = withScope(input, { fresh: this.fresh });
     this.wantsWeb = WANTS_WEB.test(input);
     await this.persist();
 
@@ -1486,6 +1507,7 @@ export class Agent {
           const problems = await this.autoCheck();
           if (problems) {
             fixRounds++;
+            this.fixing = true;
             if (reply.text) this.push({ role: 'assistant', content: reply.text });
             this.push({
               role: 'user',
@@ -1571,6 +1593,7 @@ export class Agent {
       if (handed?.done) return;
       if (handed?.problems && fixRounds < MAX_FIX_ROUNDS) {
         fixRounds++;
+        this.fixing = true;
         this.push({
           role: 'user',
           content:
@@ -1643,8 +1666,16 @@ 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); this.forgetReads(p); }
+          this.lookups = 0;
+          this.nudgedAt = 0;
+        } else if (PARALLEL_SAFE.has(call.name)) {
+          this.lookups = (this.lookups ?? 0) + 1;
+        }
+        if (call.name === 'run_command' || call.name === 'run_commands') {
+          this.ranSomething = true;
+          // A command can rewrite any file, so no whole read is still known to be current.
+          for (const key of this.reads?.keys() ?? []) if (key.endsWith('#whole')) this.reads.delete(key);
         }
-        if (call.name === 'run_command' || call.name === 'run_commands') this.ranSomething = true;
       };
 
       if (group.length > 1) {
@@ -1753,26 +1784,10 @@ export class Agent {
     if (this.openInBrowser(server.url)) this.ui.note(`Opened ${server.url} in your browser`);
   }
 
-  /**
-   * Show a URL or a local page in the desktop browser. False when it did not.
-   *
-   * A file goes to explorer on Windows, not `cmd /c start`: the folder name
-   * comes from the model, and an & in it would be a second command to cmd.
-   */
+  /** Show a URL or a page in the project in the desktop browser (see opener.js). UCODE_OPEN=0 turns it off. */
   openInBrowser(target) {
     if (!this.full || process.env.UCODE_OPEN === '0') return false;
-    const web = /^https?:\/\//.test(target);
-    // Only pages inside the project: a UNC path would have explorer reach out to another machine.
-    const rel = web ? '' : path.relative(this.cwd, target);
-    if (!web && (!rel || rel.startsWith('..') || path.isAbsolute(rel))) return false;
-    const [cmd, args] = process.platform === 'win32'
-      ? (web ? ['cmd', ['/c', 'start', '', target]] : ['explorer.exe', [target]])
-      : [process.platform === 'darwin' ? 'open' : 'xdg-open', [target]];
-    try {
-      // A missing opener (no xdg-open) fails later, as an event; unheard, it would crash ucode.
-      spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
-      return true;
-    } catch { return false; /* no browser to open — the link is in the answer */ }
+    return openInBrowser(target, { root: this.cwd });
   }
 
   cmdStats() {
@@ -1878,7 +1893,34 @@ export class Agent {
       const found = /^(\d+) problem/.exec(out.summary ?? '');
       this.ui.runStat?.(found ? `${found[1]} to fix` : 'clean');
     }
-    this.push({ role: 'tool', toolCallId: call.id, name: call.name, content: out.content + this.stuckNote(call, { out }) });
+    this.push({ role: 'tool', toolCallId: call.id, name: call.name, content: out.content + this.stuckNote(call, { out }) + this.lookupNote(call) });
+  }
+
+  /**
+   * Reading on and on while ucode's list of errors waits. A live fix round
+   * read a 1000-line app.js in seventeen slices, changed nothing, and ran the
+   * free key into its per-minute limit: every read resends the conversation.
+   */
+  lookupNote(call) {
+    if (!this.fixing || !PARALLEL_SAFE.has(call.name)) return '';
+    if (this.lookups < LOOKUP_NUDGE || this.lookups - this.nudgedAt < LOOKUP_NUDGE) return '';
+    this.nudgedAt = this.lookups;
+    return `\n\nSTOP reading - that is ${this.lookups} lookups since ucode listed the errors, and nothing has been ` +
+      'changed yet. What you need is already above. Make the fix now with edit_file or multi_edit; ucode ' +
+      'checks the app again straight after.';
+  }
+
+  /** Lines in a file small enough to send whole in one read, or null. */
+  async wholeSize(file) {
+    try {
+      const text = await readFile(path.resolve(this.cwd, file), 'utf8');
+      if (text.includes('\0')) return null;
+      const lines = text.split('\n').length;
+      // The line-number gutter adds about eight characters a line to what read_file sends.
+      return lines <= WHOLE_READ_LINES && text.length + lines * 8 <= MAX_FILE_OUTPUT ? { lines } : null;
+    } catch {
+      return null;
+    }
   }
 
   /**
@@ -2034,6 +2076,27 @@ export class Agent {
     // refused as "unchanged", and a live build spent sixty steps being told so.
     if (call.name === 'read_file' && call.args?.path) {
       const file = String(call.args.path);
+
+      // A file that fits is sent whole the first time, and not again until
+      // something writes to it. Slices were the loop: a live fix round read one
+      // app.js in seventeen of them, never edited, and hit the per-minute limit.
+      // The lead only — a worker has its own conversation, without the lead's reads.
+      if (offered === this.offering) {
+        const whole = `${fileKey(file)}#whole`;
+        if (this.reads.has(whole)) {
+          return {
+            content: `All of ${file} is already above: you read the whole file and nothing has written to it ` +
+              'since. Use that text instead of reading it again. If something in it needs changing, change it ' +
+              'now with edit_file or multi_edit.',
+            summary: 'unchanged, already read in full',
+          };
+        }
+        // Marked before the await, so two reads of one file in a parallel batch send it once.
+        this.reads.set(whole, 1);
+        const size = await this.wholeSize(file);
+        if (size) call.args = { ...call.args, offset: 1, limit: size.lines };
+        else this.reads.delete(whole);
+      }
       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) {
@@ -2809,6 +2872,8 @@ export class Agent {
       this.ui.stopSpinner();
       if (result.folded) {
         this.working = result.messages;
+        // What was read is summarised away now, so it may be read again.
+        this.reads = new Map();
         this.ui.note(
           `folded ${result.droppedCount} earlier messages into a summary ` +
           '(the full history is still saved in this session)'

package/src/core/opener.js

@@ -0,0 +1,44 @@
+/**
+ * opener.js — showing a finished page or a running server in the user's own
+ * browser.
+ *
+ * Kept apart from the loop because it is the one place ucode starts a program
+ * on a path the model chose, and that deserves to be read on its own.
+ */
+
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+/** Is this a web address rather than a file on disk? */
+const isWeb = (target) => /^https?:\/\//.test(target);
+
+/**
+ * Only pages inside the project are opened. A folder name comes from the
+ * model, and a UNC path (\\host\share) would have explorer reach out to
+ * another machine.
+ */
+export function insideRoot(target, root) {
+  const rel = path.relative(root, target);
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * Open a URL or a page inside `root`. Returns whether an opener was started.
+ *
+ * A file goes to explorer on Windows, not `cmd /c start`: an & in a folder
+ * name would be a second command to cmd.
+ */
+export function openInBrowser(target, { root }) {
+  const web = isWeb(target);
+  if (!web && !insideRoot(target, root)) return false;
+  const [cmd, args] = process.platform === 'win32'
+    ? (web ? ['cmd', ['/c', 'start', '', target]] : ['explorer.exe', [target]])
+    : [process.platform === 'darwin' ? 'open' : 'xdg-open', [target]];
+  try {
+    // A missing opener (no xdg-open) fails later, as an event; unheard, it would crash ucode.
+    spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
+    return true;
+  } catch {
+    return false; // no browser to open — the link is in the answer
+  }
+}

package/src/core/scope.js

@@ -0,0 +1,23 @@
+/**
+ * scope.js — keeping a new app to what was asked for.
+ *
+ * In the system prompt and the build-app skill alone, Flash-Lite still built
+ * "make me a tasks app" as a tasks app plus a pomodoro timer, a kanban board
+ * and analytics — twice running — and the extra views were where the builds
+ * broke. So the rule also rides on the request itself, the last thing the
+ * model reads before it starts.
+ */
+
+export const SCOPE_NOTE =
+  '(From ucode: if this asks for a new app, build it complete and well made, but as the one app asked ' +
+  'for - no extra views or tools such as timers, calendars, kanban boards, analytics, stats or an ' +
+  'editor for making your own, unless the request names them.)';
+
+/** A request that may be for a new app. Loose on purpose: the note it adds says "if". */
+export const BUILD_ASK =
+  /\b(?:make|build|create|design|code|write|generate|develop)\b|\bi\s+(?:want|need)\b|\b(?:app|game|website|site|page|tracker|calculator|quiz)\b/i;
+
+/** The request as the model sees it: one in an empty folder, or shaped like a build, carries the note. */
+export function withScope(input, { fresh = false } = {}) {
+  return fresh || BUILD_ASK.test(input) ? `${input}\n\n${SCOPE_NOTE}` : input;
+}

package/src/tools/browser.js

@@ -232,6 +232,63 @@ const NOT_ADD = /search|filter|find|sort|query/i;
 const LIST_HINT = /task|todo|to-do|item|note|add|new|entry|expense|habit|title|what needs|remind/i;
 const ADD_BUTTON = /^\s*(?:\+|add|new|create|save|submit|post|done)\b|\b(?:add|create|save)\s/i;
 
+/** A value a form will take for a field of this type, or null to leave the field alone. */
+function sampleFor(type, today) {
+  switch (type) {
+    case 'number': return '42';
+    case 'date': return today;
+    case 'time': return '12:00';
+    case 'datetime-local': return `${today}T12:00`;
+    case 'month': return today.slice(0, 7);
+    case 'email': return 'check@example.com';
+    case 'url': return 'https://example.com';
+    case 'tel': return '5550100';
+    case 'text': case 'textarea': case 'search': case '': return PROBE_TEXT;
+    default: return null; // checkboxes, radios, files, colours: nothing to guess
+  }
+}
+
+/**
+ * Fill in the rest of the form the probe text went into, the way a person
+ * would before pressing Add.
+ *
+ * Traced: a budget tracker's form also needs an amount. Only the description
+ * was typed, the browser refused the submit, and a working app was reported as
+ * "ADDING DOES NOT WORK" — the model then spent its fix rounds on code that
+ * worked. Filled: required fields, empty number fields (amounts are often
+ * checked in script, not marked required) and dropdowns left on a blank choice.
+ */
+async function fillTheRest(page, field) {
+  const marked = await field.evaluate((e) => {
+    if (!e.form) return false;
+    e.form.setAttribute('data-ucode-probe', '');
+    return true;
+  }).catch(() => false);
+  if (!marked) return;
+
+  const today = new Date().toISOString().slice(0, 10);
+  const all = page.locator('form[data-ucode-probe] :is(input, select, textarea)');
+  const n = Math.min(await all.count().catch(() => 0), 20);
+  for (let i = 0; i < n; i++) {
+    const el = all.nth(i);
+    const info = await el.evaluate((e) => ({
+      tag: e.tagName.toLowerCase(),
+      type: (e.getAttribute('type') || (e.tagName === 'TEXTAREA' ? 'textarea' : '')).toLowerCase(),
+      empty: !e.value,
+      required: e.required,
+    })).catch(() => null);
+    if (!info?.empty || !(await el.isVisible().catch(() => false))) continue;
+    if (info.tag === 'select') {
+      await el.selectOption({ index: 1 }, { timeout: 2_000 }).catch(() => {});
+      continue;
+    }
+    if (!info.required && info.type !== 'number') continue;
+    const value = sampleFor(info.type, today);
+    if (value !== null) await el.fill(value, { timeout: 2_000 }).catch(() => {});
+  }
+  await page.locator('form[data-ucode-probe]').evaluate((f) => f.removeAttribute('data-ucode-probe')).catch(() => {});
+}
+
 async function tryAdd(page) {
   const shows = () => page.evaluate((t) => document.body.innerText.includes(t), PROBE_TEXT).catch(() => false);
   const settle = () => page.waitForTimeout(400);
@@ -279,6 +336,7 @@ async function tryAdd(page) {
   }
   const ok = await field.el.fill(PROBE_TEXT, { timeout: 2_000 }).then(() => true).catch(() => false);
   if (!ok) return tried.length ? { tried, added: false, listApp } : null;
+  await fillTheRest(page, field.el);
   await field.el.press('Enter', { timeout: 2_000 }).catch(() => {});
   await settle();
   tried.push(`typed "${PROBE_TEXT}" into ${field.hint ? `"${field.hint.slice(0, 30)}"` : 'the field'} and pressed Enter`);

package/src/tools/index.js

@@ -99,7 +99,11 @@ export const tools = [
       'In "next-shadcn" every path in "files" goes under src/: a page is a route only at ' +
       '<app>/src/app/page.tsx or <app>/src/app/<segment>/page.tsx, an API handler only at ' +
       '<app>/src/app/api/<name>/route.ts, and components at <app>/src/components/<feature>/. ' +
-      'A page.tsx written anywhere else is an ordinary file the router never serves.',
+      'A page.tsx written anywhere else is an ordinary file the router never serves. ' +
+      'Scope: build what was asked, complete and well made - every feature someone using that kind of ' +
+      'app expects on first use (a tasks app adds, edits, ticks off, deletes, filters and remembers across ' +
+      'a reload) - and nothing from a different app (no timer, calendar or analytics bolted onto a tasks ' +
+      'app). Features nobody named cost minutes and are where builds break.',
     parameters: {
       type: 'object',
       properties: {

package/src/tools/shell.js

@@ -57,6 +57,13 @@ const LOOKS_LIKE_INSTALL =
 /** 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;
 
+/**
+ * Installing a browser to test the app. ucode already drives a real one after
+ * every change; a live quiz build spent two minutes on `npx @puppeteer/browsers
+ * install chrome` before it timed out.
+ */
+const INSTALLS_BROWSER = /@puppeteer\/browsers\s+install|\bplaywright(?:@\S+)?\s+install\b/i;
+
 /**
  * Any kill by program name rather than by process number.
  *
@@ -672,6 +679,14 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
     );
   }
 
+  if (INSTALLS_BROWSER.test(command)) {
+    return result(
+      'Not run: ucode already opens the app in a real browser after every change and reports what it finds. ' +
+        'Fix what that report names; there is no browser to install.',
+      'not needed — ucode has a browser',
+    );
+  }
+
   if (KILLS_BY_NAME.test(command)) {
     const attempted = `running \`${command.trim().slice(0, 80)}\``;
     try {