@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/core/workspace-files.ts

@@ -0,0 +1,492 @@
+import { execFile, execFileSync } from "node:child_process";
+import fs, { type Dir } from "node:fs";
+import { join, sep } from "node:path";
+import { performance } from "node:perf_hooks";
+
+/**
+ * Cooperative-yield surface for the async enumeration forms. Structurally
+ * compatible with the context domain's CooperativeSlicer, so callers that
+ * already hold one pass it straight through; callers without one get a local
+ * time-budgeted default. Core cannot import the domain type, by boundary.
+ */
+export interface WorkspaceEnumerationTick {
+	tick(): Promise<void>;
+}
+
+const DEFAULT_YIELD_BUDGET_MS = 8;
+
+function createDefaultTick(budgetMs = DEFAULT_YIELD_BUDGET_MS): WorkspaceEnumerationTick {
+	let sliceStart = performance.now();
+	return {
+		async tick(): Promise<void> {
+			if (performance.now() - sliceStart < budgetMs) return;
+			await new Promise<void>((resolve) => {
+				setImmediate(resolve);
+			});
+			sliceStart = performance.now();
+		},
+	};
+}
+
+const GIT_OUTPUT_LIMIT_BYTES = 128 * 1024 * 1024;
+const MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS = 200;
+
+export interface WorkspaceFallbackLimits {
+	maxVisitedEntries: number;
+	maxDepth: number;
+	maxPathBytes: number;
+	maxDurationMs: number;
+}
+
+export type WorkspaceFallbackLimitKind = "entries" | "depth" | "path-bytes" | "time";
+export type WorkspaceEnumerationOperation = "open-root" | "read-directory" | "open-directory" | "inspect-entry";
+
+const DEFAULT_WORKSPACE_FALLBACK_LIMITS: Readonly<WorkspaceFallbackLimits> = Object.freeze({
+	maxVisitedEntries: 100_000,
+	maxDepth: 64,
+	maxPathBytes: 64 * 1024 * 1024,
+	maxDurationMs: 5_000,
+});
+
+/**
+ * Explicit failure for a non-Git scan that cannot prove it saw the whole
+ * workspace within its resource contract. Callers must never publish the
+ * partial prefix as an authoritative file set.
+ */
+export class WorkspaceEnumerationLimitError extends Error {
+	readonly code = "WORKSPACE_ENUMERATION_LIMIT";
+
+	constructor(
+		readonly kind: WorkspaceFallbackLimitKind,
+		readonly limit: number,
+	) {
+		super(`non-Git workspace enumeration exceeded ${kind} limit (${limit})`);
+		this.name = "WorkspaceEnumerationLimitError";
+	}
+}
+
+function boundedDiagnosticPath(path: string): string {
+	const printable = Array.from(path.length > 0 ? path : ".", (character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f) ? "?" : character;
+	});
+	if (printable.length <= MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS) return printable.join("");
+	const side = Math.floor((MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS - 1) / 2);
+	return `${printable.slice(0, side).join("")}\u2026${printable.slice(-side).join("")}`;
+}
+
+function boundedSystemErrorCode(cause: unknown): string {
+	if (typeof cause !== "object" || cause === null || !("code" in cause)) return "UNKNOWN";
+	const code = (cause as { code?: unknown }).code;
+	return typeof code === "string" && /^[A-Z][A-Z0-9_]{0,31}$/.test(code) ? code : "UNKNOWN";
+}
+
+const ENUMERATION_OPERATION_LABELS: Readonly<Record<WorkspaceEnumerationOperation, string>> = Object.freeze({
+	"open-root": "open the workspace root",
+	"read-directory": "read a workspace directory",
+	"open-directory": "open a workspace directory",
+	"inspect-entry": "inspect a workspace entry",
+});
+
+/**
+ * Explicit failure for a non-Git scan whose filesystem view became incomplete.
+ * Only a bounded workspace-relative path and a validated system error code are
+ * retained; arbitrary filesystem error text is deliberately not propagated.
+ */
+export class WorkspaceEnumerationIncompleteError extends Error {
+	readonly code = "WORKSPACE_ENUMERATION_INCOMPLETE";
+	readonly operation: WorkspaceEnumerationOperation;
+	readonly path: string;
+	readonly causeCode: string;
+
+	constructor(operation: WorkspaceEnumerationOperation, path: string, cause: unknown) {
+		const diagnosticPath = boundedDiagnosticPath(path);
+		const causeCode = boundedSystemErrorCode(cause);
+		super(
+			`non-Git workspace enumeration could not ${ENUMERATION_OPERATION_LABELS[operation]} at '${diagnosticPath}' (${causeCode})`,
+		);
+		this.name = "WorkspaceEnumerationIncompleteError";
+		this.operation = operation;
+		this.path = diagnosticPath;
+		this.causeCode = causeCode;
+	}
+}
+
+/**
+ * Directories omitted even when Git tracks files beneath them. Git ignore
+ * rules complement this policy; they do not override it.
+ */
+export const WORKSPACE_EXCLUDED_DIRS: ReadonlySet<string> = new Set([
+	".git",
+	".hg",
+	".svn",
+	".clio-coder",
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	".venv",
+	"venv",
+	"__pycache__",
+	"target",
+	"vendor",
+	".superpowers",
+	".codex",
+	".claude",
+	".clio-coder-benchmark",
+]);
+
+function comparePaths(a: string, b: string): number {
+	return a === b ? 0 : a < b ? -1 : 1;
+}
+
+function normalizeRelativePath(path: string): string | null {
+	const posixPath = sep === "\\" ? path.replaceAll("\\", "/") : path;
+	const normalized = posixPath.replace(/^\.\//, "");
+	if (normalized.length === 0 || normalized.includes("\0") || normalized.startsWith("/")) return null;
+	if (/^[A-Za-z]:\//.test(normalized)) return null;
+	const segments = normalized.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) return null;
+	return segments.join("/");
+}
+
+function isWorkspacePathExcluded(
+	relPath: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+): boolean {
+	return relPath.split("/").some((segment) => excludedDirs.has(segment));
+}
+
+function isDisappearedWorkspaceEntry(cause: unknown): boolean {
+	if (typeof cause !== "object" || cause === null || !("code" in cause)) return false;
+	const code = (cause as { code?: unknown }).code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function isRegularWorkspaceFile(cwd: string, relPath: string, requireCompleteSnapshot: boolean): boolean {
+	try {
+		// lstat deliberately excludes symlinks. Gitlinks resolve to directories,
+		// so full scans do not enter submodules either.
+		const stat = fs.lstatSync(join(cwd, relPath));
+		if (stat.isFile()) return true;
+		if (requireCompleteSnapshot && stat.isDirectory()) {
+			// The fallback walker observed this path as a file. If it became a
+			// directory before validation, that directory may contain entries the
+			// completed walk never visited, so the snapshot is no longer complete.
+			throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, { code: "ENTRY_TYPE_CHANGED" });
+		}
+		return false;
+	} catch (cause) {
+		if (cause instanceof WorkspaceEnumerationIncompleteError) throw cause;
+		if (requireCompleteSnapshot) {
+			// A vanished file (or an ancestor replaced by a non-directory) is no
+			// longer part of the workspace at validation time and may be omitted.
+			// Permission, I/O, and stale-handle errors leave its visibility unknown
+			// and must invalidate the complete non-Git snapshot.
+			if (isDisappearedWorkspaceEntry(cause)) return false;
+			throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, cause);
+		}
+		return false;
+	}
+}
+
+function gitVisibleFilesArgs(candidates?: ReadonlyArray<string>): string[] {
+	const args = ["--literal-pathspecs", "ls-files", "-z", "--cached", "--others", "--exclude-standard"];
+	if (candidates) args.push("--", ...candidates);
+	return args;
+}
+
+function splitGitPathOutput(output: string): string[] {
+	return output.split("\0").filter((path) => path.length > 0);
+}
+
+function gitVisibleFiles(cwd: string, candidates?: ReadonlyArray<string>): string[] | null {
+	let output: Buffer;
+	try {
+		output = execFileSync("git", gitVisibleFilesArgs(candidates), {
+			cwd,
+			maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+	} catch {
+		return null;
+	}
+	return splitGitPathOutput(output.toString("utf8"));
+}
+
+function gitVisibleFilesAsync(cwd: string, candidates?: ReadonlyArray<string>): Promise<string[] | null> {
+	return new Promise((resolve) => {
+		execFile("git", gitVisibleFilesArgs(candidates), { cwd, maxBuffer: GIT_OUTPUT_LIMIT_BYTES }, (error, stdout) => {
+			resolve(error ? null : splitGitPathOutput(stdout));
+		});
+	});
+}
+
+function resolveFallbackLimits(overrides: Partial<WorkspaceFallbackLimits> | undefined): WorkspaceFallbackLimits {
+	const limits = { ...DEFAULT_WORKSPACE_FALLBACK_LIMITS, ...overrides };
+	for (const [name, value] of Object.entries(limits)) {
+		if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+			throw new RangeError(`workspace fallback ${name} must be a non-negative integer`);
+		}
+	}
+	return limits;
+}
+
+interface WalkFrame {
+	dir: Dir;
+	absPath: string;
+	prefix: string;
+	depth: number;
+}
+
+type FallbackEntryKind = "directory" | "file" | "other" | "disappeared";
+
+function fallbackEntryKind(absPath: string, relPath: string, entry: ReturnType<Dir["readSync"]>): FallbackEntryKind {
+	if (!entry) return "disappeared";
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	try {
+		// Some network and facility filesystems report DT_UNKNOWN. Inspect those
+		// entries rather than treating a potentially populated directory as a
+		// special file and silently omitting its subtree.
+		const stat = fs.lstatSync(absPath);
+		if (stat.isDirectory()) return "directory";
+		if (stat.isFile()) return "file";
+		return "other";
+	} catch (cause) {
+		if (isDisappearedWorkspaceEntry(cause)) return "disappeared";
+		throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, cause);
+	}
+}
+
+function closeFrame(frame: WalkFrame): void {
+	try {
+		frame.dir.closeSync();
+	} catch {
+		// Best-effort cleanup after an unreadable directory or bounded failure.
+	}
+}
+
+/**
+ * The bounded walk as a step generator: one yield per processed entry, so a
+ * synchronous driver drains it in place and the async driver interleaves a
+ * cooperative tick between steps. One body means the two forms cannot drift on
+ * limit enforcement, symlink policy, or failure classification. `elapsedMs`
+ * feeds the time limit: the sync driver passes wall time, the async driver
+ * passes accumulated walk time so event-loop turns spent elsewhere do not
+ * count against the walk's own budget.
+ */
+function* fallbackFilesWalk(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	limits: WorkspaceFallbackLimits,
+	elapsedMs: () => number,
+): Generator<void, string[]> {
+	let visitedEntries = 0;
+	let pathBytes = 0;
+	let root: Dir;
+	try {
+		root = fs.opendirSync(cwd);
+	} catch (cause) {
+		throw new WorkspaceEnumerationIncompleteError("open-root", ".", cause);
+	}
+	const stack: WalkFrame[] = [{ dir: root, absPath: cwd, prefix: "", depth: 0 }];
+	const files: string[] = [];
+	try {
+		while (stack.length > 0) {
+			yield;
+			if (elapsedMs() >= limits.maxDurationMs) {
+				throw new WorkspaceEnumerationLimitError("time", limits.maxDurationMs);
+			}
+			const frame = stack.at(-1);
+			if (!frame) break;
+			let entry: ReturnType<Dir["readSync"]>;
+			try {
+				entry = frame.dir.readSync();
+			} catch (cause) {
+				throw new WorkspaceEnumerationIncompleteError("read-directory", frame.prefix || ".", cause);
+			}
+			if (!entry) {
+				closeFrame(frame);
+				stack.pop();
+				continue;
+			}
+
+			visitedEntries += 1;
+			if (visitedEntries > limits.maxVisitedEntries) {
+				throw new WorkspaceEnumerationLimitError("entries", limits.maxVisitedEntries);
+			}
+			const depth = frame.depth + 1;
+			if (depth > limits.maxDepth) {
+				throw new WorkspaceEnumerationLimitError("depth", limits.maxDepth);
+			}
+			const relPath = frame.prefix.length > 0 ? `${frame.prefix}/${entry.name}` : entry.name;
+			pathBytes += Buffer.byteLength(relPath, "utf8");
+			if (pathBytes > limits.maxPathBytes) {
+				throw new WorkspaceEnumerationLimitError("path-bytes", limits.maxPathBytes);
+			}
+			const absPath = join(frame.absPath, entry.name);
+			const kind = fallbackEntryKind(absPath, relPath, entry);
+			if (kind === "disappeared" || kind === "other") continue;
+			if (kind === "directory") {
+				if (excludedDirs.has(entry.name)) continue;
+				let child: Dir;
+				try {
+					child = fs.opendirSync(absPath);
+				} catch (cause) {
+					if (isDisappearedWorkspaceEntry(cause)) continue;
+					throw new WorkspaceEnumerationIncompleteError("open-directory", relPath, cause);
+				}
+				stack.push({ dir: child, absPath, prefix: relPath, depth });
+				continue;
+			}
+			// Only direct or lstat-confirmed regular files reach this branch;
+			// symlinks and special files remain excluded, matching the Git path.
+			files.push(relPath);
+		}
+		return files;
+	} finally {
+		for (const frame of stack) closeFrame(frame);
+	}
+}
+
+function fallbackFiles(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	overrides?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const limits = resolveFallbackLimits(overrides);
+	const startedAt = performance.now();
+	const walk = fallbackFilesWalk(cwd, excludedDirs, limits, () => performance.now() - startedAt);
+	let step = walk.next();
+	while (!step.done) step = walk.next();
+	return step.value;
+}
+
+async function fallbackFilesAsync(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	overrides: Partial<WorkspaceFallbackLimits> | undefined,
+	cooperate: WorkspaceEnumerationTick,
+): Promise<string[]> {
+	const limits = resolveFallbackLimits(overrides);
+	let activeMs = 0;
+	let resumedAt = performance.now();
+	const walk = fallbackFilesWalk(cwd, excludedDirs, limits, () => activeMs + (performance.now() - resumedAt));
+	let step = walk.next();
+	while (!step.done) {
+		activeMs += performance.now() - resumedAt;
+		await cooperate.tick();
+		resumedAt = performance.now();
+		step = walk.next();
+	}
+	return step.value;
+}
+
+/** Visibility validation as steps; one yield per path so the async driver can breathe. */
+function* normalizeVisibleFilesSteps(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot: boolean,
+): Generator<void, string[]> {
+	const visible = new Set<string>();
+	for (const path of paths) {
+		yield;
+		const normalized = normalizeRelativePath(path);
+		if (!normalized) {
+			if (requireCompleteSnapshot) {
+				throw new WorkspaceEnumerationIncompleteError("inspect-entry", path, { code: "INVALID_RELATIVE_PATH" });
+			}
+			continue;
+		}
+		if (isWorkspacePathExcluded(normalized, excludedDirs)) continue;
+		if (isRegularWorkspaceFile(cwd, normalized, requireCompleteSnapshot)) visible.add(normalized);
+	}
+	return [...visible].sort(comparePaths);
+}
+
+function normalizeVisibleFiles(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot = false,
+): string[] {
+	const steps = normalizeVisibleFilesSteps(cwd, paths, excludedDirs, requireCompleteSnapshot);
+	let step = steps.next();
+	while (!step.done) step = steps.next();
+	return step.value;
+}
+
+async function normalizeVisibleFilesAsync(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot: boolean,
+	cooperate: WorkspaceEnumerationTick,
+): Promise<string[]> {
+	const steps = normalizeVisibleFilesSteps(cwd, paths, excludedDirs, requireCompleteSnapshot);
+	let step = steps.next();
+	while (!step.done) {
+		await cooperate.tick();
+		step = steps.next();
+	}
+	return step.value;
+}
+
+/**
+ * List tracked files plus untracked, nonignored work in progress. Non-Git
+ * workspaces (and hosts without a usable Git binary) retain the filesystem
+ * walker behavior.
+ */
+export function enumerateWorkspaceFiles(
+	cwd: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const gitFiles = gitVisibleFiles(cwd);
+	if (gitFiles) return normalizeVisibleFiles(cwd, gitFiles, excludedDirs);
+	return normalizeVisibleFiles(cwd, fallbackFiles(cwd, excludedDirs, fallbackLimits), excludedDirs, true);
+}
+
+/**
+ * `enumerateWorkspaceFiles` without the synchronous floor: the `git ls-files`
+ * subprocess runs async, and both the per-path lstat validation and the
+ * non-Git fallback walk yield cooperatively. The bounded-walk contract is
+ * unchanged with one deliberate reading: the time limit meters the walk's own
+ * accumulated work rather than wall clock, so a busy event loop cannot fail an
+ * enumeration that did no more work than its budget allows.
+ */
+export async function enumerateWorkspaceFilesAsync(
+	cwd: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+	cooperate: WorkspaceEnumerationTick = createDefaultTick(),
+): Promise<string[]> {
+	const gitFiles = await gitVisibleFilesAsync(cwd);
+	if (gitFiles) return normalizeVisibleFilesAsync(cwd, gitFiles, excludedDirs, false, cooperate);
+	const walked = await fallbackFilesAsync(cwd, excludedDirs, fallbackLimits, cooperate);
+	return normalizeVisibleFilesAsync(cwd, walked, excludedDirs, true, cooperate);
+}
+
+/** Apply the same visibility rules to one incremental batch without walking the tree. */
+export function filterWorkspaceFileCandidates(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const candidates = paths
+		.map(normalizeRelativePath)
+		.filter((path): path is string => path !== null && !isWorkspacePathExcluded(path, excludedDirs));
+	if (candidates.length === 0) return [];
+	const gitFiles = gitVisibleFiles(cwd, candidates);
+	if (gitFiles) return normalizeVisibleFiles(cwd, gitFiles, excludedDirs);
+	// Outside Git, incremental candidates must be reconciled against the same
+	// complete bounded snapshot as a full build. Otherwise a notification can
+	// add a path that a bounded full scan could not authoritatively enumerate.
+	const fallbackVisible = new Set(
+		normalizeVisibleFiles(cwd, fallbackFiles(cwd, excludedDirs, fallbackLimits), excludedDirs, true),
+	);
+	return candidates.filter((path) => fallbackVisible.has(path)).sort(comparePaths);
+}

