@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/interactive/slash-commands.ts

@@ -1,6 +1,7 @@
 import { BusChannels } from "../core/bus-events.js";
 import { THINKING_LEVELS } from "../core/defaults.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import { parseCouncilReport, parseOracleResult } from "../domains/agents/index.js";
 import type { AgentSpec } from "../domains/agents/spec.js";
 import type { ContextInitOptions } from "../domains/context/init-options.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
@@ -12,16 +13,46 @@ import type { InstalledExtension } from "../domains/extensions/index.js";
 import type { InteropAgentId, InteropProposal, InteropReport } from "../domains/interop/index.js";
 import type { ProvidersContract, ResolvedModelRef } from "../domains/providers/index.js";
 import { resolveModelReference } from "../domains/providers/index.js";
-import type { PromptTemplate, PromptTemplateExpansion, ResourceList } from "../domains/resources/index.js";
+import type {
+	LibraryEntryKind,
+	PromptTemplate,
+	PromptTemplateExpansion,
+	ResourceList,
+} from "../domains/resources/index.js";
 import { parseSkillCommand } from "../domains/resources/index.js";
 import type { ShareImportPlan } from "../domains/share/index.js";
 import type { UserTask } from "../domains/user-tasks/store.js";
 import { isToolProfileName, TOOL_PROFILE_NAMES, type ToolProfileName } from "../tools/profiles.js";
 import type { NoticeLevel } from "./command-output.js";
+import {
+	buildCouncilDispatchArgs,
+	COUNCIL_MAX_ROUNDS,
+	COUNCIL_SYNTHESIS_MODES,
+	type CouncilCommandOptions,
+	type CouncilRosters,
+	isCouncilSynthesisMode,
+	resolveCouncilRoster,
+} from "./council.js";
+import { COUNCIL_SYNTHESIS_LABEL } from "./council-grid.js";
+import {
+	formatOracleAnswer,
+	ORACLE_AGENT_ID,
+	ORACLE_TASK,
+	type OracleDigestSources,
+	packOracleDigest,
+} from "./oracle.js";
 import { SETTINGS_SECTIONS, type SettingsCenterRowId, type SettingsSectionId } from "./overlays/settings.js";
+import { isLibraryTab, LIBRARY_TABS } from "./overlays/skills-hub.js";
 import type { CommandArgsSpec, CommandPositionalSpec, ParsedArgs } from "./slash-spec.js";
 import { matchFromSpec, usageLine } from "./slash-spec.js";
-import { formatWorkerShareNote, selectWorkerRunToShare, workerShareFactsFromEntry } from "./worker-share.js";
+import {
+	formatCouncilMemberShareNote,
+	formatCouncilShareNote,
+	formatWorkerShareNote,
+	selectWorkerRunToShare,
+	type WorkerShareFacts,
+	workerShareFactsFromEntry,
+} from "./worker-share.js";
 import type { WorkerEntryState } from "./worker-stream.js";
 
 /**
@@ -47,6 +78,7 @@ type SlashCommandVariant =
 	/** `ref` is the turnId an `[evicted ...]` marker names. */
 	| { kind: "context-recall"; ref: string }
 	| { kind: "skill-selector" }
+	| { kind: "library"; tab?: LibraryEntryKind }
 	| { kind: "skill-invocation"; text: string }
 	| { kind: "prompts" }
 	| { kind: "extensions" }
@@ -57,6 +89,19 @@ type SlashCommandVariant =
 	| { kind: "run-usage" }
 	| { kind: "delegate"; agentId: string; task: string; source: string; share?: boolean }
 	| { kind: "delegate-usage" }
