@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/cli/modes/print.ts

@@ -12,7 +12,7 @@ import {
 import { getTerminationCoordinator } from "../../core/termination.js";
 import { ToolNames } from "../../core/tool-names.js";
 import { createRunReceiptQuality } from "../../domains/dispatch/receipt-findings.js";
-import { openLedger } from "../../domains/dispatch/state.js";
+import { newRunId, openLedger } from "../../domains/dispatch/state.js";
 import type { RunKind, RunOutcome, RunReceiptDraft, RunStatus, ToolCallStat } from "../../domains/dispatch/types.js";
 import type { AgentMessage, ImageContent } from "../../engine/types.js";
 import type { ChatLoop, ChatLoopEvent } from "../../interactive/chat-loop.js";
@@ -58,6 +58,8 @@ export interface HeadlessMainAgentOptions {
 }
 
 interface HeadlessMainAgentResult {
+	/** Latest assistant stop, superseded by subsequent continuation messages. */
+	outputExhausted: boolean;
 	text: string;
 	error: string | null;
 	/**
@@ -154,6 +156,7 @@ function resultFromEvent(event: ChatLoopEvent, current: HeadlessMainAgentResult)
 	if (event.type !== "message_end") return current;
 	const message = event.message;
 	if (message?.role !== "assistant") return current;
+	current = { ...current, outputExhausted: message.stopReason === "length", sawTerminatingToolResult: false };
 	const error = assistantError(message);
 	if (error) return { ...current, text: "", error };
 	const text = assistantText(message).trimEnd();
@@ -180,8 +183,15 @@ function recordToolEnd(stats: HeadlessMainAgentReceiptStats, event: ChatLoopEven
 	stat.count += 1;
 	const durationMs = durationMsFromEvent(event);
 	if (durationMs !== undefined) stat.totalDurationMs += durationMs;
-	if (event.isError) stat.errors += 1;
-	else stat.ok += 1;
+	// Registry settlement is authoritative; legacy producers only expose isError.
+	const outcome = (event as { outcome?: unknown }).outcome;
+	if (outcome === "blocked") stat.blocked += 1;
+	else if (outcome === "error") stat.errors += 1;
+	else if (outcome === "ok") stat.ok += 1;
+	else if (outcome === undefined) {
+		if (event.isError) stat.errors += 1;
+		else stat.ok += 1;
+	}
 	stats.toolStats.set(tool, stat);
 	if (tool === ToolNames.Context) {
 		const rawTurnId = (event as { turnId?: unknown }).turnId;
@@ -267,6 +277,7 @@ interface HeadlessTerminalOutcome {
 }
 
 async function recordHeadlessMainAgentReceipt(input: {
+	runId: string;
 	chat: ChatLoop;
 	task: string;
 	startedAt: string;
@@ -289,6 +300,7 @@ async function recordHeadlessMainAgentReceipt(input: {
 	const outcomeDetail = input.terminal.failureMessage;
 	const ledger = openLedger();
 	const envelope = ledger.create({
+		id: input.runId,
 		agentId: "main-agent",
 		executionRole: "builder",
 		requestOrigin: "user",
@@ -394,10 +406,14 @@ function defaultShutdownHooks(): HeadlessShutdownHooks {
 }
 
 export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMainAgentOptions): Promise<number> {
+	// Children need the authoritative parent before submit can invoke dispatch.
+	// The terminal writer reuses this identity whichever settlement path wins.
+	const runId = newRunId();
 	const mode = options.mode ?? "text";
 	const jsonEvents = options.jsonEvents ?? "full";
 	const startedAt = new Date().toISOString();
 	let result: HeadlessMainAgentResult = {
+		outputExhausted: false,
 		text: "",
 		error: null,
 		sawTerminatingToolResult: false,
@@ -422,6 +438,7 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 		if (sealed !== null) return sealed;
 		const endedAt = new Date().toISOString();
 		sealed = recordHeadlessMainAgentReceipt({
+			runId,
 			chat,
 			task: options.prompt,
 			startedAt,
@@ -526,6 +543,7 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 	try {
 		if (mode === "json" && jsonEvents === "terminal") writeTerminalTurnStart();
 		const submitOptions = {
+			hostRun: { runId, lineage: { parentRunId: null, rootRunId: runId, depth: 0, attempt: 0 } },
 			...(options.images && options.images.length > 0 ? { images: options.images } : {}),
 			...(options.workingContextPaths && options.workingContextPaths.length > 0
 				? { workingContextPaths: options.workingContextPaths }
@@ -573,6 +591,15 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 	} else if (result.error) {
 		terminal = { exitCode: 1, outcome: "failed", status: "failed", failureMessage: result.error };
 		stderrMessage = prefixHeadlessFailure(chat, result.error);
+	} else if (result.outputExhausted && !result.sawTerminatingToolResult) {
+		// The provider returned normally, but generation exhausted its budget.
+		// Earlier chatter and partial prose cannot turn that terminal cause into
+		// success. A later assistant message or terminating tool supersedes it.
+		const failureMessage =
+			"clio-coder run: output token limit reached (stopReason=length); generation incomplete. Consider resuming with a narrower task, lower reasoning effort, or a larger output budget.";
+		terminal = { exitCode: 1, outcome: "failed", status: "failed", failureMessage };
+		stderrMessage = failureMessage;
+		if (mode === "text" && result.text.length > 0) stdoutMessage = result.text;
 	} else if (result.text.length === 0 && !result.sawTerminatingToolResult) {
 		const failureMessage =
 			result.lastNotice !== null
@@ -611,7 +638,8 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 
 	if (stderrMessage !== null) {
 		process.stderr.write(`${stderrMessage}\n`);
-	} else if (stdoutMessage !== null) {
+	}
+	if (stdoutMessage !== null) {
 		writeRawStdout(`${stdoutMessage}\n`);
 	}
 	await flushRawStdout();

package/src/cli/run.ts

@@ -2,6 +2,7 @@ import { type ClioSettings, readSettings } from "../core/config.js";
 import { loadDomains } from "../core/domain-loader.js";
 import { readFileArgsAsync } from "../core/file-references.js";
 import { withRunOverrides } from "../core/run-overrides.js";
+import { readStrictLayeredSettings } from "../core/settings-layers.js";
 import { clioDataDir } from "../core/xdg.js";
 import type { AgentsContract } from "../domains/agents/contract.js";
 import { AgentsDomainModule } from "../domains/agents/index.js";
@@ -101,15 +102,15 @@ function hasDispatchOnlyOptions(parsed: RunCliArgs): boolean {
 
 /**
  * True when an explicit --target override names a target that is not in
- * settings.targets. `readSettings().targets` is the same source the runtime
- * resolver checks (providers.getTarget), so this mirrors its `target-not-found`
+ * effective settings.targets. Include project overlays just as the runtime
+ * resolver does (providers.getTarget), so this mirrors its `target-not-found`
  * verdict without booting the providers domain. Unreadable/invalid settings
  * fall through (returns false) so the normal boot path surfaces that error
  * instead of a misleading "target not found".
  */
-function explicitTargetMissing(targetId: string): boolean {
+export function explicitTargetMissing(targetId: string): boolean {
 	try {
-		return !readSettings().targets.some((target) => target.id === targetId);
+		return !readStrictLayeredSettings(process.cwd()).settings.targets.some((target) => target.id === targetId);
 	} catch {
 		return false;
 	}
@@ -163,9 +164,9 @@ function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
 }
 
 /**
- * The TUI's verdict for a command-shaped token the registry does not own,
- * applied to a headless task. Returns the refusal message, or null when the
- * task is not an unknown command.
+ * Refuse commands the headless prompt path cannot execute. Skill invocations
+ * and prompt templates have production expansion paths; interactive commands
+ * do not, so accepting them would send their literal text to the model.
  *
  * `parseSlashCommand` is the canonical shape test and the canonical registry
  * walk, so a token that is one word of letters, digits, hyphens, or colons and
@@ -190,11 +191,14 @@ function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
  * closure sits on. Boundaries rule6 in `tests/boundaries/check-boundaries.ts`
  * holds both halves of that.
  */
-async function unknownSlashCommandRefusal(task: string): Promise<string | null> {
+async function headlessSlashCommandRefusal(task: string): Promise<string | null> {
 	if (!task.trim().startsWith("/")) return null;
 	const { parseSlashCommand } = await import("../interactive/slash-commands.js");
 	const command = parseSlashCommand(task);
-	if (command.kind !== "unknown-command") return null;
+	if (command.kind === "skill-invocation" || command.kind === "unknown" || command.kind === "empty") return null;
+	if (command.kind !== "unknown-command") {
+		return "interactive commands are not supported by clio-coder run; use interactive chat or the corresponding CLI command";
+	}
 	const { loadPromptTemplates } = await import("../domains/resources/index.js");
 	const templates = loadPromptTemplates({ cwd: process.cwd() });
 	if (templates.items.some((template) => template.name === command.token)) return null;
@@ -260,11 +264,9 @@ export async function runClioRun(
 			if (!assembled) return 2;
 
 			if (parsed.agentId === undefined) {
-				// A mistyped slash command is a usage error, not a task. Refusing it
-				// here keeps it from booting a session and spending a model turn on a
-				// command that was never run, which is what the TUI has always done
-				// and what docs/guide/extensions-and-sharing.md documents for both surfaces.
-				const slashRefusal = await unknownSlashCommandRefusal(assembled.prompt);
+				// Reject unknown and unsupported interactive commands before boot;
+				// neither has a headless handler that could honor the request.
+				const slashRefusal = await headlessSlashCommandRefusal(assembled.prompt);
 				if (slashRefusal !== null) {
 					process.stderr.write(`clio-coder run: ${slashRefusal}\n`);
 					return 2;

package/src/cli/skills-eval.ts

@@ -272,10 +272,10 @@ export async function runSkillsEvalCommand(nameOrPath: string, options: SkillsEv
 	return anyUnmeasured || evidenceErrors.length > 0 ? 3 : 0;
 }
 
-export type NetworkPolicyLabel = "hermetic" | "allowed";
+export type NetworkPolicyLabel = "retrieve-disabled" | "allowed";
 
 function networkPolicyLabel(allowNetwork: boolean): NetworkPolicyLabel {
-	return allowNetwork ? "allowed" : "hermetic";
+	return allowNetwork ? "allowed" : "retrieve-disabled";
 }
 
 /**
@@ -287,7 +287,7 @@ function networkPolicyLabel(allowNetwork: boolean): NetworkPolicyLabel {
 function describeArmPolicy(allowNetwork: boolean): string {
 	const network = allowNetwork
 		? "network allowed (--allow-network), so arm runs keep the web tools"
-		: "network hermetic, so the web tools are stripped from every arm run (pass --allow-network to keep them)";
+		: "retrieval tools disabled in every arm run; bash networking requires OS isolation (pass --allow-network to keep web tools)";
 	return `policy: autonomy ${ARM_AUTONOMY} for the baseline and treatment arms in per-run disposable workspaces; ${network}`;
 }
 
@@ -295,7 +295,7 @@ function describeArmPolicy(allowNetwork: boolean): string {
 function describeArmPolicyOutcome(allowNetwork: boolean): string {
 	const network = allowNetwork
 		? "network: allowed (--allow-network); arm runs kept the web tools"
-		: "network: hermetic; the web tools were stripped from every arm run";
+		: "retrieval: disabled; bash networking was not constrained";
 	return `policy: the baseline and treatment arms ran at autonomy ${ARM_AUTONOMY}; ${network}`;
 }
 
@@ -353,17 +353,19 @@ function unmeasuredBullets(scenario: SkillEvalScenario, reason: string): ScoredB
 
 /**
  * The environment each arm's child `clio-coder run` inherits. Absent
- * `--allow-network` the hermetic switch is set, which strips the RETRIEVE
+ * `--allow-network` the retrieval registration switch is set, which strips the RETRIEVE
  * plane from every registry the child and its descendants build. With the flag
  * the variable is removed rather than left alone, so an ambient setting in the
  * operator's shell cannot make `--allow-network` a claim the run does not keep.
  *
  * @internal Exported for contract tests.
  */
-function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+export function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
 	const childEnv: NodeJS.ProcessEnv = { ...env };
-	if (allowNetwork) Reflect.deleteProperty(childEnv, NO_NETWORK_TOOLS_ENV);
-	else childEnv[NO_NETWORK_TOOLS_ENV] = "1";
+	if (allowNetwork) {
+		Reflect.deleteProperty(childEnv, NO_NETWORK_TOOLS_ENV);
+		Reflect.deleteProperty(childEnv, "CLIO_CODER_NO_NETWORK_TOOLS");
+	} else childEnv[NO_NETWORK_TOOLS_ENV] = "1";
 	return childEnv;
 }
 

package/src/cli/steer-channel.ts

@@ -1,18 +1,44 @@
 import * as fs from "node:fs";
+import { Socket } from "node:net";
 import * as readline from "node:readline";
 
 export function setupSteerChannel(filePath: string, onLine: (line: string) => void): () => void {
 	let closed = false;
 	let watcher: fs.FSWatcher | null = null;
-	let stream: fs.ReadStream | null = null;
+	let stream: Socket | null = null;
 	let rl: readline.Interface | null = null;
+	const cleanup = () => {
+		if (closed) return;
+		closed = true;
+		watcher?.close();
+		rl?.close();
+		stream?.destroy();
+	};
+	const reportError = (err: unknown) => {
+		if (closed) return;
+		process.stderr.write(
+			`clio-coder run: failed to setup steer channel: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+		cleanup();
+	};
 
 	try {
 		const stats = fs.statSync(filePath);
 		if (stats.isFIFO()) {
-			// Named pipe: we can just read from the stream
-			stream = fs.createReadStream(filePath);
+			// A blocking fs read cannot be cancelled while a FIFO writer stays
+			// open. Socket uses readiness-driven pipe reads that destroy() closes.
+			// Keep read-only access and the existing first-writer-EOF behavior.
+			const fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+			try {
+				stream = new Socket({ fd, readable: true, writable: false });
+			} catch (err) {
+				// Ownership transfers to Socket only after successful construction.
+				fs.closeSync(fd);
+				throw err;
+			}
+			stream.on("error", reportError);
 			rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+			rl.on("error", reportError);
 			rl.on("line", (line) => {
 				if (closed) return;
 				const trimmed = line.trim();
@@ -66,21 +92,8 @@ export function setupSteerChannel(filePath: string, onLine: (line: string) => vo
 			});
 		}
 	} catch (err) {
-		process.stderr.write(
-			`clio-coder run: failed to setup steer channel: ${err instanceof Error ? err.message : String(err)}\n`,
-		);
+		reportError(err);
 	}
 
-	return () => {
-		closed = true;
-		if (watcher) {
-			watcher.close();
-		}
-		if (rl) {
-			rl.close();
-		}
-		if (stream) {
-			stream.destroy();
-		}
-	};
+	return cleanup;
 }

package/src/cli/targets.ts

@@ -5,6 +5,8 @@ import {
 	readSettings,
 	removeFleetProfileFromSettings,
 	setFleetProfileInSettings,
+	type TargetSelectionRole,
+	type UseTargetOptions,
 	updateSettings,
 	useTargetInSettings,
 } from "../core/config.js";
@@ -24,6 +26,7 @@ import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.
 import type { CapabilityFlags } from "../domains/providers/types/capability-flags.js";
 import type { RuntimeTier } from "../domains/providers/types/runtime-descriptor.js";
 import { runConfigureCommand, runTargetRemove, runTargetRename } from "./configure.js";
+import { resolveSupportedWireModels } from "./configure-target.js";
 import { printError, printOk } from "./shared.js";
 import { column, terminalColumns, truncate, wrapPlain } from "./text-layout.js";
 
@@ -259,7 +262,7 @@ function parseUseArgs(args: ReadonlyArray<string>): UseArgs | null {
 	return parsed;
 }
 
-function runUse(args: ReadonlyArray<string>): number {
+async function runUse(args: ReadonlyArray<string>): Promise<number> {
 	if (wantsHelp(args)) return printUsage(USE_USAGE);
 	let parsed: UseArgs | null;
 	try {
@@ -281,42 +284,91 @@ function runUse(args: ReadonlyArray<string>): number {
 	}
 	const registry = getRuntimeRegistry();
 	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
-	const runtime = registry.get(target.runtime);
-	if (!runtime) {
-		printError(
-			`cannot use target '${target.id}' as orchestrator target because runtime '${target.runtime}' is not registered`,
-		);
+	const options: UseTargetOptions = {
+		...(parsed.model !== undefined ? { model: parsed.model } : {}),
+		...(parsed.orchestratorModel !== undefined ? { orchestratorModel: parsed.orchestratorModel } : {}),
+		...(parsed.workerModel !== undefined ? { workerModel: parsed.workerModel } : {}),
+		...(parsed.workerTarget !== undefined ? { workerTargetId: parsed.workerTarget } : {}),
+		...(parsed.backgroundModel !== undefined ? { backgroundModel: parsed.backgroundModel } : {}),
+	};
+	const candidate = structuredClone(settings);
+	const selection = useTargetInSettings(candidate, target.id, options);
+	if (!selection) {
+		printError(`no target with id ${parsed.workerTarget}`);
 		return 1;
 	}
-	if (!isOrchestratorEligibleRuntime(runtime)) {
-		printError(
-			`cannot use target '${target.id}' as orchestrator target because runtime '${runtime.id}' is not an HTTP/native runtime`,
-		);
+	const labels: Record<TargetSelectionRole, string> = {
+		chat: "chat",
+		fleet: "fleet dispatch",
+		memory: "background memory",
+	};
+	const routes = { chat: candidate.chat, fleet: candidate.fleet.default, memory: candidate.context.memory };
+	const inventories = new Map<string, Awaited<ReturnType<typeof resolveSupportedWireModels>>>();
+	const checkedTargets = new Map<string, string>();
+	for (const role of selection.roles) {
+		const route = routes[role];
+		const selectedTarget = candidate.targets.find((entry) => entry.id === route.target);
+		if (!selectedTarget) throw new Error("selected target disappeared");
+		const runtime = registry.get(selectedTarget.runtime);
+		if (!runtime || !(role === "fleet" ? isDispatchEligibleRuntime(runtime) : isOrchestratorEligibleRuntime(runtime))) {
+			printError(
+				`cannot use target '${selectedTarget.id}' for ${labels[role]}: runtime '${selectedTarget.runtime}' is not eligible`,
+			);
+			return 1;
+		}
+		checkedTargets.set(selectedTarget.id, JSON.stringify(selectedTarget));
+		if (route.model === null) continue;
+		let inventory = inventories.get(selectedTarget.id);
+		if (!inventory) {
+			inventory = await resolveSupportedWireModels(runtime, selectedTarget, selectedTarget);
+			inventories.set(selectedTarget.id, inventory);
+		}
+		if (inventory.models.length > 0 && !inventory.models.includes(route.model)) {
+			printError(
+				`target '${selectedTarget.id}' does not list model '${route.model}' for ${labels[role]} (${inventory.source} inventory). Use an exact listed model id: ${inventory.models.slice(0, 10).join(", ")}`,
+			);
+			return 1;
+		}
+		if (inventory.models.length === 0) {
+			// Keep offline selection possible, but never imply that an unknown id was verified.
+			process.stderr.write(
+				`warning: could not verify model '${route.model}' for ${labels[role]}: target '${selectedTarget.id}' returned no model list; saving the id as written\n`,
+			);
+		} else if (inventory.source === "cache" || inventory.source === "legacy") {
+			process.stderr.write(
+				`warning: using ${inventory.source} model inventory for target '${selectedTarget.id}'; live availability was not verified\n`,
+			);
+		}
+	}
+	// Re-read under the settings lock. A changed endpoint/default invalidates the
+	// checked inventory; unrelated concurrent role edits are preserved by the scoped mutation.
+	let changedRoles: TargetSelectionRole[] = [];
+	try {
+		updateSettings((fresh) => {
+			for (const [id, descriptor] of checkedTargets) {
+				if (JSON.stringify(fresh.targets.find((entry) => entry.id === id)) !== descriptor) {
+					throw new Error(`target '${id}' changed while checking models; retry targets use`);
+				}
+			}
+			const applied = useTargetInSettings(fresh, target.id, options);
+			if (!applied) throw new Error("target changed while checking models; retry targets use");
+			changedRoles = applied.changedRoles;
+		});
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
 		return 1;
 	}
-	let workerTarget = target;
-	if (parsed.workerTarget !== undefined && parsed.workerTarget !== target.id) {
-		const resolved = resolveDispatchProfileTarget(settings, parsed.workerTarget, "fleet worker target");
-		if ("exitCode" in resolved) return resolved.exitCode;
-		workerTarget = resolved.target;
+	const changedByTarget = new Map<string, string[]>();
+	for (const role of changedRoles) {
+		const id = routes[role].target as string;
+		const names = changedByTarget.get(id) ?? [];
+		names.push(labels[role]);
+		changedByTarget.set(id, names);
 	}
-	const backgroundModel = parsed.backgroundModel;
-	// Locked read-modify-write so a concurrent session's field-level
-	// write-through (Shift+Tab, Alt+L, …) cannot be lost between our read
-	// above and this save.
-	updateSettings((fresh) => {
-		useTargetInSettings(fresh, target.id, {
-			...(parsed.model !== undefined ? { model: parsed.model } : {}),
-			...(parsed.orchestratorModel !== undefined ? { orchestratorModel: parsed.orchestratorModel } : {}),
-			...(parsed.workerModel !== undefined ? { workerModel: parsed.workerModel } : {}),
-			workerTargetId: workerTarget.id,
-			...(backgroundModel !== undefined ? { backgroundModel } : {}),
-		});
-	});
-	const dispatchWhere = workerTarget === target ? "" : ` and ${workerTarget.id} for fleet dispatch`;
-	const chatWhere = workerTarget === target ? "for chat and fleet dispatch" : "for chat";
 	printOk(
-		`using target ${target.id} ${chatWhere}${dispatchWhere}${backgroundModel === undefined ? "" : ", and background memory"}`,
+		changedRoles.length === 0
+			? "no role settings changed"
+			: `using ${[...changedByTarget].map(([id, names]) => `target ${id} for ${names.join(" and ")}`).join("; ")}`,
 	);
 	return 0;
 }

package/src/cli/tasks.ts

@@ -1,5 +1,6 @@
 import { normalizeIntentExpectedOutputs, normalizeIntentVerification } from "../domains/dispatch/intent.js";
 import type { UserTaskAcceptance } from "../domains/user-tasks/acceptance.js";
+import { formatUserTaskHandoff } from "../domains/user-tasks/handoff.js";
 import { createUserTasksStore } from "../domains/user-tasks/store.js";
 import { packageDeclaredCheck } from "../tools/verify/catalog.js";
 import { discoverDeclaredChecksAtRoot, discoverDeclaredProjectEntriesAtRoot } from "../tools/verify/scripts.js";
@@ -74,7 +75,15 @@ export function runTasksCommand(args: string[]): number {
 		} else if (action === "list" && rest.length === 0) {
 			console.log(JSON.stringify(store.snapshot(), null, 2));
 		} else if ((action === "hand" || action === "done" || action === "drop") && rest.length === 1) {
-			console.log(JSON.stringify(store[action](rest[0] ?? ""), null, 2));
+			const task = store[action](rest[0] ?? "");
+			console.log(JSON.stringify(task, null, 2));
+			if (action === "hand") {
+				console.error(
+					"CLI hand records the inbox state only; it does not start a session or submit the interactive /tasks hand turn. " +
+						"Pass this pickup prompt to clio-coder run in the same project:\n" +
+						formatUserTaskHandoff(task),
+				);
+			}
 		} else throw new Error(HELP);
 		return 0;
 	} catch (error) {

package/src/cli/upgrade.ts

@@ -21,11 +21,12 @@ Flags:
   --dry-run             print planned actions without changing anything
   --channel=<chan>      npm dist-tag to install (latest|beta|dev). npm installs only.
   --skip-migrations     skip migrations after the install step
+  --post-install        apply local checks after a package-manager update; skip reinstall
   --json                emit machine-readable JSON output
   --help, -h            show this message
 `;
 
-const SOURCE_UPGRADE_STEPS = ["git pull", "npm run install:local", "hash -r"] as const;
+const SOURCE_UPGRADE_STEPS = ["git pull", "pnpm run install:local", "hash -r"] as const;
 /** One wording for the source-update advice. Three paths print it; they used to disagree. */
 const SOURCE_UPGRADE_LEAD = "To update the checkout itself, run:";
 
@@ -85,7 +86,7 @@ function parseUpgradeArgs(argv: ReadonlyArray<string>): UpgradeOptions {
  * the installed version is the newest one.
  */
 type RegistryLookup =
-	| { asked: false; reason: "source checkout" | "network checks are disabled" }
+	| { asked: false; reason: "source checkout" | "network checks are disabled" | "post-install checks" }
 	| { asked: true; version: string | null };
 
 function testSeam(name: string): string | undefined {
@@ -186,11 +187,13 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	const before = getVersionInfo().clio;
 	const stateDir = clioStateDir();
 	const method = detectInstallMethod();
-	const methodLabel = method === "source" ? "source checkout" : "npm global";
+	const methodLabel = method === "source" ? "source checkout" : opts.postInstall ? "package install" : "npm global";
 	presenter.setMethod(methodLabel);
 
 	const noNetwork = Boolean(testSeam("CLIO_CODER_TEST_UPGRADE_NO_NETWORK"));
-	const lookup = await lookUpAvailableVersion(opts.channel, method, noNetwork);
+	const lookup: RegistryLookup = opts.postInstall
+		? { asked: false, reason: "post-install checks" }
+		: await lookUpAvailableVersion(opts.channel, method, noNetwork);
 	const availableVersion = lookup.asked ? lookup.version : null;
 
 	presenter.step(`Installation method: ${methodLabel}`);
@@ -201,7 +204,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	if (availableVersion !== null) presenter.step(`Available version: ${availableVersion}`);
 	else if (!lookup.asked) presenter.step(`Available version: not checked (${lookup.reason})`);
 	else presenter.step("Available version: unknown (the registry could not be reached)");
-	if (method === "npm") presenter.step(`Channel: ${opts.channel}`);
+	if (method === "npm" && !opts.postInstall) presenter.step(`Channel: ${opts.channel}`);
 	presenter.step(`State dir: ${shortenPath(stateDir)}`);
 
 	const migrations = listMigrations();
@@ -236,7 +239,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 
 	if (opts.dryRun) {
 		if (method === "source") presenter.commandAdvice(SOURCE_UPGRADE_LEAD, SOURCE_UPGRADE_STEPS.join("\n"));
-		else presenter.note(`Would run: npm install -g @iowarp/clio-coder@${opts.channel}`);
+		else if (!opts.postInstall) presenter.note(`Would run: npm install -g @iowarp/clio-coder@${opts.channel}`);
 		if (opts.skipMigrations) presenter.note("Would skip migrations (--skip-migrations).");
 		else if (pendingMigrationIds.length === 0) presenter.note("No pending migrations.");
 		else {

package/src/cli/usage.ts

@@ -354,6 +354,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	diagnostics.malformedAuditRows = auditRows.errors.length;
 	const auditInWindow = auditRows.rows.filter((row) => row.ts !== null && inWindow(row.ts, windowStart, now));
 	const auditToolCalls = auditInWindow.filter((row) => row.auditKind === "tool_call");
+	const permissions = summarizePermissionDecisions(
+		auditInWindow.filter((row) => row.auditKind === "permission").map((row) => row.row),
+	);
 	const auditBlocked = auditToolCalls.filter((row) => {
 		const decision = typeof row.row.decision === "string" ? row.row.decision : "";
 		return decision === "blocked" || decision === "denied";
@@ -564,6 +567,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		emit({ kind: "fact", fact: "unverified-successes", value: accountability.unverifiedSuccesses });
 		emit({ kind: "fact", fact: "ungrounded-claims", value: accountability.ungroundedClaims });
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
+		emit({ kind: "fact", fact: "permission-approval", ...permissions });
 		if (usageMeasurable) {
 			// The origin split is emitted only when something out of turn was
 			// recorded, so a report over an archive with no `/btw`, `/handoff`, or
@@ -656,6 +660,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	} else {
 		out(`  receipt store missing at ${presence.receiptsPath}`);
 	}
+	out(
+		`  permission decisions: ${permissions.requested} requested, ${permissions.granted} granted, ${permissions.denied} denied, ${permissions.expired} expired; approval rate ${permissions.approvalRate === null ? "n/a" : `${(permissions.approvalRate * 100).toFixed(1)}%`}`,
+	);
 	out(`  audited tool calls in window: ${auditToolCalls.length} (${auditBlocked.length} blocked/denied)`);
 	if (usageMeasurable) {
 		out(
@@ -1128,3 +1135,20 @@ function numberOr0(value: unknown): number {
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+
+/** Event-window approval rate. Resolutions can belong to requests outside the window. */
+export function summarizePermissionDecisions(rows: ReadonlyArray<Record<string, unknown>>): {
+	requested: number;
+	granted: number;
+	denied: number;
+	expired: number;
+	approvalRate: number | null;
+} {
+	const counts = { requested: 0, granted: 0, denied: 0, expired: 0 };
+	for (const row of rows) {
+		const status = row.status;
+		if (status === "requested" || status === "granted" || status === "denied" || status === "expired")
+			counts[status] += 1;
+	}
+	return { ...counts, approvalRate: counts.requested === 0 ? null : counts.granted / counts.requested };
+}