jeo-code 0.12.13 → 0.12.15

package/src/messenger/session-pool.ts

@@ -6,6 +6,8 @@ interface WorkerProcess {
 	stderr: ReadableStream<Uint8Array>;
 	exited: Promise<number>;
 	kill(signal?: number | NodeJS.Signals): void;
+	/** Private IPC channel; present only on workers spawned with `ipc`. */
+	send?(message: unknown): unknown;
 }
 
 interface Pending {
@@ -18,35 +20,80 @@ interface Pending {
 
 interface Worker {
 	child: WorkerProcess;
+	exit: Promise<number>;
+	policyKey?: string;
 	pending?: Pending;
 	lastUsed: number;
 	dead: boolean;
+	forceSent?: boolean;
 	exited?: boolean;
+	cleanupNonce?: string;
+	cleanupGone?: boolean;
+	cleanupError?: Error;
 	idleTimer?: ReturnType<typeof setTimeout>;
 	exitTimer?: ReturnType<typeof setTimeout>;
 }
 
-export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn, limit = 16, idleTimeoutMs = 5 * 60_000, shutdownTimeoutMs = 5_000) {
+/** Resident sessions the pool keeps, and the number of turns it runs at once. */
+export const MESSENGER_SESSION_LIMIT = 16;
+
+export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn, limit = MESSENGER_SESSION_LIMIT, idleTimeoutMs = 5 * 60_000, shutdownTimeoutMs = 5_000, options: { requireSandboxCleanup?: boolean } = {}) {
 	const workers = new Map<string, Worker>();
 	const allWorkers = new Map<Worker, string>();
-	const exits = new Map<Promise<number>, WorkerProcess>();
+	const exits = new Map<Promise<number>, Worker>();
 	const retiring = new Map<string, Promise<number>>();
+	const keyTails = new Map<string, Promise<void>>();
+	const requireSandboxCleanup = options.requireSandboxCleanup === true;
+	const incomplete = (detail: string) => new Error(`REVOKE_INCOMPLETE: ${detail}`);
 
 	let closed = false;
 	const closedSignal = new AbortController();
 
 	let tick = 0;
 
+	// Admission: at most `limit` turns hold a worker at once. Later turns wait here in arrival order until a
+	// running turn settles, so a busy pool is backpressure on the waiting request, never a failure of it.
+	let admitted = 0;
+	const waiting: Array<() => void> = [];
+
+	function admit(signal: AbortSignal): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const grant = () => { cleanup(); resolve(); };
+			const abort = () => {
+				const index = waiting.indexOf(grant);
+				if (index >= 0) waiting.splice(index, 1);
+				cleanup();
+				reject(new Error("Messenger request aborted"));
+			};
+			const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			waiting.push(grant);
+		});
+	}
+
+	/** Hand the finished turn's slot straight to the oldest waiter, or free it. */
+	function release() {
+		const next = waiting.shift();
+		if (next) next(); else admitted--;
+	}
+
+	function forceKill(worker: Worker) {
+		if (worker.cleanupNonce) return;
+		if (worker.forceSent) return;
+		try { worker.child.kill("SIGKILL"); worker.forceSent = true; } catch { /* Retry on shutdown if termination failed. */ }
+	}
+
 	function retire(key: string, worker: Worker) {
 		if (worker.dead) return;
 		worker.dead = true;
 		if (workers.get(key) === worker) workers.delete(key);
-		allWorkers.delete(worker);
-		if (!worker.exited) {
-			retiring.set(key, worker.child.exited);
-			void worker.child.exited.then(
-				() => { if (retiring.get(key) === worker.child.exited) retiring.delete(key); },
-				() => { if (retiring.get(key) === worker.child.exited) retiring.delete(key); },
+		if (!worker.cleanupNonce) allWorkers.delete(worker);
+		if (!worker.exited || worker.cleanupNonce) {
+			retiring.set(key, worker.exit);
+			void worker.exit.then(
+				() => { if (retiring.get(key) === worker.exit) retiring.delete(key); },
+				() => { /* Keep the key blocked when process exit cannot be confirmed. */ },
 			);
 		}
 		if (worker.idleTimer) clearTimeout(worker.idleTimer);
@@ -55,7 +102,29 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		worker.pending?.reject(new Error("Messenger worker stopped"));
 		worker.pending = undefined;
 		if (!worker.exited) {
-			try { worker.child.kill(); } catch { /* Shutdown will attempt forced termination. */ }
+			if (worker.cleanupNonce) {
+				// Protected workers never receive a kill signal: Windows cannot deliver a catchable SIGTERM.
+				// Shutdown is a private IPC message; a missing or failing channel is visible, never success.
+				const channel = worker.child.send;
+				if (typeof channel !== "function") {
+					worker.cleanupError = incomplete("worker shutdown channel unavailable");
+				} else {
+					try {
+						const sent = channel.call(worker.child, { type: "jeo_messenger_shutdown", nonce: worker.cleanupNonce });
+						if (sent && typeof (sent as PromiseLike<unknown>).then === "function") {
+							void (sent as PromiseLike<unknown>).then(undefined, error => { worker.cleanupError = incomplete(`worker shutdown request failed: ${String(error)}`); });
+						}
+					} catch (error) { worker.cleanupError = incomplete(`worker shutdown request failed: ${String(error)}`); }
+				}
+			} else {
+				try { worker.child.kill(); }
+				catch (error) { worker.cleanupError = incomplete(`worker termination failed: ${String(error)}`); }
+			}
+			if (!worker.cleanupNonce) {
+				const force = setTimeout(() => forceKill(worker), shutdownTimeoutMs);
+				force.unref();
+				void worker.exit.then(() => clearTimeout(force), () => clearTimeout(force));
+			}
 		}
 	}
 
@@ -89,16 +158,45 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		} finally { reader.releaseLock(); }
 	}
 