+	| { kind: "btw"; question: string }
+	| { kind: "btw-usage" }
+	/** `/oracle <question>`: one read-only advisory run briefed on the record, never on the transcript. */
+	| { kind: "oracle"; question: string }
+	| { kind: "oracle-usage" }
+	/** `/council <task>`: one read-only council of roster members, dispatched through the dispatch tool. */
+	| { kind: "council"; task: string; options: CouncilCommandOptions }
+	| { kind: "council-usage"; reason?: string }
+	| { kind: "handoff"; goal: string }
+	| { kind: "handoff-usage" }
+	/** `/fleet run <name>`: compile the plan, show it for approval, dispatch on accept. */
+	| { kind: "fleet-run"; name: string; vars: Record<string, string> }
+	| { kind: "fleet-run-usage"; reason?: string }
 	| { kind: "agents" }
 	| { kind: "cost" }
 	| { kind: "context-view" }
@@ -109,6 +154,16 @@ export type SetOutputVerbosityResult =
 	| { status: "unsupported"; verbosity: string; supported: ReadonlyArray<string> }
 	| { status: "unavailable" };
 
+/**
+ * What one admitted dispatch-tool call reports back to `/council`. The council
+ * itself is watched on the board and in the transcript, so success is silent;
+ * only a refusal or a failure is worth a notice.
+ */
+export type CouncilDispatchOutcome =
+	| { status: "ok" }
+	| { status: "blocked"; reason: string }
+	| { status: "error"; message: string };
+
 export type TaskMemorySeedCommandResult =
 	| { status: "seeded"; seeded: number; skipped: number; source: string }
 	| { status: "disabled" }
@@ -276,6 +331,136 @@ async function handleDelegate(
 	);
 }
 
