pi-central 0.0.0-stage → 0.2.0

package/bin/pi-central.js

@@ -0,0 +1,2836 @@
+#!/usr/bin/env node
+
+// packages/orchestrator/src/config.ts
+import { homedir } from "node:os";
+
+// packages/orchestrator/src/installation-root.ts
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// packages/protocol/src/pi.ts
+var BLOCKING_DIALOG_METHODS = ["select", "confirm", "input", "editor"];
+var BLOCKING = new Set(BLOCKING_DIALOG_METHODS);
+var FIRE_AND_FORGET_UI_METHODS = [
+  "notify",
+  "setStatus",
+  "setWidget",
+  "setTitle",
+  "set_editor_text"
+];
+var FIRE_AND_FORGET = new Set(FIRE_AND_FORGET_UI_METHODS);
+function isBlockingDialog(record) {
+  if (record.type !== "extension_ui_request") return false;
+  return !FIRE_AND_FORGET.has(String(record.method ?? ""));
+}
+
+// packages/protocol/src/envelopes.ts
+var PROTOCOL_VERSION = 2;
+
+// packages/protocol/src/own-installation.ts
+var PIPELINE_MARKERS = ["packages/orchestrator", "packages/ui", "packages/protocol"];
+function normalizePath(path) {
+  const parts = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      parts.pop();
+      continue;
+    }
+    parts.push(segment);
+  }
+  const joined = parts.join("/");
+  return path.startsWith("/") ? `/${joined}` : joined;
+}
+function isOwnInstallation(candidate, installation) {
+  const a = normalizePath(candidate);
+  const b = normalizePath(installation);
+  if (a.length === 0 || b.length === 0) return false;
+  if (a === b) return true;
+  return isInside(a, b) || isInside(b, a);
+}
+function isInside(child, parent) {
+  if (parent === "/") return child !== "/";
+  return child.startsWith(`${parent}/`);
+}
+function looksLikePiCentral(paths) {
+  const normalized = paths.map(normalizePath);
+  return PIPELINE_MARKERS.every(
+    (marker) => normalized.some((path) => path === marker || path.endsWith(`/${marker}`))
+  );
+}
+var OWN_INSTALLATION_WARNING = "This is the checkout Pi Central is running from. Editing it can hot-reload this UI, desynchronise it from the orchestrator on a branch switch, and leave Pi Central unable to restart if the orchestrator's source is broken \u2014 exactly when you need it. Use a separate clone (see docs/DOGFOODING.md).";
+function ownInstallationWarning(candidate, installation) {
+  if (installation === void 0) return void 0;
+  return isOwnInstallation(candidate, installation) ? OWN_INSTALLATION_WARNING : void 0;
+}
+
+// packages/protocol/src/bytes.ts
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "\u2014";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// packages/orchestrator/src/installation-root.ts
+function resolveInstallationRoot(moduleUrl = import.meta.url) {
+  let current = fileURLToPath(new URL(".", moduleUrl));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const parent = resolve(current, "..");
+    if (parent === current) return void 0;
+    if (looksLikeInstallationRoot(parent)) return parent;
+    current = parent;
+  }
+  return void 0;
+}
+function looksLikeInstallationRoot(directory) {
+  const markers = [
+    join(directory, "packages", "orchestrator"),
+    join(directory, "packages", "ui"),
+    join(directory, "packages", "protocol")
+  ];
+  if (!markers.every((marker) => existsSync(marker))) return false;
+  return looksLikePiCentral(markers);
+}
+
+// packages/orchestrator/src/config.ts
+import { join as join3, resolve as resolve2, sep } from "node:path";
+
+// packages/orchestrator/src/agent-store.ts
+import { createHash } from "node:crypto";
+import { existsSync as existsSync2, readFileSync, readdirSync, statSync } from "node:fs";
+import { join as join2 } from "node:path";
+var KEYCHAIN_FILE = "agent.keychain-db";
+var PROVIDER_AUTH_FILE = "auth.json";
+function looksLikeAgentTree(root) {
+  if (!existsSync2(root)) return false;
+  return existsSync2(join2(root, KEYCHAIN_FILE)) || existsSync2(join2(root, "gitconfig")) || existsSync2(join2(root, "gh")) || existsSync2(join2(root, "ssh"));
+}
+function inspectProviderAuth(agentDir) {
+  const path = join2(agentDir, PROVIDER_AUTH_FILE);
+  const result = {
+    path,
+    readable: false,
+    providers: [],
+    commandProviders: [],
+    needsKeychain: false
+  };
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return result;
+  }
+  result.readable = true;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return result;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return result;
+  for (const [provider, value] of Object.entries(parsed)) {
+    result.providers.push(provider);
+    if (typeof value !== "object" || value === null) continue;
+    const key = value.key;
+    if (typeof key !== "string" || !key.startsWith("!")) continue;
+    result.commandProviders.push(provider);
+    if (/\bsecurity\b/.test(key)) result.needsKeychain = true;
+  }
+  return result;
+}
+function readStore(root, options = {}) {
+  const ownership = options.ownership ?? "managed";
+  const exists = existsSync2(root);
+  const gitconfigPath = join2(root, "gitconfig");
+  const identity = exists && existsSync2(gitconfigPath) ? readIdentity(gitconfigPath) : {};
+  const has = {
+    gitconfig: existsSync2(gitconfigPath),
+    ghConfig: existsSync2(join2(root, "gh")),
+    sshKey: existsSync2(join2(root, "ssh", "github_login_ed25519")) || existsSync2(join2(root, "ssh", "id_ed25519")),
+    sshSigningKey: existsSync2(join2(root, "ssh", "allowed_signers")),
+    knownHosts: existsSync2(join2(root, "ssh", "known_hosts")),
+    sshCommandWrapper: existsSync2(join2(root, "ssh", "ssh-github.sh")),
+    keychain: existsSync2(join2(root, KEYCHAIN_FILE))
+  };
+  const files = exists ? listFiles(root) : [];
+  const snapshot = { root, exists, ownership, identity, has, files, fingerprint: "" };
+  snapshot.fingerprint = fingerprintOf(snapshot);
+  return snapshot;
+}
+function fingerprintOf(snapshot) {
+  const facts = {
+    exists: snapshot.exists,
+    identity: snapshot.identity,
+    has: snapshot.has,
+    files: snapshot.files.map((f) => [f.relPath, f.mode, f.size])
+  };
+  return createHash("sha256").update(JSON.stringify(facts)).digest("hex").slice(0, 16);
+}
+function listFiles(root) {
+  const found = [];
+  const walk = (dir, rel, depth) => {
+    if (depth > 2) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+      const full = join2(dir, entry.name);
+      try {
+        const stats = statSync(full);
+        if (stats.isDirectory()) {
+          walk(full, relPath, depth + 1);
+        } else {
+          found.push({ relPath, mode: stats.mode & 511, size: stats.size });
+        }
+      } catch {
+      }
+    }
+  };
+  walk(root, "", 0);
+  return found.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+function readIdentity(gitconfigPath) {
+  const identity = {};
+  let text;
+  try {
+    text = readFileSync(gitconfigPath, "utf8");
+  } catch {
+    return identity;
+  }
+  let inUser = false;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("[")) {
+      inUser = /^\[user\]/i.test(line);
+      continue;
+    }
+    if (!inUser) continue;
+    const match = /^(name|email)\s*=\s*(.+)$/i.exec(line);
+    if (!match) continue;
+    const value = match[2].trim();
+    if (value === "") continue;
+    if (match[1].toLowerCase() === "name") identity.name = value;
+    else identity.email = value;
+  }
+  return identity;
+}
+
+// packages/orchestrator/src/config.ts
+function resolveAgentRoot(stateRoot, env = process.env, home = homedir()) {
+  const explicit = env["PI_CENTRAL_AGENT_ROOT"];
+  if (explicit !== void 0 && explicit !== "") return { agentRoot: explicit, managed: false };
+  const conventional = join3(home, ".agent");
+  if (looksLikeAgentTree(conventional)) return { agentRoot: conventional, managed: false };
+  return { agentRoot: join3(stateRoot, "agents", "default"), managed: true };
+}
+function defaultConfig() {
+  const home = homedir();
+  const stateRoot = process.env.PI_CENTRAL_STATE ?? join3(home, ".config", "pi-central");
+  const { agentRoot, managed } = resolveAgentRoot(stateRoot);
+  return {
+    workspaceRoot: process.env.PI_CENTRAL_WORKSPACE ?? join3(home, ".local", "share", "pi-central", "workspaces"),
+    stateRoot,
+    sessionsRoot: process.env.PI_SESSIONS_DIR ?? join3(home, ".pi", "agent", "sessions"),
+    safehouse: process.env.PI_CENTRAL_SAFEHOUSE ?? "safehouse",
+    pi: process.env.PI_CENTRAL_PI ?? "pi",
+    agentRoot,
+    fragmentDir: join3(stateRoot, "policy"),
+    agentRootManaged: managed,
+    home,
+    // Where a session actually reads provider configuration. Defaults to Pi's own agent dir,
+    // because Pi Central does not currently pass `PI_CODING_AGENT_DIR`; if that changes, this
+    // must follow, or the policy would grant keychain access for the wrong location.
+    providerAgentDir: process.env.PI_CODING_AGENT_DIR ?? join3(home, ".pi", "agent"),
+    // Derived from the ORCHESTRATOR's module URL, never from configuration (issue #25): see
+    // `installation-root.ts`. `defaultConfig` is the orchestrator's entry point, so resolving here
+    // means the answer is the running installation and not whatever a config file claims.
+    installationRoot: resolveInstallationRoot()
+  };
+}
+function contains(parent, child) {
+  const p = resolve2(parent);
+  const c = resolve2(child);
+  if (c === p) return true;
+  return c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+function scratchDirFor(config, sessionId) {
+  if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+    throw new Error(`refusing to build a workspace path from an unsafe id: ${JSON.stringify(sessionId)}`);
+  }
+  return join3(config.workspaceRoot, sessionId);
+}
+function isScratch(config, cwd) {
+  return contains(config.workspaceRoot, 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";
+
+// packages/orchestrator/src/policy.ts
+import { accessSync, constants, mkdirSync, statSync as statSync2, writeFileSync } from "node:fs";
+import { join as join4, resolve as resolve3 } from "node:path";
+
+// packages/orchestrator/src/env.ts
+var PASSTHROUGH = [
+  // Process basics a CLI needs to behave normally.
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "PATH",
+  "TMPDIR",
+  "LANG",
+  "LC_ALL",
+  "TERM",
+  "COLORTERM",
+  "EDITOR",
+  "VISUAL",
+  // Pi's own switches (environment-variables.md). These select behaviour, not identity, so
+  // passing them preserves user intent without carrying a credential.
+  "PI_OFFLINE",
+  "PI_SKIP_VERSION_CHECK",
+  "PI_TIMING",
+  "PI_CODING_AGENT_DIR",
+  "PI_CODING_AGENT_SESSION_DIR",
+  "PI_PACKAGE_DIR",
+  "PI_SUBAGENT_PI_BINARY"
+];
+var FORBIDDEN_NAMES = /* @__PURE__ */ new Set(["ssh_auth_sock", "ssh_agent_pid"]);
+function buildSessionEnv(options = {}) {
+  const source = options.source ?? process.env;
+  const env = {};
+  for (const name of PASSTHROUGH) {
+    const value = source[name];
+    if (value !== void 0) env[name] = value;
+  }
+  env["PATH"] ??= options.fallbackPath ?? DEFAULT_PATH;
+  for (const [name, value] of Object.entries(options.set ?? {})) {
+    assertInjectableName(name);
+    env[name] = value;
+  }
+  return env;
+}
+var DEFAULT_PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+function agentRoutingEnv(agentRoot) {
+  if (!agentRoot.startsWith("/")) {
+    throw new Error(`agent root must be an absolute path: ${JSON.stringify(agentRoot)}`);
+  }
+  return {
+    GH_CONFIG_DIR: `${agentRoot}/gh`,
+    GIT_CONFIG_GLOBAL: `${agentRoot}/gitconfig`,
+    GIT_CONFIG_SYSTEM: "/dev/null"
+  };
+}
+function assertInjectableName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`refusing to inject a malformed env var name: ${JSON.stringify(name)}`);
+  }
+  if (FORBIDDEN_NAMES.has(name.toLowerCase())) {
+    throw new Error(
+      `refusing to inject ${name}: it would expose the host user's ssh-agent to the session. An agent that needs SSH uses its own key with IdentitiesOnly=yes (ADR-0010 \xA74).`
+    );
+  }
+}
+
+// packages/orchestrator/src/policy.ts
+var FORBIDDEN_ENABLE = /* @__PURE__ */ new Set([
+  "wide-read",
+  "all-agents",
+  "all-apps",
+  "ssh",
+  "keychain",
+  "cloud-credentials",
+  "cloud-storage"
+]);
+var FORBIDDEN_FLAGS = ["--allow-workdir-config-writes", "--allow-profile-writes"];
+function composePolicy(spec) {
+  const warnings = [];
+  assertLaunchableDirectory(spec.cwd);
+  if (spec.mode === "direct") {
+    return {
+      launch: {
+        command: spec.pi,
+        args: ["--mode", "rpc", ...spec.name ? ["--name", spec.name] : []],
+        cwd: spec.cwd,
+        env: buildSessionEnv(spec.env ? { set: spec.env } : {})
+      },
+      isolation: "NONE \u2014 pi runs unsandboxed, inheriting this process's sandbox (if any)",
+      warnings: ["Direct mode applies no Safehouse policy. Feasibility testing only."]
+    };
+  }
+  const enable = (spec.enable ?? []).filter((feature) => {
+    if (FORBIDDEN_ENABLE.has(feature)) {
+      warnings.push(`Refused --enable=${feature}: it grants access beyond the workdir.`);
+      return false;
+    }
+    return true;
+  });
+  const fragmentFile = materializeFragment(spec);
+  const args = ["--workdir", spec.cwd];
+  if (enable.length > 0) args.push(`--enable=${enable.join(",")}`);
+  if (fragmentFile !== void 0) args.push(`--append-profile=${fragmentFile}`);
+  const env = buildSessionEnv(spec.env ? { set: spec.env } : {});
+  const injected = Object.keys(spec.env ?? {});
+  if (injected.length > 0) args.push(`--env-pass=${injected.join(",")}`);
+  for (const bad of FORBIDDEN_FLAGS) {
+    if (args.includes(bad)) throw new Error(`refusing to pass ${bad}`);
+  }
+  args.push("--", spec.pi, "--mode", "rpc");
+  if (spec.name) args.push("--name", spec.name);
+  const result = {
+    launch: { command: spec.safehouse, args, cwd: spec.cwd, env },
+    isolation: `Safehouse workdir=${spec.cwd}${enable.length ? ` enable=${enable.join(",")}` : ""}${fragmentFile !== void 0 ? " +bespoke-fragment" : ""}`,
+    warnings
+  };
+  if (fragmentFile !== void 0) result.fragmentFile = fragmentFile;
+  return result;
+}
+function materializeFragment(spec) {
+  if (spec.policyFragment === void 0) {
+    if (spec.fragmentDir !== void 0) {
+      throw new Error("fragmentDir was given without a policyFragment to write");
+    }
+    return void 0;
+  }
+  if (spec.fragmentDir === void 0) {
+    throw new Error("a policyFragment needs a fragmentDir to be written into");
+  }
+  const dir = resolve3(spec.fragmentDir);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const file = join4(dir, `${spec.id}.sb`);
+  writeFileSync(file, spec.policyFragment, { mode: 384 });
+  return file;
+}
+function assertLaunchableDirectory(dir) {
+  let stats;
+  try {
+    stats = statSync2(dir);
+  } catch {
+    throw new Error(`working directory does not exist: ${dir}`);
+  }
+  if (!stats.isDirectory()) throw new Error(`working directory is not a directory: ${dir}`);
+  try {
+    accessSync(dir, constants.R_OK | constants.X_OK);
+  } catch {
+    throw new Error(`working directory is not readable: ${dir}`);
+  }
+}
+function describe(policy) {
+  return [policy.launch.command, ...policy.launch.args].join(" ");
+}
+
+// packages/orchestrator/src/rpc.ts
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+
+// packages/orchestrator/src/framing.ts
+var JsonlDecoder = class {
+  #buffer = Buffer.alloc(0);
+  /** Feed a chunk; returns any complete records it completed. */
+  push(chunk) {
+    this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
+    return this.#drain();
+  }
+  /** Records left when the stream ends. A trailing record without LF is still valid. */
+  flush() {
+    const out = this.#drain();
+    if (this.#buffer.length > 0) {
+      const record = this.#parse(this.#buffer);
+      this.#buffer = Buffer.alloc(0);
+      if (record) out.push(record);
+    }
+    return out;
+  }
+  #drain() {
+    const records = [];
+    for (; ; ) {
+      const nl = this.#buffer.indexOf(10);
+      if (nl === -1) break;
+      const line = this.#buffer.subarray(0, nl);
+      this.#buffer = this.#buffer.subarray(nl + 1);
+      const record = this.#parse(line);
+      if (record) records.push(record);
+    }
+    return records;
+  }
+  #parse(raw) {
+    let line = raw;
+    if (line.length > 0 && line[line.length - 1] === 13) line = line.subarray(0, line.length - 1);
+    if (line.length === 0) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(line.toString("utf8"));
+    } catch {
+      return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const record = parsed;
+    if (typeof record.type !== "string" || record.type.length === 0) return null;
+    return record;
+  }
+};
+function encodeLine(value) {
+  return `${JSON.stringify(value)}
+`;
+}
+
+// packages/orchestrator/src/rpc.ts
+var RpcProcess = class extends EventEmitter {
+  launch;
+  #child = null;
+  #decoder = new JsonlDecoder();
+  #pending = /* @__PURE__ */ new Map();
+  #seq = 0;
+  #stderr = "";
+  #stopping = false;
+  #exited = false;
+  constructor(launch) {
+    super();
+    this.launch = launch;
+  }
+  start() {
+    if (this.#child) throw new Error("session already started");
+    const child = spawn(this.launch.command, this.launch.args, {
+      cwd: this.launch.cwd,
+      // Replaces the inherited environment outright. There is no merge: an omitted `env`
+      // would mean "inherit everything", which is the failure C11 exists to prevent.
+      env: this.launch.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      // Own process group, so a wedged session cannot outlive the dashboard.
+      detached: true
+    });
+    this.#child = child;
+    child.stdout.on("data", (chunk) => {
+      for (const record of this.#decoder.push(chunk)) this.#dispatch(record);
+    });
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString("utf8");
+      this.#stderr += text;
+      this.emit("stderr", text);
+    });
+    child.on("error", (error) => 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.emit("exit", { code, signal, stderr: this.stderrTail });
+    });
+    return this;
+  }
+  #dispatch(record) {
+    if (record.type === "response" && typeof record.id === "string") {
+      const pending = this.#pending.get(record.id);
+      if (pending) {
+        this.#pending.delete(record.id);
+        clearTimeout(pending.timer);
+        if (record.success === false) {
+          pending.reject(new Error(String(record.error ?? "command failed")));
+        } else {
+          pending.resolve(record.data);
+        }
+        return;
+      }
+    }
+    this.emit("record", record);
+  }
+  /** Send a command and resolve with its response `data`, or reject on error/timeout. */
+  /**
+   * Send a command and await its correlated response.
+   *
+   * Takes the CLOSED `Command` union, not `{ type: string } & Record<string, unknown>`.
+   *
+   * This is not a style preference. The union was documented as "closed, on purpose: the
+   * supervisor must not be able to send an arbitrary object derived from untrusted input", but
+   * `send` accepted any object with a `type` string — so the union was decorative and a typo
+   * (`get_message` for `get_messages`) compiled cleanly and failed only at runtime, as a
+   * `success: false` response the caller might not check. `get_messages` was in fact absent from
+   * the union while being called from the supervisor, which is exactly how that goes unnoticed.
+   */
+  send(command, timeoutMs = 6e4) {
+    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((resolve8, 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: resolve8, reject, timer });
+      child.stdin.write(encodeLine({ ...command, id }));
+    });
+  }
+  /** Fire-and-forget write, for records that produce no `response` (extension UI). */
+  write(record) {
+    const child = this.#child;
+    if (child?.stdin.writable) child.stdin.write(encodeLine(record));
+  }
+  /**
+   * Bounded, graceful teardown. Close stdin first (Pi's preferred shutdown), then escalate
+   * to the process group.
+   *
+   * Waits at every step, including after SIGKILL, so that when this resolves the process has
+   * actually been reaped. Firing the final signal and returning immediately would leave
+   * `running` true for a process that is already dying, and a caller doing `stopAll()` before
+   * exit could not tell a clean shutdown from a wedged one.
+   */
+  async stop(graceMs = 1500) {
+    if (this.#stopping) return;
+    this.#stopping = true;
+    const child = this.#child;
+    if (!child || this.#exited) return;
+    try {
+      child.stdin.end();
+    } catch {
+    }
+    const pid = child.pid;
+    if (await this.#waitForExit(graceMs)) return;
+    try {
+      if (pid) process.kill(-pid, "SIGTERM");
+    } catch {
+    }
+    if (await this.#waitForExit(2e3)) return;
+    try {
+      if (pid) process.kill(-pid, "SIGKILL");
+    } catch {
+    }
+    await this.#waitForExit(2e3);
+  }
+  #waitForExit(ms) {
+    const child = this.#child;
+    if (!child || this.#exited) return Promise.resolve(true);
+    return new Promise((resolve8) => {
+      const timer = setTimeout(() => resolve8(this.#exited), ms);
+      timer.unref?.();
+      child.once("exit", () => {
+        clearTimeout(timer);
+        resolve8(true);
+      });
+    });
+  }
+  get stderrTail() {
+    return this.#stderr.split("\n").slice(-12).join("\n").trim();
+  }
+  get running() {
+    const child = this.#child;
+    return child !== null && !this.#exited;
+  }
+};
+
+// packages/orchestrator/src/resume.ts
+import { accessSync as accessSync2, constants as constants2, statSync as statSync3 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
+function checkResumable(session) {
+  if (!session.cwd) {
+    return {
+      ok: false,
+      reason: "unknown-cwd",
+      cwd: session.cwd,
+      message: "This session does not record the directory it ran in, so a sandbox cannot be composed for it. Start a new session in the directory you want."
+    };
+  }
+  let stats;
+  try {
+    stats = statSync3(session.cwd);
+  } catch (error) {
+    const code = error.code;
+    const unreadable = code === "EACCES" || code === "EPERM";
+    return {
+      ok: false,
+      reason: unreadable ? "unreadable" : "missing-directory",
+      cwd: session.cwd,
+      message: unreadable ? `The directory this session worked in cannot be read (${code}):
+  ${session.cwd}
+
+This is a permissions problem, not a missing directory. Check that you can enter it: it may be owned by another user, or a parent directory may deny access.` : `The directory this session worked in no longer exists:
+  ${session.cwd}
+
+Restore it, or start a new session in the directory you want to work in. Pi Central does not move a session between directories.`
+    };
+  }
+  if (!stats.isDirectory()) {
+    return {
+      ok: false,
+      reason: "not-a-directory",
+      cwd: session.cwd,
+      message: `The directory this session recorded is no longer a directory:
+  ${session.cwd}`
+    };
+  }
+  try {
+    accessSync2(session.cwd, constants2.R_OK | constants2.X_OK);
+  } catch {
+    return {
+      ok: false,
+      reason: "unreadable",
+      cwd: session.cwd,
+      message: `The directory this session worked in is not readable:
+  ${session.cwd}`
+    };
+  }
+  return { ok: true, cwd: resolve4(session.cwd) };
+}
+
+// packages/orchestrator/src/capabilities.ts
+import { accessSync as accessSync3, constants as constants3 } from "node:fs";
+import { join as join6 } 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";
+function signingKeyPath(root) {
+  return join5(root, "ssh", "github_login_ed25519");
+}
+function allowedSignersPath(root) {
+  return join5(root, "ssh", "allowed_signers");
+}
+var KEYS = {
+  [normalizeKey("commit.gpgsign")]: "commitGpgsign",
+  [normalizeKey("tag.gpgsign")]: "tagGpgsign",
+  [normalizeKey("gpg.format")]: "format",
+  [normalizeKey("user.signingkey")]: "signingKey",
+  [normalizeKey("gpg.ssh.allowedSignersFile")]: "allowedSignersFile"
+};
+function normalizeKey(key) {
+  const parts = key.split(".");
+  if (parts.length < 2) return key.toLowerCase();
+  const last = parts.length - 1;
+  return parts.map((part, index) => index === 0 || index === last ? part.toLowerCase() : part).join(".");
+}
+function parseGitConfig(text) {
+  const values = /* @__PURE__ */ new Map();
+  let prefix = "";
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith(";")) continue;
+    if (line.startsWith("[")) {
+      const match2 = /^\[([^\]"\s]+)(?:\s+"([^"]*)")?\]$/.exec(line);
+      prefix = match2?.[2] !== void 0 ? `${match2[1].toLowerCase()}.${match2[2]}` : match2?.[1]?.toLowerCase() ?? "";
+      continue;
+    }
+    const match = /^([A-Za-z][A-Za-z0-9-]*)\s*=\s*(.*)$/.exec(line);
+    if (!match || prefix === "") continue;
+    values.set(normalizeKey(`${prefix}.${match[1]}`), match[2].trim());
+  }
+  return values;
+}
+function readSigning(text) {
+  const values = parseGitConfig(text);
+  const signing = {};
+  for (const [key, field] of Object.entries(KEYS)) {
+    const value = values.get(key);
+    if (value !== void 0 && value !== "") signing[field] = value;
+  }
+  return signing;
+}
+function isInside2(root, path) {
+  const from = resolve5(root);
+  const to = resolve5(path);
+  if (to === from) return true;
+  return to.startsWith(from.endsWith(sep2) ? from : from + sep2);
+}
+function auditSigning(settings, root) {
+  const problems = [];
+  const keyPath = signingKeyPath(root);
+  const signersPath = allowedSignersPath(root);
+  let misconfigured = false;
+  if (settings.signingKey !== void 0 && !isInside2(root, settings.signingKey)) {
+    misconfigured = true;
+    problems.push(
+      `user.signingkey is ${settings.signingKey}, which is OUTSIDE the agent root ${root}. ssh takes a key path rather than key contents, so this would sign commits as whoever owns that key \u2014 a leak of the user's identity, not a formatting problem.`
+    );
+  }
+  if (settings.allowedSignersFile !== void 0 && !isInside2(root, settings.allowedSignersFile)) {
+    misconfigured = true;
+    problems.push(
+      `gpg.ssh.allowedSignersFile is ${settings.allowedSignersFile}, which is outside the agent root ${root}. Verification would consult the host's trust list instead of the agent's.`
+    );
+  }
+  if (settings.format !== void 0 && settings.format !== "ssh") {
+    misconfigured = true;
+    problems.push(
+      `gpg.format is ${JSON.stringify(settings.format)}, not "ssh". The default is openpgp, which looks for a gpg installation the session does not need and may not have.`
+    );
+  }
+  if (misconfigured) return { state: "misconfigured", problems, needsFix: true };
+  const disabled = !truthy(settings.commitGpgsign) || !truthy(settings.tagGpgsign);
+  if (disabled) {
+    if (!truthy(settings.commitGpgsign)) problems.push("commit.gpgsign is not true");
+    if (!truthy(settings.tagGpgsign)) problems.push("tag.gpgsign is not true");
+    return { state: "disabled", problems, needsFix: true };
+  }
+  if (settings.format === void 0) problems.push("gpg.format is unset (must be ssh)");
+  if (settings.signingKey === void 0) problems.push(`user.signingkey is unset (must be ${keyPath})`);
+  if (settings.allowedSignersFile === void 0) {
+    problems.push(`gpg.ssh.allowedSignersFile is unset (must be ${signersPath})`);
+  }
+  if (problems.length > 0) return { state: "incomplete", problems, needsFix: true };
+  return { state: "ok", problems: [], needsFix: false };
+}
+function truthy(value) {
+  if (value === void 0) return false;
+  return ["true", "1", "yes", "on"].includes(value.toLowerCase());
+}
+function signingMaterial(root) {
+  return { key: existsSync3(signingKeyPath(root)), allowedSigners: existsSync3(allowedSignersPath(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)}`
+  ];
+}
+
+// packages/orchestrator/src/capabilities.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+function isReadable(path) {
+  try {
+    accessSync3(path, constants3.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function fragmentGrants(fragment, path) {
+  return fragment.includes(`(subpath ${JSON.stringify(path)})`);
+}
+function fragmentGrantsKeychain(fragment) {
+  return fragment.includes('(global-name "com.apple.SecurityServer")') && // The search list is load-bearing: without it `security` silently falls back to
+  // [login, System], does not see the agent keychain, and every lookup fails with no useful
+  // error (C13). A grant without it looks correct and is not.
+  //
+  // Matched as the RULE, not as a bare substring, and that distinction was found by a test: the
+  // generated fragment also *describes* the file in a comment ("The search list lives in
+  // com.apple.security.plist"), so a substring check would pass on a fragment whose only mention
+  // of the search list is prose. Matching the `(home-literal …)` form is what makes it a check.
+  fragment.includes('(home-literal "/Library/Preferences/com.apple.security.plist")');
+}
+function assessAgentCapabilities(input) {
+  const { store, fragment, sandboxed, providerAuth, keychainPath } = input;
+  const findings = [];
+  const root = store.root;
+  const granted = (path) => (
+    // In direct mode no policy applies, so the only question is readability — which the checks
+    // below answer separately. Returning `true` here keeps "unreachable" meaning "the policy
+    // denies it", rather than firing on every direct-mode session.
+    !sandboxed || fragment !== void 0 && fragmentGrants(fragment, path)
+  );
+  const gitconfigPath = join6(root, "gitconfig");
+  if (!store.has.gitconfig) {
+    findings.push({
+      id: "gitconfig",
+      state: "not-provisioned",
+      message: `the agent has no gitconfig at ${gitconfigPath}, which GIT_CONFIG_GLOBAL points at. Commits would have no identity and git would read no agent settings. Provision it (git config --file ${gitconfigPath} user.name \u2026).`
+    });
+  } else if (!isReadable(gitconfigPath)) {
+    findings.push({
+      id: "gitconfig",
+      state: "unreachable",
+      message: `the agent gitconfig exists at ${gitconfigPath} but is not readable by its owner, so no process at this UID can use it. This is a permissions problem, not a missing setup step.`
+    });
+  } else if (!granted(root)) {
+    findings.push({
+      id: "gitconfig",
+      state: "unreachable",
+      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");
+  if (!store.has.ghConfig) {
+    findings.push({
+      id: "gh-config",
+      state: "not-provisioned",
+      message: `the agent has no gh config directory at ${ghDir}, which GH_CONFIG_DIR points at. gh would fall back to the host's config, find it denied, and refuse to start. Provision it (gh auth login with GH_CONFIG_DIR set, or copy an existing gh config).`
+    });
+  } else if (!granted(root)) {
+    findings.push({
+      id: "gh-config",
+      state: "unreachable",
+      message: `the session's policy does not grant ${root}, while GH_CONFIG_DIR points into it. gh would read the host's config instead, find that denied, and fail \u2014 a Pi Central bug.`
+    });
+  } else if (!isReadable(ghDir)) {
+    findings.push({
+      id: "gh-config",
+      state: "unreachable",
+      message: `the agent gh config directory exists at ${ghDir} but is not readable by its owner, so gh cannot read it. This is a permissions problem, not a missing setup step.`
+    });
+  }
+  if (!store.has.sshKey) {
+    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.`
+    });
+  }
+  if (store.has.gitconfig) {
+    const gitconfigPath2 = join6(root, "gitconfig");
+    const settings = readSigning(readGitconfigText(gitconfigPath2));
+    const audit = auditSigning(settings, root);
+    const material = signingMaterial(root);
+    if (audit.needsFix) {
+      const commands = signingFixCommands(root).map((command) => `    ${command}`).join("\n");
+      findings.push({
+        id: "signing",
+        state: audit.state === "misconfigured" ? "unreachable" : "not-provisioned",
+        message: `the agent's gitconfig does not sign commits or tags: ${audit.problems.join("; ")}. Commits would be created unsigned, SILENTLY \u2014 the key material is present, so nothing else would report a problem (ADR-0010 \xA74). This is an explicit fix, because the agent root is yours to maintain; Pi Central does not rewrite it:
+${commands}`
+      });
+    } else if (!material.key || !material.allowedSigners) {
+      findings.push({
+        id: "signing",
+        state: "not-provisioned",
+        message: `the agent's gitconfig is configured to sign (gpg.format=ssh, commit.gpgsign=true) but ${!material.key ? `the signing key ${signingKeyPath(root)} is missing` : ""}${!material.key && !material.allowedSigners ? " and " : ""}${!material.allowedSigners ? `the allowed-signers file ${allowedSignersPath(root)} is missing` : ""}. Every commit would fail, rather than be created unsigned.`
+      });
+    }
+  }
+  if (providerAuth.needsKeychain && sandboxed) {
+    if (fragment === void 0) {
+      findings.push({
+        id: "keychain",
+        state: "unreachable",
+        message: `the provider config at ${providerAuth.path} resolves keys via a command (${providerAuth.commandProviders.join(", ")}), but this sandboxed session has no policy fragment at all. The keychain lookup would fail. This is a Pi Central bug.`
+      });
+    } else if (!fragmentGrantsKeychain(fragment)) {
+      findings.push({
+        id: "keychain",
+        state: "unreachable",
+        message: `the provider config at ${providerAuth.path} resolves keys via a command (${providerAuth.commandProviders.join(", ")}), but the session's policy grants no keychain access. The session would start, report idle, and then be unable to reach a model (C13) \u2014 a Pi Central bug, not a setup step.`
+      });
+    } else if (store.has.keychain && !isReadable(keychainPath)) {
+      findings.push({
+        id: "keychain",
+        state: "unreachable",
+        message: `the agent keychain exists at ${keychainPath} but is not readable by its owner. This is a permissions problem, not a missing setup step.`
+      });
+    }
+  }
+  const warnings = findings.filter((finding) => finding.state !== "ok").map((finding) => `${label(finding)}: ${finding.message}`);
+  return {
+    findings,
+    warnings,
+    usable: findings.every((finding) => finding.state === "ok")
+  };
+}
+function readGitconfigText(path) {
+  try {
+    return readFileSync3(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function label(finding) {
+  const name = {
+    gitconfig: "agent git identity",
+    "gh-config": "agent GitHub credentials",
+    "ssh-key": "agent SSH key",
+    keychain: "provider keychain access",
+    signing: "agent commit signing"
+  }[finding.id];
+  const kind = finding.state === "not-provisioned" ? "not provisioned" : "provisioned but unreachable";
+  return `${name} ${kind}`;
+}
+
+// packages/orchestrator/src/fragment.ts
+function ancestorLiterals(path) {
+  if (!path.startsWith("/")) throw new Error(`path must be absolute: ${JSON.stringify(path)}`);
+  const parts = path.split("/").filter((part) => part !== "");
+  const out = ['    (literal "/")'];
+  let current = "";
+  for (const part of parts) {
+    current += `/${part}`;
+    out.push(`    (literal ${JSON.stringify(current)})`);
+  }
+  return out;
+}
+var HOST_DENIES = [
+  {
+    comment: [
+      "Host git configuration (closes the credential-helper route)",
+      "The host's global gitconfig may set credential.helper = !gh auth git-credential,",
+      "which resolves a token from the login keychain - a path no file deny on ~/.ssh",
+      "would stop. The agent uses its own GIT_CONFIG_GLOBAL instead (ADR-0010 \xA73)."
+    ],
+    rules: [
+      "(deny file-read*",
+      '    (home-prefix "/.gitconfig")',
+      '    (home-subpath "/.config/git")',
+      '    (home-literal "/.gitattributes")',
+      ")"
+    ]
+  },
+  {
+    comment: [
+      "Host GitHub CLI config",
+      "On macOS gh keeps its token in the keychain, but ~/.config/gh may still hold config",
+      "for the user's own account, and the write grant in particular was a config-tampering",
+      "surface. The agent uses its own GH_CONFIG_DIR. ~/.config stays traversable so tool",
+      "discovery (mise, gh, git) still works."
+    ],
+    rules: ["(deny file-read* file-write*", '    (home-subpath "/.config/gh")', ")", "(allow file-read-metadata", '    (home-literal "/.config")', ")"]
+  },
+  {
+    comment: [
+      "The user's SSH world, closed wholesale",
+      "",
+      "This was three NAME-based regexes (id_*, *_rsa, *_ed25519) plus a deny on",
+      "~/.ssh/agent, and the list failed twice over - it was REDUNDANT where it looked",
+      "essential and DANGEROUS where it looked harmless:",
+      "",
+      "  - Redundant: the base policy grants only ~/.ssh/config and ~/.ssh/known_hosts, as",
+      "    literals. Every other path under ~/.ssh was already denied by `(deny default)`.",
+      "  - Dangerous: the base workdir grant is",
+      "    `(allow file-read* file-write* (subpath HOME))` and is emitted BEFORE this fragment.",
+      "    For a session whose cwd is $HOME that grant covers all of ~/.ssh, so the",
+      "    enumeration became the only thing there - and it did not name cupserver, jenkins,",
+      "    or sven1103-agent-strongbox, which are real private keys, nor ~/.ssh/config",
+      "    itself, which maps 58 hosts including internal infrastructure.",
+      "",
+      "A list of key NAMES is not a boundary: it fails open on the next key anyone creates",
+      "under a name nobody predicted. The directory is the unit, so the directory is denied.",
+      "",
+      "Why this is safe, measured rather than assumed: the agent does not read this",
+      "directory at all. Its git-over-SSH runs `ssh -F <agentRoot>/ssh/config` through",
+      "core.sshCommand, and `-F` REPLACES the per-user config rather than adding to it.",
+      "With HOME pointed at an empty directory - no ~/.ssh whatsoever - the agent still",
+      "authenticated to GitHub and produced a signature git verified as",
+      '`Good "git" signature for sven1103-agent`.',
+      "",
+      "The second block is deliberate duplication, not tidiness. SBPL resolves a conflict",
+      "by last-matching rule, and Safehouse's own profiles note that a more specific filter",
+      "can beat a broader one regardless of order (`10-system-runtime.sb`). The base emits",
+      '`(home-literal "/.ssh/config")` - a literal, strictly more specific than a subpath -',
+      "so the base's own paths are named again at their own specificity, and a deny wins",
+      "under either reading."
+    ],
+    rules: [
+      "(deny file-read* file-write* file-read-metadata",
+      '    (home-subpath "/.ssh")',
+      ")",
+      "(deny file-read* file-write* file-read-metadata",
+      '    (home-literal "/.ssh")',
+      '    (home-literal "/.ssh/config")',
+      '    (home-literal "/.ssh/known_hosts")',
+      '    (home-literal "/.ssh/known_hosts.old")',
+      '    (home-literal "/.ssh/allowed_signers")',
+      '    (home-subpath "/.ssh/config.d")',
+      ")   ;; the base policy's own narrower grants, restated at matching specificity",
+      "",
+      ";; The ssh-agent needs a NETWORK deny as well, since a file deny does not cover",
+      ";; connect() on a unix socket. The file half is subsumed by the wholesale deny above.",
+      ";; A session with agent access can sign as the user with any loaded key WITHOUT",
+      ";; reading a key file; the agent uses its own key with IdentitiesOnly=yes and needs",
+      ";; no agent (ADR-0010 \xA74). Defence in depth: the spawn environment is sanitized too",
+      ";; (C11). Both layers are applied, since either alone is a single point of failure.",
+      "(deny network-outbound",
+      '    (remote unix-socket (path-regex #"^/private/tmp/com\\.apple\\.launchd\\.[^/]+/Listeners$"))',
+      '    (remote unix-socket (path-regex #"^/tmp/com\\.apple\\.launchd\\.[^/]+/Listeners$"))',
+      '    (remote unix-socket (path-regex #"^/private/var/run/com\\.apple\\.launchd\\.[^/]+/Listeners$"))',
+      '    (remote unix-socket (path-regex #"^/var/run/com\\.apple\\.launchd\\.[^/]+/Listeners$"))',
+      '    (remote unix-socket (path-regex (string-append "^" HOME_DIR "/\\\\.ssh/agent(/.*)?$")))',
+      ")"
+    ]
+  }
+];
+function renderPolicyFragment(options = {}) {
+  const { agentRoot, keychain = false, keychainPath } = options;
+  if (agentRoot !== void 0 && !agentRoot.startsWith("/")) {
+    throw new Error(`agent root must be an absolute path: ${JSON.stringify(agentRoot)}`);
+  }
+  if (keychain && (keychainPath === void 0 || !keychainPath.startsWith("/"))) {
+    throw new Error("keychain access requires an absolute keychainPath");
+  }
+  const out = [
+    ";; ---------------------------------------------------------------------------",
+    ";; Pi Central \u2014 appended policy fragment (ADR-0010).",
+    ";;",
+    ";; Generated; do not edit by hand. Deterministic, so drift is diffable.",
+    ";; Appended AFTER Safehouse's generated rules: SBPL is last-match-wins, so these",
+    ";; denies override the base policy's broader allows.",
+    ";;",
+    ";; Purpose: the session runs as the AGENT, not as the user.",
+    ";;",
+    ";; Identity credentials are closed. Provider credentials are NOT denied, and that is",
+    ";; deliberate: the agent runs on the user's model access, so there is no agent-owned",
+    ";; substitute. Denying it would stop the agent thinking, not tighten isolation.",
+    ";; See ADR-0010 Amendment 1.",
+    ";; ---------------------------------------------------------------------------",
+    ""
+  ];
+  for (const block of HOST_DENIES) {
+    out.push(...block.comment.map((line) => line === "" ? ";;" : `;; ${line}`));
+    out.push(...block.rules, "");
+  }
+  if (agentRoot !== void 0) {
+    out.push(
+      ";; --- The agent's OWN credentials -----------------------------------------------",
+      ";; Read-write: gh writes cache/state under GH_CONFIG_DIR, and git may update the",
+      ";; agent's config. This is the point of the fragment - the denies above only help if",
+      ";; the agent can still reach what it legitimately owns.",
+      ";;",
+      ";; Ancestor literals are required, not decorative: SBPL needs read access to every path",
+      ";; component, and Safehouse only emits ancestor grants for the workdir. Without them the",
+      ";; agent cannot traverse into its own tree.",
+      "(allow file-read*",
+      ...ancestorLiterals(agentRoot),
+      ")",
+      "(allow file-read* file-write*",
+      `    (subpath ${JSON.stringify(agentRoot)})`,
+      ")",
+      ""
+    );
+  }
+  if (keychain) {
+    out.push(
+      ";; --- Provider key resolution (C13) ----------------------------------------------",
+      ";; auth.json resolves each provider key with a service-only lookup, e.g.",
+      ";;   !security find-generic-password -ws 'litellm'",
+      ";; That needs SecurityServer to read ANY keychain, and the user-wide search list to",
+      ";; find the agent keychain. Neither is granted by Safehouse by default.",
+      ";;",
+      ";; The grant is bounded by denying the login and System keychain FILES: the keychain is",
+      ";; all-or-nothing via IPC, so least privilege (the agent's own keychain) is the",
+      ";; control, not concealment.",
+      "(allow mach-lookup",
+      '    (global-name "com.apple.SecurityServer")',
+      ")",
+      "(deny file-read* file-write*",
+      '    (home-subpath "/Library/Keychains")',
+      '    (subpath "/Library/Keychains")',
+      ")",
+      "(allow file-read* file-write*",
+      `    (literal ${JSON.stringify(keychainPath)})`,
+      ")",
+      ";; The search list lives in com.apple.security.plist. Without read access, `security`",
+      ";; silently falls back to the built-in [login, System] list, does NOT see the agent",
+      ";; keychain, and every service-only lookup fails with no useful error. The file holds",
+      ";; only the search list - no secret.",
+      "(allow file-read*",
+      '    (home-literal "/Library/Preferences/com.apple.security.plist")',
+      ")",
+      ""
+    );
+  }
+  return out.join("\n");
+}
+
+// packages/orchestrator/src/files.ts
+import { lstatSync, readdirSync as readdirSync2, readFileSync as readFileSync4, realpathSync, statSync as statSync4 } from "node:fs";
+import { isAbsolute, join as join7, resolve as resolve6, sep as sep3 } from "node:path";
+var MAX_FILE_BYTES = 256 * 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;
+  return child.startsWith(withSep);
+}
+function fromErrno(error, what, relPath) {
+  const code = error?.code;
+  const label2 = relPath === "" ? "the working directory" : `"${relPath}"`;
+  switch (code) {
+    case "ENOENT":
+      return { reason: "not-found", code, message: `${what} ${label2}: no such file or directory (ENOENT)` };
+    case "EACCES":
+    case "EPERM":
+      return { reason: "permission", code, message: `${what} ${label2}: permission denied (${code})` };
+    case "ENOTDIR":
+      return { reason: "not-a-directory", code, message: `${what} ${label2}: not a directory (ENOTDIR)` };
+    case "EISDIR":
+      return { reason: "is-directory", code, message: `${what} ${label2}: is a directory (EISDIR)` };
+    default:
+      return {
+        reason: "unreadable",
+        code,
+        message: code === void 0 ? `${what} ${label2}: ${String(error)}` : `${what} ${label2}: ${String(error)} (${code})`
+      };
+  }
+}
+function resolveWithin(root, relative) {
+  if (typeof relative !== "string" || relative.includes("\0")) {
+    return {
+      ok: false,
+      error: {
+        reason: "invalid-path",
+        message: "the path contains a NUL byte, which no filesystem path can"
+      }
+    };
+  }
+  if (isAbsolute(relative)) {
+    return {
+      ok: false,
+      error: {
+        reason: "absolute-path",
+        message: `"${relative}" is an absolute path; paths are relative to the session's working directory`
+      }
+    };
+  }
+  const relPath = normalizeRelative(relative);
+  let realRoot;
+  try {
+    realRoot = realpathSync(root);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "the session's working directory is unavailable:", "") };
+  }
+  const candidate = resolve6(realRoot, relPath);
+  if (!containsPath(realRoot, candidate)) {
+    return {
+      ok: false,
+      error: {
+        reason: "escapes-cwd",
+        message: `"${relative}" resolves outside the session's working directory`
+      }
+    };
+  }
+  let real;
+  try {
+    real = realpathSync(candidate);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot open", relPath) };
+  }
+  if (!containsPath(realRoot, real)) {
+    return {
+      ok: false,
+      error: {
+        reason: "escapes-cwd",
+        message: `"${relative}" is a symlink whose target lies outside the session's working directory, so it is refused rather than followed`
+      }
+    };
+  }
+  return { ok: true, value: { path: real, relPath } };
+}
+function normalizeRelative(relative) {
+  const parts = [];
+  for (const part of relative.split(/[/\\]+/)) {
+    if (part === "" || part === ".") continue;
+    parts.push(part);
+  }
+  return parts.join("/");
+}
+function isHidden(name) {
+  return name.startsWith(".");
+}
+function listDirectory(root, relative, options = {}) {
+  const resolvedPath = resolveWithin(root, relative);
+  if (!resolvedPath.ok) return resolvedPath;
+  const { path, relPath } = resolvedPath.value;
+  const limit = options.limit ?? DEFAULT_ENTRY_LIMIT;
+  const includeHidden = options.includeHidden ?? false;
+  let names;
+  try {
+    names = readdirSync2(path);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot list", relPath) };
+  }
+  const entries = [];
+  let truncated = false;
+  for (const name of names) {
+    if (!includeHidden && isHidden(name)) continue;
+    if (entries.length >= limit) {
+      truncated = true;
+      break;
+    }
+    entries.push(describeEntry(join7(path, name), name));
+  }
+  entries.sort((a, b) => {
+    const aDir = a.kind === "directory" ? 0 : 1;
+    const bDir = b.kind === "directory" ? 0 : 1;
+    if (aDir !== bDir) return aDir - bDir;
+    return a.name.localeCompare(b.name, void 0, { sensitivity: "base" });
+  });
+  return { ok: true, value: { path: relPath, entries, truncated } };
+}
+function describeEntry(fullPath, name) {
+  try {
+    const stats = lstatSync(fullPath);
+    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) };
+  } catch {
+    return { name, kind: "other", hidden: isHidden(name), unreadable: true };
+  }
+}
+function linkTargetOf(fullPath) {
+  try {
+    const stats = statSync4(fullPath);
+    if (stats.isDirectory()) return "directory";
+    if (stats.isFile()) return "file";
+    return "other";
+  } catch {
+    return "missing";
+  }
+}
+function readFileText(root, relative) {
+  const resolvedPath = resolveWithin(root, relative);
+  if (!resolvedPath.ok) return resolvedPath;
+  const { path, relPath } = resolvedPath.value;
+  let stats;
+  try {
+    stats = lstatSync(path);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot open", relPath) };
+  }
+  if (stats.isDirectory()) {
+    return { ok: false, error: { reason: "is-directory", message: `"${relPath}" is a directory` } };
+  }
+  if (stats.size > MAX_FILE_BYTES) {
+    return {
+      ok: false,
+      error: {
+        reason: "too-large",
+        message: `"${relPath}" is ${formatBytes(stats.size)}, above the ${formatBytes(MAX_FILE_BYTES)} limit for reading a file here, so it was not read`
+      }
+    };
+  }
+  let buffer;
+  try {
+    buffer = readFileSync4(path);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot read", relPath) };
+  }
+  const sniff = buffer.subarray(0, BINARY_SNIFF_BYTES);
+  if (sniff.includes(0)) {
+    return {
+      ok: false,
+      error: {
+        reason: "binary",
+        message: `"${relPath}" is a binary file (it contains NUL bytes), so it was not rendered as text`
+      }
+    };
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+  } catch {
+    return {
+      ok: false,
+      error: {
+        reason: "binary",
+        message: `"${relPath}" is not valid UTF-8, so it was not rendered as text`
+      }
+    };
+  }
+  return { ok: true, value: { path: relPath, text, bytes: buffer.byteLength } };
+}
+
+// packages/orchestrator/src/state.ts
+function countAsMessage(record) {
+  const message = record.message;
+  return message?.role === "user" || message?.role === "assistant";
+}
+function interpretRecord(session, record) {
+  switch (record.type) {
+    case "agent_start":
+      return { patch: { state: "streaming" } };
+    case "agent_end":
+      return {};
+    case "compaction_end":
+      return { refreshStats: true };
+    case "agent_settled":
+      return {
+        patch: { state: session.dialogs.length > 0 ? "awaiting-approval" : "idle" },
+        refreshStats: true
+      };
+    case "message_end":
+      return countAsMessage(record) ? { patch: { messageCount: session.messageCount + 1 } } : {};
+    case "queue_update": {
+      const steering = record.steering?.length ?? 0;
+      const followUp = record.followUp?.length ?? 0;
+      return { patch: { pending: steering + followUp } };
+    }
+    case "thinking_level_changed":
+      return { patch: { thinkingLevel: record.level } };
+    case "extension_ui_request": {
+      if (!isBlockingDialog(record)) return {};
+      const dialog = {
+        id: String(record.id),
+        method: String(record.method),
+        title: record.title,
+        message: record.message,
+        options: record.options,
+        placeholder: record.placeholder,
+        prefill: record.prefill,
+        receivedAt: Date.now()
+      };
+      return { dialog, patch: { state: "awaiting-approval" } };
+    }
+    default:
+      return {};
+  }
+}
+var blockingDialogMethods = [...BLOCKING_DIALOG_METHODS];
+var fireAndForgetUiMethods = [...FIRE_AND_FORGET_UI_METHODS];
+
+// packages/orchestrator/src/supervisor.ts
+var Supervisor = class extends EventEmitter2 {
+  #config;
+  #sessions = /* @__PURE__ */ new Map();
+  #processes = /* @__PURE__ */ new Map();
+  #created = 0;
+  constructor(config) {
+    super();
+    this.#config = config;
+    this.#installationRoot = resolveInstallationRoot();
+  }
+  list() {
+    return [...this.#sessions.values()];
+  }
+  get(id) {
+    return this.#sessions.get(id);
+  }
+  /**
+   * The underlying RPC process, for verification and diagnostics.
+   *
+   * Exposed so a test can issue a probe through the *model-facing* `bash` tool inside a
+   * session (verify-three.ts). Normal product code goes through the typed lifecycle methods
+   * above; this is the escape hatch that keeps the harness honest about what it exercises.
+   */
+  rpcProcess(id) {
+    return this.#processes.get(id);
+  }
+  /**
+   * Start a new session. When `cwd` is omitted this creates and uses the app-owned default
+   * workspace for the new session's id (US-1 with US-3), rather than defaulting to `$HOME`
+   * or the orchestrator's own directory.
+   */
+  start(request = {}) {
+    const mode = request.mode ?? "sandboxed";
+    const id = `s${++this.#created}`;
+    let cwd;
+    if (request.cwd) {
+      cwd = request.cwd;
+    } else {
+      try {
+        cwd = scratchDirFor(this.#config, id);
+        mkdirSync2(cwd, { recursive: true });
+      } catch (error) {
+        return { ok: false, message: error.message };
+      }
+    }
+    return this.#spawn({ id, cwd, mode, name: request.name, enable: request.enable, env: request.env });
+  }
+  /**
+   * Resume a historical session in its own recorded directory (US-5).
+   *
+   * The cwd is validated here, before spawning, because RPC-mode Pi exits `1` on a missing
+   * directory rather than prompting (C2). The session's directory is never changed
+   * (ADR-0008); an unusable directory is refused, not retargeted.
+   */
+  resume(session, options = {}) {
+    const readiness = checkResumable(session);
+    if (!readiness.ok) return { ok: false, message: readiness.message };
+    const live = this.#findLiveByPath(session.path);
+    if (live) return { ok: true, session: live };
+    const id = `s${++this.#created}`;
+    return this.#spawn({
+      id,
+      cwd: readiness.cwd,
+      mode: options.mode ?? "sandboxed",
+      // 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
+    });
+  }
+  #findLiveByPath(sessionPath) {
+    for (const session of this.#sessions.values()) {
+      if (session.sessionFile === sessionPath && session.state !== "stopped" && session.state !== "failed") {
+        return session;
+      }
+    }
+    return void 0;
+  }
+  #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 keychainNeeded = providerAuth.needsKeychain;
+    const keychainPresent = existsSync4(keychainPath);
+    const fragment = input.mode === "sandboxed" ? renderPolicyFragment({
+      agentRoot: this.#config.agentRoot,
+      ...keychainNeeded ? { keychain: true, keychainPath } : {}
+    }) : void 0;
+    const spec = {
+      id: input.id,
+      cwd: input.cwd,
+      mode: input.mode,
+      safehouse: this.#config.safehouse,
+      pi: this.#config.pi,
+      env,
+      ...fragment !== void 0 ? { policyFragment: fragment, fragmentDir: this.#config.fragmentDir } : {},
+      ...input.enable ? { enable: input.enable } : {},
+      ...input.name ? { name: input.name } : {}
+    };
+    let policy;
+    try {
+      policy = composePolicy(spec);
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+    const store = readStore(this.#config.agentRoot, {
+      ownership: this.#config.agentRootManaged ? "managed" : "external"
+    });
+    const capabilities = assessAgentCapabilities({
+      store,
+      sandboxed: input.mode === "sandboxed",
+      ...fragment !== void 0 ? { fragment } : {},
+      providerAuth,
+      keychainPath
+    });
+    const session = {
+      id: input.id,
+      name: input.name?.trim() || defaultName(input.cwd, input.id),
+      cwd: input.cwd,
+      state: "starting",
+      mode: input.mode,
+      isolation: policy.isolation,
+      command: describe(policy),
+      scratch: isScratch(this.#config, input.cwd),
+      messageCount: 0,
+      pending: 0,
+      contextPercent: null,
+      tokensTotal: null,
+      cost: null,
+      dialogs: [],
+      // Policy warnings, credential warnings, and the self-hosting hazard (issues #28, #25).
+      // A session that starts and cannot think, or cannot use its own identity, is one failure this
+      // surfaces (C13, C15); a session pointed at the checkout Pi Central is running from is
+      // another, and it is warned about rather than refused — the user may have a good reason, and
+      // the consequences are what they need in order to judge (issue #25).
+      warnings: [
+        ...policy.warnings,
+        ...capabilities.warnings,
+        ...ownInstallationWarning(input.cwd, this.#installationRoot) !== void 0 ? [ownInstallationWarning(input.cwd, this.#installationRoot)] : []
+      ],
+      startedAt: Date.now(),
+      ...input.sessionPath ? { sessionFile: input.sessionPath } : {}
+    };
+    this.#sessions.set(session.id, session);
+    const rpc = new RpcProcess(this.#buildLaunch(policy.launch, input.sessionPath));
+    this.#processes.set(session.id, rpc);
+    rpc.on("record", (record) => this.#onRecord(session.id, record));
+    rpc.on("failed", (error) => {
+      session.state = "failed";
+      session.error = error.message;
+      this.#patch(session.id);
+      this.emit("error", session.id, error.message);
+    });
+    rpc.on("exit", ({ code, signal, stderr }) => {
+      if (session.state === "stopped") return;
+      session.state = "failed";
+      session.error = describeExitFailure(code, signal, stderr);
+      session.dialogs = [];
+      this.#patch(session.id);
+      this.emit("error", session.id, session.error);
+    });
+    rpc.start();
+    this.#patch(session.id);
+    void this.#refreshState(session.id);
+    return { ok: true, session };
+  }
+  /**
+   * A resumed session reopens its file (`--session <path>`); a new session is left to Pi's
+   * default naming in its workspace.
+   *
+   * `--session` is appended after the `--` separator, so it is a *pi* argument, not a
+   * safehouse one. The only value interpolated is a path validated to exist by
+   * `checkResumable`; the argument shape is fixed.
+   */
+  #buildLaunch(launch, sessionPath) {
+    if (!sessionPath) return launch;
+    return { ...launch, args: [...launch.args, "--session", sessionPath] };
+  }
+  async #refreshState(id) {
+    const session = this.#sessions.get(id);
+    const rpc = this.#processes.get(id);
+    if (!session || !rpc) return;
+    try {
+      const state = await rpc.send({ type: "get_state" }, 2e4);
+      const model = state.model;
+      session.model = model?.id;
+      session.provider = model?.provider;
+      session.thinkingLevel = state.thinkingLevel;
+      if (typeof state.sessionFile === "string") session.sessionFile = state.sessionFile;
+      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);
+      session.pending = Number(state.pendingMessageCount ?? session.pending);
+      if (session.state === "starting") session.state = state.isStreaming ? "streaming" : "idle";
+      session.error = void 0;
+      this.#patch(id);
+      void this.#refreshStats(id);
+      void this.#loadTranscript(id);
+    } catch (error) {
+      session.state = "failed";
+      session.error = `${error.message}${rpc.stderrTail ? `
+${rpc.stderrTail}` : ""}`;
+      this.#patch(id);
+    }
+  }
+  /**
+   * Fetch a session's conversation from Pi.
+   *
+   * **Authoritative and current, and nothing is cached.** That is the whole design, and it is a
+   * correction: an earlier version fetched once at session start, cached the result, and replayed
+   * the cache to every client that connected later. For a session started fresh that cache held
+   * the empty conversation from its first instant, so a reconnect REPLACED a correct transcript
+   * with an empty one — and a one-shot guard meant it could never recover. The UI then showed
+   * "Loading this session's history…" indefinitely, because Pi reported messages that the client
+   * would never receive.
+   *
+   * A cache of a conversation is stale the moment it is taken. Re-fetching costs one sub-
+   * millisecond round trip per session per connection, which is a price worth paying for being
+   * right.
+   *
+   * Returns a result rather than throwing, because callers must distinguish "the conversation is
+   * empty" from "the conversation could not be read" — the first is fine and the second must not
+   * be presented as an eternal spinner.
+   */
+  async fetchTranscript(id) {
+    const rpc = this.#processes.get(id);
+    if (!rpc) return { ok: false, message: "this session is not running" };
+    try {
+      const data = await rpc.send({ type: "get_messages" }, 3e4);
+      return {
+        ok: true,
+        messages: (data?.messages ?? []).filter(
+          (message) => typeof message === "object" && message !== null
+        )
+      };
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+  }
+  /**
+   * Load a session's conversation once, when it starts or resumes.
+   *
+   * **This is the fix for a resumed session showing an empty transcript.** Pi loads a resumed
+   * session's history into the model's context but does NOT re-emit it as events, so a UI built
+   * only from `record` events shows "No messages yet" for a session with hundreds of messages —
+   * which is precisely the case US-5 exists to serve.
+   *
+   * Re-emitted as `message_end` records rather than through a new event type, so history and a
+   * live stream take the SAME code path in the UI reducer. There is one renderer for one
+   * conversation; two is how the past and the present end up looking different.
+   *
+   * The once-only guard covers this automatic path to avoid duplicating the conversation on every
+   * state refresh. Clients that connect later call `fetchTranscript` directly instead, so they
+   * always get the CURRENT conversation rather than this session's opening state.
+   */
+  async #loadTranscript(id) {
+    const session = this.#sessions.get(id);
+    if (!session || session.transcriptLoaded) return;
+    const result = await this.fetchTranscript(id);
+    if (!result.ok) {
+      session.warnings = [
+        ...session.warnings,
+        `Could not load this session's earlier messages: ${result.message}`
+      ];
+      this.emit("transcriptError", id, result.message);
+      this.#patch(id);
+      return;
+    }
+    session.transcriptLoaded = true;
+    this.emit("transcript", id, result.messages);
+  }
+  async #refreshStats(id) {
+    const session = this.#sessions.get(id);
+    const rpc = this.#processes.get(id);
+    if (!session || !rpc || !rpc.running) return;
+    try {
+      const stats = await rpc.send({ type: "get_session_stats" }, 2e4);
+      const ctx = stats.contextUsage;
+      const tokens = stats.tokens;
+      session.contextPercent = ctx?.percent ?? null;
+      session.tokensTotal = tokens?.total ?? null;
+      session.cost = typeof stats.cost === "number" ? stats.cost : null;
+      this.#patch(id);
+    } catch {
+    }
+  }
+  #onRecord(id, record) {
+    const session = this.#sessions.get(id);
+    if (!session) return;
+    const effect = interpretRecord(session, record);
+    if (effect.dialog) session.dialogs.push(effect.dialog);
+    if (effect.patch) Object.assign(session, effect.patch);
+    if (effect.refreshStats) void this.#refreshStats(id);
+    this.emit("record", id, record);
+    if (record.type === "queue_update") {
+      this.emit(
+        "queue",
+        id,
+        asTextArray(record.steering),
+        asTextArray(record.followUp)
+      );
+    }
+    this.#patch(id);
+  }
+  answerDialog(id, dialogId, answer) {
+    const session = this.#sessions.get(id);
+    const rpc = this.#processes.get(id);
+    if (!session || !rpc) return;
+    const payload = { type: "extension_ui_response", id: dialogId };
+    if ("cancelled" in answer) payload.cancelled = true;
+    else if ("confirmed" in answer) payload.confirmed = answer.confirmed;
+    else payload.value = answer.value;
+    rpc.write(payload);
+    session.dialogs = session.dialogs.filter((dialog) => dialog.id !== dialogId);
+    if (session.dialogs.length === 0 && session.state === "awaiting-approval") session.state = "idle";
+    this.#patch(id);
+  }
+  /**
+   * Send a prompt. The command shape is closed; the message is the only free value.
+   *
+   * `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.
+   */
+  async prompt(id, message, behavior) {
+    const rpc = this.#processes.get(id);
+    const session = this.#sessions.get(id);
+    if (!rpc || !session) throw new Error(`no such session: ${id}`);
+    if (session.state === "streaming") {
+      await rpc.send({ type: "prompt", message, streamingBehavior: behavior ?? "followUp" }, 6e4);
+    } else {
+      await rpc.send({ type: "prompt", message }, 6e4);
+    }
+  }
+  /**
+   * Empty Pi's queue, and optionally stop the run, in that order.
+   *
+   * **The order is the whole point.** Pi's `clear_queue` returns the queued texts, so clearing
+   * first is what makes them recoverable: abort-then-clear would let the run settle and, in the
+   * window before the queue was emptied, Pi could begin delivering a queued message as a real
+   * turn. Clearing first removes the queue before anything else can act on it, and the returned
+   * texts are broadcast so the composer restores exactly what was removed instead of guessing.
+   *
+   * `abort` is sent directly rather than via `this.abort` so the pair cannot be reordered by a
+   * later refactor.
+   *
+   * Returns the cleared texts, so a caller that wants them does not have to wait for the event.
+   */
+  async clearQueue(id, andStop) {
+    const rpc = this.#processes.get(id);
+    if (!rpc) throw new Error(`no such session: ${id}`);
+    const result = await clearQueueVia((command, timeout) => rpc.send(command, timeout), andStop);
+    this.emit("queueCleared", id, result.steering, result.followUp);
+    return result;
+  }
+  async abort(id) {
+    const rpc = this.#processes.get(id);
+    if (rpc) await rpc.send({ type: "abort" }, 3e4);
+  }
+  async rename(id, name) {
+    const rpc = this.#processes.get(id);
+    const session = this.#sessions.get(id);
+    if (!rpc || !session) throw new Error(`no such session: ${id}`);
+    await rpc.send({ type: "set_session_name", name }, 2e4);
+    session.name = name;
+    this.#patch(id);
+  }
+  /**
+   * Ask Pi which models this session can use.
+   *
+   * Returns a result rather than throwing, for the same reason `fetchTranscript` does: the caller
+   * needs "there are none" and "the question failed" to be different events. A list rendered as
+   * empty when the command errored would say the session has no models, which is a different and
+   * false claim (C14's family).
+   */
+  async listModels(id) {
+    const rpc = this.#processes.get(id);
+    if (!rpc) return { ok: false, message: "this session is not running" };
+    try {
+      const data = await rpc.send({ type: "get_available_models" }, 3e4);
+      const models = (data?.models ?? []).filter((model) => typeof model === "object" && model !== null).map((model) => ({
+        provider: String(model["provider"] ?? ""),
+        id: String(model["id"] ?? ""),
+        ...typeof model["name"] === "string" ? { name: model["name"] } : {},
+        ...typeof model["reasoning"] === "boolean" ? { reasoning: model["reasoning"] } : {}
+      })).filter((model) => model.provider !== "" && model.id !== "");
+      return { ok: true, models };
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+  }
+  /**
+   * Change a session's model, then re-read the state Pi reports.
+   *
+   * **The session's fields are not set optimistically.** Pi validates the choice (an unconfigured
+   * provider fails with `No API key for <provider>/<model>`), persists it to the transcript, and
+   * re-applies the thinking level for the new model. Setting `session.model` from the request
+   * would therefore display a change that may not have happened, and would miss the thinking-level
+   * adjustment — the two ways this can disagree with Pi.
+   *
+   * A refusal is thrown, not swallowed: the caller broadcasts it, so it appears as an error naming
+   * the reason rather than as a control that silently did nothing.
+   */
+  async setModel(id, provider, modelId) {
+    const rpc = this.#processes.get(id);
+    const session = this.#sessions.get(id);
+    if (!rpc || !session) throw new Error(`no such session: ${id}`);
+    await rpc.send({ type: "set_model", provider, modelId }, 3e4);
+    await this.#refreshState(id);
+  }
+  /** Which thinking levels the CURRENT model supports. Per-model, so it must be re-read on a switch. */
+  async listThinkingLevels(id) {
+    const rpc = this.#processes.get(id);
+    if (!rpc) return { ok: false, message: "this session is not running" };
+    try {
+      const data = await rpc.send({ type: "get_available_thinking_levels" }, 3e4);
+      return { ok: true, levels: (data?.levels ?? []).map((level) => String(level)) };
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+  }
+  /**
+   * Change the thinking level, then re-read the state Pi reports.
+   *
+   * The same reasoning as `setModel`: Pi may reject a level the model does not support, so the
+   * value shown must be the one Pi confirms rather than the one that was asked for.
+   */
+  async setThinkingLevel(id, level) {
+    const rpc = this.#processes.get(id);
+    const session = this.#sessions.get(id);
+    if (!rpc || !session) throw new Error(`no such session: ${id}`);
+    await rpc.send({ type: "set_thinking_level", level }, 2e4);
+    await this.#refreshState(id);
+  }
+  async stop(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);
+  }
+  async stopAll() {
+    await Promise.all([...this.#processes.keys()].map((id) => this.stop(id)));
+  }
+  /**
+   * List a session's working directory (issue #8, ADR-0007).
+   *
+   * Synchronous and plain `fs`, at the orchestrator's UID — no sandbox, no RPC round trip. The
+   * confinement is the session's own `cwd`, which is why this goes through the supervisor: it is the
+   * component that knows what that cwd is, so there is exactly one answer to "what is this session
+   * confined to".
+   *
+   * An unknown session is REFUSED rather than resolved against some other root. Falling back would
+   * mean a stale session id browsed a directory that had nothing to do with it.
+   */
+  listFiles(id, path, options = {}) {
+    const session = this.#sessions.get(id);
+    if (!session) {
+      return {
+        ok: false,
+        error: { reason: "not-found", message: `no session ${id}, so there is no working directory to list` }
+      };
+    }
+    return listDirectory(session.cwd, path, options);
+  }
+  /** Read one text file from a session's working directory, confined the same way. */
+  readFile(id, path) {
+    const session = this.#sessions.get(id);
+    if (!session) {
+      return {
+        ok: false,
+        error: { reason: "not-found", message: `no session ${id}, so there is no working directory to read from` }
+      };
+    }
+    return readFileText(session.cwd, path);
+  }
+  /**
+   * Where this Pi Central installation lives, resolved once.
+   *
+   * Overridable so a test can supply a path rather than depending on where the test file happens to
+   * be — the same seam `#config` provides for everything else. `undefined` means the walk could not
+   * identify it, in which case no session is warned: an unidentifiable path is not evidence of
+   * safety, but a warning on every session would be noise, so the honest report is the absence of a
+   * claim. The startup banner says so instead, once.
+   */
+  #installationRoot;
+  setInstallationRoot(path) {
+    this.#installationRoot = path;
+  }
+  #patch(id) {
+    const session = this.#sessions.get(id);
+    if (session) this.emit("update", session);
+  }
+};
+function describeExitFailure(code, signal, stderr) {
+  const base = `pi exited (code=${code ?? "-"}, signal=${signal ?? "-"})${stderr ? `
+${stderr}` : ""}`;
+  if (!/sandbox_apply|Operation not permitted/i.test(stderr)) return base;
+  return `${base}
+
+This looks like Seatbelt refusing to nest (C1). The orchestrator must run from a plain terminal, not inside another sandbox, editor task, or agent harness -- because \`safehouse\` applies its policy with \`sandbox-exec\`, and that cannot run inside an existing sandbox.`;
+}
+function defaultName(cwd, id) {
+  const base = cwd.split("/").filter(Boolean).pop();
+  return base && base.length > 0 ? base : id;
+}
+function asTextArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item)) : [];
+}
+async function clearQueueVia(send, andStop) {
+  const cleared = await send({ type: "clear_queue" }, 2e4);
+  const result = {
+    steering: asTextArray(cleared?.steering),
+    followUp: asTextArray(cleared?.followUp)
+  };
+  if (andStop) await send({ type: "abort" }, 3e4);
+  return result;
+}
+
+// packages/orchestrator/src/transport.ts
+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 { fileURLToPath as fileURLToPath2 } from "node:url";
+var PACKAGE_NAME = "pi-central";
+function findOwnPackage(from = import.meta.url) {
+  let directory = dirname(fileURLToPath2(from));
+  for (; ; ) {
+    const candidate = join9(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);
+    if (parent === directory || directory === parse(directory).root) return void 0;
+    directory = parent;
+  }
+}
+function readPackageJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+
+// packages/orchestrator/src/registry.ts
+import { createReadStream, readdirSync as readdirSync3, statSync as statSync5 } from "node:fs";
+import { join as join10 } from "node:path";
+var KNOWN_SESSION_VERSIONS = /* @__PURE__ */ new Set([3]);
+var HEAD_BYTES = 256 * 1024;
+function decodeSessionDir(dirName) {
+  const inner = dirName.replace(/^--/, "").replace(/--$/, "");
+  return `/${inner.replace(/-/g, "/")}`;
+}
+async function readHead(path) {
+  return new Promise((resolve8) => {
+    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", () => resolve8(""));
+    stream.on("close", () => resolve8(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 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 = statSync5(path);
+      } catch {
+        continue;
+      }
+      const parsed = parseHead(await readHead(path));
+      if (!parsed) {
+        skipped.push({ path, reason: "not a Pi session file (no valid header)" });
+        continue;
+      }
+      if (!KNOWN_SESSION_VERSIONS.has(parsed.header.version)) {
+        skipped.push({ path, reason: `unknown session version ${parsed.header.version}` });
+        continue;
+      }
+      const cwd = parsed.header.cwd || decodeSessionDir(projectDir);
+      sessions.push({
+        path,
+        id: parsed.header.id,
+        cwd,
+        ...parsed.name ? { name: 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)
+      });
+    }
+  }
+  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/static-ui.ts
+import { createReadStream as createReadStream2, existsSync as existsSync6, statSync as statSync6 } from "node:fs";
+import { extname, join as join11, posix, resolve as resolve7, sep as sep4 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var UI_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8"
+};
+function resolveUiDistDir(env = process.env, from = import.meta.url) {
+  const explicit = env["PI_CENTRAL_UI_DIST"];
+  if (explicit !== void 0 && explicit !== "") return resolve7(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 fromSource = runningFromSource(from);
+  const candidates = fromSource ? [workspace, packaged] : [packaged, workspace];
+  for (const candidate of candidates) {
+    if (hasBuiltUi(candidate)) return candidate;
+  }
+  return fromSource ? workspace : packaged;
+}
+function runningFromSource(from) {
+  return /[\\/]packages[\\/][^\\/]+[\\/]src[\\/]/.test(fileURLToPath3(from));
+}
+function isInside3(root, candidate) {
+  const rootPath = resolve7(root);
+  const target = resolve7(candidate);
+  if (target === rootPath) return true;
+  return target.startsWith(rootPath.endsWith(sep4) ? rootPath : rootPath + sep4);
+}
+function resolveStaticPath(root, requestTarget) {
+  const rootPath = resolve7(root);
+  const target = requestTarget.split("?")[0].split("#")[0];
+  let decoded;
+  try {
+    decoded = decodeURIComponent(target);
+  } catch {
+    return { kind: "denied", reason: "the request target is not valid percent-encoding" };
+  }
+  if (decoded.includes("\0")) return { kind: "denied", reason: "the request target contains a NUL byte" };
+  if (!decoded.startsWith("/")) return { kind: "denied", reason: "the request target is not an absolute path" };
+  if (decoded.split("/").includes("..")) {
+    return { kind: "denied", reason: "the request target contains a '..' segment" };
+  }
+  const relative = posix.normalize(decoded).replace(/^\/+/, "");
+  const candidate = resolve7(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 = resolve7(options.root);
+  const csp = options.csp ?? UI_CSP;
+  const indexPath = resolve7(root, "index.html");
+  return (req, res) => {
+    const method = req.method ?? "GET";
+    if (method !== "GET" && method !== "HEAD") {
+      res.writeHead(405, {
+        "content-type": "text/plain; charset=utf-8",
+        allow: "GET, HEAD",
+        "content-security-policy": csp
+      });
+      res.end("this listener serves GET and HEAD only\n");
+      return;
+    }
+    const resolution = resolveStaticPath(root, req.url ?? "/");
+    if (resolution.kind === "denied") {
+      sendText(res, method, 403, `refused: ${resolution.reason}
+`, csp);
+      return;
+    }
+    const path = resolution.path;
+    if (isReadableFile(path)) {
+      sendFile(res, method, path, csp);
+      return;
+    }
+    const lastSegment = posix.basename(path);
+    const looksLikeRoute = !lastSegment.includes(".") || path === root;
+    if (looksLikeRoute) {
+      if (isReadableFile(indexPath)) {
+        sendFile(res, method, indexPath, csp);
+        return;
+      }
+      sendText(
+        res,
+        method,
+        500,
+        `The UI has not been built, so there is nothing to serve.
+
+Build it with:
+  npm run ui:build
+
+(looked for ${indexPath})
+`,
+        csp
+      );
+      return;
+    }
+    sendText(res, method, 404, `no such file under the served UI root: ${posix.basename(path)}
+`, csp);
+  };
+}
+function isReadableFile(path) {
+  try {
+    return statSync6(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function sendText(res, method, status, body, csp) {
+  const bytes = Buffer.byteLength(body);
+  res.writeHead(status, {
+    "content-type": "text/plain; charset=utf-8",
+    "content-length": String(bytes),
+    "x-content-type-options": "nosniff",
+    "content-security-policy": csp
+  });
+  if (method === "HEAD") res.end();
+  else res.end(body);
+}
+function sendFile(res, method, path, csp) {
+  const info = statSync6(path);
+  const type = CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+  const immutable = path.includes(`${sep4}assets${sep4}`);
+  res.writeHead(200, {
+    "content-type": type,
+    "content-length": String(info.size),
+    "content-security-policy": csp,
+    "x-content-type-options": "nosniff",
+    "cache-control": immutable ? "public, max-age=31536000, immutable" : "no-cache"
+  });
+  if (method === "HEAD") {
+    res.end();
+    return;
+  }
+  const stream = createReadStream2(path);
+  stream.on("error", () => res.destroy());
+  stream.pipe(res);
+}
+function hasBuiltUi(root) {
+  return existsSync6(resolve7(root, "index.html"));
+}
+
+// packages/orchestrator/src/transport.ts
+var KNOWN_CONTROL_KINDS = /* @__PURE__ */ new Set([
+  "list",
+  "start",
+  "prompt",
+  "clearQueue",
+  "abort",
+  "stop",
+  "rename",
+  "setModel",
+  "listModels",
+  "setThinkingLevel",
+  "listThinkingLevels",
+  "answerDialog",
+  "resume",
+  "listFiles",
+  "readFile"
+]);
+function parseControl(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { error: "not JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { error: "not an object" };
+  const envelope = parsed;
+  if (envelope.dir !== "client\u2192orchestrator") {
+    return { error: `wrong direction: expected 'client\u2192orchestrator', got '${String(envelope.dir)}'` };
+  }
+  if (envelope.protocol !== PROTOCOL_VERSION) {
+    return { error: `protocol mismatch: expected ${PROTOCOL_VERSION}, got ${String(envelope.protocol)}` };
+  }
+  const payload = envelope.payload;
+  if (typeof payload !== "object" || payload === null || typeof payload.kind !== "string") {
+    return { error: "payload has no kind" };
+  }
+  return payload;
+}
+var Transport = class {
+  #supervisor;
+  #config;
+  #options;
+  #server;
+  #wss;
+  #clients = /* @__PURE__ */ new Set();
+  #address;
+  #install;
+  constructor(supervisor, config, options = {}) {
+    this.#supervisor = supervisor;
+    this.#config = config;
+    this.#options = {
+      host: options.host ?? "127.0.0.1",
+      port: options.port ?? 0,
+      maxClients: options.maxClients ?? 8,
+      uiDir: options.uiDir === void 0 ? resolveUiDistDir() : options.uiDir
+    };
+  }
+  get address() {
+    return this.#address;
+  }
+  /** The UI directory being served, or `null` when the socket is the only surface. */
+  get uiDir() {
+    return this.#options.uiDir;
+  }
+  /** Bind and start serving. Resolves with the actual address (port 0 → a real port). */
+  async listen() {
+    if (this.#server) throw new Error("transport is already listening");
+    const uiHandler = this.#options.uiDir === null ? void 0 : createUiRequestHandler({ root: this.#options.uiDir });
+    const server = createServer((req, res) => {
+      if (uiHandler) {
+        uiHandler(req, res);
+        return;
+      }
+      res.writeHead(426, { "content-type": "text/plain" });
+      res.end("Pi Central speaks WebSocket only, and no UI directory is configured.\n");
+    });
+    const wss = new WebSocketServer({ server, maxPayload: 8 * 1024 * 1024 });
+    this.#server = server;
+    this.#wss = wss;
+    wss.on("connection", (socket) => this.#onConnection(socket));
+    await new Promise((resolve8, reject) => {
+      server.once("error", reject);
+      server.listen(this.#options.port, this.#options.host, () => {
+        server.off("error", reject);
+        resolve8();
+      });
+    });
+    const addr = server.address();
+    if (addr === null || typeof addr === "string") throw new Error("unexpected server address");
+    this.#address = {
+      host: this.#options.host,
+      port: addr.port,
+      url: `ws://${this.#options.host}:${addr.port}`
+    };
+    return this.#address;
+  }
+  #onConnection(socket) {
+    if (this.#clients.size >= this.#options.maxClients) {
+      this.#send(socket, { kind: "error", message: `too many clients (max ${this.#options.maxClients})` });
+      socket.close(1013, "too many clients");
+      return;
+    }
+    this.#clients.add(socket);
+    this.#send(socket, { kind: "hello", protocol: PROTOCOL_VERSION });
+    void this.#sendSnapshot(socket);
+    socket.on("message", (data) => void this.#onMessage(socket, String(data)));
+    socket.on("close", () => this.#clients.delete(socket));
+    socket.on("error", () => this.#clients.delete(socket));
+  }
+  /**
+   * Facts about this installation, for the Settings surface (issue #58).
+   *
+   * Computed once and cached: `findOwnPackage` walks the directory tree, and this is sent on every
+   * connection. The version cannot change while the process runs, so recomputing it per connection
+   * would be work done to produce a value already known to be identical.
+   */
+  #installFacts() {
+    if (this.#install !== void 0) return this.#install;
+    const own = findOwnPackage();
+    this.#install = {
+      // "unknown" rather than a substituted "0.0.0": a version that cannot be determined is a
+      // packaging fault, and saying so is truthful. A plausible-looking default would be believed,
+      // and every question asked afterwards would start from a false premise.
+      version: own?.version ?? "unknown",
+      sessionsRoot: this.#config.sessionsRoot,
+      workspaceRoot: this.#config.workspaceRoot,
+      agentRoot: this.#config.agentRoot,
+      agentRootManaged: this.#config.agentRootManaged,
+      protocol: PROTOCOL_VERSION
+    };
+    return this.#install;
+  }
+  async #sendSnapshot(socket) {
+    let history = [];
+    let historyTotal = 0;
+    try {
+      const discovered = await discover(this.#config);
+      history = discovered.sessions;
+      historyTotal = discovered.total;
+    } catch (error) {
+      this.#send(socket, { kind: "error", message: `discovery failed: ${error.message}` });
+    }
+    this.#send(socket, {
+      kind: "snapshot",
+      live: this.#supervisor.list(),
+      history,
+      historyTotal,
+      home: this.#config.home,
+      installationRoot: this.#config.installationRoot,
+      install: this.#installFacts()
+    });
+    for (const session of this.#supervisor.list()) {
+      if (session.state === "stopped" || session.state === "failed") continue;
+      void this.#sendTranscript(socket, session.id);
+    }
+  }
+  /** Fetch one session's conversation for one client, and report failure as a failure. */
+  async #sendTranscript(socket, sessionId) {
+    const result = await this.#supervisor.fetchTranscript(sessionId);
+    if (!result.ok) {
+      this.#send(socket, { kind: "transcriptError", sessionId, message: result.message });
+      return;
+    }
+    this.#send(socket, { kind: "transcript", sessionId, messages: result.messages });
+  }
+  async #onMessage(socket, raw) {
+    const control = parseControl(raw);
+    if ("error" in control) {
+      this.#send(socket, { kind: "error", message: `bad control: ${control.error}` });
+      return;
+    }
+    if (!KNOWN_CONTROL_KINDS.has(control.kind)) {
+      this.#send(socket, { kind: "error", message: `bad control: unknown kind '${control.kind}'` });
+      return;
+    }
+    try {
+      await this.#dispatch(control);
+    } catch (error) {
+      this.#send(socket, { kind: "error", message: error.message });
+    }
+  }
+  /**
+   * Route one control message.
+   *
+   * The switch is exhaustive over `Control`, so adding a command to the protocol without
+   * handling it here is a compile error rather than a silent no-op.
+   */
+  async #dispatch(control) {
+    switch (control.kind) {
+      case "list": {
+        const discovered = await discover(this.#config);
+        this.#broadcast({ kind: "history", history: discovered.sessions, total: discovered.total });
+        this.#broadcast({
+          kind: "snapshot",
+          live: this.#supervisor.list(),
+          history: discovered.sessions,
+          historyTotal: discovered.total,
+          home: this.#config.home,
+          installationRoot: this.#config.installationRoot
+        });
+        return;
+      }
+      case "start": {
+        const result = this.#supervisor.start({
+          ...control.cwd ? { cwd: control.cwd } : {},
+          ...control.name ? { name: control.name } : {},
+          ...control.mode ? { mode: control.mode } : {}
+        });
+        if (!result.ok) {
+          this.#broadcast({ kind: "error", message: result.message });
+          return;
+        }
+        this.#broadcast({ kind: "session", session: result.session });
+        return;
+      }
+      case "resume": {
+        const discovered = await discover(this.#config);
+        const target = discovered.sessions.find((s) => s.path === control.path);
+        if (!target) {
+          this.#broadcast({ kind: "error", message: `no such session: ${control.path}` });
+          return;
+        }
+        const result = this.#supervisor.resume(target, control.mode ? { mode: control.mode } : {});
+        if (!result.ok) {
+          this.#broadcast({ kind: "error", message: result.message });
+          return;
+        }
+        this.#broadcast({ kind: "session", session: result.session });
+        return;
+      }
+      case "prompt":
+        await this.#supervisor.prompt(
+          control.sessionId,
+          control.message,
+          ...control.behavior ? [control.behavior] : []
+        );
+        return;
+      case "clearQueue": {
+        await this.#supervisor.clearQueue(control.sessionId, control.andStop);
+        return;
+      }
+      case "abort":
+        await this.#supervisor.abort(control.sessionId);
+        return;
+      case "stop":
+        await this.#supervisor.stop(control.sessionId);
+        return;
+      case "rename":
+        await this.#supervisor.rename(control.sessionId, control.name);
+        return;
+      case "listModels": {
+        const result = await this.#supervisor.listModels(control.sessionId);
+        if (result.ok) this.#broadcast({ kind: "models", sessionId: control.sessionId, models: result.models });
+        else this.#broadcast({ kind: "modelsError", sessionId: control.sessionId, message: result.message });
+        return;
+      }
+      case "setModel": {
+        await this.#supervisor.setModel(control.sessionId, control.provider, control.modelId);
+        return;
+      }
+      case "listThinkingLevels": {
+        const result = await this.#supervisor.listThinkingLevels(control.sessionId);
+        if (result.ok) this.#broadcast({ kind: "thinkingLevels", sessionId: control.sessionId, levels: result.levels });
+        else this.#broadcast({ kind: "thinkingLevelsError", sessionId: control.sessionId, message: result.message });
+        return;
+      }
+      case "setThinkingLevel":
+        await this.#supervisor.setThinkingLevel(control.sessionId, control.level);
+        return;
+      case "answerDialog":
+        this.#supervisor.answerDialog(control.sessionId, control.dialogId, control.answer);
+        return;
+      // --- File browsing (issue #8, ADR-0007) ------------------------------------------------
+      //
+      // Resolved through the SUPERVISOR, not straight to `files.ts`, because the root is the
+      // session's cwd and only the supervisor knows it. That keeps one answer to "which directory is
+      // this session confined to" — and it means a request for an unknown session is refused as
+      // such, rather than being resolved against some path the transport guessed.
+      //
+      // Everything below is read at the ORCHESTRATOR's UID, deliberately (ADR-0007). No sandbox is
+      // involved: Safehouse confines agents, and this serves the person.
+      case "listFiles": {
+        const result = this.#supervisor.listFiles(control.sessionId, control.path, {
+          ...control.includeHidden === void 0 ? {} : { includeHidden: control.includeHidden }
+        });
+        if (result.ok) {
+          this.#broadcast({
+            kind: "files",
+            sessionId: control.sessionId,
+            // The path as the CLIENT sent it, not the normalized one the orchestrator resolved.
+            // The client keys its cache, its `loading` state and its expansion flag by the path it
+            // requested, so echoing a different spelling would file the result under one key while
+            // the node waited on another — leaving it in "Reading…" forever. Normalization stays
+            // inside the orchestrator, where it is used for the filesystem work and for messages.
+            path: control.path,
+            entries: result.value.entries,
+            truncated: result.value.truncated
+          });
+        } else {
+          this.#broadcastFileError(control.sessionId, control.path, "list", result.error);
+        }
+        return;
+      }
+      case "readFile": {
+        const result = this.#supervisor.readFile(control.sessionId, control.path);
+        if (result.ok) {
+          this.#broadcast({
+            kind: "file",
+            sessionId: control.sessionId,
+            // As sent, for the same reason as `files`: one key for the client's bookkeeping.
+            path: control.path,
+            text: result.value.text,
+            bytes: result.value.bytes
+          });
+        } else {
+          this.#broadcastFileError(control.sessionId, control.path, "read", result.error);
+        }
+        return;
+      }
+    }
+  }
+  /**
+   * Report a refused file request.
+   *
+   * `path` is echoed as the client SENT it, not as it resolved — the complaint is about what was
+   * asked for, and a resolved path would describe something the user never typed.
+   *
+   * `request` distinguishes a failed listing from a failed read, so the client routes the error to the
+   * right cache instead of guessing which request it answered.
+   */
+  #broadcastFileError(sessionId, path, request, error) {
+    this.#broadcast({
+      kind: "fileError",
+      request,
+      sessionId,
+      path,
+      reason: error.reason,
+      ...error.code === void 0 ? {} : { code: error.code },
+      message: error.message
+    });
+  }
+  /** Fan out to every client. One slow client must not stall the others. */
+  #broadcast(event) {
+    for (const socket of this.#clients) this.#send(socket, event);
+  }
+  #send(socket, event) {
+    if (socket.readyState !== socket.OPEN) return;
+    const envelope = { dir: "orchestrator\u2192client", protocol: PROTOCOL_VERSION, payload: event };
+    socket.send(JSON.stringify(envelope));
+  }
+  /**
+   * Forward supervisor events to clients.
+   *
+   * Called by the entry point after construction, because it wires the supervisor's
+   * `EventEmitter` to the socket. Kept out of the constructor so a test can build a
+   * transport without an emitting supervisor.
+   */
+  attach() {
+    this.#supervisor.on("update", (session) => {
+      this.#broadcast({ kind: "session", session });
+    });
+    this.#supervisor.on("record", (sessionId, record) => {
+      this.#broadcast({ kind: "record", sessionId, record });
+    });
+    this.#supervisor.on("transcript", (sessionId, messages) => {
+      this.#broadcast({ kind: "transcript", sessionId, messages });
+    });
+    this.#supervisor.on("transcriptError", (sessionId, message) => {
+      this.#broadcast({ kind: "transcriptError", sessionId, message });
+    });
+    this.#supervisor.on("queue", (sessionId, steering, followUp) => {
+      this.#broadcast({ kind: "queue", sessionId, steering, followUp });
+    });
+    this.#supervisor.on(
+      "queueCleared",
+      (sessionId, steering, followUp) => {
+        this.#broadcast({ kind: "queueCleared", sessionId, steering, followUp });
+      }
+    );
+    this.#supervisor.on("error", (sessionId, message) => {
+      this.#broadcast({ kind: "error", message, sessionId });
+    });
+  }
+  async close() {
+    for (const socket of this.#clients) socket.close(1001, "server shutting down");
+    this.#clients.clear();
+    const wss = this.#wss;
+    const server = this.#server;
+    this.#wss = void 0;
+    this.#server = void 0;
+    this.#address = void 0;
+    if (wss) await new Promise((resolve8) => wss.close(() => resolve8()));
+    if (server) await new Promise((resolve8) => server.close(() => resolve8()));
+  }
+};
+
+// packages/orchestrator/src/sandbox-guard.ts
+import { spawnSync } from "node:child_process";
+function probeSandbox(execPath = "/usr/bin/sandbox-exec") {
+  const result = spawnSync(execPath, ["-p", "(version 1)(allow default)", "--", "/usr/bin/true"], {
+    encoding: "utf8",
+    timeout: 1e4
+  });
+  if (result.error) {
+    return { canNest: false, detail: `cannot run ${execPath}: ${result.error.message}` };
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr ?? "").trim();
+    return {
+      canNest: false,
+      detail: stderr.length > 0 ? stderr : `exited ${result.status ?? "on a signal"}`
+    };
+  }
+  return { canNest: true, detail: "ok" };
+}
+var SandboxedEnvironmentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxedEnvironmentError";
+  }
+};
+function assertNotSandboxed(execPath = "/usr/bin/sandbox-exec") {
+  const probe = probeSandbox(execPath);
+  if (probe.canNest) return probe;
+  throw new SandboxedEnvironmentError(
+    [
+      "Pi Central cannot start: this process is inside a sandbox, and Seatbelt does not nest (C1).",
+      "",
+      `  probe: ${execPath} -p '(version 1)(allow default)' -- /usr/bin/true`,
+      `  result: ${probe.detail}`,
+      "",
+      "Every session would be spawned through `safehouse`, which applies a policy with",
+      "`sandbox-exec` -- and that fails with EPERM here, so every session would fail for a",
+      "reason that looks like a launcher bug.",
+      "",
+      "Run Pi Central from a plain shell (not a sandboxed terminal, editor task, or agent",
+      "harness). The orchestrator is intentionally unsandboxed at the user's UID (ADR-0002)."
+    ].join("\n")
+  );
+}
+
+// packages/orchestrator/src/server.ts
+function versionLine() {
+  const own = findOwnPackage();
+  if (own === void 0) return `${PACKAGE_NAME} (version unknown: no package.json found)`;
+  return `${own.name} ${own.version}`;
+}
+function printHelp() {
+  console.log(`${versionLine()}
+
+Usage: ${PACKAGE_NAME} [options]
+
+Options:
+  --port <n>                 Port to listen on (default 8787; 0 asks for any free one)
+  --direct                   Start sessions WITHOUT the sandbox (feasibility only)
+  --ui-dist <dir>            Serve a built UI from this directory
+  --no-ui                    Serve the socket only (use with a dev server)
+  --allow-unsandboxed-host   Skip the sandbox probe, for a host with no sandbox-exec (C10)
+  --version, -v              Print the version and exit
+  --help, -h                 Print this and exit
+
+Pi Central starts sessions with \`pi\` under Agent Safehouse. Run it from a PLAIN terminal:
+Seatbelt does not nest, so a sandboxed shell cannot start a sandboxed session (C1).`);
+}
+var DEFAULT_PORT = 8787;
+function parseArgs(argv) {
+  const options = {
+    port: DEFAULT_PORT,
+    mode: "sandboxed",
+    allowUnsandboxedHost: false,
+    uiDir: resolveUiDistDir(),
+    showVersion: false,
+    showHelp: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--version" || arg === "-v") {
+      options.showVersion = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.showHelp = true;
+    } else if (arg === "--port") {
+      const value = Number(argv[++i]);
+      if (Number.isInteger(value) && value >= 0 && value <= 65535) options.port = value;
+      else {
+        console.error(`--port expects a number between 0 and 65535, got ${String(argv[i])}`);
+        process.exit(2);
+      }
+    } else if (arg === "--direct") {
+      options.mode = "direct";
+    } else if (arg === "--allow-unsandboxed-host") {
+      options.allowUnsandboxedHost = true;
+    } else if (arg === "--ui-dist") {
+      const value = argv[++i];
+      if (value === void 0 || value === "") {
+        console.error("--ui-dist expects a directory containing a built UI");
+        process.exit(2);
+      }
+      options.uiDir = value;
+    } else if (arg === "--no-ui") {
+      options.uiDir = null;
+    }
+  }
+  return options;
+}
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.showVersion) {
+    console.log(versionLine());
+    return 0;
+  }
+  if (options.showHelp) {
+    printHelp();
+    return 0;
+  }
+  if (!options.allowUnsandboxedHost) {
+    try {
+      assertNotSandboxed();
+    } catch (error) {
+      if (error instanceof SandboxedEnvironmentError) {
+        console.error(error.message);
+        return 2;
+      }
+      throw error;
+    }
+  }
+  const config = defaultConfig();
+  const supervisor = new Supervisor(config);
+  const transport = new Transport(supervisor, config, { port: options.port, uiDir: options.uiDir });
+  transport.attach();
+  const address = await transport.listen();
+  console.log(`PI_CENTRAL_URL=${address.url}`);
+  console.log(`Pi Central listening on ${address.url}`);
+  console.log(`  sessions root: ${config.sessionsRoot}`);
+  console.log(`  default workspace: ${config.workspaceRoot}`);
+  console.log(`  agent root: ${config.agentRoot}${config.agentRootManaged ? " (managed)" : " (external)"}`);
+  console.log(`  isolation: ${options.mode}`);
+  if (config.installationRoot === void 0) {
+    console.log(
+      `Self-hosting check: could not identify this installation's own directory, so sessions are
+  not warned when they point at it. Point a session at a checkout of Pi Central and you may
+  still hit the problems in docs/DOGFOODING.md.`
+    );
+  } else {
+    console.log(`Self-hosting check: this installation is ${config.installationRoot}`);
+  }
+  console.log("");
+  const httpUrl = address.url.replace(/^ws/, "http");
+  if (options.uiDir === null) {
+    console.log(`UI: not served (--no-ui). Use a dev server, or drop the flag to serve a build.`);
+  } else if (hasBuiltUi(options.uiDir)) {
+    console.log(`Open ${httpUrl} \u2014 the UI is served from ${options.uiDir}`);
+  } else {
+    console.log(
+      `No built UI at ${options.uiDir}
+  Build it with:  npm run ui:build
+  Or serve the socket only with:  --no-ui  (and run npm run ui:dev)`
+    );
+  }
+  console.log("");
+  if (options.uiDir !== null && hasBuiltUi(options.uiDir)) {
+    console.log(`Start a session from the UI at ${httpUrl}. Press Ctrl-C to stop every session and exit.`);
+  } else if (options.port !== DEFAULT_PORT) {
+    console.log(`Non-default port. Start the dev UI with:
+  PI_CENTRAL_WS=${address.url} npm run ui:dev`);
+    console.log("");
+    console.log("Start a session from the UI. Press Ctrl-C to stop every session and exit.");
+  } else {
+    console.log(`Start the dev UI in another terminal:  npm run ui:dev`);
+    console.log("");
+    console.log("Start a session from the UI. Press Ctrl-C to stop every session and exit.");
+  }
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`
+${signal} received; stopping sessions...`);
+    await transport.close().catch(() => void 0);
+    await supervisor.stopAll().catch(() => void 0);
+    console.log("stopped.");
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  return 0;
+}
+main().then(
+  (code) => {
+    if (code !== 0) process.exit(code);
+  },
+  (error) => {
+    console.error(`Pi Central failed to start: ${error.message}`);
+    process.exit(1);
+  }
+);
+//# sourceMappingURL=pi-central.js.map