leglas 0.7.3 → 0.8.0

package/dist/bin.js

@@ -287,6 +287,19 @@ function parseArgs(argv) {
     }
     return { kind: "requests", json: rest.includes("--json"), clear: rest.includes("--clear") };
   }
+  if (argv[0] === "log") {
+    const rest = argv.slice(1);
+    const flags = rest.filter((argument) => argument.startsWith("--"));
+    const unknown = flags.find((flag) => flag !== "--json");
+    if (unknown !== void 0) {
+      return { kind: "error", message: `leglas log does not take ${unknown}.` };
+    }
+    const names = rest.filter((argument) => !argument.startsWith("--"));
+    if (names.length > 1) {
+      return { kind: "error", message: "leglas log takes one entry at most." };
+    }
+    return { kind: "log", entry: names[0] ?? null, json: flags.includes("--json") };
+  }
   if (argv[0] === "list") {
     const rest = argv.slice(1);
     const unknown = rest.find((argument) => argument !== "--json");
@@ -409,6 +422,84 @@ function parseArgs(argv) {
 import { stat as stat4 } from "fs/promises";
 import { join as join13 } from "path";
 
+// ../server/dist/log.js
+var DEFAULT_LOG_DIR = "design-log";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "untitled";
+}
+function frameFor(title, requests) {
+  let found = null;
+  for (const request of requests) {
+    if (request.title !== title)
+      continue;
+    for (const attachment of request.attachments ?? []) {
+      if (attachment.kind === "frame")
+        found = attachment;
+    }
+  }
+  return found;
+}
+function askedOf(title, requests) {
+  return requests.filter((request) => request.title === title && request.status !== "failed" && request.intent.trim() !== "").map((request) => request.intent.trim());
+}
+function composeEntry(input) {
+  const slug = `${input.date}-${slugify(input.surface)}`;
+  const pictures = [];
+  const lines2 = [];
+  lines2.push(`# ${input.surface}, ${input.date}`);
+  lines2.push("");
+  lines2.push(`**${input.won.title}** won and became \`${input.won.to}\`. ${input.previews.length === 1 ? "It was the only direction." : `${input.previews.length} directions were compared.`}`);
+  lines2.push("");
+  for (const preview of input.previews) {
+    const won = preview.title === input.won.title;
+    lines2.push(`## ${preview.title}${won ? " \u2014 kept" : ""}`);
+    lines2.push("");
+    if (preview.note !== void 0 && preview.note.trim() !== "") {
+      lines2.push(preview.note.trim());
+      lines2.push("");
+    }
+    const frame = frameFor(preview.title, input.requests);
+    if (frame !== null) {
+      const name = `${slugify(preview.title)}.png`;
+      pictures.push({ from: frame.file, to: name });
+      lines2.push(`![${preview.title}](${slug}/${name})`);
+      lines2.push("");
+    }
+    if (preview.basedOn !== void 0) {
+      lines2.push(`A variant of ${preview.basedOn}.`);
+      lines2.push("");
+    }
+    const asked = askedOf(preview.title, input.requests);
+    if (asked.length > 0) {
+      lines2.push("Asked for:");
+      lines2.push("");
+      for (const words of asked)
+        lines2.push(`- ${words}`);
+      lines2.push("");
+    }
+    const notes = input.annotations.filter((note) => note.title === preview.title);
+    if (notes.length > 0) {
+      lines2.push("Marked on the design:");
+      lines2.push("");
+      for (const note of notes)
+        lines2.push(`- ${note.note}`);
+      lines2.push("");
+    }
+  }
+  const failed = input.requests.filter((request) => request.status === "failed");
+  if (failed.length > 0) {
+    lines2.push("## Changes that did not land");
+    lines2.push("");
+    for (const request of failed) {
+      const why = request.failure?.message;
+      lines2.push(`- ${request.title}: ${request.intent}${why === void 0 ? "" : ` (${why})`}`);
+    }
+    lines2.push("");
+  }
+  return { slug, markdown: `${lines2.join("\n").trimEnd()}
+`, pictures };
+}
+
 // ../server/dist/config.js
 var DEFAULT_DEV_SERVER = "http://localhost:3000";
 var DEFAULT_INSTALL_COMMAND = "npm install";
@@ -527,6 +618,10 @@ function normalizeConfig(raw, options = {}) {
   if (requireDevCommand && previews.some((preview) => preview.branch !== void 0) && devCommand === void 0) {
     errors.push("A preview names a branch, so devCommand is required: Leglas has to start that checkout itself.");
   }
+  const logDir = source["logDir"] ?? DEFAULT_LOG_DIR;
+  if (typeof logDir !== "string" || logDir.trim() === "") {
+    errors.push("logDir must be a non-empty string.");
+  }
   const installCommand = source["installCommand"] ?? DEFAULT_INSTALL_COMMAND;
   if (typeof installCommand !== "string" || installCommand.trim() === "") {
     errors.push("installCommand must be a non-empty string.");
@@ -543,7 +638,8 @@ function normalizeConfig(raw, options = {}) {
       previews,
       scanPreviews,
       devCommand: typeof devCommand === "string" ? devCommand : void 0,
-      installCommand
+      installCommand,
+      logDir
     },
     errors: []
   };
@@ -1321,6 +1417,7 @@ import net from "net";
 function createProxyHandler(options) {
   const target = new URL(options.target);
   const host = target.hostname;
+  const dialHost = host.replace(/^\[|\]$/g, "");
   const port = Number(target.port || (target.protocol === "https:" ? 443 : 80));
   const authority = target.port ? `${host}:${target.port}` : host;
   function upstreamHeaders(req) {
@@ -1337,7 +1434,19 @@ function createProxyHandler(options) {
   }
   return {
     request(req, res, publicOrigin) {
-      const upstream = http.request({ host, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const close = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      res.once("finish", close);
+      res.once("close", close);
+      const upstream = http.request({ host: dialHost, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
         const headers = { ...upstreamRes.headers };
         const location = rewriteLocation(typeof headers.location === "string" ? headers.location : void 0, publicOrigin);
         if (location !== void 0)
@@ -1359,7 +1468,17 @@ Start it, or point Leglas somewhere else with --user-port.`);
       req.pipe(upstream);
     },
     upgrade(req, socket, head) {
-      const upstream = net.connect(port, host, () => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const closeActivity = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      const upstream = net.connect(port, dialHost, () => {
         const headers = Object.entries(upstreamHeaders(req)).map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : value}\r
 `).join("");
         upstream.write(`${req.method} ${req.url} HTTP/1.1\r
@@ -1371,6 +1490,7 @@ ${headers}\r
         socket.pipe(upstream);
       });
       const shutdown = () => {
+        closeActivity();
         upstream.destroy();
         socket.destroy();
       };
@@ -1381,6 +1501,62 @@ ${headers}\r
     }
   };
 }
+function startProxyServer(options) {
+  return new Promise((resolve5, reject) => {
+    let open = 0;
+    const handler = createProxyHandler({
+      ...options,
+      onOpen: () => {
+        open += 1;
+        options.onOpen?.();
+      },
+      onClose: () => {
+        open = Math.max(0, open - 1);
+        options.onClose?.();
+      }
+    });
+    const server = http.createServer((req, res) => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      handler.request(req, res, `http://127.0.0.1:${port}`);
+    });
+    const sockets = /* @__PURE__ */ new Set();
+    server.on("connection", (socket) => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    });
+    server.on("upgrade", (req, socket, head) => handler.upgrade(req, socket, head));
+    const onError = (error) => {
+      server.removeListener("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      let closed = null;
+      resolve5({
+        active: () => open > 0,
+        close: () => {
+          if (closed !== null)
+            return closed;
+          closed = new Promise((done) => {
+            for (const socket of sockets)
+              socket.destroy();
+            sockets.clear();
+            server.closeAllConnections();
+            server.close(() => done());
+          });
+          return closed;
+        },
+        url: `http://127.0.0.1:${port}`
+      });
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(0, "127.0.0.1");
+  });
+}
 
 // ../server/dist/browser.js
 import { randomBytes } from "crypto";
@@ -1448,12 +1624,12 @@ function buildNumber(entry) {
   const digits = /(\d+)\s*$/.exec(entry)?.[1];
   return digits === void 0 ? 0 : Number(digits);
 }
-function cacheRoots(platform, home, readdir4 = readableDirectories) {
+function cacheRoots(platform, home, readdir5 = readableDirectories) {
   const playwright = platform === "darwin" ? join4(home, "Library", "Caches", "ms-playwright") : join4(home, ".cache", "ms-playwright");
   const puppeteer = join4(home, ".cache", "puppeteer");
   const newestFirst = (dir, keep = () => true) => ({
     root: dir,
-    entries: readdir4(dir).filter(keep).sort((left, right) => buildNumber(right) - buildNumber(left))
+    entries: readdir5(dir).filter(keep).sort((left, right) => buildNumber(right) - buildNumber(left))
   });
   return [
     newestFirst(playwright, (entry) => entry.startsWith("chromium-") || entry.startsWith("chromium_headless_shell-")),
@@ -1474,13 +1650,13 @@ function findBrowser(search = {}) {
   const home = search.home ?? homedir();
   const exists = search.exists ?? existsSync2;
   const onPath = search.onPath ?? ((name) => firstOnPath(name, env));
-  const readdir4 = search.readdir ?? readableDirectories;
+  const readdir5 = search.readdir ?? readableDirectories;
   const firstExisting = (paths) => paths.find((path) => exists(path)) ?? null;
   for (const candidate of [env.LEGLAS_BROWSER, env.CHROME_PATH, env.PUPPETEER_EXECUTABLE_PATH]) {
     if (typeof candidate === "string" && candidate !== "" && exists(candidate))
       return candidate;
   }
-  const caches = cacheRoots(platform, home, readdir4);
+  const caches = cacheRoots(platform, home, readdir5);
   const shell = firstExisting(caches.flatMap(({ root, entries }) => entries.flatMap((entry) => HEADLESS_SHELL.map((rest) => join4(root, entry, ...rest)))));
   if (shell !== null)
     return shell;
@@ -1510,7 +1686,7 @@ function findBrowser(search = {}) {
   }
   if (platform === "darwin" || platform === "linux") {
     const playwrightRoot = platform === "darwin" ? join4(home, "Library", "Caches", "ms-playwright") : join4(home, ".cache", "ms-playwright");
-    const playwright = readdir4(playwrightRoot).filter((entry) => entry.startsWith("chromium-") || entry.startsWith("chromium_headless_shell-")).sort((left, right) => buildNumber(right) - buildNumber(left)).flatMap((entry) => {
+    const playwright = readdir5(playwrightRoot).filter((entry) => entry.startsWith("chromium-") || entry.startsWith("chromium_headless_shell-")).sort((left, right) => buildNumber(right) - buildNumber(left)).flatMap((entry) => {
       const root = join4(playwrightRoot, entry);
       return [
         ...FOR_TESTING.map((rest) => join4(root, ...rest)),
@@ -1527,7 +1703,7 @@ function findBrowser(search = {}) {
     const puppeteerCache = join4(home, ".cache", "puppeteer");
     for (const kind of ["chrome", "chrome-headless-shell"]) {
       const kindRoot = join4(puppeteerCache, kind);
-      const found = firstExisting(readdir4(kindRoot).sort((left, right) => buildNumber(right) - buildNumber(left)).flatMap((entry) => {
+      const found = firstExisting(readdir5(kindRoot).sort((left, right) => buildNumber(right) - buildNumber(left)).flatMap((entry) => {
         const root = join4(kindRoot, entry);
         return [...FOR_TESTING, ...HEADLESS_SHELL].map((rest) => join4(root, ...rest));
       }));
@@ -2745,6 +2921,141 @@ 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/branches.js
+var BRANCH_IDLE_MS = 10 * 60 * 1e3;
+var BRANCH_SWEEP_MS = 3e4;
+function publicBranchState(state) {
+  if (state.status === "ready")
+    return { status: "ready" };
+  return state;
+}
+function createBranchRegistry(options) {
+  const states = new Map(options.previews.map((preview) => [preview.title, { status: "idle" }]));
+  const previews = new Map(options.previews.map((preview) => [preview.title, preview]));
+  const inflight = /* @__PURE__ */ new Map();
+  const stopping = /* @__PURE__ */ new Map();
+  const lastActivity = /* @__PURE__ */ new Map();
+  const proxies = /* @__PURE__ */ new Map();
+  const boot = options.startWorktree ?? startWorktree;
+  const proxy = options.startProxy ?? startProxyServer;
+  let closed = false;
+  let stopPromise = null;
+  const transition = (title, state) => {
+    const previous = states.get(title);
+    if (previous?.status === "starting" && state.status === "starting" && previous.phase === state.phase) {
+      return previous;
+    }
+    states.set(title, state);
+    options.onChange?.(title, state);
+    return state;
+  };
+  const stopReady = (title, state, toIdle) => {
+    const current = stopping.get(title);
+    if (current !== void 0)
+      return current;
+    const pending = (async () => {
+      await proxies.get(title)?.close().catch(() => {
+      });
+      await state.worktree.stop().catch(() => {
+      });
+      proxies.delete(title);
+      lastActivity.delete(title);
+      if (toIdle && !closed && states.get(title) === state) {
+        transition(title, { status: "idle" });
+      }
+    })().finally(() => {
+      stopping.delete(title);
+    });
+    stopping.set(title, pending);
+    return pending;
+  };
+  const sweep = () => {
+    const now = Date.now();
+    for (const [title, state] of states) {
+      const branchProxy = proxies.get(title);
+      if (state.status !== "ready" || branchProxy === void 0 || stopping.has(title))
+        continue;
+      if (branchProxy.active()) {
+        lastActivity.set(title, now);
+        continue;
+      }
+      const seen = lastActivity.get(title) ?? now;
+      if (now - seen >= BRANCH_IDLE_MS)
+        void stopReady(title, state, true);
+    }
+  };
+  const sweepTimer = setInterval(sweep, BRANCH_SWEEP_MS);
+  sweepTimer.unref();
+  const begin = (title) => {
+    const preview = previews.get(title);
+    const current = states.get(title);
+    if (preview === void 0 || current === void 0 || closed)
+      return void 0;
+    if (current.status === "starting")
+      return inflight.get(title);
+    if (current.status === "ready")
+      return Promise.resolve(current);
+    transition(title, { status: "starting", phase: "checking out" });
+    let checkout;
+    try {
+      checkout = Promise.resolve(boot({
+        cwd: options.cwd,
+        branch: preview.branch,
+        installCommand: options.installCommand,
+        devCommand: options.devCommand ?? "",
+        onLog: (line) => {
+          transition(title, {
+            status: "starting",
+            phase: line.startsWith("installing ") ? "installing" : "starting"
+          });
+        }
+      }));
+    } catch (error) {
+      checkout = Promise.reject(error);
+    }
+    const starting = checkout.then(async (worktree) => {
+      transition(title, { status: "starting", phase: "starting" });
+      try {
+        const branchProxy = await proxy({
+          target: worktree.url,
+          onActivity: () => lastActivity.set(title, Date.now())
+        });
+        proxies.set(title, branchProxy);
+        lastActivity.set(title, Date.now());
+        return transition(title, { status: "ready", worktree });
+      } catch (error) {
+        await worktree.stop().catch(() => {
+        });
+        throw error;
+      }
+    }).catch((error) => transition(title, {
+      status: "failed",
+      reason: error instanceof Error ? error.message : String(error)
+    })).finally(() => {
+      inflight.delete(title);
+    });
+    inflight.set(title, starting);
+    return starting;
+  };
+  return {
+    state: (title) => states.get(title),
+    url: (title) => proxies.get(title)?.url,
+    start: begin,
+    stop: () => {
+      if (stopPromise !== null)
+        return stopPromise;
+      closed = true;
+      clearInterval(sweepTimer);
+      stopPromise = Promise.allSettled([...inflight.values()]).then(async () => {
+        await Promise.allSettled([...stopping.values()]);
+        const ready = [...states.entries()].filter((entry) => entry[1].status === "ready" && proxies.has(entry[0]));
+        await Promise.all(ready.map(([title, state]) => stopReady(title, state, false)));
+      });
+      return stopPromise;
+    }
+  };
+}
+
 // ../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/;
@@ -4835,6 +5146,7 @@ function resolveTitle(input, titles, renames) {
 
 // ../server/dist/server.js
 import { createReadStream, existsSync as existsSync3, statSync, unwatchFile, watch as watchFs, watchFile } from "fs";
+import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir8, readdir as readdir3, writeFile as writeFile8 } from "fs/promises";
 import http2 from "http";
 import net3 from "net";
@@ -4913,6 +5225,30 @@ function sendJson(res, status, body) {
   });
   res.end(payload);
 }
+function etagMatches(value, etag) {
+  if (value === void 0)
+    return false;
+  const values = Array.isArray(value) ? value : [value];
+  return values.some((header) => header.split(",").some((candidate) => {
+    const tag = candidate.trim();
+    return tag === "*" || tag === etag || tag === `W/${etag}`;
+  }));
+}
+function sendConditionalJson(req, res, body) {
+  const payload = JSON.stringify(body);
+  const etag = `"${createHash2("sha256").update(payload).digest("base64url")}"`;
+  if (etagMatches(req.headers["if-none-match"], etag)) {
+    res.writeHead(304, { etag, "cache-control": "private, no-cache" });
+    res.end();
+    return;
+  }
+  res.writeHead(200, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "private, no-cache",
+    etag
+  });
+  res.end(payload);
+}
 var CAPTURE_DEADLINE_MS = 15e3;
 var CAPTURE_LOAD_MS = Math.floor(CAPTURE_DEADLINE_MS * LOAD_SHARE);
 function captureSlug(title) {
@@ -5292,6 +5628,33 @@ async function startServer(options) {
   const { config, configErrors = [], configWarnings = [], shellDir = null, project = "", cwd = process.cwd(), leglasCommand = "npx -y leglas", fileMounts = /* @__PURE__ */ new Map(), detect = () => detectAgents() } = options;
   const browserPool = options.pool ?? createBrowserPool();
   const live = options.live ?? createLiveHub();
+  const branches = createBranchRegistry({
+    cwd,
+    previews: (config?.previews ?? []).flatMap((preview) => preview.branch === void 0 ? [] : [{ title: preview.title, branch: preview.branch }]),
+    installCommand: config?.installCommand ?? DEFAULT_INSTALL_COMMAND,
+    devCommand: config?.devCommand,
+    onChange: () => live.nudge("config"),
+    ...options.startWorktree === void 0 ? {} : { startWorktree: options.startWorktree }
+  });
+  const previewForConfig = (preview) => {
+    if (preview.branch === void 0)
+      return preview;
+    const state = branches.state(preview.title) ?? { status: "idle" };
+    const { url: route, ...withoutUrl } = preview;
+    const branchUrl = branches.url(preview.title);
+    return state.status === "ready" ? {
+      ...withoutUrl,
+      url: `${branchUrl ?? state.worktree.url}${route}`,
+      state: publicBranchState(state)
+    } : { ...withoutUrl, state: publicBranchState(state) };
+  };
+  const previewsForConfig = (previews) => previews.map(previewForConfig);
+  const readyPreview = (preview) => {
+    if (preview.branch === void 0)
+      return preview;
+    const state = branches.state(preview.title);
+    return state?.status === "ready" ? { ...preview, url: `${branches.url(preview.title) ?? state.worktree.url}${preview.url}` } : null;
+  };
   if (options.pool === void 0) {
     void reapOrphanedBrowsers().catch(() => {
     });
@@ -5325,7 +5688,7 @@ async function startServer(options) {
     }
     return Promise.resolve(agentsCache.agents);
   };
-  const livePreviews = async () => {
+  const livePreviewDefinitions = async () => {
     const localRead = await readLocalPreviews(cwd).catch(() => null);
     const local = localRead?.errors.length === 0 ? localRead.previews : [];
     const localTitles = new Set(local.map((entry) => entry.title));
@@ -5335,6 +5698,7 @@ async function startServer(options) {
     const fresh = local.filter((entry) => !known.has(entry.title) && entry.branch === void 0 && entry.file === void 0);
     return [...boot, ...fresh];
   };
+  const livePreviews = async () => (await livePreviewDefinitions()).map(readyPreview).filter((preview) => preview !== null);
   void probeAgents().catch(() => {
   });
   const server = http2.createServer((req, res) => {
@@ -5352,11 +5716,11 @@ async function startServer(options) {
         errors.push(notice);
       return void readLocalPreviews(cwd).then(({ previews: local, errors: localErrors }) => {
         if (localErrors.length > 0) {
-          return sendJson(res, 200, {
+          return sendConditionalJson(req, res, {
             project,
             devServer: target,
             scanPreviews: config?.scanPreviews ?? true,
-            previews: boot,
+            previews: previewsForConfig(boot),
             errors,
             warnings: configWarnings
           });
@@ -5365,23 +5729,58 @@ async function startServer(options) {
         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, {
+        sendConditionalJson(req, res, {
           project,
           devServer: target,
           scanPreviews: config?.scanPreviews ?? true,
-          previews: [...currentBoot, ...fresh],
+          previews: previewsForConfig([...currentBoot, ...fresh]),
           errors,
           warnings: configWarnings
         });
-      }).catch(() => sendJson(res, 200, {
+      }).catch(() => sendConditionalJson(req, res, {
         project,
         devServer: target,
         scanPreviews: config?.scanPreviews ?? true,
-        previews: boot,
+        previews: previewsForConfig(boot),
         errors,
         warnings: configWarnings
       }));
     }
+    if (path === `${LEGLAS_PREFIX}/api/previews/start` && req.method === "POST") {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", async () => {
+        const parsed2 = jsonBody(body);
+        if (parsed2 === null) {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        if (typeof parsed2.title !== "string" || parsed2.title.trim() === "") {
+          return sendJson(res, 400, { ok: false, error: "Body needs a direction title." });
+        }
+        const preview = (await livePreviewDefinitions()).find((entry) => entry.title === parsed2.title);
+        if (preview === void 0) {
+          return sendJson(res, 404, { ok: false, error: "No such direction." });
+        }
+        if (preview.branch === void 0) {
+          return sendJson(res, 400, {
+            ok: false,
+            error: `"${preview.title}" is not a branch preview.`
+          });
+        }
+        if (config?.devCommand === void 0) {
+          return sendJson(res, 400, {
+            ok: false,
+            error: `"${preview.title}" cannot start because the config sets no devCommand.`
+          });
+        }
+        void branches.start(preview.title);
+        const state = branches.state(preview.title);
+        if (state === void 0) {
+          return sendJson(res, 404, { ok: false, error: "No such branch preview." });
+        }
+        return sendJson(res, 200, { ok: true, state: publicBranchState(state) });
+      });
+    }
     if (path === `${LEGLAS_PREFIX}/api/previews/delete` && req.method === "POST") {
       let body = "";
       req.on("data", (chunk) => body += chunk);
@@ -5773,7 +6172,7 @@ async function startServer(options) {
         waiting: null,
         failedIds: []
       };
-      return void readRequests(cwd).then((requests) => sendJson(res, 200, {
+      return void readRequests(cwd).then((requests) => sendConditionalJson(req, res, {
         requests: requests.map(({ id, title, intent, mode, status, failure, notes }) => ({
           id,
           title,
@@ -5876,7 +6275,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "GET") {
-      return void readAnnotations(cwd).then((annotations) => sendJson(res, 200, { annotations }));
+      return void readAnnotations(cwd).then((annotations) => sendConditionalJson(req, res, { annotations }));
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "POST") {
       if (!hasJsonBody(req)) {
@@ -6002,7 +6401,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/health`) {
-      return void probe(target).then((reachable) => sendJson(res, 200, { devServer: target, reachable, cwd }));
+      return void probe(target).then((reachable) => sendConditionalJson(req, res, { devServer: target, reachable, cwd }));
     }
     if (path.startsWith(`${FILES_PREFIX}/`)) {
       const rest = path.slice(FILES_PREFIX.length + 1);
@@ -6076,7 +6475,12 @@ async function startServer(options) {
         return closePromise;
       liveFiles.close();
       liveHealth.close();
-      closePromise = Promise.all([runner.stop(), browserPool.close(), live.close()]).then(() => new Promise((done) => {
+      closePromise = Promise.all([
+        branches.stop(),
+        runner.stop(),
+        browserPool.close(),
+        live.close()
+      ]).then(() => new Promise((done) => {
         for (const socket of sockets)
           socket.destroy();
         sockets.clear();
@@ -6449,6 +6853,12 @@ out of the ignored directory, deletes the rest of the exploration, and drops
 them from the rail. Then change their component to use the kept component
 instead of the switcher.
 
+Keeping also writes what the exploration was into \`design-log/\`, which is
+committed. Before exploring a surface, read \`npx leglas log --json\` and any
+entry for that surface: it says what was already tried there, in the user's own
+words, and which direction won. Proposing something that was already rejected
+wastes their time, and the record is there so you do not have to ask.
+
 Useful to know:
 
 - \`.leglas/\` is gitignored. Exploration is disposable and nothing in there
@@ -6548,7 +6958,7 @@ async function runInit(options, deps) {
 
 // src/run-keep.ts
 import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
 import { dirname as dirname9, join as join15 } from "path";
 
 // src/keep.ts
@@ -6631,6 +7041,29 @@ function renameExport(source, to) {
     to
   );
 }
+async function writeLogEntry(options) {
+  const entry = composeEntry({
+    surface: options.surface,
+    won: options.won,
+    previews: options.previews,
+    requests: await readRequests(options.cwd),
+    annotations: await readAnnotations(options.cwd),
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  });
+  const dir = join15(options.cwd, options.logDir);
+  await mkdir9(dir, { recursive: true });
+  const file = join15(dir, `${entry.slug}.md`);
+  await writeFile10(file, entry.markdown, "utf8");
+  if (entry.pictures.length > 0) {
+    const pictureDir = join15(dir, entry.slug);
+    await mkdir9(pictureDir, { recursive: true });
+    for (const picture of entry.pictures) {
+      await copyFile2(join15(options.cwd, picture.from), join15(pictureDir, picture.to)).catch(() => {
+      });
+    }
+  }
+  return `${options.logDir}/${entry.slug}.md`;
+}
 async function runKeep(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const local = await readLocalPreviews(options.cwd);
@@ -6659,6 +7092,20 @@ async function runKeep(options, deps) {
   const source = await readFile13(from, "utf8");
   await mkdir9(dirname9(to), { recursive: true });
   await writeFile10(to, renameExport(source, plan.exportName), "utf8");
+  const surface = plan.removeDir.slice(plan.removeDir.lastIndexOf("/") + 1);
+  let logged = null;
+  let logError = null;
+  try {
+    logged = await writeLogEntry({
+      cwd: options.cwd,
+      logDir: loaded.config?.logDir ?? DEFAULT_LOG_DIR,
+      surface,
+      won: { title: resolved.title, to: plan.move.to },
+      previews: previews.filter((preview) => plan.dropTitles.includes(preview.title))
+    });
+  } catch (error) {
+    logError = error instanceof Error ? error.message : String(error);
+  }
   await rm5(join15(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
@@ -6670,6 +7117,8 @@ async function runKeep(options, deps) {
         exportName: plan.exportName,
         removed: plan.removeDir,
         droppedPreviews: dropped,
+        logged,
+        logError,
         instructions: plan.instructions
       })
     );
@@ -6677,6 +7126,8 @@ async function runKeep(options, deps) {
   }
   deps.log(`  kept     ${plan.move.to}`);
   deps.log(`  removed  ${plan.removeDir}`);
+  if (logged !== null) deps.log(`  logged   ${logged}`);
+  if (logError !== null) deps.error(`  The decision log could not be written: ${logError}`);
   if (dropped > 0) {
     deps.log(`  dropped  ${dropped} direction${dropped === 1 ? "" : "s"} from the rail`);
   }
@@ -6773,17 +7224,67 @@ async function runNew(options, deps) {
   return { exitCode: 0, written };
 }
 
-// src/run-previews.ts
-import { readFile as readFile15, writeFile as writeFile12 } from "fs/promises";
+// src/run-log.ts
+import { readFile as readFile15, readdir as readdir4 } from "fs/promises";
 import { join as join17 } from "path";
+function headline(markdown) {
+  const first = markdown.split("\n", 1)[0] ?? "";
+  return first.replace(/^#\s*/, "").trim();
+}
+async function runLog(options, deps) {
+  const loaded = await loadConfig(options.cwd);
+  const dir = loaded.config?.logDir ?? DEFAULT_LOG_DIR;
+  let names;
+  try {
+    names = (await readdir4(join17(options.cwd, dir))).filter((name) => name.endsWith(".md")).sort().reverse();
+  } catch {
+    names = [];
+  }
+  if (options.entry !== null) {
+    const wanted = options.entry.replace(/\.md$/, "");
+    const found = names.find((name) => name === `${wanted}.md`);
+    if (found === void 0) {
+      const error = `No entry called ${JSON.stringify(options.entry)} in ${dir}.`;
+      if (options.json) deps.log(JSON.stringify({ ok: false, error }));
+      else deps.error(error);
+      return { exitCode: 1 };
+    }
+    const markdown = await readFile15(join17(options.cwd, dir, found), "utf8");
+    if (options.json) deps.log(JSON.stringify({ ok: true, entry: wanted, markdown }));
+    else deps.log(markdown.trimEnd());
+    return { exitCode: 0 };
+  }
+  const entries = await Promise.all(
+    names.map(async (name) => ({
+      entry: name.replace(/\.md$/, ""),
+      title: headline(await readFile15(join17(options.cwd, dir, name), "utf8")),
+      file: `${dir}/${name}`
+    }))
+  );
+  if (options.json) {
+    deps.log(JSON.stringify({ ok: true, dir, entries }));
+    return { exitCode: 0 };
+  }
+  if (entries.length === 0) {
+    deps.log(`  No decisions recorded yet. One is written each time you run leglas keep.`);
+    return { exitCode: 0 };
+  }
+  const width = Math.max(...entries.map((entry) => entry.entry.length));
+  for (const entry of entries) deps.log(`  ${entry.entry.padEnd(width)}  ${entry.title}`);
+  return { exitCode: 0 };
+}
+
+// src/run-previews.ts
+import { readFile as readFile16, writeFile as writeFile12 } from "fs/promises";
+import { join as join18 } from "path";
 function envelope(deps, ok, body) {
   deps.log(JSON.stringify({ ok, ...body }));
 }
 async function ensureIgnored(cwd) {
-  const path = join17(cwd, ".gitignore");
+  const path = join18(cwd, ".gitignore");
   let current = null;
   try {
-    current = await readFile15(path, "utf8");
+    current = await readFile16(path, "utf8");
   } catch {
     current = null;
   }
@@ -7110,15 +7611,15 @@ async function runShow(options, deps) {
 
 // src/run-watch.ts
 import { spawn as spawn3 } from "child_process";
-import { mkdir as mkdir11, readFile as readFile16, writeFile as writeFile13 } from "fs/promises";
-import { dirname as dirname11, join as join18 } from "path";
+import { mkdir as mkdir11, readFile as readFile17, writeFile as writeFile13 } from "fs/promises";
+import { dirname as dirname11, join as join19 } from "path";
 var POLL_MS2 = 2e3;
 var HEARTBEAT_TIMEOUT_MS = 1e3;
 async function saveTemplate(cwd, run4) {
-  const path = join18(cwd, WATCH_PATH);
+  const path = join19(cwd, WATCH_PATH);
   let config = {};
   try {
-    const parsed2 = JSON.parse(await readFile16(path, "utf8"));
+    const parsed2 = JSON.parse(await readFile17(path, "utf8"));
     if (typeof parsed2 === "object" && parsed2 !== null && !Array.isArray(parsed2)) {
       config = parsed2;
     }
@@ -7267,7 +7768,7 @@ async function runWatch(options, deps) {
 import { existsSync as existsSync6 } from "fs";
 import { realpath as realpath4 } from "fs/promises";
 import { createRequire } from "module";
-import { basename as basename6, dirname as dirname12, join as join19, relative as relative5, resolve as resolve4 } from "path";
+import { basename as basename6, dirname as dirname12, join as join20, relative as relative5, resolve as resolve4 } from "path";
 import { fileURLToPath } from "url";
 
 // src/dev-server-owner.ts
@@ -7353,8 +7854,8 @@ function devServerOwnerWarning(origin, projectRoot, owners) {
 
 // src/run.ts
 function findShellDir() {
-  const bundled = join19(dirname12(fileURLToPath(import.meta.url)), "shell");
-  if (existsSync6(join19(bundled, "index.html"))) return bundled;
+  const bundled = join20(dirname12(fileURLToPath(import.meta.url)), "shell");
+  if (existsSync6(join20(bundled, "index.html"))) return bundled;
   try {
     const require2 = createRequire(import.meta.url);
     return dirname12(require2.resolve("@leglas/shell/dist/index.html"));
@@ -7368,7 +7869,7 @@ function shellWord(value) {
   return `'${value.replaceAll("'", `'\\''`)}'`;
 }
 function embeddedLeglasCommand() {
-  const entry = join19(dirname12(fileURLToPath(import.meta.url)), "bin.js");
+  const entry = join20(dirname12(fileURLToPath(import.meta.url)), "bin.js");
   if (!existsSync6(entry)) return "npx -y leglas";
   return [process.execPath, entry].map(shellWord).join(" ");
 }
@@ -7377,8 +7878,7 @@ async function run3(options, deps) {
   const local = await readLocalPreviews(options.cwd);
   let devServer = options.userPort === void 0 ? loaded.config?.devServer ?? "http://localhost:3000" : `http://localhost:${options.userPort}`;
   const merged = loaded.config === null ? null : { ...loaded.config, devServer, previews: [...loaded.config.previews, ...local.previews] };
-  const worktrees = [];
-  const worktreeErrors = [];
+  const previewErrors = [];
   const previews = [];
   let app = null;
   const needsApp = (merged?.previews ?? []).some(
@@ -7395,15 +7895,15 @@ async function run3(options, deps) {
       devServer = app.url;
       merged.devServer = app.url;
     } catch (error) {
-      worktreeErrors.push(error instanceof Error ? error.message : String(error));
+      previewErrors.push(error instanceof Error ? error.message : String(error));
     }
   }
   const fileMounts = /* @__PURE__ */ new Map();
   for (const preview of merged?.previews ?? []) {
     if (preview.file !== void 0) {
-      const absolute = join19(options.cwd, preview.file);
+      const absolute = join20(options.cwd, preview.file);
       if (!existsSync6(absolute)) {
-        worktreeErrors.push(
+        previewErrors.push(
           `"${preview.title}" names file ${preview.file}, which does not exist. The preview is skipped.`
         );
         continue;
@@ -7419,29 +7919,7 @@ async function run3(options, deps) {
       });
       continue;
     }
-    if (preview.branch === void 0) {
-      previews.push(preview);
-      continue;
-    }
-    if (merged?.devCommand === void 0) {
-      worktreeErrors.push(
-        `"${preview.title}" names branch ${preview.branch}, but the config sets no devCommand, so Leglas cannot start that checkout. Add devCommand (with {port}) to the config.`
-      );
-      continue;
-    }
-    if (!options.json) deps.log(`  starting ${preview.branch}\u2026`);
-    try {
-      const worktree = await startWorktree({
-        cwd: options.cwd,
-        branch: preview.branch,
-        installCommand: merged.installCommand,
-        devCommand: merged.devCommand
-      });
-      worktrees.push(worktree);
-      previews.push({ ...preview, url: `${worktree.url}${preview.url}` });
-    } catch (error) {
-      worktreeErrors.push(error instanceof Error ? error.message : String(error));
-    }
+    previews.push(preview);
   }
   const config = merged === null ? null : { ...merged, previews };
   const configWarnings = [];
@@ -7451,7 +7929,7 @@ async function run3(options, deps) {
   const ownerWarning = needsApp && app === null ? inspectLocalDevServer(devServer).then((owners) => devServerOwnerWarning(devServer, projectRoot, owners)).catch(() => null) : Promise.resolve(null);
   const serverPromise = startServer({
     config,
-    configErrors: [...loaded.errors, ...local.errors, ...worktreeErrors],
+    configErrors: [...loaded.errors, ...local.errors, ...previewErrors],
     configWarnings,
     fileMounts,
     shellDir: findShellDir(),
@@ -7490,9 +7968,9 @@ async function run3(options, deps) {
     );
     deps.log(`config   ${configLabel}`);
     deps.log(`          ${previewCount} preview${previewCount === 1 ? "" : "s"}`);
-    if (loaded.errors.length + worktreeErrors.length > 0) {
+    if (loaded.errors.length + previewErrors.length > 0) {
       deps.log("");
-      for (const error of [...loaded.errors, ...worktreeErrors]) deps.log(`  ! ${error}`);
+      for (const error of [...loaded.errors, ...previewErrors]) deps.log(`  ! ${error}`);
       deps.log("  Fix the config and reload; Leglas will pick it up on restart.");
     }
     if (configWarnings.length > 0) {
@@ -7515,8 +7993,6 @@ async function run3(options, deps) {
     devServer,
     previewCount,
     stop: async () => {
-      await Promise.all(worktrees.map((worktree) => worktree.stop().catch(() => {
-      })));
       await app?.stop().catch(() => {
       });
       await server.close();
@@ -7547,6 +8023,7 @@ Usage
   leglas classify            Decide where a direction should live
   leglas add --title T --url U   Register a preview on this machine
   leglas list                Show every preview, shared and local
+  leglas log [entry]         What past explorations decided
   leglas show <title>        Everything Leglas knows about one direction
   leglas requests            Show change requests made from the interface
   leglas watch --run "<cmd>" Hand each request to your agent as it arrives
@@ -7684,6 +8161,13 @@ if (parsed.kind === "watch") {
   );
   process.exit(outcome.exitCode);
 }
+if (parsed.kind === "log") {
+  const outcome = await runLog(
+    { entry: parsed.entry, json: parsed.json, cwd: process.cwd() },
+    previewDeps
+  );
+  process.exit(outcome.exitCode);
+}
 if (parsed.kind === "list") {
   const outcome = await runList({ json: parsed.json, cwd: process.cwd() }, previewDeps);
   process.exit(outcome.exitCode);