+/**
+ * `/oracle <question>`: one advisory run, dispatched like any other.
+ *
+ * Nothing here is a side channel. The run goes through the ordinary dispatch
+ * path, so admission, the receipt, and the Fleet Runs island treat it exactly
+ * as they treat a `/run`; `requestOrigin: "internal"` is what lets a shadow
+ * recipe be reached at all, and `autonomy: "read-only"` narrows the worker
+ * below whatever the session holds. The answer reaches the main agent the way
+ * `/share` puts one there: an operator-authored note on the ordinary user-turn
+ * path, never a fabricated tool result.
+ */
+async function handleOracle(question: string, ctx: SlashCommandContext): Promise<void> {
+	if (!ctx.submitOperatorNote) {
+		ctx.notice("error", "/oracle is not wired in this session; there is nowhere to put the answer");
+		return;
+	}
+	// Refused, never queued. The digest describes the record as it stands and a
+	// turn still in flight is about to change it, so an answer written against
+	// the old record would be advice about a session that no longer exists.
+	if (ctx.isTurnInFlight?.() === true) {
+		ctx.notice("warn", "a turn is in flight; /oracle is refused rather than queued");
+		return;
+	}
+	const sources = ctx.oracleBriefing?.();
+	if (!sources) {
+		ctx.notice("error", "/oracle needs the session record, which is not wired in this session");
+		return;
+	}
+	const digest = packOracleDigest({ ...sources, question });
+	const request: DispatchRequest = {
+		agentId: ORACLE_AGENT_ID,
+		task: ORACLE_TASK,
+		briefing: digest.text,
+		executionRole: requestExecutionRole({
+			agentId: ORACLE_AGENT_ID,
+			...(ctx.getAgentRoleFacts ? { resolveFacts: ctx.getAgentRoleFacts } : {}),
+		}),
+		requestOrigin: "internal",
+		autonomy: "read-only",
+	};
+	const progressBus = ctx.dispatch.ownsProgressBus?.(ctx.bus) === true ? undefined : ctx.bus;
+	try {
+		const handle = await ctx.dispatch.dispatch(request);
+		for await (const event of handle.events) {
+			const typed = event as { type?: string };
+			if (!typed.type || typed.type === "heartbeat") continue;
+			progressBus?.emit(BusChannels.DispatchProgress, { runId: handle.runId, agentId: ORACLE_AGENT_ID, event });
+		}
+		const receipt = await handle.finalPromise;
+		const parsed = parseOracleResult(receipt.output?.text ?? null);
+		if (parsed === null) {
+			ctx.notice("error", `/oracle run ${receipt.runId} returned no usable answer (${receipt.outcome})`);
+			return;
+		}
+		const note = formatWorkerShareNote({
+			agentId: ORACLE_AGENT_ID,
+			runId: receipt.runId,
+			outcome: receipt.outcome,
+			text: formatOracleAnswer(parsed),
+		});
+		if (note === null) {
+			ctx.notice("error", `/oracle run ${receipt.runId} produced no text to share`);
+			return;
+		}
+		ctx.submitOperatorNote(note);
+	} catch (err) {
+		ctx.notice("error", `/oracle failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * `/council <task>`: one council, dispatched exactly as the model dispatches one.
+ *
+ * The command builds dispatch-tool arguments and hands them to the tool
+ * registry. That is the whole of it, and it is deliberate: a council is a
+ * plan-scale dispatch, so supervised autonomy parks the call and the approval
+ * overlay shows the same artifact it shows for a model-asked council, naming
+ * every member's label, target, model, node, round count, and synthesis mode.
+ * A private path would have had to reproduce that, and would eventually have
+ * reproduced it wrongly.
+ */
+async function handleCouncil(task: string, options: CouncilCommandOptions, ctx: SlashCommandContext): Promise<void> {
+	// Refused, never queued, exactly as `/oracle` and `/fleet run` are. An
+	// approved council describes the workspace as it stands, and a turn in
+	// flight is about to change it.
+	if (ctx.isTurnInFlight?.() === true) {
+		ctx.notice("warn", "a turn is in flight; /council is refused rather than queued");
+		return;
+	}
+	if (!ctx.runCouncilDispatch) {
+		ctx.notice("error", "/council is not wired in this session");
+		return;
+	}
+	const rosters = ctx.getWorkerRosters?.();
+	if (rosters === undefined) {
+		ctx.notice("error", "/council needs workers.rosters, which is not wired in this session");
+		return;
+	}
+	const resolved = resolveCouncilRoster(options.roster, rosters);
+	if (!resolved.ok) {
+		ctx.notice("error", resolved.reason);
+		return;
+	}
+	try {
+		const outcome = await ctx.runCouncilDispatch(buildCouncilDispatchArgs(task, resolved.roster, options));
+		if (outcome.status === "blocked") ctx.notice("warn", `/council was not admitted: ${outcome.reason}`);
+		else if (outcome.status === "error") ctx.notice("error", `/council failed: ${outcome.message}`);
+	} catch (err) {
+		ctx.notice("error", `/council failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * The note a run becomes, with a council run treated as what it is.
+ *
+ * A council synthesis run seals the whole `council-report`, so sharing its id
+ * shares the council: every final member's labelled answer and the synthesis,
+ * as one bounded block. A member run seals one voice, so it travels under the
+ * roster label the operator watched it under. Every other run keeps the note it
+ * has always had. A synthesis whose sealed text does not parse as a report is
+ * shared verbatim rather than dropped: the operator asked for that run.
+ */
+function councilAwareShareNote(facts: WorkerShareFacts, entry: WorkerEntryState): string | null {
+	const council = entry.council;
+	if (council === undefined) return formatWorkerShareNote(facts);
+	if (council.label !== COUNCIL_SYNTHESIS_LABEL) return formatCouncilMemberShareNote(facts, council.label);
+	const report = parseCouncilReport(facts.text);
+	return report === null ? formatWorkerShareNote(facts) : formatCouncilShareNote(facts, report);
+}
+
 /**
  * `/share [runId]`: hand a finished worker run's answer to the main agent.
  *
@@ -299,7 +484,7 @@ function shareWorkerRun(runId: string | undefined, ctx: SlashCommandContext): vo
 		return;
 	}
 	const facts = workerShareFactsFromEntry(entry);
-	const note = facts === null ? null : formatWorkerShareNote(facts);
+	const note = facts === null ? null : councilAwareShareNote(facts, entry);
 	if (note === null) {
 		ctx.notice("error", `run ${entry.runId} produced no text to share`);
 		return;
@@ -352,7 +537,7 @@ export interface SlashCommandContext {
 	 * until the host wires a session.
 	 */
 	runContextRecall?: (ref: string) => void;
-	openSkillsHub?: () => void;
+	openSkillsHub?: (tab?: LibraryEntryKind) => void;
 	listPrompts: () => ResourceList<PromptTemplate>;
 	/**
 	 * Resolve a `/name` against the loaded prompt templates. Absent when the host
@@ -380,6 +565,51 @@ export interface SlashCommandContext {
 	exportShareArchive?: (outPath: string) => { fileCount: number; path: string };
 	importShareArchive?: (path: string, options: { dryRun?: boolean; force?: boolean }) => ShareImportPlan;
 	openCost: () => void;
+	/**
+	 * `/btw <question>`: one model round beside the session, answered in an
+	 * overlay. Nothing about it enters the transcript, the ledger, or the task
+	 * board, so the workers a fleet run briefs never see the question or its
+	 * answer.
+	 */
+	openSideQuestion: (question: string) => void;
+	/**
+	 * The record `/oracle` briefs its advisor on: settled decisions, the task
+	 * board, and the last compaction summary. Absent on a host with no session,
+	 * in which case `/oracle` says so instead of briefing on nothing.
+	 */
+	oracleBriefing?: () => Omit<OracleDigestSources, "question">;
+	/**
+	 * Configured `workers.rosters`, which is what `/council` seats a council
+	 * from. Absent on a host with no settings, in which case the command says so
+	 * rather than dispatching a roster name it could not check.
+	 */
+	getWorkerRosters?: () => CouncilRosters;
+	/**
+	 * Run one dispatch-tool call with prepared council arguments through the
+	 * ordinary tool-admission path. The council command owns no dispatch path of
+	 * its own, so admission, the approval overlay, receipts, and the board treat
+	 * an operator council exactly as they treat a model-asked one.
+	 */
+	runCouncilDispatch?: (args: Readonly<Record<string, unknown>>) => Promise<CouncilDispatchOutcome>;
+	/**
+	 * True while a turn is streaming. `/oracle` is refused then, never queued:
+	 * the digest describes the record as it stands and an in-flight turn is
+	 * about to change it.
+	 */
+	isTurnInFlight?: () => boolean;
+	/**
+	 * `/handoff <goal>`: extract this session's working state for a stated goal,
+	 * review the document, and seed a successor session with it. A session
+	 * operation only. It writes no memory promotion candidate and never calls
+	 * the task-memory bank.
+	 */
+	startHandoff: (goal: string) => void;
+	/**
+	 * `/fleet run <name>`: compile the contract's plan, show every wave, agent,
+	 * target, boundary, budget, and code-step argv for approval, and dispatch
+	 * only what the operator accepted. Absent on a host with no fleet wiring.
+	 */
+	startFleetRun?: (name: string, vars: Readonly<Record<string, string>>) => void;
 	/** Open the read-only `/context` overlay: categorized context-window ledger. */
 	openContextView: () => void;
 	/** Open the read-only `/tasks` overlay: the session task board with receipts. */
@@ -591,6 +821,26 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			}
 		},
 	},