package/src/core/xdg.ts

@@ -0,0 +1,177 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Resolve per-platform config/data/state/cache directories for Clio.
+ *
+ * This is the single resolution order, documented once:
+ *   1. Platform defaults.
+ *      Linux: XDG Base Directory spec (XDG_CONFIG_HOME, XDG_DATA_HOME,
+ *      XDG_STATE_HOME, XDG_CACHE_HOME).
+ *      macOS: ~/Library/Application Support/clio-coder/{config,data,state} and
+ *      ~/Library/Caches/clio-coder.
+ *      Windows: %APPDATA%/clio-coder/{config,data} and %LOCALAPPDATA%/clio-coder/{state,cache}.
+ *      Every root is distinct on every platform; no root nests inside another.
+ *   2. CLIO_CODER_HOME replaces all four roots symmetrically with
+ *      CLIO_CODER_HOME/{config,data,state,cache}.
+ *   3. CLIO_CODER_CONFIG_DIR / CLIO_CODER_DATA_DIR / CLIO_CODER_STATE_DIR / CLIO_CODER_CACHE_DIR each
+ *      override their one root and beat CLIO_CODER_HOME (most specific wins).
+ *
+ * Role contents: config holds user-authored files (settings, credentials,
+ * agents, skills, prompts, extensions, runtimes); data holds durable artifacts
+ * (memory, evidence, evals); state holds machine-produced session state
+ * (sessions, audit, receipts, runs.json, recent-models.json, install.json,
+ * interviews, scratch); cache holds disposable derived files.
+ */
+
+export interface ClioDirs {
+	config: string;
+	data: string;
+	state: string;
+	cache: string;
+}
+
+let cachedConfigDir: string | undefined;
+let cachedDataDir: string | undefined;
+let cachedStateDir: string | undefined;
+let cachedCacheDir: string | undefined;
+
+function envOrNull(key: string): string | null {
+	const v = process.env[key]?.trim();
+	return v && v.length > 0 ? v : null;
+}
+
+function platformDefaults(): ClioDirs {
+	const p = platform();
+	const h = homedir();
+	if (p === "win32") {
+		const appData = process.env.APPDATA ?? join(h, "AppData", "Roaming");
+		const localAppData = process.env.LOCALAPPDATA ?? join(h, "AppData", "Local");
+		return {
+			config: join(appData, "clio-coder", "config"),
+			data: join(appData, "clio-coder", "data"),
+			state: join(localAppData, "clio-coder", "state"),
+			cache: join(localAppData, "clio-coder", "cache"),
+		};
+	}
+	if (p === "darwin") {
+		const base = join(h, "Library", "Application Support", "clio-coder");
+		return {
+			config: join(base, "config"),
+			data: join(base, "data"),
+			state: join(base, "state"),
+			cache: join(h, "Library", "Caches", "clio-coder"),
+		};
+	}
+	const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(h, ".config");
+	const xdgData = process.env.XDG_DATA_HOME ?? join(h, ".local", "share");
+	const xdgState = process.env.XDG_STATE_HOME ?? join(h, ".local", "state");
+	const xdgCache = process.env.XDG_CACHE_HOME ?? join(h, ".cache");
+	return {
+		config: join(xdgConfig, "clio-coder"),
+		data: join(xdgData, "clio-coder"),
+		state: join(xdgState, "clio-coder"),
+		cache: join(xdgCache, "clio-coder"),
+	};
+}
+
+function ensureDir(dir: string): string {
+	try {
+		mkdirSync(dir, { recursive: true });
+	} catch (err) {
+		const e = err as NodeJS.ErrnoException;
+		if (e.code !== "EEXIST") throw err;
+	}
+	const s = statSync(dir);
+	if (!s.isDirectory()) throw new Error(`Expected directory at ${dir}`);
+	return dir;
+}
+
+function clioHomeOrNull(): string | null {
+	return envOrNull("CLIO_CODER_HOME");
+}
+
+function resolveRole(specificVar: string, role: keyof ClioDirs, defaults: ClioDirs): string {
+	const specific = envOrNull(specificVar);
+	if (specific) return specific;
+	const home = clioHomeOrNull();
+	if (home) return join(home, role);
+	return defaults[role];
+}
+
+export function resolveClioDirs(): ClioDirs {
+	const defaults = platformDefaults();
+	return {
+		config: resolveRole("CLIO_CODER_CONFIG_DIR", "config", defaults),
+		data: resolveRole("CLIO_CODER_DATA_DIR", "data", defaults),
+		state: resolveRole("CLIO_CODER_STATE_DIR", "state", defaults),
+		cache: resolveRole("CLIO_CODER_CACHE_DIR", "cache", defaults),
+	};
+}
+
+export function clioConfigDir(): string {
+	if (cachedConfigDir) return cachedConfigDir;
+	cachedConfigDir = ensureDir(resolveClioDirs().config);
+	return cachedConfigDir;
+}
+
+export function clioDataDir(): string {
+	if (cachedDataDir) return cachedDataDir;
+	cachedDataDir = ensureDir(resolveClioDirs().data);
+	return cachedDataDir;
+}
+
+export function clioStateDir(): string {
+	if (cachedStateDir) return cachedStateDir;
+	cachedStateDir = ensureDir(resolveClioDirs().state);
+	return cachedStateDir;
+}
+
+export function clioCacheDir(): string {
+	if (cachedCacheDir) return cachedCacheDir;
+	cachedCacheDir = ensureDir(resolveClioDirs().cache);
+	return cachedCacheDir;
+}
+
+export function clioStatePath(): string {
+	return cachedStateDir ?? resolveClioDirs().state;
+}
+
+/**
+ * True when the state root this process resolved is no longer on disk.
+ *
+ * `clio-coder uninstall` removes the whole root while processes holding session
+ * writers, ledgers and audit files are still running, and every writer under
+ * the root mkdirs its parent back: `safeResourceWrite` does it before the temp
+ * file, the state file lock does it before the critical section, the audit
+ * writer does it before opening the day's file. A write landing after the
+ * removal therefore recreated the state home, so an uninstall that reported
+ * success left one behind and the next `clio-coder` start read state from a home that
+ * was supposed to be gone. The live case was the shutdown checkpoint, roughly
+ * two minutes late, rebuilding the root around a meta.json and tree.json that
+ * announced `lastCheckpointReason: shutdown`.
+ *
+ * "Removed" and "never created" are not the same thing, and only the first is a
+ * reason to refuse a write. With no cached root this process has not resolved
+ * one yet, so a writer creating it is an ordinary first run; the audit writer
+ * reaches its first row before anything else has called `clioStateDir()`, and
+ * treating that as an uninstall silently disabled audit on a fresh install.
+ * Reads the cache directly rather than `clioStateDir()` because the latter
+ * creates the directory it is being asked about.
+ *
+ * Every writer under the state root calls this before it touches disk, and
+ * again inside whatever lock it holds, because the removal can land while the
+ * call waits for a sibling process to leave its critical section.
+ */
+export function stateRootRemoved(): boolean {
+	if (cachedStateDir === undefined) return false;
+	return !existsSync(cachedStateDir);
+}
+
+export function resetXdgCache(): void {
+	cachedConfigDir = undefined;
+	cachedDataDir = undefined;
+	cachedStateDir = undefined;
+	cachedCacheDir = undefined;
+}

