@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/domains/safety/read-scope.ts

@@ -0,0 +1,120 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { canonicalizePath, canonicalizeRawPath, type PathWalkMemo } from "../../core/path-canonical.js";
+import { ToolNames } from "../../core/tool-names.js";
+import { clioConfigDir, clioStateDir } from "../../core/xdg.js";
+import { expandPath, readPathVariants } from "../../tools/path-utils.js";
+import { INTEROP_AGENT_KINDS } from "../interop/registry.js";
+import { isSameOrDescendant } from "./path-policy.js";
+
+/**
+ * The read-class tools that take a path from the model. Each opens whatever
+ * the path resolves to, so each is held to the workspace the same way.
+ */
+const READ_SCOPE_TOOLS: ReadonlySet<string> = new Set([ToolNames.Read, ToolNames.Ls, ToolNames.Grep, ToolNames.Find]);
+
+export function isReadScopeTool(tool: string): boolean {
+	return READ_SCOPE_TOOLS.has(tool);
+}
+
+export interface ReadScopeExemptRoot {
+	path: string;
+	/** True for a tree tools can never write (skill authority, foreign agent dirs). */
+	operatorOwned: boolean;
+}
+
+/**
+ * Trees outside the workspace that Clio itself points the model at: installed
+ * skills, plugins, and extensions (a loaded SKILL.md names sibling files), the
+ * user skill roots of the agents Clio interoperates with, the offload scratch
+ * a truncation stub names, and dispatch receipts. They are operator-owned or
+ * Clio-written, the model cannot author them, and zero-access entries still
+ * apply inside them. Lexical on purpose: they are resolved again at every
+ * admission, because an operator may replace a link after the session starts.
+ */
+export function readScopeExemptRoots(): ReadScopeExemptRoot[] {
+	const roots: ReadScopeExemptRoot[] = [];
+	try {
+		const config = clioConfigDir();
+		for (const kind of ["skills", "plugins", "extensions"]) {
+			roots.push({ path: path.join(config, kind), operatorOwned: true });
+		}
+		const state = clioStateDir();
+		roots.push({ path: path.join(state, "scratch"), operatorOwned: false });
+		roots.push({ path: path.join(state, "receipts"), operatorOwned: false });
+	} catch {
+		// An unresolvable Clio home exempts nothing.
+	}
+	const home = homedir();
+	for (const kind of INTEROP_AGENT_KINDS) {
+		if (kind.userSkillRoot !== undefined) {
+			roots.push({ path: path.join(home, kind.userSkillRoot), operatorOwned: true });
+		}
+	}
+	return roots;
+}
+
+/**
+ * Every spelling a read tool can open for one path argument, already expanded
+ * the way the tool expands it and never to be expanded again (a fallback
+ * carries the narrow no-break space that expansion folds away): the path as
+ * given, then the fallbacks resolveReadPath tries on the resolved path when it
+ * does not exist. A fallback can name a link the plain spelling does not, so
+ * the path policy and the scope check judge each of them.
+ */
+export function readScopeSpellings(rawPath: string, callCwd: string): string[] {
+	const expanded = expandPath(rawPath);
+	const resolved = canonicalizeRawPath(expanded, callCwd) ?? path.resolve(callCwd, expanded);
+	return [expanded, ...readPathVariants(resolved)];
+}
+
+function hasParentSegment(rawPath: string): boolean {
+	return rawPath.split(/[\\/]/u).includes("..");
+}
+
+/**
+ * Where a read-class path call lands when that is outside the workspace, or
+ * null when it stays inside or inside an exempt root. The target is resolved
+ * the way the read tools resolve it (resolveReadPath: physical, `link/..`
+ * steps up from the link's target). A path that cannot be canonicalized is
+ * outside: nothing proves where a read through it lands.
+ *
+ * An exempt root admits a target whose real path sits under the root's real
+ * path. An operator-owned root also admits a path that, as written, has no
+ * `..` and sits under the root as written: an operator may install one skill
+ * as a link into a dotfiles tree, and what a tree no tool can write links to
+ * is the operator's choice.
+ */
+export function readScopeEscape(
+	rawPath: string,
+	callCwd: string,
+	workspace: string,
+	exemptRoots: ReadonlyArray<ReadScopeExemptRoot>,
+	memo: PathWalkMemo,
+): string | null {
+	for (const spelling of readScopeSpellings(rawPath, callCwd)) {
+		const escaped = spellingEscape(spelling, callCwd, workspace, exemptRoots, memo);
+		if (escaped !== null) return escaped;
+	}
+	return null;
+}
+
+function spellingEscape(
+	expanded: string,
+	callCwd: string,
+	workspace: string,
+	exemptRoots: ReadonlyArray<ReadScopeExemptRoot>,
+	memo: PathWalkMemo,
+): string | null {
+	const physical = canonicalizeRawPath(expanded, callCwd, memo);
+	if (physical !== null && isSameOrDescendant(physical, workspace)) return null;
+	const lexical = path.resolve(callCwd, expanded);
+	const lexicalEligible = !hasParentSegment(expanded);
+	for (const root of exemptRoots) {
+		if (root.operatorOwned && lexicalEligible && isSameOrDescendant(lexical, root.path)) return null;
+		if (physical === null) continue;
+		const realRoot = canonicalizePath(root.path, memo);
+		if (realRoot !== null && isSameOrDescendant(physical, realRoot)) return null;
+	}
+	return physical ?? lexical;
+}