+	{
+		name: "library",
+		description: "Open the Skills Hub on a resource library tab",
+		group: "Run",
+		kinds: ["library"],
+		args: { positionals: [{ name: "kind", required: false }] },
+		fromArgs(parsed) {
+			if (parsed.error) return { kind: "usage-error", command: "library", reason: parsed.error };
+			const tab = parsed.positionals[0];
+			if (tab === undefined) return { kind: "library" };
+			if (!isLibraryTab(tab)) {
+				const known = LIBRARY_TABS.map((entry) => entry.id).join(", ");
+				return { kind: "usage-error", command: "library", reason: `Unknown kind: ${tab} (one of ${known})` };
+			}
+			return { kind: "library", tab };
+		},
+		handle(command, ctx) {
+			if (command.kind === "library") ctx.openSkillsHub?.(command.tab);
+		},
+	},
 	{
 		name: "prompts",
 		description: "List prompt templates",
@@ -850,6 +1100,108 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			})();
 		},
 	},
+	{
+		name: "btw",
+		description: "Ask a side question that never enters the session transcript",
+		group: "Run",
+		kinds: ["btw", "btw-usage"],
+		args: {
+			positionals: [{ name: "question", required: true, rest: true }],
+		},
+		fromArgs(parsed) {
+			const question = parsed.rest?.trim() ?? "";
+			if (parsed.error || question.length === 0) return { kind: "btw-usage" };
+			return { kind: "btw", question };
+		},
+		handle(command, ctx) {
+			if (command.kind === "btw-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "btw");
+				if (entry) ctx.notice("info", usageNotice(entry));
+				return;
+			}
+			if (command.kind !== "btw") return;
+			ctx.openSideQuestion(command.question);
+		},
+	},
+	{
+		name: "oracle",
+		description: "Ask a read-only advisor to challenge a question against this session's settled decisions",
+		group: "Run",
+		kinds: ["oracle", "oracle-usage"],
+		args: {
+			positionals: [{ name: "question", required: true, rest: true }],
+		},
+		fromArgs(parsed) {
+			const question = parsed.rest?.trim() ?? "";
+			if (parsed.error || question.length === 0) return { kind: "oracle-usage" };
+			return { kind: "oracle", question };
+		},
+		handle(command, ctx) {
+			if (command.kind === "oracle-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "oracle");
+				if (entry) ctx.notice("info", usageNotice(entry));
+				return;
+			}
+			if (command.kind !== "oracle") return;
+			void (async () => {
+				await handleOracle(command.question, ctx);
+				ctx.render();
+			})();
+		},
+	},
+	{
+		name: "council",
+		description: "Ask a roster of read-only members the same task, with an optional vote or judge synthesis",
+		group: "Run",
+		kinds: ["council", "council-usage"],
+		args: {
+			parseFlagsBeforeRest: true,
+			flags: [
+				{ name: "--roster", takesValue: true, valueName: "name" },
+				{ name: "--rounds", takesValue: true, valueName: "n" },
+				{ name: "--synthesis", takesValue: true, values: COUNCIL_SYNTHESIS_MODES },
+			],
+			positionals: [{ name: "task", required: true, rest: true }],
+		},
+		fromArgs(parsed) {
+			const task = parsed.rest?.trim() ?? "";
+			if (parsed.error) return { kind: "council-usage", reason: parsed.error };
+			if (task.length === 0) return { kind: "council-usage" };
+			const options: CouncilCommandOptions = {};
+			const roster = parsed.flags.get("--roster");
+			if (typeof roster === "string") options.roster = roster;
+			const rounds = parsed.flags.get("--rounds");
+			if (typeof rounds === "string") {
+				const parsedRounds = Number(rounds);
+				// The tool bounds rounds at one to three, and a council that is
+				// refused after admission has already shown the operator a plan it
+				// cannot run, so the same bound is enforced where it was typed.
+				if (!Number.isInteger(parsedRounds) || parsedRounds < 1 || parsedRounds > COUNCIL_MAX_ROUNDS) {
+					return { kind: "council-usage", reason: `--rounds must be an integer 1..${COUNCIL_MAX_ROUNDS}` };
+				}
+				options.rounds = parsedRounds;
+			}
+			const synthesis = parsed.flags.get("--synthesis");
+			if (typeof synthesis === "string") {
+				if (!isCouncilSynthesisMode(synthesis)) return { kind: "council-usage" };
+				options.synthesis = synthesis;
+			}
+			return { kind: "council", task, options };
+		},
+		handle(command, ctx) {
+			if (command.kind === "council-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "council");
+				const usage = entry ? usageNotice(entry) : "usage: /council <task>";
+				ctx.notice("info", command.reason ? `${command.reason}\n${usage}` : usage);
+				return;
+			}
+			if (command.kind !== "council") return;
+			void (async () => {
+				await handleCouncil(command.task, command.options, ctx);
+				ctx.render();
+			})();
+		},
+	},
 	{
 		name: "agents",
 		description: "List Clio agents and ACP delegation agents",
@@ -944,7 +1296,59 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			}
 		},
 	},
