pi-microsandbox 0.2.0 → 0.3.0

package/docs/troubleshooting.md

@@ -4,19 +4,38 @@
 
 1. Run `/msb status` and `/msb logs`.
 2. If the state is `unavailable (blocked)`, fix the displayed configuration,
-   image, virtualization, or missing-tool error and run `/msb reload`.
+   image, virtualization, path, or missing-tool error and run `/msb reload`.
+   Startup failures fail closed; routed tools do not silently run on the host.
 3. If a process died, a later startup or `/msb prune` can remove its labelled
-   sandbox after the owner lock is free. The named volume is retained.
-4. If a same-name resource has different managed labels, pi-microsandbox refuses to
-   attach or replace it. Remove only a verified managed, unmounted volume with
-   `/msb volumes rm NAME --yes`.
-5. On unsupported virtualization hosts, use `PI_MSB_DISABLE=1` for explicit host
-   mode or configure `fallback_mode = "host"` knowingly. The latter remains
-   visibly distinct from `/msb off`.
+   sandbox after the owner lock is free.
+4. If a same-name resource has different managed labels, pi-microsandbox
+   refuses to attach or replace it. Verify the resource with Microsandbox's
+   tooling before removing it.
+5. On unsupported virtualization hosts, use `PI_MSB_DISABLE=1` or `/msb off`
+   for explicit host mode, or configure `fallback_mode = "host"` knowingly.
+   Automatic fallback remains visibly distinct from explicit off mode; both are
+   unsandboxed.
 6. For bootstrap failures, use an image that already contains the required
    command list or allow the configured network policy to reach the package
    repositories. Deny mode cannot bootstrap an image missing those commands.
 
+There are no workspace modes. A cwd inside Git mounts the entire worktree root
+read/write at the same guest path; any other cwd mounts itself. If startup fails
+because the selected root or symlink layout cannot be represented safely, fix
+the host path rather than expecting a narrower mount. Remember that writes are
+immediate, `.git`, secrets, untracked files, and sibling directories are
+visible, concurrent sessions share a checkout, and nested containers can reach
+the mount.
+
+## Legacy named volumes
+
+Named Git volumes created by older releases are never migrated or deleted
+automatically. Before upgrading, use the old `/msb volumes` and `/msb export`
+commands to inventory and copy work while those commands are available. After
+upgrading, use Microsandbox's volume tooling to inspect and recover each
+`pi-msb-vol-*` volume, then remove it manually only after confirming that
+nothing is needed. Current pi-microsandbox commands do not manage these volumes.
+
 ## Docker daemon problems
 
 `/msb status` shows the configured Docker mode, readiness, server version, and
@@ -38,7 +57,9 @@ larger Compose stacks should have 2 GiB or more; the default is 8 GiB.
 A published container port needs two mappings. Configure the outer
 `network.publish_ports` mapping before sandbox creation, then use Docker `-p`
 inside the guest. A Docker mapping by itself is not reachable from the host.
-Pull and container-egress failures under `deny` or `allowlist` are expected;
-do not bypass the outer policy or mount the host Docker socket as a workaround.
+Pull and container-egress failures under `deny` or `allowlist` are expected; do
+not bypass the outer policy or mount the host Docker socket as a workaround.
 
