@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/core/settings-layers.ts

@@ -0,0 +1,354 @@
+/**
+ * Scoped settings layering. Effective settings come from four file layers plus
+ * CLI flags, lowest precedence first:
+ *
+ *   built-in  <  user settings.yaml  <  project .clio-coder/settings.yaml
+ *             <  project .clio-coder/settings.local.yaml  <  CLI flags
+ *
+ * Layering happens on the raw parsed blobs so each effective leaf can be
+ * attributed to the layer that set it, then the merged blob is validated against
+ * the one strict schema (core/config.ts). Project layers are committed
+ * team configuration and must stay secrets-free, so credential-bearing keys are
+ * stripped from the project and project.local layers with a diagnostic.
+ *
+ * Merge semantics, documented and explicit: objects deep-merge key by key;
+ * arrays and scalars replace wholesale (a later layer's array wins entirely).
+ * Replacing arrays keeps the result predictable and avoids ambiguous element
+ * identity. Reads are best-effort: a missing file is skipped, and a malformed
+ * file degrades to the lower layers with an issue rather than throwing.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import {
+	applySettingsDelta,
+	type ClioSettings,
+	type SettingsIssue,
+	type SettingsMutator,
+	SettingsValidationError,
+	settingsPath,
+	updateSavedSettingsDocument,
+	validateSettings,
+} from "./config.js";
+
+export type SettingsOrigin = "built-in" | "user" | "project" | "project.local" | "cli";
+
+export interface SettingsLayerIssue {
+	origin: SettingsOrigin;
+	path: string;
+	message: string;
+	kind?: SettingsIssue["kind"];
+}
+
+export interface SettingsLayerInfo {
+	origin: SettingsOrigin;
+	path: string;
+	present: boolean;
+}
+
+export interface LayeredSettings {
+	settings: ClioSettings;
+	/** Dotted leaf path to the origin that set it. Keys not present here are built-in defaults. */
+	sources: Record<string, SettingsOrigin>;
+	issues: SettingsLayerIssue[];
+	layers: SettingsLayerInfo[];
+}
+
+const STRICT_USER_ISSUES = Symbol("strict-user-issues");
+type InternalLayeredSettings = LayeredSettings & { [STRICT_USER_ISSUES]: SettingsIssue[] };
+
+// Keys whose presence in a project layer means a credential leaked into a
+// committed file. `auth` carries target headers and api keys; the rest cover
+// stray secrets. Stripped from project layers with a diagnostic.
+const CREDENTIAL_KEYS: ReadonlySet<string> = new Set(["auth", "apikey", "api_key", "token", "secret", "password"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepEquals(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((entry, index) => deepEquals(entry, b[index]));
+	}
+	if (!isRecord(a) || !isRecord(b)) return false;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	return keys.every((key) => key in b && deepEquals(a[key], b[key]));
+}
+
+interface RawLayer {
+	origin: SettingsOrigin;
+	path: string;
+	blob: Record<string, unknown> | undefined;
+}
+
+function readRawLayer(origin: SettingsOrigin, path: string, issues: SettingsLayerIssue[]): RawLayer {
+	if (!existsSync(path)) return { origin, path, blob: undefined };
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (err) {
+		issues.push({
+			origin,
+			path: "(root)",
+			message: `unreadable: ${err instanceof Error ? err.message : String(err)}`,
+			kind: "unreadable",
+		});
+		return { origin, path, blob: undefined };
+	}
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(text);
+	} catch (err) {
+		issues.push({
+			origin,
+			path: "(root)",
+			message: `invalid YAML: ${err instanceof Error ? err.message : String(err)}`,
+			kind: "syntax",
+		});
+		return { origin, path, blob: undefined };
+	}
+	if (parsed === null || parsed === undefined) return { origin, path, blob: {} };
+	if (!isRecord(parsed)) {
+		issues.push({ origin, path: "(root)", message: "settings file must be a mapping at the root" });
+		return { origin, path, blob: undefined };
+	}
+	return { origin, path, blob: parsed };
+}
+
+/**
+ * Remove credential-bearing keys from a project layer, recording where each was
+ * dropped. Recurses through nested objects and arrays so a credential nested
+ * under `targets[].auth` is caught too.
+ */
+function stripCredentials(value: unknown, origin: SettingsOrigin, path: string, issues: SettingsLayerIssue[]): unknown {
+	if (Array.isArray(value)) {
+		return value.map((item, index) => stripCredentials(item, origin, `${path}[${index}]`, issues));
+	}
+	if (!isRecord(value)) return value;
+	const out: Record<string, unknown> = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (CREDENTIAL_KEYS.has(key.toLowerCase())) {
+			issues.push({
+				origin,
+				path: path ? `${path}.${key}` : key,
+				message: "credentials are not allowed in project settings; key ignored",
+			});
+			continue;
+		}
+		out[key] = stripCredentials(child, origin, path ? `${path}.${key}` : key, issues);
+	}
+	return out;
+}
+
+/**
+ * Deep-merge raw layer blobs in precedence order, recording the origin that last
+ * set each leaf. Objects recurse; arrays and scalars replace.
+ */
+function mergeLayersWithSources(layers: ReadonlyArray<RawLayer>): {
+	merged: Record<string, unknown>;
+	sources: Record<string, SettingsOrigin>;
+} {
+	const merged: Record<string, unknown> = {};
+	const sources: Record<string, SettingsOrigin> = {};
+	for (const layer of layers) {
+		if (layer.blob === undefined) continue;
+		mergeInto(merged, layer.blob, layer.origin, "", sources);
+	}
+	return { merged, sources };
+}
+
+function mergeInto(
+	target: Record<string, unknown>,
+	source: Record<string, unknown>,
+	origin: SettingsOrigin,
+	prefix: string,
+	sources: Record<string, SettingsOrigin>,
+): void {
+	for (const [key, value] of Object.entries(source)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (isRecord(value)) {
+			const existing = target[key];
+			const nested = isRecord(existing) ? existing : {};
+			mergeInto(nested, value, origin, path, sources);
+			target[key] = nested;
+			sources[path] = origin;
+		} else {
+			target[key] = Array.isArray(value) ? [...value] : value;
+			sources[path] = origin;
+		}
+	}
+}
+
+export interface ReadLayeredSettingsOptions {
+	/** Override the user settings.yaml path; defaults to the resolved config dir. */
+	userPath?: string;
+}
+
+interface PreparedLayers {
+	projectFile: string;
+	localFile: string;
+	projectRaw: RawLayer;
+	localRaw: RawLayer;
+	project: RawLayer;
+	local: RawLayer;
+}
+
+function prepareProjectLayers(cwd: string, issues: SettingsLayerIssue[]): PreparedLayers {
+	const projectFile = join(cwd, ".clio-coder", "settings.yaml");
+	const localFile = join(cwd, ".clio-coder", "settings.local.yaml");
+	const projectRaw = readRawLayer("project", projectFile, issues);
+	const localRaw = readRawLayer("project.local", localFile, issues);
+	const project: RawLayer = {
+		...projectRaw,
+		blob:
+			projectRaw.blob === undefined
+				? undefined
+				: (stripCredentials(projectRaw.blob, "project", "", issues) as Record<string, unknown>),
+	};
+	const local: RawLayer = {
+		...localRaw,
+		blob:
+			localRaw.blob === undefined
+				? undefined
+				: (stripCredentials(localRaw.blob, "project.local", "", issues) as Record<string, unknown>),
+	};
+	return { projectFile, localFile, projectRaw, localRaw, project, local };
+}
+
+function validateLayerStack(
+	user: RawLayer,
+	prepared: PreparedLayers,
+	issues: SettingsLayerIssue[],
+): { settings: ClioSettings; sources: Record<string, SettingsOrigin> } {
+	const { merged, sources } = mergeLayersWithSources([user, prepared.project, prepared.local]);
+	const validation = validateSettings(merged);
+	for (const issue of validation.issues) {
+		issues.push({ origin: settingsSourceFor(sources, issue.path), path: issue.path, message: issue.message });
+	}
+	return { settings: validation.settings, sources };
+}
+
+/**
+ * Read and layer settings for `cwd`, returning the validated effective settings
+ * plus per-leaf source attribution. Never throws: validation issues and layer
+ * problems are returned, and the effective settings always validate (invalid
+ * merges fall back to the schema defaults for the offending keys).
+ */
+export function readLayeredSettings(cwd: string, options: ReadLayeredSettingsOptions = {}): LayeredSettings {
+	const issues: SettingsLayerIssue[] = [];
+	const userFile = options.userPath ?? settingsPath();
+	const user = readRawLayer("user", userFile, issues);
+	const prepared = prepareProjectLayers(cwd, issues);
+	const { settings, sources } = validateLayerStack(user, prepared, issues);
+
+	const strictUserIssues =
+		user.blob === undefined
+			? []
+			: validateSettings(user.blob).issues.map((issue) => ({
+					path: issue.path,
+					message: issue.message,
+					...(issue.kind ? { kind: issue.kind } : {}),
+				}));
+	return {
+		settings,
+		sources,
+		issues,
+		layers: [
+			{ origin: "built-in", path: "(defaults)", present: true },
+			{ origin: "user", path: userFile, present: user.blob !== undefined },
+			{ origin: "project", path: prepared.projectFile, present: prepared.projectRaw.blob !== undefined },
+			{ origin: "project.local", path: prepared.localFile, present: prepared.localRaw.blob !== undefined },
+		],
+		[STRICT_USER_ISSUES]: strictUserIssues,
+	} as InternalLayeredSettings;
+}
+
+/**
+ * Read the complete effective stack once while retaining settings.yaml's
+ * strict launch gate. Project-layer issues remain diagnostics, matching the
+ * established best-effort workspace overlay contract.
+ */
+export function readStrictLayeredSettings(cwd: string, options: ReadLayeredSettingsOptions = {}): LayeredSettings {
+	const layered = readLayeredSettings(cwd, options) as InternalLayeredSettings;
+	const reportedUserIssues = layered.issues
+		.filter((issue) => issue.origin === "user")
+		.map(({ path, message, kind }): SettingsIssue => ({ path, message, ...(kind ? { kind } : {}) }));
+	const userIssues = [...reportedUserIssues, ...layered[STRICT_USER_ISSUES]].filter(
+		(issue, index, all) =>
+			all.findIndex(
+				(candidate) =>
+					candidate.path === issue.path && candidate.message === issue.message && candidate.kind === issue.kind,
+			) === index,
+	);
+	if (userIssues.length > 0) throw new SettingsValidationError(userIssues);
+	return layered;
+}
+
+/**
+ * Atomically persist a mutation of the effective workspace settings into the
+ * user layer. The candidate user document is re-layered with the same project
+ * files before it is written. This preserves references to project-only
+ * targets while refusing a mutation that a higher-precedence project leaf
+ * would silently override.
+ */
+export function updateLayeredSettings(cwd: string, mutate: SettingsMutator): ClioSettings {
+	let committed: ClioSettings | null = null;
+	updateSavedSettingsDocument((saved) => {
+		const userValidation = validateSettings(saved);
+		if (userValidation.issues.length > 0) throw new SettingsValidationError(userValidation.issues);
+		const issues: SettingsLayerIssue[] = [];
+		const prepared = prepareProjectLayers(cwd, issues);
+		const user: RawLayer = {
+			origin: "user",
+			path: settingsPath(),
+			blob: isRecord(saved) ? saved : {},
+		};
+		const before = validateLayerStack(user, prepared, issues).settings;
+		const candidate = structuredClone(before);
+		const next = mutate(candidate) ?? candidate;
+		const candidateValidation = validateSettings(JSON.parse(JSON.stringify(next)));
+		if (candidateValidation.issues.length > 0) throw new SettingsValidationError(candidateValidation.issues);
+
+		const nextSaved = applySettingsDelta(saved, before, candidateValidation.settings);
+		const finalIssues: SettingsLayerIssue[] = [];
+		const final = validateLayerStack(
+			{ origin: "user", path: settingsPath(), blob: isRecord(nextSaved) ? nextSaved : {} },
+			prepared,
+			finalIssues,
+		).settings;
+		if (!deepEquals(final, candidateValidation.settings)) {
+			throw new Error("a higher-precedence project setting prevents this settings update");
+		}
+		committed = final;
+		return nextSaved;
+	});
+	if (committed === null) throw new Error("layered settings update did not commit");
+	return committed;
+}
+
+/**
+ * Effective origin of one dotted key path: the layer that set it, or built-in
+ * when no layer did. A parent path's origin applies when the exact leaf was not
+ * individually tracked.
+ */
+export function settingsSourceFor(sources: Record<string, SettingsOrigin>, keyPath: string): SettingsOrigin {
+	let prefix = keyPath;
+	while (prefix.length > 0) {
+		const direct = sources[prefix];
+		if (direct) return direct;
+		const bracket = prefix.lastIndexOf("[");
+		if (bracket >= 0) {
+			const arrayKey = prefix.slice(0, bracket);
+			const hit = sources[arrayKey];
+			if (hit) return hit;
+		}
+		const dot = prefix.lastIndexOf(".");
+		if (dot < 0) break;
+		prefix = prefix.slice(0, dot);
+	}
+	return "built-in";
+}

