@skydiveai/pi-extensions 0.1.0-beta.197 → 0.1.0-beta.1973

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { DefaultExecutionEventBusManager, DefaultRequestHandler, InMemoryTaskStore } from "@a2a-js/sdk/server";
 import { UserBuilder, restHandler } from "@a2a-js/sdk/server/express";
 import { buildAgentCard, chainMiddleware, composeHandlers, createAgentExecutor, createProtocolHandlers, getCurrentTraceparent, logger, mountAt, requestHeaders, requestUrl, webHandlerToMiddleware } from "@skydiveai/pi-server";
-import { mkdir, open, readFile, readdir, stat, unlink } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { z } from "zod";
 import { pathToFileURL } from "node:url";
@@ -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");
@@ -415,6 +418,275 @@ function installIterationCap({ session, log }, configOverride = null) {
 */
 const CAPABILITY_SOUL_NUDGE = "New capability gained — once the current task is done, if this changes what you can do for the user, record it in `soul.md` so it carries into future conversations rather than being rediscovered from scratch (then commit and push).";
 //#endregion
+//#region src/extensions/tool-call-summary.ts
+const log$14 = logger.child({ module: "tool-call-summary-extension" });
+/**
+* The injected parameter name: a namespaced sentinel, so it can never collide
+* with a real tool argument and is unmistakable in transcripts and logs. The
+* frontend renderer (ANY-2723) duplicates this literal — keep the two in sync.
+*/
+const TOOL_CALL_SUMMARY_FIELD = "__skydive_summary__";
+/** JSON Schema fragment for the injected parameter. */
+const SUMMARY_PROPERTY = {
+	type: "string",
+	description: "Required for every tool call. A concise, specific summary (max ~8 words) of what THIS call does and why, written for a person watching the conversation, e.g. \"Searching feedback for billing complaints\" or \"Reading the auth middleware\". Address the user directly in second person: the summary is read by the user, so refer to their things as \"your\", never in third person — \"Reading your emails\", not \"Reading his emails\". Always use the present progressive tense, since it is shown while the call runs: \"Updating your Slack\", never \"Updated your Slack\". Make each summary distinct from your other tool calls; never reuse a generic label like \"Search query\" or \"Running command\"."
+};
+const jsonSchemaObjectSchema = z.object({
+	type: z.unknown().optional(),
+	properties: z.record(z.string(), z.unknown()).optional(),
+	required: z.array(z.string()).optional(),
+	additionalProperties: z.unknown().optional()
+}).passthrough();
+const toolEntrySchema = z.object({
+	name: z.string().optional(),
+	input_schema: jsonSchemaObjectSchema.optional(),
+	parameters: jsonSchemaObjectSchema.optional(),
+	function: z.object({
+		name: z.string().optional(),
+		parameters: jsonSchemaObjectSchema.optional()
+	}).passthrough().optional()
+}).passthrough();
+const payloadWithToolsSchema = z.object({ tools: z.array(z.unknown()) }).passthrough();
+/**
+* Add the summary property to one JSON Schema object. Returns the augmented
+* copy, or `null` when the tool should be left untouched: a strict schema
+* (`additionalProperties: false`) whose validation would reject the extra
+* field, or one that already declares a `__skydive_summary__` property of its own.
+*/
+function augmentSchema(schema) {
+	if (schema.additionalProperties === false) return null;
+	const properties = schema.properties ?? {};
+	if ("__skydive_summary__" in properties) return null;
+	const required = schema.required ?? [];
+	return {
+		...schema,
+		type: schema.type ?? "object",
+		properties: {
+			[TOOL_CALL_SUMMARY_FIELD]: SUMMARY_PROPERTY,
+			...properties
+		},
+		required: required.includes("__skydive_summary__") ? required : [...required, TOOL_CALL_SUMMARY_FIELD]
+	};
+}
+/**
+* Augment a single tool entry, dispatching on which provider shape it is.
+* Returns the (possibly rebuilt) entry and whether anything changed. Skipped
+* tools — wrong shape, strict, or name in `strictToolNames` — return unchanged.
+*/
+function augmentToolEntry(entry, strictToolNames) {
+	const parsed = toolEntrySchema.safeParse(entry);
+	if (!parsed.success) return {
+		entry,
+		changed: false
+	};
+	const tool = parsed.data;
+	const name = tool.name ?? tool.function?.name ?? null;
+	if (name !== null && strictToolNames.has(name)) return {
+		entry,
+		changed: false
+	};
+	if (tool.input_schema) {
+		const augmented = augmentSchema(tool.input_schema);
+		if (!augmented) return {
+			entry,
+			changed: false
+		};
+		return {
+			entry: {
+				...tool,
+				input_schema: augmented
+			},
+			changed: true
+		};
+	}
+	if (tool.parameters) {
+		const augmented = augmentSchema(tool.parameters);
+		if (!augmented) return {
+			entry,
+			changed: false
+		};
+		return {
+			entry: {
+				...tool,
+				parameters: augmented
+			},
+			changed: true
+		};
+	}
+	if (tool.function?.parameters) {
+		const augmented = augmentSchema(tool.function.parameters);
+		if (!augmented) return {
+			entry,
+			changed: false
+		};
+		return {
+			entry: {
+				...tool,
+				function: {
+					...tool.function,
+					parameters: augmented
+				}
+			},
+			changed: true
+		};
+	}
+	return {
+		entry,
+		changed: false
+	};
+}
+/**
+* Inject the summary field into every eligible tool in a provider payload.
+* Returns a new payload when at least one tool was augmented, or `undefined`
+* to signal "no change" (which keeps the original payload, per the
+* `before_provider_request` contract).
+*
+* @param payload The outgoing provider payload (shape varies by provider).
+* @param strictToolNames Names of tools whose registered schema is strict and
+*   must be skipped to avoid validation errors.
+*/
+function injectToolCallSummary(payload, strictToolNames) {
+	const parsed = payloadWithToolsSchema.safeParse(payload);
+	if (!parsed.success || parsed.data.tools.length === 0) return void 0;
+	let changed = false;
+	const tools = parsed.data.tools.map((entry) => {
+		const result = augmentToolEntry(entry, strictToolNames);
+		if (result.changed) changed = true;
+		return result.entry;
+	});
+	if (!changed) return void 0;
+	return {
+		...parsed.data,
+		tools
+	};
+}
+/**
+* Names of registered tools whose schema sets `additionalProperties: false`.
+* Pi validates the model's tool args against this registered schema, so the
+* injected field would make a strict tool's call fail validation — skip them.
+*/
+function getStrictToolNames(pi) {
+	const names = /* @__PURE__ */ new Set();
+	for (const tool of pi.getAllTools()) {
+		const parsed = jsonSchemaObjectSchema.safeParse(tool.parameters);
+		if (parsed.success && parsed.data.additionalProperties === false) names.add(tool.name);
+	}
+	return names;
+}
+/**
+* Whether a tool's own schema declares a `__skydive_summary__` property. We
+* never inject into such a tool, so any value it carries is a real argument
+* and must be left alone.
+*/
+function schemaDeclaresSummary(parameters) {
+	const parsed = jsonSchemaObjectSchema.safeParse(parameters);
+	return parsed.success && parsed.data.properties != null && "__skydive_summary__" in parsed.data.properties;
+}
+function toolDeclaresSummaryParam(pi, toolName) {
+	const tool = pi.getAllTools().find((candidate) => candidate.name === toolName);
+	if (!tool) return false;
+	return schemaDeclaresSummary(tool.parameters);
+}
+/** A copy of `args` without the injected summary. Never mutates its input. */
+function withoutInjectedSummary(args) {
+	if (args == null || typeof args !== "object" || Array.isArray(args)) return args;
+	if (!("__skydive_summary__" in args)) return args;
+	const { [TOOL_CALL_SUMMARY_FIELD]: _summary, ...rest } = args;
+	return rest;
+}
+/**
+* Register a tool so the injected summary is removed *before* pi validates
+* the model's arguments against the tool's schema.
+*
+* Needed because the `tool_call` strip below runs too late. pi-agent-core's
+* `prepareToolCall` goes: `tool.prepareArguments` → `validateToolArguments` →
+* `beforeToolCall` (which is what dispatches `tool_call`). A tool whose schema
+* sets `additionalProperties: false` therefore rejects the summary and errors
+* the call — client-side, before any request reaches the server — while the
+* strip meant to prevent exactly that sits one step further down.
+*
+* `augmentSchema` already skips strict tools, but that only controls what the
+* model is *told*. It still emits the field on those tools, because every
+* other tool in the list declares it as required for every call. So a server
+* can connect, bind its tools, present a healthy inventory, and have every
+* call fail — and it reads as the server's fault when it is ours.
+*
+* Apply to tools registered from schemas we do not author: MCP servers and
+* local `tools/*.ts`. Tools built here with `Type.Object(...)` do not need it
+* (TypeBox emits no `additionalProperties`, so the field validates fine and
+* the `tool_call` strip removes it in time).
+*
+* Fails open, like the rest of this module: if the strip throws, the original
+* arguments are used rather than failing the call.
+*/
+function withSummaryStrippedBeforeValidation(tool) {
+	if (schemaDeclaresSummary(tool.parameters)) return tool;
+	const toolPrepare = tool.prepareArguments;
+	const prepareArguments = ((args) => {
+		let stripped = args;
+		try {
+			stripped = withoutInjectedSummary(args);
+		} catch (err) {
+			log$14.error({
+				err,
+				event: "tool_call_summary_prepare_strip_failed",
+				toolName: tool.name
+			}, "tool_call_summary pre-validation strip failed; leaving arguments untouched");
+		}
+		return toolPrepare ? toolPrepare(stripped) : stripped;
+	});
+	return {
+		...tool,
+		prepareArguments
+	};
+}
+/**
+* Remove the injected summary from a tool's execution input. No-op when the
+* field is absent, or when the tool genuinely declares a `__skydive_summary__`
+* parameter of its own (which we never inject into, so its value is real).
+* Mutates `input` in place, matching the `tool_call` contract.
+*
+* Fails open: this runs on the critical path of tool execution, and the
+* `getAllTools()` lookup can throw. On any error we leave `input` untouched
+* (the sentinel may pass through to the tool, but a bug here can never break
+* tool execution).
+*/
+function stripInjectedSummary(pi, toolName, input) {
+	try {
+		if (!("__skydive_summary__" in input)) return;
+		if (toolDeclaresSummaryParam(pi, toolName)) return;
+		delete input[TOOL_CALL_SUMMARY_FIELD];
+	} catch (err) {
+		log$14.error({
+			err,
+			event: "tool_call_summary_strip_failed",
+			toolName
+		}, "tool_call_summary strip failed; leaving tool input untouched");
+	}
+}
+/**
+* Compute the rewritten payload for a `before_provider_request` event, failing
+* open: on any error the original payload is left untouched so a bug here can
+* never break an LLM call.
+*/
+function buildInjectedPayload(pi, payload) {
+	try {
+		return injectToolCallSummary(payload, getStrictToolNames(pi));
+	} catch (err) {
+		log$14.error({
+			err,
+			event: "tool_call_summary_injection_failed"
+		}, "tool_call_summary injection failed; passing payload through unchanged");
+		return;
+	}
+}
+const toolCallSummaryExtension = (pi) => {
+	pi.on("before_provider_request", (event) => buildInjectedPayload(pi, event.payload));
+	pi.on("tool_call", (event) => {
+		stripInjectedSummary(pi, event.toolName, event.input);
+	});
+};
+//#endregion
 //#region src/extensions/local-tools.ts
 /**
 * Local-tools adapter as a pi extension. Mirrors the mcp.ts hot-reload pattern
@@ -438,7 +710,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$13 = logger.child({ module: "local-tools-extension" });
 const TOOLS_DIRNAME = "tools";
 const fileState = /* @__PURE__ */ new Map();
 let pendingLocalToolsUpdate = null;
@@ -565,7 +837,7 @@ async function reconcileLocalTools({ pi, dir }) {
 			action = existing ? "refreshed" : "added";
 		}
 		for (const tool of tools) {
-			pi.registerTool(withDefaultPromptSnippet(tool));
+			pi.registerTool(withSummaryStrippedBeforeValidation(withDefaultPromptSnippet(tool)));
 			summary.totalTools++;
 		}
 		if (action === "added") summary.added.push(file);
@@ -582,7 +854,7 @@ async function reconcileAndQueue({ pi, dir, reason }) {
 		dir
 	});
 	if (reason !== "session_start" && summaryHasChanges$1(summary)) pendingLocalToolsUpdate = summary;