package/src/domains/safety/skill-authority.ts

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import path from "node:path";
-import { canonicalizeExistingPath } from "../../core/path-canonical.js";
+import { canonicalizeExistingPath, canonicalizeRawPath, type PathWalkMemo } from "../../core/path-canonical.js";
 import { clioConfigDir } from "../../core/xdg.js";
 import { isSameOrDescendant, type PathPolicyOperation } from "./path-policy.js";
 import { extractCommandCdTargets } from "./protected-artifacts.js";
@@ -16,35 +16,71 @@ export function activeClioSkillRoots(cwd: string): string[] {
 	]);
 }
 
-export function skillMutationReason(
-	roots: ReadonlyArray<string>,
+/** Where one mutating path target can land, lexically and physically, from one possible working directory. */
+export interface MutationCandidate {
+	operation: PathPolicyOperation;
+	lexical: string;
+	resolved: string;
+}
+
+/**
+ * Resolve every mutating target once per admission, so each authority check
+ * that follows compares the same answers instead of walking the target again.
+ */
+export function mutationCandidates(
 	targets: ReadonlyArray<{ operation: PathPolicyOperation; path: string }>,
 	cwd: string,
 	command: string | null,
-): string | null {
+	memo: PathWalkMemo,
+): MutationCandidate[] {
 	const workingDirs = [cwd];
 	// Existing shell inspection extracts literal path-bearing operations. Include
 	// their possible cd bases so a visible cd cannot hide the protected target.
 	// This deliberately cannot interpret arbitrary programs, variables or aliases.
+	// A shell cd is logical unless `-P` makes it physical, so both chains count.
 	if (command !== null) {
+		let logical = cwd;
+		let physical = cwd;
 		for (const destination of extractCommandCdTargets(command)) {
-			workingDirs.push(path.resolve(workingDirs.at(-1) ?? cwd, expandHome(destination)));
+			const next = expandHome(destination);
+			logical = path.resolve(logical, next);
+			physical = canonicalizeRawPath(next, physical, memo) ?? path.resolve(physical, next);
+			workingDirs.push(logical);
+			if (physical !== logical) workingDirs.push(physical);
 		}
 	}
+	const candidates: MutationCandidate[] = [];
 	for (const target of targets) {
 		if (target.operation === "read") continue;
 		for (const directory of workingDirs) {
-			const lexical = path.resolve(directory, expandHome(target.path));
-			const resolved = canonicalizeExistingPath(lexical);
-			for (const root of roots) {
-				for (const boundary of [root, canonicalizeExistingPath(root)]) {
-					for (const candidate of [lexical, resolved]) {
-						if (
-							isSameOrDescendant(candidate, boundary) ||
-							(target.operation === "delete" && isSameOrDescendant(boundary, candidate))
-						) {
-							return `active resource tree ${root} is operator-owned; draft changes outside installed resource roots and use the operator install or update interface`;
-						}
+			const raw = expandHome(target.path);
+			const lexical = path.resolve(directory, raw);
+			// Physical, as the kernel resolves `link/..` in a write target.
+			const resolved = canonicalizeRawPath(raw, directory, memo) ?? canonicalizeExistingPath(lexical, memo);
+			candidates.push({ operation: target.operation, lexical, resolved });
+		}
+	}
+	return candidates;
+}
+
+export function skillMutationReason(
+	roots: ReadonlyArray<string>,
+	candidates: ReadonlyArray<MutationCandidate>,
+	memo: PathWalkMemo,
+): string | null {
+	// Each root resolves at most once per check, and only when a candidate
+	// reaches it, in the order the candidates reach it.
+	const boundaries: Array<readonly string[] | undefined> = [];
+	for (const candidate of candidates) {
+		for (const [index, root] of roots.entries()) {
+			boundaries[index] ??= [root, canonicalizeExistingPath(root, memo)];
+			for (const boundary of boundaries[index]) {
+				for (const location of [candidate.lexical, candidate.resolved]) {
+					if (
+						isSameOrDescendant(location, boundary) ||
+						(candidate.operation === "delete" && isSameOrDescendant(boundary, location))
+					) {
+						return `active resource tree ${root} is operator-owned; draft changes outside installed resource roots and use the operator install or update interface`;
 					}
 				}
 			}

package/src/domains/scheduling/cluster.ts

@@ -19,6 +19,7 @@
  */
 
 import type { FleetNodeSettings } from "../../core/defaults.js";
+import type { LocalCapacity, LocalCapacityBound } from "./local-capacity.js";
 
 export type FleetNodeState = "online" | "offline";
 
@@ -30,6 +31,8 @@ export interface FleetNodeSnapshot {
 	stateReason: string | null;
 	activeWorkers: number;
 	maxWorkers: number;
+	/** What bound `maxWorkers`; null for SSH nodes, which declare their own. */
+	capacityBound: LocalCapacityBound | null;
 	labels: ReadonlyArray<string>;
 	lastSeenAt: string | null;
 }
@@ -56,6 +59,8 @@ export interface FleetRegistry {
 	 * then a snapshot reports zero rather than inventing a process-local count.
 	 */
 	bindActiveWorkers(source: (nodeId: string) => number): void;
+	/** Lease-derived active workers on one node; zero before a source is bound. */
+	activeWorkers(nodeId: string): number;
 }
 
 export const LOCAL_NODE_ID = "local";
@@ -72,8 +77,8 @@ interface NodeRuntimeState {
 
 export interface FleetRegistryOptions {
 	now?: () => number;
-	/** Display-only cap for the implicit local node. */
-	localMaxWorkers?: () => number;
+	/** Display-only limit for the implicit local node and what bound it. */
+	localCapacity?: () => LocalCapacity;
 	/** Durable lease-derived usage; never a process-local counter. */
 	activeWorkers?: (nodeId: string) => number;
 }
@@ -102,6 +107,7 @@ export function createFleetRegistry(
 	function snapshotFor(id: string, config: FleetNodeSettings | null): FleetNodeSnapshot {
 		const state = stateFor(id);
 		if (config === null) {
+			const capacity = options?.localCapacity?.();
 			return {
 				id: LOCAL_NODE_ID,
 				host: "localhost",
@@ -109,7 +115,8 @@ export function createFleetRegistry(
 				state: state.state,
 				stateReason: state.stateReason,
 				activeWorkers: activeWorkers?.(LOCAL_NODE_ID) ?? 0,
-				maxWorkers: options?.localMaxWorkers?.() ?? Number.POSITIVE_INFINITY,
+				maxWorkers: capacity?.limit ?? Number.POSITIVE_INFINITY,
+				capacityBound: capacity?.bound ?? null,
 				labels: [],
 				lastSeenAt: state.lastSeenMs !== null ? new Date(state.lastSeenMs).toISOString() : null,
 			};
@@ -122,6 +129,7 @@ export function createFleetRegistry(
 			stateReason: state.stateReason,
 			activeWorkers: activeWorkers?.(id) ?? 0,
 			maxWorkers: config.maxWorkers,
+			capacityBound: null,
 			labels: [...(config.labels ?? [])],
 			lastSeenAt: state.lastSeenMs !== null ? new Date(state.lastSeenMs).toISOString() : null,
 		};
@@ -161,6 +169,9 @@ export function createFleetRegistry(
 		bindActiveWorkers(source) {
 			activeWorkers = source;
 		},
+		activeWorkers(nodeId) {
+			return activeWorkers?.(nodeId) ?? 0;
+		},
 		recordChannelSuccess(id) {
 			const state = stateFor(id);
 			state.consecutiveFailures = 0;

package/src/domains/scheduling/contract.ts

@@ -1,5 +1,6 @@
 import type { BudgetVerdict } from "./budget.js";
 import type { FleetRegistry } from "./cluster.js";
+import type { LocalCapacity } from "./local-capacity.js";
 
 export interface BudgetPreflight {
 	verdict: BudgetVerdict;
@@ -21,6 +22,12 @@ export interface SchedulingContract {
 	preflight(): BudgetPreflight;
 	/** Configured global worker capacity; durable leases own active usage. */
 	maxWorkers(): number;
+	/**
+	 * Worker limit for the implicit local node and the input that bound it.
+	 * Under `auto` this follows host CPU and memory; optional so minimal
+	 * scheduling stubs remain valid, and dispatch then uses `maxWorkers`.
+	 */
+	localCapacity?(): LocalCapacity;
 	/**
 	 * Fleet node registry backing multi-node placement: per-node states,
 	 * capacity accounting, and channel-failure classification. Optional so

package/src/domains/scheduling/extension.ts

@@ -11,17 +11,23 @@ import type { DomainBundle, DomainContext, DomainExtension } from "../../core/do
 import type { ConfigContract } from "../config/contract.js";
 import type { ObservabilityContract } from "../observability/contract.js";
 import { createBudgetState } from "./budget.js";
-import { createFleetRegistry } from "./cluster.js";
+import { createFleetRegistry, LOCAL_NODE_ID } from "./cluster.js";
 import type { SchedulingContract } from "./contract.js";
+import {
+	createLocalCapacitySampler,
+	type LocalCapacitySamplerOptions,
+	resolveGlobalConcurrency,
+} from "./local-capacity.js";
 
-const DEFAULT_MAX_WORKERS = 4;
-
-function resolveMaxWorkers(concurrency: "auto" | number): number {
-	if (concurrency === "auto") return DEFAULT_MAX_WORKERS;
-	return Math.max(1, concurrency);
+export interface SchedulingBundleOptions {
+	/** Host sampling seams for `fleet.concurrency: auto`; tests inject facts and a clock. */
+	localCapacity?: Omit<LocalCapacitySamplerOptions, "activeLocalWorkers">;
 }
 
-export function createSchedulingBundle(context: DomainContext): DomainBundle<SchedulingContract> {
+export function createSchedulingBundle(
+	context: DomainContext,
+	options: SchedulingBundleOptions = {},
+): DomainBundle<SchedulingContract> {
 	const maybeConfig = context.getContract<ConfigContract>("config");
 	if (!maybeConfig) throw new Error("scheduling domain requires 'config' contract");
 	const config: ConfigContract = maybeConfig;
@@ -29,8 +35,12 @@ export function createSchedulingBundle(context: DomainContext): DomainBundle<Sch
 
 	const settings = config.get();
 	let budget = createBudgetState(settings.safety.limits.sessionCostUsd);
+	const localCapacity = createLocalCapacitySampler({
+		...options.localCapacity,
+		activeLocalWorkers: () => fleet.activeWorkers(LOCAL_NODE_ID),
+	});
 	const fleet = createFleetRegistry(() => config.get().fleet?.nodes ?? [], {
-		localMaxWorkers: () => resolveMaxWorkers(config.get().fleet.concurrency),
+		localCapacity: () => localCapacity.resolve(config.get().fleet.concurrency),
 	});
 	const unsubscribes: Array<() => void> = [];
 
@@ -83,7 +93,8 @@ export function createSchedulingBundle(context: DomainContext): DomainBundle<Sch
 			const { verdict, currentUsd } = evaluate();
 			return { verdict, currentUsd, ceilingUsd: budget.ceilingUsd };
 		},
-		maxWorkers: () => resolveMaxWorkers(config.get().fleet.concurrency),
+		maxWorkers: () => resolveGlobalConcurrency(config.get().fleet.concurrency),
+		localCapacity: () => localCapacity.resolve(config.get().fleet.concurrency),
 		fleet,
 	};
 

package/src/domains/scheduling/local-capacity.ts

@@ -0,0 +1,160 @@
+/**
+ * The one resolver for `fleet.concurrency`.
+ *
+ * A numeric setting is the exact worker limit for both the global pool and the
+ * local node. `auto` sizes only the local node from host facts: usable CPUs,
+ * available memory, and a cgroup memory limit when one is set, so a job inside
+ * a batch allocation is not sized from the whole machine. The global pool under
+ * `auto` resolves to the upper cap, because SSH nodes carry their own
+ * `maxWorkers` and a small orchestrator host must not shrink remote work.
+ *
+ * Memory held by Clio's own running local workers is added back so the limit
+ * does not collapse as the fleet it admits starts, and host facts are sampled
+ * at most once per interval.
+ */
+
+import { availableParallelism, freemem, totalmem } from "node:os";
+
+/** Which input decided the worker limit. */
+export type LocalCapacityBound = "configured" | "cpu" | "memory" | "cgroup" | "cap";
+
+export interface LocalCapacity {
+	limit: number;
+	bound: LocalCapacityBound;
+}
+
+export interface HostCapacityFacts {
+	/** Usable CPUs for this process; respects affinity masks such as a Slurm cpuset. */
+	cpus: number;
+	/** Host memory available to new processes (Linux MemAvailable). */
+	availableMemoryBytes: number;
+	/** Memory still available inside the cgroup limit; null when no limit is set. */
+	cgroupAvailableBytes: number | null;
+}
+
+/**
+ * Upper bound for `auto`, and the global pool under `auto`. Inference is bounded
+ * separately by per-endpoint slot limits, so this caps process fan-out only.
+ */
+export const AUTO_MAX_WORKERS = 8;
+
+/**
+ * Planning estimate per worker process. Observed worker RSS is 160 to 270 MB,
+ * but workers run compilers, type checkers, and test suites whose children
+ * routinely take several hundred MB more, so the estimate sits near four times
+ * the observed worker alone.
+ */
+export const WORKER_MEMORY_ESTIMATE_BYTES = 1024 * 1024 * 1024;
+
+/** Memory left for the OS, the orchestrator, and local inference servers. */
+export const OS_MEMORY_RESERVE_BYTES = 2 * 1024 * 1024 * 1024;
+
+/** Minimum spacing between host samples. */
+export const HOST_SAMPLE_INTERVAL_MS = 30_000;
+
+/** Global worker pool for a `fleet.concurrency` setting. */
+export function resolveGlobalConcurrency(configured: "auto" | number | undefined): number {
+	if (configured === undefined || configured === "auto") return AUTO_MAX_WORKERS;
+	return Math.max(1, Math.floor(configured));
+}
+
+function workersFor(bytes: number): number {
+	return Math.max(1, Math.floor((bytes - OS_MEMORY_RESERVE_BYTES) / WORKER_MEMORY_ESTIMATE_BYTES));
+}
+
+/**
+ * Local node limit for a `fleet.concurrency` setting. `clioHeldBytes` is memory
+ * Clio's running local workers held when the facts were sampled; it is added
+ * back so admitted workers do not count against their own fleet.
+ */
+export function resolveLocalConcurrency(
+	configured: "auto" | number | undefined,
+	facts: HostCapacityFacts,
+	clioHeldBytes = 0,
+): LocalCapacity {
+	if (configured !== undefined && configured !== "auto")
+		return { limit: resolveGlobalConcurrency(configured), bound: "configured" };
+	// Ties report the earlier input, so a host that fits the cap reports the cap.
+	const candidates: LocalCapacity[] = [
+		{ limit: AUTO_MAX_WORKERS, bound: "cap" },
+		{ limit: Math.max(1, Math.floor(facts.cpus)), bound: "cpu" },
+		{ limit: workersFor(facts.availableMemoryBytes + clioHeldBytes), bound: "memory" },
+	];
+	if (facts.cgroupAvailableBytes !== null)
+		candidates.push({ limit: workersFor(facts.cgroupAvailableBytes + clioHeldBytes), bound: "cgroup" });
+	let best = candidates[0] as LocalCapacity;
+	for (const candidate of candidates) if (candidate.limit < best.limit) best = candidate;
+	return best;
+}
+
+/**
+ * One short phrase naming what binds an `auto` limit, or null when the limit is
+ * the configured number or the cap.
+ */
+export function describeLocalCapacity(capacity: LocalCapacity): string | null {
+	if (capacity.bound === "configured" || capacity.bound === "cap") return null;
+	return `${capacity.bound}-bound at ${capacity.limit}`;
+}
+
+/** Read this process's host facts. Tests inject facts instead of calling this. */
+export function observeHostCapacityFacts(): HostCapacityFacts {
+	const available = freemem();
+	// constrainedMemory() reports an unbounded sentinel (or 0) when no cgroup
+	// limit applies; only a limit below physical memory constrains anything.
+	// availableMemory() is then the headroom left inside that limit.
+	const constrained = process.constrainedMemory();
+	const limited = Number.isFinite(constrained) && constrained > 0 && constrained < totalmem();
+	return {
+		cpus: availableParallelism(),
+		availableMemoryBytes: available,
+		cgroupAvailableBytes: limited ? process.availableMemory() : null,
+	};
+}
+
+export interface LocalCapacitySamplerOptions {
+	observe?: () => HostCapacityFacts;
+	/** Clio workers currently leased on the local node. */
+	activeLocalWorkers: () => number;
+	monotonicNow?: () => number;
+	intervalMs?: number;
+}
+
+export interface LocalCapacitySampler {
+	resolve(configured: "auto" | number | undefined): LocalCapacity;
+}
+
+interface HostSample {
+	facts: HostCapacityFacts;
+	activeWorkers: number;
+	/** Last time host facts and the active-worker count were sampled together. */
+	checkedAtMs: number;
+}
+
+/**
+ * Rate-limited host sampling for `auto`, including while workers run. Each
+ * sample captures its active-worker count so the add-back accounts for workers
+ * included in those memory facts, not workers admitted after the sample.
+ */
+export function createLocalCapacitySampler(options: LocalCapacitySamplerOptions): LocalCapacitySampler {
+	const observe = options.observe ?? observeHostCapacityFacts;
+	const monotonicNow = options.monotonicNow ?? (() => performance.now());
+	const intervalMs = options.intervalMs ?? HOST_SAMPLE_INTERVAL_MS;
+	let sample: HostSample | null = null;
+
+	function current(): HostSample {
+		const atMs = monotonicNow();
+		if (sample !== null && atMs - sample.checkedAtMs < intervalMs) return sample;
+		const activeWorkers = options.activeLocalWorkers();
+		sample = { facts: observe(), activeWorkers, checkedAtMs: atMs };
+		return sample;
+	}
+
+	return {
+		resolve(configured) {
+			if (configured !== undefined && configured !== "auto")
+				return { limit: resolveGlobalConcurrency(configured), bound: "configured" };
+			const { facts, activeWorkers } = current();
+			return resolveLocalConcurrency("auto", facts, activeWorkers * WORKER_MEMORY_ESTIMATE_BYTES);
+		},
+	};
+}

package/src/domains/session/context-accounting.ts

@@ -56,6 +56,7 @@ export interface ContextSnapshot {
 	categories: {
 		system: number;
 		tools: number;
+		toolResults?: number;
 		agents: number;
 		skills: number;
 		memory: number;
@@ -248,7 +249,10 @@ export function estimateAgentMessageTokens(message: MessageTokenEstimateInput):
 export function estimateAgentContextBreakdown(input: AgentContextEstimateInput): ContextUsageBreakdown {
 	return {
 		systemPromptTokens: input.systemPrompt ? ceilChars(input.systemPrompt.length) : 0,
-		messageTokens: input.messages.reduce((sum, message) => sum + estimateAgentMessageTokens(message), 0),
+		messageTokens: input.messages.reduce(
+			(sum, message) => sum + (message.role === "system" ? 0 : estimateAgentMessageTokens(message)),
+			0,
+		),
 		pendingUserTokens: input.pendingUserText ? ceilChars(input.pendingUserText.length) : 0,
 		toolSchemaTokens: (input.tools ?? []).reduce<number>((sum, tool) => sum + ceilChars(toolSchemaChars(tool)), 0),
 	};
@@ -263,7 +267,7 @@ export function estimateAgentContextTokens(input: AgentContextEstimateInput): nu
 	if (!usage) return projection;
 	const trailingTokens = input.messages
 		.slice(usage.index + 1)
-		.reduce((sum, message) => sum + estimateAgentMessageTokens(message), 0);
+		.reduce((sum, message) => sum + (message.role === "system" ? 0 : estimateAgentMessageTokens(message)), 0);
 	const anchored = usage.tokens + trailingTokens + breakdown.pendingUserTokens + breakdown.toolSchemaTokens;
 	return Math.max(projection, anchored);
 }
@@ -381,6 +385,7 @@ function buildSnapshotCategories(inputs: {
 	const raw: {
 		system: number;
 		tools: number;
+		toolResults: number;
 		agents: number;
 		skills: number;
 		memory: number;
@@ -390,6 +395,7 @@ function buildSnapshotCategories(inputs: {
 	} = {
 		system: 0,
 		tools: 0,
+		toolResults: 0,
 		agents: 0,
 		skills: 0,
 		memory: 0,
@@ -414,7 +420,9 @@ function buildSnapshotCategories(inputs: {
 
 	if (inputs.messages) {
 		for (const msg of inputs.messages) {
-			raw.messages += estimateAgentMessageTokens(msg as MessageTokenEstimateInput);
+			const message = msg as MessageTokenEstimateInput;
+			const bucket = message.role === "toolResult" ? "toolResults" : "messages";
+			raw[bucket] += estimateAgentMessageTokens(message);
 		}
 	}
 
@@ -432,6 +440,7 @@ function buildSnapshotCategories(inputs: {
 	return {
 		system: raw.system,
 		tools: raw.tools,
+		toolResults: raw.toolResults,
 		agents: raw.agents,
 		skills: raw.skills,
 		memory: raw.memory,
@@ -463,7 +472,16 @@ export interface CaptureContextSnapshotInput {
 	toolSignature?: string | undefined;
 }
 
-const SNAPSHOT_SPLIT_KEYS = ["system", "tools", "agents", "skills", "memory", "project", "messages"] as const;
+const SNAPSHOT_SPLIT_KEYS = [
+	"system",
+	"tools",
+	"agents",
+	"skills",
+	"memory",
+	"project",
+	"messages",
+	"toolResults",
+] as const;
 
 function estimatedSplitSources(): Record<string, "estimated" | "exact" | "reconciled"> {
 	const splits: Record<string, "estimated" | "exact" | "reconciled"> = {};
@@ -561,33 +579,28 @@ export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): Cont
 	}
 
 	const keys = SNAPSHOT_SPLIT_KEYS;
-	const currentCategories = { ...snapshot.categories };
-	const sum = keys.reduce((s, k) => s + (currentCategories[k] ?? 0), 0);
-
-	let normalized: Record<string, number>;
-	if (sum === 0) {
-		normalized = keys.reduce(
-			(acc, k) => {
-				acc[k] = k === "messages" ? exactInput : 0;
-				return acc;
-			},
-			{} as Record<string, number>,
-		);
-	} else {
-		normalized = {};
-		let newSum = 0;
-		for (const key of keys) {
-			const val = currentCategories[key] ?? 0;
-			const norm = Math.round((val / sum) * exactInput);
-			normalized[key] = norm;
-			newSum += norm;
-		}
-		const diff = exactInput - newSum;
-		if (diff !== 0) {
-			const largestKey = keys.reduce((a, b) => ((normalized[a] ?? 0) >= (normalized[b] ?? 0) ? a : b));
-			normalized[largestKey] = (normalized[largestKey] ?? 0) + diff;
-		}
+
+	// Provider totals do not measure individual categories. Keep the compiled
+	// prefix estimates stable as conversation grows; never assign result growth
+	// to tool definitions. If the measured prompt is smaller than the prefix
+	// estimate, proportionally cap that estimate to the available total.
+	const normalized: Record<string, number> = {};
+	const staticKeys = keys.filter((key) => key !== "messages" && key !== "toolResults");
+	const staticSum = staticKeys.reduce((sum, key) => sum + (snapshot.categories[key] ?? 0), 0);
+	const scale = staticSum > exactInput ? exactInput / staticSum : 1;
+	let prefix = 0;
+	for (const key of staticKeys) {
+		normalized[key] = Math.floor((snapshot.categories[key] ?? 0) * scale);
+		prefix += normalized[key] ?? 0;
 	}
+	const remaining = exactInput - prefix;
+	const resultEstimate = snapshot.categories.toolResults ?? 0;
+	const conversationEstimate = resultEstimate + snapshot.categories.messages;
+	const conversationScale = conversationEstimate > remaining ? remaining / conversationEstimate : 1;
+	normalized.toolResults = Math.floor(resultEstimate * conversationScale);
+	// Includes unclassified provider framing / tokenizer differences; this is
+	// a residual, not a claim that the provider measured message categories.
+	normalized.messages = remaining - normalized.toolResults;
 
 	const updatedCategories = {
 		...snapshot.categories,
@@ -609,7 +622,7 @@ export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): Cont
 
 	const splitsSources = keys.reduce(
 		(acc, k) => {
-			acc[k] = "reconciled";
+			acc[k] = k === "messages" ? "reconciled" : "estimated";
 			return acc;
 		},
 		{} as Record<string, "estimated" | "exact" | "reconciled">,