@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/cli/usage.ts

@@ -203,9 +203,16 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		process.stderr.write(HELP);
 		return 2;
 	}
-	if (parsed.help || parsed.command === undefined) {
+	if (parsed.help) {
 		process.stdout.write(HELP);
-		return parsed.help ? 0 : 2;
+		return 0;
+	}
+	// A bare `clio-coder usage` already exited 2, but wrote its usage to stdout,
+	// which is where the report itself goes. Usage that stands in for output the
+	// caller asked for belongs on stderr.
+	if (parsed.command === undefined) {
+		process.stderr.write(HELP);
+		return 2;
 	}
 	if (parsed.command !== "report") {
 		printError(`unknown usage command: ${parsed.command}`);
@@ -352,7 +359,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		if (bareIds.length < 3) continue;
 		opportunities.push({
 			kind: "workflow-distiller",
-			suggestion: `bash shape "${shape}" recurs with no skill activation; consider /skill:workflow-distiller to distill it`,
+			suggestion: `bash shape "${shape}" recurs with no skill activation; consider /skill workflow-distiller to distill it`,
 			evidence: `${bareIds.length} sessions: ${bareIds.slice(0, 5).join(", ")}${bareIds.length > 5 ? ", ..." : ""}`,
 		});
 	}

package/src/cli/wiki-generate.ts

@@ -6,7 +6,8 @@ import { ToolNames } from "../core/tool-names.js";
 import { AgentsDomainModule } from "../domains/agents/index.js";
 import type { ConfigContract } from "../domains/config/contract.js";
 import { ConfigDomainModule } from "../domains/config/index.js";
-import { ContextDomainModule, type WikiGenerate, type WikiGenerateInput } from "../domains/context/index.js";
+import { ContextDomainModule } from "../domains/context/runtime.js";
+import type { WikiGenerate, WikiGenerateInput } from "../domains/context/wiki/generate.js";
 import type { WikiPlan, WikiPlanPage } from "../domains/context/wiki/plan.js";
 import {
 	MAX_PAGE_ATTEMPTS,

package/src/core/agent-environment.ts

@@ -0,0 +1,7 @@
+/** Generic child-process attribution used by agent-aware developer tools. */
+export const AI_AGENT_NAME = "clio-coder";
+
+/** Add Clio's attribution without admitting any other environment variables. */
+export function withClioAgentEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	return { ...source, AI_AGENT: AI_AGENT_NAME };
+}

package/src/core/bash-exec.ts

@@ -1,4 +1,10 @@
 import { spawn } from "node:child_process";
+import { AI_AGENT_NAME } from "./agent-environment.js";
+import {
+	gitCommitAttributionEnabled,
+	reportCommitAttributionDiagnostic,
+	withManagedGitCommitAttributionEnvironment,
+} from "./git-commit-attribution.js";
 import { clampTimerDelayMs } from "./timers.js";
 
 export { clampTimerDelayMs as clampTimeoutMs } from "./timers.js";
@@ -24,14 +30,28 @@ export interface BashCommandResult {
 	outputCapped: boolean;
 }
 
+export interface BashCommandProgress {
+	/** Cumulative stdout captured so far. */
+	stdout: string;
+	/** Cumulative stderr captured so far. */
+	stderr: string;
+	/** Total bytes accepted from both streams so far. */
+	outputBytes: number;
+}
+
 export interface RunBashCommandOptions {
 	cwd?: string;
 	timeoutMs?: number;
 	signal?: AbortSignal;
+	/** Cumulative snapshots, throttled to keep terminal rendering responsive. */
+	onUpdate?: (progress: BashCommandProgress) => void;
 }
 
+const BASH_UPDATE_THROTTLE_MS = 100;
+
 function buildToolEnv(): NodeJS.ProcessEnv {
 	const env = { ...process.env };
+	env.AI_AGENT = AI_AGENT_NAME;
 	for (const key of CLIO_CONTROL_ENV_KEYS) {
 		Reflect.deleteProperty(env, key);
 	}
@@ -102,6 +122,7 @@ async function bashSpawnPlan(): Promise<BashSpawnPlan> {
 	// the capture still flow through; the CLIO control keys are re-stripped
 	// last so they never reach the child from either source.
 	const env: NodeJS.ProcessEnv = { ...process.env, ...captured };
+	env.AI_AGENT = AI_AGENT_NAME;
 	for (const key of CLIO_CONTROL_ENV_KEYS) {
 		Reflect.deleteProperty(env, key);
 	}
@@ -115,6 +136,11 @@ export function combineBashOutput(result: Pick<BashCommandResult, "stdout" | "st
 
 export async function runBashCommand(command: string, options: RunBashCommandOptions = {}): Promise<BashCommandResult> {
 	const plan = await bashSpawnPlan();
+	const attribution = withManagedGitCommitAttributionEnvironment(plan.env, {
+		cwd: options.cwd ?? process.cwd(),
+		enabled: gitCommitAttributionEnabled(process.env),
+	});
+	reportCommitAttributionDiagnostic(attribution.diagnostic);
 	return new Promise((resolve) => {
 		const timeout = clampTimerDelayMs(options.timeoutMs ?? 300_000);
 		let aborted = false;
@@ -127,14 +153,55 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		let stderr = "";
 		let outputBytes = 0;
 		let outputCapped = false;
+		let updateTimer: ReturnType<typeof setTimeout> | null = null;
+		let updateDirty = false;
+		let lastUpdateAt = 0;
 
 		const child = spawn("/bin/bash", [plan.mode, command], {
 			...(options.cwd === undefined ? {} : { cwd: options.cwd }),
-			env: plan.env,
+			env: attribution.env,
 			detached: process.platform !== "win32",
 			stdio: ["ignore", "pipe", "pipe"],
 		});
 
+		const emitUpdate = (): void => {
+			if (options.onUpdate === undefined || !updateDirty) return;
+			updateDirty = false;
+			lastUpdateAt = Date.now();
+			try {
+				options.onUpdate({ stdout, stderr, outputBytes: Math.min(outputBytes, BASH_HARD_CAP_BYTES) });
+			} catch {
+				// Rendering progress is advisory and must never change command execution.
+			}
+		};
+		const clearUpdateTimer = (): void => {
+			if (updateTimer === null) return;
+			clearTimeout(updateTimer);
+			updateTimer = null;
+		};
+		const scheduleUpdate = (): void => {
+			if (options.onUpdate === undefined) return;
+			updateDirty = true;
+			const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
+			if (delay <= 0) {
+				clearUpdateTimer();
+				emitUpdate();
+				return;
+			}
+			updateTimer ??= setTimeout(() => {
+				updateTimer = null;
+				emitUpdate();
+			}, delay);
+		};
+		const finishUpdates = (): void => {
+			clearUpdateTimer();
+			emitUpdate();
+		};
+		if (options.onUpdate !== undefined) {
+			updateDirty = true;
+			emitUpdate();
+		}
+
 		const clearKillGraceTimer = (): void => {
 			if (!killGraceTimer) return;
 			clearTimeout(killGraceTimer);
@@ -195,11 +262,13 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 					else stderr += slice;
 				}
 				outputCapped = true;
+				scheduleUpdate();
 				killChild();
 				return;
 			}
 			if (target === "stdout") stdout += chunk.toString("utf8");
 			else stderr += chunk.toString("utf8");
+			scheduleUpdate();
 		};
 
 		child.stdout?.on("data", (chunk: Buffer) => appendChunk("stdout", chunk));
@@ -209,6 +278,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
+			finishUpdates();
 			options.signal?.removeEventListener("abort", onAbort);
 			resolve({
 				error: error as NodeJS.ErrnoException,
@@ -226,6 +296,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
+			finishUpdates();
 			options.signal?.removeEventListener("abort", onAbort);
 			const error =
 				code === 0 && signalName === null

package/src/core/boot-trace.ts

@@ -20,17 +20,22 @@ export function isBootTraceEnabled(): boolean {
 	return process.env[BOOT_TRACE_ENV] === "1";
 }
 
+/** Build one trace line without choosing an output owner. */
+export function formatBootTrace(phase: string, detail?: string): string | null {
+	if (!isBootTraceEnabled()) return null;
+	const suffix = detail !== undefined && detail.length > 0 ? ` (${detail})` : "";
+	return `[clio:boot] +${performance.now().toFixed(1)}ms ${phase}${suffix}\n`;
+}
+
 /**
  * Stamp a boot phase marker to stderr, e.g. `[clio:boot] +742.1ms cli entry`.
  * `detail` appends a parenthetical (module counts, ids). No-op unless
  * `CLIO_CODER_TRACE_BOOT=1`. Never throws: a diagnostic must not affect boot.
  */
 export function traceBoot(phase: string, detail?: string): void {
-	if (!isBootTraceEnabled()) return;
 	try {
-		const elapsedMs = performance.now();
-		const suffix = detail !== undefined && detail.length > 0 ? ` (${detail})` : "";
-		process.stderr.write(`[clio:boot] +${elapsedMs.toFixed(1)}ms ${phase}${suffix}\n`);
+		const line = formatBootTrace(phase, detail);
+		if (line) process.stderr.write(line);
 	} catch {
 		// Tracing is best-effort; a write failure must never break boot.
 	}

package/src/core/bus-events.ts

@@ -34,6 +34,7 @@ export const BusChannels = {
 	SessionEnd: "session.end",
 	SessionParked: "session.parked",
 	SessionResumed: "session.resumed",
+	SessionTurnSwitched: "session.turn_switched",
 	DomainLoaded: "domain.loaded",
 	DomainFailed: "domain.failed",
 	ConfigHotReload: "config.hotReload",
@@ -300,6 +301,20 @@ export interface SessionResumedPayload {
 	at: number;
 }
 
+/**
+ * Published on {@link BusChannels.SessionTurnSwitched} when `/tree` moves the
+ * active append point inside the current session without changing which
+ * session is open. Nothing else observes that move: unlike resume/fork, the
+ * session id in `getSessionId()` callbacks stays the same, so anything keyed
+ * on session id alone (the task board cache among them) needs this signal to
+ * know its fold is stale.
+ */
+export interface SessionTurnSwitchedPayload {
+	sessionId: string;
+	turnId: string;
+	at: number;
+}
+
 /** Published on {@link BusChannels.DomainLoaded} per successfully started domain. */
 export interface DomainLoadedPayload {
 	name: string;
@@ -395,12 +410,12 @@ export interface PermissionRequestedPayload {
 
 /**
  * Published on {@link BusChannels.PermissionResolved} when a parked call is
- * granted or denied (operator decision, headless auto-deny, or a delegated
- * agent's denial relayed by dispatch). Only `status` is guaranteed; emitters
- * attach whatever provenance they have.
+ * granted, denied, or expires internally (operator decision, headless
+ * auto-deny, delegated-agent denial, or internal expiry). Only `status` is
+ * guaranteed; emitters attach whatever provenance they have.
  */
 export interface PermissionResolvedPayload {
-	status: "granted" | "denied";
+	status: "granted" | "denied" | "expired";
 	requestId?: string | undefined;
 	origin?: string | undefined;
 	decidedBy?: string | undefined;
@@ -685,6 +700,7 @@ export type BusPayloadMap = {
 	[BusChannels.SessionEnd]: SessionEndPayload;
 	[BusChannels.SessionParked]: SessionParkedPayload;
 	[BusChannels.SessionResumed]: SessionResumedPayload;
+	[BusChannels.SessionTurnSwitched]: SessionTurnSwitchedPayload;
 	[BusChannels.DomainLoaded]: DomainLoadedPayload;
 	[BusChannels.DomainFailed]: DomainFailedPayload;
 	[BusChannels.ConfigHotReload]: ConfigChangePayload;

package/src/core/commit-attribution.ts

@@ -0,0 +1,157 @@
+/**
+ * Pure Git commit-message attribution.
+ *
+ * Callers supply sealed facts, never model prose. This module only translates
+ * those facts into role trailers and has no filesystem, process, Git, or
+ * settings dependencies, so every controlled commit seam shares one policy.
+ */
+
+export const CLIO_COMMIT_IDENTITY = "Clio Coder <clio-coder@iowarp.ai>";
+
+export const CLIO_COMMIT_TRAILERS = {
+	assisted: `Assisted-by: ${CLIO_COMMIT_IDENTITY}`,
+	tested: `Tested-by: ${CLIO_COMMIT_IDENTITY}`,
+	reviewed: `Reviewed-by: ${CLIO_COMMIT_IDENTITY}`,
+	coAuthored: `Co-authored-by: ${CLIO_COMMIT_IDENTITY}`,
+} as const;
+
+export interface CommitReceiptEvidence {
+	version: 15;
+	algorithm: "sha256";
+	digest: string;
+	/** The receipt was checked against its run-ledger envelope. */
+	integrityValid: boolean;
+	/** The receipt describes work or a verdict directly relevant to this commit. */
+	directlyRelevant: boolean;
+}
+
+/** Trusted facts about the work recorded by one commit. */
+export interface CommitAttributionEvidence {
+	/** Clio materially created or edited work recorded by this commit. */
+	materiallyAssisted?: boolean;
+	/** A real validation command completed successfully against the committed work. */
+	validationSucceeded?: boolean;
+	/** An independent verifier or reviewer produced a passing result. */
+	independentReviewPassed?: boolean;
+	/** Clio materially authored part of the committed change. */
+	materiallyAuthored?: boolean;
+	/** Optional sealed receipt for a directly relevant fact above. */
+	receipt?: CommitReceiptEvidence;
+}
+
+const TRAILER_LINE = /^([A-Za-z0-9][A-Za-z0-9-]*):[ \t]+(.+)$/u;
+const SHA256 = /^[0-9a-f]{64}$/u;
+
+function normalizedTrailer(line: string): string | null {
+	const match = TRAILER_LINE.exec(line);
+	if (match === null) return null;
+	return `${match[1]?.toLowerCase()}:${match[2]
+		?.trim()
+		.replace(/[ \t]+/gu, " ")
+		.toLowerCase()}`;
+}
+
+const KNOWN_CLIO_TRAILERS = new Set(
+	Object.values(CLIO_COMMIT_TRAILERS)
+		.map((line) => normalizedTrailer(line))
+		.filter((line): line is string => line !== null),
+);
+
+function isClioTrailer(key: string): boolean {
+	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v15/sha256:");
+}
+
+/**
+ * Return the first line of a conventional trailing trailer paragraph.
+ * Human continuation lines are recognized as part of the block but never
+ * interpreted or rewritten; Clio's own trailers are always one line.
+ */
+function trailerBlockStart(lines: ReadonlyArray<string>): number | null {
+	if (lines.length < 2) return null;
+	const separator = lines.lastIndexOf("");
+	const first = separator + 1;
+	// A trailer paragraph is separated from subject/body by a blank line. This
+	// keeps a subject such as "Fix: parser" a subject rather than metadata.
+	if (separator < 0 || first >= lines.length) return null;
+	let sawTrailer = false;
+	for (const line of lines.slice(first)) {
+		if (TRAILER_LINE.test(line)) {
+			sawTrailer = true;
+			continue;
+		}
+		if (sawTrailer && /^[ \t]+/u.test(line)) continue;
+		return null;
+	}
+	return sawTrailer ? first : null;
+}
+
+function receiptTrailer(receipt: CommitReceiptEvidence | undefined): string | null {
+	if (
+		receipt?.version !== 15 ||
+		receipt.algorithm !== "sha256" ||
+		receipt.integrityValid !== true ||
+		receipt.directlyRelevant !== true ||
+		!SHA256.test(receipt.digest)
+	) {
+		return null;
+	}
+	return `Clio-Evidence: receipt-v15/sha256:${receipt.digest}`;
+}
+
+/**
+ * Append only evidence-justified Clio trailers.
+ *
+ * Disabled attribution is the one byte-preserving path. When enabled, CRLF and
+ * lone CR are normalized to LF, the message ends with one newline, existing
+ * subject/body and human trailers remain in order, repeated Clio trailers are
+ * removed case-insensitively, and processing the result again is idempotent.
+ */
+export function attributeCommitMessage(
+	originalMessage: string,
+	evidence: Readonly<CommitAttributionEvidence>,
+	enabled = true,
+): string {
+	if (!enabled) return originalMessage;
+
+	const normalized = originalMessage.replace(/\r\n?/gu, "\n");
+	const lines = normalized.replace(/\n+$/u, "").split("\n");
+	const blockStart = trailerBlockStart(lines);
+	const seenClio = new Set<string>();
+	const retained = lines.filter((line, index) => {
+		if (blockStart === null || index < blockStart) return true;
+		const key = normalizedTrailer(line);
+		if (key === null || !isClioTrailer(key)) return true;
+		if (seenClio.has(key)) return false;
+		seenClio.add(key);
+		return true;
+	});
+
+	const desired: string[] = [];
+	// Material authorship necessarily means material assistance too. Keeping the
+	// two facts separate lets Co-authored-by remain a platform compatibility
+	// marker rather than a substitute for the semantic role trailer.
+	if (evidence.materiallyAssisted === true || evidence.materiallyAuthored === true) {
+		desired.push(CLIO_COMMIT_TRAILERS.assisted);
+	}
+	if (evidence.validationSucceeded === true) desired.push(CLIO_COMMIT_TRAILERS.tested);
+	if (evidence.independentReviewPassed === true) desired.push(CLIO_COMMIT_TRAILERS.reviewed);
+	if (evidence.materiallyAuthored === true) desired.push(CLIO_COMMIT_TRAILERS.coAuthored);
+	const receipt = receiptTrailer(evidence.receipt);
+	if (receipt !== null) desired.push(receipt);
+
+	const existing = new Set(
+		(blockStart === null ? [] : retained.slice(blockStart))
+			.map((line) => normalizedTrailer(line))
+			.filter((line): line is string => line !== null),
+	);
+	const additions = desired.filter((line) => !existing.has(normalizedTrailer(line) ?? ""));
+	if (additions.length === 0) return `${retained.join("\n")}\n`;
+
+	if (blockStart === null) {
+		while (retained.at(-1) === "") retained.pop();
+		retained.push("", ...additions);
+	} else {
+		retained.push(...additions);
+	}
+	return `${retained.join("\n")}\n`;
+}

package/src/core/compile-cache.ts

@@ -0,0 +1,159 @@
+/**
+ * V8 compile cache for the dynamically imported command graphs.
+ *
+ * The interactive chunk graph alone is ~1,400 ES modules, and V8 compilation
+ * of it measures ~227 ms per cold boot (CPU profile, compileSourceTextModule).
+ * Node's module compile cache persists the bytecode across processes and cuts
+ * that to ~70 ms. The cache is a pure optimization: enableCompileCache() never
+ * throws, and a failure to enable it must never affect a command.
+ *
+ * Enable order matters twice over. In this process, only modules loaded after
+ * the call are cached, so the CLI calls this before its per-command dynamic
+ * import and after the --help/--version fast paths (which keep their
+ * no-filesystem-write contract). Enablement is further gated on Clio's cache
+ * root already existing, because read-only commands (`paths`, bare `doctor`)
+ * promise to write nothing to a home Clio never set up; a pristine home pays
+ * one uncached boot and every initialized install caches from then on. In
+ * spawned native workers, the entry's whole
+ * static graph resolves before any application code runs, so the only lever
+ * that reaches them in time is the NODE_COMPILE_CACHE environment variable;
+ * the dispatch spawn path injects it alongside {@link INJECTED_COMPILE_CACHE_ENV}.
+ *
+ * The injection is for Clio's own worker entry, not for the worker's
+ * descendants: bash tool commands, middleware hooks, and external runtime
+ * subprocesses all copy the worker's process.env, and without consumption
+ * every user-launched Node process would silently write bytecode into Clio's
+ * cache. The marker records that Clio, not the operator, put
+ * NODE_COMPILE_CACHE in this environment; the worker entry calls
+ * {@link deleteInjectedCompileCacheFrom} on its own process.env immediately
+ * after Node's bootstrap read it, so no child of any kind can inherit the
+ * pair. An operator-supplied NODE_COMPILE_CACHE never carries the marker and
+ * always passes through.
+ *
+ * Operator controls win everywhere: NODE_DISABLE_COMPILE_CACHE turns this off
+ * entirely, and an existing NODE_COMPILE_CACHE names the directory (Node reads
+ * it when enableCompileCache is called with no argument).
+ */
+
+import { existsSync } from "node:fs";
+import { enableCompileCache } from "node:module";
+import { join } from "node:path";
+import { resolveClioDirs } from "./xdg.js";
+
+/**
+ * Marks a NODE_COMPILE_CACHE value Clio itself injected into a child env. Its
+ * value is the injected directory, which is what lets the scrub distinguish
+ * Clio's injection from a NODE_COMPILE_CACHE the operator set.
+ */
+export const INJECTED_COMPILE_CACHE_ENV = "CLIO_CODER_INJECTED_COMPILE_CACHE";
+
+export interface CompileCacheHandle {
+	/**
+	 * Enable the compile cache for this process. The first call settles the
+	 * outcome, directory or null, and every later call returns that settled
+	 * value: a run that started disabled or failed must not enable itself on a
+	 * retry with a different environment.
+	 */
+	enable(env?: NodeJS.ProcessEnv): string | null;
+	/** The settled directory, or null while unattempted, disabled, or failed. */
+	directory(): string | null;
+}
+
+/**
+ * Testable factory. Production uses the module-level instance below bound to
+ * Node's real enableCompileCache and existsSync; tests inject stubs so they
+ * exercise the settle semantics without flipping the real process-global
+ * cache.
+ */
+export function createCompileCache(
+	enableFn: typeof enableCompileCache = enableCompileCache,
+	rootExists: (dir: string) => boolean = existsSync,
+): CompileCacheHandle {
+	let settled: string | null | undefined;
+	return {
+		enable(env = process.env) {
+			if (settled !== undefined) return settled;
+			if (env.NODE_DISABLE_COMPILE_CACHE !== undefined) {
+				settled = null;
+				return settled;
+			}
+			try {
+				if (env.NODE_COMPILE_CACHE !== undefined) {
+					// Presence is the operator speaking, even as an empty string,
+					// matching the worker boundary's presence check. No argument:
+					// Node interprets the operator's NODE_COMPILE_CACHE itself, and
+					// Clio's default must not override it.
+					settled = enableFn().directory ?? null;
+					return settled;
+				}
+				// Enabling creates the directory, and diagnostic commands carry a
+				// read-only contract: `paths` and `doctor` without --fix must write
+				// nothing to a home Clio never set up. Clio's cache root existing is
+				// the proof this install was set up, so only then is a write inside
+				// it a cache write rather than a first write to a pristine home.
+				const root = resolveClioDirs().cache;
+				if (!rootExists(root)) {
+					settled = null;
+					return settled;
+				}
+				settled = enableFn(join(root, "v8-compile-cache")).directory ?? null;
+			} catch {
+				settled = null;
+			}
+			return settled;
+		},
+		directory: () => settled ?? null,
+	};
+}
+
+const processCompileCache = createCompileCache();
+
+/**
+ * Enable the cache for this process; see {@link CompileCacheHandle.enable}.
+ * The boot entrypoints call it for their own module graphs, and the native
+ * worker spawn path calls it so children receive a NODE_COMPILE_CACHE they
+ * can act on before their module graph resolves.
+ */
+export function enableClioCompileCache(env?: NodeJS.ProcessEnv): string | null {
+	return processCompileCache.enable(env);
+}
+
+/**
+ * The environment a native worker spawn should hand its child. A preexisting
+ * marker never survives: the marker is Clio's own plumbing, and letting one
+ * ride into a worker beside operator controls is how a stale or spoofed
+ * marker whose value happens to equal the operator's NODE_COMPILE_CACHE
+ * would later make the worker-entry scrub delete that operator setting for
+ * every descendant. When the operator named or disabled the cache, their
+ * controls pass through alone; otherwise, if this process enabled the cache,
+ * the bound pair is injected so the worker's module graph compiles from it.
+ */
+export function workerCompileCacheEnvironment(env: NodeJS.ProcessEnv, directory: string | null): NodeJS.ProcessEnv {
+	const operatorControlled = env.NODE_COMPILE_CACHE !== undefined || env.NODE_DISABLE_COMPILE_CACHE !== undefined;
+	if (operatorControlled || directory === null) {
+		if (env[INJECTED_COMPILE_CACHE_ENV] === undefined) return env;
+		const cleaned = { ...env };
+		Reflect.deleteProperty(cleaned, INJECTED_COMPILE_CACHE_ENV);
+		return cleaned;
+	}
+	return { ...env, NODE_COMPILE_CACHE: directory, [INJECTED_COMPILE_CACHE_ENV]: directory };
+}
+
+/**
+ * Consume a Clio-injected compile-cache pair from an env, in place. The
+ * marker carries the injected directory as its value, and NODE_COMPILE_CACHE
+ * is deleted only when it still equals that value: a stale or spoofed marker
+ * sitting next to some other NODE_COMPILE_CACHE removes only itself. The one
+ * production caller is the worker entry, on its own process.env, immediately
+ * after Node's bootstrap read the pair; by construction that pair came from
+ * {@link workerCompileCacheEnvironment}, which never lets a marker travel
+ * beside operator controls.
+ */
+export function deleteInjectedCompileCacheFrom(env: NodeJS.ProcessEnv): void {
+	const injected = env[INJECTED_COMPILE_CACHE_ENV];
+	if (injected === undefined) return;
+	if (env.NODE_COMPILE_CACHE === injected) {
+		Reflect.deleteProperty(env, "NODE_COMPILE_CACHE");
+	}
+	Reflect.deleteProperty(env, INJECTED_COMPILE_CACHE_ENV);
+}