@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/session-routing.ts

@@ -0,0 +1,339 @@
+/**
+ * Session-owned live routing state.
+ *
+ * Saved settings (settings.yaml) are defaults shared by every Clio process.
+ * Live routing for a running session — active orchestrator target/model/
+ * thinking, the fleet default used by /run, and the Alt+J / Alt+K scope list —
+ * is owned by the process that is running the session. Each process seeds its
+ * routing from saved settings at boot and afterwards reads everything through
+ * an effective view: the shared snapshot (targets, theme, safety, retry, …)
+ * with the session's routing fields overlaid.
+ *
+ * Interactive routing changes update the session state first (immediate
+ * effect in this session) and write through to saved settings so new sessions
+ * inherit them. External writes to settings.yaml — another Clio session, the
+ * CLI, an editor — update the shared snapshot and therefore the defaults, but
+ * never redirect a running session's routing.
+ */
+
+import type { ClioSettings } from "./config.js";
+
+type SessionThinkingLevel = ClioSettings["orchestrator"]["thinkingLevel"];
+
+export interface SessionRoutingTarget {
+	target: string | null;
+	model: string | null;
+	thinkingLevel: SessionThinkingLevel;
+}
+
+export interface SessionRoutingState {
+	orchestrator: SessionRoutingTarget;
+	background: SessionRoutingTarget;
+	workersDefault: SessionRoutingTarget;
+	scope: string[];
+}
+
+/**
+ * Partial routing update. Only the fields present are applied to the session
+ * state and written through to saved settings, so a Shift+Tab in one session
+ * never clobbers a default model another session saved a minute earlier.
+ */
+export interface RoutingPatch {
+	orchestrator?: Partial<SessionRoutingTarget>;
+	background?: Partial<SessionRoutingTarget>;
+	workersDefault?: Partial<SessionRoutingTarget>;
+	scope?: string[];
+}
+
+function targetFrom(source: {
+	target: string | null;
+	model: string | null;
+	thinkingLevel: SessionThinkingLevel;
+}): SessionRoutingTarget {
+	return {
+		target: source.target ?? null,
+		model: source.model ?? null,
+		thinkingLevel: source.thinkingLevel ?? "off",
+	};
+}
+
+export function seedSessionRouting(saved: Readonly<ClioSettings>): SessionRoutingState {
+	return {
+		orchestrator: targetFrom(saved.orchestrator),
+		background: targetFrom(saved.background),
+		workersDefault: targetFrom(saved.workers.default),
+		scope: [...(saved.scope ?? [])],
+	};
+}
+
+/**
+ * Effective settings view: the shared snapshot with the session's routing
+ * overlaid. Everything that resolves a chat or dispatch target, and every UI
+ * surface that displays routing, must read through this view.
+ */
+export function applySessionRouting(saved: Readonly<ClioSettings>, routing: SessionRoutingState): ClioSettings {
+	const view = structuredClone(saved) as ClioSettings;
+	view.orchestrator.target = routing.orchestrator.target;
+	view.orchestrator.model = routing.orchestrator.model;
+	view.orchestrator.thinkingLevel = routing.orchestrator.thinkingLevel;
+	view.background.target = routing.background.target;
+	view.background.model = routing.background.model;
+	view.background.thinkingLevel = routing.background.thinkingLevel;
+	view.workers.default.target = routing.workersDefault.target;
+	view.workers.default.model = routing.workersDefault.model;
+	view.workers.default.thinkingLevel = routing.workersDefault.thinkingLevel;
+	view.scope = [...routing.scope];
+	return view;
+}
+
+export function applyRoutingPatch(routing: SessionRoutingState, patch: RoutingPatch): void {
+	if (patch.orchestrator) Object.assign(routing.orchestrator, patch.orchestrator);
+	if (patch.background) Object.assign(routing.background, patch.background);
+	if (patch.workersDefault) Object.assign(routing.workersDefault, patch.workersDefault);
+	if (patch.scope) routing.scope = [...patch.scope];
+}
+
+/**
+ * Session-local overrides for the non-routing settings surface (autonomy,
+ * budget, compaction, retry, …). Routing has its own dedicated state above;
+ * everything else a session changes "for this session only" lives here as a
+ * sparse map of dotted config paths to values. The /settings overlay edits one
+ * leaf at a time and every editable id equals its config path, so the keys are
+ * always object paths (never array indices). A value of `undefined` represents
+ * "delete this optional leaf in the effective view" (e.g. clearing
+ * compaction.model).
+ */
+export type SessionOverrides = Map<string, unknown>;
+
+/** True for the dotted paths owned by the session routing state (never overrides). */
+export function isRoutingPath(path: string): boolean {
+	return (
+		path === "scope" ||
+		path.startsWith("orchestrator.") ||
+		path.startsWith("background.") ||
+		path.startsWith("workers.default.")
+	);
+}
+
+/** Read a leaf from a settings blob by dotted object path. Missing ⇒ undefined. */
+export function getAtPath(source: Readonly<ClioSettings>, path: string): unknown {
+	let cursor: unknown = source;
+	for (const key of path.split(".")) {
+		if (cursor === null || typeof cursor !== "object") return undefined;
+		cursor = (cursor as Record<string, unknown>)[key];
+	}
+	return cursor;
+}
+
+/**
+ * Set (or, when `value === undefined`, delete) a leaf on a settings blob by
+ * dotted object path. Intermediate objects must already exist — every editable
+ * id targets a leaf under a known schema object, so this never has to create
+ * containers.
+ */
+export function setAtPath(target: ClioSettings, path: string, value: unknown): void {
+	const keys = path.split(".");
+	const last = keys.pop();
+	if (last === undefined) return;
+	let cursor: Record<string, unknown> = target as unknown as Record<string, unknown>;
+	for (const key of keys) {
+		const nextCursor = cursor[key];
+		if (nextCursor === null || typeof nextCursor !== "object") return;
+		cursor = nextCursor as Record<string, unknown>;
+	}
+	if (value === undefined) delete cursor[last];
+	else cursor[last] = value;
+}
+
+/**
+ * Effective non-routing view: the shared snapshot with the session's overrides
+ * applied. Returns the base untouched when there are no overrides so the common
+ * (no session-only edits) path stays allocation-free.
+ */
+export function applyOverrides(base: Readonly<ClioSettings>, overrides: SessionOverrides): ClioSettings {
+	if (overrides.size === 0) return base as ClioSettings;
+	const view = structuredClone(base) as ClioSettings;
+	for (const [path, value] of overrides) setAtPath(view, path, value);
+	return view;
+}
+
+/** Write-through of a routing patch onto a (cloned) saved-settings blob. */
+export function mergeRoutingPatchIntoSettings(settings: ClioSettings, patch: RoutingPatch): void {
+	if (patch.orchestrator) Object.assign(settings.orchestrator, patch.orchestrator);
+	if (patch.background) Object.assign(settings.background, patch.background);
+	if (patch.workersDefault) Object.assign(settings.workers.default, patch.workersDefault);
+	if (patch.scope) settings.scope = [...patch.scope];
+}
+
+/**
+ * Build the routing patch for a single /settings edit, keyed by its config-path
+ * id and read from the supplied (already-changed) settings blob. Used by the
+ * scoped /settings commit instead of a live diff: a session-only apply moves the
+ * routing state first, which would zero out a subsequent diff and make a global
+ * save no-op. Only the touched fields are included, so a global save never
+ * rewrites routing fields the operator did not change. Changing a target also
+ * carries its rebased model. Returns null for non-routing ids.
+ */
+export function routingPatchForId(path: string, settings: Readonly<ClioSettings>): RoutingPatch | null {
+	switch (path) {
+		case "orchestrator.target":
+			return { orchestrator: { target: settings.orchestrator.target, model: settings.orchestrator.model } };
+		case "orchestrator.model":
+			return { orchestrator: { model: settings.orchestrator.model } };
+		case "orchestrator.thinkingLevel":
+			return { orchestrator: { thinkingLevel: settings.orchestrator.thinkingLevel } };
+		case "background.target":
+			return { background: { target: settings.background.target, model: settings.background.model } };
+		case "background.model":
+			return { background: { model: settings.background.model } };
+		case "background.thinkingLevel":
+			return { background: { thinkingLevel: settings.background.thinkingLevel } };
+		case "workers.default.target":
+			return { workersDefault: { target: settings.workers.default.target, model: settings.workers.default.model } };
+		case "workers.default.model":
+			return { workersDefault: { model: settings.workers.default.model } };
+		case "workers.default.thinkingLevel":
+			return { workersDefault: { thinkingLevel: settings.workers.default.thinkingLevel } };
+		case "scope":
+			return { scope: [...(settings.scope ?? [])] };
+		default:
+			return null;
+	}
+}
+
+function diffTarget(
+	prev: { target: string | null; model: string | null; thinkingLevel: SessionThinkingLevel },
+	next: { target: string | null; model: string | null; thinkingLevel: SessionThinkingLevel },
+): Partial<SessionRoutingTarget> | null {
+	const out: Partial<SessionRoutingTarget> = {};
+	if ((prev.target ?? null) !== (next.target ?? null)) out.target = next.target ?? null;
+	if ((prev.model ?? null) !== (next.model ?? null)) out.model = next.model ?? null;
+	if ((prev.thinkingLevel ?? "off") !== (next.thinkingLevel ?? "off")) out.thinkingLevel = next.thinkingLevel ?? "off";
+	return Object.keys(out).length > 0 ? out : null;
+}
+
+function scopeEquals(a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolean {
+	return a.length === b.length && a.every((entry, idx) => entry === b[idx]);
+}
+
+/**
+ * Field-level diff of the routing surface between two settings blobs. Used to
+ * absorb routing edits made through whole-settings writers (the /settings
+ * overlay) into the session state without letting unrelated edits persist the
+ * session's routing as new defaults.
+ */
+export function diffRouting(prev: Readonly<ClioSettings>, next: Readonly<ClioSettings>): RoutingPatch | null {
+	const patch: RoutingPatch = {};
+	const orchestrator = diffTarget(prev.orchestrator, next.orchestrator);
+	if (orchestrator) patch.orchestrator = orchestrator;
+	const background = diffTarget(prev.background, next.background);
+	if (background) patch.background = background;
+	const workersDefault = diffTarget(prev.workers.default, next.workers.default);
+	if (workersDefault) patch.workersDefault = workersDefault;
+	if (!scopeEquals(prev.scope ?? [], next.scope ?? [])) patch.scope = [...(next.scope ?? [])];
+	return Object.keys(patch).length > 0 ? patch : null;
+}
+
+/**
+ * Replace `target`'s routing fields with `source`'s. Applied before
+ * persisting a whole-settings blob that was derived from the effective view,
+ * so a /settings edit to, say, retry.maxRetries does not silently rewrite the
+ * saved routing defaults with this session's live routing.
+ */
+export function restoreRoutingFields(target: ClioSettings, source: Readonly<ClioSettings>): void {
+	target.orchestrator.target = source.orchestrator.target;
+	target.orchestrator.model = source.orchestrator.model;
+	target.orchestrator.thinkingLevel = source.orchestrator.thinkingLevel;
+	target.background.target = source.background.target;
+	target.background.model = source.background.model;
+	target.background.thinkingLevel = source.background.thinkingLevel;
+	target.workers.default.target = source.workers.default.target;
+	target.workers.default.model = source.workers.default.model;
+	target.workers.default.thinkingLevel = source.workers.default.thinkingLevel;
+	target.scope = [...(source.scope ?? [])];
+}
+
+const ROUTING_FIELD_LABELS: ReadonlyArray<{
+	field: string;
+	label: string;
+	read: (settings: Readonly<ClioSettings>) => unknown;
+}> = [
+	{ field: "orchestrator.target", label: "chat target", read: (s) => s.orchestrator.target ?? null },
+	{ field: "orchestrator.model", label: "chat model", read: (s) => s.orchestrator.model ?? null },
+	{ field: "orchestrator.thinkingLevel", label: "chat thinking", read: (s) => s.orchestrator.thinkingLevel ?? "off" },
+	{ field: "background.target", label: "background target", read: (s) => s.background.target ?? null },
+	{ field: "background.model", label: "background model", read: (s) => s.background.model ?? null },
+	{ field: "background.thinkingLevel", label: "background thinking", read: (s) => s.background.thinkingLevel ?? "off" },
+	{ field: "workers.default.target", label: "fleet target", read: (s) => s.workers.default.target ?? null },
+	{ field: "workers.default.model", label: "fleet model", read: (s) => s.workers.default.model ?? null },
+	{
+		field: "workers.default.thinkingLevel",
+		label: "fleet thinking",
+		read: (s) => s.workers.default.thinkingLevel ?? "off",
+	},
+	{ field: "scope", label: "Alt+J/Alt+K scope", read: (s) => (s.scope ?? []).join(",") },
+];
+
+/**
+ * Given the changed paths from a settings reload, return the human labels of
+ * routing fields whose saved value now differs from the session's effective
+ * routing. A session's own write-through produces no divergence (the changed
+ * fields carry the session's values), so a non-empty result means another
+ * writer — a second session, the CLI, or a manual edit — moved the defaults
+ * out from under this session.
+ */
+export function externalRoutingDivergence(
+	changedPaths: ReadonlyArray<string>,
+	saved: Readonly<ClioSettings>,
+	effective: Readonly<ClioSettings>,
+): string[] {
+	const labels: string[] = [];
+	for (const entry of ROUTING_FIELD_LABELS) {
+		const touched = changedPaths.some((path) => path === entry.field || path.startsWith(`${entry.field}.`));
+		if (!touched) continue;
+		if (entry.read(saved) !== entry.read(effective)) labels.push(entry.label);
+	}
+	return labels;
+}
+
+export interface RoutingChangeNotice {
+	kind: "external-divergence" | "active-target-removed";
+	level: "info" | "warning";
+	text: string;
+}
+
+/**
+ * The two advisory notices a running session emits when an external writer
+ * moves settings.yaml underneath it. One helper feeds every surface — the TUI
+ * notification center and the ACP session ledger — so the wording cannot
+ * drift. `commandHints` appends the interactive remedies (/settings, /model,
+ * Alt+L), which only make sense where a user can type slash commands.
+ */
+export function routingChangeNotices(
+	changedPaths: ReadonlyArray<string>,
+	saved: Readonly<ClioSettings>,
+	effective: Readonly<ClioSettings>,
+	options?: { commandHints?: boolean },
+): RoutingChangeNotice[] {
+	const notices: RoutingChangeNotice[] = [];
+	const diverged = externalRoutingDivergence(changedPaths, saved, effective);
+	if (diverged.length > 0) {
+		const hint = options?.commandHints ? " Change live routing via /settings or /model." : "";
+		notices.push({
+			kind: "external-divergence",
+			level: "info",
+			text: `settings.yaml changed (${diverged.join(", ")}). This session keeps its routing; new sessions use the saved defaults.${hint}`,
+		});
+	}
+	const activeTarget = effective.orchestrator.target;
+	const targetsTouched = changedPaths.some((path) => path === "targets" || path.startsWith("targets."));
+	if (activeTarget && targetsTouched && !saved.targets.some((entry) => entry.id === activeTarget)) {
+		const hint = options?.commandHints ? " (/model)" : "";
+		notices.push({
+			kind: "active-target-removed",
+			level: "warning",
+			text: `active target '${activeTarget}' was removed from settings.yaml; chat turns will fail until you pick a new target${hint}.`,
+		});
+	}
+	return notices;
+}

package/src/core/settings-layers.ts

@@ -0,0 +1,220 @@
+/**
+ * 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 { type ClioSettings, settingsPath, validateSettings } from "./config.js";
+
+export type SettingsOrigin = "built-in" | "user" | "project" | "project.local" | "cli";
+
+export interface SettingsLayerIssue {
+	origin: SettingsOrigin;
+	path: string;
+	message: string;
+}
+
+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[];
+}
+
+// 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);
+}
+
+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 parsed: unknown;
+	try {
+		parsed = parseYaml(readFileSync(path, "utf8"));
+	} catch (err) {
+		issues.push({ origin, path, message: `invalid YAML: ${err instanceof Error ? err.message : String(err)}` });
+		return { origin, path, blob: undefined };
+	}
+	if (parsed === null || parsed === undefined) return { origin, path, blob: {} };
+	if (!isRecord(parsed)) {
+		issues.push({ origin, path, 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;
+}
+
+/**
+ * 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 projectFile = join(cwd, ".clio-coder", "settings.yaml");
+	const localFile = join(cwd, ".clio-coder", "settings.local.yaml");
+
+	const user = readRawLayer("user", userFile, issues);
+	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>),
+	};
+
+	const { merged, sources } = mergeLayersWithSources([user, project, 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,
+		issues,
+		layers: [
+			{ origin: "built-in", path: "(defaults)", present: true },
+			{ origin: "user", path: userFile, present: user.blob !== undefined },
+			{ origin: "project", path: projectFile, present: projectRaw.blob !== undefined },
+			{ origin: "project.local", path: localFile, present: localRaw.blob !== undefined },
+		],
+	};
+}
+
+/**
+ * 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, "'\\''")}'`;
+}