@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/tools/monitor-surface.ts

@@ -6,7 +6,7 @@ import type { ToolSurface } from "./lazy-tool.js";
 export const monitorToolSurface = {
 	name: ToolNames.Monitor,
 	description:
-		"Inspect known dispatched runs. Parent-model mid-run observation requires detach:true because ordinary dispatch auto-waits. wait observes without collecting. collect is the authoritative terminal batch operation; collect detached runs before final synthesis. receipt exposes stored evidence. Receipt integrity, evidence verification, briefing provenance, and project-context provenance are separate fields.",
+		"Inspect dispatched runs: list enumerates them; status, peek, receipt, and tools observe one run; wait blocks on one run without collecting; collect is the terminal operation for a detached batch or run list, required before final synthesis.",
 	parameters: Type.Object({
 		run_id: Type.Optional(
 			Type.String({ description: "Run id from dispatch output or monitor list; omit with mode=list." }),
@@ -14,21 +14,13 @@ export const monitorToolSurface = {
 		mode: Type.Optional(
 			StringEnum(["status", "peek", "receipt", "list", "wait", "collect", "tools"], {
 				description:
-					"What to return. Defaults to status when run_id is present and list when it is absent. status, peek, receipt, tools, and wait each observe one run and require a run_id; list takes none. tools answers what a run executed: its tool calls with outcomes, plus per-tool totals from the receipt.",
-			}),
-		),
-		batch_id: Type.Optional(Type.String({ description: "Detached batch id from dispatch detach:true (mode=collect)." })),
-		run_ids: Type.Optional(
-			Type.Array(Type.String(), {
-				description:
-					"Explicit run ids for mode=collect; a one-element array is also accepted by single-run modes when run_id is absent.",
+					"Defaults to status with run_id and list without. tools lists a run's tool calls with outcomes and per-tool totals.",
 			}),
 		),
+		batch_id: Type.Optional(Type.String({ description: "Detached batch id (mode=collect)." })),
+		run_ids: Type.Optional(Type.Array(Type.String(), { description: "Run ids to collect (mode=collect)." })),
 		timeout_ms: Type.Optional(
-			Type.Number({
-				description:
-					"mode=wait: max ms to block (default 60000, capped at 600000); mode=collect never blocks and ignores this value with a notice.",
-			}),
+			Type.Number({ description: "mode=wait: max ms to block (default 60000, max 600000); collect never blocks." }),
 		),
 	}),
 	baseActionClass: "read",

package/src/tools/monitor.ts

@@ -214,16 +214,16 @@ const TOOLS_MAX_BYTES = 8 * 1024;
 const TOOLS_ARGUMENTS_CHARS = 160;
 
 /**
- * Tail event types that describe one tool call. `clio_tool_finish` is the
+ * Tail event types that describe one tool call. `clio_coder_tool_finish` is the
  * authoritative per-call outcome (it distinguishes a permission block from a
  * command that ran and exited nonzero); the engine's own `tool_execution_end`
  * is kept only when the tail recorded a detail for it, since a bare type line
  * says nothing the finish event does not.
  */
 const TOOL_CALL_EVENT_TYPES: ReadonlySet<string> = new Set([
-	"clio_tool_finish",
-	"clio_permission_resolved",
-	"clio_permission_escalated",
+	"clio_coder_tool_finish",
+	"clio_coder_permission_resolved",
+	"clio_coder_permission_escalated",
 ]);
 
 function toolCallLines(entries: ReadonlyArray<{ at: string; type: string; detail?: string }>): string[] {

package/src/tools/observation.ts

@@ -1,4 +1,4 @@
-import { GUARDRAIL_DEFAULTS, GUARDRAIL_ENV_VARS, resolveGuardrail } from "../core/guardrails.js";
+import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../core/guardrails.js";
 import type { ToolInvokeOptions, ToolResult } from "./registry.js";
 import { offloadPointer, writeToolOffload } from "./result-shaping.js";
 import { formatSize } from "./truncate.js";
@@ -64,9 +64,8 @@ export const OBSERVE_SELF_CAPS = {
 
 // Per-turn observation budget pool. One pool per sessionId:turnId shared by
 // every OBSERVE tool; LRU-pruned so abandoned turns cannot grow the map.
-// Value, settings key, and env override live in core/guardrails.ts.
+// The configurable value lives at safety.limits.observationBytesPerTurn.
 export const DEFAULT_OBSERVATION_TURN_BUDGET_BYTES = GUARDRAIL_DEFAULTS.observationTurnBudgetBytes;
-export const OBSERVATION_TURN_BUDGET_ENV = GUARDRAIL_ENV_VARS.observationTurnBudgetBytes;
 const MIN_BUDGET_SLICE_BYTES = 1024;
 const BUDGET_TRACK_LIMIT = 256;
 
@@ -130,8 +129,8 @@ function boundContinuation(next: string | undefined): string | undefined {
 	return `${Array.from(next).slice(0, MAX_CONTINUATION_CHARS).join("")}…`;
 }
 
-function observationTurnBudgetLimit(env: NodeJS.ProcessEnv = process.env): number {
-	return Math.max(MIN_BUDGET_SLICE_BYTES, resolveGuardrail("observationTurnBudgetBytes", env));
+function observationTurnBudgetLimit(): number {
+	return Math.max(MIN_BUDGET_SLICE_BYTES, resolveGuardrail("observationTurnBudgetBytes"));
 }
 
 function budgetKey(options: ToolInvokeOptions | undefined): string | null {

package/src/tools/observers.ts

@@ -44,39 +44,6 @@ export interface FileMutationEvent {
 	toolName: string;
 }
 
-/**
- * Defers file-mutation sinks off the after_tool hot path and coalesces rapid
- * events into one best-effort batch. Lifecycle-owned sinks that must drain at
- * shutdown should admit work synchronously instead of using this convenience.
- */
-export function coalescePathSink(sink: (paths: string[]) => void): (event: FileMutationEvent) => void {
-	const pending = new Set<string>();
-	let flushScheduled = false;
-
-	const scheduleFlush = (): void => {
-		if (flushScheduled) return;
-		flushScheduled = true;
-		setImmediate(() => {
-			flushScheduled = false;
-			if (pending.size === 0) return;
-			const paths = [...pending];
-			pending.clear();
-			try {
-				sink(paths);
-			} catch {
-				// Incremental indexing is best-effort and must not change tool execution.
-			}
-			if (pending.size > 0) scheduleFlush();
-		});
-	};
-
-	return (event) => {
-		if (event.paths.length === 0) return;
-		for (const path of event.paths) pending.add(path);
-		scheduleFlush();
-	};
-}
-
 /** Notifies the caller after a successful file-mutating tool, for incremental indexing. */
 export function createFileMutationObserver(sink: (event: FileMutationEvent) => void): MiddlewareHookRegistration {
 	return {

package/src/tools/panes-surface.ts

@@ -15,23 +15,16 @@ import type { ToolSurface } from "./lazy-tool.js";
 export const panesToolSurface = {
 	name: ToolNames.Panes,
 	description:
-		"Look at, focus, and manage the terminal panes Clio owns beside this session. Use show to bring a dispatched run's live viewer pane to the front when the operator asks to see an agent (\"show me the tester\"). open starts one of the fixed utility presets; there is no way to run an arbitrary command. close removes a pane Clio created. list reports the current inventory and the pane layer's health.",
+		"Manage the terminal panes Clio owns beside this session: show focuses a dispatched run's viewer pane, open starts a fixed utility preset (files, logs, or shell; never an arbitrary command) or focuses it when it is already open, close removes a Clio-created pane, list reports the inventory and the pane layer's health.",
 	parameters: Type.Object({
-		action: StringEnum(["show", "open", "close", "list"], {
-			description:
-				"show focuses a run's viewer pane; open starts a preset utility pane; close removes a Clio-owned pane; list reports the inventory.",
-		}),
+		action: StringEnum(["show", "open", "close", "list"], { description: "Pane action." }),
 		target: Type.Optional(
 			Type.String({
 				description:
-					'action=show: an agent id or run id prefix, most recent match wins. action=close: a pane id, a pane label, an agent id, or "all".',
-			}),
-		),
-		preset: Type.Optional(
-			StringEnum([...PANES_PRESET_IDS], {
-				description: "action=open: which fixed utility pane to start.",
+					'show: an agent id or run id prefix, most recent match wins. close: a pane id, label, agent id, or "all".',
 			}),
 		),
+		preset: Type.Optional(StringEnum([...PANES_PRESET_IDS], { description: "open: which utility pane to start." })),
 	}),
 	baseActionClass: "read",
 	executionMode: "sequential",

package/src/tools/panes.ts

@@ -78,8 +78,10 @@ export function createPanesTool(deps: PanesToolDeps): ToolSpec {
 						kind: "ok",
 						output:
 							result.paneId === null
-								? `completed the ${result.label} chooser.`
-								: `opened the ${result.label} pane (${result.paneId}).`,
+								? `completed the ${result.label} pick.`
+								: result.existing
+									? `the ${result.label} pane was already open and is now focused (${result.paneId}).`
+									: `opened the ${result.label} pane (${result.paneId}).`,
 						details: { action: "open", preset, paneId: result.paneId },
 					};
 				}

package/src/tools/policy.ts

@@ -81,6 +81,13 @@ const DISPATCH_BOUND_TOOLS = new Set<ToolName>([ToolNames.Dispatch, ToolNames.Mo
 const INTERACTIVE_BOUND_TOOLS = new Set<ToolName>([ToolNames.AskUser]);
 /** Registered only when a pane host answered detection and the mux is live. */
 const PANES_BOUND_TOOLS = new Set<ToolName>([ToolNames.Panes]);
+/**
+ * Registered only when a dispatch bound an agent-ledger port to this registry,
+ * which only a worker process does. The session has no peers to coordinate
+ * with, so on that surface the tool could only answer "no ledger" and its
+ * schema was 444 tokens of every first turn for nothing.
+ */
+const LEDGER_BOUND_TOOLS = new Set<ToolName>([ToolNames.Ledger]);
 /** The RETRIEVE plane, omitted wholesale by a hermetic run (tools/network-policy.ts). */
 const NETWORK_BOUND_TOOLS = new Set<ToolName>([ToolNames.WebFetch]);
 
@@ -89,15 +96,19 @@ export interface BuiltinToolPolicyOptions {
 	includeDispatchTools?: boolean;
 	includeInteractiveTools?: boolean;
 	includePanesTools?: boolean;
+	includeLedgerTools?: boolean;
 	/**
-	 * Unlike the other four, this defaults to true: every registry registers
+	 * Unlike the others, this defaults to true: every registry registers
 	 * the network plane unless a run explicitly asked to be hermetic, so an
 	 * unset option must keep demanding it.
 	 */
 	includeNetworkTools?: boolean;
 }
 
-function validateBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: BuiltinToolPolicyOptions = {}): string[] {
+export function validateBuiltinToolPolicy(
+	specs: ReadonlyArray<ToolSpec>,
+	options: BuiltinToolPolicyOptions = {},
+): string[] {
 	const errors: string[] = [];
 	const registered = new Map<ToolName, ToolSpec>();
 
@@ -140,6 +151,7 @@ function validateBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: Buil
 	const includeDispatchTools = options.includeDispatchTools ?? false;
 	const includeInteractiveTools = options.includeInteractiveTools ?? false;
 	const includePanesTools = options.includePanesTools ?? false;
+	const includeLedgerTools = options.includeLedgerTools ?? false;
 	const includeNetworkTools = options.includeNetworkTools ?? true;
 	const required = new Set<ToolName>(Object.values(ToolNames));
 	for (const tool of [...required]) {
@@ -147,6 +159,7 @@ function validateBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: Buil
 		if (!includeDispatchTools && DISPATCH_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeInteractiveTools && INTERACTIVE_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includePanesTools && PANES_BOUND_TOOLS.has(tool)) required.delete(tool);
+		if (!includeLedgerTools && LEDGER_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeNetworkTools && NETWORK_BOUND_TOOLS.has(tool)) required.delete(tool);
 	}
 	for (const tool of required) {

package/src/tools/read.ts

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { Type } from "typebox";
-import { GUARDRAIL_DEFAULTS, GUARDRAIL_ENV_VARS, resolveGuardrail } from "../core/guardrails.js";
+import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../core/guardrails.js";
 import { ToolNames } from "../core/tool-names.js";
 import { finalizeObservation, observationBudgetExhausted, reserveObservation } from "./observation.js";
 import { resolveReadPath } from "./path-utils.js";
@@ -19,14 +19,13 @@ import { truncateUtf8 } from "./truncate-utf8.js";
 // Per-call read cap. Raised from the 16KB per-observation source cap toward
 // pi's 50KB so large source/generated files finish in fewer calls (a 144KB file
 // took ~9 sequential 16KB reads before). The per-turn observation budget
-// (src/tools/observation.ts) still bounds the aggregate. Value, settings key,
-// and env override (CLIO_CODER_READ_MAX_BYTES) live in core/guardrails.ts.
+// (src/tools/observation.ts) still bounds the aggregate. The configurable
+// value lives at safety.limits.readBytesPerCall.
 export const DEFAULT_READ_MAX_BYTES = GUARDRAIL_DEFAULTS.readMaxBytes;
-export const READ_MAX_BYTES_ENV = GUARDRAIL_ENV_VARS.readMaxBytes;
 const MIN_READ_CAP_BYTES = 1024;
 
-export function readMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
-	return Math.max(MIN_READ_CAP_BYTES, resolveGuardrail("readMaxBytes", env));
+export function readMaxBytes(): number {
+	return Math.max(MIN_READ_CAP_BYTES, resolveGuardrail("readMaxBytes"));
 }
 
 export const readTool: ToolSpec = {

package/src/tools/registry.ts

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import type { TSchema } from "typebox";
 import { isWorkerToolCallCapExceededReason } from "../core/guardrails.js";
 import { HEADLESS_PERMISSION_DENIED_MARKER } from "../core/headless-permission.js";
+import { normalizePromptHint } from "../core/prompt-hint.js";
 import {
 	evaluateSkillToolSurface,
 	type PendingSkillToolPolicy,
@@ -49,6 +50,27 @@ export type ToolExecutionMode = "sequential" | "parallel";
 export type ToolSourceScope = "core" | "domain";
 export type ToolRetrySafety = "idempotent" | "retry_safe" | "not_retry_safe" | "unknown";
 export type ToolCostLatencyClass = "local_fast" | "local_medium" | "local_slow" | "network" | "agent";
+export type ToolPromptHintRole = "session" | "worker" | "bound-worker";
+
+export interface ToolPromptHintVariants {
+	session?: string;
+	worker?: string;
+	boundWorker?: string;
+}
+
+export type ToolPromptHintMetadata = string | ToolPromptHintVariants;
+
+/** Resolve one tool's guidance for the exact prompt role being compiled. */
+export function resolveToolPromptHint(
+	hint: ToolPromptHintMetadata | undefined,
+	role: ToolPromptHintRole,
+): string | undefined {
+	if (typeof hint === "string") return normalizePromptHint(hint);
+	if (!hint) return undefined;
+	const selected =
+		role === "session" ? hint.session : role === "bound-worker" ? (hint.boundWorker ?? hint.worker) : hint.worker;
+	return normalizePromptHint(selected);
+}
 
 export interface ToolSourceInfo {
 	path: string;
@@ -77,12 +99,11 @@ export interface ToolMetadata {
 	/** Coarse cost/latency bucket for dashboard diagnostics. */
 	costLatency: ToolCostLatencyClass;
 	/**
-	 * One sentence of usage guidance rendered into the session Tool Contract
-	 * when this tool is on the frozen surface. Hints render sorted by tool
-	 * name, so the compiled prompt stays byte-stable per surface. Most tools
-	 * need none; the schema description covers them.
+	 * One sentence of usage guidance rendered when this tool is on the frozen
+	 * surface. A string applies to every role; variants keep session consent
+	 * rules out of ordinary and recipe-bound workers. Most tools need none.
 	 */
-	promptHint?: string;
+	promptHint?: ToolPromptHintMetadata;
 	/**
 	 * How transcript surfaces present this tool's block under `/output default`.
 	 * Optional: tools that declare nothing fold like every other tool.
@@ -199,6 +220,8 @@ export interface ToolInvokeOptions {
 	turnId?: string;
 	toolCallId?: string;
 	correlationId?: string;
+	/** Session-effective ceiling for one tool result, read again before every invocation. */
+	toolResultMaxBytes?: number;
 	pendingSkillPolicy?: PendingSkillToolPolicy;
 	askUserPolicy?: AskUserToolPolicy;
 	/** Host-derived display copy for an ask_user round. It has no admission authority. */
@@ -442,14 +465,14 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
 				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
 				const result = await spec.run(preparedArgs, options);
-				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const digest = toolResultDigestFor(spec, result, resultDisposition, options);
 				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition);
 				return { kind: "ok", result: finalResult, decision };
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
 				const result: ToolResult = { kind: "error", message };
-				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const digest = toolResultDigestFor(spec, result, resultDisposition, options);
 				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				return {
 					kind: "ok",

package/src/tools/result-shaping.ts

@@ -16,27 +16,30 @@ import {
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateTail } from "./truncate.js";
 import { byteLength, truncateUtf8 } from "./truncate-utf8.js";
 
-// Backstop for tools without an explicit resultSizePolicy. Sits above the
-// per-observation source cap (src/tools/truncate.ts) so a tool's own truncation
-// notice (with its precise continuation offset) survives shaping instead of
-// being cut again and replaced by a generic hint.
-export const DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES + 2 * 1024;
+// Backstop for tools without an explicit resultSizePolicy. Session settings may
+// lower or raise this fallback, while explicit per-tool policies remain tighter.
+export const DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES;
 const RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
 const RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
 const TAIL_NOTICE_RESERVE_BYTES = 512;
 export const TOOL_OFFLOAD_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
 
-type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId">;
+type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId" | "toolResultMaxBytes">;
 
 function mergeDetails(details: ToolResultDetails | undefined, resultSize: Record<string, unknown>): ToolResultDetails {
 	return { ...(details ?? {}), resultSize };
 }
 
-function maxBytesFor(spec: ToolSpec): number {
+function maxBytesFor(spec: ToolSpec, context?: ToolResultShapeContext): number {
 	const configured = spec.metadata?.resultSizePolicy?.maxBytes;
-	return typeof configured === "number" && Number.isFinite(configured) && configured > 0
-		? Math.floor(configured)
-		: DEFAULT_TOOL_RESULT_MAX_BYTES;
+	const policyMax =
+		typeof configured === "number" && Number.isFinite(configured) && configured > 0
+			? Math.floor(configured)
+			: DEFAULT_TOOL_RESULT_MAX_BYTES;
+	const sessionMax = context?.toolResultMaxBytes;
+	return typeof sessionMax === "number" && Number.isFinite(sessionMax) && sessionMax > 0
+		? Math.min(policyMax, Math.floor(sessionMax))
+		: policyMax;
 }
 
 function followUpHint(spec: ToolSpec): string {
@@ -61,11 +64,12 @@ export function toolResultDigestFor(
 	spec: ToolSpec,
 	result: ToolResult,
 	requestedDisposition?: ToolResultDisposition,
+	context?: ToolResultShapeContext,
 ): ToolResultDigest {
 	const text = resultText(result);
-	const disposition = normalizeToolResultDisposition(spec, maxBytesFor(spec), requestedDisposition);
+	const disposition = normalizeToolResultDisposition(spec, maxBytesFor(spec, context), requestedDisposition);
 	if (disposition === null) {
-		const projected = shapeLegacyToolResult(spec, result);
+		const projected = shapeLegacyToolResult(spec, result, context);
 		return legacyToolResultDigest(resultText(projected), { outcome: result.kind });
 	}
 	const capturedBytes = capturedBytesFor(result, text);
@@ -298,7 +302,7 @@ function shapeLegacyToolResult(
 	overflow: "head" | "tail" = "head",
 ): ToolResult {
 	if (existingOffloadPath(result.details) !== null) return result;
-	const maxBytes = maxBytesFor(spec);
+	const maxBytes = maxBytesFor(spec, context);
 	const offloadMaxBytes = offloadMaxBytesFor(spec);
 	const text = result.kind === "ok" ? result.output : result.message;
 	const bytes = byteLength(text);
@@ -410,7 +414,7 @@ export function shapeToolResult(
 	requestedDisposition?: ToolResultDisposition,
 ): ToolResult {
 	if (existingDisposition(result.details) !== null) return result;
-	const hardMaxBytes = maxBytesFor(spec);
+	const hardMaxBytes = maxBytesFor(spec, context);
 	const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
 	if (disposition === null) return shapeLegacyToolResult(spec, result, context);
 

package/src/tools/steer-surface.ts

@@ -6,7 +6,7 @@ import type { ToolSurface } from "./lazy-tool.js";
 export const steerToolSurface = {
 	name: ToolNames.Steer,
 	description:
-		"Control a running native worker whose run id is already available. Parent-model mid-run control requires detach:true because ordinary dispatch auto-waits and dispatch/steer are sequential; the interactive operator/TUI may steer an active synchronous native run through the dispatch contract. ACP runs have no input channel.",
+		"Guide or cancel a running native worker by run id. Only a detached run can be steered from here, because an ordinary dispatch auto-waits; ACP runs have no input channel.",
 	parameters: Type.Object({
 		run_id: Type.String({ description: "Run id from dispatch output or monitor list." }),
 		action: StringEnum(["guide", "cancel"], { description: "What to do." }),

package/src/tools/task-worktree.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 export type TaskWorktreeApply = "merge" | "preserve";
@@ -25,7 +25,9 @@ export interface TaskWorktreeReceipt {
 
 const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const OWNER_FILE_SUFFIX = ".task-owner.json";
-const COMMIT_IDENTITY = "clio-task";
+const TASK_WORKTREE_KIND = "clio-coder-task-worktree";
+const LEGACY_TASK_WORKTREE_KIND = "clio-task-worktree";
+const COMMIT_IDENTITY = "clio-coder-task";
 
 function gitBytes(root: string, args: string[]): Buffer {
 	return execFileSync("git", ["-C", root, ...args], {
@@ -160,7 +162,7 @@ export function createTaskWorktree(root: string, runId: string, base?: string):
 	const resolvedBase = base ?? git(canonical, ["rev-parse", "HEAD"]);
 	const parent = join(canonical, ".clio-coder", "worktrees");
 	const path = join(parent, runId);
-	const branch = `clio/task/${runId}`;
+	const branch = `clio-coder/task/${runId}`;
 	mkdirSync(parent, { recursive: true });
 	if (!isCanonicalWorktreePathInside(parent, path))
 		throw new Error(`task worktree path escapes its parent for run ${runId}`);
@@ -168,7 +170,7 @@ export function createTaskWorktree(root: string, runId: string, base?: string):
 	const ownerToken = randomBytes(16).toString("hex");
 	writeFileSync(
 		`${path}${OWNER_FILE_SUFFIX}`,
-		`${JSON.stringify({ version: 1, kind: "clio-task-worktree", root: canonical, runId, branch, base: resolvedBase, ownerToken }, null, 2)}\n`,
+		`${JSON.stringify({ version: 1, kind: TASK_WORKTREE_KIND, root: canonical, runId, branch, base: resolvedBase, ownerToken }, null, 2)}\n`,
 		{ encoding: "utf8", flag: "wx" },
 	);
 	return { root: canonical, runId, path, branch, base: resolvedBase, ownerToken };
@@ -182,11 +184,30 @@ function assertOwnership(worktree: TaskWorktree): void {
 	) {
 		throw new Error(`task worktree ${worktree.runId} has an invalid ownership path`);
 	}
-	if (!existsSync(`${worktree.path}${OWNER_FILE_SUFFIX}`))
-		throw new Error(`task worktree ${worktree.runId} has no ownership file`);
+	const ownerPath = `${worktree.path}${OWNER_FILE_SUFFIX}`;
+	if (!existsSync(ownerPath)) throw new Error(`task worktree ${worktree.runId} has no ownership file`);
+	let marker: Record<string, unknown>;
+	try {
+		const value = JSON.parse(readFileSync(ownerPath, "utf8")) as unknown;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("not an object");
+		marker = value as Record<string, unknown>;
+	} catch {
+		throw new Error(`task worktree ${worktree.runId} has an invalid ownership file`);
+	}
+	if (
+		marker.version !== 1 ||
+		(marker.kind !== TASK_WORKTREE_KIND && marker.kind !== LEGACY_TASK_WORKTREE_KIND) ||
+		marker.root !== worktree.root ||
+		marker.runId !== worktree.runId ||
+		marker.branch !== worktree.branch ||
+		marker.base !== worktree.base ||
+		marker.ownerToken !== worktree.ownerToken
+	) {
+		throw new Error(`task worktree ${worktree.runId} ownership facts do not match`);
+	}
 }
 
-function commitTaskWorktree(worktree: TaskWorktree, message = `Clio task ${worktree.runId}`): boolean {
+function commitTaskWorktree(worktree: TaskWorktree, message = `Clio Coder task ${worktree.runId}`): boolean {
 	assertOwnership(worktree);
 	return commitWorktreePath(worktree.path, COMMIT_IDENTITY, message);
 }

package/src/tools/tasks.ts

@@ -139,7 +139,7 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 		description:
 			"Session task board. plan declares a titled board (replaces any prior board); add appends tasks; " +
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
-			"done completes a started task and requires note as the " +
+			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
 			"Work that did not happen is blocked or dropped, never done.",
 		parameters: Type.Object({

package/src/tools/truncate.ts

@@ -8,12 +8,13 @@ import {
 	truncateTail as truncatePiTail,
 } from "../engine/truncate.js";
 
-// Per-observation source cap. Pi defaults to 50 KiB; Clio deliberately keeps
-// one result proportional to its per-turn observation budget at 16 KiB. The
-// wrappers below retain only that product-level delta while Pi owns UTF-8-safe
-// head/tail truncation, line limits, grep-line clipping, and size formatting.
+// Per-observation source cap. Pi defaults to 50 KiB; Clio allows 64 KiB while
+// its default 192 KiB turn pool remains authoritative across calls. Three full
+// results consume that pool, so a fourth finds it filled. The wrappers below
+// retain only that product-level delta while Pi owns UTF-8-safe head/tail
+// truncation, line limits, grep-line clipping, and size formatting.
 export const DEFAULT_MAX_LINES = 2000;
-export const DEFAULT_MAX_BYTES = 16 * 1024;
+export const DEFAULT_MAX_BYTES = 64 * 1024;
 export type { TruncationResult };
 export { formatSize, GREP_MAX_LINE_LENGTH, truncateLine };
 

package/src/tools/verify/authoring.ts

@@ -234,7 +234,7 @@ function boundedId(base: string, suffix = ""): string {
 }
 
 /** Allocate the same stable suffix for the same ordered set of occupied IDs. */
-export function deterministicVerifierId(preferredId: string, occupied: ReadonlySet<string>): string {
+function deterministicVerifierId(preferredId: string, occupied: ReadonlySet<string>): string {
 	const base = boundedId(slug(preferredId, "check"));
 	if (!occupied.has(base) && base !== "frontend") return base;
 	for (let index = 2; index <= PROJECT_VERIFIER_CATALOG_CAPS.checks + 2; index += 1) {
@@ -892,7 +892,7 @@ function serializeVerifierDraft(draft: VerifierDraft): string {
 }
 
 /** Validate with the same production parser used by verify(). */
-export function validateVerifierDraft(draft: VerifierDraft): VerifierDraftValidation {
+function validateVerifierDraft(draft: VerifierDraft): VerifierDraftValidation {
 	const text = serializeVerifierDraft(draft);
 	const parsed = parseProjectVerifierCatalogText(text, draft.workspaceRoot, draft.catalogPath);
 	if (!parsed.ok) return { ok: false, reason: parsed.reason, text };
@@ -944,10 +944,7 @@ function cloneDraft(draft: VerifierDraft): VerifierDraft {
 }
 
 /** Apply edits to a copy so a collision or schema failure leaves the prior draft intact. */
-export function reviseVerifierDraft(
-	draft: VerifierDraft,
-	revisions: ReadonlyArray<VerifierRevision>,
-): VerifierRevisionResult {
+function reviseVerifierDraft(draft: VerifierDraft, revisions: ReadonlyArray<VerifierRevision>): VerifierRevisionResult {
 	const next = cloneDraft(draft);
 	const diagnostics: string[] = [];
 	for (const revision of revisions) {

package/src/tools/verify/frontend.ts

@@ -447,7 +447,7 @@ async function checkModuleJavaScript(
 	label: string,
 	options: ValidationOptions,
 ): Promise<string | null> {
-	const dir = mkdtempSync(path.join(tmpdir(), "clio-frontend-check-"));
+	const dir = mkdtempSync(path.join(tmpdir(), "clio-coder-frontend-check-"));
 	const file = path.join(dir, "module.mjs");
 	try {
 		writeFileSync(file, source, "utf8");

package/src/tools/verify/surface.ts

@@ -28,20 +28,14 @@ export const verifyToolSurface = {
 	parameters: Type.Object({
 		check: Type.Optional(
 			Type.String({
-				description: `Declared project check ID, package script (${VERIFICATION_SCRIPT_FAMILY_HINT}), or "frontend". Omit to list available checks.`,
+				description: `Check id, package script (${VERIFICATION_SCRIPT_FAMILY_HINT}), or "frontend"; omit to list.`,
 			}),
 		),
-		path: Type.Optional(Type.String({ description: "check=frontend: artifact file under the workspace root." })),
-		args: Type.Optional(
-			Type.Array(Type.String(), { description: "Package scripts only: extra arguments passed after --." }),
-		),
-		browser: Type.Optional(
-			StringEnum(BROWSER_MODES, { description: "check=frontend: headless browser mode (default auto)." }),
-		),
-		cwd: Type.Optional(Type.String({ description: "Package-script working directory; ignored by project checks." })),
-		timeout_ms: Type.Optional(
-			Type.Number({ description: "Package/frontend timeout in ms; project checks use their declared timeoutMs." }),
-		),
+		path: Type.Optional(Type.String({ description: "frontend: artifact file under the workspace root." })),
+		args: Type.Optional(Type.Array(Type.String(), { description: "Package scripts only: arguments after --." })),
+		browser: Type.Optional(StringEnum(BROWSER_MODES, { description: "frontend: headless browser mode (default auto)." })),
+		cwd: Type.Optional(Type.String({ description: "Package scripts only: working directory." })),
+		timeout_ms: Type.Optional(Type.Number({ description: "Package and frontend checks only: timeout in ms." })),
 		max_output_bytes: Type.Optional(Type.Number({ description: "Output cap in bytes (default 600000)." })),
 	}),
 	baseActionClass: "execute",

package/src/tools/web-fetch-surface.ts

@@ -13,9 +13,7 @@ export const webFetchToolSurface = {
 		timeout_ms: Type.Optional(Type.Number({ description: "Timeout ms (default 30000)." })),
 		max_bytes: Type.Optional(Type.Number({ description: "Max bytes returned (default 600000)." })),
 		format: Type.Optional(
-			Type.String({
-				description: "auto (default: HTML is cleaned to Markdown, other content passes through) or raw (no conversion).",
-			}),
+			Type.String({ description: "auto (default) converts HTML to Markdown; raw returns the body unconverted." }),
 		),
 	}),
 	baseActionClass: "read",

package/src/tools/web-fetch.ts

@@ -256,7 +256,7 @@ function htmlToMarkdown(html: string, baseUrl: string): string {
 		.trim();
 }
 
-export function extractWebFetchContent(
+function extractWebFetchContent(
 	rawText: string,
 	contentType: string,
 	finalUrl: string,

package/src/worker/entry.ts

@@ -122,7 +122,7 @@ async function main(): Promise<number> {
 	setResidencyNoticeSink((notice) => {
 		process.stderr.write(`[worker] residency ${notice.kind}: ${notice.message}\n`);
 		if (notice.kind === "will-not-fit") {
-			emitEvent({ type: "clio_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
+			emitEvent({ type: "clio_coder_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
 		}
 	});
 	const demux = createWorkerStdinDemux();
@@ -227,12 +227,13 @@ async function main(): Promise<number> {
 	const handle = startWorkerRun(input, (event) => emitEvent(projectWorkerEventForStdout(event)));
 	// The demux buffers lines that landed before the runtime handle existed.
 	// Single-shot subprocesses expose no steer method, and an SDK query can race
-	// completion. The runtime emits the receipt-bearing clio_steer_received event
+	// completion. The runtime emits the receipt-bearing clio_coder_steer_received event
 	// only after it accepts the message; rejected input is diagnostic-only.
 	demux.onSteer(
 		createOrderedSteerHandler(
 			(text) => handle.steer?.(text) ?? false,
-			({ text, sequence }) => emitEvent({ type: "clio_steer_received", payload: { chars: text.trim().length, sequence } }),
+			({ text, sequence }) =>
+				emitEvent({ type: "clio_coder_steer_received", payload: { chars: text.trim().length, sequence } }),
 			(reason) => process.stderr.write(`[worker] dropped steer: ${reason}\n`),
 		),
 	);