@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/tools/codewiki/code-nav.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, normalize } from "node:path";
+import { isAbsolute, join, normalize, relative, resolve } from "node:path";
+import { resolvePackageRoot } from "../../core/package-root.js";
 import { ToolNames } from "../../core/tool-names.js";
+import { parseCodewikiRaw } from "../../domains/context/codewiki/artifact.js";
 import type { Codewiki, CodewikiFile, CodewikiSymbol } from "../../domains/context/codewiki/schema.js";
 import { listWikiPages } from "../../domains/context/wiki/layout.js";
 import { readWikiMeta } from "../../domains/context/wiki/meta.js";
@@ -22,6 +24,14 @@ import {
 import { loadCodewikiForTool, renderJson } from "./shared.js";
 
 const REGEX_SYNTAX_HINTS = /\.\*|\.\+|\^|\$|\\[dDwWsSbB]|\(\?:|\(\?=|\(\?!/;
+const CLIO_CODEWIKI_RELATIVE_PATH = join("dist", "assets", "codewiki.json");
+
+type CodeNavSource = "workspace" | "clio";
+
+interface LoadedNavSource {
+	codewiki: Codewiki;
+	entryRoot: string | null;
+}
 
 interface NavIndex {
 	filesById: Map<string, CodewikiFile>;
@@ -42,6 +52,62 @@ interface NavPayload {
 }
 
 const navIndexCache = new WeakMap<Codewiki, NavIndex>();
+let clioCodewikiCache: { packageRoot: string; codewiki: Codewiki } | null = null;
+
+function packageRootResolvedPath(packageRoot: string, indexedPath: string): string {
+	const resolved = resolve(packageRoot, indexedPath);
+	const rel = relative(packageRoot, resolved);
+	if (
+		rel.length === 0 ||
+		rel === ".." ||
+		rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+		isAbsolute(rel)
+	) {
+		throw new Error(`invalid package-root-relative path in bundled code map: ${indexedPath}`);
+	}
+	return resolved;
+}
+
+function packageRootResolvedCodewiki(packageRoot: string, codewiki: Codewiki): Codewiki {
+	return {
+		...codewiki,
+		files: codewiki.files.map((file) => ({
+			...file,
+			path: packageRootResolvedPath(packageRoot, file.path),
+		})),
+	};
+}
+
+function loadClioCodewikiForTool(): { ok: true; loaded: LoadedNavSource } | { ok: false; message: string } {
+	try {
+		const packageRoot = resolvePackageRoot();
+		if (clioCodewikiCache?.packageRoot === packageRoot) {
+			return { ok: true, loaded: { codewiki: clioCodewikiCache.codewiki, entryRoot: packageRoot } };
+		}
+		const artifactPath = join(packageRoot, CLIO_CODEWIKI_RELATIVE_PATH);
+		const parsed = parseCodewikiRaw(readFileSync(artifactPath, "utf8"));
+		if (!parsed) throw new Error("bundled artifact is not a valid codewiki");
+		const codewiki = packageRootResolvedCodewiki(packageRoot, parsed);
+		clioCodewikiCache = { packageRoot, codewiki };
+		return { ok: true, loaded: { codewiki, entryRoot: packageRoot } };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			message: `code_nav: bundled Clio code map unavailable at ${CLIO_CODEWIKI_RELATIVE_PATH}: ${message}`,
+		};
+	}
+}
+
+async function loadNavSource(
+	source: CodeNavSource,
+): Promise<{ ok: true; loaded: LoadedNavSource } | { ok: false; message: string }> {
+	if (source === "clio") return loadClioCodewikiForTool();
+	const loaded = await loadCodewikiForTool();
+	return loaded.ok
+		? { ok: true, loaded: { codewiki: loaded.codewiki, entryRoot: null } }
+		: { ok: false, message: loaded.message };
+}
 
 function regexFromPattern(pattern: string): RegExp | null {
 	if (pattern.startsWith("/") && pattern.lastIndexOf("/") > 0) {
@@ -73,7 +139,7 @@ function regexFromPattern(pattern: string): RegExp | null {
 	return null;
 }
 
-function readPackageEntryPaths(cwd: string): Set<string> {
+function readPackageEntryPaths(cwd: string, resolveFromRoot: boolean): Set<string> {
 	const out = new Set<string>();
 	const pkgPath = join(cwd, "package.json");
 	if (!existsSync(pkgPath)) return out;
@@ -85,11 +151,15 @@ function readPackageEntryPaths(cwd: string): Set<string> {
 	}
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return out;
 	const pkg = parsed as Record<string, unknown>;
-	if (typeof pkg.main === "string") out.add(normalizeEntryPath(pkg.main));
-	if (typeof pkg.bin === "string") out.add(normalizeEntryPath(pkg.bin));
+	const add = (value: string): void => {
+		const normalized = normalizeEntryPath(value);
+		out.add(resolveFromRoot ? packageRootResolvedPath(cwd, normalized) : normalized);
+	};
+	if (typeof pkg.main === "string") add(pkg.main);
+	if (typeof pkg.bin === "string") add(pkg.bin);
 	if (typeof pkg.bin === "object" && pkg.bin !== null && !Array.isArray(pkg.bin)) {
 		for (const value of Object.values(pkg.bin)) {
-			if (typeof value === "string") out.add(normalizeEntryPath(value));
+			if (typeof value === "string") add(value);
 		}
 	}
 	return out;
@@ -243,9 +313,9 @@ function runPath(index: NavIndex, query: string, limit: number): NavPayload {
 	};
 }
 
-function runEntries(index: NavIndex, limit: number): NavPayload {
-	const cwd = process.cwd();
-	const packageEntries = readPackageEntryPaths(cwd);
+function runEntries(index: NavIndex, limit: number, entryRoot: string | null): NavPayload {
+	const cwd = entryRoot ?? process.cwd();
+	const packageEntries = readPackageEntryPaths(cwd, entryRoot !== null);
 	const candidates = [...index.filesByPath.values()].filter(
 		(file) => file.lang !== "config" && (file.role === "entry" || packageEntries.has(file.path)),
 	);
@@ -488,10 +558,24 @@ function parseLimit(value: unknown, fallback: number): number {
 export const codeNavTool: ToolSpec = {
 	...codeNavToolSurface,
 	async run(args, options): Promise<ToolResult> {
+		const rawSource = args.source;
+		if (rawSource !== undefined && rawSource !== "workspace" && rawSource !== "clio") {
+			return {
+				kind: "error",
+				message: `code_nav: source must be workspace or clio; got '${String(rawSource)}'`,
+			};
+		}
+		const source: CodeNavSource = rawSource === "clio" ? "clio" : "workspace";
 		const mode = typeof args.mode === "string" ? args.mode : "";
-		const loaded = await loadCodewikiForTool();
+		if (source === "clio" && mode === "wiki") {
+			return {
+				kind: "error",
+				message: "code_nav: source=clio does not provide mode=wiki; use context scope=docs for Clio documentation",
+			};
+		}
+		const loaded = await loadNavSource(source);
 		if (!loaded.ok) return { kind: "error", message: loaded.message };
-		const index = navIndexFor(loaded.codewiki);
+		const index = navIndexFor(loaded.loaded.codewiki);
 		const query = typeof args.query === "string" ? args.query.trim() : "";
 		const limit = parseLimit(args.limit, mode === "entries" ? DEFAULT_ENTRY_LIMIT : DEFAULT_LIMIT);
 		const reservation = reserveObservation(OBSERVE_SELF_CAPS.codeNav, options);
@@ -506,15 +590,17 @@ export const codeNavTool: ToolSpec = {
 		}
 		const close = (nav: NavPayload | ToolResult): ToolResult => {
 			if ("kind" in nav) return nav;
+			const next = source === "clio" && nav.next !== undefined ? `source=clio ${nav.next}` : nav.next;
+			const payload = next === nav.next ? nav.payload : { ...nav.payload, next };
 			return finalizeObservation({
 				tool: ToolNames.CodeNav,
 				unit: "results",
 				format: "json",
-				output: renderJson(nav.payload),
+				output: renderJson(payload),
 				shownCount: nav.shownCount,
 				totalCount: nav.totalCount,
 				truncated: nav.shownCount < nav.totalCount,
-				...(nav.next !== undefined ? { next: nav.next } : {}),
+				...(next !== undefined ? { next } : {}),
 				reservation,
 				...(options ? { options } : {}),
 			});
@@ -527,7 +613,7 @@ export const codeNavTool: ToolSpec = {
 			if (query.length === 0) return { kind: "error", message: "code_nav: mode=path requires query" };
 			return close(runPath(index, query, limit));
 		}
-		if (mode === "entries") return close(runEntries(index, limit));
+		if (mode === "entries") return close(runEntries(index, limit, loaded.loaded.entryRoot));
 		if (mode === "outline") {
 			if (query.length === 0) return { kind: "error", message: "code_nav: mode=outline requires query path" };
 			return close(runOutline(index, query, limit));

package/src/tools/context/docs-engine.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
 import { resolvePackageRoot } from "../../core/package-root.js";
 
 // Deterministic, dependency-free retrieval over Clio's bundled human docs,
@@ -298,14 +298,27 @@ function indexSection(section: RawSection): IndexedSection {
 
 function candidateDocFiles(root: string): string[] {
 	const docsDir = join(root, "docs");
+	const htmlDir = join(docsDir, "html");
 	const files: string[] = [];
-	try {
-		for (const name of readdirSync(docsDir).sort((a, b) => a.localeCompare(b))) {
-			if (name.toLowerCase().endsWith(".md")) files.push(join("docs", name));
+	const walk = (dir: string): void => {
+		let entries: import("node:fs").Dirent[];
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
 		}
-	} catch {
-		// The caller reports a missing docs directory below if nothing can load.
-	}
+		for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+			const absolute = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (absolute !== htmlDir) walk(absolute);
+				continue;
+			}
+			if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+				files.push(relative(root, absolute).replaceAll("\\", "/"));
+			}
+		}
+	};
+	walk(docsDir);
 	for (const name of ["README.md", "CHANGELOG.md", "CLIO-CODER.md"]) {
 		if (existsSync(join(root, name))) files.push(name);
 	}

package/src/tools/context/index.ts

@@ -181,20 +181,33 @@ function pendingSkillPolicyError(name: string, options: ToolInvokeOptions | unde
 	if (!policy) {
 		return NO_PENDING_SKILL_DENIAL;
 	}
+	const recipeBound = policyIsRecipeBound(policy);
+	// auto-edit / full-auto: the operator already chose to let the model act
+	// without being asked, and a skill only ever narrows the tool surface, so
+	// the model activates an installed skill itself under the same per-run
+	// policy `/skill` produces. A skill that is not installed still fails the
+	// lookup below with the operator-gated marketplace message.
+	if (policy.modelActivation === true && !recipeBound) {
+		if (!policy.loadedSkillNames.has(name)) return null;
+		const window = policy.carriedSurface === true ? "in this session" : "this turn";
+		return `context: skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+	}
 	const allowed = [...new Set(policy.allowedSkillNames.map((entry) => entry.trim()).filter(Boolean))];
 	if (allowed.length === 0) {
 		return NO_PENDING_SKILL_DENIAL;
 	}
-	const recipeBound = policyIsRecipeBound(policy);
 	if (!allowed.includes(name)) {
-		return recipeBound
-			? `context: this agent run may load only its declared skill(s): ${allowed.join(", ")}.`
-			: `context: this turn has pending skill request(s): ${allowed.join(", ")}. Load only those before doing anything else.`;
+		if (recipeBound) return `context: this agent run may load only its declared skill(s): ${allowed.join(", ")}.`;
+		// A carried surface is a skill the operator activated on an earlier
+		// turn, not a request waiting to be loaded now. Claiming a pending
+		// request here would invite a retry of a load nothing asked for.
+		if (policy.carriedSurface === true) return NO_PENDING_SKILL_DENIAL;
+		return `context: this turn has pending skill request(s): ${allowed.join(", ")}. Load only those before doing anything else.`;
 	}
 	if (policy.loadedSkillNames.has(name)) {
-		return recipeBound
-			? `context: skill ${name} is already loaded in this run; continue with its workflow.`
-			: `context: pending skill ${name} already loaded this turn; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+		if (recipeBound) return `context: skill ${name} is already loaded in this run; continue with its workflow.`;
+		const window = policy.carriedSurface === true ? "in this session" : "this turn";
+		return `context: pending skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
 	}
 	return null;
 }
@@ -203,6 +216,23 @@ function pendingSkillRequestFor(name: string, options: ToolInvokeOptions | undef
 	return options?.pendingSkillPolicy?.requests.find((request) => request.name === name) ?? null;
 }
 
+/**
+ * A hidden skill is intentionally absent from model discovery, but
+ * `disable-model-invocation` still promises that the operator may activate it
+ * by hand. Slash-command and selector requests are the two authenticated
+ * interactive paths for that choice. Recipe and marketplace requests do not
+ * widen visibility: neither proves that the operator selected an installed
+ * manual-only skill for this turn.
+ */
+function operatorRequestedManualSkill(skill: Skill, request: ReturnType<typeof pendingSkillRequestFor>): boolean {
+	return (
+		skill.trusted &&
+		skill.disableModelInvocation &&
+		request?.installed === true &&
+		(request.source === "slash-command" || request.source === "selector")
+	);
+}
+
 function renderPendingSkillTask(name: string, options: ToolInvokeOptions | undefined): string[] {
 	const request = pendingSkillRequestFor(name, options);
 	if (!request) return [];
@@ -257,16 +287,18 @@ function renderSkillsList(
 	skills: ReadonlyArray<Skill>,
 	marketplace: ReadonlyArray<MarketplaceSkill>,
 	marketplaceOffered: boolean,
+	modelActivation: boolean,
 ): string {
 	if (skills.length === 0 && marketplace.length === 0) {
 		// A registry that never offers the marketplace (a worker) must not
 		// claim none is configured; it simply has nothing to list.
 		return marketplaceOffered ? "No skills are installed and no marketplace is configured." : "No skills are installed.";
 	}
-	const lines = [
-		"Available skills. Match the current task against the descriptions below: when one fits, suggest the operator run /skill <name>; when several compose, suggest the sequence in order. Skill bodies load only after an explicit operator request; never load one without it.",
-		"",
-	];
+	// The header names the listing and nothing more. The reply protocol is
+	// stated once, as the recency anchor at the bottom, because that is the
+	// line literal models act on; a second copy up here cost every listing
+	// call the same sentences again.
+	const lines = ["Available skills.", ""];
 	if (skills.length > 0) {
 		lines.push("Installed:");
 		for (const skill of skills) {
@@ -280,10 +312,7 @@ function renderSkillsList(
 		// operator's /skill <name> prompts to install before it runs, so the
 		// model's move is the same suggest-and-wait. Only the body is out of
 		// reach until then, which is why the description is all that appears.
-		lines.push(
-			"",
-			"Marketplace (not installed; /skill <name> offers to install, or `clio-coder skills install <name>`). Suggest these the same way when one matches; their bodies cannot be loaded until the operator installs them:",
-		);
+		lines.push("", "Marketplace (not installed; /skill <name> offers to install):");
 		for (const entry of marketplace) {
 			const category = entry.category ? ` [${entry.category}]` : "";
 			lines.push(`- ${entry.name}${category}: ${entry.description}`);
@@ -293,7 +322,9 @@ function renderSkillsList(
 	// template where they skip conditional prose in the header.
 	lines.push(
 		"",
-		`If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
+		modelActivation
+			? `If one skill above matches the current task, load it now with context(scope="skills", name="<name>") and continue in the same turn; at this autonomy level you activate installed skills yourself and do not wait for the operator. Marketplace rows below are not installed and still need the operator. If none match, do not mention skills.`
+			: `If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
 	);
 	if (marketplace.length > 0) {
 		// The offer protocol mirrors the marketplace-offer middleware: fixed
@@ -407,8 +438,13 @@ function runSkillsScope(
 	if (name.length === 0) {
 		const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
 		const visible = modelVisibleSkills(list.items);
-		const marketplace = marketplaceRowsFor(deps, visible, options);
-		const rendered = renderSkillsList(visible, marketplace, deps.skillMarketplace !== false);
+		const marketplace = marketplaceRowsFor(deps, list.items, options);
+		const rendered = renderSkillsList(
+			visible,
+			marketplace,
+			deps.skillMarketplace !== false,
+			options?.pendingSkillPolicy?.modelActivation === true,
+		);
 		// The catalog is bounded but not small: the whole listing must fit the
 		// per-call cap like any observation, and a cut list says so instead of
 		// silently dropping the marketplace tail.
@@ -437,12 +473,15 @@ function runSkillsScope(
 	if (policyError) return { kind: "error", message: policyError };
 	const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
 	const visible = modelVisibleSkills(list.items);
-	const skill = visible.find((item) => item.name === name);
+	const pendingRequest = pendingSkillRequestFor(name, options);
+	const skill =
+		visible.find((item) => item.name === name) ??
+		list.items.find((item) => item.name === name && operatorRequestedManualSkill(item, pendingRequest));
 	if (!skill) {
 		// A marketplace entry is a skill that exists and is not installed. Saying
 		// "unknown skill" about it denies the operator a thing the listing just
 		// offered; name the state and the one move that changes it.
-		const installable = marketplaceRowsFor(deps, visible, options).some((entry) => entry.name === name);
+		const installable = marketplaceRowsFor(deps, list.items, options).some((entry) => entry.name === name);
 		if (installable) {
 			return {
 				kind: "error",
@@ -455,7 +494,6 @@ function runSkillsScope(
 	}
 	const includeTree = args.include_tree === true;
 	const tree = includeTree ? buildResourceTree(skill.baseDir, DEFAULT_TREE_ENTRIES) : null;
-	const pendingRequest = pendingSkillRequestFor(name, options);
 	const pendingTask = pendingRequest?.args.trim() ?? "";
 	// Provenance: the activated content is compared against whatever recorded
 	// hash can speak for it, the audited catalog's pinned manifest or the

package/src/tools/core-bootstrap.ts

@@ -38,6 +38,16 @@ export interface CoreToolBootstrapDeps {
 	taskBoard?: TaskBoardStore;
 	userTasks?: UserTasksStore;
 	agentLedger?: AgentLedgerPort;
+	/**
+	 * Register the ledger tool even without a port. A worker registry needs
+	 * this: `attestedToolSignature` signs the names a bare worker registry
+	 * produces, and the orchestrator admits `ledger` for every batch member,
+	 * so a registry that dropped the tool for want of a port drifted the
+	 * signature and admission refused every batch worker. The session never
+	 * sets it: it has no peers, and the schema was 444 tokens of every first
+	 * turn for a tool that could only answer "no ledger".
+	 */
+	includeLedgerTools?: boolean;
 	getSkillLoaderOptions?: () => Pick<
 		LoadSkillsInput,
 		"trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths"
@@ -49,6 +59,8 @@ export interface CoreToolRegistration {
 	includeNetworkTools: boolean;
 	includeSessionTools: boolean;
 	includeInteractiveTools: boolean;
+	/** True only when a worker bound its dispatch's agent-ledger port; the session never does. */
+	includeLedgerTools: boolean;
 }
 
 export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstrapDeps = {}): CoreToolRegistration {
@@ -154,12 +166,21 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 	registry.register({
 		...builtin(createArtifactTool({ getCwd: skillToolDeps.getCwd }), { path: "src/tools/artifact.ts", scope: "core" }),
 	});
-	registry.register({
-		...builtin(createLedgerTool(deps.agentLedger ? { agentLedger: deps.agentLedger } : {}), {
-			path: "src/tools/ledger.ts",
-			scope: "core",
-		}),
-	});
+	// The coordination board exists only inside a dispatch: a worker process
+	// binds the port, the session never does, and without a port the tool can
+	// only answer "no ledger". Registering it on the session put its schema on
+	// every first turn, so the session registers it with a port or not at all;
+	// a worker registry asks for it explicitly, port or no port, because its
+	// attested surface must not depend on whether this run bound one.
+	const includeLedgerTools = deps.includeLedgerTools === true || deps.agentLedger !== undefined;
+	if (includeLedgerTools) {
+		registry.register({
+			...builtin(createLedgerTool(deps.agentLedger ? { agentLedger: deps.agentLedger } : {}), {
+				path: "src/tools/ledger.ts",
+				scope: "core",
+			}),
+		});
+	}
 	registry.register({
 		...builtin(
 			createTasksTool({
@@ -177,6 +198,7 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 		includeNetworkTools,
 		includeSessionTools: Boolean(session),
 		includeInteractiveTools: Boolean(deps.askUser),
+		includeLedgerTools,
 	};
 }
 

package/src/tools/credential-present.ts

@@ -92,8 +92,7 @@ export const credentialPresentTool: ToolSpec = {
 		name: Type.String({ description: "Credential key name, e.g. OPENAI_API_KEY." }),
 		source: Type.Optional(
 			StringEnum(["auto", "environment", "env", "file"], {
-				description:
-					"auto checks the environment and the file when file is supplied; environment/env checks only the process environment; file checks only the file.",
+				description: "auto (default) checks the environment, then file when given; the others check one source.",
 			}),
 		),
 		file: Type.Optional(Type.String({ description: "Env-style file to check for NAME=, e.g. .env." })),

package/src/tools/dispatch-arguments.ts

@@ -50,6 +50,7 @@ const AUTO_BASELINE_BY_TASK_TYPE: Readonly<Record<AgentTaskType, string>> = {
 	// Read-only shapes.
 	code_review: "verifier",
 	research: "researcher",
+	world_knowledge: "world-knowledge",
 	code_read: "scout",
 	unknown: "scout",
 };
@@ -186,7 +187,11 @@ function dispatchRequestFromArgs(
 	let rawIntent = args.intent;
 	if (Object.hasOwn(args, "gate")) {
 		if (typeof args.gate !== "string" || args.gate.trim().length === 0) {
-			return { ok: false, message: "gate must be a non-empty declared check id" };
+			return {
+				ok: false,
+				message:
+					"gate must be a non-empty declared check id: a check verify() lists, never a shell command; omit gate and run the check yourself after the receipt",
+			};
 		}
 		rawIntent = { ...(isRecord(rawIntent) ? rawIntent : {}), verification: [{ check: args.gate.trim() }] };
 	}

package/src/tools/dispatch-event-text.ts

@@ -1,3 +1,4 @@
+import { gatewayRoutingObservationFromRecord, gatewayRoutingObservationLabel } from "../core/gateway-routing.js";
 import { responseModelIdObservationFromRecord } from "../core/response-model-id.js";
 import { durableAssistantTextFromEvent } from "../domains/dispatch/event-pump.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
@@ -23,3 +24,12 @@ export function receiptResponseModelIdObservationLabel(receipt: Pick<RunReceipt,
 	});
 	return `response_model_id_observation=${labels.join(",")}`;
 }
+
+/** Human projection of gateway routes carried by a receipt. */
+export function receiptGatewayRoutingLabel(receipt: Pick<RunReceipt, "upstreamResponses">): string | null {
+	const observations = (receipt.upstreamResponses ?? [])
+		.map((response) => gatewayRoutingObservationFromRecord(response as unknown as Record<string, unknown>))
+		.filter((observation) => observation !== null);
+	if (observations.length === 0) return null;
+	return observations.map(gatewayRoutingObservationLabel).join(" | ");
+}

package/src/tools/dispatch-plan.ts

@@ -103,7 +103,14 @@ export interface DispatchPlanView {
 	/** True when this call requires plan approval at supervised autonomy levels. */
 	planScale: boolean;
 	tasks: DispatchPlanTaskView[];
-	/** Rendered plan artifact, deterministic for identical arguments. */
+	/**
+	 * Rendered plan artifact, deterministic for identical arguments against an
+	 * unchanged working tree. The tree is an input because a legacy task's scope
+	 * lines resolve a "../"-leading prose token by probing the dispatch root, so
+	 * creating or deleting the probed file between two renders of the same call
+	 * changes this text and the hash below. Nothing re-derives the hash to compare
+	 * it; both renders of one call happen in the same synchronous admission pass.
+	 */
 	text: string;
 	/** sha256 of the rendered artifact. */
 	hash: string;
@@ -251,12 +258,24 @@ function safeField(value: string, bindChangedValue = true): string {
 	return `${result}{sha256=${createHash("sha256").update(value, "utf8").digest("hex")}}`;
 }
 
-function renderLegacyPathScope(task: DispatchPlanTaskView): string[] {
+/**
+ * The scope lines of the approval artifact, for a task with no typed intent.
+ *
+ * `cwd` is the dispatch's own working directory, not this process's: prose
+ * inference probes a "../"-leading token against the dispatch root, so a plan
+ * rendered against `process.cwd()` would show the operator a working context
+ * the run does not resolve whenever the call carries an explicit `cwd` (a
+ * worktree, most often). Passing it makes this render and admission read the
+ * same tree, which is also the sense in which the artifact is deterministic:
+ * identical arguments against an unchanged tree, not against any tree.
+ */
+function renderLegacyPathScope(task: DispatchPlanTaskView, cwd: string | undefined): string[] {
 	if (task.intent !== undefined) return [];
 	const scope = resolveDispatchPathScope({
 		agentId: task.agent,
 		executionRole: task.executionRole,
 		task: task.task,
+		...(cwd !== undefined ? { cwd } : {}),
 		...(task.briefing !== undefined ? { briefing: task.briefing } : {}),
 	});
 	const lines = ["    scope mode=legacy-inferred"];
@@ -275,6 +294,17 @@ function renderLegacyPathScope(task: DispatchPlanTaskView): string[] {
 	if (scope.provenance.workingContextPaths.length === 0 && scope.provenance.writeBoundaries.length === 0) {
 		lines.push("    scope policy_paths=none");
 	}
+	// Named here as well as on the dispatch-time notice, because this artifact is
+	// the surface an operator approves: a token the run anchored somewhere the
+	// prose did not spell, or discarded outright, would otherwise be visible in
+	// the plan only as a scope line that has no counterpart in the task text.
+	for (const entry of scope.parentTokens) {
+		lines.push(
+			`    scope parent_token raw=${JSON.stringify(safeField(entry.token))} resolved=${
+				entry.resolved === null ? "dropped" : JSON.stringify(safeField(entry.resolved))
+			} source=${entry.source}`,
+		);
+	}
 	return lines;
 }
 
@@ -365,6 +395,7 @@ function renderPlanText(
 	source: DispatchPlanSource,
 	maxWorkers: number | null,
 	onFailure: ResolvedDispatchPlanArtifact["onFailure"],
+	cwd: string | undefined,
 	confirmation?: ResolvedDispatchPlanArtifact["confirmation"],
 ): string {
 	const lines = [
@@ -453,7 +484,7 @@ function renderPlanText(
 			const serialized = JSON.stringify(task.intent);
 			lines.push(`    intent_sha256=${createHash("sha256").update(serialized, "utf8").digest("hex")}`);
 		}
-		lines.push(...renderLegacyPathScope(task));
+		lines.push(...renderLegacyPathScope(task, cwd));
 		for (const check of task.resolvedVerification ?? []) {
 			lines.push(
 				`    verification check=${safeField(check.check)} argv=${JSON.stringify(check.argv)} cwd=${JSON.stringify(check.cwd)} timeout_ms=${check.timeoutMs}`,
@@ -606,6 +637,7 @@ const RESULT_CONTRACT_KINDS = new Set<ResultContract["kind"]>([
 	"council-report",
 	"debugger-report",
 	"research-report",
+	"world-knowledge-report",
 	"mutation-report",
 	"provenance-report",
 	"oracle-report",
@@ -887,7 +919,20 @@ export function describeDispatchPlan(rawArgs: Record<string, unknown> | undefine
 			tasks.some((task) => task.failover === "approved") ||
 			confirmation !== undefined ||
 			isRecord(args.apply_winner));
-	const text = renderPlanText(topology, tasks, costCeilingUsd, deadlineMs, source, maxWorkers, onFailure, confirmation);
+	const text = renderPlanText(
+		topology,
+		tasks,
+		costCeilingUsd,
+		deadlineMs,
+		source,
+		maxWorkers,
+		onFailure,
+		// Read off the whole call rather than a task view: `cwd` is one top-level
+		// dispatch argument, so it survives on both the freshly parsed path and
+		// the resolved-artifact path, where the sealed task shape carries no cwd.
+		str(args.cwd),
+		confirmation,
+	);
 	return {
 		topology,
 		taskCount: Math.max(1, tasks.length),

package/src/tools/dispatch-run-events.ts

@@ -102,7 +102,7 @@ export function runTailEntryFromEvent(event: unknown, at: string = new Date().to
 export interface DispatchRunEventRegistryOptions {
 	/**
 	 * Durable tee for the display tail. Omitted takes the process-wide default
-	 * journal (settings-gated by `panes.journal`); `null` turns it off for this
+	 * journal (settings-gated by `fleet.history.journal`); `null` turns it off for this
 	 * registry. This is the one wiring choke point: every registry in the
 	 * process is built by this factory, so the sink attaches here rather than at
 	 * each of the three construction sites that call it.

package/src/tools/dispatch-runner.ts

@@ -2153,6 +2153,18 @@ export async function runDispatchTool(
 	if (options?.signal?.aborted) return { kind: "error", message: "dispatch: aborted" };
 	const maxOutputBytes = snapshot.maxOutputBytes;
 	const timeoutMs = snapshot.timeoutMs;
+	// All modes, including derived Scout/review runs, share the invocation's
+	// admission bounds. Keep these off the serializable approved request.
+	const dispatch = deps.dispatch;
+	const preparation = {
+		...(options?.signal === undefined ? {} : { signal: options.signal }),
+		...(timeoutMs === undefined ? {} : { deadlineAt: Date.now() + timeoutMs }),
+	};
+	deps.dispatch = {
+		...dispatch,
+		dispatch: (request, observer) => dispatch.dispatch(request, observer, preparation),
+		dispatchBatch: (requests) => dispatch.dispatchBatch(requests, preparation),
+	};
 	let review = snapshot.review === undefined ? undefined : structuredClone(snapshot.review);
 	let council = snapshot.council === undefined ? undefined : structuredClone(snapshot.council);