-For installation prerequisites, see [installation and requirements](getting-started.md). To test a live sandbox from source, see the [live test matrix](development.md#live-test-matrix).
+For installation prerequisites, see
+[installation and requirements](getting-started.md). To test a live sandbox
+from source, see the [live test matrix](development.md#live-test-matrix).

package/extensions/pi-msb/command.ts

@@ -2,12 +2,10 @@ import type {
   ExtensionAPI,
   ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
-import {
-  LABEL_KEYS,
-  type MsbControl,
-  type PruneReport,
-  type RuntimeState,
-  type VolumeRecord,
+import type {
+  MsbControl,
+  PruneReport,
+  RuntimeState,
 } from "./types.ts";
 
 /** The small part of Pi's command context used by this module. */
@@ -24,10 +22,7 @@ const HELP = `Usage: /msb <command>
 
 /status                         Show the current runtime
 /on | /off | /reload            Change runtime state
-/prune                          Remove stale sandboxes (never volumes)
-/volumes ls                     List retained volumes
-/volumes rm <name> [--yes]      Remove one unmounted managed volume
-/export <paths...> [--to dir]   Safely export files from the sandbox
+/prune                          Remove stale sandboxes
 /logs [tail-lines]              Show recent sandbox logs
 /config                         Show redacted effective configuration
 /set <key> <value>              Set a session override
@@ -52,19 +47,6 @@ function displayTime(createdAt: number | undefined): string {
   return `${Math.floor(hours / 24)}d`;
 }
 
-function formatBytes(bytes: number | undefined): string {
-  if (bytes === undefined || !Number.isFinite(bytes)) return "unknown";
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KiB", "MiB", "GiB", "TiB"];
-  let value = bytes;
-  let unit = -1;
-  while (value >= 1024 && unit < units.length - 1) {
-    value /= 1024;
-    unit++;
-  }
-  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unit]}`;
-}
-
 /**
  * Format the short footer/status representation. A display ID is deliberately
  * not used as an identity here; the full sandbox name is the authoritative name.
@@ -74,7 +56,7 @@ export function formatStatus(state: RuntimeState): string | undefined {
     case "active": {
       const info = state.info;
       if (!info) return "MSB active (sandbox details unavailable)";
-      return `MSB active · ${info.mode} · ${info.name}`;
+      return `MSB active · ${info.root} · ${info.name}`;
     }
     case "booting":
       return "MSB booting…";
@@ -99,12 +81,9 @@ export function systemPromptNote(state: RuntimeState): string {
     case "active": {
       const info = state.info;
       if (!info) return "MSB is active, but runtime details are unavailable.";
-      const volume = info.volumeName
-        ? ` Retained volume: ${info.volumeName}${info.volumeHostPath ? ` at ${info.volumeHostPath}` : ""}.`
-        : "";
       const targetWarning =
         " Host-target execution, when enabled, is an explicit escape from the sandbox and should be used deliberately.";
-      return `MSB sandbox is active in ${info.mode} mode (${info.name}).${volume}${targetWarning}`;
+      return `MSB sandbox ${info.name} has the host workspace mounted read/write at ${info.root}.${targetWarning}`;
     }
     case "off":
       return "MSB is explicitly off: tools run on the host. No sandbox is active.";
@@ -194,7 +173,8 @@ function fullState(state: RuntimeState): string {
   }
 
   lines.push(`Name: ${info.name}`);
-  lines.push(`Mode: ${info.mode}`);
+  lines.push(`Workspace root: ${info.root}`);
+  lines.push(`Workdir: ${info.cwd}`);
   lines.push(`Image: ${info.image}`);
   lines.push(`PID: ${info.pid}`);
   lines.push(`Age: ${displayTime(info.createdAt)}`);
@@ -203,30 +183,9 @@ function fullState(state: RuntimeState): string {
   if (info.docker.version) lines.push(`Docker version: ${info.docker.version}`);
   if (info.docker.storageDriver) lines.push(`Docker storage driver: ${info.docker.storageDriver}`);
   if (info.docker.reason) lines.push(`Docker reason: ${info.docker.reason}`);
-  if (info.seedBranch) lines.push(`Branch: ${info.seedBranch}`);
-  if (info.seedSha) lines.push(`Seed SHA: ${info.seedSha}`);
-  if (info.volumeName) lines.push(`Retained volume: ${info.volumeName}`);
-  if (info.volumeHostPath) lines.push(`Volume path: ${info.volumeHostPath}`);
   return lines.join("\n");
 }
 
-function volumeLine(
-  volume: VolumeRecord,
-  details?: {
-    branch?: string;
-    lastCommit?: string;
-    dirtyCount?: number;
-    mounted?: boolean;
-  },
-): string {
-  const labels = volume.labels;
-  const branch = details?.branch ?? labels[LABEL_KEYS.seedBranch] ?? "-";
-  const lastCommit = details?.lastCommit ?? labels[LABEL_KEYS.seedSha] ?? "-";
-  const dirty = details?.dirtyCount === undefined ? "unknown" : String(details.dirtyCount);
-  const mounted = details?.mounted ? " mounted" : "";
-  return `${volume.name}  labels=${JSON.stringify(labels)}  path=${volume.hostPath}  size=${formatBytes(volume.usedBytes)}  age=${displayTime(volume.createdAt)}  branch=${branch}  last=${lastCommit}  dirty=${dirty}${mounted}`;
-}
-
 function redactedError(error: unknown, control: MsbControl): string {
   let message = error instanceof Error ? error.message : String(error);
   try {
@@ -243,15 +202,6 @@ function notify(ctx: CommandContext, message: string, type: "info" | "warning" |
   ctx.ui.notify(message, type);
 }
 
-async function confirm(
-  ctx: CommandContext,
-  title: string,
-  message: string,
-): Promise<boolean> {
-  if (!ctx.hasUI || typeof ctx.ui.confirm !== "function") return false;
-  return ctx.ui.confirm(title, message);
-}
-
 function parseTail(args: string[]): number | undefined {
   if (!args.length) return undefined;
   if (args.length !== 1 || !/^\d+$/.test(args[0])) {
@@ -262,118 +212,11 @@ function parseTail(args: string[]): number | undefined {
   return tail;
 }
 
-async function listVolumes(control: MsbControl): Promise<string> {
-  const volumes = await control.listVolumes();
-  if (!volumes.length) return "No retained volumes.\nVolumes are never pruned automatically.";
-  const rows = await Promise.all(
-    volumes.map(async (volume) => {
-      try {
-        const described = await control.describeVolume(volume.name);
-        return volumeLine(volume, described);
-      } catch {
-        return volumeLine(volume);
-      }
-    }),
-  );
-  return ["Retained volumes (volumes are never pruned automatically):", ...rows].join("\n");
-}
-
 function pruneSummary(report: PruneReport): string {
   const removed = report.removed.length ? report.removed.join(", ") : "none";
   const kept = report.kept.length ? report.kept.join(", ") : "none";
   const errors = report.errors.length ? report.errors.join("; ") : "none";
-  return `Prune complete\nInspected: ${report.inspected}\nRemoved: ${removed}\nKept: ${kept}\nErrors: ${errors}\nVolumes are never pruned.`;
-}
-
-async function handleVolumeRemove(
-  args: string[],
-  ctx: CommandContext,
-  control: MsbControl,
-): Promise<void> {
-  const yes = args.includes("--yes");
-  const names = args.filter((arg) => arg !== "--yes");
-  if (names.length !== 1 || args.filter((arg) => arg === "--yes").length > 1) {
-    throw new Error("usage: /msb volumes rm <name> [--yes]");
-  }
-  await ctx.waitForIdle();
-  const name = names[0];
-  const described = await control.describeVolume(name);
-  if (described.volume.labels[LABEL_KEYS.managed] !== "true") {
-    throw new Error("refusing to remove an unmanaged volume");
-  }
-  if (described.mounted) throw new Error("refusing to remove a mounted volume");
-
-  const metadata = volumeLine(described.volume, described);
-  if (!yes) {
-    if (!ctx.hasUI || typeof ctx.ui.confirm !== "function") {
-      throw new Error("volume removal requires --yes when no UI is available");
-    }
-    const approved = await confirm(
-      ctx,
-      "Remove retained volume?",
-      `This permanently removes the managed volume.\n${metadata}`,
-    );
-    if (!approved) {
-      notify(ctx, "Volume removal cancelled", "warning");
-      return;
-    }
-  }
-  await control.removeVolume(name);
-  notify(ctx, `Removed volume ${name}.`);
-}
-
-function parseExportArgs(args: string[]): { paths: string[]; destination?: string; yes: boolean } {
-  const paths: string[] = [];
-  let destination: string | undefined;
-  let yes = false;
-  for (let index = 0; index < args.length; index++) {
-    const arg = args[index];
-    if (arg === "--yes") {
-      if (yes) throw new Error("duplicate --yes");
-      yes = true;
-    } else if (arg === "--to") {
-      if (destination !== undefined || index + 1 >= args.length) {
-        throw new Error("usage: /msb export <paths...> [--to dir]");
-      }
-      destination = args[++index];
-    } else if (arg.startsWith("--")) {
-      throw new Error(`unknown export option ${arg}`);
-    } else {
-      paths.push(arg);
-    }
-  }
-  if (!paths.length) throw new Error("usage: /msb export <paths...> [--to dir]");
-  return { paths, destination, yes };
-}
-
-async function handleExport(
-  args: string[],
-  ctx: CommandContext,
-  control: MsbControl,
-): Promise<void> {
-  const { paths, destination, yes } = parseExportArgs(args);
-  await ctx.waitForIdle();
-  if (!yes && (!ctx.hasUI || typeof ctx.ui.confirm !== "function")) {
-    throw new Error("export requires --yes when no UI is available");
-  }
-  if (!yes && ctx.hasUI && typeof ctx.ui.confirm === "function") {
-    const where = destination ? ` to ${destination}` : " to the dedicated export directory";
-    const approved = await confirm(
-      ctx,
-      "Export sandbox files?",
-      `Export ${paths.length} path${paths.length === 1 ? "" : "s"}${where}. Existing destinations are never overwritten without confirmation.`,
-    );
-    if (!approved) {
-      notify(ctx, "Export cancelled", "warning");
-      return;
-    }
-  }
-  const results = await control.exportPaths(paths, destination);
-  if (!results.length) {
-    notify(ctx, "No paths were exported.", "warning");
-    return;
-  }
-  notify(ctx, results.map((result) => `${result.source} -> ${result.destination}`).join("\n"));
+  return `Prune complete\nInspected: ${report.inspected}\nRemoved: ${removed}\nKept: ${kept}\nErrors: ${errors}`;
 }
 
 async function handleNetwork(args: string[], control: MsbControl): Promise<string> {
@@ -448,16 +291,9 @@ async function executeCommand(
     case "reload": {
       if (tokens.length) throw new Error(`usage: /msb ${command}`);
       await ctx.waitForIdle();
-      const before = control.getState();
       if (command === "reload") await control.reload();
       else await control.setEnabled(command === "on");
-      const after = control.getState();
-      const reused =
-        before.info?.volumeName &&
-        after.info?.volumeName === before.info.volumeName
-          ? `\nVolume reused: ${after.info.volumeName}`
-          : "";
-      notify(ctx, `${fullState(after)}${reused}`);
+      notify(ctx, fullState(control.getState()));
       return;
     }
     case "prune": {
@@ -466,19 +302,6 @@ async function executeCommand(
       notify(ctx, pruneSummary(await control.pruneNow()));
       return;
     }
-    case "volumes":
-      if (tokens[0] === "ls" && tokens.length === 1) {
-        notify(ctx, await listVolumes(control));
-        return;
-      }
-      if (tokens[0] === "rm") {
-        await handleVolumeRemove(tokens.slice(1), ctx, control);
-        return;
-      }
-      throw new Error("usage: /msb volumes ls | /msb volumes rm <name> [--yes]");
-    case "export":
-      await handleExport(tokens, ctx, control);
-      return;
     case "logs":
       notify(ctx, await control.getLogs(parseTail(tokens)));
       return;
@@ -531,7 +354,7 @@ export function createCommandHandler(control: MsbControl): CommandHandler {
 
 export function registerMsbCommand(pi: ExtensionAPI, control: MsbControl): void {
   pi.registerCommand("msb", {
-    description: "Manage pi-microsandbox and retained volumes",
+    description: "Manage pi-microsandbox",
     handler: createCommandHandler(control),
   });
 }

package/extensions/pi-msb/config.ts

@@ -19,6 +19,8 @@ const CONTROL_KEYS = new Set(["removeSecrets", "removeMounts", "removeRouteTools
 const SECRET_FIELDS = new Set(["env", "value", "allowHosts"]);
 const MOUNT_FIELDS = new Set(["type", "hostPath", "guestPath", "readonly", "options"]);
 const FORBIDDEN_CONFIG_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const REMOVED_WORKSPACE_KEYS = new Set(["mode", "cloneBranch", "cloneDepth", "shallowArchive", "volumeQuotaMiB"]);
+const REMOVED_WORKSPACE_MESSAGE = "was removed; pi-microsandbox now bind-mounts the discovered workspace root read/write";
 const PROTECTED_GUEST_ENV = new Set([
   "BASH_ENV",
   "CDPATH",
@@ -72,11 +74,6 @@ export const DEFAULT_CONFIG = deepFreeze<Config>({
   replace: false,
   replaceTimeoutMs: 10_000,
   sandboxName: null,
-  mode: "direct",
-  cloneBranch: "current",
-  cloneDepth: "unlimited",
-  shallowArchive: false,
-  volumeQuotaMiB: 2_048,
   network: { mode: "default", allowHosts: [], allowDns: true, publishPorts: [] },
   docker: { mode: "auto", startupTimeoutMs: 15_000 },
   secrets: [],
@@ -178,6 +175,16 @@ function camel(key: string): string {
 function snake(key: string): string {
   return key.replace(/MiB/g, "mib").replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
+function removedWorkspaceIssues(value: Record<string, unknown>): string[] {
+  return Object.keys(value)
+    .map(camel)
+    .filter((key) => REMOVED_WORKSPACE_KEYS.has(key))
+    .map((key) => `${snake(key)} ${REMOVED_WORKSPACE_MESSAGE}`);
+}
+function assertNoRemovedWorkspaceKeys(value: Record<string, unknown>): void {
+  const issues = removedWorkspaceIssues(value);
+  if (issues.length) throw new ConfigError(issues);
+}
 function pathKey(parts: string[]): string { return parts.join("."); }
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -229,6 +236,64 @@ function findEquals(text: string): number {
   }
   return -1;
 }
+function decodeBasicTomlKey(text: string): string {
+  let result = "";
+  for (let index = 1; index < text.length - 1; index++) {
+    const character = text[index]!;
+    if (character !== "\\") {
+      result += character;
+      continue;
+    }
+    const escape = text[++index];
+    if (escape === undefined) throw new Error("invalid quoted TOML key");
+    const simple: Record<string, string> = { b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", "\"": "\"", "\\": "\\" };
+    if (Object.hasOwn(simple, escape)) {
+      result += simple[escape];
+      continue;
+    }
+    if (escape !== "u" && escape !== "U") throw new Error("invalid quoted TOML key");
+    const length = escape === "u" ? 4 : 8;
+    const hex = text.slice(index + 1, index + 1 + length);
+    if (!new RegExp(`^[0-9a-fA-F]{${length}}$`).test(hex)) throw new Error("invalid quoted TOML key");
+    const codePoint = Number.parseInt(hex, 16);
+    if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) throw new Error("invalid quoted TOML key");
+    result += String.fromCodePoint(codePoint);
+    index += length;
+  }
+  return result;
+}
+function parseTomlKeySegment(text: string): string {
+  const key = text.trim();
+  if (key.startsWith("\"") && key.endsWith("\"")) return decodeBasicTomlKey(key);
+  if (key.startsWith("'") && key.endsWith("'") && !key.slice(1, -1).includes("'")) return key.slice(1, -1);
+  if (/^[A-Za-z0-9_-]+$/.test(key)) return key;
+  throw new Error("invalid TOML key");
+}
+function parseTomlKey(text: string): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  let quote = "";
+  for (let index = 0; index < text.length; index++) {
+    const character = text[index]!;
+    if (quote === "\"") {
+      if (character === "\\") index++;
+      else if (character === quote) quote = "";
+      continue;
+    }
+    if (quote === "'") {
+      if (character === quote) quote = "";
+      continue;
+    }
+    if (character === "\"" || character === "'") quote = character;
+    else if (character === ".") {
+      parts.push(parseTomlKeySegment(text.slice(start, index)));
+      start = index + 1;
+    }
+  }
+  if (quote) throw new Error("invalid TOML key");
+  parts.push(parseTomlKeySegment(text.slice(start)));
+  return parts;
+}
 function parseTomlValue(text: string): unknown {
   const value = text.trim();
   if (value.startsWith("[") && value.endsWith("]")) return splitTopLevel(value.slice(1, -1)).map(parseTomlValue);
@@ -237,9 +302,8 @@ function parseTomlValue(text: string): unknown {
     for (const part of splitTopLevel(value.slice(1, -1))) {
       const at = findEquals(part);
       if (at < 0) throw new Error("invalid inline table");
-      const key = part.slice(0, at).trim();
-      assertSafeConfigKey(key, [key]);
-      object[key] = parseTomlValue(part.slice(at + 1));
+      const keys = parseTomlKey(part.slice(0, at));
+      assign(object, keys, parseTomlValue(part.slice(at + 1)));
     }
     return object;
   }
@@ -270,7 +334,7 @@ function readToml(text: string): Record<string, unknown> {
     const line = stripTomlComment(raw);
     if (!line) continue;
     if (line.startsWith("[[") && line.endsWith("]]")) {
-      const keys = line.slice(2, -2).trim().split(".").map((x) => x.trim());
+      const keys = parseTomlKey(line.slice(2, -2).trim());
       assertSafeConfigPath(keys);
       let parent: Record<string, unknown> = root;
       for (const key of keys.slice(0, -1)) {
@@ -288,14 +352,14 @@ function readToml(text: string): Record<string, unknown> {
       continue;
     }
     if (line.startsWith("[") && line.endsWith("]")) {
-      section = line.slice(1, -1).trim().split(".").map((x) => x.trim());
+      section = parseTomlKey(line.slice(1, -1).trim());
       assertSafeConfigPath(section);
       arraySection = null;
       continue;
     }
     const at = findEquals(line);
     if (at < 0) throw new Error("invalid assignment");
-    const key = line.slice(0, at).trim();
+    const keys = parseTomlKey(line.slice(0, at));
     const value = parseTomlValue(line.slice(at + 1));
     if (arraySection) {
       let parent: Record<string, unknown> = root;
@@ -304,9 +368,8 @@ function readToml(text: string): Record<string, unknown> {
         if (!Array.isArray(list) || !isPlainObject(list[list.length - 1])) throw new Error("invalid array table");
         parent = list[list.length - 1] as Record<string, unknown>;
       }
-      assertSafeConfigKey(key, [...arraySection, key]);
-      parent[key] = value;
-    } else assign(root, [...section, ...key.split(".").map((x) => x.trim())], value);
+      assign(parent, keys, value);
+    } else assign(root, [...section, ...keys], value);
   }
   return root;
 }
@@ -335,7 +398,7 @@ function knownPath(path: string): boolean {
   if (parts[0] === "docker") return parts.length === 1 || (parts.length === 2 && ["mode", "startupTimeoutMs"].includes(parts[1]));
   if (parts[0] === "secrets") return parts.length === 1 || (parts.length === 2 && SECRET_FIELDS.has(parts[1]));
   if (parts[0] === "mounts") return parts.length === 1 || (parts.length === 2 && MOUNT_FIELDS.has(parts[1]));
-  return ["image", "pullPolicy", "bootstrapTools", "cpus", "memoryMiB", "idleTimeoutSec", "stopTimeoutMs", "detached", "replace", "replaceTimeoutMs", "sandboxName", "mode", "cloneBranch", "cloneDepth", "shallowArchive", "volumeQuotaMiB", "blockThirdParty", "routeTools", "passThroughTools", "allowHostExecution", "allowSkillReads", "fallbackMode", "exposeSessionEnvironment", "hostEnv", "autoStart", "pruneOnStart", "showFooter", "lockDir", "hostRoAllowlist"].includes(parts[0]);
+  return ["image", "pullPolicy", "bootstrapTools", "cpus", "memoryMiB", "idleTimeoutSec", "stopTimeoutMs", "detached", "replace", "replaceTimeoutMs", "sandboxName", "blockThirdParty", "routeTools", "passThroughTools", "allowHostExecution", "allowSkillReads", "fallbackMode", "exposeSessionEnvironment", "hostEnv", "autoStart", "pruneOnStart", "showFooter", "lockDir", "hostRoAllowlist"].includes(parts[0]);
 }
 function collectUnknown(value: unknown, base: string[], warnings: string[]): void {
   if (!isPlainObject(value)) return;
@@ -368,7 +431,9 @@ function withMountDefaults(value: LayerValue): LayerValue {
 }
 function normalizeLayer(name: ConfigLayerName, raw: Record<string, unknown>, source?: string): ParsedConfigLayer {
   assertSafeConfigValue(raw);
-  const value = withMountDefaults(normalizeValue(raw) as LayerValue);
+  const normalized = normalizeValue(raw) as Record<string, unknown>;
+  assertNoRemovedWorkspaceKeys(normalized);
+  const value = withMountDefaults(normalized as LayerValue);
   const warnings: string[] = [];
   collectUnknown(value, [], warnings);
   if (name === "project" && Array.isArray(value.secrets)) {
@@ -383,7 +448,10 @@ function normalizeLayer(name: ConfigLayerName, raw: Record<string, unknown>, sou
 
 export function parseTomlConfig(text: string, source: string): ParsedConfigLayer {
   try { return normalizeLayer(source === "cli" ? "cli" : source === "env" ? "env" : source === "project" ? "project" : "global", readToml(text), source); }
-  catch { throw new ConfigError([`invalid TOML in ${source}`]); }
+  catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError([`invalid TOML in ${source}`]);
+  }
 }
 
 function envScalar(text: string, key: string): unknown {
@@ -488,6 +556,7 @@ export function mergeConfigLayers(layers: readonly ConfigLayerInput[]): MergeRes
   const warnings: string[] = [];
   for (const layer of layers) {
     assertSafeConfigValue(layer.value);
+    assertNoRemovedWorkspaceKeys(layer.value as Record<string, unknown>);
     warnings.push(...layer.warnings.map(warning));
     const source = withMountDefaults(clone(layer.value) as LayerValue);
     applyRemovals(result, source, layer.name, provenance);
@@ -517,6 +586,7 @@ function validatePort(port: unknown): boolean {
 }
 
 export function validateConfig(raw: DeepPartial<Config>): Config {
+  assertNoRemovedWorkspaceKeys(raw as Record<string, unknown>);
   const config = mergeWithDefaults(raw);
   const issues: string[] = [];
   const n = (value: unknown) => typeof value === "number" && Number.isFinite(value);
@@ -527,18 +597,14 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   if (!n(config.idleTimeoutSec) || config.idleTimeoutSec < 0) issues.push(issueForPath("idleTimeoutSec", "must be non-negative"));
   if (!n(config.stopTimeoutMs) || config.stopTimeoutMs < 1) issues.push(issueForPath("stopTimeoutMs", "must be positive"));
   if (!n(config.replaceTimeoutMs) || config.replaceTimeoutMs < 1) issues.push(issueForPath("replaceTimeoutMs", "must be positive"));
-  if (!n(config.volumeQuotaMiB) || config.volumeQuotaMiB < 1) issues.push(issueForPath("volumeQuotaMiB", "must be positive"));
-  if (!["auto", "git", "direct", "none"].includes(config.mode)) issues.push(issueForPath("mode", "unknown storage mode"));
   const docker = isPlainObject(config.docker) ? config.docker : null;
   if (!docker || !["auto", "require", "disabled"].includes(docker.mode as string)) issues.push(issueForPath("docker.mode", "must be auto, require, or disabled"));
   if (!docker || !n(docker.startupTimeoutMs) || !Number.isInteger(docker.startupTimeoutMs) || (docker.startupTimeoutMs as number) < 1 || (docker.startupTimeoutMs as number) > 300_000) issues.push(issueForPath("docker.startupTimeoutMs", "must be an integer between 1 and 300000"));
   if (!["auto", true, false].includes(config.bootstrapTools)) issues.push(issueForPath("bootstrapTools", "must be auto, true, or false"));
   if (!["block", "host"].includes(config.fallbackMode)) issues.push(issueForPath("fallbackMode", "must be block or host"));
-  const booleanFields = ["detached", "replace", "shallowArchive", "blockThirdParty", "allowHostExecution", "allowSkillReads", "exposeSessionEnvironment", "autoStart", "pruneOnStart", "showFooter"] as const;
+  const booleanFields = ["detached", "replace", "blockThirdParty", "allowHostExecution", "allowSkillReads", "exposeSessionEnvironment", "autoStart", "pruneOnStart", "showFooter"] as const;
   for (const field of booleanFields) if (typeof config[field] !== "boolean") issues.push(issueForPath(field, "must be boolean"));
   if (config.sandboxName !== null && typeof config.sandboxName !== "string") issues.push(issueForPath("sandboxName", "must be a string or null"));
-  if (typeof config.cloneBranch !== "string" || !config.cloneBranch) issues.push(issueForPath("cloneBranch", "must be a non-empty string"));
-  if (config.cloneDepth !== "unlimited" && (!n(config.cloneDepth) || !Number.isInteger(config.cloneDepth) || config.cloneDepth < 1)) issues.push(issueForPath("cloneDepth", "must be a positive integer or unlimited"));
   const stringArray = (field: string, value: unknown) => {
     if (!Array.isArray(value)) { issues.push(issueForPath(field, "must be an array")); return false; }
     for (const item of value) if (typeof item !== "string" || !item) issues.push(issueForPath(field, "must contain non-empty strings"));
@@ -619,7 +685,10 @@ function configDir(env: NodeJS.ProcessEnv, input: ResolveConfigInput): string {
 }
 function layerFromText(name: ConfigLayerName, text: string, source: string): ParsedConfigLayer {
   try { return normalizeLayer(name, readToml(text), source); }
-  catch { throw new ConfigError([`invalid TOML in ${source}`]); }
+  catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError([`invalid TOML in ${source}`]);
+  }
 }
 
 export async function resolveConfig(input: ResolveConfigInput): Promise<ResolvedConfig> {
@@ -643,23 +712,35 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
     }
   };
   const project = await projectFile(input.cwd, input.repoRoot, input.configDirName, exists);
-  if (project && !input.projectTrusted) warnings.push("project config ignored because this project is not trusted");
-  if (project && input.projectTrusted) {
-    const text = await readFile(project);
-    if (text !== null) {
-      const parsed = layerFromText("project", text, project);
-      const projectValue = withMountDefaults(clone(parsed.value) as LayerValue);
-      if (Array.isArray(projectValue.mounts)) {
-        projectValue.mounts = await Promise.all(projectValue.mounts.map(async (mount: any) => {
-          if (mount && (mount.type === "dir" || mount.type === "file") && typeof mount.hostPath === "string" && isAbsolute(mount.hostPath)) {
-            return { ...mount, hostPath: await canonicalPath(mount.hostPath, true) };
-          }
-          return mount;
-        })) as any;
+  const projectText = project ? await readFile(project) : null;
+  if (project && !input.projectTrusted) {
+    warnings.push("project config ignored because this project is not trusted");
+    if (projectText !== null) {
+      // Ignored project configuration cannot influence policy, but a removed
+      // workspace selector must still stop startup before direct host writes.
+      try {
+        const normalized = normalizeValue(readToml(projectText)) as Record<string, unknown>;
+        assertNoRemovedWorkspaceKeys(normalized);
+      } catch (error) {
+        if (error instanceof ConfigError && error.issues.some((issue) => issue.includes(REMOVED_WORKSPACE_MESSAGE))) throw error;
+        // Preserve the existing trust rule for every other malformed/unsafe key:
+        // untrusted project configuration is not interpreted.
       }
-      layers.push({ ...parsed, value: projectValue });
     }
   }
+  if (project && input.projectTrusted && projectText !== null) {
+    const parsed = layerFromText("project", projectText, project);
+    const projectValue = withMountDefaults(clone(parsed.value) as LayerValue);
+    if (Array.isArray(projectValue.mounts)) {
+      projectValue.mounts = await Promise.all(projectValue.mounts.map(async (mount: any) => {
+        if (mount && (mount.type === "dir" || mount.type === "file") && typeof mount.hostPath === "string" && isAbsolute(mount.hostPath)) {
+          return { ...mount, hostPath: await canonicalPath(mount.hostPath, true) };
+        }
+        return mount;
+      })) as any;
+    }
+    layers.push({ ...parsed, value: projectValue });
+  }
   layers.push(parseEnvConfig(env));
   if (input.cliOverridesToml !== undefined) layers.push(parseTomlConfig(input.cliOverridesToml, "cli"));
   const merged = mergeConfigLayers(layers);
@@ -767,7 +848,11 @@ function setAt(base: any, parts: string[], value: unknown): any {
 export function applyOverride(base: DeepPartial<Config>, dottedSnakeKey: string, value: unknown): DeepPartial<Config> {
   const rawParts = dottedSnakeKey.split(".").filter(Boolean);
   assertSafeConfigPath(rawParts);
-  return setAt(base, rawParts.map(camel), value) as DeepPartial<Config>;
+  const parts = rawParts.map(camel);
+  if (REMOVED_WORKSPACE_KEYS.has(parts[0] ?? "")) {
+    throw new ConfigError([`${dottedSnakeKey} ${REMOVED_WORKSPACE_MESSAGE}`]);
+  }
+  return setAt(base, parts, value) as DeepPartial<Config>;
 }
 export function removeOverride(base: DeepPartial<Config>, dottedSnakeKey: string): DeepPartial<Config> {
   assertSafeConfigValue(base);
@@ -776,6 +861,9 @@ export function removeOverride(base: DeepPartial<Config>, dottedSnakeKey: string
   assertSafeConfigPath(rawParts);
   const parts = rawParts.map(camel);
   assertSafeConfigPath(parts);
+  if (REMOVED_WORKSPACE_KEYS.has(parts[0] ?? "")) {
+    throw new ConfigError([`${dottedSnakeKey} ${REMOVED_WORKSPACE_MESSAGE}`]);
+  }
   let current = out;
   for (const part of parts.slice(0, -1)) { if (!isPlainObject(current[part])) return out; current = current[part]; }
   delete current[parts[parts.length - 1]];