leglas 0.4.0 → 0.5.0

package/dist/index.js

@@ -57,6 +57,7 @@ function parseAdd(rest) {
   let branch;
   let file;
   let basedOn;
+  let askedFor;
   const tags = [];
   let json = false;
   for (let index = 0; index < rest.length; index += 1) {
@@ -75,7 +76,9 @@ function parseAdd(rest) {
     } else {
       value = argument.slice(equals + 1);
     }
-    if (!["--title", "--url", "--note", "--tag", "--branch", "--file", "--based-on"].includes(flag)) {
+    if (!["--title", "--url", "--note", "--tag", "--branch", "--file", "--based-on", "--asked-for"].includes(
+      flag
+    )) {
       return { kind: "error", message: `leglas add does not take ${flag}.` };
     }
     if (value === void 0 || value === "") {
@@ -87,6 +90,7 @@ function parseAdd(rest) {
     else if (flag === "--branch") branch = value;
     else if (flag === "--file") file = value;
     else if (flag === "--based-on") basedOn = value;
+    else if (flag === "--asked-for") askedFor = value;
     else tags.push(value);
   }
   if (title === void 0) {
@@ -100,7 +104,16 @@ function parseAdd(rest) {
   }
   return {
     kind: "add",
-    preview: { title, url, note, tags: tags.length > 0 ? tags : void 0, branch, file, basedOn },
+    preview: {
+      title,
+      url,
+      note,
+      tags: tags.length > 0 ? tags : void 0,
+      branch,
+      file,
+      basedOn,
+      askedFor
+    },
     json
   };
 }
@@ -600,6 +613,11 @@ direction. Build it directly. A planning or approval step before implementing
 costs more than the work itself, and the directions on screen are the thing
 being asked for.
 
+A request that says it came from the running Leglas interface has already
+completed exploration, request collection and the live-server check. Follow
+the exact source and registration command in that request directly. Do not
+repeat \`explore\`, \`requests\`, \`list\`, CLI help/version checks or server startup.
+
 When asked for design variations, alternatives, or "a few options":
 
 1. **Add beside what exists. Never replace it.** Every direction has to render
@@ -808,6 +826,10 @@ function normalizeConfig(raw, options = {}) {
     if (basedOn !== void 0 && (typeof basedOn !== "string" || basedOn.trim() === "")) {
       errors.push(`${at} has a basedOn that is not a direction title.`);
     }
+    const askedFor = entry["askedFor"];
+    if (askedFor !== void 0 && (typeof askedFor !== "string" || askedFor.trim() === "")) {
+      errors.push(`${at} has an askedFor that is not a change request.`);
+    }
     const tags = entry["tags"];
     previews.push({
       title: typeof title === "string" ? title : "",
@@ -816,7 +838,8 @@ function normalizeConfig(raw, options = {}) {
       tags: Array.isArray(tags) ? tags.filter((tag) => typeof tag === "string") : [],
       ...typeof branch === "string" ? { branch } : {},
       ...typeof file === "string" ? { file } : {},
-      ...typeof basedOn === "string" && basedOn.trim() !== "" ? { basedOn } : {}
+      ...typeof basedOn === "string" && basedOn.trim() !== "" ? { basedOn } : {},
+      ...typeof askedFor === "string" && askedFor.trim() !== "" ? { askedFor } : {}
     });
   });
   const devCommand = source["devCommand"];
@@ -932,6 +955,10 @@ import { spawn } from "child_process";
 import { constants } from "fs";
 import { access, mkdir, readFile, writeFile } from "fs/promises";
 import { delimiter, dirname, isAbsolute, join, relative } from "path";
+var CODEX_WORKSPACE_CONFIG = [
+  "-c",
+  "sandbox_workspace_write.network_access=true"
+];
 var KNOWN_AGENTS = {
   claude: {
     name: "Claude",
@@ -962,6 +989,12 @@ var KNOWN_AGENTS = {
       "--permission-mode",
       "acceptEdits"
     ],
+    // Non-interactive Claude cannot approve a Bash call: acceptEdits covers
+    // files, so a command the prompt requires is refused every time with
+    // nobody there to say yes. This allows exactly that command and nothing
+    // wider. Codex needs no equivalent, because workspace-write already lets
+    // it run commands.
+    allowArgs: (command) => ["--allowedTools", `Bash(${command} *)`],
     // Every stream-json event names its session.
     sessionFrom: (event) => typeof event.session_id === "string" && event.session_id !== "" ? event.session_id : null,
     authArgs: ["auth", "status"],
@@ -982,15 +1015,41 @@ var KNOWN_AGENTS = {
   codex: {
     name: "Codex",
     binary: "codex",
-    args: (prompt) => ["exec", "--json", "-s", "workspace-write", prompt],
-    terminalArgs: (prompt) => ["exec", "-s", "workspace-write", prompt],
+    // `--skip-git-repo-check` is what lets Codex run at all in a project the
+    // user never put under version control: without it codex-cli refuses
+    // before it reaches a model, with "Not inside a trusted directory and
+    // --skip-git-repo-check was not specified", and every Codex request in a
+    // non-git project fails for a reason nothing in Leglas explained. The flag
+    // moves that precondition and only that: `-s workspace-write` still
+    // confines writes to the project, so the sandbox boundary is unchanged,
+    // and in a git repository the flag does nothing at all.
+    args: (prompt) => [
+      "exec",
+      "--json",
+      ...CODEX_WORKSPACE_CONFIG,
+      "-s",
+      "workspace-write",
+      "--skip-git-repo-check",
+      prompt
+    ],
+    terminalArgs: (prompt) => [
+      "exec",
+      ...CODEX_WORKSPACE_CONFIG,
+      "-s",
+      "workspace-write",
+      "--skip-git-repo-check",
+      prompt
+    ],
     // No sandbox flag here: `codex exec resume` refuses it and inherits the
-    // session's own sandbox, which the first turn set to workspace-write.
+    // session's own sandbox, which the first turn set to workspace-write. The
+    // repository check is per invocation, so resume needs the flag of its own.
     resumeArgs: (sessionId, prompt) => [
       "exec",
       "resume",
       sessionId,
       "--json",
+      ...CODEX_WORKSPACE_CONFIG,
+      "--skip-git-repo-check",
       prompt
     ],
     sessionFrom: (event) => event.type === "thread.started" && typeof event.thread_id === "string" ? event.thread_id : null,
@@ -1016,7 +1075,7 @@ var KNOWN_AGENTS = {
   }
 };
 var PROBE_TIMEOUT_MS = 3e3;
-function execProbe(binary, args) {
+function execProbe(binary, args, timeoutMs = PROBE_TIMEOUT_MS) {
   return new Promise((resolve) => {
     let child;
     try {
@@ -1029,7 +1088,10 @@ function execProbe(binary, args) {
       if (stdout.length < 4096)
         stdout += chunk.toString();
     });
-    const deadline = setTimeout(() => child.kill("SIGKILL"), PROBE_TIMEOUT_MS);
+    const deadline = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve(null);
+    }, timeoutMs);
     child.once("error", () => {
       clearTimeout(deadline);
       resolve(null);
@@ -1098,10 +1160,10 @@ function shownCommand(value) {
 function claudeActivity(event, cwd) {
   if (event.type !== "assistant")
     return null;
-  const message = record(event.message);
-  if (message === null || !Array.isArray(message.content))
+  const message2 = record(event.message);
+  if (message2 === null || !Array.isArray(message2.content))
     return null;
-  for (const rawBlock of message.content) {
+  for (const rawBlock of message2.content) {
     const block = record(rawBlock);
     if (block?.type !== "tool_use" || typeof block.name !== "string")
       continue;
@@ -1170,6 +1232,25 @@ function sessionFrom(agent, line) {
     return null;
   return KNOWN_AGENTS[agent].sessionFrom(event);
 }
+function retryFrom(agent, line) {
+  if (agent !== "claude" && agent !== "cursor")
+    return null;
+  let event;
+  try {
+    event = record(JSON.parse(line));
+  } catch {
+    return null;
+  }
+  if (event === null || event.type !== "system" || event.subtype !== "api_retry")
+    return null;
+  const attempt = typeof event.attempt === "number" ? event.attempt : 1;
+  return {
+    attempt,
+    max: typeof event.max_retries === "number" ? event.max_retries : null,
+    status: typeof event.error_status === "number" ? event.error_status : null,
+    reason: typeof event.error === "string" && event.error !== "" ? event.error.toLowerCase() : null
+  };
+}
 function isAgentChoice(value) {
   return value === "custom" || typeof value === "string" && Object.hasOwn(KNOWN_AGENTS, value);
 }
@@ -1313,8 +1394,8 @@ async function loadConfig(cwd) {
       exported = module.default;
     }
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { config: null, errors: [`${label} could not be loaded: ${message}`], path };
+    const message2 = error instanceof Error ? error.message : String(error);
+    return { config: null, errors: [`${label} could not be loaded: ${message2}`], path };
   }
   const result = normalizeConfig(exported);
   return {
@@ -1333,8 +1414,17 @@ async function readLocalPreviews(cwd) {
   let raw;
   try {
     raw = await readFile3(path, "utf8");
-  } catch {
-    return { previews: [], errors: [] };
+  } catch (error) {
+    const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
+    if (code === "ENOENT") {
+      return { previews: [], errors: [] };
+    }
+    return {
+      previews: [],
+      errors: [
+        `${LOCAL_PREVIEWS_PATH} could not be read (${code ?? "unknown error"}). Check its permissions and file type; nothing shared is lost.`
+      ]
+    };
   }
   let parsed;
   try {
@@ -1375,7 +1465,8 @@ async function addLocalPreview(cwd, input, shared) {
     ...input.tags === void 0 ? {} : { tags: input.tags },
     ...input.branch === void 0 ? {} : { branch: input.branch },
     ...input.file === void 0 ? {} : { file: input.file },
-    ...input.basedOn === void 0 ? {} : { basedOn: input.basedOn }
+    ...input.basedOn === void 0 ? {} : { basedOn: input.basedOn },
+    ...input.askedFor === void 0 ? {} : { askedFor: input.askedFor }
   };
   const check = normalizeConfig({ previews: [candidate] }, { requireDevCommand: false });
   if (check.config === null) {
@@ -1607,17 +1698,220 @@ async function startAppProcess(options) {
   throw new Error(`${options.label} did not start within ${Math.round(readyTimeoutMs / 1e3)}s. Check that its dev command serves the port it is given.`);
 }
 
-// ../server/dist/requests.js
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+// ../server/dist/failure.js
+var NEEDS_TRUST = /not inside a trusted directory|--skip-git-repo-check/i;
+var MISSING_BINARY = /\b(ENOENT|EACCES|ENOTDIR)\b/;
+var NOT_SIGNED_IN = /not logged in|not signed in|please (?:re-?)?(?:run|sign|log)\s*in|\/login\b|invalid api key|unauthorized|authentication_failed|\b401\b/i;
+var LIMIT = /\b429\b|rate limit|usage limit|quota exceeded|too many requests/i;
+var OVERLOADED = /\b(?:503|529)\b|overloaded|service unavailable/i;
+function fromStatus(status, reason) {
+  if (status === 401 || status === 403 || reason === "authentication_failed")
+    return "not-signed-in";
+  if (status === 429 || reason === "rate_limit")
+    return "provider-limit";
+  if (status === 529 || status === 503 || reason === "overloaded")
+    return "provider-overloaded";
+  return null;
+}
+function fromLines(lines) {
+  for (const line of [...lines].reverse()) {
+    if (NEEDS_TRUST.test(line))
+      return "needs-trust";
+    if (NOT_SIGNED_IN.test(line))
+      return "not-signed-in";
+    if (LIMIT.test(line))
+      return "provider-limit";
+    if (OVERLOADED.test(line))
+      return "provider-overloaded";
+  }
+  return null;
+}
+function attempts(retry) {
+  if (retry === null || retry === void 0)
+    return "";
+  const total = retry.max === null ? retry.attempt : Math.max(retry.attempt, retry.max);
+  return ` It retried ${total} times first.`;
+}
+function message(code, input) {
+  const agent = input.agent;
+  switch (code) {
+    case "cancelled":
+      return "You stopped this run.";
+    case "stopped":
+      return "Leglas shut down while this was running.";
+    case "missing-agent":
+      return `${agent} could not be started. Its command is not on this machine's PATH any more.`;
+    case "not-signed-in":
+      return `${agent} is not signed in. Sign in to it in a terminal, then run this again.`;
+    case "provider-overloaded":
+      return `${agent}'s provider was overloaded and gave up.${attempts(input.retry)}`;
+    case "provider-limit":
+      return `${agent} reported a rate or usage limit, so nothing ran.`;
+    case "needs-trust":
+      return `Codex refused this project: it is not a git repository and Codex has no trust on record for it.`;
+    case "not-registered":
+      return `${agent} finished without registering the new direction, so nothing reached the rail. Its last output is in the Leglas terminal.`;
+    case "agent-error":
+      return input.exitCode === null || input.exitCode === void 0 ? `${agent} stopped without finishing. Its last output is in the Leglas terminal.` : `${agent} exited with code ${input.exitCode}. Its last output is in the Leglas terminal.`;
+  }
+}
+function classifyFailure(input) {
+  const lines = input.lines ?? [];
+  const error = input.error ?? null;
+  const code = error === "cancelled" ? "cancelled" : error === "not-registered" ? "not-registered" : error !== null && /^stopped by /.test(error) ? "stopped" : error !== null && MISSING_BINARY.test(error) ? "missing-agent" : (error !== null ? fromLines([error]) : null) ?? fromStatus(input.retry?.status ?? null, input.retry?.reason ?? null) ?? fromLines(lines) ?? "agent-error";
+  return { code, message: message(code, input) };
+}
+function sessionShaped(code) {
+  return code === "agent-error";
+}
+
+// ../server/dist/annotations.js
 import { randomBytes } from "crypto";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname4, join as join5 } from "path";
+var ANNOTATIONS_PATH = ".leglas/annotations.json";
+var NOTE_CAP = 500;
+var SELECTOR_CAP = 300;
+var TEXT_CAP = 120;
+var TAG_CAP = 40;
+var CLASS_CAP = 8;
+var CLASS_LENGTH_CAP = 60;
+var COVERS_CAP = 8;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value, cap) {
+  return typeof value === "string" ? value.trim().slice(0, cap) : "";
+}
+function fraction(value) {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    return 0.5;
+  return Math.min(1, Math.max(0, value));
+}
+function size(value) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.round(value) : 0;
+}
+function anchorFrom(value) {
+  if (!isRecord2(value))
+    return null;
+  const selector = text(value["selector"], SELECTOR_CAP);
+  if (selector === "")
+    return null;
+  const rect = isRecord2(value["rect"]) ? value["rect"] : {};
+  const classes = Array.isArray(value["classes"]) ? value["classes"].filter((entry) => typeof entry === "string").slice(0, CLASS_CAP).map((entry) => entry.slice(0, CLASS_LENGTH_CAP)) : [];
+  const rawRegion = isRecord2(value["region"]) ? value["region"] : null;
+  const region = rawRegion === null ? null : {
+    height: fraction(rawRegion["height"]),
+    width: fraction(rawRegion["width"]),
+    x: fraction(rawRegion["x"]),
+    y: fraction(rawRegion["y"])
+  };
+  const covers = Array.isArray(value["covers"]) ? value["covers"].filter(isRecord2).slice(0, COVERS_CAP).map((entry) => ({
+    tag: text(entry["tag"], TAG_CAP) || "element",
+    text: text(entry["text"], TEXT_CAP)
+  })) : [];
+  return {
+    classes,
+    ...covers.length === 0 ? {} : { covers },
+    ...region === null ? {} : { region },
+    rect: {
+      height: size(rect["height"]),
+      width: size(rect["width"]),
+      x: size(rect["x"]),
+      y: size(rect["y"])
+    },
+    selector,
+    spot: {
+      x: fraction(isRecord2(value["spot"]) ? value["spot"]["x"] : void 0),
+      y: fraction(isRecord2(value["spot"]) ? value["spot"]["y"] : void 0)
+    },
+    tag: text(value["tag"], TAG_CAP) || "element",
+    text: text(value["text"], TEXT_CAP),
+    viewport: size(value["viewport"])
+  };
+}
+async function readAnnotations(cwd) {
+  try {
+    const raw = await readFile4(join5(cwd, ANNOTATIONS_PATH), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.annotations))
+      return [];
+    return parsed.annotations.flatMap((entry, index) => {
+      if (!isRecord2(entry))
+        return [];
+      const anchor = anchorFrom(entry["anchor"]);
+      const title = text(entry["title"], TAG_CAP * 4);
+      if (anchor === null || title === "")
+        return [];
+      return [
+        {
+          anchor,
+          id: typeof entry["id"] === "string" ? entry["id"] : String(index),
+          note: text(entry["note"], NOTE_CAP),
+          title
+        }
+      ];
+    });
+  } catch {
+    return [];
+  }
+}
+async function write(cwd, annotations) {
+  const path = join5(cwd, ANNOTATIONS_PATH);
+  await mkdir3(dirname4(path), { recursive: true });
+  await writeFile3(path, `${JSON.stringify({ annotations }, null, 2)}
+`, "utf8");
+}
+async function addAnnotation(cwd, input) {
+  const annotation = { ...input, id: randomBytes(6).toString("base64url") };
+  await write(cwd, [...await readAnnotations(cwd), annotation]);
+  return annotation;
+}
+async function removeAnnotations(cwd, ids) {
+  const wanted = new Set(ids);
+  const annotations = await readAnnotations(cwd);
+  const remaining = annotations.filter((entry) => !wanted.has(entry.id));
+  const dropped = annotations.length - remaining.length;
+  if (dropped > 0)
+    await write(cwd, remaining);
+  return dropped;
+}
+function annotationsFor(annotations, title) {
+  return annotations.filter((entry) => entry.title === title);
+}
+function describeAnchor(anchor) {
+  const where = `about ${anchor.rect.width}\xD7${anchor.rect.height} at (${anchor.rect.x}, ${anchor.rect.y}) in a ${anchor.viewport}px-wide viewport`;
+  if (anchor.region !== void 0) {
+    const covered = (anchor.covers ?? []).map((entry) => entry.text === "" ? `<${entry.tag}>` : `<${entry.tag}> \u201C${entry.text}\u201D`).join(", ");
+    const inside = covered === "" ? "" : ` covering ${covered};`;
+    return `an area inside <${anchor.tag}>;${inside} path ${anchor.selector}; ${where}`;
+  }
+  const parts = [`<${anchor.tag}>`];
+  if (anchor.classes.length > 0)
+    parts.push(`class "${anchor.classes.join(" ")}"`);
+  if (anchor.text !== "")
+    parts.push(`reading \u201C${anchor.text}\u201D`);
+  return `${parts.join(", ")}; path ${anchor.selector}; ${where}`;
+}
+function describeAnnotations(annotations) {
+  return annotations.map((annotation, index) => {
+    const said = annotation.note === "" ? "Look at this." : annotation.note;
+    return `${index + 1}. ${said}
+   The element: ${describeAnchor(annotation.anchor)}`;
+  }).join("\n\n");
+}
+
+// ../server/dist/requests.js
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
+import { randomBytes as randomBytes2 } from "crypto";
+import { dirname as dirname5, join as join6 } from "path";
 var SAFE_SEGMENT = /^[a-z0-9][a-z0-9-]*$/i;