-	function start(key: string, command: string[], cwd: string, env: Record<string, string>): Worker {
-		if (workers.size >= limit) {
+	function waitForExit(exit: Promise<number>, signal: AbortSignal, capacity = false): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
+			const unavailable = () => new Error("Messenger worker capacity unavailable while another session is being cleaned up");
+			const timer = setTimeout(() => { cleanup(); reject(capacity ? unavailable() : requireSandboxCleanup ? incomplete("previous worker cleanup is still pending") : new Error("Messenger worker did not exit")); }, shutdownTimeoutMs * 2);
+			const cleanup = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted || closed) { abort(); return; }
+			void exit.then(() => { cleanup(); resolve(); }, error => { cleanup(); reject(capacity ? unavailable() : requireSandboxCleanup ? incomplete(`previous worker cleanup failed: ${String(error)}`) : new Error("Messenger worker exit could not be confirmed")); });
+		});
+	}
+
+	async function start(key: string, command: string[], cwd: string, env: Record<string, string>, signal: AbortSignal, policyKey?: string): Promise<Worker> {
+		while ((requireSandboxCleanup ? allWorkers.size : workers.size) >= limit) {
 			const idle = [...workers.entries()].filter(([, worker]) => !worker.pending).sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
-			if (!idle) throw new Error("Messenger worker capacity reached");
+			if (!idle) {
+				const retiringWorker = requireSandboxCleanup ? [...allWorkers.keys()].find(worker => worker.dead) : undefined;
+				if (!retiringWorker) throw new Error("Messenger worker capacity reached");
+				await waitForExit(retiringWorker.exit, signal, true);
+				continue;
+			}
 			retire(idle[0], idle[1]);
+			if (requireSandboxCleanup) await waitForExit(idle[1].exit, signal, true);
 		}
-		const child = spawn(command, { cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe" }) as unknown as WorkerProcess;
-		const worker: Worker = { child, lastUsed: ++tick, dead: false };
-		exits.set(child.exited, child);
-		void child.exited.then(() => exits.delete(child.exited), () => exits.delete(child.exited));
+		if (closed || signal.aborted) throw new Error("Messenger request aborted");
+		const cleanupNonce = requireSandboxCleanup ? crypto.randomUUID() : undefined;
+		const workerEnv = { ...env };
+		delete workerEnv.JEO_MESSENGER_SHUTDOWN_NONCE;
+		if (cleanupNonce) workerEnv.JEO_MESSENGER_SHUTDOWN_NONCE = cleanupNonce;
+		const spawnOptions = { cwd, env: workerEnv, stdin: "pipe", stdout: "pipe", stderr: "pipe", ...(cleanupNonce ? { ipc() {}, serialization: "json" } : {}) };
+		const child = spawn(command, spawnOptions as never) as unknown as WorkerProcess;
+		const cleanup = Promise.withResolvers<number>();
+		const worker: Worker = { child, exit: cleanupNonce ? cleanup.promise : child.exited, cleanupNonce, policyKey, lastUsed: ++tick, dead: false };
+		exits.set(worker.exit, worker);
+		void worker.exit.then(() => {
+			exits.delete(worker.exit);
+			if (cleanupNonce) allWorkers.delete(worker);
+		}, () => { if (!cleanupNonce) exits.delete(worker.exit); });
 		workers.set(key, worker);
 		allWorkers.set(worker, key);
 		const stdoutDone = readLines(child.stdout, line => {
@@ -113,7 +211,17 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 				finishTurn(key, worker, pending);
 			} catch { retire(key, worker); }
 		}).catch(() => retire(key, worker));
-		void readLines(child.stderr, line => {
+		const stderrDone = readLines(child.stderr, line => {
+			if (cleanupNonce && line.startsWith("JEO_MESSENGER_SHUTDOWN_ACK ")) {
+				try {
+					const ack: unknown = JSON.parse(line.slice("JEO_MESSENGER_SHUTDOWN_ACK ".length));
+					if (typeof ack === "object" && ack !== null && "nonce" in ack && ack.nonce === cleanupNonce && "gone" in ack) {
+						worker.cleanupGone = ack.gone === true;
+						worker.cleanupError = worker.cleanupGone ? undefined : incomplete("worker supervisor cleanup failed");
+					}
+				} catch { /* Unauthenticated or malformed output is never cleanup proof. */ }
+				return;
+			}
 			if (line.startsWith("JEO_MESSENGER_ACTIVITY ")) {
 				const activityText = line.slice("JEO_MESSENGER_ACTIVITY ".length).trim();
 				if (activityText) worker.pending?.report?.(activityText);
@@ -121,9 +229,15 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 				worker.pending?.report?.("Working on your request");
 			}
 		}).catch(() => retire(key, worker));
-		void child.exited.then(() => {
-			if (worker.dead) return;
+		if (cleanupNonce) {
+			void Promise.all([child.exited, stderrDone, stdoutDone]).then(([code]) => {
+				if (worker.cleanupGone) cleanup.resolve(code);
+				else cleanup.reject(worker.cleanupError ?? incomplete("worker exited without supervisor cleanup acknowledgement"));
+			}, error => cleanup.reject(incomplete(`worker exit could not be verified: ${String(error)}`)));
+		}
+		void worker.exit.then(() => {
 			worker.exited = true;
+			if (worker.dead) return;
 			if (workers.get(key) === worker) workers.delete(key);
 			worker.exitTimer = setTimeout(() => retire(key, worker), shutdownTimeoutMs);
 			worker.exitTimer.unref();
@@ -134,24 +248,61 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 		return worker;
 	}
 
-	async function turn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter): Promise<string> {
+	function turn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter, policyKey?: string): Promise<string> {
+		if (closed || signal.aborted) return Promise.reject(new Error("Messenger request aborted"));
+		const run = () => runTurn(key, command, cwd, env, text, signal, report, policyKey).finally(release);
+		const admitRun = () => {
+			if (closed || signal.aborted) return Promise.reject(new Error("Messenger request aborted"));
+			if (admitted < limit && waiting.length === 0) {
+				admitted++;
+				return run();
+			}
+			return admit(signal).then(run);
+		};
+		// Same-key turns run strictly in arrival order. Queued turns hold no admission slot while they wait,
+		// so they never block other sessions; different keys are fully independent.
+		const previous = keyTails.get(key);
+		const result = previous ? waitForTurn(previous, signal).then(admitRun) : admitRun();
+		const settled = result.then(() => undefined, () => undefined);
+		// The tail also covers the predecessor, so an aborted queued turn never lets its successor overtake it.
+		const tail: Promise<void> = previous ? Promise.all([previous, settled]).then(() => undefined) : settled;
+		keyTails.set(key, tail);
+		void tail.then(() => { if (keyTails.get(key) === tail) keyTails.delete(key); });
+		return result;
+	}
+
+	function waitForTurn(previous: Promise<void>, signal: AbortSignal): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
+			const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
+			signal.addEventListener("abort", abort, { once: true });
+			closedSignal.signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted || closed) { abort(); return; }
+			void previous.then(() => { cleanup(); resolve(); });
+		});
+	}
+
+	async function runTurn(key: string, command: string[], cwd: string, env: Record<string, string>, text: string, signal: AbortSignal, report?: MessengerActivityReporter, policyKey?: string): Promise<string> {
 		if (closed || signal.aborted) throw new Error("Messenger request aborted");
-		const previousExit = retiring.get(key);
-		if (previousExit) {
-			await new Promise<void>((resolve, reject) => {
-				const abort = () => { cleanup(); reject(new Error("Messenger request aborted")); };
-				const cleanup = () => { signal.removeEventListener("abort", abort); closedSignal.signal.removeEventListener("abort", abort); };
-				signal.addEventListener("abort", abort, { once: true });
-				closedSignal.signal.addEventListener("abort", abort, { once: true });
-				if (signal.aborted || closed) { abort(); return; }
-				void previousExit.then(() => { cleanup(); resolve(); }, () => { cleanup(); resolve(); });
-			});
+		for (;;) {
+			const existing = workers.get(key);
+			if (existing && existing.policyKey !== policyKey) {
+				if (existing.pending) throw new Error("Messenger conversation is already active");
+				retire(key, existing);
+			}
+			const previousExit = retiring.get(key);
+			if (!previousExit) break;
+			await waitForExit(previousExit, signal);
 		}
 		if (closed || signal.aborted) throw new Error("Messenger request aborted");
 		if ([...allWorkers].some(([worker, workerKey]) => workerKey === key && worker.pending)) {
 			throw new Error("Messenger conversation is already active");
 		}
-		const worker = workers.get(key) ?? start(key, command, cwd, env);
+		const worker = workers.get(key) ?? await start(key, command, cwd, env, signal, policyKey);
+		if (closed || signal.aborted || worker.dead) {
+			retire(key, worker);
+			throw new Error("Messenger worker stopped");
+		}
 		if (worker.pending) throw new Error("Messenger conversation is already active");
 		if (worker.idleTimer) clearTimeout(worker.idleTimer);
 		worker.idleTimer = undefined;
@@ -179,15 +330,18 @@ export function createMessengerSessionPool(spawn: typeof Bun.spawn = Bun.spawn,
 			let timer: ReturnType<typeof setTimeout> | undefined;
 			try {
 				return await Promise.race([
-					Promise.allSettled([...exits.keys()]).then(() => true),
+					Promise.allSettled([...exits.keys()]).then(results => {
+						const failure = results.find(result => result.status === "rejected");
+						if (failure?.status === "rejected" && requireSandboxCleanup) throw incomplete(`worker cleanup failed: ${String(failure.reason)}`);
+						return true;
+					}),
 					new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), shutdownTimeoutMs); }),
 				]);
 			} finally { if (timer) clearTimeout(timer); }
 		};
 		if (await waitForExits()) return;