package/src/core/shared-bus.ts

@@ -0,0 +1,8 @@
+import { createSafeEventBus, type SafeEventBus } from "./event-bus.js";
+
+let sharedBus: SafeEventBus | null = null;
+
+export function getSharedBus(): SafeEventBus {
+	if (!sharedBus) sharedBus = createSafeEventBus();
+	return sharedBus;
+}

package/src/core/shell-quote.ts

@@ -0,0 +1,26 @@
+/**
+ * POSIX single-quote escaping for one shell word.
+ *
+ * Every consumer here builds a command string that a POSIX shell will parse:
+ * an eval runner's `sh -c`, the SSH transport's remote command, and an
+ * external editor launched through `$SHELL -lc`. The escaping a
+ * single-quoted POSIX word needs is fixed by the shell grammar rather than
+ * chosen per caller, so there is one rule and it cannot drift per consumer
+ * without that consumer having stopped targeting a POSIX shell.
+ *
+ * Inside single quotes a POSIX shell treats every byte literally, including
+ * backslashes, so the only character that needs handling is the quote itself.
+ * `'\''` closes the string, emits an escaped literal quote, and reopens it.
+ *
+ * The result always begins and ends with a single quote, including for the
+ * empty string, which is what makes it exactly one word. `fleet-preflight.ts`
+ * relies on that shape: it strips the outer pair to embed an already-escaped
+ * value inside a `case` pattern, so an implementation that returned a bare
+ * word for safe input would silently break that caller.
+ *
+ * This is quoting for a shell, never sanitization for a security boundary. A
+ * quoted word is one argument; it is not a value that has been vetted.
+ */
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/core/skill-activation.ts

