@iowarp/clio-coder 0.3.0 → 0.3.1

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() {
+		traceBoot("boot start");
+	}
+
+	mark(name: string): void {
+		this.marks.push({ name, at: performance.now() - this.start });
+		traceBoot(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");
+	}
+}

package/src/core/state-file-lock.ts

@@ -0,0 +1,207 @@
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, utimesSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import { processAlive, processBirthToken } from "./process-identity.js";
+
+/**
+ * The one cross-process advisory file lock. Every durable lock in the tree runs
+ * through it (settings.yaml, the dispatch admission state file,
+ * credentials.yaml, residency mutations) so there is a single staleness policy
+ * instead of four that disagreed by a factor of 26.
+ *
+ * The lock is keyed by target path (`<target>.lock`) and records the owner's
+ * host, pid and birth token. A holder is presumed gone only when its pid is
+ * gone on this host; a record from another host is never adjudicated here. The
+ * age of the lockfile decides only for a record whose owner cannot be read, so
+ * staleness is a backstop rather than a cap on how long a critical section may
+ * legitimately take: the settings lock used to steal itself back from a healthy
+ * writer after five seconds. Async holders additionally refresh the lockfile mtime while
+ * they work, so even the backstop does not fire under a live holder. The sync
+ * path blocks the event loop by construction and cannot run that timer; pid
+ * liveness is what protects it.
+ */
+
+/** Consulted only when the owner cannot be identified. */
+const STALE_LOCK_MS = 30_000;
+/** Well under STALE_LOCK_MS, so a slow holder never reads as an abandoned one. */
+const REFRESH_LOCK_MS = 5_000;
+/**
+ * Default acquisition budget. Deliberately under DEFAULT_CAPACITY_LEASE_TTL_MS:
+ * the sync path blocks the event loop, so a process waiting here also stalls its
+ * own lease heartbeat, and a wait longer than a lease lives would let a live
+ * holder's lease expire under it. capacity-lease.ts asserts the relation.
+ */
+export const FILE_LOCK_ACQUIRE_TIMEOUT_MS = 20_000;
+
+export interface StateFileLockOptions {
+	/** Acquisition budget. Default `FILE_LOCK_ACQUIRE_TIMEOUT_MS`. */
+	timeoutMs?: number;
+	/**
+	 * `run-unlocked` runs `fn` anyway when the lock cannot be taken. Residency
+	 * mutations need it: serializing them is an optimization and must never fail
+	 * or stall a turn. Everything else fails closed.
+	 */
+	onAcquireFailure?: "throw" | "run-unlocked";
+}
+
+interface LockOwner {
+	/** Null on a record written before the field existed; read as this host. */
+	host: string | null;
+	pid: number;
+	birthToken: string | null;
+}
+
+function readLockOwner(lockPath: string): LockOwner | null {
+	try {
+		const raw = readFileSync(lockPath, "utf8").trim();
+		const record = raw.startsWith("{") ? (JSON.parse(raw) as Record<string, unknown>) : { pid: Number.parseInt(raw, 10) };
+		const { host, pid, birthToken } = record;
+		if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return null;
+		return {
+			host: typeof host === "string" ? host : null,
+			pid,
+			birthToken: typeof birthToken === "string" ? birthToken : null,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Mirrors compete-worktrees' ownerIsAlive: foreign hosts are never adjudicated, a null token cannot rule out pid reuse. */
+function ownerIsAlive(owner: LockOwner): boolean {
+	if (owner.host !== null && owner.host !== hostname()) return true;
+	if (!processAlive(owner.pid)) return false;
+	if (owner.birthToken === null) return true;
+	const current = processBirthToken(owner.pid);
+	return current === null || current === owner.birthToken;
+}
+
+function lockfileAgeMs(lockPath: string): number | null {
+	try {
+		return Date.now() - statSync(lockPath).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+
+/** True once the lock is ours. Steals only from an owner that is provably gone. */
+function tryAcquire(lockPath: string): boolean {
+	try {
+		const fd = openSync(lockPath, "wx", 0o600);
+		try {
+			writeSync(
+				fd,
+				`${JSON.stringify({ host: hostname(), pid: process.pid, birthToken: processBirthToken(), at: new Date().toISOString() })}\n`,
+			);
+		} finally {
+			closeSync(fd);
+		}
+		return true;
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+	}
+	const owner = readLockOwner(lockPath);
+	const ageMs = lockfileAgeMs(lockPath);
+	const abandoned = owner !== null ? !ownerIsAlive(owner) : ageMs !== null && ageMs > STALE_LOCK_MS;
+	if (abandoned) {
+		try {
+			unlinkSync(lockPath);
+		} catch {
+			// Another waiter reclaimed it first; the next attempt races normally.
+		}
+	}
+	return false;
+}
+
+function timeoutError(lockPath: string, timeoutMs: number): Error {
+	return new Error(
+		`timed out after ${timeoutMs}ms waiting for ${lockPath} (owner pid=${readLockOwner(lockPath)?.pid ?? "?"}); delete it if no other clio process is running`,
+	);
+}
+
+function backoffMs(attempt: number): number {
+	return Math.min(100, 5 * 2 ** Math.min(attempt, 5));
+}
+
+function release(lockPath: string): void {
+	// Only unlink a lock we still own. If ours was reclaimed as abandoned and a
+	// sibling now holds a fresh one, deleting here would open their section.
+	const owner = readLockOwner(lockPath);
+	if (owner?.pid !== process.pid || (owner.host !== null && owner.host !== hostname())) return;
+	try {
+		unlinkSync(lockPath);
+	} catch {
+		// Already gone; fine.
+	}
+}
+
+/**
+ * Keep a held lock's mtime current so the staleness backstop cannot fire under
+ * a live holder. Only the async path can do this; see the module comment.
+ */
+function startRefresh(lockPath: string): () => void {
+	const timer = setInterval(() => {
+		const at = new Date();
+		try {
+			utimesSync(lockPath, at, at);
+		} catch {
+			// Released or stolen; `release` re-checks ownership either way.
+		}
+	}, REFRESH_LOCK_MS);
+	timer.unref();
+	return () => clearInterval(timer);
+}
+
+/** Synchronous variant for admission planners whose host API cannot yield. */
+export function withStateFileLockSync<T>(targetPath: string, fn: () => T, options: StateFileLockOptions = {}): T {
+	const lockPath = `${targetPath}.lock`;
+	const timeoutMs = options.timeoutMs ?? FILE_LOCK_ACQUIRE_TIMEOUT_MS;
+	let held = false;
+	try {
+		mkdirSync(dirname(lockPath), { recursive: true });
+		const deadlineMs = Date.now() + timeoutMs;
+		for (let attempt = 1; !tryAcquire(lockPath); attempt += 1) {
+			if (Date.now() > deadlineMs) throw timeoutError(lockPath, timeoutMs);
+			// Atomics.wait rather than a timer: the callers of this variant are
+			// inside host APIs that cannot yield.
+			Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoffMs(attempt));
+		}
+		held = true;
+	} catch (err) {
+		if (options.onAcquireFailure !== "run-unlocked") throw err;
+	}
+	try {
+		return fn();
+	} finally {
+		if (held) release(lockPath);
+	}
+}
+
+export async function withStateFileLock<T>(
+	targetPath: string,
+	fn: () => T | Promise<T>,
+	options: StateFileLockOptions = {},
+): Promise<T> {
+	const lockPath = `${targetPath}.lock`;
+	const timeoutMs = options.timeoutMs ?? FILE_LOCK_ACQUIRE_TIMEOUT_MS;
+	let held = false;
+	try {
+		mkdirSync(dirname(lockPath), { recursive: true });
+		const deadlineMs = Date.now() + timeoutMs;
+		for (let attempt = 1; !tryAcquire(lockPath); attempt += 1) {
+			if (Date.now() > deadlineMs) throw timeoutError(lockPath, timeoutMs);
+			const base = backoffMs(attempt);
+			await new Promise((resolve) => setTimeout(resolve, base + Math.floor(Math.random() * base)));
+		}
+		held = true;
+	} catch (err) {
+		if (options.onAcquireFailure !== "run-unlocked") throw err;
+	}
+	const stopRefresh = held ? startRefresh(lockPath) : null;
+	try {
+		return await fn();
+	} finally {
+		stopRefresh?.();
+		if (held) release(lockPath);
+	}
+}

package/src/core/termination.ts

@@ -0,0 +1,202 @@
+/**
+ * Shutdown coordinator implementing the four-phase sequence from spec §17:
+ *   DRAIN     stop accepting new input / dispatch
+ *   TERMINATE kill active workers (wired in Phase 7)
+ *   PERSIST   atomic writes of domain state
+ *   EXIT      tear down TUI and process.exit
+ *
+ * Each registered hook runs under a per-hook timeout so a single slow or
+ * hanging hook cannot block the TUI from exiting. The cap is 500ms by
+ * default and can be overridden via CLIO_CODER_SHUTDOWN_HOOK_MS for tests.
+ * Timed-out hooks are logged and shutdown continues to the next hook.
+ */
+
+import { BusChannels } from "./bus-events.js";
+import { getSharedBus } from "./shared-bus.js";
+
+export type TerminationPhase = "idle" | "draining" | "terminating" | "persisting" | "exiting";
+
+type Hook = () => void | Promise<void>;
+
+/** Wall-clock budget per hook and per domain.stop() call. */
+export const DEFAULT_SHUTDOWN_HOOK_MS = 500;
+
+const SIGNAL_EXIT_CODES: Partial<Record<NodeJS.Signals, number>> = {
+	SIGHUP: 129,
+	SIGINT: 130,
+	SIGTERM: 143,
+};
+
+export function resolveShutdownHookBudgetMs(): number {
+	const raw = process.env.CLIO_CODER_SHUTDOWN_HOOK_MS;
+	if (raw === undefined) return DEFAULT_SHUTDOWN_HOOK_MS;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_SHUTDOWN_HOOK_MS;
+	return parsed;
+}
+
+/**
+ * Run `op` with a wall-clock cap. Resolves true when `op` completes within
+ * the budget, false when the cap fires first. Errors from `op` are swallowed
+ * and reported via `onError` so a rejecting hook cannot propagate past the
+ * shutdown coordinator.
+ */
+export async function runWithBudget(
+	op: () => void | Promise<void>,
+	budgetMs: number,
+	onError?: (err: unknown) => void,
+): Promise<boolean> {
+	let timer: NodeJS.Timeout | undefined;
+	const timeout = new Promise<"timeout">((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), budgetMs);
+	});
+	try {
+		const done = Promise.resolve()
+			.then(() => op())
+			.then(() => "done" as const)
+			.catch((err) => {
+				onError?.(err);
+				return "done" as const;
+			});
+		const outcome = await Promise.race([done, timeout]);
+		return outcome === "done";
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+class TerminationCoordinator {
+	private phase: TerminationPhase = "idle";
+	private readonly drainHooks: Hook[] = [];
+	private readonly terminateHooks: Hook[] = [];
+	private readonly persistHooks: Hook[] = [];
+	private exitCode = 0;
+	private started = false;
+	private signalHandler: ((signal: NodeJS.Signals) => void) | null = null;
+
+	getPhase(): TerminationPhase {
+		return this.phase;
+	}
+
+	/**
+	 * The process exit code this shutdown will use. Set before any hook runs,
+	 * so a hook sealing terminal accounting records the same status the process
+	 * reports (130 for SIGINT, 143 for SIGTERM).
+	 */
+	getExitCode(): number {
+		return this.exitCode;
+	}
+
+	onDrain(hook: Hook): void {
+		this.drainHooks.push(hook);
+	}
+	onTerminate(hook: Hook): void {
+		this.terminateHooks.push(hook);
+	}
+	onPersist(hook: Hook): void {
+		this.persistHooks.push(hook);
+	}
+
+	async shutdown(code = 0): Promise<void> {
+		if (this.started) return;
+		this.started = true;
+		this.exitCode = code;
+		const bus = getSharedBus();
+		const debug = process.env.CLIO_CODER_DEBUG_SHUTDOWN === "1";
+		const budgetMs = resolveShutdownHookBudgetMs();
+		const mark = debug ? process.hrtime.bigint() : 0n;
+		const log = (msg: string): void => {
+			if (!debug) return;
+			const ms = Number(process.hrtime.bigint() - mark) / 1e6;
+			process.stderr.write(`[clio:shutdown] +${ms.toFixed(1)}ms ${msg}\n`);
+		};
+
+		this.phase = "draining";
+		bus.emit(BusChannels.ShutdownRequested, { phase: this.phase });
+		log("drain:start");
+		await this.runHooks(this.drainHooks, "drain", budgetMs, log);
+		log("drain:end");
+		bus.emit(BusChannels.ShutdownDrained, {});
+
+		this.phase = "terminating";
+		log("terminate:start");
+		await this.runHooks(this.terminateHooks, "terminate", budgetMs, log);
+		log("terminate:end");
+		bus.emit(BusChannels.ShutdownTerminated, {});
+
+		this.phase = "persisting";
+		log("persist:start");
+		await this.runHooks(this.persistHooks, "persist", budgetMs, log);
+		log("persist:end");
+		bus.emit(BusChannels.ShutdownPersisted, {});
+
+		this.phase = "exiting";
+		bus.emit(BusChannels.SessionEnd, { exitCode: this.exitCode });
+		log("process.exit");
+		process.exit(this.exitCode);
+	}
+
+	private async runHooks(hooks: Hook[], phase: string, budgetMs: number, log: (msg: string) => void): Promise<void> {
+		for (let i = 0; i < hooks.length; i++) {
+			const hook = hooks[i];
+			if (!hook) continue;
+			const t0 = process.hrtime.bigint();
+			const completed = await runWithBudget(hook, budgetMs, (err) => {
+				console.error("[clio:termination] hook failed:", err);
+			});
+			const dt = Number(process.hrtime.bigint() - t0) / 1e6;
+			if (!completed) {
+				process.stderr.write(
+					`[clio:termination] ${phase}[${i}] exceeded ${budgetMs}ms budget; abandoning and continuing shutdown\n`,
+				);
+			}
+			log(`  ${phase}[${i}] ${dt.toFixed(1)}ms${completed ? "" : " (timed out)"}`);
+		}
+	}
+
+	/**
+	 * SIGHUP is here for the same reason as SIGTERM. Without a listener Node
+	 * takes its default action and the process dies with no shutdown at all,
+	 * which on a TUI session means the terminal is never given back. Exit codes
+	 * follow the 128+signal convention.
+	 */
+	installSignalHandlers(): void {
+		if (this.signalHandler) return;
+		const handler = (signal: NodeJS.Signals): void => {
+			process.stderr.write(`\nClio Coder: received ${signal}, shutting down...\n`);
+			void this.shutdown(SIGNAL_EXIT_CODES[signal] ?? 143);
+		};
+		this.signalHandler = handler;
+		process.once("SIGINT", handler);
+		process.once("SIGTERM", handler);
+		process.once("SIGHUP", handler);
+	}
+
+	/**
+	 * Hand SIGINT to a foreground owner and return the call that takes it back.
+	 *
+	 * Boot arms this coordinator before any interactive surface exists, and Node
+	 * runs signal listeners in registration order, so a TUI that merely added its
+	 * own listener would lose every first press to a shutdown already underway.
+	 * One owner holds the interrupt at a time and the transfer is explicit.
+	 * SIGTERM is not part of the handover; it is never an interactive gesture.
+	 */
+	releaseInterruptOwnership(): () => void {
+		const handler = this.signalHandler;
+		if (!handler) return () => {};
+		process.off("SIGINT", handler);
+		let restored = false;
+		return () => {
+			if (restored) return;
+			restored = true;
+			process.once("SIGINT", handler);
+		};
+	}
+}
+
+let coordinator: TerminationCoordinator | null = null;
+
+export function getTerminationCoordinator(): TerminationCoordinator {
+	if (!coordinator) coordinator = new TerminationCoordinator();
+	return coordinator;
+}

package/src/core/timers.ts

@@ -0,0 +1,38 @@
+/** Largest delay Node can schedule without overflowing to an approximately 1 ms timer. */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Normalize optional/disable-capable timer inputs. Nonpositive and NaN values
+ * disable the timer; oversized and infinite values cap at Node's real limit.
+ */
+export function clampTimerDelayMs(value: number): number {
+	if (Number.isNaN(value) || value <= 0) return 0;
+	return value >= MAX_TIMER_DELAY_MS ? MAX_TIMER_DELAY_MS : Math.floor(value);
+}
+
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+let negativeDurations = 0;
+
+/**
+ * Elapsed between two reads of the same clock, signed.
+ *
+ * A negative result means the clock moved backwards between the two reads —
+ * an NTP correction, a resume, or a duration derived across two hosts — and it
+ * is a bug in the caller, not a value to be silently swallowed. Clamping with
+ * `Math.max(0, …)` hides that, so the clamp belongs at the render boundary and
+ * nothing else. Every occurrence is counted; nothing is written to stderr,
+ * because the TUI owns that stream and this sits on hot measurement paths.
+ */
+export function rawDurationMs(start: number, end: number): number {
+	const elapsed = end - start;
+	if (elapsed < 0) negativeDurations += 1;
+	return elapsed;
+}
+
+/** How many negative durations this process has produced since it started. */
+export function negativeDurationCount(): number {
+	return negativeDurations;
+}