-		for (const child of exits.values()) {
-			try { child.kill("SIGKILL"); } catch { /* The process may have exited concurrently. */ }
-		}
+		if (requireSandboxCleanup) throw incomplete("worker cleanup is still pending; cleanup owner retained");
+		for (const worker of exits.values()) forceKill(worker);
 		if (!(await waitForExits())) throw new Error("Messenger workers did not exit after forced termination");
 	}
 

package/src/messenger/types.ts

@@ -1,3 +1,5 @@
+import type { SandboxConfig } from "../agent/sandbox/types";
+
 export type MessengerPlatform = "discord" | "telegram" | "slack";
 
 export interface MessengerMessage {
@@ -51,9 +53,8 @@ export interface MessengerConfig {
 	cwd: string;
 	sessionDir: string;
 	toolNames: string[];
+	sandbox?: SandboxConfig;
 	platforms: Partial<Record<MessengerPlatform, MessengerPlatformConfig>>;
-	/** Whether each message invocation runs in an isolated independent session. Defaults to true. */
-	independentSessions?: boolean;
 }
 
 export interface MessengerTransportDeps {

package/src/skills/catalog.ts

@@ -209,6 +209,17 @@ import * as path from "node:path";
 import * as os from "node:os";
 
 import { jeoEnv } from "../util/env";
+import { currentSandboxExecution } from "../agent/hooks";
+import type { SandboxSupervisor } from "../agent/sandbox/types";
+import { canonicalSandboxPath, nativeSandboxHome } from "../agent/sandbox/policy";
+
+async function sandboxSkillCatalog<T>(action: string, cwd: string, args: Record<string, unknown> = {}): Promise<T> {
+  const sandbox = currentSandboxExecution();
+  if (!sandbox) throw new Error("SANDBOX_SKILLS: missing execution scope");
+  const result = await sandbox.supervisor.call("__workflow", { operation: "skillCatalog", action, ...args }, { cwd, signal: sandbox.signal });
+  if (!result.success) throw new Error(result.error || "SANDBOX_SKILLS: operation failed");
+  return JSON.parse(result.output) as T;
+}
 
 const BUILTIN_SLASH_ALIASES = new Set([
   "/help", "/clear", "/compact", "/model", "/fast", "/provider", "/logout",
@@ -479,8 +490,204 @@ async function resolveSkillEntry(dir: string, entry: Dirent): Promise<SkillDoc |
  *  batches racing across the `skillDirs` loop below. */
 const SKILL_ENTRY_LOAD_BATCH = 32;
 
+interface CatalogPath { path: string; traversal: string[]; visited?: string[]; guestPath?: string }
+interface CatalogEntry { location: CatalogPath; skillName: string; doc?: SkillDoc }
+interface CatalogDirectory { location: CatalogPath; entries: CatalogEntry[] }
+interface SandboxSkillCatalog { cwd: string; roots: string[]; readableRoots: string[]; directories: CatalogDirectory[] }
+const sandboxSkillCatalogs = new WeakMap<SandboxSupervisor, SandboxSkillCatalog>();
+
+function withinCatalogRoot(file: string, root: string): boolean {
+  const relative = path.relative(root, file);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function guestCatalogPath(location: CatalogPath, roots: string[]): string | undefined {
+  if (location.guestPath) return location.guestPath;
+  const route = location.traversal.find(file => roots.some(root => withinCatalogRoot(file, root)));
+  if (!route && location.visited?.some(file => roots.some(root => withinCatalogRoot(file, root)))) {
+    throw new Error("SANDBOX_SKILLS: catalog traversal leaves a writable root; explicit guest access required");
+  }
+  return route;
+}
+
+/** Metadata only: stop BEFORE traversing a workspace-controlled symlink. Called
+ * only while constructing the pre-execution snapshot, never for live host reads. */
+async function traceCatalogPath(file: string, roots: string[], protectedRoots: string[]): Promise<CatalogPath> {
+  const absolute = path.resolve(file);
+  const parsed = path.parse(absolute);
+  let current = parsed.root;
+  let parts = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  const traversal = [absolute];
+  if (!protectedRoots.some(root => withinCatalogRoot(absolute, root))) return { path: absolute, traversal, guestPath: absolute };
+  const visited: string[] = [];
+  let links = 0;
+  while (parts.length > 0) {
+    const part = parts.shift()!;
+    if (part === ".") continue;
+    current = part === ".." ? path.dirname(current) : path.join(current, part);
+    visited.push(current);
+    const candidate = path.join(current, ...parts);
+    if (!protectedRoots.some(root => withinCatalogRoot(current, root) || withinCatalogRoot(root, current))) {
+      return { path: candidate, traversal, visited, guestPath: candidate };
+    }
+    if (roots.some(root => withinCatalogRoot(current, root))) {
+      traversal.push(candidate);
+      const location = { path: candidate, traversal, visited };
+      guestCatalogPath(location, roots); // Reject '..' escape, never normalize it into a trusted host read.
+      return location;
+    }
+    if (part !== ".." && (await fs.lstat(current)).isSymbolicLink()) {
+      if (++links > 40) throw new Error("Too many skill catalog symlinks");
+      const target = await fs.readlink(current);
+      const targetRoot = path.parse(target).root;
+      current = targetRoot || path.dirname(current);
+      // Retain '..' until its preceding components and symlinks have been visited.
+      parts = target.slice(targetRoot.length).split(path.sep).filter(Boolean).concat(parts);
+      traversal.push(path.join(current, ...parts));
+    }
+  }
+  return { path: current, traversal, visited };
+}
+
+/** Must run before the supervisor executes any model-controlled guest code.
+ * Parent skill bytes are frozen in memory, not reread after tools can mutate paths. */
+export async function prepareSandboxSkillCatalog(supervisor: SandboxSupervisor, cwd: string, writableRoots: readonly string[] = [], readableRoots: readonly string[] = writableRoots): Promise<void> {
+  if (currentSandboxExecution()) throw new Error("SANDBOX_SKILLS: snapshot requires trusted initialization");
+  if (sandboxSkillCatalogs.has(supervisor)) throw new Error("SANDBOX_SKILLS: catalog already initialized");
+  const roots = [...new Set([path.resolve(cwd), await fs.realpath(cwd), ...writableRoots.map(root => path.resolve(root))])];
+  // These roots (and their canonical aliases) are forbidden to EVERY sandbox
+  // profile, unlike runtime HOME/config directories or another session's grants.
+  const nativeHome = await nativeSandboxHome();
+  const nativeRoots = [".agents", ".claude", ".jeo", ".jeopi"].map(name => path.join(nativeHome, name));
+  const protectedRoots = [...new Set([...nativeRoots, ...await Promise.all(nativeRoots.map(root => canonicalSandboxPath(root, false)))])];
+  const authorizedRoots = [...new Set([path.resolve(cwd), await fs.realpath(cwd), ...readableRoots.map(root => path.resolve(root))])];
+  const directories: CatalogDirectory[] = [];
+  for (const dir of skillDirs(cwd)) {
+    let location: CatalogPath;
+    try { location = await traceCatalogPath(dir, roots, protectedRoots); }
+    catch {
+      directories.push({ location: { path: path.resolve(dir), traversal: [path.resolve(dir)] }, entries: [] });
+      continue;
+    }
+    const directory: CatalogDirectory = { location, entries: [] };
+    directories.push(directory);
+    if (guestCatalogPath(location, roots)) continue;
+    let entries: Dirent[];
+    try { entries = await fs.readdir(location.path, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      try {
+        let resolved = await traceCatalogPath(path.join(location.path, entry.name), roots, protectedRoots);
+        resolved.traversal.unshift(...location.traversal.map(root => path.join(root, entry.name)));
+        resolved.visited = [...(location.visited ?? []), ...(resolved.visited ?? [])];
+        let isDirectory = false;
+        if (!guestCatalogPath(resolved, roots)) {
+          const stat = await fs.stat(resolved.path);
+          if (stat.isDirectory()) {
+            isDirectory = true;
+            const skillFile = await traceCatalogPath(path.join(resolved.path, "SKILL.md"), roots, protectedRoots);
+            skillFile.traversal.unshift(...resolved.traversal.map(root => path.join(root, "SKILL.md")));
+            skillFile.visited = [...(resolved.visited ?? []), ...(skillFile.visited ?? [])];
+            resolved = skillFile;
+          } else if (!stat.isFile() || !entry.name.endsWith(".md")) continue;
+        }
+        const item: CatalogEntry = { location: resolved, skillName: entry.name.replace(/\.md$/, "") };
+        directory.entries.push(item);
+        if (guestCatalogPath(resolved, roots)) continue;
+        const doc = parseSkillMarkdown(entry.name.replace(/\.md$/, ""), await fs.readFile(resolved.path, "utf-8"), { preferMetaName: true });
+        doc.sourcePath = path.join(dir, entry.name, ...(isDirectory ? ["SKILL.md"] : []));
+        if (isSupportedExternalSkill(doc)) item.doc = doc;
+      } catch {
+        // Absent/unreadable global docs are not part of this session's snapshot.
+      }
+    }
+  }
+  sandboxSkillCatalogs.set(supervisor, { cwd: path.resolve(cwd), roots, readableRoots: authorizedRoots, directories });
+}
+
+/** Grant revisions may taint formerly trusted paths. Reclassify captured path
+ * provenance only; never refresh content from a now-running model's host paths. */
+export function updateSandboxSkillCatalogRoots(supervisor: SandboxSupervisor, writableRoots: readonly string[], readableRoots: readonly string[] = writableRoots): void {
+  const catalog = sandboxSkillCatalogs.get(supervisor);
+  if (!catalog) throw new Error("SANDBOX_SKILLS: catalog not initialized");
+  catalog.roots = [...new Set([...catalog.roots, ...writableRoots.map(root => path.resolve(root))])];
+  catalog.readableRoots = [...new Set([catalog.cwd, ...readableRoots.map(root => path.resolve(root))])];
+}
+
+async function loadSandboxSkills(cwd: string): Promise<SkillDoc[]> {
+  const sandbox = currentSandboxExecution();
+  if (!sandbox) throw new Error("SANDBOX_SKILLS: missing execution scope");
+  const catalog = sandboxSkillCatalogs.get(sandbox.supervisor);
+  if (!catalog) throw new Error("SANDBOX_SKILLS: trusted catalog not initialized");
+  const byName = new Map<string, SkillDoc>(SKILLS.map(skill => [skill.name.toLowerCase(), skill]));
+  for (const name of await sandboxSkillCatalog<string[]>("lock", cwd)) ALLOWED_SKILL_NAMES.add(name.toLowerCase());
+  // A subagent may use another approved cwd: reuse only trusted global bytes,
+  // and derive its project directories without touching host filesystem state.
+  const directories = path.resolve(cwd) === catalog.cwd
+    ? catalog.directories
+    : catalog.directories.map((directory, index) => index >= 5 && index < 10
+      ? { location: { path: skillDirs(cwd)[index]!, traversal: [skillDirs(cwd)[index]!] }, entries: [] }
+      : directory);
+  for (const directory of directories) {
+    const guestDir = guestCatalogPath(directory.location, catalog.roots)
+      ?? (path.resolve(cwd) !== catalog.cwd && withinCatalogRoot(directory.location.path, path.resolve(cwd)) ? directory.location.path : undefined);
+    if (guestDir) {
+      if (!catalog.readableRoots.some(root => withinCatalogRoot(guestDir, root))) continue;
+      for (const doc of await sandboxSkillCatalog<SkillDoc[]>("scan", guestDir)) byName.set(doc.name.toLowerCase(), doc);
+      continue;
+    }
+    for (const entry of directory.entries) {
+      const guestFile = guestCatalogPath(entry.location, catalog.roots);
+      if (guestFile && !catalog.readableRoots.some(root => withinCatalogRoot(guestFile, root))) continue;
+      const doc = guestFile
+        ? await sandboxSkillCatalog<SkillDoc | null>("entry", path.dirname(guestFile), { name: path.basename(guestFile), skillName: entry.skillName })
+        : entry.doc;
+      if (doc) byName.set(doc.name.toLowerCase(), { ...doc });
+    }
+  }
+  return [...byName.values()];
+}
+
+async function scanSkillDirectory(dir: string): Promise<SkillDoc[]> {
+  let entries: Dirent[];
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return []; }
+  const skills: SkillDoc[] = [];
+  for (let i = 0; i < entries.length; i += SKILL_ENTRY_LOAD_BATCH) {
+    const resolved = await Promise.all(entries.slice(i, i + SKILL_ENTRY_LOAD_BATCH).map(entry => resolveSkillEntry(dir, entry)));
+    for (const skill of resolved) if (skill) skills.push(skill);
+  }
+  return skills;
+}
+
+/** Only workspace catalog effects execute in hands; trusted global docs stay in brain. */
+export async function executeSkillCatalogOperation(args: Record<string, unknown>, cwd: string): Promise<unknown> {
+  if (currentSandboxExecution()) throw new Error("SANDBOX_SKILLS: guest handler cannot run in the brain");
+  if (args.action === "lock") {
+    try {
+      const lockData: unknown = JSON.parse(await fs.readFile(path.join(cwd, "skills-lock.json"), "utf-8"));
+      if (lockData && typeof lockData === "object" && "skills" in lockData && lockData.skills && typeof lockData.skills === "object") return Object.keys(lockData.skills);
+    } catch {}
+    return [];
+  }
+  if (args.action === "scan") return scanSkillDirectory(cwd);
+  if (args.action === "entry") {
+    if (typeof args.name !== "string" || args.name !== path.basename(args.name)) throw new Error("Invalid skill entry name");
+    const entryPath = path.join(cwd, args.name);
+    try {
+      const stat = await fs.stat(entryPath);
+      const file = stat.isDirectory() ? path.join(entryPath, "SKILL.md") : entryPath;
+      if (!stat.isDirectory() && (!stat.isFile() || !args.name.endsWith(".md"))) return null;
+      const doc = parseSkillMarkdown(typeof args.skillName === "string" ? args.skillName : args.name.replace(/\.md$/, ""), await fs.readFile(file, "utf-8"), { preferMetaName: true });
+      doc.sourcePath = file;
+      return isSupportedExternalSkill(doc) ? doc : null;
+    } catch { return null; }
+  }
+  throw new Error("Unknown skill catalog operation");
+}
+
 /** Bundled skills merged with user skill docs from {@link skillDirs} (user overrides by name). */
 export async function loadSkills(cwd: string = process.cwd()): Promise<SkillDoc[]> {
+  if (currentSandboxExecution()) return loadSandboxSkills(cwd);
   try {
     const lockPath = path.join(cwd, "skills-lock.json");
     const lockContent = await fs.readFile(lockPath, "utf-8");