leglas 0.7.4 → 0.8.0

package/README.md

@@ -196,7 +196,14 @@ edit the hero. The supporting commands:
   a direction from the rail hands over a block that ends in this command, so
   an agent given the block can go and get the rest.
 - `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
-  into real source and ends the exploration.
+  into real source and ends the exploration. It also writes down what the
+  exploration was, into `design-log/`: every direction with its note, the words
+  you typed at each of them, the captures the agent was sent, and which one
+  won. Plain markdown and PNGs, committed, so a pull request can link it and
+  somebody can read it in three months without this tool. Exploring is
+  episodic, and the archive is what makes coming back to a surface cheaper than
+  starting over. `npx leglas log` lists what is there. Set `logDir` if you want
+  it somewhere else.
 
 Asking for a change works from the interface too. Type what you want
 changed into the field under the rail (or press `R`) and Leglas composes a
@@ -388,6 +395,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

package/dist/args.d.ts

@@ -44,6 +44,10 @@ export type ParseResult = {
 } | {
     kind: "list";
     json: boolean;
+} | {
+    kind: "log";
+    entry: string | null;
+    json: boolean;
 } | {
     kind: "show";
     title: string;

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));
       }));
@@ -2746,6 +2922,8 @@ async function startAppProcess(options) {
 }
 
 // ../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" };
@@ -2755,7 +2933,11 @@ 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) => {
@@ -2767,6 +2949,43 @@ function createBranchRegistry(options) {
     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);
@@ -2794,9 +3013,21 @@ function createBranchRegistry(options) {
     } catch (error) {
       checkout = Promise.reject(error);
     }
-    const starting = checkout.then((worktree) => {
+    const starting = checkout.then(async (worktree) => {
       transition(title, { status: "starting", phase: "starting" });
-      return transition(title, { status: "ready", worktree });
+      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)
@@ -2808,15 +3039,17 @@ function createBranchRegistry(options) {
   };
   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 () => {
-        const worktrees = [...states.values()].filter((state) => state.status === "ready").map((state) => state.worktree);
-        await Promise.all(worktrees.map((worktree) => worktree.stop().catch(() => {
-        })));
+        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;
     }
@@ -4913,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";
@@ -4991,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) {
@@ -5383,9 +5641,10 @@ async function startServer(options) {
       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: `${state.worktree.url}${route}`,
+      url: `${branchUrl ?? state.worktree.url}${route}`,
       state: publicBranchState(state)
     } : { ...withoutUrl, state: publicBranchState(state) };
   };
@@ -5394,7 +5653,7 @@ async function startServer(options) {
     if (preview.branch === void 0)
       return preview;
     const state = branches.state(preview.title);
-    return state?.status === "ready" ? { ...preview, url: `${state.worktree.url}${preview.url}` } : null;
+    return state?.status === "ready" ? { ...preview, url: `${branches.url(preview.title) ?? state.worktree.url}${preview.url}` } : null;
   };
   if (options.pool === void 0) {
     void reapOrphanedBrowsers().catch(() => {
@@ -5457,7 +5716,7 @@ 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,
@@ -5470,7 +5729,7 @@ 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,
@@ -5478,7 +5737,7 @@ async function startServer(options) {
           errors,
           warnings: configWarnings
         });
-      }).catch(() => sendJson(res, 200, {
+      }).catch(() => sendConditionalJson(req, res, {
         project,
         devServer: target,
         scanPreviews: config?.scanPreviews ?? true,
@@ -5913,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,
@@ -6016,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)) {
@@ -6142,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);
@@ -6594,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
@@ -6693,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
@@ -6776,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);
@@ -6804,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) {
@@ -6815,6 +7117,8 @@ async function runKeep(options, deps) {
         exportName: plan.exportName,
         removed: plan.removeDir,
         droppedPreviews: dropped,
+        logged,
+        logError,
         instructions: plan.instructions
       })
     );
@@ -6822,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`);
   }
@@ -6918,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;
   }
@@ -7255,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;
     }
@@ -7412,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
@@ -7498,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"));
@@ -7513,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(" ");
 }
