@iowarp/clio-coder 0.4.0 → 0.4.1

package/src/core/domain-loader.ts

@@ -95,7 +95,7 @@ export async function loadDomains(
 			// render the failure, so the structured line must land first.
 			const message = error instanceof Error ? error.message : String(error);
 			(options.diagnostic ?? ((text: string) => process.stderr.write(text)))(
-				`[clio:domain] load failed: ${name}: ${message}\n`,
+				`[clio-coder:domain] load failed: ${name}: ${message}\n`,
 			);
 			throw new DomainLoadError(name, error);
 		}
@@ -111,15 +111,17 @@ export async function loadDomains(
 			const t0 = debug ? process.hrtime.bigint() : 0n;
 			const completed = await runWithBudget(stopFn, budgetMs, (err) => {
 				const message = err instanceof Error ? err.message : String(err);
-				writeShutdownNotice(`[clio:domain-loader] ${name}.stop() failed: ${message}`);
+				writeShutdownNotice(`[clio-coder:domain-loader] ${name}.stop() failed: ${message}`);
 				if (debug && err instanceof Error && err.stack) process.stderr.write(`${err.stack}\n`);
 			});
 			if (!completed) {
-				writeShutdownNotice(`[clio:domain-loader] ${name}.stop() exceeded ${budgetMs}ms budget; abandoning`);
+				writeShutdownNotice(`[clio-coder:domain-loader] ${name}.stop() exceeded ${budgetMs}ms budget; abandoning`);
 			}
 			if (debug) {
 				const dt = Number(process.hrtime.bigint() - t0) / 1e6;
-				process.stderr.write(`[clio:shutdown]   domain.${name} ${dt.toFixed(1)}ms${completed ? "" : " (timed out)"}\n`);
+				process.stderr.write(
+					`[clio-coder:shutdown]   domain.${name} ${dt.toFixed(1)}ms${completed ? "" : " (timed out)"}\n`,
+				);
 			}
 		}
 	};

package/src/core/event-bus.ts

