@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/tools/agent-tools.ts

@@ -296,6 +296,35 @@ function errorMessage(err: unknown): string {
 	return err instanceof Error ? err.message : String(err);
 }
 
+/**
+ * The parameter schema as the provider should see it.
+ *
+ * TypeBox 1.x annotates every schema it builds with string-keyed markers
+ * (`~unsafe` on `Type.Unsafe`, `~optional` on `Type.Optional`, and so on).
+ * Unlike the older symbol keys they survive `JSON.stringify`, so each enum
+ * field reached the model as `{"~unsafe": null, "~optional": true, ...}`:
+ * 44 junk keys on the default surface, and a small model has no way to know
+ * that `"~unsafe": null` means nothing. Validation does not need them
+ * (`Value.Check` answers identically with and without), so the copy handed
+ * to the agent loop drops every `~`-prefixed key. Symbol keys are copied
+ * through untouched because pi-ai picks its coercion path by the TypeBox
+ * kind symbol on the root schema.
+ */
+function wireParameterSchema<T>(schema: T): T {
+	if (Array.isArray(schema)) return schema.map((entry) => wireParameterSchema(entry)) as T;
+	if (typeof schema !== "object" || schema === null) return schema;
+	const source = schema as Record<PropertyKey, unknown>;
+	const out: Record<PropertyKey, unknown> = {};
+	for (const key of Object.keys(source)) {
+		if (key.startsWith("~")) continue;
+		out[key] = wireParameterSchema(source[key]);
+	}
+	for (const symbol of Object.getOwnPropertySymbols(source)) {
+		out[symbol] = source[symbol];
+	}
+	return out as T;
+}
+
 function toAgentTool(
 	spec: ToolSpec,
 	registry: ToolRegistry,
@@ -305,7 +334,7 @@ function toAgentTool(
 	const tool: AgentTool<TSchema> = {
 		name: spec.name,
 		description: spec.description,
-		parameters: spec.parameters,
+		parameters: wireParameterSchema(spec.parameters),
 		label: spec.metadata?.uiLabel ?? spec.name,
 		async execute(
 			toolCallId: string,

package/src/tools/artifact.ts

@@ -20,7 +20,7 @@ import type { ToolResult, ToolSpec } from "./registry.js";
  * tree holds files a human asked for, and everything Clio generates on its own
  * belongs in the gitignored project directory. An explicit `path` still writes
  * wherever the caller says, inside the workspace. See core/artifact-paths.ts
- * and docs/artifact-placement.md.
+ * and docs/architecture/artifact-placement.md.
  *
  * Skills are not artifacts: a skill is a SKILL.md folder written with the
  * ordinary write tool and validated by the skills loader on load. The
@@ -83,7 +83,7 @@ async function writeTerminalArtifact(
 export function createArtifactTool(deps: ArtifactToolDeps = {}): ToolSpec {
 	return {
 		name: ToolNames.Artifact,
-		description: `Write a named artifact: kind=plan|review|report writes a terminal Markdown document and completes the turn. Without an explicit path it lands in ${CLIO_ARTIFACT_DIR}/ (PLAN.md, REVIEW.md, REPORT.md); pass path only when the user asked for a file at a specific place.`,
+		description: `Write a named artifact: kind=plan|review|report writes a terminal Markdown document and completes the turn, so close the task board (tasks done/block/drop) before writing it. Without an explicit path it lands in ${CLIO_ARTIFACT_DIR}/ (PLAN.md, REVIEW.md, REPORT.md); pass path only when the user asked for a file at a specific place.`,
 		parameters: Type.Object({
 			kind: StringEnum(ARTIFACT_KINDS, { description: "Artifact kind." }),
 			content: Type.String({ description: "Full Markdown body." }),

package/src/tools/ask-user.ts

@@ -92,13 +92,13 @@ export interface AskUserToolDeps {
 export const askUserParameters = Type.Object({
 	action: Type.Optional(
 		StringEnum(["ask", "complete"], {
-			description: "ask presents a round of questions; complete (exactly once) records decisions before final prose.",
+			description: "ask presents a round of questions; complete records the decisions, once, before final prose.",
 		}),
 	),
 	mode: Type.Optional(
 		StringEnum(["round", "single_question"], {
 			description:
-				"Caps how many questions this call may carry. single_question accepts exactly 1 and rejects the call otherwise (interviews); round accepts 1 to 4 tightly related confirmations. Default is round.",
+				"round (default) accepts 1 to 4 tightly related questions; single_question accepts exactly one, for interviews.",
 		}),
 	),
 	questions: Type.Optional(
@@ -135,7 +135,7 @@ export const askUserParameters = Type.Object({
 	exposure: Type.Optional(
 		StringEnum(["local", "outward"], {
 			description:
-				"Blast radius of this gate. local (default) stays inside the workspace. outward means answering it publishes or sends something the operator cannot take back (filing an issue or PR, posting a comment, pushing, releasing); at autonomy auto-edit an outward gate parks for the operator instead of being answered automatically.",
+				"local (default) stays inside the workspace; outward publishes or sends something the operator cannot take back (issue, PR, comment, push, release) and parks for the operator at auto-edit.",
 		}),
 	),
 });
@@ -261,7 +261,7 @@ function normalizeDecisions(value: unknown): { decisions?: AskUserDecision[]; er
 	return { decisions };
 }
 
-export function normalizeAskUserCall(args: Record<string, unknown>): { call?: AskUserCall; error?: string } {
+function normalizeAskUserCall(args: Record<string, unknown>): { call?: AskUserCall; error?: string } {
 	const rawAction = trimOptionalString(args.action)?.toLowerCase() ?? "ask";
 	if (rawAction !== "ask" && rawAction !== "complete") {
 		return { error: "action must be ask or complete" };
@@ -499,7 +499,7 @@ async function persistAskUserTranscript(
 		await mkdir(dir, { recursive: true });
 		if (!policy.transcriptPath) policy.transcriptPath = path.join(dir, transcriptFileName(policy));
 		const transcript = {
-			schema: "clio.ask_user.interview.v1",
+			schema: "clio-coder.ask_user.interview.v1",
 			id: policy.id,
 			status: policy.status,
 			startedAt: policy.startedAt,
@@ -595,7 +595,7 @@ async function completeInterview(
 	return okInterviewResult(policy, event);
 }
 
-export async function finalizeAskUserInterview(
+async function finalizeAskUserInterview(
 	policy: AskUserToolPolicy,
 	reason: string,
 	options?: ToolInvokeOptions,

package/src/tools/bash.ts

@@ -48,7 +48,7 @@ export const BASH_DEFAULT_RESULT_DISPOSITION: ToolResultDisposition = {
 };
 
 /** Pure, idempotent normalization used by registry admission and direct calls. */
-export function normalizeBashArguments(args: Record<string, unknown>): Record<string, unknown> {
+function normalizeBashArguments(args: Record<string, unknown>): Record<string, unknown> {
 	return args.output_policy === undefined ? { ...args, output_policy: "bounded" } : args;
 }
 
@@ -163,7 +163,7 @@ export const bashTool: ToolSpec = {
 		cwd: Type.Optional(
 			Type.String({
 				description:
-					"Omit this. The command already runs at the session workspace root. Set it only to run in a subdirectory of that root, as a relative path; an absolute path outside the root is blocked.",
+					"Omit unless the command must run in a subdirectory of the workspace root, given as a relative path; outside the root is blocked.",
 			}),
 		),
 		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in milliseconds." })),

package/src/tools/bootstrap.ts

@@ -10,6 +10,7 @@ import type { CompeteMuxWorktrees } from "./compete-worktrees.js";
 import { assertRegisteredBuiltinTools, type CoreToolBootstrapDeps, registerCoreTools } from "./core-bootstrap.js";
 import { createDispatchRunEventRegistry, createDispatchTool } from "./dispatch.js";
 import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
+import type { DispatchSchemaComposition } from "./dispatch-schema.js";
 import { lazyTool } from "./lazy-tool.js";
 import { monitorToolSurface } from "./monitor-surface.js";
 import { panesToolSurface } from "./panes-surface.js";
@@ -27,6 +28,8 @@ export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
 	getAutonomy?: () => AutonomyLevel;
 	getCostCeilingUsd?: () => number;
 	getWorkerRosters?: () => WorkerRosters;
+	/** Which optional `dispatch` schema blocks this session advertises; absent means every block. */
+	getDispatchSchemaComposition?: () => DispatchSchemaComposition;
 	dispatchBackground?: DispatchBackgroundRegistry;
 	/** Optional herdr worktree lifecycle for compete candidates. */
 	competeMuxWorktrees?: CompeteMuxWorktrees;
@@ -61,6 +64,7 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 			...(deps.getAutonomy ? { getAutonomy: deps.getAutonomy } : {}),
 			...(deps.getCostCeilingUsd ? { getCostCeilingUsd: deps.getCostCeilingUsd } : {}),
 			...(deps.getWorkerRosters ? { getWorkerRosters: deps.getWorkerRosters } : {}),
+			...(deps.getDispatchSchemaComposition ? { getSchemaComposition: deps.getDispatchSchemaComposition } : {}),
 			...(deps.dispatchBackground ? { background: deps.dispatchBackground } : {}),
 			...(deps.competeMuxWorktrees ? { competeWorktrees: { mux: deps.competeMuxWorktrees } } : {}),
 		};

package/src/tools/builtin-tool-catalog.ts

@@ -4,7 +4,13 @@ import { BASH_DEFAULT_RESULT_DISPOSITION } from "./bash.js";
 import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
 import { toolPresentationPolicy } from "./presentation.js";
 import { readMaxBytes } from "./read.js";
-import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
+import {
+	resolveToolPromptHint,
+	type ToolMetadata,
+	type ToolPromptHintRole,
+	type ToolSourceInfo,
+	type ToolSpec,
+} from "./registry.js";
 
 function withSourceInfo<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
 	return { ...spec, sourceInfo };
@@ -83,7 +89,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultSizePolicy: observePolicy(OBSERVE_SELF_CAPS.codeNav, "Raise limit or use a narrower mode/query."),
 		costLatency: "local_fast",
 		promptHint:
-			"Use code_nav for indexed code navigation (modes: symbol, path, entries, outline, deps, dependents, wiki).",
+			"Use code_nav with source=workspace (default) for project code and source=clio for Clio's shipped code map; modes: symbol, path, entries, outline, deps, dependents, wiki (workspace only).",
 	},
 	[ToolNames.Context]: {
 		objective: "Return workspace, bundled-docs, or skill context.",
@@ -94,8 +100,14 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 			"Use a narrower query or scope to inspect omitted content.",
 		),
 		costLatency: "local_fast",
-		promptHint:
-			'Call context with scope="skills" to list installed and marketplace skills; when one matches the task, or the operator names a skill or asks how one works, suggest the operator run /skill <name> (a marketplace skill is offered for install) and never load it uninvited. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else. When an [evicted ...] marker names content you need, recall it with context(scope="recall", ref=...); re-read the file only when the marker says it changed.',
+		promptHint: {
+			session:
+				'On an explicit pending skill request, first load exactly that skill with context(scope="skills", name=<skill>). Follow a [Marketplace] reminder\'s exact ask_user options. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+			worker:
+				'This worker has no operator skill-activation channel; do not load or suggest skills. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+			boundWorker:
+				'Load only the harness-activated recipe-bound skills named in the persona, and only when they match the assigned task. This worker cannot install or suggest marketplace skills. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+		},
 	},
 	[ToolNames.CredentialPresent]: {
 		objective: "Check whether a credential key is present without returning its value.",
@@ -135,7 +147,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultDisposition: BASH_DEFAULT_RESULT_DISPOSITION,
 		costLatency: "local_slow",
 		promptHint:
-			"Bash output_policy defaults to bounded diagnostic tail. Use summary for noisy commands, metadata-only when only outcome and retrieval matter, and full only when output is known to fit the bounded result budget.",
+			"bash output_policy: omit for a bounded tail; summary for noisy commands; metadata-only when only the outcome matters; full only when the output is known to fit.",
 	},
 	[ToolNames.Git]: {
 		objective: "Read-only git inspection: status, diff, or log.",
@@ -167,9 +179,8 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		costLatency: "local_fast",
 		promptHint:
-			'When a request contains three or more distinct steps, declare the board before your first edit: tasks action="plan" with a title and the task list. ' +
-			'Mark one task active with "start" before working it, close it with "done" plus an evidence note ' +
-			'(what proves it works), and use "block" with a reason instead of silently stalling.',
+			'For a request with three or more distinct steps, declare the board before the first edit: tasks(action="plan") with a title and the task list. ' +
+			"start one task before working it, close it with done plus an evidence note, and block with a reason instead of stalling.",
 	},
 	[ToolNames.Ledger]: {
 		objective: "Coordinate with the peer workers of this dispatch through typed claims, findings, and reviews.",
@@ -191,9 +202,10 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultSizePolicy: summaryPolicy(
 			"Use the dispatch receipt paths or ask a narrower worker follow-up for omitted output.",
 		),
+		// No hint: the Tool Contract's inventory line already says when
+		// dispatch(list:true) is the right answer, and the Fleet section says
+		// everything else about routing.
 		costLatency: "agent",
-		promptHint:
-			"Call dispatch with list:true only when the operator asks about agents, workers, or the fleet; never use it to inventory direct tools.",
 	},
 	[ToolNames.Monitor]: {
 		objective: "Inspect dispatched runs: state, recent events, receipts.",
@@ -226,7 +238,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		costLatency: "local_fast",
 		promptHint:
-			'When the operator asks to see a dispatched agent ("show me the tester"), call panes with action="show" and the agent id. Utility panes are presets only; an arbitrary command is the operator\'s own /panes open.',
+			'When the operator asks to see a dispatched agent ("show me the tester"), call panes(action="show", target=<agent id>).',
 	},
 	// RETRIEVE: network-class.
 	[ToolNames.WebFetch]: {
@@ -252,7 +264,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		costLatency: "local_slow",
 		promptHint:
-			'Use ask_user only when blocked on a decision the request does not answer; never ask about anything the operator already stated. One question per round in interview workflows, up to four tightly related questions otherwise, recommended option first. Finish with action="complete" and a compact decisions array before final prose. If cancelled, continue with defaults and do not ask again.',
+			'Use ask_user only when blocked on a decision the request does not answer, never about something the operator already stated: one question per round in interviews, up to four related questions otherwise, recommended option first, then action="complete" with the decisions before final prose.',
 	},
 	// ARTIFACT: terminal writers.
 	[ToolNames.Artifact]: {
@@ -264,15 +276,21 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 	},
 };
 
-/** Canonical, registry-owned prompt hints for an already-admitted tool set. */
-export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): ReadonlyArray<{ tool: string; hint: string }> {
-	const seen = new Set<string>();
+/** Canonical, role-aware prompt hints for an already-admitted tool set. */
+export function toolPromptHintsForNames(
+	names: ReadonlyArray<ToolName>,
+	role: ToolPromptHintRole = "session",
+): ReadonlyArray<{ tool: string; hint: string }> {
+	const seenTools = new Set<string>();
+	const seenHints = new Set<string>();
 	const hints: Array<{ tool: string; hint: string }> = [];
 	for (const name of [...names].sort()) {
-		if (seen.has(name)) continue;
-		seen.add(name);
-		const hint = TOOL_METADATA[name]?.promptHint?.trim();
-		if (hint) hints.push({ tool: name, hint });
+		if (seenTools.has(name)) continue;
+		seenTools.add(name);
+		const hint = resolveToolPromptHint(TOOL_METADATA[name]?.promptHint, role);
+		if (!hint || seenHints.has(hint)) continue;
+		seenHints.add(hint);
+		hints.push({ tool: name, hint });
 	}
 	return hints;
 }
@@ -282,9 +300,21 @@ export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): Readonl
 // live panel (which has no registry) answer the fold question identically.
 function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
 	const metadata = TOOL_METADATA[spec.name];
-	return metadata
-		? withMetadata(spec, { ...metadata, presentation: toolPresentationPolicy(spec.name, undefined) })
-		: spec;
+	if (!metadata) return spec;
+	// The read cap is a guardrail (`safety.limits.readBytesPerCall`) installed
+	// from settings after this module loads, so the table's import-time value
+	// is the default, not the operator's. Recompute the policy cap when the tool
+	// is registered; the drift check in policy.ts compares against the live cap
+	// and a settings file raising the read cap used to fail boot.
+	const resultSizePolicy =
+		spec.name === ToolNames.Read
+			? observePolicy(readMaxBytes(), metadata.resultSizePolicy?.followUpHint ?? "")
+			: metadata.resultSizePolicy;
+	return withMetadata(spec, {
+		...metadata,
+		...(resultSizePolicy ? { resultSizePolicy } : {}),
+		presentation: toolPresentationPolicy(spec.name, undefined),
+	});
 }
 
 export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {

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

@@ -12,6 +12,12 @@ export const codeNavToolSurface = {
 	description:
 		"Navigate the indexed codewiki: mode=symbol finds files by symbol, path finds files by glob/regex/substring, entries lists likely entry points, outline lists file symbols, deps lists imports, and dependents lists importers. mode=wiki without query lists generated Markdown wiki pages; with query it resolves a page id/title and returns its summary plus a path to open with read. For Clio's bundled product docs use context scope=docs.",
 	parameters: Type.Object({
+		source: Type.Optional(
+			StringEnum(["workspace", "clio"], {
+				description: "Code map source (default workspace).",
+				default: "workspace",
+			}),
+		),
 		mode: StringEnum(["symbol", "path", "entries", "outline", "deps", "dependents", "wiki"], {
 			description: "Lookup mode.",
 		}),

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/compete-worktrees.ts

@@ -2,7 +2,7 @@
  * Scratch git worktrees for the compete dispatch topology.
  *
  * Each candidate builds in its own worktree on its own branch
- * (`clio/compete/<group>/<n>`), created from the repository HEAD under
+ * (`clio-coder/compete/<group>/<n>`), created from the repository HEAD under
  * `<root>/.clio-coder/worktrees/<group>/candidate-<n>`. The path sits inside the
  * project root because remote fleet nodes share the filesystem and doctor
  * preflight verifies path parity only for the project root; `.clio-coder/` is
@@ -127,8 +127,9 @@ export interface CompeteRunAdmission {
 
 const COMPETE_PARENT_SEGMENTS = [".clio-coder", "worktrees"] as const;
 const COMPETE_MANIFEST_FILE = ".clio-coder-compete-owner.json";
-const COMPETE_MANIFEST_KIND = "clio-compete-group";
-const COMPETE_COMMIT_IDENTITY = "clio-compete";
+const COMPETE_MANIFEST_KIND = "clio-coder-compete-group";
+const LEGACY_COMPETE_MANIFEST_KIND = "clio-compete-group";
+const COMPETE_COMMIT_IDENTITY = "clio-coder-compete";
 
 const SAFE_GROUP = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const PROCESS_EXIT_GRACE_MS = 750;
@@ -324,7 +325,7 @@ function isCanonicalDirectoryAt(path: string): boolean {
  * `relative()` makes the decision by path segment, so `/group-a2` can never
  * be mistaken for a child of `/group-a` as it can with textual startsWith.
  */
-export function isCanonicalPathInside(parent: string, candidate: string): boolean {
+function isCanonicalPathInside(parent: string, candidate: string): boolean {
 	return isCanonicalWorktreePathInside(parent, candidate);
 }
 
@@ -333,7 +334,7 @@ function manifestFromUnknown(value: unknown): CompeteGroupManifest | null {
 	const manifest = value as Record<string, unknown>;
 	if (
 		manifest.version !== 2 ||
-		manifest.kind !== COMPETE_MANIFEST_KIND ||
+		(manifest.kind !== COMPETE_MANIFEST_KIND && manifest.kind !== LEGACY_COMPETE_MANIFEST_KIND) ||
 		typeof manifest.root !== "string" ||
 		typeof manifest.group !== "string" ||
 		typeof manifest.token !== "string" ||
@@ -417,10 +418,14 @@ export function isGitRepository(root: string): boolean {
 	}
 }
 
-function competeBranch(group: string, index: number): string {
+function competeBranch(group: string, index: number, legacy = false): string {
 	validateGroup(group);
 	if (!Number.isInteger(index) || index < 1) throw new Error(`invalid compete candidate index ${index}`);
-	return `clio/compete/${group}/${index}`;
+	return `${legacy ? "clio" : "clio-coder"}/compete/${group}/${index}`;
+}
+
+function competeBranchMatches(branch: string, group: string, index: number): boolean {
+	return branch === competeBranch(group, index) || branch === competeBranch(group, index, true);
 }
 
 /** Claim the group before creating a branch or candidate worktree. */
@@ -549,11 +554,7 @@ export function markCompeteGroupWinnerPreserved(
  * baseline is a parameter rather than HEAD so every candidate in a compete
  * transaction starts from the same approved state.
  */
-export function createCandidateWorktree(
-	ownership: CompeteGroupOwnership,
-	index: number,
-	baseline: string,
-): CandidateWorktree {
+function createCandidateWorktree(ownership: CompeteGroupOwnership, index: number, baseline: string): CandidateWorktree {
 	assertOwnership(ownership);
 	const branch = competeBranch(ownership.group, index);
 	const path = join(ownership.directory, `candidate-${index}`);
@@ -589,7 +590,7 @@ export async function createCandidateWorktreeMapped(
 				branch,
 				base: baseline,
 				path,
-				label: `clio compete ${ownership.group} candidate ${index}`,
+				label: `clio-coder compete ${ownership.group} candidate ${index}`,
 				focus: false,
 			})
 			.catch(() => null);
@@ -652,7 +653,7 @@ function exactGroupBranches(root: string, group: string): string[] {
 			const parts = branch.split("/");
 			return (
 				parts.length === 4 &&
-				parts[0] === "clio" &&
+				(parts[0] === "clio-coder" || parts[0] === "clio") &&
 				parts[1] === "compete" &&
 				parts[2] === group &&
 				/^\d+$/.test(parts[3] ?? "")
@@ -660,6 +661,16 @@ function exactGroupBranches(root: string, group: string): string[] {
 		});
 }
 
+/** Resolve a current candidate branch while retaining indefinite read support for released refs. */
+export function competeBranchForCandidate(root: string, group: string, index: number): string {
+	const branches = exactGroupBranches(root, group);
+	return (
+		branches.find((branch) => branch === competeBranch(group, index)) ??
+		branches.find((branch) => branch === competeBranch(group, index, true)) ??
+		competeBranch(group, index)
+	);
+}
+
 function removeRegisteredWorktree(root: string, path: string): void {
 	try {
 		git(root, ["worktree", "remove", "--force", path]);
@@ -676,10 +687,9 @@ function removeCandidateWorktree(
 ): void {
 	assertOwnership(ownership);
 	const expectedPath = join(ownership.directory, `candidate-${worktree.index}`);
-	const expectedBranch = competeBranch(ownership.group, worktree.index);
 	if (
 		resolve(worktree.path) !== resolve(expectedPath) ||
-		worktree.branch !== expectedBranch ||
+		!competeBranchMatches(worktree.branch, ownership.group, worktree.index) ||
 		!isCanonicalPathInside(ownership.directory, worktree.path)
 	) {
 		throw new Error(`candidate ${worktree.index} does not belong to compete group ${ownership.group}`);
@@ -819,8 +829,8 @@ export function settleRecoveredCompeteDecision(
 		cleanupWorktreeGroup(ownership);
 		return null;
 	}
-	const winnerBranch = competeBranch(group, winnerIndex);
 	const branches = exactGroupBranches(ownership.root, group);
+	const winnerBranch = competeBranchForCandidate(ownership.root, group, winnerIndex);
 	const winnerPath = join(ownership.directory, `candidate-${winnerIndex}`);
 	if (
 		!branches.includes(winnerBranch) ||