@@ -7545,7 +7901,7 @@ async function run3(options, deps) {
   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)) {
         previewErrors.push(
           `"${preview.title}" names file ${preview.file}, which does not exist. The preview is skipped.`
@@ -7667,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
@@ -7804,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);

package/dist/index.js

@@ -281,6 +281,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");
@@ -725,6 +738,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
@@ -785,6 +804,84 @@ ${AGENTS_SECTION}`
 // src/keep.ts
 import { basename as basename4, extname as extname4, normalize as normalize2 } 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";
@@ -903,6 +1000,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.");
@@ -919,7 +1020,8 @@ function normalizeConfig(raw, options = {}) {
       previews,
       scanPreviews,
       devCommand: typeof devCommand === "string" ? devCommand : void 0,
-      installCommand
+      installCommand,
+      logDir
     },
     errors: []
   };
@@ -1697,6 +1799,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) {
@@ -1713,7 +1816,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)
@@ -1735,7 +1850,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
@@ -1747,6 +1872,7 @@ ${headers}\r
         socket.pipe(upstream);
       });
       const shutdown = () => {
+        closeActivity();
         upstream.destroy();
         socket.destroy();
       };
@@ -1757,6 +1883,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";
@@ -3122,6 +3304,8 @@ async function startAppProcess(options) {
 }
 
 // ../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" };
@@ -3131,7 +3315,11 @@ 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) => {
@@ -3143,6 +3331,43 @@ function createBranchRegistry(options) {
     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);
@@ -3170,9 +3395,21 @@ function createBranchRegistry(options) {
     } catch (error) {
       checkout = Promise.reject(error);
     }
-    const starting = checkout.then((worktree) => {
+    const starting = checkout.then(async (worktree) => {
       transition(title, { status: "starting", phase: "starting" });
-      return transition(title, { status: "ready", worktree });
+      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)
@@ -3184,15 +3421,17 @@ function createBranchRegistry(options) {
   };
   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 () => {
-        const worktrees = [...states.values()].filter((state) => state.status === "ready").map((state) => state.worktree);
-        await Promise.all(worktrees.map((worktree) => worktree.stop().catch(() => {
-        })));
+        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;
     }
@@ -5289,6 +5528,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";
@@ -5367,6 +5607,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) {
@@ -5759,9 +6023,10 @@ async function startServer(options) {
       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: `${state.worktree.url}${route}`,
+      url: `${branchUrl ?? state.worktree.url}${route}`,
       state: publicBranchState(state)
     } : { ...withoutUrl, state: publicBranchState(state) };
   };
@@ -5770,7 +6035,7 @@ async function startServer(options) {
     if (preview.branch === void 0)
       return preview;
     const state = branches.state(preview.title);
-    return state?.status === "ready" ? { ...preview, url: `${state.worktree.url}${preview.url}` } : null;
+    return state?.status === "ready" ? { ...preview, url: `${branches.url(preview.title) ?? state.worktree.url}${preview.url}` } : null;
   };
   if (options.pool === void 0) {
     void reapOrphanedBrowsers().catch(() => {
@@ -5833,7 +6098,7 @@ 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,
@@ -5846,7 +6111,7 @@ 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,
@@ -5854,7 +6119,7 @@ async function startServer(options) {
           errors,
           warnings: configWarnings
         });
-      }).catch(() => sendJson(res, 200, {
+      }).catch(() => sendConditionalJson(req, res, {
         project,
         devServer: target,
         scanPreviews: config?.scanPreviews ?? true,
@@ -6289,7 +6554,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,
@@ -6392,7 +6657,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)) {
@@ -6518,7 +6783,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);
@@ -6708,7 +6973,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 join14 } from "path";
 
 // src/resolve-title.ts
@@ -6736,6 +7001,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 = join14(options.cwd, options.logDir);
+  await mkdir9(dir, { recursive: true });
+  const file = join14(dir, `${entry.slug}.md`);
+  await writeFile10(file, entry.markdown, "utf8");
+  if (entry.pictures.length > 0) {
+    const pictureDir = join14(dir, entry.slug);
+    await mkdir9(pictureDir, { recursive: true });
+    for (const picture of entry.pictures) {
+      await copyFile2(join14(options.cwd, picture.from), join14(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);
@@ -6764,6 +7052,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(join14(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
@@ -6775,6 +7077,8 @@ async function runKeep(options, deps) {
         exportName: plan.exportName,
         removed: plan.removeDir,
         droppedPreviews: dropped,
+        logged,
+        logError,
         instructions: plan.instructions
       })
     );
@@ -6782,6 +7086,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`);
   }

package/dist/run-log.d.ts

@@ -0,0 +1,20 @@
+export type LogDeps = {
+    log(line: string): void;
+    error(line: string): void;
+};
+/**
+ * Read what past explorations decided.
+ *
+ * The entries are plain markdown in a committed directory and are meant to be
+ * read that way, in a pull request or on GitHub. This exists because an agent
+ * asked to work on a surface should be able to find what was already tried
+ * there without being told where to look, and because a person coming back to
+ * a project should not have to know the directory's name.
+ */
+export declare function runLog(options: {
+    entry: string | null;
+    json: boolean;
+    cwd: string;
+}, deps: LogDeps): Promise<{
+    exitCode: number;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leglas",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Compare design directions inside your own running app.",
   "license": "MIT",
   "repository": {