-	settingsDeepLink("fleet", "fleet", "Open Settings → Fleet: defaults, profiles, agent bindings, nodes"),
+	{
+		name: "fleet",
+		description: "Open Settings → Fleet, or run a fleet contract with an approval preview",
+		group: "Configure",
+		kinds: ["fleet-run", "fleet-run-usage"],
+		subcommandDescriptions: { run: "Preview and run a repo-owned fleet contract" },
+		args: {
+			subcommands: {
+				run: {
+					flags: [{ name: "--var", takesValue: true, repeatable: true, valueName: "key=value" }],
+					positionals: [{ name: "name", required: true }],
+				},
+			},
+		},
+		/**
+		 * `/fleet` alone keeps the settings deep link it has always been, and
+		 * only `run` parses as a command of its own, so an operator who types
+		 * `/fleet` out of habit still lands in Settings → Fleet. Anything else
+		 * on the line stays the usage error every other deep link reports.
+		 */
+		fromArgs(parsed) {
+			if (parsed.subcommand !== "run") {
+				return parsed.error
+					? { kind: "usage-error", command: "fleet", reason: parsed.error }
+					: { kind: "settings", section: "fleet" };
+			}
+			if (parsed.error) return { kind: "fleet-run-usage", reason: parsed.error };
+			const name = parsed.positionals[0] ?? "";
+			if (name.length === 0) return { kind: "fleet-run-usage" };
+			const vars: Record<string, string> = {};
+			for (const pair of parsed.flagValues.get("--var") ?? []) {
+				const eq = pair.indexOf("=");
+				const key = eq < 0 ? "" : pair.slice(0, eq).trim();
+				if (key.length === 0) return { kind: "fleet-run-usage", reason: "--var requires key=value" };
+				vars[key] = pair.slice(eq + 1);
+			}
+			return { kind: "fleet-run", name, vars };
+		},
+		handle(command, ctx) {
+			if (command.kind === "fleet-run-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "fleet");
+				const usage = entry ? usageNotice(entry, "run") : "usage: /fleet run <name> [--var key=value ...]";
+				ctx.notice("info", command.reason ? `${command.reason}\n${usage}` : usage);
+				return;
+			}
+			if (command.kind !== "fleet-run") return;
+			if (!ctx.startFleetRun) {
+				ctx.notice("error", "/fleet run is not wired in this session");
+				return;
+			}
+			ctx.startFleetRun(command.name, command.vars);
+		},
+	},
 	{
 		name: "decisions",
 		description: "Show settled interview decisions and operator revisions",
@@ -1250,6 +1654,29 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			ctx.startNewSession();
 		},
 	},
