@skydiveai/pi-extensions 0.1.0-beta.129 → 0.1.0-beta.1293

package/dist/index.mjs

@@ -19,6 +19,9 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { Resource } from "@opentelemetry/resources";
 import { BatchSpanProcessor, NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { execFile } from "node:child_process";
+import { availableParallelism } from "node:os";
+import { promisify } from "node:util";
 import { hc } from "hono/client";
 import { parse } from "yaml";
 import { quote } from "shell-quote";
@@ -256,7 +259,7 @@ function createHealthHandler({ metadata }) {
 * read on the hot path before every LLM call), it falls back to the default
 * for that knob and logs once.
 */
-const log$13 = logger.child({ module: "context-management-config" });
+const log$15 = logger.child({ module: "context-management-config" });
 const DEFAULT_CONTEXT_MANAGEMENT_CONFIG = {
 	enabled: false,
 	perResultMaxBytes: 16 * 1024,
@@ -304,7 +307,7 @@ function resolveContextManagementConfig(env = process.env) {
 		maxModelCallsPerTurn: env.SKYDIVE_CTX_MAX_MODEL_CALLS
 	});
 	if (!parsed.success) {
-		log$13.warn({
+		log$15.warn({
 			event: "context_management_config_invalid",
 			err: parsed.error
 		}, "falling back to default context-management config");
@@ -438,7 +441,7 @@ const CAPABILITY_SOUL_NUDGE = "New capability gained — once the current task i
 * or `ToolDefinition[]`. Files starting with `_` or `.` are skipped, so
 * `tools/_example.ts` documents the shape without registering.
 */
-const log$12 = logger.child({ module: "local-tools-extension" });
+const log$14 = logger.child({ module: "local-tools-extension" });
 const TOOLS_DIRNAME = "tools";
 const fileState = /* @__PURE__ */ new Map();
 let pendingLocalToolsUpdate = null;
@@ -582,7 +585,7 @@ async function reconcileAndQueue({ pi, dir, reason }) {
 		dir
 	});
 	if (reason !== "session_start" && summaryHasChanges$1(summary)) pendingLocalToolsUpdate = summary;
-	log$12.info({
+	log$14.info({
 		event: "local_tools_reconcile",
 		reason,
 		total_tools: summary.totalTools,
@@ -604,7 +607,7 @@ const localToolsExtension = (pi) => {
 				reason: "session_start"
 			});
 		} catch (err) {
-			log$12.error({
+			log$14.error({
 				err,
 				event: "local_tools_reconcile_failed"
 			}, "local tools reconcile failed");
@@ -616,7 +619,7 @@ const localToolsExtension = (pi) => {
 		try {
 			current = await listToolFiles(dir);
 		} catch (err) {
-			log$12.warn({
+			log$14.warn({
 				err,
 				event: "local_tools_listing_failed"
 			}, "tools/ listing failed");
@@ -638,7 +641,7 @@ const localToolsExtension = (pi) => {
 				reason: "auto_reload"
 			});
 		} catch (err) {
-			log$12.error({
+			log$14.error({
 				err,
 				event: "local_tools_auto_reload_failed"
 			}, "auto-reload after tools/ change failed");
@@ -692,6 +695,19 @@ const STDERR_BUFFER_BYTES = 4096;
 * indistinguishable from any other transport problem. Walk the cause
 * chain so the agent sees the real underlying error.
 */
+/**
+* True when an error from an http MCP transport (connect, listTools, or a tool
+* call) is an authentication failure. With no authProvider configured the SDK
+* surfaces a 401 as `StreamableHTTPError(401)`; older paths translate it to
+* `UnauthorizedError`. A dead/expired OAuth token (the proxy can no longer
+* mint one) shows up here on the NEXT request against a previously-connected
+* client — not just at connect — so reconcile must re-classify such a failure
+* as `pending_auth` instead of a generic `failed`, keeping the "waiting on
+* auth" report consistent with `platform auth`.
+*/
+function isUnauthorizedError(err) {
+	return err instanceof UnauthorizedError || err instanceof StreamableHTTPError && err.code === 401;
+}
 function formatError(err) {
 	if (!(err instanceof Error)) return String(err);
 	const parts = [err.message];
@@ -713,7 +729,7 @@ async function connectHttp(_id, config, client) {
 			stderr: null
 		};
 	} catch (err) {
-		if (err instanceof UnauthorizedError || err instanceof StreamableHTTPError && err.code === 401) return {
+		if (isUnauthorizedError(err)) return {
 			status: "pending_auth",
 			client,
 			stderr: "",
@@ -863,7 +879,7 @@ async function loadMcpConfig(path) {
 * Clients are keyed by JSON-stringified config and reused across
 * reloads — only changed configs reconnect.
 */
-const log$11 = logger.child({ module: "mcp-extension" });
+const log$13 = logger.child({ module: "mcp-extension" });
 async function closeConnected(connected) {
 	try {
 		await connected.client.close();
@@ -1190,6 +1206,64 @@ var McpExtension = class {
 		try {
 			mcpTools = (await connected.client.listTools()).tools;
 		} catch (err) {
+			if (isUnauthorizedError(err) && serverConfig.transport === "http") {
+				await closeConnected(connected);
+				const retry = await connectClient(id, serverConfig, { connectTimeoutMs });
+				if (retry.status === "pending_auth") return {
+					id,
+					store: {
+						client: retry.client,
+						configKey,
+						status: "pending_auth",
+						stderrBuffer: null,
+						cliHint: retry.cliHint
+					},
+					serverStatus: {
+						status: "pending_auth",
+						stderr: "",
+						cliHint: retry.cliHint
+					},
+					change: null,
+					error: null,
+					tools: null
+				};
+				if (retry.status === "failed") return {
+					id,
+					store: null,
+					serverStatus: {
+						status: "failed",
+						error: retry.error,
+						stderr: retry.stderr
+					},
+					change: null,
+					error: {
+						serverId: id,
+						message: retry.error
+					},
+					tools: null
+				};
+				if (retry.status === "connected") {
+					connected = {
+						client: retry.client,
+						configKey,
+						status: "connected",
+						stderrBuffer: retry.stderr,
+						cliHint: null
+					};
+					mcpTools = (await connected.client.listTools()).tools;
+					return {
+						id,
+						store: connected,
+						serverStatus: { status: "connected" },
+						change: action === "reused" ? "refreshed" : action,
+						error: null,
+						tools: {
+							client: connected.client,
+							list: mcpTools
+						}
+					};
+				}
+			}
 			const message = err instanceof Error ? err.message : String(err);
 			const stderr = connected.stderrBuffer?.read() ?? "";
 			return {
@@ -1227,7 +1301,7 @@ var McpExtension = class {
 		});
 		this.lastConfigMtimeMs = await readConfigMtimeMs(configPath);
 		if (reason !== "session_start" && summaryHasChanges(summary)) this.pendingMcpUpdate = summary;
-		log$11.info({
+		log$13.info({
 			event: "mcp_reconcile",
 			reason,
 			total_tools: summary.totalTools,
@@ -1250,7 +1324,7 @@ var McpExtension = class {
 						reason: "session_start"
 					});
 				} catch (err) {
-					log$11.error({
+					log$13.error({
 						err,
 						event: "mcp_reconcile_failed"
 					}, "MCP reconcile failed");
@@ -1262,7 +1336,7 @@ var McpExtension = class {
 				try {
 					mtime = await readConfigMtimeMs(configPath);
 				} catch (err) {
-					log$11.warn({
+					log$13.warn({
 						err,
 						event: "mcp_mtime_check_failed"
 					}, "mtime check on mcp.config.json failed");
@@ -1276,7 +1350,7 @@ var McpExtension = class {
 						reason: "auto_reload"
 					});
 				} catch (err) {
-					log$11.error({
+					log$13.error({
 						err,
 						event: "mcp_auto_reload_failed"
 					}, "auto-reload after mcp.config.json change failed");
@@ -1639,16 +1713,380 @@ const bashDefaultTimeoutExtension = (pi) => {
 	});
 };
 //#endregion
+//#region src/extensions/resource-pressure-warning.ts
+/**
+* Mid-run resource-pressure warning to the agent.
+*
+* The sandbox already detects pressure — the boot scripts cap the
+* user-workload cgroup (memory.high/memory.max) and watchers log warn/crit
+* edges for memory and disk — but nothing told the *agent*, so a turn burned
+* straight to the OOM kill (or a full disk) and only learned about it from
+* the post-mortem notice. This extension closes that gap in-process: while a
+* turn is active it polls the agent cgroup and the root filesystem and, the
+* first time usage crosses a warn threshold, folds a system notification into
+* the open turn so the agent can checkpoint, shed work (constrain
+* parallelism, kill a background hog, clean scratch space), or request a
+* bigger tier BEFORE the kill.
+*
+* The notification is triggered by the two conditions that actually kill
+* work — memory near the cgroup hard cap, disk near full — and reports a
+* snapshot of all the relevant stats (memory, CPU utilization, disk) so the
+* agent can tell which resource is the problem and how much headroom the
+* others have.
+*
+* Edge-triggered, once per trigger per turn: the fired flags reset on
+* agent_start, so a turn that rides a threshold gets one warning per
+* resource, not a stream. Polling only runs while the agent is active — an
+* idle sandbox's resource usage is not the agent's problem and there is no
+* open turn to deliver into anyway.
+*
+* Best-effort throughout: any read failure (cgroup absent, controller not
+* delegated, non-cgroup-v2 host, df missing) reads as "no signal" for that
+* stat and the extension warns on what it can see — it must never break a
+* turn over an observability feature.
+*/
+const execFileAsync = promisify(execFile);
+const log$12 = logger.child({ module: "resource-pressure-warning" });
+const POLL_INTERVAL_MS = 1e4;
+function envOverride(name) {
+	for (const prefix of ["SKYDIVE_", "ANYONE_"]) {
+		const value = process.env[`${prefix}${name}`];
+		if (value != null && value !== "") return value;
+	}
+	return null;
+}
+function cgroupDir() {
+	return envOverride("AGENT_CGROUP") ?? "/sys/fs/cgroup/agent";
+}
+function diskRoot() {
+	return envOverride("DISK_ROOT") ?? "/";
+}
+/**
+* Read a cgroup v2 scalar file. Returns a number, or null for "max"
+* (uncapped), an empty/absent file, or any read/parse error — an uncapped or
+* unreadable limit means there is nothing meaningful to warn against.
+*/
+async function readScalar(file) {
+	try {
+		const raw = (await readFile(`${cgroupDir()}/${file}`, "utf8")).trim();
+		if (raw === "" || raw === "max") return null;
+		const n = Number(raw);
+		return Number.isFinite(n) ? n : null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Read a cgroup v2 "flat keyed" file (one `key value` pair per line, e.g.
+* cpu.stat) and return the counter for `key`, or null when absent.
+*/
+async function readKeyedCounter(file, key) {
+	try {
+		const raw = await readFile(`${cgroupDir()}/${file}`, "utf8");
+		for (const line of raw.split("\n")) {
+			const [k, v] = line.trim().split(/\s+/);
+			if (k === key) {
+				const n = Number(v);
+				return Number.isFinite(n) ? n : null;
+			}
+		}
+		return null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Live memory usage as an integer percent of the hard cap, or null when
+* either side is unreadable/uncapped. Exported for tests.
+*/
+async function readMemUsePct() {
+	const [current, max] = await Promise.all([readScalar("memory.current"), readScalar("memory.max")]);
+	if (current === null || max === null || max <= 0) return null;
+	return {
+		pct: Math.floor(current / max * 100),
+		currentBytes: current,
+		maxBytes: max
+	};
+}
+/**
+* Root filesystem used% (df -P Capacity column), or null on any failure.
+* Exported for tests.
+*/
+async function readDiskUsePct() {
+	try {
+		const { stdout } = await execFileAsync("df", ["-P", diskRoot()]);
+		const dataRow = stdout.trim().split("\n")[1];
+		if (dataRow == null) return null;
+		const capacity = dataRow.trim().split(/\s+/)[4];
+		if (capacity == null) return null;
+		const pct = Number(capacity.replace("%", ""));
+		return Number.isFinite(pct) ? pct : null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* CPU utilization sampler. cgroup v2 exposes cumulative CPU time
+* (cpu.stat usage_usec); utilization is the delta between two samples over
+* the wall time between them, normalized by core count. The first call after
+* construction has no previous sample and returns null.
+*/
+function createCpuSampler() {
+	let prevUsageUsec = null;
+	let prevAtMs = null;
+	return async () => {
+		const usage = await readKeyedCounter("cpu.stat", "usage_usec");
+		const now = Date.now();
+		const prev = prevUsageUsec;
+		const prevAt = prevAtMs;
+		prevUsageUsec = usage;
+		prevAtMs = now;
+		if (usage === null || prev === null || prevAt === null) return null;
+		const wallUsec = (now - prevAt) * 1e3;
+		if (wallUsec <= 0) return null;
+		const cores = availableParallelism();
+		const pct = Math.round((usage - prev) / (wallUsec * cores) * 100);
+		return Math.max(0, Math.min(100, pct));
+	};
+}
+function fmtMb(bytes) {
+	return Math.round(bytes / 1024 / 1024);
+}
+/** The model-facing warning text. Exported for tests. */
+function resourcePressureWarningText(trigger, { mem, cpuPct, diskPct }) {
+	const stats = [];
+	if (mem) stats.push(`memory ${mem.pct}% of cap (${fmtMb(mem.currentBytes)}/${fmtMb(mem.maxBytes)} MB)`);
+	if (cpuPct !== null) stats.push(`CPU ${cpuPct}%`);
+	if (diskPct !== null) stats.push(`disk ${diskPct}% full`);
+	const lead = trigger === "memory" ? `Your sandbox is at ${mem?.pct}% of its memory cap. If usage keeps climbing, the kernel will kill the offending process and this turn may die with it.` : `Your sandbox's disk is ${diskPct}% full. If it fills completely, writes will start failing and this turn may die with them.`;
+	const remedy = trigger === "memory" ? "checkpoint in-flight work (commit and push), then reduce the footprint — constrain parallelism, run heavy steps sequentially, or kill background processes you no longer need." : "checkpoint in-flight work (commit and push), then free space — clean build artifacts, caches, and scratch files you no longer need.";
+	return `<system_notification>${lead} Current usage: ${stats.join(", ")}. Act now: ${remedy} If the workload genuinely needs more resources, request a bigger sandbox with \`platform compute request\`. This is an automated resource warning, not a message from the user; continue the task, adjusted.</system_notification>`;
+}
+const resourcePressureWarningExtension = (pi) => {
+	let agentActive = false;
+	let warnedMemThisTurn = false;
+	let warnedDiskThisTurn = false;
+	let timer = null;
+	const sampleCpu = createCpuSampler();
+	async function checkOnce() {
+		if (!agentActive || warnedMemThisTurn && warnedDiskThisTurn) return;
+		const [mem, cpuPct, diskPct] = await Promise.all([
+			readMemUsePct(),
+			sampleCpu(),
+			readDiskUsePct()
+		]);
+		let trigger = null;
+		if (!warnedMemThisTurn && mem !== null && mem.pct >= 80) {
+			trigger = "memory";
+			warnedMemThisTurn = true;
+		} else if (!warnedDiskThisTurn && diskPct !== null && diskPct >= 80) {
+			trigger = "disk";
+			warnedDiskThisTurn = true;
+		}
+		if (trigger === null) return;
+		log$12.warn({
+			trigger,
+			mem,
+			cpuPct,
+			diskPct
+		}, "resource pressure warning delivered to agent");
+		await pi.sendMessage({
+			customType: "anyone-resource-pressure-warning",
+			content: resourcePressureWarningText(trigger, {
+				mem,
+				cpuPct,
+				diskPct
+			}),
+			display: false
+		}, {
+			triggerTurn: true,
+			deliverAs: "followUp"
+		});
+	}
+	pi.on("agent_start", async () => {
+		agentActive = true;
+		warnedMemThisTurn = false;
+		warnedDiskThisTurn = false;
+		if (!timer) {
+			timer = setInterval(() => {
+				checkOnce().catch((err) => {
+					log$12.error({ err }, "resource pressure check failed");
+				});
+			}, POLL_INTERVAL_MS);
+			timer.unref?.();
+		}
+	});
+	pi.on("agent_end", async () => {
+		agentActive = false;
+		if (timer) {
+			clearInterval(timer);
+			timer = null;
+		}
+	});
+};
+//#endregion
+//#region src/extensions/disk-guard.ts
+const log$11 = logger.child({ module: "disk-guard" });
+/**
+* In-band bypass. The guard is a safety net, not a jail: when the agent knows
+* a flagged command is genuinely safe (writing to a different mount, a tiny
+* bounded download, a delete-then-clone one-liner, an emergency it accepts the
+* risk on) it can force the command through by appending this marker as a
+* trailing shell comment. Kept as a comment so it never changes what the
+* command does, and matched case-insensitively with flexible spacing so the
+* agent doesn't have to reproduce it byte-for-byte.
+*/
+const BYPASS_MARKER = /#\s*disk-guard:\s*allow\b/i;
+/** The exact marker text the block message tells the agent to append. */
+const BYPASS_HINT = "# disk-guard: allow";
+/**
+* Harness-level kill switch: set DISK_GUARD_DISABLE=1 to turn the guard off
+* entirely. This is the "I own my harness, let me opt out" knob — an agent
+* that boots its own harness can disable the guard for its whole process
+* without a code roll, and it's also the fleet-wide escape hatch if the
+* classifier ever misfires and blocks real work. The bare name is honored
+* first; the SKYDIVE_/ANYONE_ prefixes are accepted too for consistency with
+* the other env overrides. Empty/unset/"0"/"false" leave the guard on.
+*/
+function guardDisabledByEnv() {
+	for (const name of [
+		"DISK_GUARD_DISABLE",
+		"SKYDIVE_DISK_GUARD_DISABLE",
+		"ANYONE_DISK_GUARD_DISABLE"
+	]) {
+		const value = process.env[name];
+		if (value != null && value !== "" && value !== "0" && value !== "false") return true;
+	}
+	return false;
+}
+/** True when the command carries the in-band bypass marker. */
+function hasBypassMarker(command) {
+	return BYPASS_MARKER.test(command);
+}
+/**
+* Commands that reclaim space or merely inspect it. If any of these verbs
+* appears in the command line, we never block — otherwise the guard would trap
+* the agent by blocking the exact command it needs to dig out. Matched as
+* whole words so `remove-item` etc. don't accidentally match `rm`.
+*/
+const RECLAIM_PATTERNS = [
+	/\brm\b/,
+	/\brmdir\b/,
+	/\bdf\b/,
+	/\bdu\b/,
+	/\bncdu\b/,
+	/\bfind\b[^|]*\s-delete\b/,
+	/\btruncate\b/,
+	/\bgit\s+(gc|prune|clean|worktree\s+remove|worktree\s+prune)\b/,
+	/\b(yarn|npm|pnpm|bun)\s+.*\b(cache\s+clean|cache\s+clear|store\s+prune)\b/,
+	/\bcache\s+(clean|clear|prune)\b/,
+	/\b(docker|podman)\s+.*\bprune\b/,
+	/\bapt(-get)?\s+clean\b/,
+	/\bjournalctl\b[^|]*--vacuum/
+];
+/**
+* File extensions that mean a download is actually LARGE — archives, disk
+* images, compiled/binary artifacts, model weights, media. A curl/wget is only
+* gated when it writes one of these; an API/page fetch to a `.json`/`.html`/
+* `.txt` file is tiny and must not be blocked. Derived from 4,144 real
+* commands: ~64% of `curl -o` uses were tiny fetches, only ~4% large.
+*/
+const BIG_DOWNLOAD_EXT = "(?:tar\\.gz|tgz|tar|zip|iso|gz|bz2|xz|zst|deb|rpm|pkg|dmg|whl|jar|7z|img|mp4|mov|avi|mkv|onnx|gguf|safetensors|bin|node)";
+/**
+* Commands that consume a meaningful amount of disk. Kept deliberately tight
+* and high-precision: validated against 4,144 real commands from the last 7
+* days, the earlier "writes a file" heuristic flagged 82% of everything (a
+* `curl -o /tmp/x.json` API call is not a disk event). This set flags ~33%,
+* almost all genuinely large — real installs, clones, big-archive downloads,
+* extractions. What was DROPPED and why:
+*   - `git fetch` / `git pull` — incremental on an existing clone, usually tiny.
+*   - `git checkout` — overwhelmingly `git checkout <ref> -- <file>` or a
+*     branch switch, ~zero net growth; the rare full materialization isn't
+*     worth the false-positive rate.
+*   - bare `curl -o` / `wget -o` — see BIG_DOWNLOAD_EXT above.
+*   - loose `… build` — matched `--mode=skip-build`, `oxfmt … build`, prose.
+* The remaining big-disk op in escher is `git clone` and `git worktree add`
+* (which is really a checkout), both kept.
+*/
+const SPACE_HUNGRY_PATTERNS = [
+	/\bgit\s+clone\b/,
+	/\bgit\s+worktree\s+add\b/,
+	/\b(yarn|npm|pnpm|bun)\s+(install|add|ci)\b/,
+	/\byarn\s*$/,
+	/\byarn\s+--(?!version|help)\S/,
+	/\bpip3?\s+install\b/,
+	/\bapt(-get)?\s+install\b/,
+	/\bnpm\s+pack\b/,
+	/\bdocker\s+(build|pull)\b/,
+	new RegExp(`\\b(?:curl|wget)\\b[^\\n]*\\s-[a-zA-Z]*[oO]\\b[^\\n]*\\.${BIG_DOWNLOAD_EXT}\\b`, "i"),
+	new RegExp(`\\b(?:curl|wget)\\b[^\\n]*\\.${BIG_DOWNLOAD_EXT}\\b[^\\n]*\\s-[a-zA-Z]*[oO]\\b`, "i"),
+	/\btar\s+[^\n|]*x[^\n|]*f/,
+	/\bunzip\b/,
+	/\bdd\b[^\n|]*\bof=/
+];
+/**
+* True when the command reclaims or inspects space — these are always allowed,
+* even on a 100%-full box, so the agent can dig itself out.
+*/
+function isReclaimCommand(command) {
+	return RECLAIM_PATTERNS.some((re) => re.test(command));
+}
+/**
+* True when the command is likely to consume a meaningful amount of disk.
+* A reclaim/inspect command is never space-hungry — the reclaim check wins so a
+* `git worktree remove` or a `yarn cache clean` is never mistaken for growth.
+*/
+function isSpaceHungryCommand(command) {
+	if (isReclaimCommand(command)) return false;
+	return SPACE_HUNGRY_PATTERNS.some((re) => re.test(command));
+}
+/**
+* The decision, factored out and pure so it's exhaustively testable without a
+* real filesystem. Block only when we have a disk reading, it's at/above the
+* critical threshold, the command is space-hungry (and not a reclaim), and the
+* agent hasn't explicitly opted out with the bypass marker.
+*/
+function shouldBlockForDisk(command, diskPct) {
+	if (diskPct === null) return false;
+	if (diskPct < 95) return false;
+	if (hasBypassMarker(command)) return false;
+	return isSpaceHungryCommand(command);
+}
+/** The agent-facing explanation returned as the blocked tool result. */
+function diskBlockReason(command, diskPct) {
+	return `Blocked: the sandbox disk is ${diskPct}% full and this command (\`${command.trim().slice(0, 120)}\`) writes a large amount, so it would fail partway with ENOSPC and leave a corrupt result. Reclaim space FIRST, then retry. Free ONLY what THIS conversation created — scratch/build output you wrote this run, downloads you're done with, and worktrees/branches whose work you've already committed and pushed (\`git worktree remove\`, \`yarn cache clean\`, delete your own scratch). Do NOT blindly wipe /tmp or delete a clone/worktree you don't recognize — other conversations share this box. Check headroom with \`df -h /\` and \`du -sh ~/workspace/* 2>/dev/null\`. If you genuinely can't free enough, stop and tell the user you're blocked on disk rather than retrying the write. If you're certain this command is safe anyway (writes elsewhere, tiny bounded size, delete-then-write), force it through by appending \` ${BYPASS_HINT}\` to the command.`;
+}
+const diskGuardExtension = (pi) => {
+	pi.on("tool_call", async (event) => {
+		if (event.toolName !== "bash") return;
+		if (guardDisabledByEnv()) return;
+		const command = event.input.command;
+		if (typeof command !== "string" || command.length === 0) return;
+		if (hasBypassMarker(command)) return;
+		if (!isSpaceHungryCommand(command)) return;
+		const diskPct = await readDiskUsePct();
+		if (!shouldBlockForDisk(command, diskPct)) return;
+		log$11.warn({
+			diskPct,
+			command: command.slice(0, 200)
+		}, "blocked space-hungry bash command on near-full disk");
+		return {
+			block: true,
+			reason: diskBlockReason(command, diskPct)
+		};
+	});
+};
+//#endregion
 //#region src/channel-context-ref.ts
 /**
-* The worker injects only a reference — `{ channel, messageId }` — into the
-* sandbox env (`SKYDIVE_CHANNEL_CONTEXT`) rather than the full context.
+* The worker injects a small reference — `{ channel, messageId, runId }` —
+* into the sandbox env (`SKYDIVE_CHANNEL_CONTEXT`) rather than the full context.
 *
 * The canonical `ChannelContextRef` type + `parseChannelContextRef` live in
 * `@createinc/anyone-channels`, but the harness (`@skydiveai/*`) keeps zero
 * `@createinc/*` dependencies — importing that package would pull the whole
-* platform channel stack (Slack/email/Linq SDKs, messaging) in just to read
-* two fields. So we validate the (stable) shape locally instead.
+* platform channel stack (Slack/email/Linq SDKs, messaging) just to read one
+* field. So we validate the field this consumer needs locally instead.
 */
 const channelContextRefSchema = z.object({ messageId: z.string().nullable() });
 /**
@@ -1680,6 +2118,23 @@ function apiBaseUrl() {
 }
 //#endregion
 //#region src/extensions/platform.ts
+/**
+* Platform extension — bridges the agent harness to the Skydive platform daemon.
+*
+* Responsibilities:
+* - Heartbeat: periodic POST to the API so the sandbox manager knows the
+*   agent is alive. Throttled to once per minute, triggered by tool events.
+* - Session tracking: registers the session with the daemon on start,
+*   streams tool_call / tool_result events so the daemon can track which
+*   session is actively executing, and signals session end on agent_end.
+* - Channel context: passes the SKYDIVE_CHANNEL_CONTEXT (containing the
+*   messageId) to the daemon so file writes can be attributed to the
+*   correct conversation.
+*
+* All daemon POSTs are fire-and-forget — failures are logged but never
+* block the agent. The daemon may not be running (e.g. local dev without
+* a sandbox), and that's fine.
+*/
 const HEARTBEAT_THROTTLE_MS = 6e4;
 const TOOL_HEARTBEAT_INTERVAL_MS = 5e3;
 const MAX_TOOL_HEARTBEATS = 1440 * 60 * 1e3 / TOOL_HEARTBEAT_INTERVAL_MS;
@@ -1691,9 +2146,56 @@ function sandboxClient() {
 	return hc(`${apiUrl}/api/v1/sandbox`);
 }
 /**
-* Fetch every harness feature flag in one GET (`{ contextManagement, subagent,
-* ... }` — see apps/anyone/api/src/routes/sandbox-feature-flags.ts). Returns
-* null when indeterminate (no api url, or the request failed) so the shared
+* Is this box still an unclaimed warm-pool sandbox? (ANY-6000, the
+* feature-flags half of the ANY-5184 pool 403 wave.)
+*
+* `GET /sandbox/feature-flags` is agent-only, so the shared poller's request
+* from a pool box can only 403 — a guaranteed-failing GET every 60s for the
+* life of the pool phase. The discriminator is the sandbox token's `type`
+* claim, read UNVERIFIED (this box never holds the signing secret): not an
+* authorization decision, only "should I bother calling?", and the api still
+* authorizes every request.
+*
+* Read per call from the daemon's persisted env file, NOT process.env:
+* claiming a pool box rebinds the token in place (the daemon rewrites this
+* file) while the harness's process.env keeps the boot snapshot, so a
+* process-env gate would leave a claimed box permanently skipping — trading a
+* wasted request for silently frozen flags, which is strictly worse. "Cannot
+* tell" (no file, no token, unparseable payload) reports false so the poll
+* proceeds.
+*/
+const daemonEnvIdentitySchema = z.object({
+	ANYONE_SANDBOX_TOKEN: z.string().optional(),
+	SKYDIVE_SANDBOX_TOKEN: z.string().optional()
+}).passthrough();
+const tokenTypeSchema = z.object({ type: z.string() }).passthrough();
+async function isPoolIdentity() {
+	try {
+		const override = process.env.ANYONE_DAEMON_ENV_CACHE;
+		const candidates = override ? [override] : ["/run/anyone-system/daemon-env.json", "/tmp/.anyone/daemon-env.json"];
+		let raw = null;
+		for (const file of candidates) {
+			raw = await readFile(file, "utf8").catch(() => null);
+			if (raw !== null) break;
+		}
+		if (raw === null) return false;
+		const env = daemonEnvIdentitySchema.safeParse(JSON.parse(raw));
+		if (!env.success) return false;
+		const token = env.data.ANYONE_SANDBOX_TOKEN ?? env.data.SKYDIVE_SANDBOX_TOKEN;
+		if (typeof token !== "string" || token === "") return false;
+		const payload = token.split(".")[1];
+		if (!payload) return false;
+		const claims = tokenTypeSchema.safeParse(JSON.parse(Buffer.from(payload, "base64url").toString("utf8")));
+		return claims.success && claims.data.type === "onboarding-pool";
+	} catch (_err) {
+		return false;
+	}
+}
+/**
+* Fetch every harness feature flag in one GET (`{ contextManagement, ... }`
+* — see apps/anyone/api/src/routes/sandbox-feature-flags.ts). Returns
+* null when indeterminate (no api url, the request failed, or the box is an
+* unclaimed pool sandbox whose token the route would 403) so the shared
 * poller keeps the last-known values rather than flipping on a transient error.
 * This is the single fetch behind `feature-flags-poll.ts`; extensions read the
 * polled values there instead of issuing their own GET.
@@ -1701,6 +2203,7 @@ function sandboxClient() {
 async function fetchHarnessFlags() {
 	const client = sandboxClient();
 	if (!client) return null;
+	if (await isPoolIdentity()) return null;
 	try {
 		const res = await client["feature-flags"].$get();
 		if (!res.ok) {
@@ -1710,11 +2213,7 @@ async function fetchHarnessFlags() {
 			}, "feature-flags fetch failed");
 			return null;
 		}
-		const body = await res.json();
-		return {
-			contextManagement: body.contextManagement ?? null,
-			subagent: body.subagent ?? null
-		};
+		return { contextManagement: (await res.json()).contextManagement ?? null };
 	} catch (err) {
 		log$10.debug({
 			err,
@@ -1772,8 +2271,19 @@ async function postSubagentSpawn({ messageId, tasks }) {
 		messageId,
 		tasks
 	} });
-	if (!res.ok) throw new Error(`subagent-spawn POST failed: ${res.status}`);
-	return { taskIds: (await res.json()).taskIds };
+	if (!res.ok) {
+		let detail = "";
+		try {
+			const errBody = await res.json();
+			if (errBody && typeof errBody.error === "string") detail = `: ${errBody.error}`;
+		} catch {}
+		throw new Error(`subagent-spawn POST failed (${res.status})${detail}`);
+	}
+	const body = await res.json();
+	return {
+		taskIds: body.taskIds,
+		tasks: body.tasks ?? []
+	};
 }
 function createHeartbeatThrottle({ messageId }) {
 	let lastAt = 0;
@@ -1922,20 +2432,16 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 * Shared harness feature-flag poll.
 *
 * The api exposes one `/feature-flags` GET that returns every harness flag in a
-* single response (`{ contextManagement, subagent, commandFlags }` — see
+* single response (`{ contextManagement, commandFlags }` — see
 * apps/anyone/api/src/routes/sandbox-feature-flags.ts). Rather than each
 * extension issuing its own GET — and, worse, a *blocking* GET on the
 * pre-first-token `session_start` path — a single background poller fetches
 * that response once per interval and fans the values out to every subscriber.
 *
-* Why one poller: the subagent extension gates its tool registration on the
-* `subagent` flag. If it awaited a fresh GET inside `session_start` the tool
-* schema (part of the prefill) couldn't be finalized until a serial
-* sandbox→api round-trip settled, adding a net-new pre-token network hop on
-* every session, flag on or off. Reading the last-polled value instead keeps
-* the hot path allocation-only. A cold cache reads as `null` (fail-open to
-* unregistered); a newly-flipped flag takes effect on the next poll, matching
-* how context-management already treats its flag.
+* Why one poller: context-management consumes the `contextManagement` flag
+* without a blocking GET on the pre-first-token `session_start` path. Reading
+* the last-polled value keeps the hot path allocation-only; a cold cache reads
+* as `null` and a newly-flipped flag takes effect on the next poll.
 *
 * The poll is fire-and-forget and self-unref'd — it never keeps the process
 * alive and an indeterminate result (no api url / transient failure) leaves the
@@ -1944,15 +2450,11 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 const log$9 = logger.child({ module: "feature-flags-poll" });
 const FLAG_POLL_INTERVAL_MS = 6e4;
 let contextManagement = null;
-let subagent = null;
-const subscribers = {
-	contextManagement: /* @__PURE__ */ new Set(),
-	subagent: /* @__PURE__ */ new Set()
-};
+const subscribers = { contextManagement: /* @__PURE__ */ new Set() };
 let pollerStarted = false;
 let firstPollSettled = false;
 let resolveFirstPoll = null;
-const firstPollPromise = new Promise((resolve) => {
+new Promise((resolve) => {
 	resolveFirstPoll = resolve;
 });
 function markFirstPollSettled() {
@@ -1961,20 +2463,8 @@ function markFirstPollSettled() {
 	resolveFirstPoll?.();
 }
 /** Last-polled value of a flag, or `null` if not yet resolved. */
-function getPolledFlag(name) {
-	return name === "contextManagement" ? contextManagement : subagent;
-}
-/**
-* Await the first poll already kicked by `startFeatureFlagPoller` (never a new
-* GET). Resolves when that poll settles, immediately if it already has, or
-* immediately when there's no flag source to poll. Callers on the hot path
-* should race this against their own short timeout so a slow/failed flag
-* service cannot delay first-token; a timeout just means the caller reads the
-* still-cold cache and falls back to its default, exactly as before.
-*/
-function awaitFirstFlagPoll() {
-	if (firstPollSettled || !hasFlagSource()) return Promise.resolve();
-	return firstPollPromise;
+function getPolledFlag(_name) {
+	return contextManagement;
 }
 /**
 * Subscribe to changes of a flag. The callback fires only on a *transition*
@@ -1987,9 +2477,8 @@ function onFlagChange(name, cb) {
 }
 function apply(name, next) {
 	if (next === null) return;
-	const prev = name === "contextManagement" ? contextManagement : subagent;
-	if (name === "contextManagement") contextManagement = next;
-	else subagent = next;
+	const prev = contextManagement;
+	contextManagement = next;
 	if (next !== prev) for (const cb of subscribers[name]) try {
 		cb(next);
 	} catch (err) {
@@ -2004,7 +2493,6 @@ async function pollOnce() {
 		const flags = await fetchHarnessFlags();
 		if (!flags) return;
 		apply("contextManagement", flags.contextManagement ?? null);
-		apply("subagent", flags.subagent ?? null);
 	} catch (err) {
 		log$9.debug({ err }, "feature-flag poll threw");
 	}
@@ -2763,7 +3251,7 @@ function soulSection(cwd, soul) {
 
 **\`soul.md\` is where behavior lives.** Any standing instruction about how you should act — a rule a user wants you to follow going forward, a tone or format preference, a workflow convention, a "from now on, always/never …" — belongs here, not in \`.memory/\`. Memory records *what happened* (facts, events, findings); soul defines *how you behave*. When a user gives you a durable behavioral rule, write it to \`soul.md\`. If you find behavioral rules that ended up in \`.memory/\`, treat that as misfiled and move them here.
 
-Keep it current. When you gain a durable new capability — a tool you build, a skill or integration you set up, a service you connect — or a user hands you a lasting behavioral rule, record it in \`soul.md\` so a future conversation knows it's part of you rather than rediscovering it from scratch. Edit it (then \`git add soul.md && git commit && git push\`) to redefine yourself; picked up on the next message.
+Keep it current. When you gain a durable new capability — a tool you build, a skill or integration you set up, a service you connect, a secret or auth credential you wire in — or a user hands you a lasting behavioral rule, record it in \`soul.md\` so a future conversation knows it's part of you rather than rediscovering it from scratch. Do this the moment you gain the capability, and for a credential that means the moment it verifies with a real call, not after a human points out that you forgot. Connecting a capability is itself a durable change worth recording, not merely a step toward the task in front of you. Edit \`soul.md\` (then \`git add soul.md && git commit && git push\`) to redefine yourself; picked up on the next message.
 
 ${soul ? soul : "_(empty — write to `soul.md` to define your persona)_"}`;
 }
@@ -2782,7 +3270,6 @@ const soulExtension = (pi) => {
 //#endregion
 //#region src/extensions/subagent/index.ts
 const log$2 = logger.child({ module: "subagent-ext" });
-const COLD_START_FLAG_WAIT_MS = 750;
 const MAX_TASKS = 8;
 const TaskItem = Type.Object({
 	task: Type.String({ description: "The task to delegate to a subagent run." }),
@@ -2791,8 +3278,14 @@ const TaskItem = Type.Object({
 		maxLength: 120
 	}),
 	persona: Type.Optional(Type.String({ description: "Optional extra system prompt / role for this task, applied ON TOP of the child run's own default persona (your full identity and soul are still there underneath). Omit to run with just your default persona." })),
-	model: Type.Optional(Type.String({ description: "Optional model id to run this subagent on (e.g. \"anthropic/claude-opus-4-8\"). Must be a real catalogued model. Omit to run on your own model. If you are locked to a Google-compliant model, only compliant models are accepted." }))
+	model: Type.Optional(Type.String({ description: "Optional model id to run this subagent on. PREFER A LOWER-COST, FASTER MODEL when the task is well-scoped and does not need your full reasoning depth — most delegated subtasks (searching, summarizing, mechanical edits, gathering or reformatting data, running a check) run just as well on a lighter model and cost far less. Reserve a top-tier model for subtasks that genuinely need deep reasoning or careful judgment. Must be a real catalogued model id. Omit to inherit your own model. If you are locked to a Google-compliant model, only compliant models are accepted." })),
+	timeoutMinutes: Type.Optional(Type.Integer({
+		description: "Optional wall-clock timeout for this subagent, in minutes. If the run is still going after this long it is ended and you are rewoken with a timeout result, so a hung subagent can never strand you. Omit for the default (30 minutes). Raise it for genuinely long work (a big migration, a large audit); lower it for a quick lookup. Range 1-360.",
+		minimum: 1,
+		maximum: 360
+	}))
 });
+const DEFAULT_SUBAGENT_TIMEOUT_MS = 30 * 6e4;
 const SubagentParams = Type.Object({ tasks: Type.Array(TaskItem, {
 	description: "One or more tasks to delegate. Each spawns an isolated subagent run linked to this conversation; they run in parallel and each rewakes you with its result when it finishes.",
 	minItems: 1,
@@ -2807,7 +3300,9 @@ function buildTool(messageId) {
 			"Delegate one or more tasks to subagent runs — fresh isolated copies of yourself, each with its own context window, linked to this conversation.",
 			"Use it to parallelize independent work, to keep a large or noisy subtask out of your own context, or to run a task under a specialized persona.",
 			"Fire-and-forget: this returns immediately after queueing. It does NOT wait for results. Each subagent runs on its own and, when it finishes, sends you its result on this thread — so queue the work, then keep going or end your turn. To chain, re-delegate after a result lands.",
-			"Pass tasks: [{ task, title, persona?, model? }]. title is a short 3-6 word name for the task — it is shown to the person in the chat as that subagent's row, so name the work rather than restating the prompt. persona is an optional extra system prompt layered ON TOP of your default persona for that task (it adds to, it does not replace, your identity); omit it to run with just your default persona. model is an optional model id for that task; omit it to run on your own model."
+			"Pass tasks: [{ task, title, persona?, model? }]. title is a short 3-6 word name for the task — it is shown to the person in the chat as that subagent's row, so name the work rather than restating the prompt. persona is an optional extra system prompt layered ON TOP of your default persona for that task (it adds to, it does not replace, your identity); omit it to run with just your default persona. model is an optional model id for that task — prefer a lower-cost, faster model for well-scoped subtasks that don't need deep reasoning, and reserve a top-tier model for the ones that do; omit it to inherit your own model.",
+			"Peering: each queued task comes back with its own conversation id. A subagent is a real linked conversation, so to see what one is doing RIGHT NOW while it runs — its reasoning, the tools it has called and their results, its progress — read that conversation with `platform conversations show <conversationId>` (you are already authorized; it is your own delegated run). Check in that way instead of waiting blind for the final result. The read reflects the child's persisted state, which lags a few seconds behind live (tool results land as they complete; in-progress reasoning can be up to ~5s stale), so peek between checkpoints rather than polling in a tight loop.",
+			"Steering: to add context, correct course, or answer a question a subagent needs mid-run, post to its conversation with `platform conversations post <conversationId> --message \"...\"`. If the subagent is still running, your message lands as a live steer picked up in that same turn; if it has gone idle, it queues as its next turn. This is the same primitive as any conversation message — there is no separate steer channel."
 		].join(" "),
 		promptSnippet: "subagent — delegate tasks to isolated subagent runs; each rewakes you with its result when done",
 		parameters: SubagentParams,
@@ -2825,24 +3320,35 @@ function buildTool(messageId) {
 				task: t.task,
 				title: t.title ?? null,
 				persona: t.persona ?? null,
-				model: t.model ?? null
+				model: t.model ?? null,
+				timeoutMs: t.timeoutMinutes != null ? t.timeoutMinutes * 6e4 : DEFAULT_SUBAGENT_TIMEOUT_MS
 			}));
 			try {
-				const { taskIds } = await postSubagentSpawn({
+				const spawned = await postSubagentSpawn({
 					messageId,
 					tasks: spawnTasks
 				});
+				const { taskIds } = spawned;
 				log$2.info({
 					event: "subagent_spawned",
 					count: taskIds.length
 				}, "subagent tasks queued");
-				const lines = taskIds.map((id, i) => `- ${id}: ${spawnTasks[i]?.title ?? spawnTasks[i]?.task ?? ""}`).join("\n");
+				const convByTask = new Map(spawned.tasks.map((t) => [t.taskId, t.conversationId]));
+				const lines = taskIds.map((id, i) => {
+					const label = spawnTasks[i]?.title ?? spawnTasks[i]?.task ?? "";
+					const conv = convByTask.get(id);
+					return `- ${id}: ${label}${conv ? ` — conversation ${conv}` : ""}`;
+				}).join("\n");
+				const peerHint = spawned.tasks.length ? "\nEach subagent runs on its own conversation (id shown per task above). To SEE what one is doing while it runs, read it with `platform conversations show <conversationId>`. To STEER one mid-run — add context, correct course, answer a question — post to its conversation with `platform conversations post <conversationId> --message \"...\"`; it lands as a live steer if the subagent is still running, or as its next turn if it has gone idle." : "";
 				return {
 					content: [{
 						type: "text",
-						text: `Queued ${taskIds.length} subagent ${taskIds.length === 1 ? "run" : "runs"}. Each runs on its own and will send you its result on this thread when it finishes — keep working or end your turn meanwhile.\n${lines}`
+						text: `Queued ${taskIds.length} subagent ${taskIds.length === 1 ? "run" : "runs"}. Each runs on its own and will send you its result on this thread when it finishes — keep working or end your turn meanwhile.\n${lines}${peerHint}`
 					}],
-					details: { taskIds }
+					details: {
+						taskIds,
+						tasks: spawned.tasks
+					}
 				};
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
@@ -2863,16 +3369,15 @@ function buildTool(messageId) {
 	};
 }
 /**
-* Gated on `harness-subagent-enabled`, read from the shared feature-flag poll.
 * The factory takes the session's channel context to resolve the originating
 * messageId — the api links each spawned run to the conversation that message
 * belongs to and rewakes it on completion (nothing about the parent is piped
-* from the sandbox beyond that id).
+* from the sandbox beyond that id). The tool is registered unconditionally at
+* session_start.
 */
 function createSubagentExtension({ channelContext }) {
 	return (pi) => {
 		const messageId = extractMessageId(channelContext);
-		startFeatureFlagPoller();
 		let registered = false;
 		const registerOnce = () => {
 			if (registered) return;
@@ -2880,12 +3385,8 @@ function createSubagentExtension({ channelContext }) {
 			pi.registerTool(buildTool(messageId));
 			log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
 		};
-		onFlagChange("subagent", (enabled) => {
-			if (enabled) registerOnce();
-		});
-		pi.on("session_start", async () => {
-			if (getPolledFlag("subagent") === null) await Promise.race([awaitFirstFlagPoll(), new Promise((resolve) => setTimeout(resolve, COLD_START_FLAG_WAIT_MS).unref?.())]);
-			if (getPolledFlag("subagent") === true) registerOnce();
+		pi.on("session_start", () => {
+			registerOnce();
 		});
 	};
 }
@@ -3645,6 +4146,7 @@ const all = [
 	localToolsExtension,
 	toolCallEnvExtension,
 	bashDefaultTimeoutExtension,
+	diskGuardExtension,
 	toolCallSummaryExtension
 ];
 /**
@@ -3663,7 +4165,8 @@ function platformExtensions({ sessionId, channelContext }) {
 		selfTraceExtension,
 		createBackgroundTasksExtension({ channelContext }),
 		createSubagentExtension({ channelContext }),
-		createContextManagementExtension()
+		createContextManagementExtension(),
+		resourcePressureWarningExtension
 	];
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skydiveai/pi-extensions",
-  "version": "0.1.0-beta.129",
+  "version": "0.1.0-beta.1293",
   "homepage": "https://skydive.com",
   "license": "MIT",
   "author": "Create, Inc.",
@@ -17,12 +17,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      }
-    },
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {