pi-central 0.6.1 → 0.8.0

package/bin/pi-central.js

@@ -25,7 +25,7 @@ function isBlockingDialog(record) {
 }
 
 // packages/protocol/src/envelopes.ts
-var PROTOCOL_VERSION = 4;
+var PROTOCOL_VERSION = 5;
 
 // packages/protocol/src/own-installation.ts
 var PIPELINE_MARKERS = ["packages/orchestrator", "packages/ui", "packages/protocol"];
@@ -271,8 +271,8 @@ function isScratch(config, cwd) {
 
 // packages/orchestrator/src/supervisor.ts
 import { EventEmitter as EventEmitter2 } from "node:events";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join10 } from "node:path";
 
 // packages/orchestrator/src/policy.ts
 import { accessSync, constants, mkdirSync, statSync as statSync2, writeFileSync } from "node:fs";
@@ -492,6 +492,24 @@ var RpcProcess = class extends EventEmitter {
   #stderr = "";
   #stopping = false;
   #exited = false;
+  /**
+   * True when the process never started at all (`spawn` failed).
+   *
+   * Node's contract for a failed spawn is `error` and **no `exit`**. Every wait below is on
+   * `exit`, so treating that case as "still running" made `stop()` wait out its timers for a
+   * process that does not exist — and because those timers are `unref`'d, the event loop could
+   * drain first and take the caller's promise with it.
+   *
+   * Found through the startup restore (issue #185): a fleet of restored sessions on a host where
+   * the binary is missing (C10 — `safehouse` is macOS-only) is a fleet of failed spawns, and
+   * shutdown then never finished. It was always reachable by hand; restoring made it the normal
+   * path.
+   *
+   * `child.pid === undefined` is the precise signal, which is why it is the condition rather than
+   * "any `error` event": a runtime error on a started process still has a pid, and it still gets
+   * its `exit`.
+   */
+  #spawnFailed = false;
   constructor(launch) {
     super();
     this.launch = launch;
@@ -516,19 +534,29 @@ var RpcProcess = class extends EventEmitter {
       this.#stderr += text;
       this.emit("stderr", text);
     });
-    child.on("error", (error) => this.emit("failed", error));
+    child.on("error", (error) => {
+      if (child.pid === void 0) {
+        this.#spawnFailed = true;
+        this.#rejectPending(`could not start ${this.launch.command}: ${error.message}`);
+      }
+      this.emit("failed", error);
+    });
     child.on("exit", (code, signal) => {
       this.#exited = true;
       for (const record of this.#decoder.flush()) this.#dispatch(record);
-      for (const [, pending] of this.#pending) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error(`pi exited before responding (code=${code ?? "-"}, signal=${signal ?? "-"})`));
-      }
-      this.#pending.clear();
+      this.#rejectPending(`pi exited before responding (code=${code ?? "-"}, signal=${signal ?? "-"})`);
       this.emit("exit", { code, signal, stderr: this.stderrTail });
     });
     return this;
   }
+  /** Reject every in-flight command with one reason, clearing their timers. */
+  #rejectPending(reason) {
+    for (const [, pending] of this.#pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(reason));
+    }
+    this.#pending.clear();
+  }
   #dispatch(record) {
     if (record.type === "response" && typeof record.id === "string") {
       const pending = this.#pending.get(record.id);
@@ -562,13 +590,13 @@ var RpcProcess = class extends EventEmitter {
     const child = this.#child;
     if (!child || !child.stdin.writable) return Promise.reject(new Error("session is not running"));
     const id = `c${++this.#seq}`;
-    return new Promise((resolve9, reject) => {
+    return new Promise((resolve10, reject) => {
       const timer = setTimeout(() => {
         this.#pending.delete(id);
         reject(new Error(`timeout after ${timeoutMs}ms waiting for ${command.type}`));
       }, timeoutMs);
       timer.unref?.();
-      this.#pending.set(id, { resolve: resolve9, reject, timer });
+      this.#pending.set(id, { resolve: resolve10, reject, timer });
       child.stdin.write(encodeLine({ ...command, id }));
     });
   }
@@ -590,7 +618,7 @@ var RpcProcess = class extends EventEmitter {
     if (this.#stopping) return;
     this.#stopping = true;
     const child = this.#child;
-    if (!child || this.#exited) return;
+    if (!child || this.#exited || this.#spawnFailed) return;
     try {
       child.stdin.end();
     } catch {
@@ -610,14 +638,16 @@ var RpcProcess = class extends EventEmitter {
   }
   #waitForExit(ms) {
     const child = this.#child;
-    if (!child || this.#exited) return Promise.resolve(true);
-    return new Promise((resolve9) => {
-      const timer = setTimeout(() => resolve9(this.#exited), ms);
-      timer.unref?.();
-      child.once("exit", () => {
+    if (!child || this.#exited || this.#spawnFailed) return Promise.resolve(true);
+    return new Promise((resolve10) => {
+      const settle = () => {
         clearTimeout(timer);
-        resolve9(true);
-      });
+        resolve10(true);
+      };
+      const timer = setTimeout(() => resolve10(this.#exited || this.#spawnFailed), ms);
+      timer.unref?.();
+      child.once("exit", settle);
+      this.once("failed", settle);
     });
   }
   get stderrTail() {
@@ -625,7 +655,7 @@ var RpcProcess = class extends EventEmitter {
   }
   get running() {
     const child = this.#child;
-    return child !== null && !this.#exited;
+    return child !== null && !this.#exited && !this.#spawnFailed;
   }
 };
 
@@ -716,18 +746,336 @@ Restore it, or start a new session in the directory you want to work in. Pi Cent
   return { ok: true, cwd: resolve4(session.cwd) };
 }
 
+// packages/orchestrator/src/open-sessions.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, realpathSync, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname, join as join5, resolve as resolve5 } from "node:path";
+function normalizeSessionFile(sessionFile) {
+  try {
+    return realpathSync(sessionFile);
+  } catch {
+    return resolve5(sessionFile);
+  }
+}
+function openSessionsPath(stateRoot) {
+  return join5(stateRoot, "open-sessions.json");
+}
+function readOpenSessions(stateRoot) {
+  const path = openSessionsPath(stateRoot);
+  let text;
+  try {
+    text = readFileSync2(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { sessions: [] };
+    return { sessions: [], note: `could not read ${path}: ${error.message}` };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { sessions: [], note: `${path} is not valid JSON, so no sessions were restored` };
+  }
+  const shape = parsed;
+  if (typeof shape !== "object" || shape === null || shape.version !== 1 || !Array.isArray(shape.sessions)) {
+    return { sessions: [], note: `${path} is not a recognised open-sessions file, so no sessions were restored` };
+  }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const entry of shape.sessions) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { sessionFile, mode } = entry;
+    if (typeof sessionFile !== "string" || sessionFile.length === 0) continue;
+    if (sessionFile.includes("\0")) continue;
+    const canonical = normalizeSessionFile(sessionFile);
+    byFile.set(canonical, { sessionFile: canonical, mode: mode === "direct" ? "direct" : "sandboxed" });
+  }
+  return { sessions: [...byFile.values()] };
+}
+function writeOpenSessions(stateRoot, sessions) {
+  const path = openSessionsPath(stateRoot);
+  const body = { version: 1, sessions };
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync2(dirname(path), { recursive: true });
+    writeFileSync2(temporary, `${JSON.stringify(body, null, 2)}
+`, "utf8");
+    renameSync(temporary, path);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: `could not write ${path}: ${error.message}` };
+  }
+}
+var OpenSessionStore = class {
+  #stateRoot;
+  #entries = /* @__PURE__ */ new Map();
+  #warned = false;
+  constructor(stateRoot) {
+    this.#stateRoot = stateRoot;
+  }
+  /**
+   * Load the remembered set from disk, reporting anything the reader should know.
+   *
+   * Separate from the constructor because it touches the filesystem and can produce a note the
+   * startup log must print — the same shape `readOpenSessions` returns.
+   */
+  load() {
+    const { sessions, note } = readOpenSessions(this.#stateRoot);
+    this.#entries = new Map(sessions.map((entry) => [entry.sessionFile, entry]));
+    return note === void 0 ? { sessions } : { sessions, note };
+  }
+  /** Every remembered session, in insertion order. */
+  list() {
+    return [...this.#entries.values()];
+  }
+  has(sessionFile) {
+    return this.#entries.has(normalizeSessionFile(sessionFile));
+  }
+  /** Remember a session. A no-op (and no write) when nothing changed. */
+  remember(sessionFile, mode) {
+    if (sessionFile === void 0) return;
+    const canonical = normalizeSessionFile(sessionFile);
+    const existing = this.#entries.get(canonical);
+    if (existing !== void 0 && existing.mode === mode) return;
+    this.#entries.set(canonical, { sessionFile: canonical, mode });
+    this.#changed();
+  }
+  /** Forget a session — an EXPLICIT stop, never a shutdown. */
+  forget(sessionFile) {
+    if (sessionFile === void 0) return;
+    if (!this.#entries.delete(normalizeSessionFile(sessionFile))) return;
+    this.#changed();
+  }
+  /**
+   * Write the current set.
+   *
+   * The warning is printed once per process: a state root that cannot be written would otherwise
+   * produce a line on every session start and stop, which trains a reader to ignore it.
+   */
+  #changed() {
+    const result = writeOpenSessions(this.#stateRoot, this.list());
+    if (result.ok || this.#warned) return;
+    this.#warned = true;
+    console.error(`Sessions will not be restored after a restart: ${result.message}`);
+  }
+};
+
+// packages/orchestrator/src/registry.ts
+import { createReadStream, readdirSync as readdirSync2, realpathSync as realpathSync2, statSync as statSync5 } from "node:fs";
+import { basename, dirname as dirname2, join as join6, resolve as resolve6, sep as sep2 } from "node:path";
+var KNOWN_SESSION_VERSIONS = /* @__PURE__ */ new Set([3]);
+var HEAD_BYTES = 256 * 1024;
+var TAIL_BYTES = 8 * 1024;
+function decodeSessionDir(dirName) {
+  const inner = dirName.replace(/^--/, "").replace(/--$/, "");
+  return `/${inner.replace(/-/g, "/")}`;
+}
+async function readLateSessionName(path) {
+  let stats;
+  try {
+    stats = statSync5(path);
+  } catch {
+    return void 0;
+  }
+  const start = Math.max(0, stats.size - TAIL_BYTES);
+  if (start === 0) return void 0;
+  const text = await new Promise((resolve10) => {
+    const chunks = [];
+    const stream = createReadStream(path, { start, end: stats.size - 1 });
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("error", () => resolve10(""));
+    stream.on("close", () => resolve10(Buffer.concat(chunks).toString("utf8")));
+  });
+  if (text === "") return void 0;
+  const lines = text.split("\n");
+  lines.shift();
+  let name;
+  for (const line of lines) {
+    if (!line.includes('"session_info"')) continue;
+    try {
+      const record = JSON.parse(line);
+      if (record.type === "session_info" && typeof record.name === "string") {
+        const trimmed = record.name.trim();
+        if (trimmed.length > 0) name = trimmed;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return name;
+}
+async function readHead(path) {
+  return new Promise((resolve10) => {
+    const chunks = [];
+    let size = 0;
+    const stream = createReadStream(path, { start: 0, end: HEAD_BYTES - 1 });
+    stream.on("data", (chunk) => {
+      chunks.push(chunk);
+      size += chunk.length;
+    });
+    stream.on("error", () => resolve10(""));
+    stream.on("close", () => resolve10(Buffer.concat(chunks, size).toString("utf8")));
+  });
+}
+function parseHead(text) {
+  const lines = text.split("\n");
+  let header = null;
+  let name;
+  let firstMessage = "";
+  let messageCount = 0;
+  for (const line of lines) {
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      if (!header) continue;
+      break;
+    }
+    if (!header) {
+      if (record.type !== "session") return null;
+      if (typeof record.id !== "string" || typeof record.cwd !== "string") return null;
+      header = {
+        type: "session",
+        version: Number(record.version ?? 0),
+        id: record.id,
+        timestamp: String(record.timestamp ?? ""),
+        cwd: record.cwd,
+        ...typeof record.parentSession === "string" ? { parentSession: record.parentSession } : {}
+      };
+      continue;
+    }
+    if (record.type === "session_info" && typeof record.name === "string") {
+      name = record.name.trim() || void 0;
+      continue;
+    }
+    if (record.type === "message") {
+      messageCount += 1;
+      if (!firstMessage) {
+        const message = record.message;
+        if (message?.role === "user") firstMessage = flattenContent(message.content).slice(0, 200);
+      }
+    }
+  }
+  return header ? { header, name, firstMessage, messageCount } : null;
+}
+function flattenContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === "string") return part;
+      if (part && typeof part === "object" && "text" in part) return String(part.text);
+      return "";
+    }).join(" ");
+  }
+  return "";
+}
+async function describeSessionFile(config, path, projectDir, stats) {
+  const head = await readHead(path);
+  const parsed = parseHead(head);
+  if (!parsed) return { ok: false, reason: "not a Pi session file (no valid header)" };
+  const lateName = stats.size > HEAD_BYTES ? await readLateSessionName(path) : void 0;
+  if (!KNOWN_SESSION_VERSIONS.has(parsed.header.version)) {
+    return { ok: false, reason: `unknown session version ${parsed.header.version}` };
+  }
+  const cwd = parsed.header.cwd || decodeSessionDir(projectDir);
+  return {
+    ok: true,
+    session: {
+      path,
+      id: parsed.header.id,
+      cwd,
+      // The late name wins: it is the most recent rename, and the head's is the earliest one.
+      ...lateName ?? parsed.name ? { name: lateName ?? parsed.name } : {},
+      created: parsed.header.timestamp,
+      modifiedMs: stats.mtimeMs,
+      bytes: stats.size,
+      messageCount: parsed.messageCount,
+      firstMessage: parsed.firstMessage,
+      cwdExists: directoryExists(cwd),
+      scratch: isScratch(config, cwd)
+    }
+  };
+}
+async function sessionAt(config, requested) {
+  if (typeof requested !== "string" || requested.length === 0 || requested.includes("\0")) return void 0;
+  let root;
+  let real;
+  try {
+    root = realpathSync2(config.sessionsRoot);
+    real = realpathSync2(resolve6(requested));
+  } catch {
+    return void 0;
+  }
+  const inside = (parent, child) => child === parent || child.startsWith(parent.endsWith(sep2) ? parent : parent + sep2);
+  if (!inside(root, real)) return void 0;
+  if (!real.endsWith(".jsonl")) return void 0;
+  let stats;
+  try {
+    stats = statSync5(real);
+  } catch {
+    return void 0;
+  }
+  if (!stats.isFile()) return void 0;
+  const projectDir = basename(dirname2(real));
+  const row = await describeSessionFile(config, real, projectDir, stats);
+  return row.ok ? row.session : void 0;
+}
+async function discover(config, limit = 500) {
+  const sessions = [];
+  const skipped = [];
+  let projectDirs;
+  try {
+    projectDirs = readdirSync2(config.sessionsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return { sessions, total: 0, skipped };
+  }
+  for (const projectDir of projectDirs) {
+    const projectPath = join6(config.sessionsRoot, projectDir);
+    let entries;
+    try {
+      entries = readdirSync2(projectPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.name.endsWith(".jsonl")) continue;
+      if (!entry.isFile()) continue;
+      const path = join6(projectPath, entry.name);
+      let stats;
+      try {
+        stats = statSync5(path);
+      } catch {
+        continue;
+      }
+      const row = await describeSessionFile(config, path, projectDir, stats);
+      if (!row.ok) {
+        skipped.push({ path, reason: row.reason });
+        continue;
+      }
+      sessions.push(row.session);
+    }
+  }
+  sessions.sort((a, b) => b.modifiedMs - a.modifiedMs);
+  return { sessions: sessions.slice(0, limit), total: sessions.length, skipped };
+}
+function directoryExists(dir) {
+  try {
+    return statSync5(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 // packages/orchestrator/src/capabilities.ts
 import { accessSync as accessSync3, constants as constants3 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join8 } from "node:path";
 
 // packages/orchestrator/src/signing.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
-import { join as join5, resolve as resolve5, sep as sep2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join7, resolve as resolve7, sep as sep3 } from "node:path";
 function signingKeyPath(root) {
-  return join5(root, "ssh", "github_login_ed25519");
+  return join7(root, "ssh", "github_login_ed25519");
 }
 function allowedSignersPath(root) {
-  return join5(root, "ssh", "allowed_signers");
+  return join7(root, "ssh", "allowed_signers");
 }
 var KEYS = {
   [normalizeKey("commit.gpgsign")]: "commitGpgsign",
@@ -769,10 +1117,10 @@ function readSigning(text) {
   return signing;
 }
 function isInside2(root, path) {
-  const from = resolve5(root);
-  const to = resolve5(path);
+  const from = resolve7(root);
+  const to = resolve7(path);
   if (to === from) return true;
-  return to.startsWith(from.endsWith(sep2) ? from : from + sep2);
+  return to.startsWith(from.endsWith(sep3) ? from : from + sep3);
 }
 function auditSigning(settings, root) {
   const problems = [];
@@ -821,16 +1169,16 @@ function signingMaterial(root) {
 }
 function signingFixCommands(root) {
   return [
-    `git config --file ${join5(root, "gitconfig")} commit.gpgsign true`,
-    `git config --file ${join5(root, "gitconfig")} tag.gpgsign true`,
-    `git config --file ${join5(root, "gitconfig")} gpg.format ssh`,
-    `git config --file ${join5(root, "gitconfig")} user.signingkey ${signingKeyPath(root)}`,
-    `git config --file ${join5(root, "gitconfig")} gpg.ssh.allowedSignersFile ${allowedSignersPath(root)}`
+    `git config --file ${join7(root, "gitconfig")} commit.gpgsign true`,
+    `git config --file ${join7(root, "gitconfig")} tag.gpgsign true`,
+    `git config --file ${join7(root, "gitconfig")} gpg.format ssh`,
+    `git config --file ${join7(root, "gitconfig")} user.signingkey ${signingKeyPath(root)}`,
+    `git config --file ${join7(root, "gitconfig")} gpg.ssh.allowedSignersFile ${allowedSignersPath(root)}`
   ];
 }
 
 // packages/orchestrator/src/capabilities.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 function isReadable(path) {
   try {
     accessSync3(path, constants3.R_OK);
@@ -863,7 +1211,7 @@ function assessAgentCapabilities(input) {
     // denies it", rather than firing on every direct-mode session.
     !sandboxed || fragment !== void 0 && fragmentGrants(fragment, path)
   );
-  const gitconfigPath = join6(root, "gitconfig");
+  const gitconfigPath = join8(root, "gitconfig");
   if (!store.has.gitconfig) {
     findings.push({
       id: "gitconfig",
@@ -883,7 +1231,7 @@ function assessAgentCapabilities(input) {
       message: `the session's policy does not grant ${root}, while GIT_CONFIG_GLOBAL points into it. The agent would be configured to read a file its own sandbox denies \u2014 a Pi Central bug, not a setup step.`
     });
   }
-  const ghDir = join6(root, "gh");
+  const ghDir = join8(root, "gh");
   if (!store.has.ghConfig) {
     findings.push({
       id: "gh-config",
@@ -907,11 +1255,11 @@ function assessAgentCapabilities(input) {
     findings.push({
       id: "ssh-key",
       state: "not-provisioned",
-      message: `the agent has no SSH key under ${join6(root, "ssh")}. It can still push over HTTPS with its gh token, but not over SSH, and it cannot sign commits. Provision a key to use either.`
+      message: `the agent has no SSH key under ${join8(root, "ssh")}. It can still push over HTTPS with its gh token, but not over SSH, and it cannot sign commits. Provision a key to use either.`
     });
   }
   if (store.has.gitconfig) {
-    const gitconfigPath2 = join6(root, "gitconfig");
+    const gitconfigPath2 = join8(root, "gitconfig");
     const settings = readSigning(readGitconfigText(gitconfigPath2));
     const audit = auditSigning(settings, root);
     const material = signingMaterial(root);
@@ -961,7 +1309,7 @@ ${commands}`
 }
 function readGitconfigText(path) {
   try {
-    return readFileSync3(path, "utf8");
+    return readFileSync4(path, "utf8");
   } catch {
     return "";
   }
@@ -1162,15 +1510,15 @@ function renderPolicyFragment(options = {}) {
 }
 
 // packages/orchestrator/src/files.ts
-import { lstatSync, readdirSync as readdirSync2, readFileSync as readFileSync4, realpathSync, statSync as statSync5 } from "node:fs";
-import { isAbsolute, join as join7, resolve as resolve6, sep as sep3 } from "node:path";
+import { lstatSync, readdirSync as readdirSync3, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync6 } from "node:fs";
+import { isAbsolute, join as join9, resolve as resolve8, sep as sep4 } from "node:path";
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 var BINARY_SNIFF_BYTES = 8 * 1024;
 var DEFAULT_ENTRY_LIMIT = 2e3;
 function containsPath(parent, child) {
   if (parent === child) return true;
-  const withSep = parent.endsWith(sep3) ? parent : parent + sep3;
+  const withSep = parent.endsWith(sep4) ? parent : parent + sep4;
   return child.startsWith(withSep);
 }
 function fromErrno(error, what, relPath) {
@@ -1216,11 +1564,11 @@ function resolveWithin(root, relative) {
   const relPath = normalizeRelative(relative);
   let realRoot;
   try {
-    realRoot = realpathSync(root);
+    realRoot = realpathSync3(root);
   } catch (error) {
     return { ok: false, error: fromErrno(error, "the session's working directory is unavailable:", "") };
   }
-  const candidate = resolve6(realRoot, relPath);
+  const candidate = resolve8(realRoot, relPath);
   if (!containsPath(realRoot, candidate)) {
     return {
       ok: false,
@@ -1232,7 +1580,7 @@ function resolveWithin(root, relative) {
   }
   let real;
   try {
-    real = realpathSync(candidate);
+    real = realpathSync3(candidate);
   } catch (error) {
     return { ok: false, error: fromErrno(error, "cannot open", relPath) };
   }
@@ -1266,7 +1614,7 @@ function listDirectory(root, relative, options = {}) {
   const includeHidden = options.includeHidden ?? false;
   let names;
   try {
-    names = readdirSync2(path);
+    names = readdirSync3(path);
   } catch (error) {
     return { ok: false, error: fromErrno(error, "cannot list", relPath) };
   }
@@ -1278,7 +1626,7 @@ function listDirectory(root, relative, options = {}) {
       truncated = true;
       break;
     }
-    entries.push(describeEntry(join7(path, name), name));
+    entries.push(describeEntry(join9(path, name), name));
   }
   entries.sort((a, b) => {
     const aDir = a.kind === "directory" ? 0 : 1;
@@ -1294,16 +1642,18 @@ function describeEntry(fullPath, name) {
     if (stats.isSymbolicLink()) {
       return { name, kind: "symlink", linkTarget: linkTargetOf(fullPath), hidden: isHidden(name) };
     }
-    if (stats.isDirectory()) return { name, kind: "directory", hidden: isHidden(name) };
-    if (stats.isFile()) return { name, kind: "file", size: stats.size, hidden: isHidden(name) };
-    return { name, kind: "other", hidden: isHidden(name) };
+    if (stats.isDirectory()) return { name, kind: "directory", mtimeMs: stats.mtimeMs, hidden: isHidden(name) };
+    if (stats.isFile()) {
+      return { name, kind: "file", size: stats.size, mtimeMs: stats.mtimeMs, hidden: isHidden(name) };
+    }
+    return { name, kind: "other", mtimeMs: stats.mtimeMs, hidden: isHidden(name) };
   } catch {
     return { name, kind: "other", hidden: isHidden(name), unreadable: true };
   }
 }
 function linkTargetOf(fullPath) {
   try {
-    const stats = statSync5(fullPath);
+    const stats = statSync6(fullPath);
     if (stats.isDirectory()) return "directory";
     if (stats.isFile()) return "file";
     return "other";
@@ -1335,7 +1685,7 @@ function readFileText(root, relative) {
   }
   let buffer;
   try {
-    buffer = readFileSync4(path);
+    buffer = readFileSync5(path);
   } catch (error) {
     return { ok: false, error: fromErrno(error, "cannot read", relPath) };
   }
@@ -1408,7 +1758,7 @@ function readFileForDisplay(root, relative) {
   }
   let buffer;
   try {
-    buffer = readFileSync4(path);
+    buffer = readFileSync5(path);
   } catch (error) {
     return { ok: false, error: fromErrno(error, "cannot read", relPath) };
   }
@@ -1479,16 +1829,91 @@ var blockingDialogMethods = [...BLOCKING_DIALOG_METHODS];
 var fireAndForgetUiMethods = [...FIRE_AND_FORGET_UI_METHODS];
 
 // packages/orchestrator/src/supervisor.ts
+var EMPTY_PROMPT_WITH_IMAGES = "See the attached image.";
 var Supervisor = class extends EventEmitter2 {
   #config;
   #sessions = /* @__PURE__ */ new Map();
   #processes = /* @__PURE__ */ new Map();
   #created = 0;
-  constructor(config) {
+  /**
+   * Which sessions were open, so a restart can reopen them (issue #185).
+   *
+   * Loaded eagerly rather than on first use: the startup restore reads it before any session
+   * exists, and a lazily-created store would be a second code path that only the first launch takes.
+   */
+  #open;
+  /**
+   * Whether starting and stopping a session changes the remembered set (issue #185).
+   *
+   * Off for the one-shot CLI (`run`, `resume`), and that is a correctness requirement rather than a
+   * preference: the CLI exits immediately after stopping its session, so recording it would leave an
+   * entry the web app would faithfully reopen on its next launch — a session nobody has open, spawned
+   * behind the surprise of whoever started the orchestrator. It would also rewrite the file the
+   * running web app owns, from a second process.
+   *
+   * On for the long-running server, which is the thing a restart can lose.
+   */
+  #rememberOpenSessions;
+  constructor(config, options = {}) {
     super();
     this.#config = config;
+    this.#open = new OpenSessionStore(config.stateRoot);
+    this.#rememberOpenSessions = options.rememberOpenSessions === true;
     this.#installationRoot = resolveInstallationRoot();
   }
+  /**
+   * Reopen the sessions that were open when this process last ran (issue #185).
+   *
+   * Called once at startup by the entry point, deliberately NOT from the constructor: restoring
+   * spawns Pi, and a constructor that spawned processes would make every test that builds a
+   * supervisor launch sandboxes (C1 — they cannot, in CI).
+   *
+   * Each entry goes through the SAME path a reader's click does — `sessionAt` for the file, then
+   * `resume` for the spawn — so restore inherits every rule already established there: the file
+   * must still be a valid Pi session, the recorded cwd must still exist (C2), and the cwd is never
+   * retargeted (ADR-0008). A second implementation of "is this resumable" is exactly the drift
+   * `registry.ts` refuses elsewhere.
+   *
+   * Three outcomes, and the difference between them is the point:
+   *
+   *   - **the file is gone** → dropped from the set. A deleted session cannot come back, and keeping
+   *     it would mean reporting the same absence on every launch forever.
+   *   - **the cwd is gone** → reported and KEPT. This is the case that must not be forgotten: a
+   *     worktree on an unmounted volume, a directory restored later in the day. Dropping it would
+   *     turn a temporary absence into permanent loss of the reader's rail.
+   *   - **it resumed** → nothing to say.
+   *
+   * Returns a summary rather than logging, so the entry point owns the wording and a test can assert
+   * the decisions without capturing stderr.
+   */
+  async restoreOpenSessions() {
+    const loaded = this.#open.load();
+    const report = {
+      ...loaded.note === void 0 ? {} : { note: loaded.note },
+      restored: [],
+      missingFile: [],
+      unavailable: []
+    };
+    for (const entry of loaded.sessions) {
+      const session = await sessionAt(this.#config, entry.sessionFile);
+      if (session === void 0) {
+        this.#open.forget(entry.sessionFile);
+        report.missingFile.push(entry.sessionFile);
+        continue;
+      }
+      const result = this.resume(session, { mode: entry.mode });
+      if (!result.ok) {
+        report.unavailable.push({ sessionFile: entry.sessionFile, message: result.message });
+        continue;
+      }
+      report.restored.push(result.session);
+    }
+    return report;
+  }
+  /** The remembered open sessions, for diagnosis and tests. */
+  openSessions() {
+    return this.#open.list();
+  }
   list() {
     return [...this.#sessions.values()];
   }
@@ -1519,7 +1944,7 @@ var Supervisor = class extends EventEmitter2 {
     } else {
       try {
         cwd = scratchDirFor(this.#config, id);
-        mkdirSync2(cwd, { recursive: true });
+        mkdirSync3(cwd, { recursive: true });
       } catch (error) {
         return { ok: false, message: error.message };
       }
@@ -1539,15 +1964,18 @@ var Supervisor = class extends EventEmitter2 {
     const live = this.#findLiveByPath(session.path);
     if (live) return { ok: true, session: live };
     const id = `s${++this.#created}`;
-    return this.#spawn({
+    const mode = options.mode ?? "sandboxed";
+    const spawned = this.#spawn({
       id,
       cwd: readiness.cwd,
-      mode: options.mode ?? "sandboxed",
+      mode,
       // No name: the session already carries its own, and re-applying one would append a
       // redundant session_info entry to a file we did not create.
       ...options.env ? { env: options.env } : {},
       sessionPath: session.path
     });
+    if (spawned.ok && this.#rememberOpenSessions) this.#open.remember(session.path, mode);
+    return spawned;
   }
   #findLiveByPath(sessionPath) {
     for (const session of this.#sessions.values()) {
@@ -1610,7 +2038,7 @@ var Supervisor = class extends EventEmitter2 {
   #spawn(input) {
     const env = { ...agentRoutingEnv(this.#config.agentRoot), ...input.env ?? {} };
     const providerAuth = inspectProviderAuth(this.#config.providerAgentDir);
-    const keychainPath = join8(this.#config.agentRoot, KEYCHAIN_FILE);
+    const keychainPath = join10(this.#config.agentRoot, KEYCHAIN_FILE);
     const keychainNeeded = providerAuth.needsKeychain;
     const keychainPresent = existsSync4(keychainPath);
     const fragment = input.mode === "sandboxed" ? renderPolicyFragment({
@@ -1696,6 +2124,22 @@ var Supervisor = class extends EventEmitter2 {
     void this.#refreshState(session.id);
     return { ok: true, session };
   }
+  /**
+   * Persist a session once its FILE is known (issue #185).
+   *
+   * Called from the two places that learn it: `#refreshState` (the first `get_state` of a new
+   * session, where Pi reports the file it just created) and `retry` of a session that already had
+   * one. Recording the Pi Central handle here instead would be the "keyed by handle" mistake
+   * `roster.ts` documents: `sN` is per-process, and after a restart it addresses a different
+   * conversation.
+   *
+   * A resumed session is already known — `resume` records it synchronously — so the store's own
+   * "nothing changed, no write" check keeps this from writing on every state refresh.
+   */
+  #rememberSession(session) {
+    if (!this.#rememberOpenSessions) return;
+    this.#open.remember(session.sessionFile, session.mode);
+  }
   /**
    * A resumed session reopens its file (`--session <path>`); a new session is left to Pi's
    * default naming in its workspace.
@@ -1719,6 +2163,7 @@ var Supervisor = class extends EventEmitter2 {
       session.provider = model?.provider;
       session.thinkingLevel = state.thinkingLevel;
       if (typeof state.sessionFile === "string") session.sessionFile = state.sessionFile;
+      this.#rememberSession(session);
       if (typeof state.sessionId === "string" && state.sessionId) session.sessionId = state.sessionId;
       if (typeof state.sessionName === "string" && state.sessionName) session.name = state.sessionName;
       session.messageCount = Number(state.messageCount ?? session.messageCount);
@@ -1848,22 +2293,32 @@ ${rpc.stderrTail}` : ""}`;
     this.#patch(id);
   }
   /**
-   * Send a prompt. The command shape is closed; the message is the only free value.
+   * Send a prompt. The command shape is closed; the message and its images are the only free values.
    *
    * `behavior` decides what a message means mid-run, and it is the caller's choice rather than
    * this method's: Pi REJECTS a streaming `prompt` with no `streamingBehavior` (`"Agent is
    * already processing. Specify streamingBehavior ('steer' or 'followUp')"`), so defaulting it
    * silently would decide for the user something the composer is there to ask (issue #3). When
    * idle there is nothing to steer into, so the flag is dropped rather than sent.
+   *
+   * `images` arrive ALREADY VALIDATED (`prompt-images.ts`) and are mapped to Pi's shape here — the one
+   * place a control becomes Pi's stdin, which is the right place for the spelling to change. Pi wants
+   * `{ type: "image", data, mimeType }`; the wire carries `{ mediaType, data }` because `type` is the
+   * discriminant of every record on that wire and reusing it inside a payload makes a log ambiguous.
    */
-  async prompt(id, message, behavior) {
+  async prompt(id, message, behavior, images = []) {
     const rpc = this.#processes.get(id);
     const session = this.#sessions.get(id);
     if (!rpc || !session) throw new Error(`no such session: ${id}`);
+    const text = message.trim().length === 0 && images.length > 0 ? EMPTY_PROMPT_WITH_IMAGES : message;
+    const withImages = images.length > 0 ? { images: images.map((image) => ({ type: "image", data: image.data, mimeType: image.mediaType })) } : {};
     if (session.state === "streaming") {
-      await rpc.send({ type: "prompt", message, streamingBehavior: behavior ?? "followUp" }, 6e4);
+      await rpc.send(
+        { type: "prompt", message: text, streamingBehavior: behavior ?? "followUp", ...withImages },
+        6e4
+      );
     } else {
-      await rpc.send({ type: "prompt", message }, 6e4);
+      await rpc.send({ type: "prompt", message: text, ...withImages }, 6e4);
     }
   }
   /**
@@ -1916,7 +2371,20 @@ ${rpc.stderrTail}` : ""}`;
         provider: String(model["provider"] ?? ""),
         id: String(model["id"] ?? ""),
         ...typeof model["name"] === "string" ? { name: model["name"] } : {},
-        ...typeof model["reasoning"] === "boolean" ? { reasoning: model["reasoning"] } : {}
+        ...typeof model["reasoning"] === "boolean" ? { reasoning: model["reasoning"] } : {},
+        /*
+         * `input` decides whether the composer may offer a paste.
+         *
+         * Filtered to the two values the wire declares rather than passed through: Pi's catalogue may grow a
+         * modality this version does not know, and an unrecognised member would widen the UI's type for a capability
+         * nothing here can use. Absent when Pi did not report it — which is "unknown", NOT "text only", and the
+         * difference decides whether the affordance is hidden or merely unflagged.
+         */
+        ...Array.isArray(model["input"]) ? {
+          input: model["input"].filter(
+            (value) => value === "text" || value === "image"
+          )
+        } : {}
       })).filter((model) => model.provider !== "" && model.id !== "");
       return { ok: true, models };
     } catch (error) {
@@ -1972,12 +2440,36 @@ ${rpc.stderrTail}` : ""}`;
     if (!session || !rpc) return;
     session.state = "stopped";
     session.dialogs = [];
+    if (this.#rememberOpenSessions) this.#open.forget(session.sessionFile);
     this.#patch(id);
     await rpc.stop();
     this.#processes.delete(id);
   }
-  async stopAll() {
-    await Promise.all([...this.#processes.keys()].map((id) => this.stop(id)));
+  /**
+   * Stop every session, WITHOUT forgetting them (issue #185).
+   *
+   * This is the shutdown path (Ctrl-C, SIGTERM), and the distinction is the whole feature: the next
+   * launch reopens what was open. `forget` exists for the one caller that really means "empty the
+   * rail" — an explicit stop.
+   */
+  async stopAll(options = {}) {
+    const ids = [...this.#processes.keys()];
+    if (options.forget === true) {
+      await Promise.all(ids.map((id) => this.stop(id)));
+      return;
+    }
+    await Promise.all(
+      ids.map(async (id) => {
+        const session = this.#sessions.get(id);
+        const rpc = this.#processes.get(id);
+        if (!session || !rpc) return;
+        session.state = "stopped";
+        session.dialogs = [];
+        this.#patch(id);
+        await rpc.stop();
+        this.#processes.delete(id);
+      })
+    );
   }
   /**
    * List a session's working directory (issue #8, ADR-0007).
@@ -2094,28 +2586,28 @@ import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 
 // packages/orchestrator/src/package-meta.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
-import { dirname, join as join9, parse } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join11, parse } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var PACKAGE_NAME = "pi-central";
 function findOwnPackage(from = import.meta.url) {
-  let directory = dirname(fileURLToPath2(from));
+  let directory = dirname3(fileURLToPath2(from));
   for (; ; ) {
-    const candidate = join9(directory, "package.json");
+    const candidate = join11(directory, "package.json");
     if (existsSync5(candidate)) {
       const parsed = readPackageJson(candidate);
       if (parsed?.name === PACKAGE_NAME && typeof parsed.version === "string") {
         return { path: candidate, root: directory, name: parsed.name, version: parsed.version };
       }
     }
-    const parent = dirname(directory);
+    const parent = dirname3(directory);
     if (parent === directory || directory === parse(directory).root) return void 0;
     directory = parent;
   }
 }
 function readPackageJson(path) {
   try {
-    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    const parsed = JSON.parse(readFileSync6(path, "utf8"));
     if (typeof parsed !== "object" || parsed === null) return void 0;
     return parsed;
   } catch {
@@ -2124,216 +2616,93 @@ function readPackageJson(path) {
 }
 var VERIFY_INSTALL_HINT = "npm audit signatures";
 
-// packages/orchestrator/src/registry.ts
-import { createReadStream, readdirSync as readdirSync3, realpathSync as realpathSync2, statSync as statSync6 } from "node:fs";
-import { basename, dirname as dirname2, join as join10, resolve as resolve7, sep as sep4 } from "node:path";
-var KNOWN_SESSION_VERSIONS = /* @__PURE__ */ new Set([3]);
-var HEAD_BYTES = 256 * 1024;
-var TAIL_BYTES = 8 * 1024;
-function decodeSessionDir(dirName) {
-  const inner = dirName.replace(/^--/, "").replace(/--$/, "");
-  return `/${inner.replace(/-/g, "/")}`;
-}
-async function readLateSessionName(path) {
-  let stats;
-  try {
-    stats = statSync6(path);
-  } catch {
-    return void 0;
-  }
-  const start = Math.max(0, stats.size - TAIL_BYTES);
-  if (start === 0) return void 0;
-  const text = await new Promise((resolve9) => {
-    const chunks = [];
-    const stream = createReadStream(path, { start, end: stats.size - 1 });
-    stream.on("data", (chunk) => chunks.push(chunk));
-    stream.on("error", () => resolve9(""));
-    stream.on("close", () => resolve9(Buffer.concat(chunks).toString("utf8")));
-  });
-  if (text === "") return void 0;
-  const lines = text.split("\n");
-  lines.shift();
-  let name;
-  for (const line of lines) {
-    if (!line.includes('"session_info"')) continue;
-    try {
-      const record = JSON.parse(line);
-      if (record.type === "session_info" && typeof record.name === "string") {
-        const trimmed = record.name.trim();
-        if (trimmed.length > 0) name = trimmed;
-      }
-    } catch {
-      continue;
-    }
-  }
-  return name;
-}
-async function readHead(path) {
-  return new Promise((resolve9) => {
-    const chunks = [];
-    let size = 0;
-    const stream = createReadStream(path, { start: 0, end: HEAD_BYTES - 1 });
-    stream.on("data", (chunk) => {
-      chunks.push(chunk);
-      size += chunk.length;
-    });
-    stream.on("error", () => resolve9(""));
-    stream.on("close", () => resolve9(Buffer.concat(chunks, size).toString("utf8")));
-  });
+// packages/orchestrator/src/prompt-images.ts
+var PROMPT_IMAGE_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp"
+];
+var MAX_PROMPT_IMAGE_BYTES = 3 * 1024 * 1024;
+function refuseImage(refusal, detail) {
+  switch (refusal) {
+    case "unsupported-type":
+      return `an image of type ${detail?.type ?? "unknown"} cannot be sent \u2014 prompts accept PNG, JPEG, GIF and WebP`;
+    case "too-large":
+      return `that image is ${formatMegabytes(detail?.bytes ?? 0)} decoded, above the ${formatMegabytes(MAX_PROMPT_IMAGE_BYTES)} limit for a prompt \u2014 downscale it and paste again`;
+    case "not-base64":
+      return "that image's data is not valid base64 \u2014 it may have been truncated in transit";
+    case "missing-type":
+      return "an image arrived without a media type";
+    case "missing-data":
+      return "an image arrived with no data";
+    case "not-an-object":
+      return "an image arrived in an unrecognised shape";
+  }
+}
+function formatMegabytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "an unknown size";
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
-function parseHead(text) {
-  const lines = text.split("\n");
-  let header = null;
-  let name;
-  let firstMessage = "";
-  let messageCount = 0;
-  for (const line of lines) {
-    if (!line) continue;
-    let record;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      if (!header) continue;
-      break;
-    }
-    if (!header) {
-      if (record.type !== "session") return null;
-      if (typeof record.id !== "string" || typeof record.cwd !== "string") return null;
-      header = {
-        type: "session",
-        version: Number(record.version ?? 0),
-        id: record.id,
-        timestamp: String(record.timestamp ?? ""),
-        cwd: record.cwd,
-        ...typeof record.parentSession === "string" ? { parentSession: record.parentSession } : {}
+function base64Bytes(data) {
+  if (data.length === 0) return 0;
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return Math.floor(data.length * 3 / 4) - padding;
+}
+function isBase64(data) {
+  if (data.length === 0 || data.length % 4 !== 0) return false;
+  return /^[A-Za-z0-9+/]+={0,2}$/.test(data);
+}
+function acceptImage(raw) {
+  if (typeof raw !== "object" || raw === null) return { ok: false, reason: "not-an-object" };
+  const candidate = raw;
+  if (typeof candidate.mediaType !== "string" || candidate.mediaType.length === 0) {
+    return { ok: false, reason: "missing-type" };
+  }
+  if (typeof candidate.data !== "string" || candidate.data.length === 0) {
+    return { ok: false, reason: "missing-data" };
+  }
+  const mediaType = candidate.mediaType.toLowerCase();
+  if (!PROMPT_IMAGE_TYPES.includes(mediaType)) return { ok: false, reason: "unsupported-type" };
+  if (!isBase64(candidate.data)) return { ok: false, reason: "not-base64" };
+  const bytes = base64Bytes(candidate.data);
+  if (bytes > MAX_PROMPT_IMAGE_BYTES) return { ok: false, reason: "too-large" };
+  return { ok: true, image: { mediaType, data: candidate.data } };
+}
+var MAX_PROMPT_IMAGES_ENCODED_BYTES = 6 * 1024 * 1024;
+function acceptImages(raw) {
+  if (raw === void 0 || raw === null) return { ok: true, images: [] };
+  if (!Array.isArray(raw)) return { ok: false, message: "images must be a list" };
+  if (raw.length === 0) return { ok: true, images: [] };
+  const images = [];
+  for (const entry of raw) {
+    const result = acceptImage(entry);
+    if (!result.ok) {
+      const type = typeof entry === "object" && entry !== null ? entry.mediaType : void 0;
+      const bytes = typeof entry === "object" && entry !== null && typeof entry.data === "string" ? base64Bytes(entry.data) : void 0;
+      return {
+        ok: false,
+        message: refuseImage(result.reason, {
+          ...typeof type === "string" ? { type } : {},
+          ...bytes !== void 0 ? { bytes } : {}
+        })
       };
-      continue;
     }
-    if (record.type === "session_info" && typeof record.name === "string") {
-      name = record.name.trim() || void 0;
-      continue;
-    }
-    if (record.type === "message") {
-      messageCount += 1;
-      if (!firstMessage) {
-        const message = record.message;
-        if (message?.role === "user") firstMessage = flattenContent(message.content).slice(0, 200);
-      }
-    }
-  }
-  return header ? { header, name, firstMessage, messageCount } : null;
-}
-function flattenContent(content) {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content.map((part) => {
-      if (typeof part === "string") return part;
-      if (part && typeof part === "object" && "text" in part) return String(part.text);
-      return "";
-    }).join(" ");
-  }
-  return "";
-}
-async function describeSessionFile(config, path, projectDir, stats) {
-  const head = await readHead(path);
-  const parsed = parseHead(head);
-  if (!parsed) return { ok: false, reason: "not a Pi session file (no valid header)" };
-  const lateName = stats.size > HEAD_BYTES ? await readLateSessionName(path) : void 0;
-  if (!KNOWN_SESSION_VERSIONS.has(parsed.header.version)) {
-    return { ok: false, reason: `unknown session version ${parsed.header.version}` };
-  }
-  const cwd = parsed.header.cwd || decodeSessionDir(projectDir);
-  return {
-    ok: true,
-    session: {
-      path,
-      id: parsed.header.id,
-      cwd,
-      // The late name wins: it is the most recent rename, and the head's is the earliest one.
-      ...lateName ?? parsed.name ? { name: lateName ?? parsed.name } : {},
-      created: parsed.header.timestamp,
-      modifiedMs: stats.mtimeMs,
-      bytes: stats.size,
-      messageCount: parsed.messageCount,
-      firstMessage: parsed.firstMessage,
-      cwdExists: directoryExists(cwd),
-      scratch: isScratch(config, cwd)
-    }
-  };
-}
-async function sessionAt(config, requested) {
-  if (typeof requested !== "string" || requested.length === 0 || requested.includes("\0")) return void 0;
-  let root;
-  let real;
-  try {
-    root = realpathSync2(config.sessionsRoot);
-    real = realpathSync2(resolve7(requested));
-  } catch {
-    return void 0;
+    images.push(result.image);
   }
-  const inside = (parent, child) => child === parent || child.startsWith(parent.endsWith(sep4) ? parent : parent + sep4);
-  if (!inside(root, real)) return void 0;
-  if (!real.endsWith(".jsonl")) return void 0;
-  let stats;
-  try {
-    stats = statSync6(real);
-  } catch {
-    return void 0;
-  }
-  if (!stats.isFile()) return void 0;
-  const projectDir = basename(dirname2(real));
-  const row = await describeSessionFile(config, real, projectDir, stats);
-  return row.ok ? row.session : void 0;
-}
-async function discover(config, limit = 500) {
-  const sessions = [];
-  const skipped = [];
-  let projectDirs;
-  try {
-    projectDirs = readdirSync3(config.sessionsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-  } catch {
-    return { sessions, total: 0, skipped };
-  }
-  for (const projectDir of projectDirs) {
-    const projectPath = join10(config.sessionsRoot, projectDir);
-    let entries;
-    try {
-      entries = readdirSync3(projectPath, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.name.endsWith(".jsonl")) continue;
-      if (!entry.isFile()) continue;
-      const path = join10(projectPath, entry.name);
-      let stats;
-      try {
-        stats = statSync6(path);
-      } catch {
-        continue;
-      }
-      const row = await describeSessionFile(config, path, projectDir, stats);
-      if (!row.ok) {
-        skipped.push({ path, reason: row.reason });
-        continue;
-      }
-      sessions.push(row.session);
-    }
-  }
-  sessions.sort((a, b) => b.modifiedMs - a.modifiedMs);
-  return { sessions: sessions.slice(0, limit), total: sessions.length, skipped };
-}
-function directoryExists(dir) {
-  try {
-    return statSync6(dir).isDirectory();
-  } catch {
-    return false;
+  const encoded = images.reduce((total, image) => total + image.data.length, 0);
+  if (encoded > MAX_PROMPT_IMAGES_ENCODED_BYTES) {
+    return {
+      ok: false,
+      message: `these images total ${(encoded / (1024 * 1024)).toFixed(1)} MB encoded, above the ${(MAX_PROMPT_IMAGES_ENCODED_BYTES / (1024 * 1024)).toFixed(1)} MB limit for one prompt \u2014 remove one or downscale them`
+    };
   }
+  return { ok: true, images };
 }
 
 // packages/orchestrator/src/static-ui.ts
-import { createReadStream as createReadStream2, existsSync as existsSync6, statSync as statSync7 } from "node:fs";
-import { extname, join as join11, posix, resolve as resolve8, sep as sep5 } from "node:path";
+import { createReadStream as createReadStream2, existsSync as existsSync6, readFileSync as readFileSync7, statSync as statSync7 } from "node:fs";
+import { extname, join as join12, posix, resolve as resolve9, sep as sep5 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var UI_CSP = (
   // `blob:` is REQUIRED and is not covered by `'self'` (issue #111).
@@ -2370,13 +2739,13 @@ var CONTENT_TYPES = {
 };
 function resolveUiDistDir(env = process.env, from = import.meta.url) {
   const explicit = env["PI_CENTRAL_UI_DIST"];
-  if (explicit !== void 0 && explicit !== "") return resolve8(explicit);
+  if (explicit !== void 0 && explicit !== "") return resolve9(explicit);
   const own = findOwnPackage(from);
   if (own === void 0) {
     return fileURLToPath3(new URL("../../ui/dist", from));
   }
-  const packaged = join11(own.root, "dist", "ui");
-  const workspace = join11(own.root, "packages", "ui", "dist");
+  const packaged = join12(own.root, "dist", "ui");
+  const workspace = join12(own.root, "packages", "ui", "dist");
   const fromSource = runningFromSource(from);
   const candidates = fromSource ? [workspace, packaged] : [packaged, workspace];
   for (const candidate of candidates) {
@@ -2388,13 +2757,13 @@ function runningFromSource(from) {
   return /[\\/]packages[\\/][^\\/]+[\\/]src[\\/]/.test(fileURLToPath3(from));
 }
 function isInside3(root, candidate) {
-  const rootPath = resolve8(root);
-  const target = resolve8(candidate);
+  const rootPath = resolve9(root);
+  const target = resolve9(candidate);
   if (target === rootPath) return true;
   return target.startsWith(rootPath.endsWith(sep5) ? rootPath : rootPath + sep5);
 }
 function resolveStaticPath(root, requestTarget) {
-  const rootPath = resolve8(root);
+  const rootPath = resolve9(root);
   const target = requestTarget.split("?")[0].split("#")[0];
   let decoded;
   try {
@@ -2408,16 +2777,16 @@ function resolveStaticPath(root, requestTarget) {
     return { kind: "denied", reason: "the request target contains a '..' segment" };
   }
   const relative = posix.normalize(decoded).replace(/^\/+/, "");
-  const candidate = resolve8(rootPath, relative);
+  const candidate = resolve9(rootPath, relative);
   if (!isInside3(rootPath, candidate)) {
     return { kind: "denied", reason: "the request target resolves outside the served UI root" };
   }
   return { kind: "file", path: candidate };
 }
 function createUiRequestHandler(options) {
-  const root = resolve8(options.root);
+  const root = resolve9(options.root);
   const csp = options.csp ?? UI_CSP;
-  const indexPath = resolve8(root, "index.html");
+  const indexPath = resolve9(root, "index.html");
   return (req, res) => {
     const method = req.method ?? "GET";
     if (method !== "GET" && method !== "HEAD") {
@@ -2504,7 +2873,21 @@ function sendFile(res, method, path, csp) {
   stream.pipe(res);
 }
 function hasBuiltUi(root) {
-  return existsSync6(resolve8(root, "index.html"));
+  return existsSync6(resolve9(root, "index.html"));
+}
+function servedUiIdentity(root) {
+  let html;
+  let mtime;
+  try {
+    const indexPath = resolve9(root, "index.html");
+    html = readFileSync7(indexPath, "utf8");
+    mtime = statSync7(indexPath).mtime;
+  } catch {
+    return void 0;
+  }
+  const entry = /assets\/index-[A-Za-z0-9_-]+\.js/.exec(html)?.[0];
+  if (entry === void 0) return void 0;
+  return { entry, builtAt: mtime.toISOString() };
 }
 
 // packages/orchestrator/src/transport.ts
@@ -2590,11 +2973,11 @@ var Transport = class {
     this.#server = server;
     this.#wss = wss;
     wss.on("connection", (socket) => this.#onConnection(socket));
-    await new Promise((resolve9, reject) => {
+    await new Promise((resolve10, reject) => {
       server.once("error", reject);
       server.listen(this.#options.port, this.#options.host, () => {
         server.off("error", reject);
-        resolve9();
+        resolve10();
       });
     });
     const addr = server.address();
@@ -2642,6 +3025,20 @@ var Transport = class {
     };
     return this.#install;
   }
+  /**
+   * The install facts for ONE snapshot, with the served-UI identity read live (issue #184).
+   *
+   * `#installFacts` is cached because a package walk cannot change under a running process; the UI
+   * directory CAN — a dev `vite build` replaces it while the orchestrator runs, and reading it is
+   * one small file — so `ui` is resolved per snapshot rather than frozen into the cached facts. A
+   * stale `ui` here would be the one value issue #184 exists for, reported wrong.
+   */
+  #snapshotInstallFacts() {
+    const facts = this.#installFacts();
+    if (this.#options.uiDir === null) return facts;
+    const ui = servedUiIdentity(this.#options.uiDir);
+    return ui === void 0 ? facts : { ...facts, ui };
+  }
   async #sendSnapshot(socket) {
     let history = [];
     let historyTotal = 0;
@@ -2659,7 +3056,7 @@ var Transport = class {
       historyTotal,
       home: this.#config.home,
       installationRoot: this.#config.installationRoot,
-      install: this.#installFacts()
+      install: this.#snapshotInstallFacts()
     });
     for (const session of this.#supervisor.list()) {
       if (session.state === "stopped" || session.state === "failed") continue;
@@ -2708,7 +3105,11 @@ var Transport = class {
           history: discovered.sessions,
           historyTotal: discovered.total,
           home: this.#config.home,
-          installationRoot: this.#config.installationRoot
+          installationRoot: this.#config.installationRoot,
+          // `install` here as well as on the connect snapshot (issue #184): a page that never
+          // reconnects still learns the orchestrator was replaced the next time it lists, rather
+          // than only when the socket happens to drop.
+          install: this.#snapshotInstallFacts()
         });
         return;
       }
@@ -2751,13 +3152,15 @@ var Transport = class {
         this.#broadcast({ kind: "session", session: result.session });
         return;
       }
-      case "prompt":
-        await this.#supervisor.prompt(
-          control.sessionId,
-          control.message,
-          ...control.behavior ? [control.behavior] : []
-        );
+      case "prompt": {
+        const accepted = acceptImages(control.images);
+        if (!accepted.ok) {
+          this.#broadcast({ kind: "error", message: `image refused: ${accepted.message}`, sessionId: control.sessionId });
+          return;
+        }
+        await this.#supervisor.prompt(control.sessionId, control.message, control.behavior, accepted.images);
         return;
+      }
       case "clearQueue": {
         await this.#supervisor.clearQueue(control.sessionId, control.andStop);
         return;
@@ -2912,14 +3315,14 @@ var Transport = class {
     this.#wss = void 0;
     this.#server = void 0;
     this.#address = void 0;
-    if (wss) await new Promise((resolve9) => wss.close(() => resolve9()));
-    if (server) await new Promise((resolve9) => server.close(() => resolve9()));
+    if (wss) await new Promise((resolve10) => wss.close(() => resolve10()));
+    if (server) await new Promise((resolve10) => server.close(() => resolve10()));
   }
 };
 
 // packages/orchestrator/src/startup-error.ts
-import { readFileSync as readFileSync6, statSync as statSync8 } from "node:fs";
-import { join as join12 } from "node:path";
+import { statSync as statSync8 } from "node:fs";
+import { join as join13 } from "node:path";
 function explainStartupError(error, host, port) {
   const code = error?.code;
   if (code === "EADDRINUSE") {
@@ -2954,15 +3357,15 @@ function explainStartupError(error, host, port) {
   return void 0;
 }
 function describeBuiltUi(uiDir) {
+  let readable = true;
   try {
-    const html = readFileSync6(join12(uiDir, "index.html"), "utf8");
-    const entry = /assets\/index-[A-Za-z0-9_-]+\.js/.exec(html)?.[0];
-    if (entry === void 0) return "(no entry bundle named in index.html)";
-    const { mtime } = statSync8(join12(uiDir, "index.html"));
-    return `${entry} (built ${mtime.toISOString().slice(0, 16).replace("T", " ")})`;
+    statSync8(join13(uiDir, "index.html"));
   } catch {
-    return "(unreadable)";
+    readable = false;
   }
+  const identity = servedUiIdentity(uiDir);
+  if (identity === void 0) return readable ? "(no entry bundle named in index.html)" : "(unreadable)";
+  return `${identity.entry} (built ${identity.builtAt.slice(0, 16).replace("T", " ")})`;
 }
 
 // packages/orchestrator/src/sandbox-guard.ts
@@ -3100,7 +3503,8 @@ async function main() {
     }
   }
   const config = defaultConfig();
-  const supervisor = new Supervisor(config);
+  const supervisor = new Supervisor(config, { rememberOpenSessions: true });
+  const restored = await supervisor.restoreOpenSessions();
   const transport = new Transport(supervisor, config, { port: options.port, uiDir: options.uiDir });
   transport.attach();
   const address = await transport.listen();
@@ -3110,6 +3514,18 @@ async function main() {
   console.log(`  default workspace: ${config.workspaceRoot}`);
   console.log(`  agent root: ${config.agentRoot}${config.agentRootManaged ? " (managed)" : " (external)"}`);
   console.log(`  isolation: ${options.mode}`);
+  if (restored.note !== void 0) console.log(`  sessions to restore: ${restored.note}`);
+  if (restored.restored.length > 0) {
+    console.log(`  reopened ${restored.restored.length} session${restored.restored.length === 1 ? "" : "s"} from the last run`);
+  }
+  for (const gone of restored.missingFile) {
+    console.log(`  forgot a session whose file no longer exists: ${gone}`);
+  }
+  for (const unavailable of restored.unavailable) {
+    const [first = ""] = unavailable.message.split("\n");
+    console.log(`  could not reopen ${unavailable.sessionFile}: ${first}`);
+    console.log(`    kept in the list; it will be tried again on the next start`);
+  }
   console.log(`  running from: ${ownPackageRoot()}`);
   console.log(`  verify this install: ${VERIFY_INSTALL_HINT}   (see README, "Verify what you installed")`);
   if (config.installationRoot === void 0) {
@@ -3155,7 +3571,7 @@ async function main() {
     console.log(`
 ${signal} received; stopping sessions...`);
     await transport.close().catch(() => void 0);
-    await supervisor.stopAll().catch(() => void 0);
+    await supervisor.stopAll({ forget: false }).catch(() => void 0);
     console.log("stopped.");
     process.exit(0);
   };