@@ -0,0 +1,190 @@
+export type SkillActivationTrigger = "slash-command" | "tool";
+export type PendingSkillRequestSource = "slash-command" | "selector" | "marketplace" | "recipe";
+
+/**
+ * The one reply shape every surface teaches for skill suggestions: the
+ * context(scope="skills") listing footer, the first-turn middleware
+ * reminder, and the operator-gate denial all cite this exact line so the
+ * model learns a single protocol.
+ */
+export const SKILL_SUGGESTION_ANCHOR = "Suggested skill: /skill <name>";
+
+/**
+ * The part of the anchor a real reply keeps once `<name>` is substituted.
+ *
+ * Surfaces that recognize a suggestion in live output must match this, not the
+ * template: no model ever writes the literal `<name>`, so a full-anchor test is
+ * always false. The chat panel's glyph guard was exactly that, and the
+ * suggestion held the turn's ✦ while the answer beneath it hung plain.
+ */
+export const SKILL_SUGGESTION_PREFIX = SKILL_SUGGESTION_ANCHOR.slice(0, SKILL_SUGGESTION_ANCHOR.indexOf("<name>"));
+
+export interface PendingSkillRequest {
+	name: string;
+	args: string;
+	source: PendingSkillRequestSource;
+	installed: boolean;
+	filePath?: string;
+	marketplaceRef?: string;
+}
+
+/** Tool surface a loaded SKILL.md declares for its own workflow. */
+export interface SkillDeclaredToolPolicy {
+	allowedTools?: ReadonlyArray<string>;
+	disallowedTools?: ReadonlyArray<string>;
+}
+
+export interface PendingSkillToolPolicy {
+	allowedSkillNames: ReadonlyArray<string>;
+	requests: ReadonlyArray<PendingSkillRequest>;
+	loadedSkillNames: Set<string>;
+	/** Declared tool policy per successfully loaded skill, recorded by context(scope=skills). */
+	loadedSkillPolicies: Map<string, SkillDeclaredToolPolicy>;
+}
+
+/**
+ * Tools admitted regardless of any active skill narrowing: context so the
+ * remaining requested skills of the same turn can still load, and ask_user as
+ * the escape hatch the block message points at when a workflow genuinely
+ * needs a tool its skill did not declare.
+ */
+const SKILL_SURFACE_EXEMPT_TOOLS: ReadonlySet<string> = new Set(["context", "ask_user"]);
+
+export interface SkillToolSurfaceViolation {
+	/** Every loaded skill that contributed a declaration to the merged surface. */
+	skills: ReadonlyArray<string>;
+	/** Merged allowed-tools union when allow-narrowing applies; null for a disallow hit. */
+	mergedAllowedTools: ReadonlyArray<string> | null;
+	/** Skills whose disallowed-tools name the tool directly. */
+	disallowedBy: ReadonlyArray<string>;
+}
+
+/**
+ * Evaluate a tool call against the tool surface declared by the skills loaded
+ * so far under `policy`. Narrowing only ever blocks; it never grants anything
+ * the safety net or autonomy mapping would refuse. Merge semantics:
+ *
+ * - Denials win: a tool named in any loaded skill's disallowed-tools is out.
+ * - Allow-narrowing applies only while every loaded skill declares
+ *   allowed-tools; the merged surface is their union. A loaded skill with no
+ *   allowed-tools keeps the full surface for its own workflow, so it lifts
+ *   the allow-narrowing (but not the denials) for the turn.
+ *
+ * Returns null when the call is inside the surface or no narrowing is active.
+ */
+export function evaluateSkillToolSurface(
+	policy: PendingSkillToolPolicy | undefined,
+	tool: string,
+): SkillToolSurfaceViolation | null {
+	if (!policy || policy.loadedSkillPolicies.size === 0) return null;
+	if (SKILL_SURFACE_EXEMPT_TOOLS.has(tool)) return null;
+	const entries = [...policy.loadedSkillPolicies.entries()];
+	const skills = entries.map(([name]) => name);
+	const disallowedBy = entries
+		.filter(([, declared]) => declared.disallowedTools?.includes(tool) === true)
+		.map(([name]) => name);
+	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy };
+	const allowLists = entries.map(([, declared]) => declared.allowedTools);
+	if (allowLists.some((list) => list === undefined || list.length === 0)) return null;
+	const merged = [...new Set(allowLists.flatMap((list) => [...(list ?? [])]))];
+	if (merged.includes(tool)) return null;
+	return { skills, mergedAllowedTools: merged, disallowedBy: [] };
+}
+
+/**
+ * Per-run skill policy for a dispatched worker whose agent recipe declares
+ * skills. The worker may load exactly these skill names; anything else gets
+ * the same deterministic rejection an unrequested skill gets interactively.
+ */
+export function agentSkillToolPolicy(skillNames: ReadonlyArray<string>): PendingSkillToolPolicy | undefined {
+	const allowedSkillNames = [...new Set(skillNames.map((name) => name.trim()).filter((name) => name.length > 0))];
+	if (allowedSkillNames.length === 0) return undefined;
+	return {
+		allowedSkillNames,
+		requests: allowedSkillNames.map((name) => ({ name, args: "", source: "recipe" as const, installed: true })),
+		loadedSkillNames: new Set<string>(),
+		loadedSkillPolicies: new Map<string, SkillDeclaredToolPolicy>(),
+	};
+}
+
+export interface SkillActivation {
+	name: string;
+	filePath: string;
+	hash: string;
+	source: string;
+	/** Precise root provenance, for example extension:user:<id> or codex-project. */
+	sourceOrigin?: string;
+	/** Pinned-manifest comparison verdict; "mismatch" records skill_drift. */
+	drift?: "match" | "mismatch";
+	triggeredBy: SkillActivationTrigger;
+	turnId?: string;
+	/**
+	 * Dispatch run whose worker performed this activation. Absent on
+	 * main-agent activations; set when a dispatch completion folds a worker
+	 * receipt's activations into the session ledger.
+	 */
+	runId?: string;
+}
+
+export interface SkillActivationSource {
+	name: string;
+	filePath: string;
+	hash: string;
+	source: string;
+	sourceOrigin?: string;
+	sourceInfo?: { source?: string };
+}
+
+function trimmedString(value: unknown): string | null {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function skillActivationFromSource(
+	source: SkillActivationSource,
+	triggeredBy: SkillActivationTrigger,
+	turnId?: string,
+): SkillActivation {
+	const sourceOrigin = trimmedString(source.sourceOrigin) ?? trimmedString(source.sourceInfo?.source);
+	return {
+		name: source.name,
+		filePath: source.filePath,
+		hash: source.hash,
+		source: source.source,
+		...(sourceOrigin ? { sourceOrigin } : {}),
+		triggeredBy,
+		...(turnId ? { turnId } : {}),
+	};
+}
+
+export function skillActivationFromToolDetails(details: unknown, turnId?: string): SkillActivation | null {
+	if (!details || typeof details !== "object" || Array.isArray(details)) return null;
+	const record = details as Record<string, unknown>;
+	const name = trimmedString(record.name);
+	const filePath = trimmedString(record.filePath) ?? trimmedString(record.path);
+	const hash = trimmedString(record.hash);
+	const source = trimmedString(record.source);
+	const sourceOrigin = trimmedString(record.sourceOrigin) ?? trimmedString(record.origin);
+	if (!name || !filePath || !hash || !source) return null;
+	const activation = skillActivationFromSource(
+		{ name, filePath, hash, source, ...(sourceOrigin ? { sourceOrigin } : {}) },
+		"tool",
+		turnId,
+	);
+	if (record.drift === "match" || record.drift === "mismatch") activation.drift = record.drift;
+	return activation;
+}
+
+export function isSkillActivation(value: unknown): value is SkillActivation {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.name === "string" &&
+		typeof record.filePath === "string" &&
+		typeof record.hash === "string" &&
+		typeof record.source === "string" &&
+		(record.sourceOrigin === undefined || typeof record.sourceOrigin === "string") &&
+		(record.triggeredBy === "slash-command" || record.triggeredBy === "tool") &&
+		(record.turnId === undefined || typeof record.turnId === "string") &&
+		(record.runId === undefined || typeof record.runId === "string")
+	);
+}

