@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/entry/orchestrator.ts

@@ -9,6 +9,7 @@ import { BusChannels } from "../core/bus-events.js";
 import { installBusTracer } from "../core/bus-trace.js";
 import { type ClioSettings, readSettings, type SettingsMutator, updateSettings } from "../core/config.js";
 import { DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS } from "../core/defaults.js";
+import { writeDiagnostic } from "../core/diagnostics.js";
 import { loadDomains } from "../core/domain-loader.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import { expandInlineFileReferencesAsync } from "../core/file-references.js";
@@ -82,6 +83,7 @@ import {
 } from "../domains/memory/index.js";
 import { TaskMemoryBank } from "../domains/memory/task-bank.js";
 import { TaskMemoryEndpointBusyError } from "../domains/memory/task-memory-policy.js";
+import { createDemoGuidanceRegistration } from "../domains/middleware/demo-guidance.js";
 import {
 	createDetachedDispatchNudgeRegistration,
 	createReadOnlyExplorationNudgeRegistration,
@@ -108,7 +110,7 @@ import type { BackgroundMemoryUsageSink } from "../domains/observability/backgro
 import { recordFailedCompactionCalls } from "../domains/observability/compaction-usage.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import { ObservabilityDomainModule } from "../domains/observability/index.js";
-import { PluginsDomainModule } from "../domains/plugins/index.js";
+import { PluginsDomainModule, pluginSnapshotFor } from "../domains/plugins/index.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
 import { createPromptsDomainModule } from "../domains/prompts/index.js";
 import type { ProvidersContract, TargetDescriptor, ThinkingLevel } from "../domains/providers/index.js";
@@ -139,6 +141,7 @@ import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.
 import {
 	createResourcesDomainModule,
 	discoverMarketplaceSkills,
+	installedSkillNames,
 	installSkill,
 	modelVisibleSkills,
 	type ResourcesContract,
@@ -180,12 +183,19 @@ import { createTaskBoardStore } from "../domains/session/task-board.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import { type ShareContract, ShareDomainModule } from "../domains/share/index.js";
 import { ToolchainDomainModule } from "../domains/toolchain/index.js";
+import type { UserTaskAcceptance } from "../domains/user-tasks/acceptance.js";
 import { activeUserTaskAcceptance } from "../domains/user-tasks/active-acceptance.js";
 import { createUserTasksStore } from "../domains/user-tasks/store.js";
+import { acpCommandControl } from "../engine/acp/commands.js";
 import { type AcpSafeSettingsPatch, type AcpSafeSettingsSnapshot, serveClioAcpAgent } from "../engine/acp/server.js";
 import { createStdioServerTransport } from "../engine/acp/transport.js";
 import { completeEngineText, type EngineTextCompletionResult } from "../engine/ai.js";
-import { setProtectedModelsProvider } from "../engine/apis/residency.js";
+import {
+	declareRuntimeNoticeProducer,
+	EXIT_RELEASE_MS,
+	releaseClioLoadedModelsOnExit,
+	setProtectedModelsProvider,
+} from "../engine/apis/residency.js";
 import {
 	createLoopGuardRegistration,
 	INTERACTIVE_LOOP_BLOCK_BUDGET,
@@ -194,7 +204,7 @@ import {
 import { cwdHash, openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
 import type { EngineModel } from "../engine/types.js";
 import { createChatLoop } from "../interactive/chat-loop.js";
-import { type RunIo, startInteractive } from "../interactive/index.js";
+import type { RunIo } from "../interactive/index.js";
 import { buildModelReplayAgentMessagesFromTurns } from "../interactive/model-session-replay.js";
 import { prepareBackgroundModelMetadata } from "./background-model-metadata.js";
 import type { BootOptions } from "./boot-options.js";
@@ -225,6 +235,8 @@ import { dispatchSchemaCompositionFor } from "../tools/dispatch-schema.js";
 import { createFileMutationObserver, createSkillActivationObserver } from "../tools/observers.js";
 import { createRegistry } from "../tools/registry.js";
 import { sweepExpiredToolOffloads } from "../tools/result-shaping.js";
+import { gitCheckoutRoot, recoverTaskWorktrees } from "../tools/task-worktree.js";
+import { allowedWorktreeParents } from "../tools/worktree-root.js";
 
 export interface BootResult {
 	exitCode: number;
@@ -527,6 +539,8 @@ function prepareBackgroundMemoryRoute(
 	};
 }
 
+const emitRouteFallbackNotice = declareRuntimeNoticeProducer("background-memory-route", ["route-fallback"]);
+
 /** Production callback composition shared with routing/capacity contracts. */
 export function createBackgroundMemoryRouting(
 	providers: ProvidersContract,
@@ -544,18 +558,18 @@ export function createBackgroundMemoryRouting(
 		const message = `Memory: ${route.fallbackReason}; selected chat fallback ${route.targetId}/${route.wireModelId} for this step, subject to available endpoint capacity.`;
 		if (message === lastNotice) return;
 		lastNotice = message;
-		try {
-			bus?.emit(BusChannels.RuntimeNotice, {
-				kind: "degraded",
+		if (!bus) return;
+		emitRouteFallbackNotice(
+			{
+				kind: "route-fallback",
 				level: "info",
 				message,
 				targetId: route.targetId,
 				runtimeId: providers.getTarget(route.targetId)?.runtime ?? "unknown",
 				model: route.wireModelId,
-			});
-		} catch {
-			/* Advisory only. */
-		}
+			},
+			bus,
+		);
 	};
 	return {
 		getModelClient: (): TaskMemoryModelClient | null => {
@@ -1132,6 +1146,27 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		} catch (err) {
 			bootStderr(`[dispatch] compete recovery failed closed: ${err instanceof Error ? err.message : String(err)}\n`);
 		}
+		// Task worktrees (`worktree: true`) get the same restart sweep: a dead
+		// owner's empty worktree goes, one holding work stays and is named once.
+		try {
+			// Dispatch creates them under the checkout root, which a session started
+			// in a subdirectory is not.
+			const checkout = gitCheckoutRoot(process.cwd()) ?? process.cwd();
+			// A configured absolute root is only known from settings; the disk and
+			// tmpfs locations are recognized whatever the settings say.
+			const worktreeRootSetting = options.startupSettings?.fleet.worktrees.root ?? startupWorktreeRootSetting();
+			const recovery = recoverTaskWorktrees(checkout, allowedWorktreeParents(worktreeRootSetting, checkout));
+			for (const kept of recovery.preserved) {
+				bootStderr(
+					`[dispatch] task worktree recovery preserved ${kept.runId}: ${kept.reason} on ${kept.branch}; inspect with git log ${kept.base}..${kept.branch}\n`,
+				);
+			}
+			for (const failure of recovery.failed) {
+				bootStderr(`[dispatch] task worktree recovery preserved ${failure.runId}: ${failure.message}\n`);
+			}
+		} catch (err) {
+			bootStderr(`[dispatch] task worktree recovery failed closed: ${err instanceof Error ? err.message : String(err)}\n`);
+		}
 	}
 
 	let effectiveSettingsForDispatch: (() => Readonly<ClioSettings>) | null = null;
@@ -1174,6 +1209,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			SafetyDomainModule,
 			createPromptsDomainModule({
 				noContextFiles: options.noContextFiles === true,
+				noSkills: options.noSkills === true || options.headless?.noSkills === true,
 			}),
 			AgentsDomainModule,
 			MiddlewareDomainModule,
@@ -1269,19 +1305,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	const mux = result.getContract<MuxContract>("mux");
 	const contextDomain = result.getContract<ContextContract>("context");
 	const interop = result.getContract<InteropContract>("interop");
-	// Boot detection resolves paths only: no `--version` subprocess and no skill
-	// walk on the boot path. The hint is gated on `interactive`, which is already
-	// false under headless and ACP.
-	const interopReport = interactive && interop ? await interop.detect({ cwd: process.cwd() }) : null;
 	const initialNotices = interactive ? [...(contextDomain?.startupHints() ?? [])] : [];
 	// Once per version, interactive only: headless and ACP have no operator at
 	// the keyboard to tell, and the record is left unclaimed for the boot that does.
 	const upgrade = interactive ? takeUpgradeNotice() : null;
 	if (upgrade !== null) initialNotices.push(describeUpgradeNotice(upgrade));
-	if (interop && interopReport) {
-		const interopHint = interop.bootHint(interopReport);
-		if (interopHint !== null) initialNotices.push(interopHint);
-	}
 	if (!providers || !dispatch || !observability || !safety || !middleware) {
 		bootStderr(
 			"Clio Coder: chat mode requires safety + middleware + providers + dispatch + observability contracts; aborting.\n",
@@ -1493,11 +1521,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		})
 			.then((result) => {
 				for (const error of result.errors) {
-					process.stderr.write(`[clio-coder:memory] proposed record not written for ${error}\n`);
+					writeDiagnostic(`[clio-coder:memory] proposed record not written for ${error}\n`);
 				}
 			})
 			.catch((error: unknown) => {
-				process.stderr.write(
+				writeDiagnostic(
 					`[clio-coder:memory] proposed records not written: ${error instanceof Error ? error.message : String(error)}\n`,
 				);
 			});
@@ -1584,19 +1612,42 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		(config?.get() ?? readSettings()).safety.autonomy ??
 		"auto-edit";
 	const resolveEffectiveAutonomy = (): AutonomyLevel => activeAcpSessionAutonomy ?? resolveBaselineAutonomy();
+	const skillDiscoveryEnabled = options.noSkills !== true && options.headless?.noSkills !== true;
+	let readySkillSnapshot: { key: string; count: number } | undefined;
+	const getReadySkillCount = (): number => {
+		if (!resources) return 0;
+		const cwd = process.cwd();
+		// Skill loading reads and hashes the filesystem. Reuse the count across
+		// warm/real requests and reminders until the same source epoch that
+		// invalidates prompt composition changes (/library reload, config, etc.).
+		if (!prompts) return modelVisibleSkills(resources.skills(cwd).items).length;
+		const key = JSON.stringify([
+			cwd,
+			prompts.inputEpoch(),
+			skillDiscoveryEnabled,
+			config?.get().integrations.projectResources.trustProjectImports === true,
+			options.skillPaths ?? options.headless?.skillPaths ?? [],
+		]);
+		if (readySkillSnapshot?.key === key) return readySkillSnapshot.count;
+		const count = modelVisibleSkills(resources.skills(cwd).items).length;
+		readySkillSnapshot = { key, count };
+		return count;
+	};
 	// First-turn skills reminder: user-message-visible text is the one channel
 	// the battery-tested local models act on. Which protocol it teaches follows
 	// the effective autonomy level, resolved one line up: suggest-and-wait at
 	// read-only and suggest, load-it-yourself at auto-edit and full-auto.
-	if (resources) {
+	if (resources && skillDiscoveryEnabled) {
 		middleware.registerHook(
 			createSkillsReminderRegistration({
-				countModelVisibleSkills: () => modelVisibleSkills(resources.skills(process.cwd()).items).length,
+				getTurnConstraints: () => chat.currentTurnConstraints?.(),
+				countModelVisibleSkills: getReadySkillCount,
 				// Same lookup context(scope="skills") lists under its Marketplace
 				// heading, minus what is already installed, so the count the
 				// reminder quotes is the count the listing will show.
 				countInstallableSkills: () => {
-					const installed = new Set(resources.skills(process.cwd()).items.map((skill) => skill.name));
+					if (!skillDiscoveryEnabled) return 0;
+					const installed = installedSkillNames(resources.skills(process.cwd()).items, process.cwd());
 					return discoverMarketplaceSkills({ cwd: process.cwd() }).skills.filter((skill) => !installed.has(skill.name))
 						.length;
 				},
@@ -1607,11 +1658,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// Marketplace self-promotion: coordinator-only by this wiring (never a
 	// dispatch worker), local matcher and operator-consented installs at every autonomy level. The
 	// registration also checks the own-marketplace source gate before installing.
-	if (resources) {
+	if (resources && skillDiscoveryEnabled) {
 		middleware.registerHook(
 			createMarketplaceOfferRegistration({
 				interactive,
-				listInstalledSkillNames: () => resources.skills(process.cwd()).items.map((skill) => skill.name),
+				listInstalledSkillNames: () => [...installedSkillNames(resources.skills(process.cwd()).items, process.cwd())],
 				listMarketplaceEntries: () => discoverMarketplaceSkills({ cwd: process.cwd() }).skills,
 				installEntry: (entry, scope) => {
 					const installed = installSkill({ source: `skill:${entry.name}`, scope, name: entry.name, cwd: process.cwd() });
@@ -1738,7 +1789,8 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					getCwd: () => process.cwd(),
 				})
 			: null;
-	registerAllTools(toolRegistry, {
+	const toolBootstrap = registerAllTools(toolRegistry, {
+		getSettings: () => getCurrentSettings(),
 		termination,
 		captureWorkerContext: () => chat.captureWorkerContext?.() ?? null,
 		...(session
@@ -1807,6 +1859,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	const sessionOverrides: SessionOverrides = new Map(
 		startupAutonomy === undefined ? [] : [["safety.autonomy", startupAutonomy]],
 	);
+	if (options.demo !== undefined) sessionOverrides.set("interface.demo", options.demo);
 	// The effective view is derived by deep-cloning the saved snapshot, and it
 	// is read on the tool-admission hot path (every call resolves autonomy
 	// through it). Memoize on the two things it depends on: the config
@@ -2081,6 +2134,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	if (session) {
 		middleware.registerHook(
 			createFinishContractRegistration({
+				getTurnConstraints: () => chat.currentTurnConstraints?.(),
 				// Tail-scoped: the contract only needs the last-user-message window, so
 				// it parses a bounded ledger tail per turn_end rather than the whole
 				// file (which grows unbounded with session length).
@@ -2097,7 +2151,12 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		);
 	}
 
+	if (!options.headless && !options.acp) {
+		middleware.registerHook(createDemoGuidanceRegistration(() => getCurrentSettings().interface.demo));
+	}
 	const chat = createChatLoop({
+		getReadySkillCount,
+		interactiveGuidance: !options.headless && !options.acp,
 		// The pre-warm holds one slot on its endpoint while it runs, so dispatch
 		// admission (#250) sees it exactly as it sees the orchestrator's own turn.
 		registerPrewarmEndpointSlot: (runtime) => {
@@ -2168,6 +2227,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		// never submits at all, so neither has latency to buy; the ACP surface has
 		// an operator on the other end of the client and keeps it.
 		isLatencySurface: () => interactive || acpMode,
+		isPrewarmBusy: () => Boolean(options.terminalLease?.editor.getText().trim()),
 	});
 
 	// Coordinated shutdown (SIGINT/SIGTERM, TUI quit) must abort any in-flight
@@ -2184,6 +2244,13 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		// impossible by ordering.
 		await chat.whenSettled();
 	});
+	// Every Ollama chat pins its model with keep_alive -1, and the ownership
+	// record dies with this process, so release the models this process loaded
+	// once the drain above has stopped the turn that could pin them again
+	// (#379). Terminate runs on every coordinated exit: a finished or failed
+	// headless run, --timeout, SIGINT, SIGTERM, and interactive quit. The
+	// release bounds itself, so an unreachable server never stalls the exit.
+	termination.onTerminate(() => releaseClioLoadedModelsOnExit(), { timeoutMs: EXIT_RELEASE_MS + 500 });
 
 	// A boot-time resume (headless --session or --continue) must replay the resumed
 	// session into the chat loop the same way the interactive /resume overlay
@@ -2270,10 +2337,86 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 						}
 					: {}),
 				providers,
+				// The fleet controls `clio-coder/dispatch/steer` reaches. The server
+				// takes the two operations by structure, never the whole contract, so
+				// no ACP client can enqueue or route dispatch work through it.
+				dispatch: {
+					steer: (runId, text) => {
+						dispatch.steer(runId, text);
+					},
+					abort: (runId) => {
+						dispatch.abort(runId);
+					},
+					snapshot: () => dispatch.snapshot(),
+				},
 				settings: {
 					read: readAcpSafeSettings,
 					commit: commitAcpSafeSettings,
 				},
+				// The operator-command host. Only the members the thirteen
+				// allowlisted commands actually reach are passed; every TUI-only
+				// member stays absent, which is what makes the registry take its
+				// documented non-TUI fallback instead of trying to draw an overlay.
+				//
+				// A command that submits a user turn (`/share`, `/oracle`,
+				// `/skill <name>`, `/tasks hand`) is refused by the server while a
+				// prompt is active. Outside one, the turn is persisted to the ledger
+				// and replayed on the next `session/load`, but it emits no live
+				// `session/update`: ACP v1 has no channel for agent content outside a
+				// prompt, the same constraint recorded above for routing notices.
+				...(dispatch && providers
+					? {
+							commands: acpCommandControl({
+								dispatch,
+								bus,
+								providers,
+								cwd: process.cwd(),
+								runDoctor: async ({ deep }) => {
+									const { collectDoctorFindings, doctorNotice } = await import("../cli/doctor.js");
+									return doctorNotice(
+										await collectDoctorFindings({
+											workspaceRoot: process.cwd(),
+											deep: deep ? { providers, autonomy: resolveBaselineAutonomy() } : false,
+										}),
+									);
+								},
+								clearSkillSurface: () => chat.clearSkillSurface(),
+								// Narrowed exactly as `interactive-slash-runtime.ts` narrows it:
+								// the store's `note` parameter has no command-line spelling, and
+								// a handoff is attributed to the session that asked for it.
+								userTasks: {
+									add: (title: string, acceptance?: UserTaskAcceptance) => userTasks.add(title, undefined, acceptance),
+									hand: (id: string) => userTasks.hand(id, chat.getSessionId() ?? undefined),
+									done: (id: string) => userTasks.done(id),
+									drop: (id: string) => userTasks.drop(id),
+								},
+								getDecisionBoard: () => decisionBoard.snapshot(),
+								isTurnInFlight: () => chat.isStreaming(),
+								seedTaskMemory: seedCurrentTaskMemoryFromHandoff,
+								...(agents ? { getAgentRoleFacts: agentRoleFactsResolver((id: string) => agents.getSpec(id)) } : {}),
+								...(config ? { getWorkerRosters: () => config.get().fleet.rosters } : {}),
+								...(resources
+									? {
+											parsePendingSkillRequests: (text: string, commandCwd?: string) =>
+												resources.parsePendingSkillRequests(text, commandCwd ?? process.cwd()),
+										}
+									: {}),
+								submitTurn: (text, submitOptions) => {
+									void chat
+										.submit(
+											text,
+											submitOptions.pendingSkillRequests === undefined
+												? {}
+												: { pendingSkillRequests: [...submitOptions.pendingSkillRequests] },
+										)
+										.catch(() => undefined);
+								},
+								submitOperatorNote: (text) => {
+									void chat.submit(text).catch(() => undefined);
+								},
+							}),
+						}
+					: {}),
 				toolRegistry,
 				bus,
 				autonomy: resolveBaselineAutonomy,
@@ -2308,6 +2451,12 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			await chat.whenSettled();
 			chat.dispose();
 			await dispatch.drain();
+			// A client that closes the session ends ACP here, outside the
+			// termination coordinator, so its terminate hook never runs. Release
+			// the Ollama models this process and its workers loaded on this path
+			// too (#379); SIGINT and SIGTERM still reach the hook. The release
+			// bounds itself by EXIT_RELEASE_MS and never throws.
+			await releaseClioLoadedModelsOnExit();
 			await result.stop();
 			return { exitCode: code, bootTimeMs: timer.snapshot().totalMs };
 		} finally {
@@ -2372,6 +2521,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			const workingContextPaths = [...(options.headless.workingContextPaths ?? []), ...fileExpansion.referencedPaths];
 			const code = await runHeadlessMainAgent(chat, {
 				prompt: fileExpansion.text,
+				...(options.headless.constraints ? { constraints: options.headless.constraints } : {}),
 				...(images.length > 0 ? { images } : {}),
 				...(workingContextPaths.length > 0 ? { workingContextPaths } : {}),
 				...(options.headless.sampling ? { sampling: options.headless.sampling } : {}),
@@ -2381,6 +2531,8 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				mode: options.headless.mode ?? "text",
 				...(options.headless.jsonEvents ? { jsonEvents: options.headless.jsonEvents } : {}),
 				...(options.headless.steerChannel ? { steerChannel: options.headless.steerChannel } : {}),
+				...(options.headless.failOnNoop === true ? { failOnNoop: true } : {}),
+				...(options.headless.deadline !== undefined ? { deadline: options.headless.deadline } : {}),
 				getSessionHeader: () => printJsonSessionHeader(session?.current() ?? null),
 			});
 			await termination.shutdown(code);
@@ -2398,7 +2550,21 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		}
 	}
 
+	const activePluginIds = () =>
+		pluginSnapshotFor(process.cwd())
+			.packages.filter((p) => p.loadable && (p.kind === undefined || p.kind === "plugin"))
+			.map((p) => p.id);
+	let dashboardPlugins = activePluginIds();
+	const unsubscribeDashboardPlugins = bus.on(BusChannels.PluginsReloaded, () => {
+		dashboardPlugins = activePluginIds();
+	});
+	termination.onTerminate(() => unsubscribeDashboardPlugins());
+	const { startInteractive } = await import("../interactive/index.js");
 	await startInteractive({
+		getConnections: () => ({
+			mcp: toolBootstrap.mcpCapabilities?.connectedIds({ readyOnly: true }) ?? [],
+			plugins: dashboardPlugins,
+		}),
 		bus,
 		providers,
 		dispatch,
@@ -2472,6 +2638,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		},
 		getSettings: getCurrentSettings,
 		getFleetNodes: () => result.getContract<SchedulingContract>("scheduling")?.fleet?.list() ?? [],
+		getRouteBreakers: () => result.getContract<DispatchContract>("dispatch")?.routeBreakers?.() ?? [],
 		onBackgroundDispatch: () => dispatchBackground.backgroundNewest(),
 		// A boot-time resume opens onto an existing conversation, so the welcome
 		// header starts collapsed rather than offering fresh-start onboarding.
@@ -2500,6 +2667,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 						const bootstrapOptions = bootstrapInputFromInitOptions(options);
 						await contextDomain.runBootstrap({
 							cwd: process.cwd(),
+							...(runIo ? { io: runIo } : {}),
 							confirmGitignore: () => true,
 							adopt: options.adopt === true,
 							...bootstrapOptions,
@@ -2527,25 +2695,19 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 								: {}),
 						});
 					},
-					onContextClear: async (options: { all?: boolean; confirmed?: boolean; confirmedAll?: boolean }) => {
+					onContextClear: async (options: { all?: boolean; confirmed?: boolean; confirmedAll?: boolean }, runIo?: RunIo) => {
 						await contextDomain.runContextClear({
 							cwd: process.cwd(),
 							all: options.all === true,
-							io: {
-								stdout: (s) => process.stdout.write(s),
-								stderr: (s) => process.stderr.write(s),
-							},
+							...(runIo ? { io: runIo } : {}),
 							confirmContext: () => options.confirmed === true,
 							confirmAll: () => options.confirmedAll === true,
 						});
 					},
-					onContextRefresh: async () => {
+					onContextRefresh: async (runIo?: RunIo) => {
 						await contextDomain.runContextRefresh({
 							cwd: process.cwd(),
-							io: {
-								stdout: (s) => process.stdout.write(s),
-								stderr: (s) => process.stderr.write(s),
-							},
+							...(runIo ? { io: runIo } : {}),
 						});
 					},
 				}
@@ -2639,3 +2801,12 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	});
 	return { exitCode: 0, bootTimeMs: timer.snapshot().totalMs };
 }
+
+/** The configured task worktree root, or the default when settings cannot be read this early in boot. */
+function startupWorktreeRootSetting(): string {
+	try {
+		return readSettings().fleet.worktrees.root;
+	} catch {
+		return "disk";
+	}
+}

package/src/interactive/assistant-generation-timing.ts

@@ -0,0 +1,52 @@
+type TimingEvent = {
+	type: string;
+	message?: { role?: string };
+	assistantMessageEvent?: unknown;
+};
+
+export function hasAssistantGenerationDelta(update: unknown): boolean {
+	if (typeof update !== "object" || update === null) return false;
+	const event = update as { type?: unknown; delta?: unknown };
+	return (
+		event.type === "toolcall_start" ||
+		((event.type === "text_delta" || event.type === "thinking_delta" || event.type === "toolcall_delta") &&
+			typeof event.delta === "string" &&
+			event.delta.length > 0)
+	);
+}
+
+/** Monotonic generation spans; tool waits and each call's prefill stay outside Tk/s. */
+export function createAssistantGenerationTiming() {
+	let startedAt: number | null = null;
+	let firstDeltaAt: number | null = null;
+	let activeSince: number | null = null;
+	let settledMs = 0;
+	const settle = (at: number): void => {
+		if (activeSince !== null) settledMs += Math.max(0, at - activeSince);
+		activeSince = null;
+	};
+	return {
+		record(event: TimingEvent, at: number): void {
+			if (event.type === "agent_start") {
+				startedAt = at;
+				firstDeltaAt = null;
+				activeSince = null;
+				settledMs = 0;
+			} else if (startedAt !== null) {
+				if (event.type === "message_update" && hasAssistantGenerationDelta(event.assistantMessageEvent)) {
+					firstDeltaAt ??= at;
+					activeSince ??= at;
+				} else if ((event.type === "message_end" && event.message?.role === "assistant") || event.type === "agent_end") {
+					settle(at);
+				}
+			}
+		},
+		snapshot(at: number): { durationMs: number; ttftMs: number } | null {
+			if (startedAt === null || firstDeltaAt === null) return null;
+			return {
+				durationMs: Math.max(1, settledMs + (activeSince === null ? 0 : Math.max(0, at - activeSince))),
+				ttftMs: Math.max(0, firstDeltaAt - startedAt),
+			};
+		},
+	};
+}

package/src/interactive/chat-loop-messages.ts

@@ -466,18 +466,21 @@ function classifyCacheUsage(input: number, cacheRead: number): BackendCacheVerdi
  * persisted value rather than reclassifying:
  *   hot      cacheRead > 0  and input < 2000   (prefix reused, prefill ≈ user text)
  *   partial  cacheRead > 0  and input >= 2000  (prefix reused up to a divergence point)
- *   cold     cacheRead == 0 and input >= 2000  (full re-prefill)
+ *   cold     reported cacheRead == 0 and input >= 2000
+ *   unknown  no cache-read count was supplied on the wire
  *   small    cacheRead == 0 and input < 2000   (too small to judge)
  */
 export function backendCacheVerdict(
 	input: number,
 	cacheRead: number,
 	backend?: BackendCompletionTimings | null,
+	cacheReadReported?: boolean,
 ): BackendCacheVerdict {
 	if (cacheRead === 0 && backend?.cachedTokens !== null && backend?.cachedTokens !== undefined) {
 		const backendInput = uncachedPrefillTokens(backend);
 		if (backendInput !== null) return classifyCacheUsage(backendInput, backend.cachedTokens);
 	}
+	if (cacheRead === 0 && cacheReadReported === false) return "unknown";
 	return classifyCacheUsage(input, cacheRead);
 }