@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/domains/share/archive.ts

@@ -11,9 +11,16 @@ import {
 	safeResourceWrite,
 } from "../../core/safe-resource-write.js";
 import { clioConfigDir, resolveClioDirs } from "../../core/xdg.js";
+import { parseFrontmatter } from "../agents/frontmatter.js";
+import {
+	assertAgentSpecPolicy,
+	normalizeAgentSpec,
+	parseAgentRecipeSchema,
+	parseFleetContract,
+} from "../agents/index.js";
 
 export type ShareScope = "project" | "user";
-export type ShareEntryType = "project-context" | "prompt" | "skill" | "settings" | "extension";
+export type ShareEntryType = "project-context" | "prompt" | "skill" | "agent" | "fleet" | "settings" | "extension";
 
 export interface ShareArchiveFile {
 	type: ShareEntryType;
@@ -61,6 +68,8 @@ export interface ShareExportOptions {
 	includeContext?: boolean;
 	includePrompts?: boolean;
 	includeSkills?: boolean;
+	includeAgents?: boolean;
+	includeFleets?: boolean;
 	includeSettings?: boolean;
 	includeExtensions?: boolean;
 }
@@ -206,7 +215,13 @@ function defaultedIncludes(
 ): Required<
 	Pick<
 		ShareExportOptions,
-		"includeContext" | "includePrompts" | "includeSkills" | "includeSettings" | "includeExtensions"
+		| "includeContext"
+		| "includePrompts"
+		| "includeSkills"
+		| "includeAgents"
+		| "includeFleets"
+		| "includeSettings"
+		| "includeExtensions"
 	>
 > {
 	// True when the caller named at least one include flag explicitly. In that
@@ -216,12 +231,16 @@ function defaultedIncludes(
 		options.includeContext !== undefined ||
 		options.includePrompts !== undefined ||
 		options.includeSkills !== undefined ||
+		options.includeAgents !== undefined ||
+		options.includeFleets !== undefined ||
 		options.includeSettings !== undefined ||
 		options.includeExtensions !== undefined;
 	return {
 		includeContext: hasExplicitInclude ? options.includeContext === true : true,
 		includePrompts: hasExplicitInclude ? options.includePrompts === true : true,
 		includeSkills: hasExplicitInclude ? options.includeSkills === true : true,
+		includeAgents: hasExplicitInclude ? options.includeAgents === true : true,
+		includeFleets: hasExplicitInclude ? options.includeFleets === true : true,
 		includeSettings: hasExplicitInclude ? options.includeSettings === true : true,
 		includeExtensions: hasExplicitInclude ? options.includeExtensions === true : true,
 	};
@@ -263,6 +282,18 @@ export function createShareArchive(options: ShareExportOptions = {}): ClioShareA
 			addTree(files, "skill", scope, root, `${scope}/skills`);
 		}
 	}
+	if (includes.includeAgents) {
+		for (const scope of scopes) {
+			const root = scope === "user" ? path.join(clioConfigDir(), "agents") : path.join(cwd, ".clio-coder", "agents");
+			addTree(files, "agent", scope, root, `${scope}/agents`);
+		}
+	}
+	if (includes.includeFleets) {
+		for (const scope of scopes) {
+			const root = scope === "user" ? path.join(clioConfigDir(), "fleets") : path.join(cwd, ".clio-coder", "fleets");
+			addTree(files, "fleet", scope, root, `${scope}/fleets`);
+		}
+	}
 	if (includes.includeExtensions) {
 		for (const scope of scopes) {
 			const root =
@@ -313,9 +344,19 @@ function parseArchive(raw: unknown): ClioShareArchive {
 		throw new Error("share archive manifest is malformed");
 	}
 	const archive = raw as unknown as ClioShareArchive;
+	const allowedTypes = new Set<ShareEntryType>([
+		"project-context",
+		"prompt",
+		"skill",
+		"agent",
+		"fleet",
+		"settings",
+		"extension",
+	]);
 	for (const file of archive.files) {
 		if (
 			!isRecord(file) ||
+			!allowedTypes.has(file.type as ShareEntryType) ||
 			typeof file.archivePath !== "string" ||
 			typeof file.relativePath !== "string" ||
 			typeof file.sha256 !== "string" ||
@@ -392,6 +433,10 @@ function targetRootForFile(entry: ShareArchiveFile, options: ShareImportOptions)
 			return scope === "user"
 				? { root: path.join(config, "skills"), containmentRoot: config, scope }
 				: { root: path.join(cwd, ".clio-coder", "skills"), containmentRoot: cwd, scope };
+		case "agent":
+			return { root: path.join(config, "agents"), containmentRoot: config, scope: "user" };
+		case "fleet":
+			return { root: path.join(config, "fleets"), containmentRoot: config, scope: "user" };
 		case "extension":
 			return scope === "user"
 				? { root: path.join(config, "extensions"), containmentRoot: config, scope }
@@ -563,6 +608,26 @@ function prepareShareImport(filePath: string, options: ShareImportOptions = {}):
 	}
 	for (const targetInfo of preflight.targets) {
 		const { entry, target, scope, buffer } = targetInfo;
+		if (entry.type === "fleet") {
+			try {
+				parseFleetContract(buffer.toString("utf8"), target);
+			} catch (error) {
+				diagnostics.push({ type: "error", message: error instanceof Error ? error.message : String(error), path: target });
+				continue;
+			}
+		}
+		if (entry.type === "agent") {
+			try {
+				const parsed = parseFrontmatter(buffer.toString("utf8"), target);
+				const id = path.basename(target, ".md");
+				assertAgentSpecPolicy(
+					normalizeAgentSpec(parseAgentRecipeSchema({ id, source: "user", filepath: target, ...parsed })),
+				);
+			} catch (error) {
+				diagnostics.push({ type: "error", message: error instanceof Error ? error.message : String(error), path: target });
+				continue;
+			}
+		}
 		if (entry.type === "settings") {
 			diagnostics.push(...settingsPlan(buffer, options));
 			actions.push({ action: "settings", type: entry.type, scope, path: target });

package/src/entry/orchestrator.ts

@@ -90,6 +90,7 @@ import {
 import { createMemoryInterventionRegistration } from "../domains/middleware/memory-intervention.js";
 import { createTaskBoardReminderRegistration } from "../domains/middleware/task-board-reminder.js";
 import { createTaskNudgeRegistration } from "../domains/middleware/task-nudge.js";
+import { createWatchdogRegistration } from "../domains/middleware/watchdog.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import { ObservabilityDomainModule } from "../domains/observability/index.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
@@ -177,6 +178,7 @@ import {
 import { subscribeLoopGuardStop } from "../interactive/loop-guard-interrupt.js";
 import { BUILTIN_SLASH_COMMANDS } from "../interactive/slash-commands.js";
 import { createToolProseRegistration } from "../interactive/tool-prose-registration.js";
+import { runWatchdogReview } from "../interactive/watchdog-run.js";
 import { type AskUserHandler, cancelledAskUserResult } from "../tools/ask-user.js";
 import { registerAllTools } from "../tools/bootstrap.js";
 import { isGitRepository, recoverCleanupReadyCompeteGroups } from "../tools/compete-worktrees.js";
@@ -1069,6 +1071,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// Bound late: the registration is built here, but the buffer a deferred
 	// reminder lands in belongs to the chat loop that has not been composed yet.
 	let deferredMemoryReminderSink: ((message: string) => void) | null = null;
+	// The watchdog's findings are for the operator, not the model, so they take
+	// the transcript-notice path rather than the reminder buffer. Bound late for
+	// the same reason: the chat loop that owns the transcript is composed below.
+	let deferredWatchdogNoticeSink: ((text: string) => void) | null = null;
 	// Content-bearing, so it exists only when the operator named a file. The
 	// telemetry row says which silence happened; this says what the model wrote.
 	const memoryTracePath = taskMemoryTracePath();
@@ -1261,6 +1267,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		getAutonomy: resolveEffectiveAutonomy,
 		...(interactive ? { dispatchBackground } : {}),
 		getCostCeilingUsd: () => result.getContract<SchedulingContract>("scheduling")?.ceilingUsd() ?? 0,
+		...(config ? { getWorkerRosters: () => config.get().workers.rosters } : {}),
 		getSkillLoaderOptions: () => ({
 			trustProjectCompatRoots: config?.get().skills.trustProjectCompatRoots === true,
 			disableDiscovery: options.noSkills === true || options.headless?.noSkills === true,
@@ -1521,6 +1528,29 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	middleware.registerHook(
 		createDetachedDispatchNudgeRegistration({ getOpenBatches: () => openDetachedBatchViews(dispatch) }),
 	);
+	// The opt-in turn-end watchdog. Headless and ACP runs pass `false` for the
+	// surface: neither has an operator reading a transcript, so a notice they
+	// cannot see would be a worker run spent on nothing whatever the setting says.
+	middleware.registerHook(
+		createWatchdogRegistration({
+			firesOnThisSurface: interactive,
+			getSettings: () => (effectiveSettingsForDispatch?.() ?? getCurrentSettings()).watchdog,
+			getScope: () => {
+				const board = taskBoard.snapshot();
+				if (board === null) return null;
+				const active = board.tasks.find((task) => task.status === "active");
+				return active ? `${board.title}: ${active.id} ${active.title}` : board.title;
+			},
+			run: (trigger) =>
+				runWatchdogReview(trigger, {
+					dispatch,
+					bus,
+					...(agents ? { getAgentRoleFacts: agentRoleFactsResolver((id: string) => agents.getSpec(id)) } : {}),
+					target: (effectiveSettingsForDispatch?.() ?? getCurrentSettings()).watchdog.target,
+					...(deferredWatchdogNoticeSink ? { emitNotice: deferredWatchdogNoticeSink } : {}),
+				}),
+		}),
+	);
 	if (session) {
 		middleware.registerHook(
 			createFinishContractRegistration({
@@ -1584,6 +1614,9 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		registerDeferredReminderSink: (sink) => {
 			deferredMemoryReminderSink = sink;
 		},
+		registerDeferredNoticeSink: (sink) => {
+			deferredWatchdogNoticeSink = sink;
+		},
 		onAskUserFinalized: (policy) => {
 			decisionBoard.recordFinalizedInterview(policy);
 		},
@@ -1822,6 +1855,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		providers,
 		dispatch,
 		...(agents ? { agents } : {}),
+		...(() => {
+			const scheduling = result.getContract<SchedulingContract>("scheduling");
+			return scheduling ? { scheduling } : {};
+		})(),
 		observability,
 		chat,
 		...(options.terminalLease

package/src/interactive/bus-notices.ts

@@ -187,6 +187,32 @@ export function middlewareHookFailedSessionNotice(payload: unknown, seenBudgetWa
 	return middlewareHookFailedNotice(payload, { noteBudgetWarningSuppression: key !== null });
 }
 
+/** How many failed checks a watchdog notice names before it counts the rest. */
+export const WATCHDOG_NOTICE_CHECK_LIMIT = 3;
+
+/**
+ * The watchdog's finding, as the one transcript line it is allowed.
+ *
+ * A passing report renders nothing: the operator asked for a warning, not a
+ * receipt, and a green line after every mutating turn is noise that trains
+ * people to stop reading the channel. Only the failed checks of the
+ * `verifier-report` contract reach here, and only their names: the evidence
+ * body belongs to the receipt, which the operator can open. Returning null
+ * means the turn passed or the report carried nothing usable.
+ */
+export function watchdogBlockersNotice(checks: ReadonlyArray<{ name: string; passed: boolean }>): BusNotice | null {
+	const failed = checks.filter((check) => !check.passed && check.name.trim().length > 0);
+	if (failed.length === 0) return null;
+	const named = failed.slice(0, WATCHDOG_NOTICE_CHECK_LIMIT).map((check) => check.name.trim());
+	const rest = failed.length - named.length;
+	const more = rest > 0 ? `, and ${rest} more` : "";
+	const blockers = failed.length === 1 ? "blocker" : "blockers";
+	return {
+		level: "warn",
+		text: `[watchdog] ${failed.length} ${blockers} after this turn: ${named.join("; ")}${more}. Nothing was changed or queued.`,
+	};
+}
+
 /**
  * A tool call parked for one-shot approval (sd-01 §3.3). The text names the
  * axis that produced the ask: a safety-net rail asks at every level, while an

package/src/interactive/chat-loop.ts

@@ -17,16 +17,19 @@ import { BusChannels, type RunAbortSource } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { PendingSkillRequest } from "../core/skill-activation.js";
+import { clioStateDir } from "../core/xdg.js";
 import {
 	createMiddlewareToolChoiceControl,
 	type MiddlewareContract,
 	type MiddlewareToolChoiceControl,
 } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
+import type { CostEntryLabel } from "../domains/observability/cost.js";
+import { appendOutOfTurnUsageRow, type OutOfTurnUsageRow } from "../domains/observability/out-of-turn-usage.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
 import { toContextOverflowError } from "../domains/providers/errors.js";
 import type { ProvidersContract } from "../domains/providers/index.js";
-import { runtimeTargetSnapshot } from "../domains/providers/index.js";
+import { normalizeCostProvenance, runtimeTargetSnapshot, targetRequiresAuth } from "../domains/providers/index.js";
 import type { ProtectedArtifactState } from "../domains/safety/protected-artifacts.js";
 import type { CompactResult } from "../domains/session/compaction/compact.js";
 import type { ContextSnapshot, ContextUsageSnapshot } from "../domains/session/context-accounting.js";
@@ -38,6 +41,7 @@ import { protectedArtifactStateFromSessionEntries } from "../domains/session/pro
 import { isRetryableErrorMessage, type RetrySettings } from "../domains/session/retry.js";
 import { createEngineAgent } from "../engine/agent.js";
 import { resolveReservedOutputTokens } from "../engine/apis/output-budget.js";
+import { cwdHash } from "../engine/session.js";
 import type { AgentEvent, AgentMessage, ImageContent } from "../engine/types.js";
 import { resolveSessionTools } from "../tools/agent-tools.js";
 import { finalizeAskUserInterviewForHost } from "../tools/ask-user.js";
@@ -53,7 +57,9 @@ import {
 	toolSignatureFromState,
 } from "./chat-loop-messages.js";
 import { normalizeRetrySettings } from "./chat-loop-policy.js";
+import { runHandoffRound } from "./handoff-round.js";
 import type { ApprovalRequestView } from "./permission-overlay.js";
+import { runSideQuestion, type SideQuestionResult } from "./side-question.js";
 import type { AgentStatusEvent } from "./status/types.js";
 import { createTurnContext } from "./turn-context.js";
 import { createTurnMiddleware } from "./turn-middleware.js";
@@ -184,6 +190,13 @@ export interface ChatSubmitOptions {
 	onAdmitted?: () => void;
 }
 
+/**
+ * Placeholder key a target that needs no auth still has to be handed. Mirrors
+ * the turn runtime's own local fallback, so a `/btw` round against a local
+ * server authenticates exactly the way a turn against it does.
+ */
+const LOCAL_SIDE_QUESTION_API_KEY = "clio-local-target";
+
 /** Closing notice an operator interrupt leaves in the transcript and the ledger. */
 const INTERRUPT_CANCEL_REASON = "[Clio Coder] run interrupted by operator; delivering the new message now.";
 const ENGINE_ACTIVE_PROMPT_ERROR =
@@ -212,6 +225,24 @@ export interface ChatCancelOptions {
 	auditReason?: string;
 }
 
+export interface SideQuestionOptions {
+	/** Cancels the round. Esc and Ctrl+C in the overlay abort through it. */
+	signal?: AbortSignal;
+	/** Streamed answer text so the overlay fills as the provider produces it. */
+	onDelta?: (partialText: string) => void;
+}
+
+/**
+ * How a `/btw` round ended. `refused` is a round that never started (a turn was
+ * in flight, or no orchestrator target is configured); `failed` is a round that
+ * started and the provider rejected.
+ */
+export type SideQuestionOutcome =
+	| { status: "answered"; text: string }
+	| { status: "aborted"; text: string }
+	| { status: "refused"; reason: string }
+	| { status: "failed"; reason: string };
+
 export interface ChatLoop {
 	submit(text: string, options?: ChatSubmitOptions): Promise<void>;
 	steer(text: string): boolean;
@@ -250,6 +281,28 @@ export interface ChatLoop {
 	 * notice so the `/context compact` handler does not have to mirror the logic.
 	 */
 	compact(instructions?: string): Promise<void>;
+	/**
+	 * `/btw`: answer one side question against the session's active target,
+	 * model, and compiled message history without starting a turn.
+	 *
+	 * Nothing this produces reaches the session ledger, the transcript, the
+	 * context ledger, or the footer token counters; the message history is read,
+	 * never mutated. The round's provider usage is still reported to `/cost`,
+	 * labeled as a side question, because money was spent. Refused outright
+	 * while a turn is in flight rather than queued.
+	 */
+	askSideQuestion(question: string, options?: SideQuestionOptions): Promise<SideQuestionOutcome>;
+	/**
+	 * `/handoff`: run the extraction round for a goal against the same target,
+	 * model, and compiled message history, and return its raw JSON answer.
+	 *
+	 * Like a side question this is out of turn: no tools are sent, the message
+	 * history is read and never mutated, and nothing the round produces reaches
+	 * the ledger. Validating, bounding, and reviewing the answer belong to the
+	 * caller; this method only owns the provider call. Refused outright while a
+	 * turn is in flight rather than queued.
+	 */
+	extractHandoff(goal: string, options?: SideQuestionOptions): Promise<SideQuestionOutcome>;
 	/**
 	 * Drop or replace the chat-loop's in-memory state after a session switch
 	 * (/resume, /fork, /new). `leafTurnId` is the id the next user turn
@@ -292,6 +345,20 @@ export interface CreateChatLoopDeps {
 	 */
 	prompts?: PromptsContract;
 	createAgent?: typeof createEngineAgent;
+	/**
+	 * The `/btw` round. Defaults to the real provider call; contracts inject a
+	 * stub so they can assert what a side question does to the session without
+	 * standing up a provider, exactly as `createAgent` does for a turn.
+	 */
+	runSideQuestion?: typeof runSideQuestion;
+	/** The `/handoff` extraction round. Injectable for the same reason. */
+	runHandoffRound?: typeof runHandoffRound;
+	/**
+	 * Append one priced out-of-turn call to the durable out-of-turn usage store.
+	 * Defaults to the real writer under the state dir. Contracts inject a spy so
+	 * they can assert the row was written without touching a real state dir.
+	 */
+	recordOutOfTurnUsageRow?: (row: OutOfTurnUsageRow) => void;
 	/**
 	 * Return the current session's entries for token estimation. The chat-loop
 	 * calls this on every submit so the auto-compaction threshold sees the
@@ -369,6 +436,12 @@ export interface CreateChatLoopDeps {
 	 * composition; the loop owns the buffer the reminder lands in.
 	 */
 	registerDeferredReminderSink?: (sink: (message: string) => void) => void;
+	/**
+	 * The same seam for findings that are for the operator rather than the model.
+	 * The watchdog uses it: its run settles after the turn it reviewed, and its
+	 * blockers become one transcript notice that never enters model context.
+	 */
+	registerDeferredNoticeSink?: (sink: (text: string) => void) => void;
 	/**
 	 * Host-finalizer seam for branch-anchored interview snapshots. Called once,
 	 * after the ask-user host finalizer has settled the policy and its transcript.
@@ -399,6 +472,8 @@ export function reloadProtectedArtifactsForSession(
 export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	const listeners = new Set<(event: ChatLoopEvent) => void>();
 	const createAgent = deps.createAgent ?? createEngineAgent;
+	const sideQuestionRound = deps.runSideQuestion ?? runSideQuestion;
+	const handoffRound = deps.runHandoffRound ?? runHandoffRound;
 	const middlewareToolChoice = deps.middlewareToolChoice ?? createMiddlewareToolChoiceControl();
 	const state = createTurnState(deps.getSettings().orchestrator.thinkingLevel ?? "off");
 	const toolStartTimes = new Map<string, number>();
@@ -485,6 +560,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 
 	try {
 		deps.registerDeferredReminderSink?.((message) => middleware.injectDeferredReminder(message));
+		deps.registerDeferredNoticeSink?.((text) => middleware.emitDeferredNotice(text));
 	} catch {
 		// A background observer losing its delivery path must not stop the loop
 		// from starting; it simply stays silent.
@@ -592,6 +668,102 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		return null;
 	};
 
+	/**
+	 * Everything an out-of-turn round needs, or the reason it cannot run.
+	 *
+	 * `/btw` and `/handoff` are the two callers. Both read the compiled history
+	 * the next turn would see, both authenticate exactly the way a turn against
+	 * the same target does, and both are refused rather than queued while a turn
+	 * is in flight, so the admission decision is made once here.
+	 */
+	type OutOfTurnPreparation =
+		| { ok: true; runtime: AgentRuntime; apiKey: string | undefined }
+		| { ok: false; reason: string };
+
+	const prepareOutOfTurnRound = async (inFlightRefusal: string, signal?: AbortSignal): Promise<OutOfTurnPreparation> => {
+		if (state.streaming) return { ok: false, reason: inFlightRefusal };
+		let agentRuntime: AgentRuntime | null;
+		try {
+			agentRuntime = turnRuntime.ensureRuntime();
+		} catch (err) {
+			return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+		}
+		if (!agentRuntime) return { ok: false, reason: notConfiguredNotice() };
+		const resolution = agentRuntime.runtimeResolution;
+		try {
+			const apiKey = targetRequiresAuth(resolution.target, resolution.runtime)
+				? (
+						await deps.providers.auth.resolveForTarget(resolution.target, resolution.runtime, signal ? { signal } : undefined)
+					).apiKey
+				: LOCAL_SIDE_QUESTION_API_KEY;
+			return { ok: true, runtime: agentRuntime, apiKey };
+		} catch (err) {
+			return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+		}
+	};
+
+	const writeOutOfTurnUsageRow =
+		deps.recordOutOfTurnUsageRow ?? ((row: OutOfTurnUsageRow): void => appendOutOfTurnUsageRow(clioStateDir(), row));
+
+	/**
+	 * Report an out-of-turn round's provider usage. Money was spent, so `/cost`
+	 * says so under its own label; turn persistence, the working-set ledger,
+	 * compaction inputs, and the footer counters never see it.
+	 *
+	 * The same call is also appended to the out-of-turn usage store under the
+	 * state dir. That store exists because `/cost` only knows what this process
+	 * spent: the round appends nothing to the session JSONL by design, so an
+	 * archive reader such as `clio-coder usage report` had no record of the
+	 * spend at all once the process exited. The session ledger stays untouched.
+	 */
+	const recordOutOfTurnUsage = (
+		runtime: AgentRuntime,
+		usage: SideQuestionResult["usage"],
+		label: CostEntryLabel,
+	): void => {
+		if (!usage) return;
+		const costProvenance = runtime.runtimeResolution.costProvenance;
+		deps.observability?.recordTokens(
+			runtime.targetId,
+			runtime.wireModelId,
+			usage.totalTokens,
+			usage.costUsd,
+			{
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				reasoningTokens: usage.reasoning,
+				totalTokens: usage.totalTokens,
+				apiCalls: 1,
+			},
+			costProvenance,
+			undefined,
+			label,
+		);
+		const meta = deps.session?.current() ?? null;
+		writeOutOfTurnUsageRow({
+			label,
+			sessionId: meta?.id ?? null,
+			// The identity the session ledger is filed under, so `usage report
+			// --repo` selects these rows with the same hash it selects ledgers with.
+			repoIdentity: meta ? meta.cwdHash || cwdHash(meta.cwd || process.cwd()) : null,
+			timestamp: new Date().toISOString(),
+			target: runtime.targetId,
+			attributedModelId: runtime.wireModelId,
+			usage: {
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				reasoning: usage.reasoning,
+				totalTokens: usage.totalTokens,
+				costUsd: usage.costUsd,
+				costProvenance: normalizeCostProvenance(costProvenance),
+			},
+		});
+	};
+
 	const api: ChatLoop = {
 		steer: (text) => queues.steer(text),
 		queueFollowUp: (text) => queues.queueFollowUp(text),
@@ -1024,6 +1196,68 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			middlewareToolChoice.reset();
 		},
 
+		async askSideQuestion(question: string, options: SideQuestionOptions = {}): Promise<SideQuestionOutcome> {
+			const text = question.trim();
+			if (text.length === 0) {
+				return { status: "refused", reason: "a side question needs a question" };
+			}
+			// Never queued. A side question exists to be answered now, beside a run
+			// the operator is watching; holding it until the run settles would
+			// deliver it after the moment it was asked in had passed.
+			const prepared = await prepareOutOfTurnRound(
+				"a turn is in flight; /btw runs beside the session, not in its queue",
+				options.signal,
+			);
+			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
+			let result: SideQuestionResult;
+			try {
+				result = await sideQuestionRound({
+					model: prepared.runtime.agent.state.model,
+					// Read-only: runSideQuestion copies before appending its own
+					// message, so the live agent's history is untouched.
+					messages: prepared.runtime.agent.state.messages,
+					question: text,
+					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+					...(options.signal ? { signal: options.signal } : {}),
+					...(options.onDelta ? { onDelta: options.onDelta } : {}),
+				});
+			} catch (err) {
+				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
+			}
+			recordOutOfTurnUsage(prepared.runtime, result.usage, "side-question");
+			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
+		},
+
+		async extractHandoff(goal: string, options: SideQuestionOptions = {}): Promise<SideQuestionOutcome> {
+			const text = goal.trim();
+			if (text.length === 0) {
+				return { status: "refused", reason: "a handoff needs a goal" };
+			}
+			// Refused, never queued: a handoff describes a session that has stopped
+			// working, and a turn still in flight is about to change what the
+			// document would say.
+			const prepared = await prepareOutOfTurnRound(
+				"a turn is in flight; /handoff cannot summarize a session that is still moving",
+				options.signal,
+			);
+			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
+			let result: SideQuestionResult;
+			try {
+				result = await handoffRound({
+					model: prepared.runtime.agent.state.model,
+					// Read-only, exactly as the side-question round treats it.
+					messages: prepared.runtime.agent.state.messages,
+					goal: text,
+					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+					...(options.signal ? { signal: options.signal } : {}),
+				});
+			} catch (err) {
+				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
+			}
+			recordOutOfTurnUsage(prepared.runtime, result.usage, "handoff");
+			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
+		},
+
 		async compact(instructions?: string): Promise<void> {
 			// Session check runs BEFORE orchestrator-configuration so a fresh
 			// TUI with nothing configured still reports the actionable "no

package/src/interactive/chat-renderer.ts

@@ -31,6 +31,13 @@ import type {
 	ThinkingLevelChangeEntry,
 	WorkerRunEntry,
 } from "../domains/session/entries.js";
+import {
+	HANDOFF_NOTE_CUSTOM_TYPE,
+	HANDOFF_SEED_CUSTOM_TYPE,
+	handoffSeedContextText,
+	isHandoffNoteData,
+	isHandoffSeedData,
+} from "../domains/session/handoff.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import {
 	type BashExecutionMessage,
@@ -795,11 +802,18 @@ function rendersCustomEntry(entry: CustomEntry): boolean {
 	if (entry.display === false) return false;
 	if (entry.customType === "retryStatus") return true;
 	if (entry.customType === "finishContractAdvisory" || entry.customType === "middlewareReminder") return true;
+	if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE || entry.customType === HANDOFF_NOTE_CUSTOM_TYPE) return true;
 	return entry.display === true;
 }
 
 function renderCustomEntry(entry: CustomEntry, width: number): string[] {
 	if (entry.customType === "retryStatus") return renderRetryStatusEntry(entry, width);
+	if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE && isHandoffSeedData(entry.data)) {
+		return wrapTextWithAnsi(styleTaggedNotice(`[handoff] carried from session ${entry.data.fromSessionId}`), width);
+	}
+	if (entry.customType === HANDOFF_NOTE_CUSTOM_TYPE && isHandoffNoteData(entry.data)) {
+		return wrapTextWithAnsi(styleTaggedNotice(`[handoff] handed off to session ${entry.data.toSessionId}`), width);
+	}
 	// "finishContractAdvisory" is the pre-middleware name for the same entry
 	// shape; older session ledgers still carry it.
 	if (entry.customType === "finishContractAdvisory" || entry.customType === "middlewareReminder") {
@@ -1039,7 +1053,15 @@ export function buildReplayAgentMessagesFromTurns(
 			case "skillActivation":
 				appendContextMessage(out, "user", skillActivationContextText(entry), entry.timestamp);
 				break;
+			// The one custom entry that becomes a model message. `/handoff` seeds a
+			// new session with a reviewed document, and the seed is the first thing
+			// the model reads there; it is labelled by its origin session and
+			// carried as data, never as a user turn the operator did not write.
 			case "custom":
+				if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE && isHandoffSeedData(entry.data)) {
+					appendContextMessage(out, "user", handoffSeedContextText(entry.data), entry.timestamp);
+				}
+				break;
 			case "modelChange":
 			case "thinkingLevelChange":
 			case "fileEntry":