-	log$12.info({
+	log$13.info({
 		event: "local_tools_reconcile",
 		reason,
 		total_tools: summary.totalTools,
@@ -604,7 +876,7 @@ const localToolsExtension = (pi) => {
 				reason: "session_start"
 			});
 		} catch (err) {
-			log$12.error({
+			log$13.error({
 				err,
 				event: "local_tools_reconcile_failed"
 			}, "local tools reconcile failed");
@@ -616,7 +888,7 @@ const localToolsExtension = (pi) => {
 		try {
 			current = await listToolFiles(dir);
 		} catch (err) {
-			log$12.warn({
+			log$13.warn({
 				err,
 				event: "local_tools_listing_failed"
 			}, "tools/ listing failed");
@@ -638,7 +910,7 @@ const localToolsExtension = (pi) => {
 				reason: "auto_reload"
 			});
 		} catch (err) {
-			log$12.error({
+			log$13.error({
 				err,
 				event: "local_tools_auto_reload_failed"
 			}, "auto-reload after tools/ change failed");
@@ -692,6 +964,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,12 +998,12 @@ 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: "",
 			stderrBuffer: null,
-			cliHint: `platform auth mcp ${config.url}`
+			cliHint: `platform auth mcp ${config.url} --service "<Product>"`
 		};
 		return {
 			status: "failed",
@@ -784,6 +1069,126 @@ async function connectClient(id, config, opts = {}) {
 	};
 }
 //#endregion
+//#region src/extensions/mcp/limits.ts
+/**
+* Tool-budget guardrails for MCP registration.
+*
+* Why this exists: the agent loop sends the *full* tool list — every tool's
+* name, description, and JSON-schema `parameters` — to the model on every
+* prompt. MCP servers add tools without bound: a handful of chatty servers (or
+* one server that exposes 100+ tools, or a few tools with enormous schemas) can
+* push the registered set past what the model can accept, and the request is
+* rejected before the turn even runs. Because `reconcile` re-registers from
+* `mcp.config.json` on *every* turn, an over-limit config bricks the harness on
+* a loop — the agent can't get a turn to run in order to edit the config back
+* down. Worse, the person can't tell *why*: tools just stop working.
+*
+* What actually overflows the request is *tokens*, not tool count — a few tools
+* with deeply-nested schemas and long descriptions cost more than a hundred
+* trivial ones. And how many tokens are safe depends on the *model*: a 200K
+* context window can afford far more tool surface than a 32K one. So the primary
+* limiter is a **token budget derived from the active model's context window**,
+* with a fixed tool-count cap as a coarse secondary guard (and the fallback
+* when the model — hence its window — isn't known at reconcile time).
+*
+* The fix is to make registration bounded and fail-soft. We register in
+* deterministic config order and stop before we blow the budget, recording how
+* much we dropped so the agent is *told* it hit the limit and which servers
+* were truncated. A config that would have bricked the harness now degrades to
+* "a bounded set of tools plus a loud warning", which the agent can act on by
+* pruning servers.
+*
+* Everything is env-overridable so the ceilings can be tuned per deployment
+* without a release, but ships with conservative defaults. A cap value of 0 (or
+* a non-finite / negative override) disables that cap — an explicit escape
+* hatch, not the default.
+*/
+const env = process.env;
+/**
+* Fraction of the model's context window we're willing to spend on MCP tool
+* schemas. Tool definitions are sent on every prompt, so they permanently eat
+* into the window available for the conversation, but a generous tool budget is
+* worth more than a marginally larger conversation window given how the harness
+* is used. 0.35 of a 200K window is ~70K tokens of tool schema, comfortably
+* more than any sane MCP setup; of a 32K window it's ~11.2K, which still forces
+* truncation before a small model chokes.
+*/
+const DEFAULT_MCP_TOOL_TOKEN_BUDGET_FRACTION = .35;
+/**
+* Floor for the token budget when the model's context window is unknown at
+* reconcile time (e.g. the model hasn't been resolved yet). Generous enough not
+* to truncate an ordinary tool set, low enough to still catch a runaway.
+*/
+const DEFAULT_MCP_TOOL_TOKEN_BUDGET_FLOOR = 16e3;
+/**
+* Read a positive-integer cap from an env var, falling back to `fallback`.
+* A `0` override (or any non-finite / negative value) means "no cap" and is
+* returned as `Infinity`, so callers can compare against it directly.
+*/
+function readCap(raw, fallback) {
+	if (raw === void 0 || raw.trim() === "") return fallback;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return Number.POSITIVE_INFINITY;
+	if (parsed === 0) return Number.POSITIVE_INFINITY;
+	return Math.floor(parsed);
+}
+/** Read a fraction in (0, 1] from an env var, falling back to `fallback`. */
+function readFraction(raw, fallback) {
+	if (raw === void 0 || raw.trim() === "") return fallback;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) return fallback;
+	return parsed;
+}
+/** Read a non-negative integer from an env var, falling back to `fallback`. */
+function readNonNegativeInt(raw, fallback) {
+	if (raw === void 0 || raw.trim() === "") return fallback;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+	return Math.floor(parsed);
+}
+/**
+* Resolve the active caps from the environment. Read once per reconcile so a
+* deployment can retune without a restart, cheap enough not to cache.
+*/
+function resolveMcpToolLimits() {
+	return {
+		maxTotalTools: readCap(env["SKYDIVE_MCP_MAX_TOTAL_TOOLS"], 128),
+		maxToolsPerServer: readCap(env["SKYDIVE_MCP_MAX_TOOLS_PER_SERVER"], 50),
+		tokenBudgetFraction: readFraction(env["SKYDIVE_MCP_TOOL_TOKEN_BUDGET_FRACTION"], DEFAULT_MCP_TOOL_TOKEN_BUDGET_FRACTION),
+		tokenBudgetFloor: readNonNegativeInt(env["SKYDIVE_MCP_TOOL_TOKEN_BUDGET_FLOOR"], DEFAULT_MCP_TOOL_TOKEN_BUDGET_FLOOR)
+	};
+}
+/**
+* The token budget for MCP tool schemas, given the active model's context
+* window (or undefined when the model isn't known yet).
+*
+* With a known window we spend `tokenBudgetFraction` of it, but never less than
+* the floor — a tiny window shouldn't collapse the budget to near-zero and
+* strand every tool. With no window we fall back to the floor outright.
+*/
+function resolveTokenBudget(limits, contextWindow) {
+	if (contextWindow === void 0 || !Number.isFinite(contextWindow)) return limits.tokenBudgetFloor;
+	return Math.max(limits.tokenBudgetFloor, Math.floor(contextWindow * limits.tokenBudgetFraction));
+}
+/**
+* Estimate the tokens an MCP tool's *definition* costs in the request. We
+* serialize what's actually sent to the model — the tool name, its description,
+* and its JSON-schema parameters — and apply pi's own ~chars/4 heuristic
+* (`estimateTokens` in the coding agent uses the same convention; there is no
+* per-provider tokenizer to lean on, and the provider's real usage is only
+* known after the response). Rough by design, but it tracks the true cost far
+* better than a flat per-tool count: a fat schema is charged for its fatness.
+*/
+function estimateToolTokens(tool) {
+	let chars = tool.name.length + (tool.description?.length ?? 0);
+	if (tool.inputSchema !== void 0 && tool.inputSchema !== null) try {
+		chars += JSON.stringify(tool.inputSchema).length;
+	} catch {
+		chars += 256;
+	}
+	return Math.ceil(chars / 4);
+}
+//#endregion
 //#region src/extensions/mcp/mcp-config.ts
 /**
 * mcp.config.json schema + loader. Split out from the extension so it has
@@ -863,7 +1268,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$12 = logger.child({ module: "mcp-extension" });
 async function closeConnected(connected) {
 	try {
 		await connected.client.close();
@@ -953,7 +1358,7 @@ var McpExtension = class {
 		const parameters = Type.Unsafe(tool.inputSchema);
 		const description = tool.description?.trim() ?? "";
 		const promptSnippet = description.length > 0 ? description : `MCP tool from server "${serverId}".`;
-		pi.registerTool({
+		pi.registerTool(withSummaryStrippedBeforeValidation({
 			name,
 			label: `MCP: ${serverId}/${tool.name}`,
 			description,
@@ -987,22 +1392,29 @@ var McpExtension = class {
 					};
 				}
 			}
-		});
+		}));
 		this.registeredMcpToolNames.add(name);
 	}
-	async reconcile({ pi, configPath, connectTimeoutMs }) {
+	async reconcile({ pi, configPath, connectTimeoutMs, contextWindow }) {
 		let config;
 		try {
 			config = await loadMcpConfig(configPath);
 		} catch (err) {
 			throw new Error(`Failed to load MCP config: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		const limits = resolveMcpToolLimits();
+		const tokenBudget = resolveTokenBudget(limits, contextWindow);
 		const summary = {
 			added: [],
 			removed: [],
 			refreshed: [],
 			errors: [],
 			totalTools: 0,
+			droppedTools: 0,
+			limits,
+			tokenBudget,
+			tokensUsed: 0,
+			toolCounts: {},
 			servers: {}
 		};
 		const desiredIds = new Set(Object.keys(config.servers));
@@ -1026,14 +1438,46 @@ var McpExtension = class {
 			if (outcome.error) summary.errors.push(outcome.error);
 			if (outcome.change === "added") summary.added.push(id);
 			else if (outcome.change === "refreshed") summary.refreshed.push(id);
-			if (outcome.tools) for (const tool of outcome.tools.list) {
-				this.registerMcpTool({
-					pi,
-					serverId: id,
-					client: outcome.tools.client,
-					tool
-				});
-				summary.totalTools++;
+			if (outcome.tools) {
+				const advertised = outcome.tools.list.length;
+				const perServerRoom = Math.min(advertised, limits.maxToolsPerServer);
+				let registered = 0;
+				let serverTokens = 0;
+				let droppedReason = null;
+				for (const tool of outcome.tools.list) {
+					if (summary.totalTools >= limits.maxTotalTools) {
+						droppedReason = "total";
+						break;
+					}
+					if (registered >= perServerRoom) {
+						droppedReason = "per_server";
+						break;
+					}
+					const cost = estimateToolTokens(tool);
+					if (summary.tokensUsed + cost > tokenBudget && summary.totalTools > 0) {
+						droppedReason = "tokens";
+						break;
+					}
+					this.registerMcpTool({
+						pi,
+						serverId: id,
+						client: outcome.tools.client,
+						tool
+					});
+					registered++;
+					serverTokens += cost;
+					summary.totalTools++;
+					summary.tokensUsed += cost;
+				}
+				const dropped = advertised - registered;
+				if (dropped > 0) summary.droppedTools += dropped;
+				else droppedReason = null;
+				summary.toolCounts[id] = {
+					advertised,
+					registered,
+					tokens: serverTokens,
+					droppedReason
+				};
 			}
 		}
 		return summary;
@@ -1190,6 +1634,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 {
@@ -1220,17 +1722,21 @@ var McpExtension = class {
 			}
 		};
 	}
-	async reconcileAndRecordMtime({ pi, configPath, reason }) {
+	async reconcileAndRecordMtime({ pi, configPath, reason, contextWindow }) {
 		const summary = await this.reconcile({
 			pi,
-			configPath
+			configPath,
+			contextWindow
 		});
 		this.lastConfigMtimeMs = await readConfigMtimeMs(configPath);
 		if (reason !== "session_start" && summaryHasChanges(summary)) this.pendingMcpUpdate = summary;
-		log$11.info({
+		log$12.info({
 			event: "mcp_reconcile",
 			reason,
 			total_tools: summary.totalTools,
+			tokens_used: summary.tokensUsed,
+			token_budget: summary.tokenBudget,
+			dropped_tools: summary.droppedTools,
 			added: summary.added,
 			removed: summary.removed,
 			refreshed: summary.refreshed,
@@ -1247,10 +1753,11 @@ var McpExtension = class {
 					await this.reconcileAndRecordMtime({
 						pi,
 						configPath,
-						reason: "session_start"
+						reason: "session_start",
+						contextWindow: ctx.model?.contextWindow
 					});
 				} catch (err) {
-					log$11.error({
+					log$12.error({
 						err,
 						event: "mcp_reconcile_failed"
 					}, "MCP reconcile failed");
@@ -1262,7 +1769,7 @@ var McpExtension = class {
 				try {
 					mtime = await readConfigMtimeMs(configPath);
 				} catch (err) {
-					log$11.warn({
+					log$12.warn({
 						err,
 						event: "mcp_mtime_check_failed"
 					}, "mtime check on mcp.config.json failed");
@@ -1273,10 +1780,11 @@ var McpExtension = class {
 					await this.reconcileAndRecordMtime({
 						pi,
 						configPath,
-						reason: "auto_reload"
+						reason: "auto_reload",
+						contextWindow: ctx.model?.contextWindow
 					});
 				} catch (err) {
-					log$11.error({
+					log$12.error({
 						err,
 						event: "mcp_auto_reload_failed"
 					}, "auto-reload after mcp.config.json change failed");
@@ -1293,7 +1801,8 @@ var McpExtension = class {
 						const summary = await this.reconcileAndRecordMtime({
 							pi,
 							configPath,
-							reason: "tool"
+							reason: "tool",
+							contextWindow: ctx.model?.contextWindow
 						});
 						return {
 							content: [{
@@ -1352,9 +1861,29 @@ function appendStderrBlock(lines, stderr) {
 	for (const line of stderr.trimEnd().split("\n")) lines.push(`    ${line}`);
 	lines.push("    ---");
 }
+/**
+* Human-readable lines describing any budget-driven truncation, shared by
+* `summaryText` (the reload_mcp tool output) and `formatMcpUpdateMessage` (the
+* synthetic continuation). Empty when nothing was dropped.
+*/
+function truncationLines(summary) {
+	if (summary.droppedTools <= 0) return [];
+	const lines = [];
+	const { maxTotalTools, maxToolsPerServer } = summary.limits;
+	const totalCapHint = Number.isFinite(maxTotalTools) ? `${maxTotalTools}` : "unlimited";
+	lines.push(`  WARNING: ${summary.droppedTools} MCP tool(s) were NOT registered because a tool budget was hit (token budget: ~${summary.tokenBudget} tokens, used ~${summary.tokensUsed}; total-tool cap: ${totalCapHint}, per-server cap: ${Number.isFinite(maxToolsPerServer) ? maxToolsPerServer : "unlimited"}).`);
+	lines.push("  Tool definitions are sent to the model on every prompt; too many (or too-large) tool schemas push the request over the limit, so they are budgeted against the model context window. Prune servers from mcp.config.json to bring the tool surface down.");
+	for (const [id, count] of Object.entries(summary.toolCounts)) {
+		if (count.droppedReason === null) continue;
+		const why = count.droppedReason === "tokens" ? "token budget exhausted" : count.droppedReason === "total" ? "total-tool cap reached" : "per-server cap";
+		lines.push(`    - ${id}: registered ${count.registered}/${count.advertised} tools (~${count.tokens} tokens, ${why}).`);
+	}
+	return lines;
+}
 function summaryText(summary) {
 	const lines = [];
 	lines.push(`MCP reconcile complete: ${summary.totalTools} tool(s) live.`);
+	lines.push(...truncationLines(summary));
 	if (summary.added.length > 0) lines.push(`  Added: ${summary.added.join(", ")}`);
 	if (summary.refreshed.length > 0) lines.push(`  Refreshed: ${summary.refreshed.join(", ")}`);
 	if (summary.removed.length > 0) lines.push(`  Removed: ${summary.removed.join(", ")}`);
@@ -1380,7 +1909,7 @@ function summaryText(summary) {
 	return lines.join("\n");
 }
 function summaryHasChanges(summary) {
-	return summary.added.length > 0 || summary.removed.length > 0 || summary.refreshed.length > 0 || summary.errors.length > 0;
+	return summary.added.length > 0 || summary.removed.length > 0 || summary.refreshed.length > 0 || summary.errors.length > 0 || summary.droppedTools > 0;
 }
 /**
 * Format a queued tool-update as a synthetic system-style message for
@@ -1393,6 +1922,10 @@ function formatMcpUpdateMessage(summary) {
 	if (summary.added.length > 0) lines.push(`Newly available servers: ${summary.added.join(", ")}`);
 	if (summary.refreshed.length > 0) lines.push(`Refreshed servers: ${summary.refreshed.join(", ")}`);
 	if (summary.removed.length > 0) lines.push(`Removed servers (and their tools): ${summary.removed.join(", ")}`);
+	if (summary.droppedTools > 0) {
+		lines.push("");
+		lines.push(...truncationLines(summary));
+	}
 	const pending = pendingAuthEntries(summary);
 	if (pending.length > 0) {
 		lines.push("");
@@ -1639,16 +2172,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$11 = 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$11.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$11.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$10 = 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$10.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,20 +2577,84 @@ 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;
 const DAEMON_URL = "http://localhost:38994";
-const log$10 = logger.child({ module: "platform-ext" });
+const log$9 = logger.child({ module: "platform-ext" });
 function sandboxClient() {
 	const apiUrl = apiBaseUrl();
 	if (!apiUrl) return null;
 	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,22 +2662,19 @@ 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) {
-			log$10.debug({
+			log$9.debug({
 				status: res.status,
 				event: "feature_flags_fetch_failed"
 			}, "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({
+		log$9.debug({
 			err,
 			event: "feature_flags_fetch_error"
 		}, "feature-flags request errored");
@@ -1727,7 +2685,7 @@ function postHeartbeat({ messageId }) {
 	const client = sandboxClient();
 	if (!client) return;
 	client.heartbeat.$post({ json: { messageId } }).catch((err) => {
-		log$10.debug({
+		log$9.debug({
 			err,
 			event: "heartbeat_failed"
 		}, "heartbeat failed");
@@ -1739,7 +2697,7 @@ async function resolveConversationFromApi(messageId) {
 	try {
 		const res = await client["message-conversation"].$get({ query: { messageId } });
 		if (!res.ok) {
-			log$10.warn({
+			log$9.warn({
 				status: res.status,
 				messageId,
 				event: "resolve_conversation_failed"
@@ -1748,7 +2706,7 @@ async function resolveConversationFromApi(messageId) {
 		}
 		return (await res.json()).conversationId ?? null;
 	} catch (err) {
-		log$10.warn({
+		log$9.warn({
 			err,
 			messageId,
 			event: "resolve_conversation_error"
@@ -1765,6 +2723,71 @@ async function postBackgroundTaskDone({ messageId, content }) {
 	} });
 	if (!res.ok) throw new Error(`bg-task-done POST failed: ${res.status}`);
 }
+async function putBackgroundTaskJournalSpec({ messageId, spec }) {
+	const client = sandboxClient();
+	if (!client) return;
+	try {
+		const res = await client["bg-task-journal"].$put({ json: {
+			messageId,
+			spec
+		} });
+		if (!res.ok) log$9.warn({
+			status: res.status,
+			taskId: spec.id,
+			event: "bg_journal_put_failed"
+		}, "bg-task journal PUT failed");
+	} catch (err) {
+		log$9.warn({
+			err,
+			taskId: spec.id,
+			event: "bg_journal_put_failed"
+		}, "bg-task journal PUT threw");
+	}
+}
+async function deleteBackgroundTaskJournalSpec({ messageId, taskId }) {
+	const client = sandboxClient();
+	if (!client) return;
+	try {
+		await client["bg-task-journal"].$delete({ json: {
+			messageId,
+			taskId
+		} });
+	} catch (err) {
+		log$9.debug({
+			err,
+			taskId,
+			event: "bg_journal_delete_failed"
+		}, "bg-task journal DELETE failed");
+	}
+}
+async function listBackgroundTaskJournalSpecs({ messageId }) {
+	const client = sandboxClient();
+	if (!client) return [];
+	try {
+		const res = await client["bg-task-journal"].$get({ query: { messageId } });
+		if (!res.ok) return [];
+		return (await res.json()).specs ?? [];
+	} catch (err) {
+		log$9.debug({
+			err,
+			event: "bg_journal_list_failed"
+		}, "bg-task journal GET failed");
+		return [];
+	}
+}
+function postBackgroundTasksSnapshot({ messageId, tasks }) {
+	const client = sandboxClient();
+	if (!client || !messageId) return;
+	client["bg-tasks"].$post({ json: {
+		messageId,
+		tasks
+	} }).catch((err) => {
+		log$9.debug({
+			err,
+			event: "bg_tasks_snapshot_failed"
+		}, "bg-tasks snapshot publish failed");
+	});
+}
 async function postSubagentSpawn({ messageId, tasks }) {
 	const client = sandboxClient();
 	if (!client) throw new Error("no api url for subagent-spawn");
@@ -1772,8 +2795,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;
@@ -1822,7 +2856,7 @@ function createToolHeartbeat({ messageId }) {
 			}
 			heartbeatCount++;
 			if (heartbeatCount > MAX_TOOL_HEARTBEATS) {
-				log$10.warn({
+				log$9.warn({
 					heartbeatCount,
 					activeToolCalls: [...activeToolCalls]
 				}, "tool heartbeat max reached, stopping");
@@ -1853,7 +2887,7 @@ function postToDaemon(path, body) {
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify(body)
 	}).catch((err) => {
-		log$10.debug({
+		log$9.debug({
 			err,
 			path,
 			event: "daemon_post_failed"
@@ -1862,7 +2896,7 @@ function postToDaemon(path, body) {
 }
 function createPlatformExtensions({ sessionId, channelContext }) {
 	return (pi) => {
-		log$10.info({
+		log$9.info({
 			sessionId,
 			hasChannelContext: Boolean(channelContext)
 		}, "platform extension initialized");
@@ -1911,7 +2945,7 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 			});
 		});
 		pi.on("agent_end", () => {
-			log$10.info({ sessionId }, "session ending");
+			log$9.info({ sessionId }, "session ending");
 			postToDaemon("/session/end", { sessionId });
 		});
 	};
@@ -1922,37 +2956,29 @@ 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
 * last-known values untouched so a blip can't silently flip behavior.
 */
-const log$9 = logger.child({ module: "feature-flags-poll" });
+const log$8 = 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 +2987,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,13 +3001,12 @@ 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) {
-		log$9.warn({
+		log$8.warn({
 			err,
 			flag: name
 		}, "flag subscriber threw");
@@ -2004,9 +3017,8 @@ 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");
+		log$8.debug({ err }, "feature-flag poll threw");
 	}
 }
 /**
@@ -2113,7 +3125,7 @@ function transformContextMessages(messages, config, now) {
 }
 //#endregion
 //#region src/extensions/context-management.ts
-const log$8 = logger.child({ module: "context-management-extension" });
+const log$7 = logger.child({ module: "context-management-extension" });
 function isAnthropicMessagesPayload(payload) {
 	if (typeof payload !== "object" || payload === null) return false;
 	const candidate = payload;
@@ -2178,13 +3190,13 @@ function createContextManagementExtension() {
 		setContextManagementFlagOverride(getPolledFlag("contextManagement"));
 		onFlagChange("contextManagement", (enabled) => {
 			setContextManagementFlagOverride(enabled);
-			log$8.info({
+			log$7.info({
 				event: "context_management_flag_update",
 				enabled
 			}, "context-management flag updated from platform");
 		});
 		startFeatureFlagPoller();
-		log$8.info({
+		log$7.info({
 			event: "context_management_registered",
 			enabled: initial.enabled,
 			flagSource: hasFlagSource(),
@@ -2196,13 +3208,13 @@ function createContextManagementExtension() {
 			const { messages } = event;
 			try {
 				const result = transformContextIfEnabled(messages, getContextManagementConfig(), Date.now());
-				if (result.stats && (result.stats.clearedResults > 0 || result.stats.trimmedResults > 0)) log$8.info({
+				if (result.stats && (result.stats.clearedResults > 0 || result.stats.trimmedResults > 0)) log$7.info({
 					event: "context_management_applied",
 					...result.stats
 				}, "trimmed/cleared tool output before LLM call");
 				return { messages: result.messages };
 			} catch (err) {
-				log$8.error({
+				log$7.error({
 					err,
 					event: "context_management_transform_failed"
 				}, "context transform failed; passing messages through unchanged");
@@ -2214,7 +3226,7 @@ function createContextManagementExtension() {
 }
 //#endregion
 //#region src/extensions/current-time.ts
-const log$7 = logger.child({ module: "current-time-extension" });
+const log$6 = logger.child({ module: "current-time-extension" });
 const PI_DATE_LINE = /^Current date:.*$/m;
 function formatCurrentTimeLine(now) {
 	return `Current date: ${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}-${String(now.getUTCDate()).padStart(2, "0")} (${new Intl.DateTimeFormat("en-US", {
@@ -2227,7 +3239,7 @@ const currentTimeExtension = (pi) => {
 		const line = formatCurrentTimeLine(/* @__PURE__ */ new Date());
 		const base = event.systemPrompt;
 		if (PI_DATE_LINE.test(base)) {
-			log$7.info({ event: "pi_date_line_present" }, "pi base prompt carries its own 'Current date:' line again; replacing it in place (pi prompt format may have changed)");
+			log$6.info({ event: "pi_date_line_present" }, "pi base prompt carries its own 'Current date:' line again; replacing it in place (pi prompt format may have changed)");
 			return { systemPrompt: base.replace(PI_DATE_LINE, line) };
 		}
 		return { systemPrompt: `${base}\n${line}` };
@@ -2236,37 +3248,35 @@ const currentTimeExtension = (pi) => {
 //#endregion
 //#region src/memory.ts
 /**
-* In-harness memory index builder.
+* In-harness memory readers.
 *
-* The agent has an agent-level file-based memory at `<cwd>/.memory/`,
-* organized by directory:
+* The agent has an agent-level file-based memory at `<cwd>/.memory/`, split
+* into two halves that are surfaced differently:
 *
-*   .memory/users/<id>-<name>/<topic>.md
-*   .memory/projects/<project_slug>/<topic>.md
-*   .memory/feedback/<topic>.md
-*   .memory/reference/<topic>.md
+* 1. Shared knowledge (projects, lessons, external systems) — indexed by a
+*    single hand-maintained `<cwd>/.memory/MEMORY.md` that the *agent* writes
+*    and curates, Claude-Code style: one line per fact pointing at the file
+*    that holds it. `readMemoryIndexFile` just reads that file; the agent owns
+*    its contents. This is the whole index for the shared half — there is no
+*    derived walk and no per-directory `MEMORY.md`.
 *
-* The path encodes type and subject (for `users/`, the subject is the
-* person's stable id with a readable name suffix); each `.md` file's
-* frontmatter only carries `name` and `description`.
+* 2. Per-person memory — `.memory/users/<id>-<name>/<topic>.md`. This half is
+*    *derived*, not hand-maintained, because it has to be filtered to the one
+*    person on the current turn (a single hand-written index couldn't be
+*    scoped per-user without leaking one person's notes into another's
+*    conversation). `buildMemoryIndex` walks a single user's directory, reads
+*    only the frontmatter of each `.md` (open fd → read first ~4KB → close, in
+*    parallel), and renders an index. Each `.md`'s frontmatter carries `name`
+*    and `description`; bodies are never read — the agent loads a specific
+*    memory's body on demand via the `read` tool.
 *
-* `buildMemoryIndex` walks `.memory/` by type directory, reads only the
-* frontmatter of each `.md` (open fd → read first ~4KB → close, in
-* parallel), and renders a markdown index grouped by type and (where
-* applicable) by subject. Files outside the four type directories are
-* ignored. Bodies are never read — the agent loads a specific memory's
-* body on demand via the `read` tool when the index entry says it's
-* relevant.
+* Mtime cache (for the derived per-user half) keyed by cwd — within the
+* lifetime of a sandbox the cwd is fixed, so this is effectively a single-entry
+* cache. It invalidates when any `.md` under `users/` is added/modified/
+* deleted; turns where memory didn't change reuse the cached entries.
 *
-* Mtime cache keyed by cwd — within the lifetime of a sandbox the cwd
-* is fixed, so this is effectively a single-entry cache. Cache invalidates
-* when any `.md` in the tree is added/modified/deleted; turns where
-* memory didn't change reuse the cached string.
-*
-* Frontmatter is parsed as YAML (`yaml` package) and validated with a
-* zod schema — files that don't match the shape are dropped from the
-* index. The same schema can be reused at write time if we want to
-* validate before commit.
+* Frontmatter is parsed as YAML (`yaml` package) and validated with a zod
+* schema — files that don't match the shape are dropped from the index.
 */
 const FRONTMATTER_READ_BYTES = 4096;
 const FrontmatterSchema = z.object({
@@ -2274,33 +3284,118 @@ const FrontmatterSchema = z.object({
 	description: z.string().min(1)
 }).passthrough();
 const MEMORY_DIRNAME = ".memory";
-const TYPE_DIRS = [
-	"users",
-	"projects",
-	"feedback",
-	"reference"
+const MEMORY_INDEX_FILENAME = "MEMORY.md";
+const USERS_DIRNAME = "users";
+/**
+* The shared-knowledge type dirs from the old frontmatter-indexed layout, used
+* only to seed a `MEMORY.md` for agents created before it existed (see
+* `seedMemoryIndexFile`). `users/` is deliberately excluded — per-person memory
+* stays derived and never lands in the shared, un-scoped `MEMORY.md`.
+*/
+const LEGACY_SHARED_TYPES = [
+	{
+		dir: "projects",
+		label: "Projects"
+	},
+	{
+		dir: "feedback",
+		label: "Feedback"
+	},
+	{
+		dir: "reference",
+		label: "Reference"
+	}
 ];
-const TYPES_WITH_SUBJECT = new Set(["users", "projects"]);
-const TYPE_LABELS = {
-	users: "Users",
-	projects: "Projects",
-	feedback: "Feedback",
-	reference: "Reference"
-};
+/**
+* Soft budget for an injected index block. The index is read and injected into
+* the system prompt on every turn, so every entry costs context for the rest of
+* the conversation. Past this size we nudge the agent to consolidate and prune
+* rather than keep appending. Not a hard cap — nothing is truncated.
+*/
+const MEMORY_INDEX_SOFT_BUDGET_CHARS = 2e4;
+/**
+* Hard cap on the injected index — double the soft budget. The soft budget only
+* warns; this actually bounds what we inject so a runaway index can't consume
+* unbounded context on every turn. Past this, the index is truncated (on a line
+* boundary) before injection. It's a backstop, not a normal operating point.
+*/
+const MEMORY_INDEX_HARD_BUDGET_CHARS = MEMORY_INDEX_SOFT_BUDGET_CHARS * 2;
+/**
+* Cheap size summary of a rendered index block, used to surface how much of the
+* every-turn context budget the index is spending so the agent keeps it lean.
+* Counts pointer/file lines — both the derived `` - `path` — desc`` form and
+* the hand-maintained `- [Title](path) — hook` form — not the group headers.
+*/
+function summarizeIndex(index) {
+	const entryCount = index.split("\n").filter((line) => /^\s*- (?:`|\[)/.test(line)).length;
+	const charCount = index.length;
+	return {
+		entryCount,
+		charCount,
+		overBudget: charCount > MEMORY_INDEX_SOFT_BUDGET_CHARS
+	};
+}
+/**
+* One-line size note for an index block header, e.g. `12 entries, 3187 chars`.
+*/
+function indexSizeNote(index) {
+	const { entryCount, charCount } = summarizeIndex(index);
+	return `${entryCount} ${entryCount === 1 ? "entry" : "entries"}, ${charCount} chars`;
+}
+/**
+* An explicit warning to surface to the agent when an index has grown past its
+* budget, or `null` when it's within budget. Extensions render this prominently
+* above the index so the agent prunes before it keeps appending.
+*/
+function indexBudgetWarning(index) {
+	const { charCount, overBudget } = summarizeIndex(index);
+	if (!overBudget) return null;
+	return `⚠️ This memory index is ${charCount} chars, over its ${MEMORY_INDEX_SOFT_BUDGET_CHARS}-char budget. It's costing you context on every turn — consolidate duplicate entries and delete stale ones to bring it back under budget before adding anything new.`;
+}
+/**
+* Enforce the hard cap on an index before injection. Under the cap the index is
+* returned unchanged; over it, the index is truncated on a line boundary and a
+* notice is appended naming the true size so the agent knows entries are hidden
+* and must be pruned. This is the actual bound on injected context — callers
+* still report the true size via {@link indexSizeNote} so nothing is masked.
+*/
+function enforceMemoryIndexHardBudget(index) {
+	if (index.length <= 4e4) return index;
+	const clipped = index.slice(0, MEMORY_INDEX_HARD_BUDGET_CHARS);
+	const lastNewline = clipped.lastIndexOf("\n");
+	return `${lastNewline > 0 ? clipped.slice(0, lastNewline) : clipped}\n\n⚠️ Memory index truncated at ${MEMORY_INDEX_HARD_BUDGET_CHARS} chars (it is ${index.length}). Entries past this point are NOT shown. Prune the index now — delete stale entries and consolidate duplicates.`;
+}
+/**
+* Read the agent's hand-maintained shared index at `.memory/MEMORY.md`.
+* Returns the trimmed contents, or `null` when the file is absent or empty —
+* the agent owns this file, so we surface exactly what it wrote.
+*/
+async function readMemoryIndexFile({ cwd }) {
+	const path = join(cwd, MEMORY_DIRNAME, MEMORY_INDEX_FILENAME);
+	try {
+		const trimmed = (await readFile(path, "utf-8")).trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch {
+		return null;
+	}
+}
 const cache = /* @__PURE__ */ new Map();
 /**
+* Build the derived per-person index for a single user.
+*
 * Returns:
-* - `null` if `.memory/` doesn't exist
-* - `""` if the dir exists but contains nothing in the requested scope
+* - `null` if `.memory/users/` doesn't exist
+* - `""` if it exists but this user has no memory
 * - rendered markdown body (no surrounding header — caller wraps)
 *
-* The mtime-keyed cache stores the raw walked entries (the cost is the FS
-* walk); filtering by scope is cheap and runs per call, so two turns with
-* different scopes on the same cwd render correctly from one cached walk.
+* Scoping by id keeps one person's memory from bleeding into another's
+* conversation. The mtime-keyed cache stores the raw walked entries (the cost
+* is the FS walk); filtering by user is cheap and runs per call, so two turns
+* with different users on the same cwd render correctly from one cached walk.
 */
-async function buildMemoryIndex({ cwd, scope }) {
-	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
-	const maxMtimeMs = await maxMtimeAcrossDir(memoryDirAbs);
+async function buildMemoryIndex({ cwd, userId }) {
+	const usersDirAbs = join(cwd, MEMORY_DIRNAME, USERS_DIRNAME);
+	const maxMtimeMs = await maxMtimeAcrossDir(usersDirAbs);
 	if (maxMtimeMs === null) {
 		cache.delete(cwd);
 		return null;
@@ -2308,13 +3403,13 @@ async function buildMemoryIndex({ cwd, scope }) {
 	let cached = cache.get(cwd);
 	if (!cached || cached.builtAtMs < maxMtimeMs) {
 		cached = {
-			entries: await collectEntries(memoryDirAbs, cwd),
+			entries: await collectUserEntries(usersDirAbs, cwd),
 			builtAtMs: Date.now()
 		};
 		cache.set(cwd, cached);
 	}
-	const visible = cached.entries.filter((entry) => scope.kind === "user" ? entry.type === "users" && entry.subject?.startsWith(scope.userId) === true : entry.type !== "users");
-	return visible.length === 0 ? "" : renderIndex(visible);
+	const visible = cached.entries.filter((entry) => entry.subject.startsWith(userId));
+	return visible.length === 0 ? "" : renderUserIndex(visible);
 }
 async function maxMtimeAcrossDir(dir) {
 	let dirStat;
@@ -2362,45 +3457,22 @@ async function listSubdirs(dir) {
 	}
 	return entries.filter((e) => e.isDirectory()).map((e) => join(dir, e.name));
 }
-async function collectEntries(rootDirAbs, cwd) {
-	const collected = [];
-	await Promise.all(TYPE_DIRS.map(async (type) => {
-		const typeDirAbs = join(rootDirAbs, type);
-		if (TYPES_WITH_SUBJECT.has(type)) {
-			const subjectDirs = await listSubdirs(typeDirAbs);
-			await Promise.all(subjectDirs.map(async (subjectDirAbs) => {
-				const subject = basename(subjectDirAbs);
-				const files = await listMdFilesShallow(subjectDirAbs);
-				const parsed = await Promise.all(files.map(async (file) => {
-					const fm = await readFrontmatterOnly(file);
-					if (!fm?.name || !fm?.description) return null;
-					return {
-						name: fm.name,
-						description: fm.description,
-						type,
-						subject,
-						relPath: relative(cwd, file)
-					};
-				}));
-				for (const e of parsed) if (e) collected.push(e);
-			}));
-		} else {
-			const files = await listMdFilesShallow(typeDirAbs);
-			const parsed = await Promise.all(files.map(async (file) => {
-				const fm = await readFrontmatterOnly(file);
-				if (!fm?.name || !fm?.description) return null;
-				return {
-					name: fm.name,
-					description: fm.description,
-					type,
-					subject: null,
-					relPath: relative(cwd, file)
-				};
-			}));
-			for (const e of parsed) if (e) collected.push(e);
-		}
-	}));
-	return collected;
+async function collectUserEntries(usersDirAbs, cwd) {
+	const subjectDirs = await listSubdirs(usersDirAbs);
+	return (await Promise.all(subjectDirs.map(async (subjectDirAbs) => {
+		const subject = basename(subjectDirAbs);
+		const files = await listMdFilesShallow(subjectDirAbs);
+		return (await Promise.all(files.map(async (file) => {
+			const fm = await readFrontmatterOnly(file);
+			if (!fm?.name || !fm?.description) return null;
+			return {
+				name: fm.name,
+				description: fm.description,
+				subject,
+				relPath: relative(cwd, file)
+			};
+		}))).filter((e) => e !== null);
+	}))).flat();
 }
 async function readFrontmatterOnly(filePath) {
 	let fh;
@@ -2431,77 +3503,189 @@ function parseFrontmatter(text) {
 	const result = FrontmatterSchema.safeParse(parsed);
 	return result.success ? result.data : null;
 }
-function renderIndex(entries) {
-	const byType = {
-		users: [],
-		projects: [],
-		feedback: [],
-		reference: []
-	};
-	for (const e of entries) byType[e.type].push(e);
+function renderUserIndex(entries) {
+	const bySubject = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const list = bySubject.get(e.subject) ?? [];
+		list.push(e);
+		bySubject.set(e.subject, list);
+	}
+	const lines = ["### Users"];
+	for (const subject of [...bySubject.keys()].sort()) {
+		lines.push(`- **${subject}**`);
+		for (const e of bySubject.get(subject) ?? []) lines.push(`  - \`${e.relPath}\` — ${e.description}`);
+	}
+	return lines.join("\n");
+}
+/**
+* One-time migration for agents created before `MEMORY.md` existed. If there is
+* no hand-maintained `.memory/MEMORY.md` yet but the agent has shared memory
+* files from the old frontmatter-indexed layout (`projects/`, `feedback/`,
+* `reference/`), derive a `MEMORY.md` from their frontmatter and write it once.
+* After that the agent owns the file — this never runs again for that agent and
+* never clobbers an existing index.
+*
+* Returns the seeded contents (also written to disk), or `null` when nothing
+* was seeded (index already present, or no legacy shared files). A write
+* failure propagates so the caller can log it; the read path then falls back to
+* whatever is on disk.
+*/
+async function seedMemoryIndexFile({ cwd }) {
+	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
+	const indexPath = join(memoryDirAbs, MEMORY_INDEX_FILENAME);
+	if (await stat(indexPath).catch(() => null)) return null;
+	const perType = await Promise.all(LEGACY_SHARED_TYPES.map(async ({ dir, label }) => {
+		const typeDirAbs = join(memoryDirAbs, dir);
+		const files = [];
+		await walkMdFiles(typeDirAbs, files);
+		return {
+			label,
+			entries: (await Promise.all(files.map(async (file) => {
+				const fm = await readFrontmatterOnly(file);
+				if (!fm?.name || !fm?.description) return null;
+				return {
+					name: fm.name,
+					description: fm.description,
+					relPath: relative(cwd, file)
+				};
+			}))).filter((e) => !!e)
+		};
+	}));
+	if (perType.every((group) => group.entries.length === 0)) return null;
+	const content = renderSeededIndex(perType);
+	await writeFile(indexPath, `${content}\n`, "utf-8");
+	return content;
+}
+function renderSeededIndex(groups) {
 	const sections = [];
-	for (const type of TYPE_DIRS) {
-		const items = byType[type];
-		if (items.length === 0) continue;
-		sections.push(`### ${TYPE_LABELS[type]}`);
-		if (TYPES_WITH_SUBJECT.has(type)) {
-			const bySubject = /* @__PURE__ */ new Map();
-			for (const e of items) {
-				const subject = e.subject ?? "(unknown)";
-				const list = bySubject.get(subject) ?? [];
-				list.push(e);
-				bySubject.set(subject, list);
-			}
-			const subjects = [...bySubject.keys()].sort();
-			for (const subject of subjects) {
-				sections.push(`- **${subject}**`);
-				for (const e of bySubject.get(subject) ?? []) sections.push(`  - \`${e.relPath}\` — ${e.description}`);
-			}
-		} else for (const e of items) sections.push(`- \`${e.relPath}\` — ${e.description}`);
+	for (const { label, entries } of groups) {
+		if (entries.length === 0) continue;
+		sections.push(`### ${label}`);
+		const sorted = [...entries].sort((a, b) => a.relPath.localeCompare(b.relPath));
+		for (const e of sorted) sections.push(`- [${e.name}](${e.relPath}) — ${e.description}`);
 		sections.push("");
 	}
 	return sections.join("\n").trimEnd();
 }
+/**
+* The version at which the hand-maintained `MEMORY.md` layout was introduced.
+* Used to classify an unversioned `.memory/`: if it already has a `MEMORY.md`
+* it's on this layout (not the pre-MEMORY.md v1 frontmatter layout), so it
+* shouldn't be treated as v1 and re-seeded.
+*/
+const HAND_MAINTAINED_INDEX_VERSION = 2;
+const VERSION_FILENAME = ".version";
+const MEMORY_MIGRATIONS = [{
+	from: 1,
+	to: 2,
+	apply: async ({ cwd }) => {
+		await seedMemoryIndexFile({ cwd });
+	}
+}];
+/**
+* The layout version of an agent's `.memory/`:
+* - `null` when there's no `.memory/` at all (a fresh agent is current by
+*   construction; nothing to migrate).
+* - `1` when `.memory/` exists but carries no `.version` marker — i.e. it
+*   predates versioning.
+* - otherwise the integer in `.memory/.version`.
+*/
+async function readMemoryVersion(cwd) {
+	const memoryDirAbs = join(cwd, MEMORY_DIRNAME);
+	if (!(await stat(memoryDirAbs).catch(() => null))?.isDirectory()) return null;
+	const raw = await readFile(join(memoryDirAbs, VERSION_FILENAME), "utf-8").catch(() => null);
+	if (raw === null) return await stat(join(memoryDirAbs, MEMORY_INDEX_FILENAME)).then((s) => s.isFile()).catch(() => false) ? HAND_MAINTAINED_INDEX_VERSION : 1;
+	const parsed = Number.parseInt(raw.trim(), 10);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
+}
+async function writeMemoryVersion(cwd, version) {
+	await writeFile(join(cwd, MEMORY_DIRNAME, VERSION_FILENAME), `${version}\n`, "utf-8");
+}
+/**
+* Bring an agent's `.memory/` up to `CURRENT_MEMORY_VERSION` by applying the
+* ordered migrations. Runs on session start. No-op when there's no `.memory/`
+* yet or it's already current. Migrations must be idempotent, so a lost/unwritten
+* version marker (the file isn't committed by the harness) only costs a repeated
+* no-op, never corruption. Returns the `{ from, to }` actually applied, or
+* `null` when nothing ran.
+*/
+async function migrateMemory({ cwd }) {
+	const from = await readMemoryVersion(cwd);
+	if (from === null || from >= 2) return null;
+	let version = from;
+	while (version < 2) {
+		const migration = MEMORY_MIGRATIONS.find((m) => m.from === version);
+		if (!migration) break;
+		await migration.apply({ cwd });
+		version = migration.to;
+	}
+	await writeMemoryVersion(cwd, version);
+	return {
+		from,
+		to: version
+	};
+}
 //#endregion
 //#region src/extensions/memory.ts
-const log$6 = logger.child({ module: "memory-extension" });
+const log$5 = logger.child({ module: "memory-extension" });
 /**
 * The standing instructions for the memory system. Always injected (even with
-* an empty `.memory/`) so the agent knows it can persist notes. `users/` is
+* no `MEMORY.md`) so the agent knows it can persist notes and how. `users/` is
 * described by the platform memory extension, which is the only thing that can
 * scope it to a person — here we just point at it.
 */
 function memoryInstructions(cwd) {
 	return `## Memory across conversations
 
-Persistent notes across conversations live at \`${cwd}/.memory/\` — plain markdown files in your repo. The harness builds and injects an **index** of these files (paths + one-line descriptions) into your system prompt every turn; **bodies are NOT auto-loaded** — when an index entry looks relevant, use your \`read\` tool to load that specific file.
+Persistent notes across conversations live at \`${cwd}/.memory/\` — plain markdown files in your repo, one fact per file. You maintain a hand-written index of them at \`${cwd}/.memory/MEMORY.md\`, and the harness injects that index into your system prompt every turn. **Bodies are NOT auto-loaded** — when an index line looks relevant, use your \`read\` tool to load that specific file.
 
 Memory records **what happened**: facts you learned, events, investigation findings, project and system details worth carrying forward. It is NOT where behavior goes. A standing rule about how you should act — a "from now on, always/never …", a tone or format preference, a workflow convention a user wants you to follow — belongs in \`soul.md\` (see the Persona / Standing instructions section), not here. When a note is really an instruction about your behavior, write it to \`soul.md\`; when it is a fact or a record of something that occurred, write it here.
 
-Shared knowledge is laid out as \`projects/<slug>/<topic>.md\` for project and system context, \`feedback/<topic>.md\` for concrete lessons learned from something that happened (the event and what it taught you — not a free-floating rule; the rule itself, if durable, goes in \`soul.md\`), and \`reference/<topic>.md\` for how external systems work. (Notes about a specific person live under \`users/\` and are shown separately, scoped to whoever you're talking to.) Each file's frontmatter declares \`name\` and \`description\` (the description is what shows up in the index, so make it a one-line behavior-triggering hook). Commit and push after writing to persist it.`;
+You own \`MEMORY.md\`. When you learn something durable, write the fact to its own \`.md\` file and add a one-line pointer to \`MEMORY.md\` in the form \`- [Title](relative/path.md) — one-line hook\`, where the hook is what tells future-you when to open the file. \`MEMORY.md\` is an *index*, never a store — put the actual content in the topic file and only a pointer line in \`MEMORY.md\`; do not inline a fact's body into the index even when it seems cheaper. Start each topic file with \`name:\`/\`description:\` frontmatter (the \`description\` is the one-line hook) so the index can be re-seeded, re-derived, or linted from the files themselves. When a fact changes, edit both the file and its line; when it stops being true, delete the file and its line. Shared knowledge is laid out as \`projects/<slug>/<topic>.md\` for project and system context, \`feedback/<topic>.md\` for concrete lessons learned from something that happened (the event and what it taught you — not a free-floating rule; the rule itself, if durable, goes in \`soul.md\`), and \`reference/<topic>.md\` for how external systems work. (Notes about a specific person live under \`users/\` and are indexed for you separately, scoped to whoever you're talking to — don't put people's private notes in the shared \`MEMORY.md\`.)
+
+Keep \`MEMORY.md\` lean. It's re-injected on *every* turn, so a small, high-signal index is worth far more than an exhaustive one — curate it like a tightly-edited table of contents, not a log:
+- Be selective. Only record something durable that will matter in a *future* conversation. Don't record what only matters right now, what you can re-derive on demand, or what's already obvious from the repo.
+- Consolidate before you create. Before adding a line, scan \`MEMORY.md\` for one that already covers the topic; if it exists, \`read\` that file and rewrite it with the new facts merged in rather than adding a near-duplicate. One fact per file, but don't fragment a topic across many thin files.
+- Prune as you go. Delete lines (and their files) that are wrong, stale, or superseded. The index header reports its size — when it's flagged over budget, consolidate and delete before adding anything new.
+- Write dates absolute, not relative. Resolve "last week" / "yesterday" to a concrete date when you record it (e.g. "on 7/3 Dhruv told me to …"), so the note still reads correctly in a future conversation.
+
+Commit and push after editing \`.memory/\` to persist it.`;
 }
 function composeBlock$1({ cwd, index }) {
 	const instructions = memoryInstructions(cwd);
 	if (!index || index.length === 0) return instructions;
-	return `${instructions}\n\n## Memory index\n\n${index}`;
+	const header = `## Memory index (${indexSizeNote(index)})`;
+	const warning = indexBudgetWarning(index);
+	const rendered = enforceMemoryIndexHardBudget(index);
+	return `${instructions}\n\n${warning ? `${header}\n\n${warning}\n\n${rendered}` : `${header}\n\n${rendered}`}`;
 }
 const memoryExtension = (pi) => {
 	let cachedBlock = null;
 	pi.on("session_start", async (_event, ctx) => {
 		try {
-			const index = await buildMemoryIndex({
-				cwd: ctx.cwd,
-				scope: { kind: "shared" }
-			});
+			const migrated = await migrateMemory({ cwd: ctx.cwd });
+			if (migrated !== null) log$5.info({
+				event: "memory_migrated",
+				from: migrated.from,
+				to: migrated.to
+			}, "migrated memory layout to current version");
+		} catch (err) {
+			log$5.warn({
+				err,
+				event: "memory_migration_failed"
+			}, "memory migration failed; continuing with existing index");
+		}
+		try {
+			const index = await readMemoryIndexFile({ cwd: ctx.cwd });
 			cachedBlock = composeBlock$1({
 				cwd: ctx.cwd,
 				index
 			});
 		} catch (err) {
-			log$6.warn({
+			log$5.warn({
 				err,
 				event: "memory_index_failed"
-			}, "memory index build failed; injecting instructions only");
+			}, "memory index read failed; injecting instructions only");
 			cachedBlock = memoryInstructions(ctx.cwd);
 		}
 	});
@@ -2512,7 +3696,7 @@ const memoryExtension = (pi) => {
 };
 //#endregion
 //#region src/extensions/platform-memory.ts
-const log$5 = logger.child({ module: "platform-memory-extension" });
+const log$4 = logger.child({ module: "platform-memory-extension" });
 /**
 * Resolve the human on this turn via the API, keyed by the message id.
 * `/sandbox/channel-context` only returns a sender for a platform-known
@@ -2525,13 +3709,13 @@ const log$5 = logger.child({ module: "platform-memory-extension" });
 async function resolveTurnUser(messageId) {
 	const client = sandboxClient();
 	if (!client) {
-		log$5.debug({ event: "resolve_turn_user_no_api_url" }, "no API url in env; withholding user memory");
+		log$4.debug({ event: "resolve_turn_user_no_api_url" }, "no API url in env; withholding user memory");
 		return null;
 	}
 	try {
 		const res = await client["channel-context"].$get({ query: { messageId } });
 		if (!res.ok) {
-			log$5.warn({
+			log$4.warn({
 				event: "resolve_turn_user_failed",
 				status: res.status
 			}, "channel-context returned non-ok; withholding user memory");
@@ -2544,7 +3728,7 @@ async function resolveTurnUser(messageId) {
 			displayName: sender.displayName
 		};
 	} catch (err) {
-		log$5.warn({
+		log$4.warn({
 			err,
 			event: "resolve_turn_user_failed"
 		}, "failed to resolve current user; withholding user memory");
@@ -2560,9 +3744,12 @@ function slugifyName(name) {
 function composeBlock({ index, user }) {
 	const instructions = `## Current user memory
 
-Notes about the person on this turn — the only \`users/\` memory you can see. Store anything you learn about them under \`${`.memory/users/${user.id}-${slugifyName(user.displayName)}/`}<topic>.md\`, using exactly this directory. Other people's \`users/\` notes are never shown, so never address someone by a name you only find in memory.`;
+Notes about the person on this turn — the only \`users/\` memory you can see. Store anything you learn about them under \`${`.memory/users/${user.id}-${slugifyName(user.displayName)}/`}<topic>.md\`, using exactly this directory. Other people's \`users/\` notes are never shown, so never address someone by a name you only find in memory. Keep it lean and be selective — this is re-injected every turn; consolidate related facts into one file and delete what's stale rather than piling on near-duplicates.`;
 	if (!index || index.length === 0) return instructions;
-	return `${instructions}\n\n${index}`;
+	const warning = indexBudgetWarning(index);
+	const header = `Memory index (${indexSizeNote(index)}):`;
+	const rendered = enforceMemoryIndexHardBudget(index);
+	return `${instructions}\n\n${warning ? `${warning}\n\n${header}\n\n${rendered}` : `${header}\n\n${rendered}`}`;
 }
 /**
 * Build the platform memory extension. `channelContext` is the per-turn ref
@@ -2583,15 +3770,12 @@ function createPlatformMemoryExtension({ channelContext }) {
 				cachedBlock = composeBlock({
 					index: await buildMemoryIndex({
 						cwd: ctx.cwd,
-						scope: {
-							kind: "user",
-							userId: user.id
-						}
+						userId: user.id
 					}),
 					user
 				});
 			} catch (err) {
-				log$5.warn({
+				log$4.warn({
 					err,
 					event: "user_memory_index_failed"
 				}, "user memory index build failed; skipping injection");
@@ -2606,7 +3790,7 @@ function createPlatformMemoryExtension({ channelContext }) {
 }
 //#endregion
 //#region src/extensions/self-trace.ts
-const log$4 = logger.child({ module: "self-trace-extension" });
+const log$3 = logger.child({ module: "self-trace-extension" });
 /**
 * Reports the agent's own execution as OpenTelemetry spans:
 * agent.session → agent.run → agent.turn.N → tool.NAME, with token/cost
@@ -2631,7 +3815,7 @@ const selfTraceExtension = (pi) => {
 		sessionSpan = tracer.startSpan("agent.session", { attributes: { "agent.model": modelId } }, remoteCtx);
 		sessionCtx = trace.setSpan(remoteCtx, sessionSpan);
 		const sc = sessionSpan.spanContext();
-		log$4.info({
+		log$3.info({
 			event: "self_trace_session_start",
 			trace_id: sc.traceId,
 			span_id: sc.spanId,
@@ -2743,13 +3927,13 @@ const selfTraceExtension = (pi) => {
 * Lives in the harness package — soul.md is content from the agent's
 * own git repo, not from the platform — so its handling stays here.
 */
-const log$3 = logger.child({ module: "soul-extension" });
+const log$2 = logger.child({ module: "soul-extension" });
 async function readSoul(cwd) {
 	try {
 		return (await readFile(join(cwd, "soul.md"), "utf8")).trim() || null;
 	} catch (err) {
 		if (err?.code === "ENOENT") return null;
-		log$3.warn({
+		log$2.warn({
 			err,
 			event: "soul_read_failed"
 		}, "soul.md read failed");
@@ -2781,8 +3965,7 @@ 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 log$1 = logger.child({ module: "subagent-ext" });
 const MAX_TASKS = 8;
 const TaskItem = Type.Object({
 	task: Type.String({ description: "The task to delegate to a subagent run." }),
@@ -2791,8 +3974,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 +3996,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,28 +4016,39 @@ 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
 				});
-				log$2.info({
+				const { taskIds } = spawned;
+				log$1.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);
-				log$2.warn({
+				log$1.warn({
 					err,
 					event: "subagent_spawn_failed"
 				}, "subagent spawn failed");
@@ -2863,29 +4065,24 @@ 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;
 			registered = true;
 			pi.registerTool(buildTool(messageId));
-			log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
+			log$1.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();
 		});
 	};
 }
@@ -2916,214 +4113,6 @@ const toolCallEnvExtension = (pi) => {
 	});
 };
 //#endregion
-//#region src/extensions/tool-call-summary.ts
-const log$1 = logger.child({ module: "tool-call-summary-extension" });
-/**
-* The injected parameter name: a namespaced sentinel, so it can never collide
-* with a real tool argument and is unmistakable in transcripts and logs. The
-* frontend renderer (ANY-2723) duplicates this literal — keep the two in sync.
-*/
-const TOOL_CALL_SUMMARY_FIELD = "__skydive_summary__";
-/** JSON Schema fragment for the injected parameter. */
-const SUMMARY_PROPERTY = {
-	type: "string",
-	description: "Required for every tool call. A concise, specific summary (max ~8 words) of what THIS call does and why, written for a person watching the conversation, e.g. \"Searching feedback for billing complaints\" or \"Reading the auth middleware\". Address the user directly in second person: the summary is read by the user, so refer to their things as \"your\", never in third person — \"Reading your emails\", not \"Reading his emails\". Always use the present progressive tense, since it is shown while the call runs: \"Updating your Slack\", never \"Updated your Slack\". Make each summary distinct from your other tool calls; never reuse a generic label like \"Search query\" or \"Running command\"."
-};
-const jsonSchemaObjectSchema = z.object({
-	type: z.unknown().optional(),
-	properties: z.record(z.string(), z.unknown()).optional(),
-	required: z.array(z.string()).optional(),
-	additionalProperties: z.unknown().optional()
-}).passthrough();
-const toolEntrySchema = z.object({
-	name: z.string().optional(),
-	input_schema: jsonSchemaObjectSchema.optional(),
-	parameters: jsonSchemaObjectSchema.optional(),
-	function: z.object({
-		name: z.string().optional(),
-		parameters: jsonSchemaObjectSchema.optional()
-	}).passthrough().optional()
-}).passthrough();
-const payloadWithToolsSchema = z.object({ tools: z.array(z.unknown()) }).passthrough();
-/**
-* Add the summary property to one JSON Schema object. Returns the augmented
-* copy, or `null` when the tool should be left untouched: a strict schema
-* (`additionalProperties: false`) whose validation would reject the extra
-* field, or one that already declares a `__skydive_summary__` property of its own.
-*/
-function augmentSchema(schema) {
-	if (schema.additionalProperties === false) return null;
-	const properties = schema.properties ?? {};
-	if ("__skydive_summary__" in properties) return null;
-	const required = schema.required ?? [];
-	return {
-		...schema,
-		type: schema.type ?? "object",
-		properties: {
-			[TOOL_CALL_SUMMARY_FIELD]: SUMMARY_PROPERTY,
-			...properties
-		},
-		required: required.includes("__skydive_summary__") ? required : [...required, TOOL_CALL_SUMMARY_FIELD]
-	};
-}
-/**
-* Augment a single tool entry, dispatching on which provider shape it is.
-* Returns the (possibly rebuilt) entry and whether anything changed. Skipped
-* tools — wrong shape, strict, or name in `strictToolNames` — return unchanged.
-*/
-function augmentToolEntry(entry, strictToolNames) {
-	const parsed = toolEntrySchema.safeParse(entry);
-	if (!parsed.success) return {
-		entry,
-		changed: false
-	};
-	const tool = parsed.data;
-	const name = tool.name ?? tool.function?.name ?? null;
-	if (name !== null && strictToolNames.has(name)) return {
-		entry,
-		changed: false
-	};
-	if (tool.input_schema) {
-		const augmented = augmentSchema(tool.input_schema);
-		if (!augmented) return {
-			entry,
-			changed: false
-		};
-		return {
-			entry: {
-				...tool,
-				input_schema: augmented
-			},
-			changed: true
-		};
-	}
-	if (tool.parameters) {
-		const augmented = augmentSchema(tool.parameters);
-		if (!augmented) return {
-			entry,
-			changed: false
-		};
-		return {
-			entry: {
-				...tool,
-				parameters: augmented
-			},
-			changed: true
-		};
-	}
-	if (tool.function?.parameters) {
-		const augmented = augmentSchema(tool.function.parameters);
-		if (!augmented) return {
-			entry,
-			changed: false
-		};
-		return {
-			entry: {
-				...tool,
-				function: {
-					...tool.function,
-					parameters: augmented
-				}
-			},
-			changed: true
-		};
-	}
-	return {
-		entry,
-		changed: false
-	};
-}
-/**
-* Inject the summary field into every eligible tool in a provider payload.
-* Returns a new payload when at least one tool was augmented, or `undefined`
-* to signal "no change" (which keeps the original payload, per the
-* `before_provider_request` contract).
-*
-* @param payload The outgoing provider payload (shape varies by provider).
-* @param strictToolNames Names of tools whose registered schema is strict and
-*   must be skipped to avoid validation errors.
-*/
-function injectToolCallSummary(payload, strictToolNames) {
-	const parsed = payloadWithToolsSchema.safeParse(payload);
-	if (!parsed.success || parsed.data.tools.length === 0) return void 0;
-	let changed = false;
-	const tools = parsed.data.tools.map((entry) => {
-		const result = augmentToolEntry(entry, strictToolNames);
-		if (result.changed) changed = true;
-		return result.entry;
-	});
-	if (!changed) return void 0;
-	return {
-		...parsed.data,
-		tools
-	};
-}
-/**
-* Names of registered tools whose schema sets `additionalProperties: false`.
-* Pi validates the model's tool args against this registered schema, so the
-* injected field would make a strict tool's call fail validation — skip them.
-*/
-function getStrictToolNames(pi) {
-	const names = /* @__PURE__ */ new Set();
-	for (const tool of pi.getAllTools()) {
-		const parsed = jsonSchemaObjectSchema.safeParse(tool.parameters);
-		if (parsed.success && parsed.data.additionalProperties === false) names.add(tool.name);
-	}
-	return names;
-}
-function toolDeclaresSummaryParam(pi, toolName) {
-	const tool = pi.getAllTools().find((candidate) => candidate.name === toolName);
-	if (!tool) return false;
-	const parsed = jsonSchemaObjectSchema.safeParse(tool.parameters);
-	return parsed.success && parsed.data.properties != null && "__skydive_summary__" in parsed.data.properties;
-}
-/**
-* Remove the injected summary from a tool's execution input. No-op when the
-* field is absent, or when the tool genuinely declares a `__skydive_summary__`
-* parameter of its own (which we never inject into, so its value is real).
-* Mutates `input` in place, matching the `tool_call` contract.
-*
-* Fails open: this runs on the critical path of tool execution, and the
-* `getAllTools()` lookup can throw. On any error we leave `input` untouched
-* (the sentinel may pass through to the tool, but a bug here can never break
-* tool execution).
-*/
-function stripInjectedSummary(pi, toolName, input) {
-	try {
-		if (!("__skydive_summary__" in input)) return;
-		if (toolDeclaresSummaryParam(pi, toolName)) return;
-		delete input[TOOL_CALL_SUMMARY_FIELD];
-	} catch (err) {
-		log$1.error({
-			err,
-			event: "tool_call_summary_strip_failed",
-			toolName
-		}, "tool_call_summary strip failed; leaving tool input untouched");
-	}
-}
-/**
-* Compute the rewritten payload for a `before_provider_request` event, failing
-* open: on any error the original payload is left untouched so a bug here can
-* never break an LLM call.
-*/
-function buildInjectedPayload(pi, payload) {
-	try {
-		return injectToolCallSummary(payload, getStrictToolNames(pi));
-	} catch (err) {
-		log$1.error({
-			err,
-			event: "tool_call_summary_injection_failed"
-		}, "tool_call_summary injection failed; passing payload through unchanged");
-		return;
-	}
-}
-const toolCallSummaryExtension = (pi) => {
-	pi.on("before_provider_request", (event) => buildInjectedPayload(pi, event.payload));
-	pi.on("tool_call", (event) => {
-		stripInjectedSummary(pi, event.toolName, event.input);
-	});
-};
-//#endregion
 //#region src/extensions/background-tasks.ts
 /**
 * Background bash tasks as a pi extension.
@@ -3163,21 +4152,43 @@ const toolCallSummaryExtension = (pi) => {
 * from the origin messageId in its channel context (`resolveConversationFromApi`)
 * — and every run of the same conversation resolves to the same id, keeping the
 * shared map correctly scoped across turns. `bg_*`, the completion wake, and the
-* next-session injection all filter to the resolved conversation — an agent
-* never sees or is woken by a task from a different chat. Only the output log
+* next-session injection all filter by a **scope key** — the resolved
+* conversation id, or, when a session's conversation is unresolvable (a bare
+* CLI session, or a run whose channel-context ref carries no messageId), a
+* sentinel unique to that one session instance. Comparing on the raw
+* `conversationId` would bucket every unresolvable session together under
+* `null` and leak one's completion wake / status / next-session injection into
+* another; the sentinel keeps each isolated so an agent never sees or is woken
+* by a task from a different chat. Only the output log
 * spills to disk (/home/user/.anyone/bg-tasks/<id>.log) to avoid buffering a chatty job
 * in memory; exit code and run state live on the in-memory task.
 *
-* **No cross-restart survival (v1, deliberate).** Task state lives only in
-* the running harness process. A harness restart (crash → supervisord
-* respawn, or `platform harness reload` after the agent edits its own
-* harness) drops the map and pi's exec children are reaped with it. We don't
-* resurrect from disk because the common next-run case cold-provisions a
-* *different* sandbox anyway (warm reuse is the minority in prod), so on-disk
-* state would rarely be the box the next run lands on. The idle-completion wake
-* does cross the sandbox → platform boundary (a fresh run via `bg-task-done`),
-* but a task whose harness dies before it finishes is gone — it is not
-* resurrected, and this stays distinct from the scheduled-run (cron) system.
+* **Cross-restart survival is OPT-IN, via `bg_run({ resumable: true })`.**
+* A non-resumable task's state lives only in the running harness process: a
+* harness restart (crash → supervisord respawn, `platform harness reload`, or
+* a sandbox recycle on idle timeout / redeploy / template rebuild) drops the
+* map and pi's exec children are reaped with it, and the task is gone — the
+* right behavior for a one-shot side-effecting command, which must never
+* silently re-run.
+*
+* A RESUMABLE task additionally checkpoints its *spec* (command, cwd, labels,
+* origin messageId — not its live output/exit state) to a durable, api-side
+* journal keyed by conversation (`/sandbox/bg-task-journal`, redis). On the
+* NEXT run's `session_start` — which usually lands on a *different*,
+* cold-provisioned sandbox, which is exactly why the journal is api-side and
+* not on the sandbox disk — the harness lists the journal and relaunches any
+* spec it isn't already running, keeping the original id and prepending a
+* `<resumed-after-restart>` banner so the agent knows it re-ran from scratch,
+* not continued. The spec is dropped from the journal when the task
+* finishes/kills. Because relaunch RE-EXECUTES the command, resumable is only
+* for idempotent, long-lived work (pollers, watchers, retry loops); the tool
+* description enforces this and the default is false.
+*
+* The idle-completion wake (a task finishing while the agent is idle) crosses
+* the sandbox → platform boundary via a fresh run (`bg-task-done`) for both
+* resumable and non-resumable tasks; the journal is a separate, additive layer
+* that only handles a task whose harness dies BEFORE it finishes. This stays
+* distinct from the scheduled-run (cron) system.
 */
 const log = logger.child({ module: "background-tasks-ext" });
 const ops = createLocalBashOperations();
@@ -3188,6 +4199,7 @@ const WATCHDOG_INTERVAL_MS = 3e4;
 const KEEPALIVE_EVERY_MS = 6e4;
 const KEEPALIVE_MAX_MS = 3600 * 1e3;
 const STALL_HINT_AFTER_MS = 120 * 1e3;
+const PUBLISH_DEBOUNCE_MS = 300;
 const MAX_LOG_BYTES = 100 * 1024 * 1024;
 const DEFAULT_TAIL_LINES = 30;
 const TAIL_READ_BYTES = 64 * 1024;
@@ -3195,11 +4207,12 @@ function taskLabel(meta) {
 	return `${meta.id} "${meta.description ?? meta.command.slice(0, 60)}"`;
 }
 let taskCounter = 0;
+let sessionScopeCounter = 0;
 const tasks = /* @__PURE__ */ new Map();
 let watchdogInterval = null;
 let lastKeepaliveAt = 0;
-function sameConversation(meta, conversationId) {
-	return meta.conversationId === conversationId;
+function sameScope(meta, scopeKey) {
+	return meta.scopeKey === scopeKey;
 }
 function logPath(id) {
 	return join(tasksDir(), `${id}.log`);
@@ -3312,6 +4325,10 @@ function createBackgroundTasksExtension({ channelContext }) {
 				return id;
 			});
 		}
+		const unresolvedScopeSentinel = `unresolved:${process.pid.toString(36)}:${(sessionScopeCounter += 1).toString(36)}`;
+		function scopeKey() {
+			return conversationId ?? unresolvedScopeSentinel;
+		}
 		let agentActive = false;
 		pi.on("agent_start", async () => {
 			agentActive = true;
@@ -3339,13 +4356,16 @@ ${recentOutput}
 </background-task-finished>
 Run bg_logs for the full output.
 
-This is a background-task completion, not a message from the user. If it needs no user-facing response — a routine or expected finish, a leftover or self-killed process, nothing the user must act on or would want to know right now — call \`platform channel suppress-reply\` and output nothing. Only send a message if the outcome changes what the user should do or know, or if you were explicitly waiting to report this result.`,
+This is a background-task completion, not a message from the user.
+For a routine or expected completion, output nothing.
+Only reply if the outcome changes what the user should know or do,
+or if you were explicitly waiting to report it.`,
 				display: false
 			};
 		}
 		async function notifyCompletion(meta) {
 			if (meta.notified) return;
-			if (agentActive && sameConversation(meta, conversationId)) {
+			if (agentActive && sameScope(meta, scopeKey())) {
 				meta.notified = true;
 				pi.sendMessage(await taskDoneMessage(meta), {
 					triggerTurn: true,
@@ -3376,9 +4396,83 @@ This is a background-task completion, not a message from the user. If it needs n
 				});
 			} else log.info({ taskId: meta.id }, "bg task completed idle with no origin message; deferring to next session_start");
 		}
-		async function launchTask({ command, description, cwd }) {
+		const SNAPSHOT_TAIL_LINES = 40;
+		let lastPublishedSignature = null;
+		let publishInFlight = null;
+		let publishQueued = false;
+		function snapshotSignature(snapshot) {
+			return JSON.stringify(snapshot.map((t) => ({
+				id: t.id,
+				state: t.state,
+				exitCode: t.exitCode,
+				killedReason: t.killedReason,
+				outputTail: t.outputTail
+			})));
+		}
+		async function doPublishSnapshot() {
+			if (!messageId) return;
+			const mine = [...tasks.values()].filter((t) => sameScope(t, scopeKey()));
+			try {
+				const snapshot = await Promise.all(mine.map(async (t) => ({
+					id: t.id,
+					command: t.command,
+					description: t.description,
+					startedAt: t.startedAt,
+					state: t.running ? "running" : "finished",
+					exitCode: t.exitCode,
+					killedReason: t.killedReason,
+					outputTail: await tailLog(t.id, SNAPSHOT_TAIL_LINES)
+				})));
+				const signature = snapshotSignature(snapshot);
+				if (signature === lastPublishedSignature) return;
+				lastPublishedSignature = signature;
+				postBackgroundTasksSnapshot({
+					messageId,
+					tasks: snapshot
+				});
+			} catch (err) {
+				log.debug({
+					err,
+					event: "bg_tasks_snapshot_build_failed"
+				}, "building bg-tasks snapshot failed");
+			}
+		}
+		async function publishSnapshotNow() {
+			if (publishInFlight) {
+				publishQueued = true;
+				return;
+			}
+			publishInFlight = (async () => {
+				try {
+					do {
+						publishQueued = false;
+						await doPublishSnapshot();
+					} while (publishQueued);
+				} finally {
+					publishInFlight = null;
+				}
+			})();
+			await publishInFlight;
+		}
+		let publishTimer = null;
+		function schedulePublishSnapshot() {
+			if (publishTimer) return;
+			publishTimer = setTimeout(() => {
+				publishTimer = null;
+				publishSnapshotNow();
+			}, PUBLISH_DEBOUNCE_MS);
+			publishTimer.unref?.();
+		}
+		async function flushPublishSnapshot() {
+			if (publishTimer) {
+				clearTimeout(publishTimer);
+				publishTimer = null;
+			}
+			await publishSnapshotNow();
+		}
+		async function launchTask({ command, description, cwd, resumable = false, resumedFromJournal = false, id: providedId, startedAt: providedStartedAt }) {
 			taskCounter += 1;
-			const id = `bg-${process.pid.toString(36)}-${taskCounter}`;
+			const id = providedId ?? `bg-${process.pid.toString(36)}-${taskCounter}`;
 			try {
 				await mkdir(tasksDir(), { recursive: true });
 			} catch (err) {
@@ -3394,7 +4488,7 @@ This is a background-task completion, not a message from the user. If it needs n
 					taskId: id
 				}, "bg task log write failed");
 			});
-			const startedAt = Date.now();
+			const startedAt = providedStartedAt ?? Date.now();
 			const meta = {
 				id,
 				command: stripPlatformExportsForDisplay(command),
@@ -3402,6 +4496,7 @@ This is a background-task completion, not a message from the user. If it needs n
 				logBytes: 0,
 				lastOutputAt: startedAt,
 				conversationId,
+				scopeKey: scopeKey(),
 				messageId,
 				description,
 				notified: false,
@@ -3409,9 +4504,23 @@ This is a background-task completion, not a message from the user. If it needs n
 				controller: new AbortController(),
 				running: true,
 				exitCode: null,
-				error: null
+				error: null,
+				resumable,
+				cwd,
+				resumedFromJournal
 			};
 			tasks.set(id, meta);
+			if (resumable && messageId) putBackgroundTaskJournalSpec({
+				messageId,
+				spec: {
+					id,
+					command,
+					cwd,
+					description,
+					startedAt,
+					messageId
+				}
+			});
 			ops.exec(command, cwd, {
 				onData: (chunk) => {
 					meta.logBytes += chunk.length;
@@ -3437,6 +4546,11 @@ This is a background-task completion, not a message from the user. If it needs n
 					taskId: id,
 					exitCode: meta.exitCode
 				}, "bg task finished");
+				if (meta.resumable && meta.messageId) deleteBackgroundTaskJournalSpec({
+					messageId: meta.messageId,
+					taskId: id
+				});
+				schedulePublishSnapshot();
 				await notifyCompletion(meta);
 			});
 			ensureWatchdog();
@@ -3444,19 +4558,55 @@ This is a background-task completion, not a message from the user. If it needs n
 				taskId: id,
 				conversationId
 			}, "bg task started");
+			schedulePublishSnapshot();
 			return meta;
 		}
 		function knownTaskIds() {
-			return [...tasks.values()].filter((t) => sameConversation(t, conversationId)).map((t) => t.id).join(", ") || "(none)";
+			return [...tasks.values()].filter((t) => sameScope(t, scopeKey())).map((t) => t.id).join(", ") || "(none)";
+		}
+		let journalChecked = false;
+		async function rehydrateJournaledTasks() {
+			if (!messageId || journalChecked) return;
+			journalChecked = true;
+			const specs = await listBackgroundTaskJournalSpecs({ messageId });
+			if (specs.length === 0) return;
+			for (const spec of specs) {
+				const live = tasks.get(spec.id);
+				if (live && sameScope(live, scopeKey())) continue;
+				log.info({
+					taskId: spec.id,
+					conversationId
+				}, "relaunching journaled resumable bg task after restart");
+				const meta = await launchTask({
+					command: spec.command,
+					description: spec.description,
+					cwd: spec.cwd,
+					resumable: true,
+					resumedFromJournal: true,
+					id: spec.id,
+					startedAt: spec.startedAt
+				});
+				try {
+					const stream = createWriteStream(logPath(meta.id), { flags: "a" });
+					stream.write(`<resumed-after-restart>requeued and relaunched on a new sandbox after the previous one was drained; this is a fresh execution of the command from the start, not a continuation</resumed-after-restart>\n`);
+					stream.end();
+				} catch (err) {
+					log.debug({
+						err,
+						taskId: meta.id
+					}, "resume banner write failed");
+				}
+			}
 		}
 		pi.on("session_start", async () => {
-			if (tasks.size === 0) return;
+			if (tasks.size === 0 && (!messageId || journalChecked)) return;
 			await ensureConversationId();
-			for (const [id, meta] of tasks) if (sameConversation(meta, conversationId) && !meta.running && meta.notified) {
+			await rehydrateJournaledTasks();
+			for (const [id, meta] of tasks) if (sameScope(meta, scopeKey()) && !meta.running && meta.notified) {
 				tasks.delete(id);
 				await unlink(logPath(id)).catch(() => {});
 			}
-			const unnotified = [...tasks.values()].filter((t) => sameConversation(t, conversationId) && !t.notified && !t.running);
+			const unnotified = [...tasks.values()].filter((t) => sameScope(t, scopeKey()) && !t.notified && !t.running);
 			for (const meta of unnotified) {
 				meta.notified = true;
 				pi.sendMessage(await taskDoneMessage(meta));
@@ -3465,7 +4615,9 @@ This is a background-task completion, not a message from the user. If it needs n
 				conversationId,
 				count: unnotified.length
 			}, "injected completed bg tasks at session_start");
-			if ([...tasks.values()].some((t) => sameConversation(t, conversationId) && t.running)) ensureWatchdog();
+			if ([...tasks.values()].some((t) => sameScope(t, scopeKey()) && t.running)) ensureWatchdog();
+			lastPublishedSignature = null;
+			await flushPublishSnapshot();
 		});
 		function err(text) {
 			return {
@@ -3482,11 +4634,11 @@ This is a background-task completion, not a message from the user. If it needs n
 		}
 		function resolveTask(taskId) {
 			const exact = tasks.get(taskId);
-			if (exact && sameConversation(exact, conversationId)) return {
+			if (exact && sameScope(exact, scopeKey())) return {
 				error: null,
 				meta: exact
 			};
-			const matches = [...tasks.values()].filter((t) => sameConversation(t, conversationId) && t.id.startsWith(taskId));
+			const matches = [...tasks.values()].filter((t) => sameScope(t, scopeKey()) && t.id.startsWith(taskId));
 			if (matches.length === 1) return {
 				error: null,
 				meta: matches[0]
@@ -3495,7 +4647,7 @@ This is a background-task completion, not a message from the user. If it needs n
 			return err(`Unknown task ${taskId}. Known tasks: ${knownTaskIds()}`);
 		}
 		function listTasks() {
-			const mine = [...tasks.values()].filter((t) => sameConversation(t, conversationId));
+			const mine = [...tasks.values()].filter((t) => sameScope(t, scopeKey()));
 			if (mine.length === 0) return "No background tasks.";
 			return mine.map((t) => {
 				const state = t.running ? "running" : t.exitCode !== null ? `exited ${t.exitCode}${t.killedReason ? ` (killed: ${t.killedReason})` : ""}` : t.killedReason ? `killed: ${t.killedReason}` : "ended";
@@ -3508,24 +4660,27 @@ This is a background-task completion, not a message from the user. If it needs n
 		const bgRun = {
 			name: "bg_run",
 			label: "Run in background",
-			description: "Run a bash command in the background. Returns immediately with a task id; output streams to a log file. You are sent a message when it finishes — keep working or end your turn meanwhile. Use for anything over a couple of minutes (builds, batch jobs, retry loops, downloads). Inspect with bg_status / bg_logs, stop with bg_kill.",
-			promptSnippet: "bg_run — run a long command without blocking; you are notified on completion",
+			description: "Run a bash command in the background. Returns immediately with a task id; output streams to a log file. You are sent a message when it finishes — keep working or end your turn meanwhile. Use for anything over a couple of minutes (builds, batch jobs, retry loops, downloads). Inspect with bg_status / bg_logs, stop with bg_kill. Pass resumable:true ONLY for an idempotent, long-lived command (a poller/watcher/retry loop) that should be requeued and relaunched on your next run if the sandbox goes away before it finishes (a sandbox is drained and replaced with a fresh one, not restarted in place) — the requeue re-runs the command from scratch, so never mark a one-shot side-effecting job (a migration, an apply, a send) resumable.",
+			promptSnippet: "bg_run — run a long command without blocking; you are notified on completion (resumable:true requeues the task onto a fresh sandbox if the current one is drained, idempotent commands only)",
 			parameters: Type.Object({
 				command: Type.String({ description: "Bash command to execute" }),
-				description: Type.Optional(Type.String({ description: "Clear, concise description of what this command does in active voice (2-6 words)." }))
+				description: Type.Optional(Type.String({ description: "Clear, concise description of what this command does in active voice (2-6 words)." })),
+				resumable: Type.Optional(Type.Boolean({ description: "When true, this task is requeued and relaunched on your next run if the sandbox it is running on goes away before it finishes (a sandbox is drained and replaced with a fresh one, rather than restarted in place, so an in-flight task would otherwise be lost). Use ONLY for idempotent, long-lived commands (pollers, watchers, retry loops) — the requeue re-runs the command from scratch on the new sandbox, so never set this on a one-shot side-effecting command." }))
 			}),
 			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				await ensureConversationId();
-				const { command, description = null } = params;
+				const { command, description = null, resumable = false } = params;
 				const meta = await launchTask({
 					command,
 					description,
-					cwd: ctx.cwd
+					cwd: ctx.cwd,
+					resumable
 				});
+				const resumeNote = resumable && meta.messageId ? "\nResumable: if this sandbox is drained before the task finishes, it will be requeued and relaunched from the start on your next run." : resumable ? "\nNote: resumable was requested but this session has no durable conversation, so it will NOT be requeued if the sandbox is drained." : "";
 				return {
 					content: [{
 						type: "text",
-						text: `Started background task ${taskLabel(meta)}.\nlog: ${logPath(meta.id)}\nYou will get a message when it finishes. Check on it with bg_status {"taskId":"${meta.id}"}.`
+						text: `Started background task ${taskLabel(meta)}.\nlog: ${logPath(meta.id)}\nYou will get a message when it finishes. Check on it with bg_status {"taskId":"${meta.id}"}.${resumeNote}`
 					}],
 					details: {}
 				};
@@ -3645,6 +4800,7 @@ const all = [
 	localToolsExtension,
 	toolCallEnvExtension,
 	bashDefaultTimeoutExtension,
+	diskGuardExtension,
 	toolCallSummaryExtension
 ];
 /**
@@ -3663,7 +4819,8 @@ function platformExtensions({ sessionId, channelContext }) {
 		selfTraceExtension,
 		createBackgroundTasksExtension({ channelContext }),
 		createSubagentExtension({ channelContext }),
-		createContextManagementExtension()
+		createContextManagementExtension(),
+		resourcePressureWarningExtension
 	];
 }
 //#endregion