@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/resources/prompts/loader.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { parseCommandArgs, substituteArgs } from "../../../engine/prompt-templates.js";
@@ -13,7 +13,6 @@ import {
 import {
 	COMPAT_RESOURCE_PRECEDENCE,
 	defaultScopedResourceRoots,
-	readRootEntries,
 	sourceInfoForRoot,
 	splitYamlFrontmatter,
 	stringField,
@@ -28,11 +27,21 @@ export interface PromptTemplate {
 	sourceInfo: ResourceSourceInfo;
 	/** False for a project compatibility root until the operator opts in; such a template refuses to expand. */
 	trusted: boolean;
+	/**
+	 * Why this template cannot be expanded, when a load-time failure left it
+	 * with no usable body. It is loaded anyway, so the namespaced command is
+	 * recognized and invoking it reports this reason instead of "not a command"
+	 * (issue #245). `content` is empty on such a template and nothing may send
+	 * it to a model.
+	 */
+	unavailable?: string;
 	argumentHint?: string;
 }
 
 export interface PromptTemplateRoot {
 	path: string;
+	/** Present only for an installed extension resource root. */
+	rootPath?: string;
 	scope: ResourceScope;
 	source?: string;
 	precedence?: number;
@@ -139,6 +148,95 @@ function fallbackDescription(body: string): string {
 	return normalized.length > 60 ? `${normalized.slice(0, 57)}...` : normalized;
 }
 
+// Keep the suffix deliberately conservative. Prompt prose commonly places a
+// comma, parenthesis, or full stop immediately after an @path; treating that
+// punctuation as part of the filesystem reference makes a valid template look
+// unresolved. Extension bundles use portable path components, so these are the
+// only characters needed in a reference while still allowing `..` to be
+// detected and rejected by the containment check below.
+const EXTENSION_ROOT_REFERENCE = /\$\{extensionRoot\}(\/[A-Za-z0-9._~%+@/-]*)?/g;
+const EXTENSION_ROOT_TOKEN = "$" + "{extensionRoot}";
+
+function contained(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+/**
+ * The outcome of a step that may leave the template with no usable body.
+ * `reason` is the one sentence that becomes both the diagnostic the `/prompts`
+ * overlay renders and the refusal the operator gets when they invoke the
+ * command, so the two can never disagree.
+ */
+type BodyResolution = { body: string } | { reason: string };
+
+/**
+ * Resolve only existing paths contained by the declaring extension package.
+ *
+ * The safety half is unchanged: a missing or escaping reference never expands
+ * and never reads outside the package. What changed is what the caller does
+ * with the failure, which used to be dropping the template entirely.
+ */
+function resolveExtensionReferences(body: string, root: PromptTemplateRoot): BodyResolution {
+	if (root.rootPath === undefined || !body.includes(EXTENSION_ROOT_TOKEN)) return { body };
+	let canonicalRoot: string;
+	try {
+		canonicalRoot = realpathSync(root.rootPath);
+	} catch (error) {
+		return { reason: `extension root could not be resolved: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	let invalid: string | null = null;
+	const resolved = body.replace(EXTENSION_ROOT_REFERENCE, (reference, suffix: string | undefined) => {
+		const candidate = path.resolve(canonicalRoot, `.${suffix ?? ""}`);
+		try {
+			const canonicalCandidate = realpathSync(candidate);
+			if (!contained(canonicalRoot, canonicalCandidate)) invalid = reference;
+		} catch {
+			invalid = reference;
+		}
+		return candidate;
+	});
+	if (invalid !== null) {
+		return { reason: `prompt template has an unresolved or escaping extension reference: ${invalid}` };
+	}
+	return { body: resolved };
+}
+
+/**
+ * A template that exists and cannot run.
+ *
+ * Dropping it made the operator's namespaced command answer "not a command",
+ * so an extension author's single bad `${extensionRoot}` path read to their
+ * users as "the prompt was never installed" (issue #245). The template is
+ * loaded with an empty body and the reason attached instead, which is the same
+ * shape an untrusted project template already had, so the existing refusal
+ * path carries it to the operator with no new machinery.
+ */
+function unavailableTemplate(
+	name: string,
+	filePath: string,
+	root: PromptTemplateRoot,
+	reason: string,
+	diagnostics: ResourceDiagnostic[],
+	description?: string,
+): ResourceCandidate<PromptTemplate> {
+	diagnostics.push({ type: "warning", message: reason, path: filePath });
+	const sourceInfo: ResourceSourceInfo = sourceInfoForRoot(root, filePath);
+	return {
+		name,
+		value: {
+			name,
+			description: description ?? "Prompt template (unavailable)",
+			content: "",
+			filePath,
+			sourceInfo,
+			trusted: root.trusted !== false,
+			unavailable: `${reason} (${filePath})`,
+		},
+		source: sourceInfo,
+	};
+}
+
 function loadPromptFile(
 	filePath: string,
 	root: PromptTemplateRoot,
@@ -146,25 +244,45 @@ function loadPromptFile(
 ): ResourceCandidate<PromptTemplate> | null {
 	const ext = path.extname(filePath).toLowerCase();
 	if (ext !== ".md") return null;
+
+	// The name comes before the read, so a file that exists but cannot be read
+	// still has a command the operator can invoke and be told why.
+	const relativePath = path.relative(root.path, filePath);
+	if (
+		relativePath === "" ||
+		relativePath === ".." ||
+		relativePath.startsWith(`..${path.sep}`) ||
+		path.isAbsolute(relativePath)
+	) {
+		// The one failure that stays a drop: the path is outside the discovery
+		// root, so there is no name here to offer a command under.
+		diagnostics.push({ type: "warning", message: "prompt template escaped its discovery root", path: filePath });
+		return null;
+	}
+	const name = relativePath.slice(0, -ext.length).split(path.sep).join(":");
+	if (name.trim().length === 0) return null;
+
 	let raw: string;
 	try {
 		raw = readFileSync(filePath, "utf8");
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
-		diagnostics.push({ type: "warning", message: `prompt template could not be read: ${reason}`, path: filePath });
-		return null;
+		return unavailableTemplate(name, filePath, root, `prompt template could not be read: ${reason}`, diagnostics);
 	}
 
-	const name = path.basename(filePath, ext);
-	if (name.trim().length === 0) return null;
 	const { frontmatter, body } = splitOptionalFrontmatter(raw, filePath, diagnostics);
-	const description = stringField(frontmatter, "description") ?? fallbackDescription(body);
+	const declaredDescription = stringField(frontmatter, "description");
+	const resolution = resolveExtensionReferences(body, root);
+	if ("reason" in resolution) {
+		return unavailableTemplate(name, filePath, root, resolution.reason, diagnostics, declaredDescription ?? undefined);
+	}
+	const description = declaredDescription ?? fallbackDescription(resolution.body);
 	const argumentHint = stringField(frontmatter, "argument-hint") ?? stringField(frontmatter, "argumentHint");
 	const sourceInfo: ResourceSourceInfo = sourceInfoForRoot(root, filePath);
 	const template: PromptTemplate = {
 		name,
 		description,
-		content: body.trim(),
+		content: resolution.body.trim(),
 		filePath,
 		sourceInfo,
 		trusted: root.trusted !== false,
@@ -178,10 +296,42 @@ function loadPromptRoot(
 	diagnostics: ResourceDiagnostic[],
 ): ResourceCandidate<PromptTemplate>[] {
 	const candidates: ResourceCandidate<PromptTemplate>[] = [];
-	for (const entry of readRootEntries(root, "prompt template", diagnostics)) {
-		if (!entry.isFile()) continue;
-		const candidate = loadPromptFile(path.join(root.path, entry.name), root, diagnostics);
-		if (candidate) candidates.push(candidate);
+	const pending = [root.path];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		if (!directory) continue;
+		let entries: import("node:fs").Dirent[];
+		try {
+			const stat = lstatSync(directory);
+			if (stat.isSymbolicLink() || !stat.isDirectory()) {
+				diagnostics.push({
+					type: "warning",
+					message: "prompt template root contains a non-directory or symbolic link",
+					path: directory,
+				});
+				continue;
+			}
+			entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+			diagnostics.push({
+				type: "warning",
+				message: `prompt template directory could not be read: ${error instanceof Error ? error.message : String(error)}`,
+				path: directory,
+			});
+			continue;
+		}
+		for (const entry of [...entries].reverse()) {
+			const filePath = path.join(directory, entry.name);
+			if (entry.isSymbolicLink()) {
+				diagnostics.push({ type: "warning", message: "prompt template symbolic link was ignored", path: filePath });
+			} else if (entry.isDirectory()) {
+				pending.push(filePath);
+			} else if (entry.isFile()) {
+				const candidate = loadPromptFile(filePath, root, diagnostics);
+				if (candidate) candidates.push(candidate);
+			}
+		}
 	}
 	return candidates;
 }
@@ -210,13 +360,18 @@ export function loadPromptTemplates(input: LoadPromptTemplatesInput = {}): Promp
 }
 
 function parsePromptCommand(input: string): { name: string; rest: string } | null {
-	const trimmed = input.trim();
-	if (!trimmed.startsWith("/")) return null;
-	const withoutSlash = trimmed.slice(1);
+	const framed = input.trimStart();
+	if (!framed.startsWith("/")) return null;
+	const withoutSlash = framed.slice(1);
 	const separator = withoutSlash.search(/\s/);
 	const name = separator === -1 ? withoutSlash : withoutSlash.slice(0, separator);
 	if (name.length === 0 || name.includes("/")) return null;
-	const rest = separator === -1 ? "" : withoutSlash.slice(separator).trim();
+	// Leading whitespace before `/` and the first whitespace after the command
+	// are framing. A CRLF pair is one delimiter. Every subsequent byte belongs
+	// to the argument payload, including indentation, blank lines, and trailing
+	// whitespace, so raw `$ARGUMENTS` substitution can be exact at its boundary.
+	const delimiterWidth = separator !== -1 && withoutSlash.slice(separator, separator + 2) === "\r\n" ? 2 : 1;
+	const rest = separator === -1 ? "" : withoutSlash.slice(separator + delimiterWidth);
 	return { name, rest };
 }
 
@@ -225,6 +380,18 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 	if (!command) return { expanded: false, text: input, args: [], diagnostics: templates.diagnostics };
 	const template = templates.items.find((entry) => entry.name === command.name);
 	if (!template) return { expanded: false, text: input, args: [], diagnostics: templates.diagnostics };
+	// A load-time failure refuses before anything else, and before the trust
+	// check, because there is no body here to be trusted or untrusted.
+	if (template.unavailable !== undefined) {
+		const message = `prompt template /${template.name} cannot run: ${template.unavailable}`;
+		return {
+			expanded: false,
+			text: input,
+			args: [],
+			diagnostics: templates.diagnostics,
+			refusal: { template, message },
+		};
+	}
 	if (!template.trusted) {
 		const message = `prompt template ${template.name} comes from an untrusted project root; set skills.trustProjectCompatRoots to use it`;
 		return {
@@ -238,7 +405,7 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 	const args = parseCommandArgs(command.rest);
 	return {
 		expanded: true,
-		text: substituteArgs(template.content, args),
+		text: substituteArgs(template.content, args, command.rest),
 		args,
 		template,
 		diagnostics: templates.diagnostics,

package/src/domains/safety/call-target.ts

@@ -31,6 +31,58 @@ function oneLine(value: string): string {
 	return value.replace(/\s+/g, " ").trim();
 }
 
+/** Columns one tab occupies when a multi-line surface expands it. */
+const DISPLAY_TAB_WIDTH = 4;
+
+/** Stands in for a control byte that was neutralized, so the cut is visible. */
+const CONTROL_BYTE_PLACEHOLDER = "·";
+
+export interface SanitizedDisplayText {
+	text: string;
+	/** A control byte or escape sequence was neutralized. */
+	neutralized: boolean;
+	/** A tab was expanded, so column positions are display positions. */
+	tabsExpanded: boolean;
+}
+
+/**
+ * Neutralize escape sequences and control bytes while keeping line structure.
+ * {@link sanitizeCallTargetText} is the one-line form for a card; this is the
+ * form a multi-line operator surface needs, where the newlines are the content
+ * rather than whitespace to collapse. Tabs become spaces because a bordered
+ * frame measures visible width and a literal tab makes that measurement a lie.
+ * Every other C0 byte and DEL becomes a visible placeholder, so a payload
+ * cannot style, reposition, or spoof the surface that is approving it.
+ */
+export function sanitizeMultilineDisplayText(value: string): SanitizedDisplayText {
+	const escapesStripped = value.replace(OSC_PATTERN, "").replace(CSI_PATTERN, "");
+	let neutralized = escapesStripped.length !== value.length;
+	// CRLF is line structure, not an injection, so it normalizes rather than
+	// showing a placeholder at the end of every line of a Windows-authored file.
+	const stripped = escapesStripped.replace(/\r\n/g, "\n");
+	let tabsExpanded = false;
+	let out = "";
+	for (const ch of stripped) {
+		if (ch === "\n") {
+			out += ch;
+			continue;
+		}
+		if (ch === "\t") {
+			out += " ".repeat(DISPLAY_TAB_WIDTH);
+			tabsExpanded = true;
+			continue;
+		}
+		const code = ch.codePointAt(0) ?? 0;
+		if (code < 0x20 || code === 0x7f) {
+			out += CONTROL_BYTE_PLACEHOLDER;
+			neutralized = true;
+			continue;
+		}
+		out += ch;
+	}
+	return { text: out, neutralized, tabsExpanded };
+}
+
 /**
  * Neutralize escape sequences and control bytes in a pre-composed target
  * string and collapse it to one line. Used where a description crosses a

package/src/domains/safety/policy-engine.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { artifactDefaultPath } from "../../core/artifact-paths.js";
+import { pathBoundaryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { ToolNames } from "../../core/tool-names.js";
 import { clioConfigDir } from "../../core/xdg.js";
@@ -89,7 +90,8 @@ export interface SafetyPolicyEngineOptions {
 	rulePacks?: RulePacks;
 	projectPolicy?: LoadedProjectSafetyPolicy;
 	/**
-	 * Absolute directories a write-class tool call is confined to for this run.
+	 * Absolute path boundaries a write-class tool call is confined to for this run.
+	 * Exact files omit a trailing slash and subtrees retain one.
 	 * When present and non-empty, a write/edit target outside every root is a
 	 * final BLOCK (reason code "write-root"). Empty or absent disables the check.
 	 * Enforced at the worker safety seam so both the native worker registry and
@@ -182,9 +184,7 @@ function evaluateWriteRoots(roots: ReadonlyArray<string>, writeRootCwd: string,
 	const target = writeRootTargetPath(call);
 	if (target === null) return null;
 	const resolved = path.resolve(writeRootCwd, target);
-	for (const root of roots) {
-		if (resolved === root || resolved.startsWith(`${root}${path.sep}`)) return null;
-	}
+	if (pathBoundaryCovers(roots, resolved)) return null;
 	return `write target '${target}' resolves to '${resolved}', which is outside the permitted write roots for this run: ${roots.join(", ")}`;
 }
 
@@ -193,7 +193,7 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 	// Write-root containment resolves lexically, so it keeps its own un-canonicalized
 	// cwd and roots to compare like against like (the design mandates no symlink chasing).
 	const writeRootCwd = path.resolve(options.cwd ?? process.cwd());
-	const writeRoots = (options.writeRoots ?? []).map((root) => path.resolve(root));
+	const writeRoots = (options.writeRoots ?? []).map((root) => resolvePathBoundary(writeRootCwd, root));
 	const packs = options.rulePacks ?? getCachedDefaultRulePacks();
 	const projectPolicy = options.projectPolicy ?? loadProjectSafetyPolicy(cwd);
 	const projectPolicyRoot =

package/src/domains/safety/run-effects.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { ToolNames } from "../../core/tool-names.js";
+import { classify } from "./action-classifier.js";
 import { typedValidationSummary } from "./finish-contract.js";
 import {
 	detectValidationCommand,
@@ -25,6 +26,13 @@ import {
  * bash command that writes through a script) leaves the path absent from the
  * set and the validator falls back to the filesystem rather than to a failed
  * conformance.
+ *
+ * `writeRecordComplete` is the other half of that sentence, and it exists for
+ * the reader that cannot fall back to the filesystem. The write boundary uses
+ * this record the other way round, to decide that a path the run did *not*
+ * write is somebody else's and must survive. Reading an under-reporting set as
+ * a closed list would clear a step of a write it really made, so the recorder
+ * says outright whether the set is closed.
  */
 export interface RunEffects {
 	/** Absolute paths the run's successful tool calls aimed a mutation at. */
@@ -56,6 +64,35 @@ export interface RunEffects {
 	 * wider set.
 	 */
 	verificationCommands: ReadonlySet<string>;
+	/**
+	 * False once the run made a successful call to a tool that can mutate a path
+	 * its own arguments do not name. After such a call `mutatedPaths` is a lower
+	 * bound rather than the whole list, so a reader that would treat an absent
+	 * path as proof the run did not write it has to stop treating it that way.
+	 *
+	 * The downgrade covers the whole run rather than the one call, because an
+	 * opaque call's effect is unbounded. A shell command, a project script, or a
+	 * spawned worker can write anywhere the process can reach, so once one has
+	 * run there is no path left in the checkout that the record can clear.
+	 */
+	writeRecordComplete: boolean;
+	/**
+	 * Successful opaque calls that made the write record incomplete. The call id
+	 * and tool name are retained so a later write-boundary verdict can explain
+	 * exactly why attribution was downgraded instead of exposing only a boolean.
+	 */
+	writeRecordDowngrades: ReadonlyArray<WriteRecordDowngrade>;
+}
+
+export interface WriteRecordDowngrade {
+	reason: "opaque_tool_succeeded";
+	tool: string;
+	toolCallId: string;
+}
+
+export interface RunEffectsRecorderOptions {
+	/** Fires once, when the first successful opaque call opens the record. */
+	onWriteRecordDowngraded?(downgrade: WriteRecordDowngrade): void;
 }
 
 export interface RunEffectsRecorder {
@@ -67,9 +104,44 @@ export interface RunEffectsRecorder {
 }
 
 interface PendingEffects {
+	tool: string;
+	toolCallId: string;
 	paths: ReadonlyArray<string>;
 	validationCommand: string | null;
 	verificationCommand: string | null;
+	opaque: boolean;
+}
+
+/**
+ * Action classes whose successful calls write only paths their own arguments
+ * name. `read` covers the observe, retrieve, interact, and orchestrate-bookkeeping
+ * tools, none of which touch a source-workspace file: `git` is a closed
+ * status/diff/log surface, and `tasks`, `ledger`, and `context` write Clio's own
+ * state. `write` covers `write`, `edit`, and `artifact`, whose target
+ * `toolMutationPaths` resolves from the call itself, including the artifact
+ * tool's default path.
+ */
+const ENUMERABLE_ACTION_CLASSES: ReadonlySet<string> = new Set(["read", "write"]);
+
+/**
+ * Whether a successful call to this tool can mutate a path its own recorded
+ * arguments do not name.
+ *
+ * Asked of the classifier rather than of a hand-written list, because
+ * `src/tools/policy.ts` asserts at bootstrap that every registered tool's
+ * `baseActionClass` equals what this classifier returns and what the plane
+ * table declares. A tool added to the execute or orchestrate-dispatch plane is
+ * therefore opaque the day it is registered, with no list to remember to update.
+ *
+ * The classifier is asked about the tool name alone. Bash's argument scan can
+ * escalate a single call to `system_modify` or `git_destructive`, and those are
+ * still bash; the question here is what the tool can do, not what one call was
+ * caught doing. An unregistered name (a dynamic or MCP tool) classifies as
+ * `unknown` and is opaque, which is the fail-closed answer for a tool whose
+ * arguments this process has no schema for.
+ */
+export function toolWritesOpaquely(toolName: string): boolean {
+	return !ENUMERABLE_ACTION_CLASSES.has(classify({ tool: toolName }).actionClass);
 }
 
 /**
@@ -151,24 +223,31 @@ function validationCommandOf(
  * when its result comes back clean: a blocked write and a red command are not
  * evidence that the workspace changed or that a check passed.
  */
-export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
+export function createRunEffectsRecorder(cwd: string, options: RunEffectsRecorderOptions = {}): RunEffectsRecorder {
 	const pending = new Map<string, PendingEffects>();
 	const mutatedPaths = new Set<string>();
 	const failedMutationPaths = new Set<string>();
 	const validationCommands = new Set<string>();
 	const verificationCommands = new Set<string>();
+	const writeRecordDowngrades = new Map<string, WriteRecordDowngrade>();
 	return {
 		start(toolCallId, toolName, args) {
 			const paths = mutationTargets(toolName, args);
 			const validationCommand = validationCommandOf(toolName, args, "finish-contract");
 			const verificationCommand = validationCommandOf(toolName, args, "grounding");
-			if (paths.length === 0 && validationCommand === null && verificationCommand === null) return;
+			const opaque = toolWritesOpaquely(toolName);
+			// An opaque call is tracked even when it exposed no path and no
+			// command, because the fact that it ran at all is the finding.
+			if (!opaque && paths.length === 0 && validationCommand === null && verificationCommand === null) return;
 			// A bash call may re-base its relative paths with its own cwd argument.
 			const base = typeof args?.cwd === "string" && args.cwd.length > 0 ? path.resolve(cwd, args.cwd) : cwd;
 			pending.set(toolCallId, {
+				tool: toolName,
+				toolCallId,
 				paths: paths.map((target) => path.resolve(base, target)),
 				validationCommand,
 				verificationCommand,
+				opaque,
 			});
 		},
 		finish(toolCallId, failed) {
@@ -179,6 +258,19 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 				for (const target of effects.paths) failedMutationPaths.add(target);
 				return;
 			}
+			// Success-gated on purpose. A shell command the safety policy blocked,
+			// or one that came back an error, never reached the filesystem, so it
+			// leaves the record closed.
+			if (effects.opaque) {
+				const downgrade: WriteRecordDowngrade = {
+					reason: "opaque_tool_succeeded",
+					tool: effects.tool,
+					toolCallId: effects.toolCallId,
+				};
+				const recordWasComplete = writeRecordDowngrades.size === 0;
+				writeRecordDowngrades.set(effects.toolCallId, downgrade);
+				if (recordWasComplete) options.onWriteRecordDowngraded?.({ ...downgrade });
+			}
 			for (const target of effects.paths) mutatedPaths.add(target);
 			if (effects.validationCommand !== null) validationCommands.add(effects.validationCommand);
 			if (effects.verificationCommand !== null) verificationCommands.add(effects.verificationCommand);
@@ -191,6 +283,8 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 				failedMutationPaths: new Set([...failedMutationPaths].filter((target) => !mutatedPaths.has(target))),
 				validationCommands: new Set(validationCommands),
 				verificationCommands: new Set(verificationCommands),
+				writeRecordComplete: writeRecordDowngrades.size === 0,
+				writeRecordDowngrades: [...writeRecordDowngrades.values()].map((entry) => ({ ...entry })),
 			};
 		},
 	};

package/src/domains/safety/scope.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { asDirectoryPathBoundary, pathBoundaryEntryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
 import type { ActionClass } from "./action-classifier.js";
 
 /**
@@ -15,15 +16,7 @@ export interface ScopeSpec {
 }
 
 function normalizeRoot(root: string): string {
-	return path.resolve(root);
-}
-
-function isUnder(child: string, parent: string): boolean {
-	const c = normalizeRoot(child);
-	const p = normalizeRoot(parent);
-	if (c === p) return true;
-	const rel = path.relative(p, c);
-	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+	return resolvePathBoundary(process.cwd(), root);
 }
 
 export function isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean {
@@ -31,7 +24,9 @@ export function isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean {
 		if (!orchestrator.allowedActions.has(action)) return false;
 	}
 	for (const root of worker.allowedWriteRoots) {
-		const covered = orchestrator.allowedWriteRoots.some((outer) => isUnder(root, outer));
+		const covered = orchestrator.allowedWriteRoots.some((outer) =>
+			pathBoundaryEntryCovers(normalizeRoot(outer), normalizeRoot(root)),
+		);
 		if (!covered) return false;
 	}
 	if (worker.allowNetwork && !orchestrator.allowNetwork) return false;
@@ -48,14 +43,14 @@ export const READONLY_SCOPE: ScopeSpec = {
 
 export const WORKSPACE_SCOPE: ScopeSpec = {
 	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch"]),
-	allowedWriteRoots: [process.cwd()],
+	allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
 	allowNetwork: true,
 	allowDispatch: true,
 };
 
 export const CONFIRMED_SCOPE: ScopeSpec = {
 	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch", "system_modify"]),
-	allowedWriteRoots: [process.cwd()],
+	allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
 	allowNetwork: true,
 	allowDispatch: true,
 };

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

@@ -72,6 +72,19 @@ export interface ContextSnapshot {
 		splits: Record<string, "estimated" | "exact" | "reconciled">;
 	};
 
+	/**
+	 * Divergence record. `estimatedTokens` is the chars/4 prompt-side total this
+	 * snapshot was captured with and is never rewritten by a reconcile, so the
+	 * two figures stay comparable. `reconciledTokens` is the provider's own
+	 * prompt token count for the call this snapshot was reconciled against
+	 * (cached prompt tokens folded back in), and `divergenceRatio` is
+	 * `reconciledTokens / estimatedTokens`. A ratio above 1 is the estimator
+	 * under-counting, which is what issue #227 recorded as a provider overflow.
+	 */
+	estimatedTokens?: number | undefined;
+	reconciledTokens?: number | undefined;
+	divergenceRatio?: number | undefined;
+
 	promptHash?: string | undefined;
 	toolSignature?: string | undefined;
 	messageRange?: { start: number; end: number } | undefined;
@@ -332,6 +345,31 @@ export function getLatestContextSnapshot(meta: SessionMeta): ContextSnapshot | n
 	return list.at(-1) ?? null;
 }
 
+/**
+ * The window a previous process measured this session's prompts against, when
+ * the backend itself reported it as the one it had open (issue #227).
+ *
+ * A resumed session re-resolves its target before discovery has reported a
+ * loaded window, so the first turn budgets against the probed server-wide
+ * figure, which on a multi-slot backend is a multiple of what the model is
+ * actually serving. The snapshot ledger already recorded the number the
+ * backend named, so the resume carries it forward instead of re-probing.
+ * Scoped to the same target and model: a different selection has no claim on
+ * that measurement, and a live loaded window always outranks this one, so a
+ * model reloaded at a new size corrects on the next resolution.
+ */
+export function lastLoadedContextWindow(meta: SessionMeta, providerId: string, modelId: string): number | null {
+	const snapshots = getContextSnapshots(meta);
+	for (let i = snapshots.length - 1; i >= 0; i -= 1) {
+		const snapshot = snapshots[i];
+		if (snapshot?.contextWindowSource !== "loaded") continue;
+		if (snapshot.providerId !== providerId || snapshot.modelId !== modelId) continue;
+		const window = snapshot.effectiveContextWindow;
+		if (typeof window === "number" && Number.isFinite(window) && window > 0) return window;
+	}
+	return null;
+}
+
 export function buildSnapshotCategories(inputs: {
 	systemPrompt?: string | undefined;
 	promptSegments?: ReadonlyArray<{ id: string; tokenEstimate: number }> | undefined;
@@ -456,6 +494,7 @@ export function captureContextSnapshot(input: CaptureContextSnapshotInput): Cont
 		compactionThreshold: input.compactionThreshold,
 	});
 	return {
+		estimatedTokens: sumSplitTokens(categories),
 		snapshotId: nextSnapshotId(),
 		sessionId: input.sessionId,
 		turnId: input.turnId,
@@ -480,9 +519,13 @@ export function captureContextSnapshot(input: CaptureContextSnapshotInput): Cont
 	};
 }
 
+function sumSplitTokens(categories: ContextSnapshot["categories"]): number {
+	return SNAPSHOT_SPLIT_KEYS.reduce((sum, key) => sum + (categories[key] ?? 0), 0);
+}
+
 /** Sum of the prompt-side categories (everything except reserve/free/streaming). */
 export function snapshotInputTokens(snapshot: ContextSnapshot): number {
-	return SNAPSHOT_SPLIT_KEYS.reduce((sum, key) => sum + (snapshot.categories[key] ?? 0), 0);
+	return sumSplitTokens(snapshot.categories);
 }
 
 export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): ContextSnapshot {
@@ -572,9 +615,17 @@ export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): Cont
 		{} as Record<string, "estimated" | "exact" | "reconciled">,
 	);
 
+	// The estimate this snapshot was captured with, kept whole across repeated
+	// reconciles so the recorded divergence always compares the provider count
+	// against chars/4 rather than against a previously normalized total.
+	const estimatedTokens = snapshot.estimatedTokens ?? sumSplitTokens(snapshot.categories);
+
 	return {
 		...snapshot,
 		categories: updatedCategories,
+		estimatedTokens,
+		reconciledTokens: exactInput,
+		divergenceRatio: estimatedTokens > 0 ? Math.round((exactInput / estimatedTokens) * 1000) / 1000 : undefined,
 		sources: {
 			total: "reconciled",
 			splits: splitsSources,