+	{
+		name: "handoff",
+		description: "Hand this session's working state to a fresh session for a stated goal",
+		group: "Sessions",
+		kinds: ["handoff", "handoff-usage"],
+		args: {
+			positionals: [{ name: "goal", required: true, rest: true }],
+		},
+		fromArgs(parsed) {
+			const goal = parsed.rest?.trim() ?? "";
+			if (parsed.error || goal.length === 0) return { kind: "handoff-usage" };
+			return { kind: "handoff", goal };
+		},
+		handle(command, ctx) {
+			if (command.kind === "handoff-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "handoff");
+				if (entry) ctx.notice("info", usageNotice(entry));
+				return;
+			}
+			if (command.kind !== "handoff") return;
+			ctx.startHandoff(command.goal);
+		},
+	},
 	{
 		name: "tree",
 		description: "Open session tree navigator",

package/src/interactive/slash-spec.ts

@@ -154,18 +154,31 @@ export function parseArgs(spec: CommandArgsSpec, argsLine: string): ParsedArgs {
 	const positionalSpecs = currentSpec.positionals ?? [];
 	let positionalIndex = 0;
 
+	// A token ends at whitespace unless a quote is open: `--var task="do it"`
+	// and `--var "task=do it"` both carry the spaces through, and the quotes
+	// themselves are dropped. An unterminated quote runs to the end of the line.
 	const readToken = (): { token: string } | null => {
 		const tokenStart = index;
+		let token = "";
+		let quote: string | null = null;
 		while (index < argsLine.length) {
-			const char = argsLine[index];
-			if (char && !/\s/.test(char)) {
+			const char = argsLine[index] ?? "";
+			if (quote !== null) {
+				if (char === quote) quote = null;
+				else token += char;
 				index++;
-			} else {
-				break;
+				continue;
+			}
+			if (char === '"' || char === "'") {
+				quote = char;
+				index++;
+				continue;
 			}
+			if (/\s/.test(char)) break;
+			token += char;
+			index++;
 		}
-		const token = argsLine.slice(tokenStart, index);
-		if (token.length === 0) return null;
+		if (index === tokenStart) return null;
 		return { token };
 	};
 

package/src/interactive/theme/tokens.ts

@@ -119,3 +119,33 @@ export function createClioTheme(options: { truecolor?: boolean; color?: boolean
 		fgSequence: (token) => (color ? `\u001b[${fgCode(TOKENS[token], truecolor)}m` : ""),
 	};
 }
+
+/** True when `value` names one of the theme's own tokens, so it can be painted as one. */
+export function isClioToken(value: string): value is ClioToken {
+	return Object.hasOwn(TOKENS, value);
+}
+
+const HEX_COLOR = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/u;
+
+/**
+ * Paint text in a configured `#rrggbb` color.
+ *
+ * A council roster member may carry one. A roster color is the operator's own
+ * choice rather than a token from the palette, which is why a literal color
+ * reaches the screen here and nowhere else. Returns the text unchanged when
+ * color is disabled or the value is not a six-digit hex color, so a caller can
+ * fall back to a token without inspecting the string twice. A terminal without
+ * truecolor gets the nearest color in the 6x6x6 xterm cube.
+ */
+export function paintHex(text: string, hex: string, options: { truecolor?: boolean; color?: boolean } = {}): string {
+	const match = HEX_COLOR.exec(hex);
+	if (match === null) return text;
+	if (!(options.color ?? !colorDisabled())) return text;
+	const truecolor = options.truecolor ?? detectTruecolor();
+	const red = Number.parseInt(match[1] ?? "0", 16);
+	const green = Number.parseInt(match[2] ?? "0", 16);
+	const blue = Number.parseInt(match[3] ?? "0", 16);
+	if (truecolor) return `\u001b[38;2;${red};${green};${blue}m${text}${SGR_RESET}`;
+	const cube = (channel: number): number => Math.round((channel / 255) * 5);
+	return `\u001b[38;5;${16 + 36 * cube(red) + 6 * cube(green) + cube(blue)}m${text}${SGR_RESET}`;
+}

package/src/interactive/turn-middleware.ts

@@ -25,7 +25,7 @@ export interface TurnMiddlewareDeps {
 	middleware?: MiddlewareContract | undefined;
 	session?: SessionContract | undefined;
 	middlewareToolChoice: MiddlewareToolChoiceControl;
-	emitNotice: (text: string) => void;
+	emitNotice: (text: string, level?: "info" | "warning" | "error") => void;
 	emitFooterNotice: (level: "info" | "success" | "warning" | "error", text: string, key: string) => void;
 }
 
@@ -55,6 +55,14 @@ export interface TurnMiddleware {
 	 * turn_end reminder takes.
 	 */
 	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity): void;
+	/**
+	 * Deliver an operator-facing finding produced after its turn boundary closed.
+	 * The watchdog seam: its run settles well after the turn it reviewed, and
+	 * what it found is for the person, not the model. Unlike a deferred
+	 * reminder, this never joins the pending-reminder buffer and never appends a
+	 * `middlewareReminder` entry, so nothing it says can enter the next request.
+	 */
+	emitDeferredNotice(text: string, level?: "info" | "warning"): void;
 }
 
 export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
@@ -280,5 +288,11 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			appendMiddlewareReminderEntry(text, level);
 			deps.emitNotice(text);
 		},
+
+		emitDeferredNotice(text, level = "warning"): void {
+			const message = text.trim();
+			if (message.length === 0) return;
+			deps.emitNotice(message, level);
+		},
 	};
 }