@@ -40,7 +40,7 @@ type StoredListener = (payload: never) => void | Promise<void>;
 
 function reportListenerError(channel: string, error: unknown): void {
 	const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
-	console.error(`[clio:event-bus] Listener crashed on ${channel}: ${message}`);
+	console.error(`[clio-coder:event-bus] Listener crashed on ${channel}: ${message}`);
 }
 
 export function createSafeEventBus(): SafeEventBus {

package/src/core/file-references.ts

@@ -25,9 +25,70 @@ export interface FileReferenceOptions {
 	autoResizeImages?: boolean;
 }
 
-const FILE_REF = /(^|\s)@(\S+)/g;
 const DEFAULT_IMAGE_MAX_BASE64_BYTES = 4.5 * 1024 * 1024;
 
+interface InlineFileReference {
+	start: number;
+	end: number;
+	raw: string;
+	fileArg: string;
+	quoted: boolean;
+}
+
+function decodeQuotedFileArg(input: string, start: number, quote: '"' | "'"): { value: string; end: number } | null {
+	let value = "";
+	let escaped = false;
+	for (let index = start; index < input.length; index += 1) {
+		const character = input[index] ?? "";
+		if (escaped) {
+			value += character;
+			escaped = false;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (character === quote) return { value, end: index + 1 };
+		value += character;
+	}
+	return null;
+}
+
+/** Scanner shared by sync and async expansion; quoted references may contain spaces. */
+function inlineFileReferences(input: string): InlineFileReference[] {
+	const references: InlineFileReference[] = [];
+	for (let start = 0; start < input.length; start += 1) {
+		if (input[start] !== "@" || (start > 0 && !/\s/u.test(input[start - 1] ?? ""))) continue;
+		const next = input[start + 1];
+		if (next === '"' || next === "'") {
+			const decoded = decodeQuotedFileArg(input, start + 2, next);
+			if (!decoded || decoded.value.length === 0) continue;
+			references.push({
+				start,
+				end: decoded.end,
+				raw: input.slice(start, decoded.end),
+				fileArg: decoded.value,
+				quoted: true,
+			});
+			start = decoded.end - 1;
+			continue;
+		}
+		let end = start + 1;
+		while (end < input.length && !/\s/u.test(input[end] ?? "")) end += 1;
+		if (end === start + 1) continue;
+		references.push({
+			start,
+			end,
+			raw: input.slice(start, end),
+			fileArg: input.slice(start + 1, end),
+			quoted: false,
+		});
+		start = end - 1;
+	}
+	return references;
+}
+
 function renderTextFile(filePath: string, content: string): string {
 	return `<file name="${filePath}">\n${content}\n</file>\n`;
 }
@@ -64,42 +125,6 @@ function detectSupportedImageMimeType(bytes: Buffer): string | null {
 	return null;
 }
 
-function readFileReference(fileArg: string, options: FileReferenceOptions): FileReferenceResult {
-	const filePath = expandConfigPath(fileArg, options.cwd === undefined ? undefined : { cwd: options.cwd });
-	if (!existsSync(filePath)) {
-		if (options.missing === "leave") return result(`@${fileArg}`);
-		return result("", [{ type: "error", message: `file not found: ${filePath}`, path: filePath }]);
-	}
-	let stat: ReturnType<typeof statSync>;
-	try {
-		stat = statSync(filePath);
-	} catch (err) {
-		const reason = err instanceof Error ? err.message : String(err);
-		return result("", [{ type: "error", message: `file could not be stat'ed: ${reason}`, path: filePath }]);
-	}
-	if (!stat.isFile()) {
-		return result("", [{ type: "error", message: `not a file: ${filePath}`, path: filePath }]);
-	}
-	if (stat.size === 0) return result("", [], [], [filePath]);
-	try {
-		const bytes = readFileSync(filePath);
-		const imageMimeType = detectSupportedImageMimeType(bytes);
-		if (imageMimeType) {
-			if (options.includeImages !== true) return result(`@${fileArg}`);
-			return result(
-				renderImageFile(filePath),
-				[],
-				[{ type: "image", mimeType: imageMimeType, data: bytes.toString("base64") }],
-				[filePath],
-			);
-		}
-		return result(renderTextFile(filePath, bytes.toString("utf8")), [], [], [filePath]);
-	} catch (err) {
-		const reason = err instanceof Error ? err.message : String(err);
-		return result("", [{ type: "error", message: `file could not be read: ${reason}`, path: filePath }]);
-	}
-}
-
 async function readFileReferenceAsync(fileArg: string, options: FileReferenceOptions): Promise<FileReferenceResult> {
 	const filePath = expandConfigPath(fileArg, options.cwd === undefined ? undefined : { cwd: options.cwd });
 	if (!existsSync(filePath)) {
@@ -191,39 +216,6 @@ function splitTrailingPunctuation(token: string): { fileArg: string; suffix: str
 	return { fileArg: candidate, suffix };
 }
 
-export function expandInlineFileReferences(input: string, options: FileReferenceOptions = {}): FileReferenceResult {
-	const diagnostics: FileReferenceDiagnostic[] = [];
-	const images: ImageContent[] = [];
-	const referencedPaths: string[] = [];
-	const text = input.replace(FILE_REF, (match: string, prefix: string, token: string) => {
-		const direct = readFileReference(token, {
-			...options,
-			missing: "leave",
-			includeImages: options.includeImages === true,
-		});
-		if (direct.text !== `@${token}`) {
-			diagnostics.push(...direct.diagnostics);
-			images.push(...direct.images);
-			referencedPaths.push(...direct.referencedPaths);
-			return `${prefix}${direct.text}`;
-		}
-
-		const { fileArg, suffix } = splitTrailingPunctuation(token);
-		if (fileArg === token) return match;
-		const stripped = readFileReference(fileArg, {
-			...options,
-			missing: "leave",
-			includeImages: options.includeImages === true,
-		});
-		if (stripped.text === `@${fileArg}`) return match;
-		diagnostics.push(...stripped.diagnostics);
-		images.push(...stripped.images);
-		referencedPaths.push(...stripped.referencedPaths);
-		return `${prefix}${stripped.text}${suffix}`;
-	});
-	return { text, images, diagnostics, referencedPaths };
-}
-
 export async function expandInlineFileReferencesAsync(
 	input: string,
 	options: FileReferenceOptions = {},
@@ -233,31 +225,29 @@ export async function expandInlineFileReferencesAsync(
 	const referencedPaths: string[] = [];
 	let text = "";
 	let lastIndex = 0;
-	for (const match of input.matchAll(FILE_REF)) {
-		const index = match.index ?? 0;
-		const full = match[0] ?? "";
-		const prefix = match[1] ?? "";
-		const token = match[2] ?? "";
-		text += input.slice(lastIndex, index);
+	for (const reference of inlineFileReferences(input)) {
+		text += input.slice(lastIndex, reference.start);
 
-		const direct = await readFileReferenceAsync(token, {
+		const direct = await readFileReferenceAsync(reference.fileArg, {
 			...options,
 			missing: "leave",
 			includeImages: options.includeImages === true,
 		});
-		if (direct.text !== `@${token}`) {
+		if (direct.text !== `@${reference.fileArg}`) {
 			diagnostics.push(...direct.diagnostics);
 			images.push(...direct.images);
 			referencedPaths.push(...direct.referencedPaths);
-			text += `${prefix}${direct.text}`;
-			lastIndex = index + full.length;
+			text += direct.text;
+			lastIndex = reference.end;
 			continue;
 		}
 
-		const { fileArg, suffix } = splitTrailingPunctuation(token);
-		if (fileArg === token) {
-			text += full;
-			lastIndex = index + full.length;
+		const { fileArg, suffix } = reference.quoted
+			? { fileArg: reference.fileArg, suffix: "" }
+			: splitTrailingPunctuation(reference.fileArg);
+		if (fileArg === reference.fileArg) {
+			text += reference.raw;
+			lastIndex = reference.end;
 			continue;
 		}
 
@@ -267,15 +257,15 @@ export async function expandInlineFileReferencesAsync(
 			includeImages: options.includeImages === true,
 		});
 		if (stripped.text === `@${fileArg}`) {
-			text += full;
-			lastIndex = index + full.length;
+			text += reference.raw;
+			lastIndex = reference.end;
 			continue;
 		}
 		diagnostics.push(...stripped.diagnostics);
 		images.push(...stripped.images);
 		referencedPaths.push(...stripped.referencedPaths);
-		text += `${prefix}${stripped.text}${suffix}`;
-		lastIndex = index + full.length;
+		text += `${stripped.text}${suffix}`;
+		lastIndex = reference.end;
 	}
 	text += input.slice(lastIndex);
 	return { text, images, diagnostics, referencedPaths };

package/src/core/git-commit-attribution.ts

@@ -63,7 +63,7 @@ export interface ManagedCommitAttributionEnvironment {
 export function reportCommitAttributionDiagnostic(diagnostic: string | null): void {
 	if (diagnostic === null || reportedDiagnostics.has(diagnostic)) return;
 	reportedDiagnostics.add(diagnostic);
-	process.stderr.write(`[clio:attribution] ${diagnostic}\n`);
+	process.stderr.write(`[clio-coder:attribution] ${diagnostic}\n`);
 }
 
 export function setGitCommitAttributionEnabled(enabled: boolean): void {
@@ -74,12 +74,6 @@ export function gitCommitAttributionEnabled(source: NodeJS.ProcessEnv = process.
 	return source[CLIO_GIT_COMMITS_ENABLED_ENV] !== "0";
 }
 
-/** Forget cached repository probes and the installed managed hooks directory. */
-export function resetGitCommitAttributionCachesForTests(): void {
-	probeCache.clear();
-	installedHooksDirectory = null;
-}
-
 function boundedDiagnostic(message: string): string {
 	const folded = message.replace(/\s+/gu, " ").trim();
 	return folded.length <= DIAGNOSTIC_MAX_CHARS ? folded : `${folded.slice(0, DIAGNOSTIC_MAX_CHARS - 3)}...`;
@@ -171,7 +165,7 @@ hook_name=$(basename "$0")
 base_count=$${CONFIG_BASE_COUNT_ENV}
 case "$base_count" in
   '' | *[!0-9]*)
-    printf '%s\\n' '[clio:attribution] invalid managed hook environment' >&2
+    printf '%s\\n' '[clio-coder:attribution] invalid managed hook environment' >&2
     exit 0
     ;;
   0) unset GIT_CONFIG_COUNT ;;
@@ -241,7 +235,7 @@ has_trailer() {
 append_trailer() {
   if has_trailer "$1"; then return 0; fi
   git interpret-trailers --in-place --if-exists=addIfDifferent --trailer "$1" "$message_file" ||
-    printf '%s\\n' '[clio:attribution] git interpret-trailers failed; commit left as written' >&2
+    printf '%s\\n' '[clio-coder:attribution] git interpret-trailers failed; commit left as written' >&2
 }
 
 if [ "$${ASSISTED_ENV}" = '1' ] || [ "$${AUTHORED_ENV}" = '1' ]; then

package/src/core/guardrails.ts

@@ -76,6 +76,30 @@ export const GUARDRAIL_ENV_VARS: Readonly<Record<keyof GuardrailValues, string>>
 	internalDispatchTimeoutMs: "CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS",
 };
 
+/** Project canonical v2 settings leaves onto the process-local guardrail registry. */
+export function guardrailValuesFromSettings(settings: {
+	safety: {
+		limits: {
+			chatToolCallsPerTurn: number;
+			readBytesPerCall: number;
+			observationBytesPerTurn: number;
+		};
+	};
+	fleet: {
+		limits: { toolCallsPerRun: number; internalRunTimeoutMs: number };
+		history: { maxRuns: number };
+	};
+}): GuardrailValues {
+	return {
+		turnToolCallBudget: settings.safety.limits.chatToolCallsPerTurn,
+		workerToolCallCap: settings.fleet.limits.toolCallsPerRun,
+		maxDispatchRuns: settings.fleet.history.maxRuns,
+		readMaxBytes: settings.safety.limits.readBytesPerCall,
+		observationTurnBudgetBytes: settings.safety.limits.observationBytesPerTurn,
+		internalDispatchTimeoutMs: settings.fleet.limits.internalRunTimeoutMs,
+	};
+}
+
 /**
  * Older env spellings that still read. `CLIO_CODER_MAX_RUNS` was the only
  * guardrail whose variable was not the SCREAMING_SNAKE of its key, and CI
@@ -112,10 +136,6 @@ export function workerSynthesisReserveBlockReason(tool: string, remaining: numbe
 	);
 }
 
-export function isWorkerSynthesisReserveBlockReason(reason: string): boolean {
-	return /^workerToolCallReserve: only [1-9]\d* of [1-9]\d* tool calls remain/.test(reason);
-}
-
 export function workerToolCallCapExceededReason(cap: number): string {
 	return `workerToolCallCap reached (${cap}); abort run`;
 }

package/src/core/naming-compat.ts

@@ -0,0 +1,45 @@
+/**
+ * Released naming aliases retained for the v0.5 and v0.6 compatibility window.
+ * Canonical writers must never call this helper; it exists only at read and
+ * protocol boundaries where an older Clio Coder installation can still be the
+ * producer.
+ */
+
+const warned = new Set<string>();
+
+export const LEGACY_NAMING_COMPATIBILITY_RETIREMENT = "v0.7.0";
+
+/** Emit one deprecation diagnostic per legacy/canonical pair in this process. */
+export function warnLegacyNaming(legacy: string, canonical: string): void {
+	const key = `${legacy}\0${canonical}`;
+	if (warned.has(key)) return;
+	warned.add(key);
+	process.emitWarning(
+		`'${legacy}' is a deprecated Clio Coder identifier; use '${canonical}'. ` +
+			`Legacy naming compatibility is scheduled for removal in ${LEGACY_NAMING_COMPATIBILITY_RETIREMENT}.`,
+		{ code: "CLIO_CODER_LEGACY_NAMING", type: "DeprecationWarning" },
+	);
+}
+
+/** Prefer a canonical environment variable and temporarily fall back to its released alias. */
+export function readNamingEnvironment(
+	environment: NodeJS.ProcessEnv,
+	canonical: string,
+	legacy: string,
+): string | undefined {
+	const current = environment[canonical]?.trim();
+	if (current) return current;
+	const fallback = environment[legacy]?.trim();
+	if (!fallback) return undefined;
+	warnLegacyNaming(legacy, canonical);
+	return fallback;
+}
+
+/** Parent-to-child bridge used only during the two-minor compatibility window. */
+export function namingCompatibilityEnvironment(
+	canonical: string,
+	legacy: string,
+	value: string,
+): Record<string, string> {
+	return { [canonical]: value, [legacy]: value };
+}

package/src/core/naming-events.ts

@@ -0,0 +1,62 @@
+const CLIO_CODER_EVENT_SUFFIXES = new Set([
+	"permission_escalated",
+	"permission_resolved",
+	"plan_update",
+	"run_outcome",
+	"safety_decision",
+	"skill_activation",
+	"steer_received",
+	"tool_activity",
+	"tool_finish",
+	"tool_start",
+	"usage",
+	"verification",
+	"write_record_downgraded",
+]);
+
+/** Canonicalize one released snake-case event id without accepting arbitrary prefixes. */
+export function normalizeClioCoderEventType(type: string): string {
+	if (!type.startsWith("clio_") || type.startsWith("clio_coder_")) return type;
+	const suffix = type.slice("clio_".length);
+	return CLIO_CODER_EVENT_SUFFIXES.has(suffix) ? `clio_coder_${suffix}` : type;
+}
+
+/** Clone one decoded event only when its top-level discriminator is legacy. */
+export function normalizeClioCoderEventRecord(record: Record<string, unknown>): Record<string, unknown> {
+	if (typeof record.type !== "string") return record;
+	const type = normalizeClioCoderEventType(record.type);
+	return type === record.type ? record : { ...record, type };
+}
+
+/**
+ * Normalize legacy event discriminators in an in-memory decoded history tree.
+ * This never writes the source session/eval/evidence file.
+ */
+export function normalizeClioCoderEventTree(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		let changed = false;
+		const next = value.map((entry) => {
+			const normalized = normalizeClioCoderEventTree(entry);
+			if (normalized !== entry) changed = true;
+			return normalized;
+		});
+		return changed ? next : value;
+	}
+	if (typeof value !== "object" || value === null) return value;
+	const record = value as Record<string, unknown>;
+	let changed = false;
+	const next: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(record)) {
+		const normalized = normalizeClioCoderEventTree(entry);
+		next[key] = normalized;
+		if (normalized !== entry) changed = true;
+	}
+	if (typeof record.type === "string") {
+		const type = normalizeClioCoderEventType(record.type);
+		if (type !== record.type) {
+			next.type = type;
+			changed = true;
+		}
+	}
+	return changed ? next : value;
+}

package/src/core/recent-models.ts

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { safeResourceWrite } from "./safe-resource-write.js";
 import { clioStateDir, stateRootRemoved } from "./xdg.js";
 
-export function recentModelsPath(): string {
+function recentModelsPath(): string {
 	return join(clioStateDir(), "recent-models.json");
 }
 
@@ -83,9 +83,3 @@ export function rememberRecentModel(ref: string, limit: number): string[] {
 	}
 	return next;
 }
-
-/** Test hook: clear the in-process cache after CLIO_* dir overrides change. */
-export function resetRecentModelsCache(): void {
-	cache = null;
-	cachePath = null;
-}

package/src/core/residency-protection.ts

@@ -43,14 +43,10 @@ export function protectedResidencyModels(settings: ClioSettings): ProtectedModel
 		if (!trimmed || byId.has(trimmed)) return;
 		byId.set(trimmed, role);
 	};
-	add(settings.orchestrator.model, "chat");
-	add(settings.background.model, "memory");
-	add(settings.workers.default.model, "worker");
-	for (const profile of Object.values(settings.workers.profiles ?? {})) add(profile.model, "worker");
+	add(settings.chat.model, "chat");
+	add(settings.context.memory.model, "memory");
+	add(settings.fleet.default.model, "worker");
+	for (const profile of Object.values(settings.fleet.profiles ?? {})) add(profile.model, "worker");
 	for (const target of settings.targets) add(target.defaultModel, "target-default");
 	return [...byId].map(([modelId, role]) => ({ modelId, role }));
 }
-
-export function protectedResidencyModelIds(settings: ClioSettings): string[] {
-	return protectedResidencyModels(settings).map((ref) => ref.modelId);
-}

package/src/core/resolve-config-value.ts

@@ -50,7 +50,7 @@ function warnStaticCommand(config: string, options?: ResolveConfigValueOptions):
 	});
 }
 
-export function expandConfigValue(value: string, options?: ResolveConfigValueOptions): string {
+function expandConfigValue(value: string, options?: ResolveConfigValueOptions): string {
 	const sourceEnv = env(options);
 	return value.replace(/\$(\w+)|\$\{([^}]+)\}/g, (match, bare: string | undefined, braced: string | undefined) => {
 		const key = bare ?? braced;

package/src/core/response-model-id.ts

@@ -101,20 +101,6 @@ export function responseModelIdObservationFromRecord(
 	return { state: "legacy-difference-only", differingModelId: nonEmptyString(record.responseModel) };
 }
 
-/** Human vocabulary shared by usage, footer, and receipt projections. */
-export function responseModelIdObservationLabel(observation: ResponseModelIdObservation): string {
-	switch (observation.state) {
-		case "reported":
-			return "reported";
-		case "not-reported":
-			return "not reported";
-		case "not-observed":
-			return "not observed";
-		case "legacy-difference-only":
-			return "legacy difference-only";
-	}
-}
-
 /** Model id used for accounting without claiming more than the observation supports. */
 export function attributedModelId(
 	observation: ResponseModelIdObservation,