-function targetFor(url) {
+function variantSlot(url) {
   if (!url.startsWith("/"))
     return null;
-  const query = url.slice(url.indexOf("?") + 1);
   if (!url.includes("?"))
     return null;
+  const query = url.slice(url.indexOf("?") + 1);
   for (const pair of query.split("&")) {
     const [rawKey, rawValue] = pair.split("=");
     if (rawKey === void 0 || rawValue === void 0)
@@ -1628,37 +1922,125 @@ function targetFor(url) {
     const option = decodeURIComponent(rawValue);
     if (!SAFE_SEGMENT.test(surface) || !SAFE_SEGMENT.test(option))
       return null;
-    return `.leglas/variants/${surface}/${option}.tsx`;
+    return { surface, option };
   }
   return null;
 }
-function composeRequest(preview, intent) {
+function targetFor(url) {
+  const slot = variantSlot(url);
+  return slot === null ? null : `.leglas/variants/${slot.surface}/${slot.option}.tsx`;
+}
+function composeRequest(preview, intent, mode, notes = [], leglasCommand = "npx -y leglas") {
   const target = preview.file ?? targetFor(preview.url);
   const cleaned = intent.trim();
+  const asked = changeBlock(cleaned, notes);
+  const recorded = cleaned === "" ? notes.map((entry) => entry.note).filter((entry) => entry !== "").join("; ") : cleaned;
+  const prompt = mode === "variant" ? variantPrompt(preview, recorded, asked, target, leglasCommand) : replacePrompt(preview, asked, target);
+  return { prompt, target, mode };
+}
+var ANCHORS = `Each path and rectangle was recorded when the note was left, against the design as it looked then. Trust the element's own words first, then its tag and classes, then the path, and treat the rectangle as a hint about where on the page to look rather than a fact.`;
+function changeBlock(cleaned, notes) {
+  if (notes.length === 0)
+    return `What to change: ${cleaned}`;
+  const many = notes.length === 1 ? "a note" : `${notes.length} notes`;
+  const lead = cleaned === "" ? `What to change, left as ${many} on the design itself:` : `What to change: ${cleaned}
+
+And ${many} left on the design itself:`;
+  return `${lead}
+
+${describeAnnotations(notes)}
+
+${ANCHORS}`;
+}
+var SCOPE = `This request came from the running Leglas interface. Request collection, direction discovery and the live-server check are already complete. Do not run Leglas explore, requests, list, show, help or version commands, do not inspect package caches, and do not start or restart the app or Leglas. Use the existing live preview if visual inspection is useful.
+
+This is a scoped design change: no test run, no build, and no survey of the rest of the project is needed. The result is checked visually in a live preview, not by tooling.
+
+Leave every other direction exactly as it is; they are alternatives being compared side by side, so changing a sibling destroys the comparison. Keep the change additive: do not rewrite shared components that other directions rely on.`;
+function registrationCommand(leglasCommand) {
+  return `${leglasCommand} add`;
+}
+function replacePrompt(preview, asked, target) {
   const where = target === null ? `The direction is titled "${preview.title}" and renders at ${preview.url}. Find what produces it.` : `It lives at ${target}.`;
   const pace = target === null ? `Once found, make the change and finish. ` : `Make the change in that file and finish. `;
-  const prompt = `In this project, change only the "${preview.title}" design direction. ${where}
+  return `In this project, change only the "${preview.title}" design direction. ${where}
+
+${asked}
+
+${pace}${SCOPE} The direction is already registered, so nothing needs re-registering.`;
+}
+function variantPrompt(preview, recorded, asked, target, leglasCommand) {
+  const slot = variantSlot(preview.url);
+  const parent = JSON.stringify(preview.title);
+  const askedFor = JSON.stringify(recorded);
+  const add = registrationCommand(leglasCommand);
+  const source = target === null ? `Find what renders it first.` : `Its source is ${target}.`;
+  const [make, register] = preview.file !== void 0 ? [
+    `Copy that file to a new file beside it and make the change in the copy.`,
+    `  ${add} --title "<name>" --file "<the new file>" --based-on ${parent} --note "<what this direction is, one line>" --asked-for ${askedFor}`
+  ] : slot !== null ? [
+    `Copy that file to a new one in the same folder and make the change in the copy. The new file's name without its extension is its key, and that key has to be listed in the DIRECTIONS map in .leglas/variants/${slot.surface}/switch.tsx or its URL will not resolve.`,
+    `  ${add} --title "<name>" --url "/?v-${slot.surface}=<key>" --based-on ${parent} --note "<what this direction is, one line>" --asked-for ${askedFor}`
+  ] : [
+    `Copy its source rather than editing it, and make the change in the copy. Add the new direction the way this project already switches between them; if it has a Leglas branch point, that is the DIRECTIONS map in .leglas/variants/<surface>/switch.tsx.`,
+    `  ${add} --title "<name>" --url "<the URL that shows it>" --based-on ${parent} --note "<what this direction is, one line>" --asked-for ${askedFor}`
+  ];
+  return `In this project, add a new design direction based on the "${preview.title}" direction. Leave "${preview.title}" itself exactly as it is: it is the thing the new one will be compared against.
 
-What to change: ${cleaned}
+${source} ${make}
 
-${pace}This is a scoped design change: no test run, no build, and no survey of the rest of the project is needed. The result is checked visually in a live preview, not by tooling.
+${asked}
+
+Then register it, which is what puts it on the rail:
+
+${register}
 
-Leave every other direction exactly as it is; they are alternatives being compared side by side, so changing a sibling destroys the comparison. The direction is already registered, so nothing needs re-registering. Keep the change additive: do not rewrite shared components that other directions rely on.`;
-  return { prompt, target };
+Name it for its idea rather than numbering it, and keep the name short enough to read in a narrow rail. Pass --asked-for exactly as given above; it is the user's own words and the interface shows them. Registering it is the last step; finish there.
+
+${SCOPE}`;
 }
 var REQUESTS_PATH = ".leglas/requests.json";
+var TERMINAL = ["failed", "cancelled"];
+function isTerminal(status) {
+  return TERMINAL.includes(status);
+}
+var FAILURE_CODES = [
+  "cancelled",
+  "stopped",
+  "missing-agent",
+  "not-signed-in",
+  "provider-overloaded",
+  "provider-limit",
+  "needs-trust",
+  "not-registered",
+  "agent-error"
+];
+function failureOf(value) {
+  if (typeof value !== "object" || value === null)
+    return null;
+  const entry = value;
+  if (typeof entry.message !== "string" || entry.message === "")
+    return null;
+  if (entry.code === void 0 || !FAILURE_CODES.includes(entry.code))
+    return null;
+  return { code: entry.code, message: entry.message };
+}
 async function readRequests(cwd) {
   try {
-    const raw = await readFile4(join5(cwd, REQUESTS_PATH), "utf8");
+    const raw = await readFile5(join6(cwd, REQUESTS_PATH), "utf8");
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed.requests))
       return [];
     return parsed.requests.map((request, index) => {
-      const entry = request;
+      const { failure: rawFailure, ...entry } = request;
+      const status = entry.status === "picked-up" || entry.status === "failed" || entry.status === "cancelled" ? entry.status : "queued";
+      const failure = isTerminal(status) ? failureOf(rawFailure) : null;
       return {
         ...entry,
         id: typeof entry.id === "string" ? entry.id : String(index),
-        status: entry.status === "picked-up" ? "picked-up" : "queued"
+        status,
+        mode: entry.mode === "variant" ? "variant" : "replace",
+        ...failure === null ? {} : { failure }
       };
     });
   } catch {
@@ -1666,23 +2048,23 @@ async function readRequests(cwd) {
   }
 }
 async function writeQueue(cwd, requests) {
-  const path = join5(cwd, REQUESTS_PATH);
-  await mkdir3(dirname4(path), { recursive: true });
-  await writeFile3(path, `${JSON.stringify({ requests }, null, 2)}
+  const path = join6(cwd, REQUESTS_PATH);
+  await mkdir4(dirname5(path), { recursive: true });
+  await writeFile4(path, `${JSON.stringify({ requests }, null, 2)}
 `, "utf8");
 }
 async function appendRequest(cwd, request) {
   await writeQueue(cwd, [
     ...await readRequests(cwd),
-    { ...request, id: randomBytes(6).toString("base64url"), status: "queued" }
+    { ...request, id: randomBytes2(6).toString("base64url"), status: "queued" }
   ]);
 }
 async function collectRequests(cwd) {
   const requests = await readRequests(cwd);
-  const collected = requests.map((request) => ({ ...request, status: "picked-up" }));
-  if (requests.some((request) => request.status !== "picked-up"))
+  const collected = requests.map((request) => isTerminal(request.status) ? request : { ...request, status: "picked-up" });
+  if (requests.some((request) => request.status === "queued"))
     await writeQueue(cwd, collected);
-  return collected;
+  return collected.filter((request) => !isTerminal(request.status));
 }
 async function markPickedUp(cwd, id) {
   const requests = await readRequests(cwd);
@@ -1691,6 +2073,17 @@ async function markPickedUp(cwd, id) {
   await writeQueue(cwd, requests.map((request) => request.id === id ? { ...request, status: "picked-up" } : request));
   return true;
 }
+async function markFailed(cwd, id, failure) {
+  const requests = await readRequests(cwd);
+  if (!requests.some((request) => request.id === id))
+    return false;
+  await writeQueue(cwd, requests.map((request) => request.id === id ? {
+    ...request,
+    status: failure.code === "cancelled" ? "cancelled" : "failed",
+    failure
+  } : request));
+  return true;
+}
 async function removeRequest(cwd, id) {
   const requests = await readRequests(cwd);
   const remaining = requests.filter((request) => request.id !== id);
@@ -1701,7 +2094,7 @@ async function removeRequest(cwd, id) {
 }
 async function clearRequests(cwd) {
   const requests = await readRequests(cwd);
-  const pending = requests.filter((request) => request.status !== "picked-up");
+  const pending = requests.filter((request) => request.status === "queued");
   const cleared = requests.length - pending.length;
   if (cleared > 0)
     await writeQueue(cwd, pending);
@@ -1710,10 +2103,13 @@ async function clearRequests(cwd) {
 
 // ../server/dist/runner.js
 import { spawn as nodeSpawn } from "child_process";
+import { readFile as readFile6 } from "fs/promises";
+import { join as join7 } from "path";
 var POLL_MS = 2e3;
 var OUTPUT_LINES = 20;
+var CANCEL_GRACE_MS = 5e3;
 var SESSION_TURNS_CAP = 8;
-function resolveCommand(choice, prompt, sessionId = null) {
+function resolveCommand(choice, prompt, sessionId = null, registration = null) {
   if (choice.agent === null)
     return null;
   if (choice.agent === "custom") {
@@ -1725,12 +2121,13 @@ function resolveCommand(choice, prompt, sessionId = null) {
     return { agent: "custom", name: "Custom", ...commandFor(parsed.template, prompt), resumed: false };
   }
   const adapter = KNOWN_AGENTS[choice.agent];
+  const allow = registration !== null && "allowArgs" in adapter ? adapter.allowArgs(registration) : [];
   if (sessionId !== null && "resumeArgs" in adapter) {
     return {
       agent: choice.agent,
       name: adapter.name,
       command: adapter.binary,
-      args: adapter.resumeArgs(sessionId, prompt),
+      args: [...adapter.resumeArgs(sessionId, prompt), ...allow],
       resumed: true
     };
   }
@@ -1738,7 +2135,7 @@ function resolveCommand(choice, prompt, sessionId = null) {
     agent: choice.agent,
     name: adapter.name,
     command: adapter.binary,
-    args: adapter.args(prompt),
+    args: [...adapter.args(prompt), ...allow],
     resumed: false
   };
 }
@@ -1768,12 +2165,17 @@ function startRunner(options) {
   const setEvery = options.setInterval ?? ((callback, milliseconds) => setInterval(callback, milliseconds));
   const clearEvery = options.clearInterval ?? ((handle2) => clearInterval(handle2));
   const failed = /* @__PURE__ */ new Set();
+  const setLater = options.setTimeout ?? ((callback, milliseconds) => {
+    setTimeout(callback, milliseconds).unref?.();
+  });
   let state = {
     running: false,
     requestId: null,
     agent: null,
     activity: null,
-    startedAt: null
+    startedAt: null,
+    stopping: false,
+    waiting: null
   };
   let stopped = false;
   let ticking = null;
@@ -1781,15 +2183,30 @@ function startRunner(options) {
   let active = null;
   const sessions = /* @__PURE__ */ new Map();
   const idle = () => {
-    state = { running: false, requestId: null, agent: null, activity: null, startedAt: null };
+    state = {
+      running: false,
+      requestId: null,
+      agent: null,
+      activity: null,
+      startedAt: null,
+      stopping: false,
+      waiting: null
+    };
   };
   const rememberLine = (lines, line) => {
     lines.push(line);
     if (lines.length > OUTPUT_LINES)
       lines.splice(0, lines.length - OUTPUT_LINES);
   };
-  const reportFailure = (request, error, lines) => {
-    console.error(`Leglas agent failed for ${request.title}: ${error}`);
+  const reportFailure = async (request, failure, lines) => {
+    await markFailed(options.cwd, request.id, failure).catch(() => {
+    });
+    failed.add(request.id);
+    if (failure.code === "cancelled") {
+      console.error(`Leglas stopped the run for ${request.title}.`);
+      return;
+    }
+    console.error(`Leglas agent failed for ${request.title}: ${failure.message}`);
     for (const line of lines)
       console.error(`  ${line}`);
   };
@@ -1807,19 +2224,31 @@ function startRunner(options) {
         error: error instanceof Error ? error.message : String(error)
       });
     }
-    const current = { child, requestId: request.id, cancelled: false };
+    const current = {
+      child,
+      requestId: request.id,
+      cancelled: false,
+      abandon: () => {
+      }
+    };
     active = current;
     const stdoutFlush = lineReader(child.stdout, (line) => {
       rememberLine(lines, line);
       const sessionId = sessionFrom(resolved.agent, line);
       if (sessionId !== null)
         observed.sessionId = sessionId;
+      const retry = retryFrom(resolved.agent, line);
+      if (retry !== null) {
+        observed.retry = retry;
+        if (active === current)
+          state = { ...state, waiting: retry };
+      }
       const activity = activityFrom(resolved.agent, line, options.cwd);
       if (activity !== null) {
         if (activity.startsWith("editing"))
           observed.edited = true;
         if (active === current)
-          state = { ...state, activity };
+          state = { ...state, activity, waiting: null };
       }
     });
     const stderrFlush = lineReader(child.stderr, (line) => rememberLine(lines, line));
@@ -1833,6 +2262,7 @@ function startRunner(options) {
         stderrFlush();
         resolve(outcome);
       };
+      current.abandon = () => settle({ ok: false, error: "cancelled" });
       child.once("error", (error) => settle({ ok: false, error: error.message }));
       child.once("close", (code, signal) => {
         if (current.cancelled)
@@ -1846,10 +2276,12 @@ function startRunner(options) {
         active = null;
     });
   };
+  const registered = () => readFile6(join7(options.cwd, LOCAL_PREVIEWS_PATH), "utf8").catch(() => null);
   const handle = async (request, choice) => {
     const session = choice.agent !== null ? sessions.get(choice.agent) ?? null : null;
     const continuable = session !== null && session.turns < SESSION_TURNS_CAP;
-    let resolved = resolveCommand(choice, request.prompt, continuable ? session.id : null);
+    const registration = request.mode === "variant" && options.leglasCommand !== void 0 ? registrationCommand(options.leglasCommand) : null;
+    let resolved = resolveCommand(choice, request.prompt, continuable ? session.id : null, registration);
     if (resolved === null)
       return;
     const lines = [];
@@ -1857,7 +2289,7 @@ function startRunner(options) {
       if (!await markPickedUp(options.cwd, request.id))
         return;
       if (stopped) {
-        failed.add(request.id);
+        await reportFailure(request, classifyFailure({ agent: resolved.name, error: "stopped by shutdown" }), []);
         return;
       }
       state = {
@@ -1865,25 +2297,47 @@ function startRunner(options) {
         requestId: request.id,
         agent: resolved.name,
         activity: null,
-        startedAt: Date.now()
+        startedAt: Date.now(),
+        stopping: false,
+        waiting: null
       };
-      const observed = { sessionId: null, edited: false };
+      const observed = {
+        sessionId: null,
+        edited: false,
+        retry: null
+      };
+      const before = request.mode === "variant" ? await registered() : null;
+      const agent = resolved.name;
       let outcome = await runChild(request, resolved, lines, observed);
-      const cancelled = !outcome.ok && outcome.error === "cancelled";
-      if (!(outcome.ok && outcome.code === 0) && resolved.resumed && !observed.edited && !cancelled && // Not redundant with the line above: a stop that lands between the
-      // first child settling and the retry starting finds no child to
-      // cancel, so nothing says "cancelled". Stopped still means stopped.
+      const verdict = () => classifyFailure({
+        agent,
+        error: outcome.ok ? null : stopped && outcome.error === "cancelled" ? "stopped by shutdown" : outcome.error,
+        exitCode: outcome.ok ? outcome.code : null,
+        lines,
+        retry: observed.retry
+      });
+      let failure = verdict();
+      if (!(outcome.ok && outcome.code === 0) && resolved.resumed && !observed.edited && sessionShaped(failure.code) && // Not redundant with the verdict: a stop that lands between the first
+      // child settling and the retry starting finds no child to cancel, so
+      // nothing says "cancelled". Stopped still means stopped.
       !stopped) {
         sessions.delete(resolved.agent);
-        const cold = resolveCommand(choice, request.prompt);
+        const cold = resolveCommand(choice, request.prompt, null, registration);
         if (cold !== null) {
           resolved = cold;
           observed.sessionId = null;
-          state = { ...state, activity: null };
+          observed.retry = null;
+          state = { ...state, activity: null, waiting: null };
           outcome = await runChild(request, resolved, lines, observed);
+          failure = verdict();
         }
       }
       if (outcome.ok && outcome.code === 0) {
+        if (request.mode === "variant" && await registered() === before) {
+          sessions.delete(resolved.agent);
+          await reportFailure(request, classifyFailure({ agent, error: "not-registered" }), lines);
+          return;
+        }
         if (observed.sessionId !== null) {
           const previous = sessions.get(resolved.agent);
           sessions.set(resolved.agent, {
@@ -1891,12 +2345,14 @@ function startRunner(options) {
             turns: resolved.resumed && previous?.id === observed.sessionId ? previous.turns + 1 : 1
           });
         }
+        if (request.mode === "replace" && request.notes !== void 0) {
+          await removeAnnotations(options.cwd, request.notes).catch(() => 0);
+        }
         await removeRequest(options.cwd, request.id);
         return;
       }
       sessions.delete(resolved.agent);
-      failed.add(request.id);
-      reportFailure(request, outcome.ok ? `${resolved.command} exited ${outcome.code}` : outcome.error, lines);
+      await reportFailure(request, failure, lines);
     } finally {
       idle();
     }
@@ -1930,12 +2386,23 @@ function startRunner(options) {
       return false;
     if (id !== void 0 && active.requestId !== id)
       return false;
-    active.cancelled = true;
-    failed.add(active.requestId);
+    const current = active;
+    current.cancelled = true;
+    failed.add(current.requestId);
+    state = { ...state, stopping: true, waiting: null };
     try {
-      active.child.kill("SIGTERM");
+      current.child.kill("SIGTERM");
     } catch {
     }
+    setLater(() => {
+      if (active !== current)
+        return;
+      try {
+        current.child.kill("SIGKILL");
+      } catch {
+      }
+      current.abandon();
+    }, CANCEL_GRACE_MS);
     return true;
   };
   const stop = () => {
@@ -1960,12 +2427,12 @@ function startRunner(options) {
 }
 
 // ../server/dist/renames.js
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5, join as join6 } from "path";
+import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname6, join as join8 } from "path";
 var RENAMES_PATH = ".leglas/renames.json";
 async function readRenames(cwd) {
   try {
-    const raw = await readFile5(join6(cwd, RENAMES_PATH), "utf8");
+    const raw = await readFile7(join8(cwd, RENAMES_PATH), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.renames === null || typeof parsed.renames !== "object")
       return {};
@@ -1975,9 +2442,9 @@ async function readRenames(cwd) {
   }
 }
 async function writeRenames(cwd, renames) {
-  const path = join6(cwd, RENAMES_PATH);
-  await mkdir4(dirname5(path), { recursive: true });
-  await writeFile4(path, `${JSON.stringify({ renames }, null, 2)}
+  const path = join8(cwd, RENAMES_PATH);
+  await mkdir5(dirname6(path), { recursive: true });
+  await writeFile5(path, `${JSON.stringify({ renames }, null, 2)}
 `, "utf8");
 }
 function resolveTitle(input, titles, renames) {
@@ -1995,7 +2462,7 @@ function resolveTitle(input, titles, renames) {
 import { createReadStream, existsSync as existsSync2, statSync } from "fs";
 import http2 from "http";
 import net3 from "net";
-import { extname, join as join7, normalize, relative as relative3 } from "path";
+import { extname, join as join9, normalize, relative as relative3 } from "path";
 var LEGLAS_PREFIX = "/leglas";
 var DEFAULT_PORT = 4100;
 var PORT_ATTEMPTS = 20;
@@ -2068,6 +2535,9 @@ function isTrustedMutation(req) {
     return false;
   }
 }
+function isEnded(request, failedIds) {
+  return isTerminal(request.status) || failedIds.includes(request.id);
+}
 function hasJsonBody(req) {
   const contentType = req.headers["content-type"];
   return typeof contentType === "string" && contentType.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
@@ -2094,7 +2564,7 @@ function probe(target, timeoutMs = 1e3) {
 }
 function serveFrom(res, dir, relativePath) {
   const relative5 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
-  const candidate = join7(dir, relative5);
+  const candidate = join9(dir, relative5);
   if (!candidate.startsWith(dir))
     return false;
   if (!existsSync2(candidate) || !statSync(candidate).isFile())
@@ -2179,7 +2649,7 @@ async function bind(server, requested) {
   throw new Error(`No free port between ${requested} and ${requested + PORT_ATTEMPTS - 1}.`);
 }
 async function startServer(options) {
-  const { config, configErrors = [], shellDir = null, project = "", cwd = process.cwd(), fileMounts = /* @__PURE__ */ new Map(), detect = () => detectAgents() } = options;
+  const { config, configErrors = [], shellDir = null, project = "", cwd = process.cwd(), leglasCommand = "npx -y leglas", fileMounts = /* @__PURE__ */ new Map(), detect = () => detectAgents() } = options;
   const target = config?.devServer ?? "http://localhost:3000";
   const proxy = createProxyHandler({ target });
   const bootConfigSnapshot = snapshotConfig(cwd);
@@ -2219,13 +2689,23 @@ async function startServer(options) {
       const notice = configStalenessNotice(cwd, bootConfigSnapshot, snapshotConfig(cwd));
       if (notice !== null)
         errors.push(notice);
-      return void readLocalPreviews(cwd).then(({ previews: local }) => {
-        const known = new Set(boot.map((preview) => preview.title));
+      return void readLocalPreviews(cwd).then(({ previews: local, errors: localErrors }) => {
+        if (localErrors.length > 0) {
+          return sendJson(res, 200, {
+            project,
+            devServer: target,
+            previews: boot,
+            errors
+          });
+        }
+        const localTitles = new Set(local.map((preview) => preview.title));
+        const currentBoot = boot.filter((preview) => preview.local !== true || localTitles.has(preview.title));
+        const known = new Set(currentBoot.map((preview) => preview.title));
         const fresh = local.filter((preview) => !known.has(preview.title) && preview.branch === void 0 && preview.file === void 0);
         sendJson(res, 200, {
           project,
           devServer: target,
-          previews: [...boot, ...fresh],
+          previews: [...currentBoot, ...fresh],
           errors
         });
       }).catch(() => sendJson(res, 200, {
@@ -2235,6 +2715,47 @@ async function startServer(options) {
         errors
       }));
     }
+    if (path === `${LEGLAS_PREFIX}/api/previews/delete` && req.method === "POST") {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", async () => {
+        let parsed;
+        try {
+          parsed = JSON.parse(body || "{}");
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        const titles = parsed.titles;
+        if (!Array.isArray(titles) || titles.length === 0 || titles.some((title) => typeof title !== "string" || title.trim() === "")) {
+          return sendJson(res, 400, {
+            ok: false,
+            error: "Body needs a non-empty array of direction titles."
+          });
+        }
+        const unique = [...new Set(titles)];
+        try {
+          const local = await readLocalPreviews(cwd);
+          if (local.errors.length > 0) {
+            return sendJson(res, 409, { ok: false, error: local.errors.join(" ") });
+          }
+          const localTitles = new Set(local.previews.map((preview) => preview.title));
+          const unknown = unique.filter((title) => !localTitles.has(title));
+          if (unknown.length > 0) {
+            return sendJson(res, 400, {
+              ok: false,
+              error: "Only machine-local directions can be deleted from the registry."
+            });
+          }
+          const deleted = await dropLocalPreviews(cwd, unique);
+          return sendJson(res, 200, { ok: true, deleted });
+        } catch {
+          return sendJson(res, 500, {
+            ok: false,
+            error: "The directions could not be deleted from Leglas."
+          });
+        }
+      });
+    }
     if (path === `${LEGLAS_PREFIX}/api/request` && req.method === "POST") {
       let body = "";
       req.on("data", (chunk) => body += chunk);
@@ -2245,16 +2766,51 @@ async function startServer(options) {
         } catch {
           return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
         }
-        const local = await readLocalPreviews(cwd).then((read) => read.previews, () => []);
-        const preview = [...config?.previews ?? [], ...local].find((entry) => entry.title === parsed.title);
-        if (!preview || !parsed.intent?.trim()) {
+        if (parsed.mode !== void 0 && parsed.mode !== "variant" && parsed.mode !== "replace") {
+          return sendJson(res, 400, {
+            ok: false,
+            error: 'mode must be "variant" or "replace".'
+          });
+        }
+        const mode = parsed.mode === "replace" ? "replace" : "variant";
+        const localRead = await readLocalPreviews(cwd).catch(() => null);
+        const local = localRead?.errors.length === 0 ? localRead.previews : [];
+        const localTitles = new Set(local.map((entry) => entry.title));
+        const bootConfig = config?.previews ?? [];
+        const boot = localRead === null || localRead.errors.length > 0 ? bootConfig : bootConfig.filter((entry) => entry.local !== true || localTitles.has(entry.title));
+        const preview = [...boot, ...local].find((entry) => entry.title === parsed.title);
+        if (!preview) {
+          return sendJson(res, 400, { ok: false, error: "Unknown preview, or empty request." });
+        }
+        const notes = annotationsFor(await readAnnotations(cwd).catch(() => []), preview.title);
+        if (!parsed.intent?.trim() && notes.length === 0) {
           return sendJson(res, 400, { ok: false, error: "Unknown preview, or empty request." });
         }
-        const composed = composeRequest(preview, parsed.intent);
+        const intent = (parsed.intent ?? "").trim();
+        const live = (await readRequests(cwd).catch(() => [])).filter((entry) => entry.status === "queued" || entry.status === "picked-up");
+        const sameNotes = (entry) => {
+          const before = [...entry.notes ?? []].sort().join(",");
+          return before === notes.map((note) => note.id).sort().join(",");
+        };
+        if (live.some((entry) => entry.title === preview.title && entry.intent === intent && // The same words in the other mode are not the same request:
+        // one forks the direction and the other rewrites it. Only a
+        // genuine repeat is refused.
+        (entry.mode ?? "replace") === mode && sameNotes(entry))) {
+          return sendJson(res, 409, {
+            ok: false,
+            duplicate: true,
+            error: `That exact change to ${preview.title} is already waiting.`
+          });
+        }
+        const composed = composeRequest(preview, intent, mode, notes, leglasCommand);
         void appendRequest(cwd, {
           title: preview.title,
           url: preview.url,
-          intent: parsed.intent.trim(),
+          intent,
+          // The ids travel with the request so a change made in place can
+          // forget the notes it answered. A fork leaves them where they are:
+          // the direction they point at was not touched.
+          ...notes.length === 0 ? {} : { notes: notes.map((entry) => entry.id) },
           ...composed
         }).then(() => {
           runner?.nudge();
@@ -2330,21 +2886,33 @@ async function startServer(options) {
         agent: null,
         activity: null,
         startedAt: null,
+        stopping: false,
+        waiting: null,
         failedIds: []
       };
       return void readRequests(cwd).then((requests) => sendJson(res, 200, {
-        requests: requests.map(({ id, title, intent, status }) => ({
+        requests: requests.map(({ id, title, intent, status, failure }) => ({
           id,
           title,
           intent,
-          status: snapshot.running && snapshot.requestId === id ? "running" : snapshot.failedIds.includes(id) ? "failed" : status
+          // The run in flight is the one thing the file cannot know. After
+          // that the file is the record, including across a restart, and the
+          // process-local failed set only covers a request whose verdict
+          // could not be written.
+          status: snapshot.running && snapshot.requestId === id ? "running" : status === "queued" && snapshot.failedIds.includes(id) ? "failed" : status,
+          failure: failure ?? null
         })),
         agent: {
           attached: externallyAttached(),
           running: snapshot.running,
           name: snapshot.running ? snapshot.agent : null,
           activity: snapshot.running ? snapshot.activity : null,
-          startedAt: snapshot.running ? snapshot.startedAt : null
+          startedAt: snapshot.running ? snapshot.startedAt : null,
+          // A stop that has been asked for but not yet obeyed. The card
+          // says so rather than going on describing a live run.
+          stopping: snapshot.running && snapshot.stopping,
+          // Why a run that looks stalled is stalled, while it is stalled.
+          waiting: snapshot.running ? snapshot.waiting : null
         }
       }));
     }
@@ -2387,8 +2955,8 @@ async function startServer(options) {
         if (request === void 0) {
           return sendJson(res, 404, { ok: false, error: "No such request." });
         }
-        if (!(runner?.snapshot().failedIds.includes(request.id) ?? false)) {
-          return sendJson(res, 400, { ok: false, error: "Only a failed request can be retried." });
+        if (!isEnded(request, runner?.snapshot().failedIds ?? [])) {
+          return sendJson(res, 400, { ok: false, error: "Only an ended request can be run again." });
         }
         try {
           if (!await removeRequest(cwd, request.id)) {
@@ -2399,7 +2967,11 @@ async function startServer(options) {
             url: request.url,
             intent: request.intent,
             target: request.target,
-            prompt: request.prompt
+            prompt: request.prompt,
+            // The stored prompt already carries the mode's instructions; the
+            // field travels with it so the queue keeps saying which kind of
+            // change this is.
+            ...request.mode === void 0 ? {} : { mode: request.mode }
           });
           runner?.nudge();
           return sendJson(res, 200, { ok: true });
@@ -2408,6 +2980,65 @@ async function startServer(options) {
         }
       });
     }
+    if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "GET") {
+      return void readAnnotations(cwd).then((annotations) => sendJson(res, 200, { annotations }));
+    }
+    if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "POST") {
+      if (!hasJsonBody(req)) {
+        return sendJson(res, 400, { ok: false, error: "A note must be JSON." });
+      }
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", async () => {
+        let parsed;
+        try {
+          parsed = JSON.parse(body || "{}");
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        if (typeof parsed.title !== "string" || parsed.title.trim() === "") {
+          return sendJson(res, 400, { ok: false, error: "A note needs a direction." });
+        }
+        const anchor = anchorFrom(parsed.anchor);
+        if (anchor === null) {
+          return sendJson(res, 400, { ok: false, error: "A note needs something to point at." });
+        }
+        try {
+          const annotation = await addAnnotation(cwd, {
+            anchor,
+            note: typeof parsed.note === "string" ? parsed.note.trim() : "",
+            title: parsed.title
+          });
+          return sendJson(res, 200, { ok: true, annotation });
+        } catch {
+          return sendJson(res, 500, { ok: false, error: "The note could not be kept." });
+        }
+      });
+    }
+    if (path === `${LEGLAS_PREFIX}/api/annotations/delete` && req.method === "POST") {
+      if (!hasJsonBody(req)) {
+        return sendJson(res, 400, { ok: false, error: "Delete must be JSON." });
+      }
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", async () => {
+        let parsed;
+        try {
+          parsed = JSON.parse(body || "{}");
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        const ids = Array.isArray(parsed.ids) ? parsed.ids.filter((entry) => typeof entry === "string") : [];
+        if (ids.length === 0) {
+          return sendJson(res, 400, { ok: false, error: "Body needs the notes to forget." });
+        }
+        try {
+          return sendJson(res, 200, { ok: true, deleted: await removeAnnotations(cwd, ids) });
+        } catch {
+          return sendJson(res, 500, { ok: false, error: "The notes could not be forgotten." });
+        }
+      });
+    }
     if (path === `${LEGLAS_PREFIX}/api/requests/dismiss` && req.method === "POST") {
       if (!hasJsonBody(req)) {
         return sendJson(res, 400, { ok: false, error: "Dismiss must be JSON." });
@@ -2424,8 +3055,9 @@ async function startServer(options) {
         if (typeof parsed.id !== "string") {
           return sendJson(res, 400, { ok: false, error: "Body needs a request id." });
         }
-        if (!(runner?.snapshot().failedIds.includes(parsed.id) ?? false)) {
-          return sendJson(res, 400, { ok: false, error: "Only a failed request can be dismissed." });
+        const target2 = (await readRequests(cwd)).find((entry) => entry.id === parsed.id);
+        if (target2 === void 0 || !isEnded(target2, runner?.snapshot().failedIds ?? [])) {
+          return sendJson(res, 400, { ok: false, error: "Only an ended request can be dismissed." });
         }
         try {
           if (!await removeRequest(cwd, parsed.id)) {
@@ -2500,7 +3132,7 @@ async function startServer(options) {
     proxy.upgrade(req, socket, head);
   });
   const port = await bind(server, options.port ?? DEFAULT_PORT);
-  runner = startRunner({ cwd, externallyAttached });
+  runner = startRunner({ cwd, externallyAttached, leglasCommand });
   let closePromise = null;
   return {
     port,
@@ -2575,11 +3207,11 @@ function planKeep(options) {
 }
 
 // src/run-init.ts
-import { readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
-import { join as join8 } from "path";
+import { readFile as readFile8, writeFile as writeFile6 } from "fs/promises";
+import { join as join10 } from "path";
 async function readIfPresent(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile8(path, "utf8");
   } catch {
     return null;
   }
@@ -2587,18 +3219,18 @@ async function readIfPresent(path) {
 async function runInit(options, deps) {
   const existingConfig = findConfigFile(options.cwd);
   const plan = planInit({
-    agents: await readIfPresent(join8(options.cwd, "AGENTS.md")),
+    agents: await readIfPresent(join10(options.cwd, "AGENTS.md")),
     config: existingConfig === null ? null : "present",
-    gitignore: await readIfPresent(join8(options.cwd, ".gitignore")),
+    gitignore: await readIfPresent(join10(options.cwd, ".gitignore")),
     force: options.force
   });
   const touched = [];
-  for (const write of plan.writes) {
-    await writeFile5(join8(options.cwd, write.path), write.contents, "utf8");
-    touched.push(write.path);
+  for (const write2 of plan.writes) {
+    await writeFile6(join10(options.cwd, write2.path), write2.contents, "utf8");
+    touched.push(write2.path);
   }
   if (plan.gitignore !== null) {
-    await writeFile5(join8(options.cwd, ".gitignore"), plan.gitignore, "utf8");
+    await writeFile6(join10(options.cwd, ".gitignore"), plan.gitignore, "utf8");
     touched.push(".gitignore");
   }
   if (options.json) {
@@ -2618,8 +3250,8 @@ async function runInit(options, deps) {
 
 // src/run-keep.ts
 import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir5, readFile as readFile7, rm as rm2, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname6, join as join9 } from "path";
+import { mkdir as mkdir6, readFile as readFile9, rm as rm2, writeFile as writeFile7 } from "fs/promises";
+import { dirname as dirname7, join as join11 } from "path";
 
 // src/resolve-title.ts
 function resolveOrExplain(input, titles, renames) {
@@ -2663,18 +3295,18 @@ async function runKeep(options, deps) {
   if (!resolved.ok) return fail(resolved.error);
   const plan = planKeep({ title: resolved.title, previews, to: options.to });
   if (!plan.ok) return fail(plan.error);
-  const from = join9(options.cwd, plan.move.from);
-  const to = join9(options.cwd, plan.move.to);
+  const from = join11(options.cwd, plan.move.from);
+  const to = join11(options.cwd, plan.move.to);
   if (!existsSync3(from)) {
     return fail(`${plan.move.from} does not exist. Nothing to keep.`);
   }
   if (existsSync3(to)) {
     return fail(`${plan.move.to} already exists. Choose another destination or move it aside.`);
   }
-  const source = await readFile7(from, "utf8");
-  await mkdir5(dirname6(to), { recursive: true });
-  await writeFile6(to, renameExport(source, plan.exportName), "utf8");
-  await rm2(join9(options.cwd, plan.removeDir), { recursive: true, force: true });
+  const source = await readFile9(from, "utf8");
+  await mkdir6(dirname7(to), { recursive: true });
+  await writeFile7(to, renameExport(source, plan.exportName), "utf8");
+  await rm2(join11(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
     deps.log(
@@ -2709,11 +3341,11 @@ async function runKeep(options, deps) {
 
 // src/run-new.ts
 import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir6, readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname7, join as join10 } from "path";
+import { mkdir as mkdir7, readFile as readFile10, writeFile as writeFile8 } from "fs/promises";
+import { dirname as dirname8, join as join12 } from "path";
 async function readIfPresent2(path) {
   try {
-    return await readFile8(path, "utf8");
+    return await readFile10(path, "utf8");
   } catch {
     return null;
   }
@@ -2721,19 +3353,19 @@ async function readIfPresent2(path) {
 async function runNew(options, deps) {
   let from;
   if (options.from !== void 0) {
-    const contents = await readIfPresent2(join10(options.cwd, options.from));
+    const contents = await readIfPresent2(join12(options.cwd, options.from));
     if (contents === null) {
-      const message = `${options.from} does not exist, so there is nothing to use as the baseline.`;
-      if (options.json) deps.log(JSON.stringify({ ok: false, error: message }));
-      else deps.log(message);
+      const message2 = `${options.from} does not exist, so there is nothing to use as the baseline.`;
+      if (options.json) deps.log(JSON.stringify({ ok: false, error: message2 }));
+      else deps.log(message2);
       return { exitCode: 1, written: [] };
     }
     from = { path: options.from, contents };
   }
   const plan = planNew({
     surface: options.surface,
-    packageJson: await readIfPresent2(join10(options.cwd, "package.json")),
-    gitignore: await readIfPresent2(join10(options.cwd, ".gitignore")),
+    packageJson: await readIfPresent2(join12(options.cwd, "package.json")),
+    gitignore: await readIfPresent2(join12(options.cwd, ".gitignore")),
     from
   });
   const fail = (error) => {
@@ -2749,26 +3381,26 @@ async function runNew(options, deps) {
       deps.log(JSON.stringify({ ok: true, files: plan.writes, instructions: plan.instructions, previews: plan.previews }));
       return { exitCode: 0, written: [] };
     }
-    for (const write of plan.writes) {
-      deps.log(`--- ${write.path}`);
-      deps.log(write.contents);
+    for (const write2 of plan.writes) {
+      deps.log(`--- ${write2.path}`);
+      deps.log(write2.contents);
     }
     deps.log(plan.instructions);
     return { exitCode: 0, written: [] };
   }
-  const existing = plan.writes.filter((write) => existsSync4(join10(options.cwd, write.path)));
+  const existing = plan.writes.filter((write2) => existsSync4(join12(options.cwd, write2.path)));
   if (existing.length > 0) {
     return fail(`${existing[0]?.path} already exists. Delete it first, or pick another surface name.`);
   }
   const written = [];
-  for (const write of plan.writes) {
-    const target = join10(options.cwd, write.path);
-    await mkdir6(dirname7(target), { recursive: true });
-    await writeFile7(target, write.contents, "utf8");
-    written.push(write.path);
+  for (const write2 of plan.writes) {
+    const target = join12(options.cwd, write2.path);
+    await mkdir7(dirname8(target), { recursive: true });
+    await writeFile8(target, write2.contents, "utf8");
+    written.push(write2.path);
   }
   if (plan.gitignore !== null) {
-    await writeFile7(join10(options.cwd, ".gitignore"), plan.gitignore, "utf8");
+    await writeFile8(join12(options.cwd, ".gitignore"), plan.gitignore, "utf8");
     written.push(".gitignore");
   }
   if (options.json) {
@@ -2789,21 +3421,21 @@ async function runNew(options, deps) {
 }
 
 // src/run-previews.ts
-import { readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
-import { join as join11 } from "path";
+import { readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
+import { join as join13 } from "path";
 function envelope(deps, ok, body) {
   deps.log(JSON.stringify({ ok, ...body }));
 }
 async function ensureIgnored(cwd) {
-  const path = join11(cwd, ".gitignore");
+  const path = join13(cwd, ".gitignore");
   let current = null;
   try {
-    current = await readFile9(path, "utf8");
+    current = await readFile11(path, "utf8");
   } catch {
     current = null;
   }
   const next = ignoreEntry(current);
-  if (next !== null) await writeFile8(path, next, "utf8");
+  if (next !== null) await writeFile9(path, next, "utf8");
 }
 async function runAdd(options, deps) {
   const loaded = await loadConfig(options.cwd);
@@ -2827,7 +3459,8 @@ async function runAdd(options, deps) {
       tags: options.preview.tags,
       branch: options.preview.branch,
       file: options.preview.file,
-      basedOn: options.preview.basedOn
+      basedOn: options.preview.basedOn,
+      askedFor: options.preview.askedFor
     },
     shared
   );
@@ -2887,6 +3520,7 @@ async function runList(options, deps) {
         note: preview.note ?? null,
         tags: preview.tags,
         basedOn: preview.basedOn ?? null,
+        askedFor: preview.askedFor ?? null,
         local: preview.local,
         branch: preview.branch ?? null,
         file: preview.file ?? null
@@ -3049,23 +3683,23 @@ async function runShow(options, deps) {
 
 // src/run-watch.ts
 import { spawn as spawn3 } from "child_process";
-import { mkdir as mkdir7, readFile as readFile10, writeFile as writeFile9 } from "fs/promises";
-import { dirname as dirname8, join as join12 } from "path";
+import { mkdir as mkdir8, readFile as readFile12, writeFile as writeFile10 } from "fs/promises";
+import { dirname as dirname9, join as join14 } from "path";
 var POLL_MS2 = 2e3;
 var HEARTBEAT_TIMEOUT_MS = 1e3;
 async function saveTemplate(cwd, run3) {
-  const path = join12(cwd, WATCH_PATH);
+  const path = join14(cwd, WATCH_PATH);
   let config = {};
   try {
-    const parsed = JSON.parse(await readFile10(path, "utf8"));
+    const parsed = JSON.parse(await readFile12(path, "utf8"));
     if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
       config = parsed;
     }
   } catch {
   }
   config.run = run3;
-  await mkdir7(dirname8(path), { recursive: true });
-  await writeFile9(path, `${JSON.stringify(config, null, 2)}
+  await mkdir8(dirname9(path), { recursive: true });
+  await writeFile10(path, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 function spawnAgent(command, args, cwd) {
@@ -3151,9 +3785,13 @@ async function runWatch(options, deps) {
       return;
     }
     failed.add(request.id);
-    deps.error(
-      `  failed  ${request.title}: ${outcome.ok ? `${command} exited ${outcome.code}` : outcome.error}`
-    );
+    const failure = classifyFailure({
+      agent: (shownCommand2.split(/\s+/)[0] ?? command).split("/").pop() ?? command,
+      error: outcome.ok ? null : outcome.error,
+      exitCode: outcome.ok ? outcome.code : null
+    });
+    await markFailed(options.cwd, request.id, failure);
+    deps.error(`  failed  ${request.title}: ${failure.message}`);
     deps.error("  Left in the queue and not retried.");
   };
   const tick = async () => {
@@ -3199,12 +3837,12 @@ async function runWatch(options, deps) {
 
 // src/run-classify.ts
 import { stat } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join15 } from "path";
 async function runClassify(options, deps) {
   const declared = await Promise.all(
     options.changes.map(async (change) => ({
       ...change,
-      exists: await stat(join13(options.cwd, change.path)).then(
+      exists: await stat(join15(options.cwd, change.path)).then(
         () => true,
         () => false
       )
@@ -3232,18 +3870,28 @@ async function runClassify(options, deps) {
 // src/run.ts
 import { existsSync as existsSync5 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname9, join as join14, relative as relative4 } from "path";
+import { basename as basename3, dirname as dirname10, join as join16, relative as relative4 } from "path";
 import { fileURLToPath } from "url";
 function findShellDir() {
-  const bundled = join14(dirname9(fileURLToPath(import.meta.url)), "shell");
-  if (existsSync5(join14(bundled, "index.html"))) return bundled;
+  const bundled = join16(dirname10(fileURLToPath(import.meta.url)), "shell");
+  if (existsSync5(join16(bundled, "index.html"))) return bundled;
   try {
     const require2 = createRequire(import.meta.url);
-    return dirname9(require2.resolve("@leglas/shell/dist/index.html"));
+    return dirname10(require2.resolve("@leglas/shell/dist/index.html"));
   } catch {
     return null;
   }
 }
+function shellWord(value) {
+  if (/^[A-Za-z0-9_./:=+\\-]+$/.test(value)) return value;
+  if (process.platform === "win32") return `"${value.replaceAll('"', '""')}"`;
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function embeddedLeglasCommand() {
+  const entry = join16(dirname10(fileURLToPath(import.meta.url)), "bin.js");
+  if (!existsSync5(entry)) return "npx -y leglas";
+  return [process.execPath, entry].map(shellWord).join(" ");
+}
 async function run2(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const local = await readLocalPreviews(options.cwd);
@@ -3273,7 +3921,7 @@ async function run2(options, deps) {
   const fileMounts = /* @__PURE__ */ new Map();
   for (const preview of merged?.previews ?? []) {
     if (preview.file !== void 0) {
-      const absolute = join14(options.cwd, preview.file);
+      const absolute = join16(options.cwd, preview.file);
       if (!existsSync5(absolute)) {
         worktreeErrors.push(
           `"${preview.title}" names file ${preview.file}, which does not exist. The preview is skipped.`
@@ -3284,7 +3932,7 @@ async function run2(options, deps) {
       for (let suffix = 2; fileMounts.has(slug); suffix += 1) {
         slug = `${worktreeSlug(preview.title) || "file"}-${suffix}`;
       }
-      fileMounts.set(slug, dirname9(absolute));
+      fileMounts.set(slug, dirname10(absolute));
       previews.push({
         ...preview,
         url: `${FILES_PREFIX}/${slug}/${encodeURIComponent(basename3(absolute))}`
@@ -3325,6 +3973,7 @@ async function run2(options, deps) {
     // directory does. Either way saved layout survives a port change.
     project: loaded.path ?? options.cwd,
     cwd: options.cwd,
+    leglasCommand: embeddedLeglasCommand(),
     ...options.port === void 0 ? {} : { port: options.port }
   });
   const url = `${server.url}${LEGLAS_PREFIX}`;