package/src/core/startup-timer.ts

@@ -0,0 +1,37 @@
+/**
+ * Micro-profiler for boot phases. Target budget is ≤800ms to first frame per spec §17.
+ *
+ * Marks double as boot-trace phase markers: each `mark()` forwards to
+ * `traceBoot`, so `CLIO_CODER_TRACE_BOOT=1` streams the same phases live to stderr
+ * (with elapsed-from-process-start) while the in-memory report stays relative
+ * to construction for the `CLIO_CODER_TIMING=1` summary.
+ */
+
+import { traceBoot } from "./boot-trace.js";
+
+type Mark = { name: string; at: number };
+
+export class StartupTimer {
+	private readonly start = performance.now();
+	private readonly marks: Mark[] = [];
+
+	constructor(private readonly trace: (phase: string) => void = traceBoot) {
+		this.trace("boot start");
+	}
+
+	mark(name: string): void {
+		this.marks.push({ name, at: performance.now() - this.start });
+		this.trace(name);
+	}
+
+	snapshot(): { totalMs: number; marks: ReadonlyArray<Mark> } {
+		return { totalMs: performance.now() - this.start, marks: [...this.marks] };
+	}
+
+	report(): string {
+		const snap = this.snapshot();
+		const lines = [`Clio Coder boot total ${snap.totalMs.toFixed(1)}ms`];
+		for (const m of snap.marks) lines.push(`  ${m.at.toFixed(1)}ms  ${m.name}`);
+		return lines.join("\n");
+	}
+}