@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/engine/acp/tool-mediator.ts

@@ -27,7 +27,7 @@ interface MediatorInput {
 	toolGovernance: DelegationToolGovernance;
 	/**
 	 * Session autonomy level (sd-01 §2.5). Applied after the safety net under
-	 * clio-policy governance; `ask` dispositions resolve as non-stall denials
+	 * clio-coder-policy governance; `ask` dispositions resolve as non-stall denials
 	 * because a delegation has no operator to answer a prompt.
 	 */
 	autonomy?: AutonomyLevel;
@@ -579,7 +579,7 @@ export class AcpToolMediator {
 		let safetyDecision: SafetyDecision | undefined;
 
 		if (mapped.validationError !== undefined) {
-			if (this.input.toolGovernance === "clio-policy") {
+			if (this.input.toolGovernance === "clio-coder-policy") {
 				const invalidSafetyDecisions = mapped.evaluations.map((evaluation) =>
 					this.input.safety.evaluate({ tool: evaluation.tool, args: evaluation.args }),
 				);

package/src/engine/acp/types.ts

@@ -7,6 +7,13 @@ import type { AgentMessage } from "../types.js";
  */
 export const ACP_USAGE_META_KEY = "clio-coder/usage";
 export const ACP_SESSION_META_KEY = "clio-coder/session";
+/**
+ * Per-frame agent attribution on `session/update`. It names which agent
+ * produced the frame so a client can label a message, reasoning item, or tool
+ * call instead of attributing every frame to the product. Purely additive: a
+ * client that does not read it sees exactly the frames it saw before.
+ */
+export const ACP_AGENT_META_KEY = "clio-coder/agent";
 
 /**
  * Wire bounds for one prompt turn (CONTRACT C001 §3). A client renders every
@@ -27,7 +34,7 @@ export const ACP_MAX_CHUNK_BYTES = 16384;
  * Upper bound on a `toolCallId` this server puts on the wire, in UTF-8 bytes
  * (CONTRACT C001 §3). Identity is one call per id in both directions: an engine
  * id over this bound, missing, or already claimed by another call this turn
- * travels under a `clio-tool-<n>` alias, and an engine id starting a second call
+ * travels under a `clio-coder-tool-<n>` alias, and an engine id starting a second call
  * mints a fresh alias rather than reusing the first call's wire id. A permission
  * request binds only to an id the client already received a `tool_call` for and
  * has not yet seen finish; nothing is minted on that path.
@@ -87,11 +94,20 @@ export interface AcpImplementationInfo {
 	version?: string;
 }
 
+export interface AcpAuthMethod {
+	id: string;
+	name: string;
+	description?: string;
+	type: "agent" | "terminal";
+	args?: string[];
+	env?: Record<string, string>;
+}
+
 export interface AcpInitializeResponse {
 	protocolVersion?: number;
 	agentCapabilities?: Record<string, unknown>;
 	agentInfo?: AcpImplementationInfo;
-	authMethods?: unknown[];
+	authMethods?: AcpAuthMethod[];
 }
 
 export interface AcpSessionInfo {
@@ -141,6 +157,8 @@ export interface AcpToolCallUpdate {
 export interface AcpSessionUpdateParams {
 	sessionId?: string;
 	update?: Record<string, unknown>;
+	/** Namespaced extension slot; carries replay and agent-attribution metadata. */
+	_meta?: Record<string, unknown>;
 }
 
 export type AcpPermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always" | string;

package/src/engine/alcf-oauth.ts

@@ -40,7 +40,7 @@ function randomState(): string {
 	return base64Url(bytes);
 }
 
-export function buildAuthorizeUrl(params: { challenge: string; state: string }): string {
+function buildAuthorizeUrl(params: { challenge: string; state: string }): string {
 	const query = new URLSearchParams({
 		client_id: AUTH_CLIENT_ID,
 		response_type: "code",
@@ -55,7 +55,7 @@ export function buildAuthorizeUrl(params: { challenge: string; state: string }):
 	return `${AUTHORIZE_URL}?${query.toString()}`;
 }
 
-export function parseAuthorizationInput(input: string): string {
+function parseAuthorizationInput(input: string): string {
 	const value = input.trim();
 	if (!value) return "";
 	try {
@@ -89,7 +89,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
-export function selectGatewayGrant(payload: GlobusTokenResponse): GlobusTokenGrant {
+function selectGatewayGrant(payload: GlobusTokenResponse): GlobusTokenGrant {
 	const grants: GlobusTokenGrant[] = [payload, ...(Array.isArray(payload.other_tokens) ? payload.other_tokens : [])];
 	const byResourceServer = grants.find((grant) => grant.resource_server === GATEWAY_CLIENT_ID);
 	if (byResourceServer) return byResourceServer;
@@ -103,7 +103,7 @@ export function selectGatewayGrant(payload: GlobusTokenResponse): GlobusTokenGra
 	);
 }
 
-export function grantToCredentials(grant: GlobusTokenGrant, previousRefresh?: string): OAuthCredentials {
+function grantToCredentials(grant: GlobusTokenGrant, previousRefresh?: string): OAuthCredentials {
 	const access = grant.access_token;
 	if (typeof access !== "string" || access.length === 0) {
 		throw new Error("Globus token response is missing an access token for the ALCF gateway.");
@@ -172,7 +172,7 @@ async function refreshGatewayToken(refreshToken: string, signal: AbortSignal): P
 	return grantToCredentials(selectGatewayGrant(payload), refreshToken);
 }
 
-export async function loginAlcf(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+async function loginAlcf(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
 	const { verifier, challenge } = await generatePkce();
 	const url = buildAuthorizeUrl({ challenge, state: randomState() });
 	callbacks.onAuth({

package/src/engine/antigravity/subprocess-runtime.ts

@@ -63,7 +63,7 @@ export function antigravitySubprocessConfigForAutonomy(
 	return { extraArgs: [], dangerousBypass: false, externalMode: "agy-settings-default" };
 }
 
-export function buildAntigravityPrompt(input: WorkerRunInput): string {
+function buildAntigravityPrompt(input: WorkerRunInput): string {
 	const parts: string[] = [];
 	const systemPrompt = input.systemPrompt.trim();
 	if (systemPrompt.length > 0) parts.push(systemPrompt);
@@ -75,7 +75,7 @@ export function buildAntigravityPrompt(input: WorkerRunInput): string {
 	return parts.join("\n\n");
 }
 
-export function buildAgyArgs(input: WorkerRunInput): string[] {
+function buildAgyArgs(input: WorkerRunInput): string[] {
 	assertToolProfileEnforceable(input.toolProfile, "antigravity-code");
 	const permission = antigravitySubprocessConfigForAutonomy(input.autonomy);
 	const args = ["--print", ...permission.extraArgs];

package/src/engine/api-registry.ts

@@ -78,7 +78,7 @@ function unregisterEngineApiProviders(sourceId: string): void {
 	compatUniverse?.unregisterApiProviders(sourceId);
 }
 
-export function getEngineApiProvider(api: Api): EngineRegisteredApiProvider | undefined {
+function getEngineApiProvider(api: Api): EngineRegisteredApiProvider | undefined {
 	return registry.get(api)?.provider;
 }
 

package/src/engine/apis/llamacpp-residency.ts

@@ -5,7 +5,6 @@ import {
 	type ResidencyAdapter,
 	ResidencyPreconditionError,
 	reconcileResidency,
-	resetResidencyState,
 	residencyManaged,
 	residentTagProtected,
 } from "./residency.js";
@@ -72,11 +71,6 @@ interface LlamaCppRouterProps {
 	maxInstances?: number;
 }
 
-/** Test-only: clear the reconciler's TTL cache and Clio-loaded registry. */
-export function resetLlamaCppResidencyState(): void {
-	resetResidencyState();
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -107,19 +101,7 @@ function residentModel(model: LlamaCppRouterModel): boolean {
 	return isResidentState(model.state);
 }
 
-/** Extract resident (loaded, loading, or sleeping) model records from a /v1/models payload. */
-export function parseLlamaCppResidentModels(payload: unknown): LlamaCppResidentModel[] {
-	return parseRouterModels(payload)
-		.filter(residentModel)
-		.map((entry) => ({ id: entry.id, tags: entry.tags }));
-}
-
-/** Extract resident (loaded or loading) model ids from a /v1/models payload. */
-export function parseLlamaCppResident(payload: unknown): string[] {
-	return parseLlamaCppResidentModels(payload).map((entry) => entry.id);
-}
-
-export function parseLlamaCppRouterProps(payload: unknown): LlamaCppRouterProps {
+function parseLlamaCppRouterProps(payload: unknown): LlamaCppRouterProps {
 	if (!isRecord(payload)) return {};
 	const maxInstances = payload.max_instances;
 	return typeof maxInstances === "number" && Number.isFinite(maxInstances) && maxInstances > 0

package/src/engine/apis/lmstudio.ts

@@ -19,7 +19,7 @@ interface LmStudioModelMetadata {
 	clio?: {
 		targetId: string;
 		runtimeId: string;
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		lmstudio?: TargetDescriptor["lmstudio"];
 		lmstudioDefaultModel?: string;
 	};
@@ -145,11 +145,6 @@ function emitResidencyNoticeOnce(key: string, notice: Parameters<typeof emitResi
 	emitResidencyNotice(notice);
 }
 
-/** Test seam: forget which residency facts were announced. */
-export function resetAnnouncedResidencyFacts(): void {
-	announcedResidencyFacts.clear();
-}
-
 export async function ensureLmStudioResidency(
 	model: Model<"openai-completions">,
 	options: { apiKey?: string; signal?: AbortSignal } = {},

package/src/engine/apis/ollama-native.ts

@@ -47,7 +47,7 @@ interface ClioRuntimeMetadata {
 		targetId: string;
 		runtimeId: string;
 		/** Present only when settings set the target lifecycle explicitly. */
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		family?: string;
 		quirks?: LocalModelQuirks;
@@ -159,7 +159,7 @@ function userToOllama(content: string | (TextContent | ImageContent)[]): OllamaM
 	return out;
 }
 
-export function assistantToOllama(content: AssistantMessage["content"]): OllamaMessage {
+function assistantToOllama(content: AssistantMessage["content"]): OllamaMessage {
 	const textParts: string[] = [];
 	const toolCalls: OllamaToolCall[] = [];
 	const thinkingParts: string[] = [];
@@ -270,7 +270,7 @@ function ollamaEvictClient(baseUrl: string, headers?: Record<string, string>): O
  * Map an Ollama `/api/ps` response to the runtime-agnostic resident shape,
  * preserving the GPU/total footprint when the server reports it.
  */
-export async function listResidentOllamaModels(client: OllamaEvictClient): Promise<ResidentModelInfo[]> {
+async function listResidentOllamaModels(client: OllamaEvictClient): Promise<ResidentModelInfo[]> {
 	const resident = await client.ps();
 	return resident.models.map((entry) => {
 		const primary = entry.model || entry.name;

package/src/engine/apis/openai-completions.ts

@@ -64,7 +64,7 @@ interface ClioRuntimeMetadata {
 		targetId: string;
 		runtimeId: string;
 		/** Present only when settings set the target lifecycle explicitly. */
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		quirks?: LocalModelQuirks;
 		chatTemplateKwargsUnsupported?: boolean;
@@ -679,7 +679,7 @@ function hasReportedReasoningUsage(usage: Usage): boolean {
  * upstream already reported reasoning usage, because ACP consumers accept all
  * three field spellings for cross-agent compatibility.
  */
-export function applyOpenAICompatReasoningEstimate(message: AssistantMessage): void {
+function applyOpenAICompatReasoningEstimate(message: AssistantMessage): void {
 	if (hasReportedReasoningUsage(message.usage)) return;
 	const estimated = estimateReasoningTokens(message.content);
 	const reportedOutput = message.usage.output;

package/src/engine/apis/residency.ts

@@ -130,7 +130,7 @@ export function residentTagProtected(tags: ReadonlyArray<string> | undefined): b
 const clioLoaded = new Map<string, Set<string>>();
 
 /** Record that Clio loaded `modelId` on the target identified by `targetKey`. */
-export function markClioLoaded(targetKey: string, modelId: string): void {
+function markClioLoaded(targetKey: string, modelId: string): void {
 	let set = clioLoaded.get(targetKey);
 	if (!set) {
 		set = new Set();
@@ -156,12 +156,6 @@ function isClioLoaded(targetKey: string, entry: ResidentModelInfo): boolean {
 export const RECONCILE_TTL_MS = 60_000;
 const reconcileCache = new Map<string, { modelId: string; decision: "reconcile" | "observe"; at: number }>();
 
-/** Test-only: clear the cross-call Clio-loaded registry and TTL cache. */
-export function resetResidencyState(): void {
-	clioLoaded.clear();
-	reconcileCache.clear();
-}
-
 // --- residency decision (pure) ----------------------------------------------
 
 /**
@@ -301,7 +295,7 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
  * tiers, eviction order, and every notice case directly testable without a
  * server.
  */
-export function decideResidency(facts: ResidencyFacts): ResidencyPlan {
+function decideResidency(facts: ResidencyFacts): ResidencyPlan {
 	const notices: ResidencyNotice[] = [];
 	const keepResident = facts.resident.some((entry) => residentMatchesKeep(entry, facts.keepModelId));
 	const others = facts.resident.filter((entry) => !residentMatchesKeep(entry, facts.keepModelId));
@@ -801,7 +795,7 @@ export function residencyManaged(env: NodeJS.ProcessEnv = process.env): boolean
  * only sets the metadata field when settings carry an explicit value.
  */
 export function residencyManagedFor(
-	lifecycle: "user-managed" | "clio-managed" | undefined,
+	lifecycle: "user-managed" | "clio-coder-managed" | undefined,
 	env: NodeJS.ProcessEnv = process.env,
 ): boolean {
 	if (lifecycle === "user-managed") return false;

package/src/engine/claude/sdk-module.ts

@@ -0,0 +1,87 @@
+/**
+ * Lazy loader for the optional `@anthropic-ai/claude-agent-sdk` package.
+ *
+ * The SDK's platform package ships a 224MB proprietary binary, so it lives in
+ * `optionalDependencies` and a default install skips it under
+ * `npm install --omit=optional`. Nothing may import it at module scope: boot,
+ * `doctor`, and every non-Claude runtime have to work on an install that never
+ * fetched it. The one value the runtime needs (`query`) is reached through the
+ * dynamic import below, at the moment a `claude-sdk` run actually starts, and a
+ * missing package surfaces as a typed error naming the package and the install
+ * command instead of an ESM resolution stack.
+ */
+import type { query } from "@anthropic-ai/claude-agent-sdk";
+
+/** The optional package this module resolves. */
+export const CLAUDE_AGENT_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Version the checkout pins in `optionalDependencies`. A contract test keeps
+ * the two in step so the install command quoted in the diagnostic never drifts
+ * from the version the runtime was built against.
+ */
+export const CLAUDE_AGENT_SDK_VERSION = "0.3.186";
+
+/** Exact command an operator can paste to make the Claude SDK runtime usable. */
+export const CLAUDE_AGENT_SDK_INSTALL_COMMAND = `npm install ${CLAUDE_AGENT_SDK_PACKAGE}@${CLAUDE_AGENT_SDK_VERSION}`;
+
+/** The slice of the SDK surface the worker runtime calls. */
+export interface ClaudeAgentSdkModule {
+	query: typeof query;
+}
+
+/** Thrown when a `claude-sdk` run starts on an install that omitted the optional package. */
+export class ClaudeAgentSdkUnavailableError extends Error {
+	readonly code = "CLAUDE_AGENT_SDK_UNAVAILABLE";
+	readonly packageName = CLAUDE_AGENT_SDK_PACKAGE;
+	readonly installCommand = CLAUDE_AGENT_SDK_INSTALL_COMMAND;
+
+	constructor(cause?: unknown) {
+		super(
+			`The claude-sdk runtime needs the optional package ${CLAUDE_AGENT_SDK_PACKAGE}, which is not installed. ` +
+				`Install it with \`${CLAUDE_AGENT_SDK_INSTALL_COMMAND}\` (or reinstall clio-coder without \`--omit=optional\`), ` +
+				`then select the target again. Every other runtime works without it.`,
+			cause === undefined ? undefined : { cause },
+		);
+		this.name = "ClaudeAgentSdkUnavailableError";
+	}
+}
+
+/** Resolution failures that mean "the package is not on disk" rather than "the package is broken". */
+const MISSING_MODULE_CODES: ReadonlySet<string> = new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_PACKAGE_PATH_NOT_EXPORTED",
+]);
+
+function isMissingModuleError(error: unknown): boolean {
+	const code = (error as { code?: unknown } | null)?.code;
+	return typeof code === "string" && MISSING_MODULE_CODES.has(code);
+}
+
+export type ClaudeAgentSdkLoader = () => Promise<ClaudeAgentSdkModule>;
+
+// The literal specifier is what keeps the SDK's types available here; the tsup
+// `external` entry keeps esbuild from bundling it and leaves this as a real
+// runtime `import()`.
+const realLoader: ClaudeAgentSdkLoader = async () => await import("@anthropic-ai/claude-agent-sdk");
+
+const loader: ClaudeAgentSdkLoader = realLoader;
+let cached: ClaudeAgentSdkModule | null = null;
+
+/**
+ * Resolve the SDK, or fail with {@link ClaudeAgentSdkUnavailableError}. A load
+ * error that is not a resolution failure (a broken install, a throwing module
+ * top level) propagates unchanged, so a real fault is never mislabeled as an
+ * absent package.
+ */
+export async function loadClaudeAgentSdk(): Promise<ClaudeAgentSdkModule> {
+	if (cached) return cached;
+	try {
+		cached = await loader();
+		return cached;
+	} catch (error) {
+		if (isMissingModuleError(error)) throw new ClaudeAgentSdkUnavailableError(error);
+		throw error;
+	}
+}

package/src/engine/claude/sdk-runtime.ts

@@ -1,15 +1,18 @@
-import {
-	type CanUseTool,
-	type EffortLevel,
-	type HookCallback,
-	type Options,
-	type PermissionMode,
-	type PermissionResult,
+// Types only. `@anthropic-ai/claude-agent-sdk` is an optional dependency, so
+// nothing here may reach it at module scope; the one value this runtime calls
+// (`query`) comes from the lazy loader in ./sdk-module.js at run time.
+import type {
+	CanUseTool,
+	EffortLevel,
+	HookCallback,
+	Options,
+	PermissionMode,
+	PermissionResult,
 	query,
-	type SDKMessage,
-	type SDKResultMessage,
-	type SDKUserMessage,
-	type ThinkingConfig,
+	SDKMessage,
+	SDKResultMessage,
+	SDKUserMessage,
+	ThinkingConfig,
 } from "@anthropic-ai/claude-agent-sdk";
 
 import { readClioVersion } from "../../core/package-root.js";
@@ -19,6 +22,7 @@ import { isReserveAdmittedTool, resolveDeliveryTools } from "../loop-guard.js";
 import type { AgentEvent, AgentMessage, Usage } from "../types.js";
 import type { WorkerEventEmit, WorkerRunHandle, WorkerRunInput, WorkerRunResult } from "../worker-runtime.js";
 import { createWorkerSafety } from "../worker-tools.js";
+import { loadClaudeAgentSdk } from "./sdk-module.js";
 import { isClaudeCodeSessionId } from "./session-id.js";
 import {
 	type ClaudeToolPermissionDecision,
@@ -49,11 +53,11 @@ async function* oneSdkUserMessage(message: SDKUserMessage): AsyncIterable<SDKUse
 	yield message;
 }
 
-export function claudeSdkPermissionModeForAutonomy(_level: AutonomyLevel | undefined): PermissionMode {
+function claudeSdkPermissionModeForAutonomy(_level: AutonomyLevel | undefined): PermissionMode {
 	return "default";
 }
 
-export function claudeSdkToolsForAutonomy(_level: AutonomyLevel | undefined): NonNullable<Options["tools"]> {
+function claudeSdkToolsForAutonomy(_level: AutonomyLevel | undefined): NonNullable<Options["tools"]> {
 	return DEFAULT_CLAUDE_TOOLS;
 }
 
@@ -310,7 +314,7 @@ export interface ClaudeWorkerBudgetGate {
 }
 
 /** Canonical call counter shared by the SDK's PreToolUse/canUseTool mediation seam. */
-export function createClaudeWorkerBudgetGate(
+function createClaudeWorkerBudgetGate(
 	budget: WorkerBudget,
 	onBoundary: () => void,
 	onHardCap: () => void,
@@ -434,7 +438,7 @@ function decideToolUse(
 }
 
 /** Share one logical permission decision across the SDK hook/callback pair. */
-export function decideClaudeSdkToolUseOnce(
+function decideClaudeSdkToolUseOnce(
 	handled: Map<string, ClaudeToolPermissionDecision>,
 	toolUseID: string | undefined,
 	decide: () => ClaudeToolPermissionDecision,
@@ -532,7 +536,7 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 				() => {},
 				() => {
 					budgetFailure = true;
-					emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+					emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
 					abort();
 				},
 				resolveDeliveryTools(allowedToolSet, input.product),
@@ -559,7 +563,7 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 		if (hookInput.hook_event_name !== "PostToolBatch" || !budgetGate?.phaseReached()) return { continue: true };
 		if (input.budget?.synthesis === false) {
 			budgetFailure = true;
-			emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+			emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
 			return { continue: false, stopReason: `worker agent budget reached (${input.budget.toolCalls})` };
 		}
 		return {
@@ -607,6 +611,10 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 
 		emit({ type: "agent_start" } as AgentEvent);
 		try {
+			// First touch of the optional SDK. An install that omitted it fails
+			// here with a typed diagnostic naming the package and the install
+			// command, and lands in the catch below as an ordinary run failure.
+			const { query } = await loadClaudeAgentSdk();
 			queryHandle = query({ prompt: buildClaudeSdkPrompt(input), options });
 			for await (const sdkMessage of queryHandle) {
 				if (sdkMessage.type === "system" && (sdkMessage as { subtype?: string }).subtype === "init") {

package/src/engine/claude/subprocess-runtime.ts

@@ -54,7 +54,7 @@ function buildClaudeCodePrompt(input: WorkerRunInput): string {
 	return parts.join("\n\n");
 }
 
-export function buildClaudeCodeArgs(input: WorkerRunInput): string[] {
+function buildClaudeCodeArgs(input: WorkerRunInput): string[] {
 	assertToolProfileEnforceable(input.toolProfile, "claude-code");
 	const permission = claudeSubprocessPermissionConfigForAutonomy(input.autonomy);
 	const args = [

package/src/engine/claude/tool-safety.ts

@@ -227,7 +227,7 @@ function budgetDenial(
 	};
 }
 
-export function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput): ClaudeToolPermissionDecision {
+function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput): ClaudeToolPermissionDecision {
 	const mapped = mapClaudeToolCall(input.toolName, input.input, input.cwd);
 	const call: ClassifierCall = { tool: mapped.clioToolName, args: mapped.args };
 	const attempt = input.budgetGate?.attempt(mapped.clioToolName);
@@ -346,7 +346,7 @@ function emitToolFinish(
 	const finalReasonCode = reasonCode ?? decision.policy?.reasonCode;
 	if (finalReasonCode !== undefined) event.reasonCode = finalReasonCode;
 	if (decision.policy?.policySource !== undefined) event.policySource = decision.policy.policySource;
-	emit({ type: "clio_tool_finish", payload: event });
+	emit({ type: "clio_coder_tool_finish", payload: event });
 }
 
 export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermissionInput): ClaudeToolPermissionDecision {
@@ -366,7 +366,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 		startedAt,
 		...(action !== null ? { action } : {}),
 	};
-	input.emit({ type: "clio_tool_start", payload: start });
+	input.emit({ type: "clio_coder_tool_start", payload: start });
 	if (decision.kind === "allow") {
 		emitToolFinish(
 			input.emit,
@@ -383,7 +383,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 	if (decision.permissionRequired) {
 		const mode = input.onPermission ?? "deny";
 		input.emit({
-			type: "clio_permission_resolved",
+			type: "clio_coder_permission_resolved",
 			payload: {
 				tool: decision.mapped.clioToolName,
 				actionClass: decision.decision.classification.actionClass,

package/src/engine/loop-guard.ts

@@ -352,11 +352,6 @@ export function isLoopGuardSynthesisBackstopReason(reason: string): boolean {
 	return /^loop guard: tool calls stayed disabled and .+ was called again instead of answering/.test(reason);
 }
 
-/** Worker lifetime tool-call cap: env > settings guardrails > default. */
-export function readWorkerToolCallCap(env: NodeJS.ProcessEnv = process.env): number {
-	return resolveGuardrail("workerToolCallCap", env);
-}
-
 /** Soft/hard per-turn tool-call budget for the interactive orchestrator. */
 export interface OrchTurnToolCallBudget {
 	/** Distinct calls in a turn that trigger the re-plan nudge. */

package/src/engine/session.ts

@@ -39,6 +39,7 @@ import {
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { normalizeClioCoderEventTree } from "../core/naming-events.js";
 import { readClioVersion, readPiMonoVersion } from "../core/package-root.js";
 import { assertSafeId } from "../core/safe-id.js";
 import { fsyncDirectory, safeResourceWrite } from "../core/safe-resource-write.js";
@@ -52,7 +53,7 @@ export interface ClioSessionMeta {
 	endedAt: string | null;
 	model: string | null;
 	target: string | null;
-	clioVersion: string;
+	clioCoderVersion: string;
 	piMonoVersion: string;
 	platform: string;
 	nodeVersion: string;
@@ -181,7 +182,7 @@ function defaultSessionJsonlWarning(warning: SessionJsonlWarning): void {
 	if (reportedSessionJsonlWarnings.has(key)) return;
 	if (reportedSessionJsonlWarnings.size >= REPORTED_SESSION_JSONL_WARNING_LIMIT) reportedSessionJsonlWarnings.clear();
 	reportedSessionJsonlWarnings.add(key);
-	process.stderr.write(`[clio:session] ${warning.path}:${warning.line}: ${warning.message}\n`);
+	process.stderr.write(`[clio-coder:session] ${warning.path}:${warning.line}: ${warning.message}\n`);
 }
 
 function serializeJsonl(entries: ReadonlyArray<unknown>): string {
@@ -201,7 +202,7 @@ function serializeJsonl(entries: ReadonlyArray<unknown>): string {
  * A crash or interruption before the rename leaves the original target
  * untouched; when no target exists yet, recovery readers can promote the tmp.
  */
-export function writeJsonlFileAtomic(
+function writeJsonlFileAtomic(
 	targetPath: string,
 	entries: ReadonlyArray<unknown>,
 	options: SessionJsonlWriteOptions = {},
@@ -246,7 +247,7 @@ function parseSessionJsonlLine(
 ): void {
 	if (line.trim().length === 0) return;
 	try {
-		entries.push(JSON.parse(line) as unknown);
+		entries.push(normalizeClioCoderEventTree(JSON.parse(line) as unknown));
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		warn({ path: readPath, line: lineNumber, message: `invalid JSON skipped: ${message}` });
@@ -319,7 +320,7 @@ function readExactAt(fd: number, buffer: Buffer, position: number, length: numbe
  * Behaviour matches `readSessionFileEntries` line-for-line over the tail it
  * returns: same `parseSessionJsonlLine` (torn-tail tolerant), same warning sink.
  */
-export function readSessionFileTailEntries(
+function readSessionFileTailEntries(
 	path: string,
 	maxEntries: number,
 	options: SessionJsonlReadOptions & { chunkBytes?: number } = {},
@@ -461,7 +462,7 @@ function buildMeta(input: { cwd: string; model?: string | null; target?: string
 		endedAt: null,
 		model: input.model ?? null,
 		target: input.target ?? null,
-		clioVersion: readClioVersion(),
+		clioCoderVersion: readClioVersion(),
 		piMonoVersion: readPiMonoVersion(),
 		platform: process.platform,
 		nodeVersion: process.version,
@@ -471,7 +472,13 @@ function buildMeta(input: { cwd: string; model?: string | null; target?: string
 
 function readMetaFile(path: string): ClioSessionMeta {
 	const raw = readFileSync(path, "utf8");
-	return JSON.parse(raw) as ClioSessionMeta;
+	const parsed = JSON.parse(raw) as Record<string, unknown>;
+	const clioCoderVersion = parsed.clioCoderVersion ?? parsed.clioVersion;
+	if (typeof clioCoderVersion !== "string" || clioCoderVersion.length === 0) {
+		throw new Error(`session metadata has no Clio Coder version: ${path}`);
+	}
+	const { clioVersion: _legacyVersion, ...canonical } = parsed;
+	return { ...canonical, clioCoderVersion } as unknown as ClioSessionMeta;
 }
 
 const TURN_KINDS: readonly ClioTurnRecord["kind"][] = [

package/src/engine/tui-primitives.ts

@@ -0,0 +1,21 @@
+/**
+ * The terminal-engine primitives a non-interactive surface needs, kept in a
+ * module of its own rather than behind ./tui.js.
+ *
+ * ./tui.js is the interactive layer's barrel: it carries the instrumented
+ * renderer and SelectList, and every consumer of it also pulls the interactive
+ * theme. A CLI command that only measures text and paints an alternate screen
+ * needs none of that, and reaching it through the barrel is not free. An edge
+ * from outside src/interactive/ to ./tui.js, static or dynamic, gives that
+ * module a reachability set the theme modules do not share, so the bundler
+ * peels it into a chunk of its own. That chunk lands in the Stage 0 instant
+ * shell closure, which tests/contracts/instant-shell-import-graph.test.ts holds
+ * to six chunks. Everything re-exported here is a pass-through to the external
+ * terminal engine, which is not bundled and so adds no chunk at all.
+ *
+ * The engine-boundary rule (rule1 in tests/boundaries/check-boundaries.ts) keeps
+ * terminal-engine value imports inside src/engine/, which is why this seam lives
+ * here and not in src/cli/.
+ */
+
+export { ProcessTerminal, TuiAltScreen, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";

package/src/engine/tui.ts

@@ -18,6 +18,7 @@ export type {
 	MarkdownTheme,
 	OverlayHandle,
 	OverlayOptions,
+	OverlayUnfocusOptions,
 	ScrollViewScrollbar,
 	SelectItem,
 	SelectListLayoutOptions,