package/src/domains/agents/builtins/architect.md

@@ -4,7 +4,7 @@ name: Architect
 description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
 tools:
   required: [artifact, context]
-  optional: [read, grep, find, ls, code_nav, git]
+  optional: [read, grep, find, ls, code_nav, git, ledger]
 skills: [cut-it]
 audience: base
 category: plan
@@ -12,7 +12,7 @@ capabilityClass: artifact-write
 latencyClass: deep
 projectContextTier: bounded
 budget: {toolCalls: 32, readReserve: 5, synthesis: true}
-resultContract: {kind: architect-plan, path: PLAN.md}
+resultContract: {kind: architect-plan, path: .clio-coder/artifacts/PLAN.md}
 tags: [architecture, boundaries, migration]
 ---
 
@@ -27,7 +27,7 @@ Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely
 Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
 Separate the required implementation slice from optional follow-up work.
 Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.
-Use `artifact` (kind="plan") only when the result should become a reviewable `PLAN.md`.
+Use `artifact` (kind="plan") only when the result should become a reviewable plan document.
 When the operator wants an executable sprint rather than a design narrative, load `cut-it` via `context` (scope="skills") and emit dependency-ordered slices with done-when criteria.
 Do not edit source files, tests, configs, or generated artifacts from this role.
-Write the plan with `artifact` (kind="plan") at `PLAN.md`. The integrity-recorded `PLAN.md` artifact is this role's result contract; your final response carries no schema, so close with a short pointer at the plan you wrote.
+Write the plan with `artifact` (kind="plan") and no path argument, which lands it at `.clio-coder/artifacts/PLAN.md`. That integrity-recorded artifact is this role's result contract; your final response carries no schema, so close with a short pointer at the plan you wrote.