@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/cli/doctor-slurm.ts

@@ -0,0 +1,130 @@
+import { tmpdir } from "node:os";
+import { runCommandVector } from "../core/safe-exec.js";
+import { resolveClioDirs } from "../core/xdg.js";
+import { resolveMcpServers } from "../domains/gateway/mcp/index.js";
+import { resolveOnPath } from "../domains/interop/detect.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+
+const PROBE_TIMEOUT_MS = 5_000;
+const PROBE_MAX_OUTPUT_BYTES = 16 * 1024;
+const GUIDE = "docs/guide/slurm.md";
+
+export interface SlurmMcpOptions {
+	workspaceRoot?: string;
+	/** Skip the declaration lookup: reading it would resolve the config root. */
+	untouched?: boolean;
+	timeoutMs?: number;
+	/** Override for the user config directory (tests). */
+	configDir?: string;
+}
+
+async function run(binary: string, args: string[], timeoutMs: number): Promise<{ ok: boolean; text: string }> {
+	const cwd = tmpdir();
+	const result = await runCommandVector(binary, args, {
+		cwd,
+		workspaceRoot: cwd,
+		timeoutMs,
+		maxOutputBytes: PROBE_MAX_OUTPUT_BYTES,
+	});
+	return { ok: !result.timedOut && result.exitCode === 0, text: `${result.stdout}\n${result.stderr}` };
+}
+
+/** `clio-kit` has shipped without `--version`; the server listing still says whether Slurm is in this build. */
+async function clioKitDetail(binary: string, timeoutMs: number): Promise<string> {
+	const version = await run(binary, ["--version"], timeoutMs);
+	const versionLine = version.ok
+		? (version.text
+				.split(/\r?\n/)
+				.map((line) => line.trim())
+				.find((line) => /\d+\.\d+/.test(line)) ?? "version not reported")
+		: "version not reported (no --version)";
+	const listing = await run(binary, ["mcp-servers"], timeoutMs);
+	const ships = listing.ok
+		? /^\s*-?\s*slurm\s*$/mu.test(listing.text)
+			? "ships the slurm server"
+			: "does not list a slurm server"
+		: "its server listing could not be read";
+	return `${binary}: ${versionLine}; ${ships}`;
+}
+
+function isSlurmServer(server: { command: string; args: ReadonlyArray<string> }): boolean {
+	const words = [server.command, ...server.args];
+	const at = words.indexOf("mcp-server");
+	return at !== -1 && words[at + 1] === "slurm" && /(^|\/)clio-kit$/u.test(words[at - 1] ?? server.command);
+}
+
+/**
+ * Slurm through the clio-kit MCP server: whether `clio-kit` is on PATH, whether
+ * an `mcp.yaml` declares its Slurm server, and whether the scheduler clients
+ * exist. Most installs use none of this, so nothing here is ever a failure,
+ * and an install with none of the three gets one informational row.
+ */
+export async function slurmMcpFindings(options: SlurmMcpOptions = {}): Promise<DoctorFinding[]> {
+	const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+	const clioKit = resolveOnPath(["clio-kit"]);
+	const sbatch = resolveOnPath(["sbatch"]);
+	const squeue = resolveOnPath(["squeue"]);
+	const declared =
+		options.untouched === true
+			? []
+			: resolveMcpServers({
+					cwd: options.workspaceRoot ?? process.cwd(),
+					configDir: options.configDir ?? resolveClioDirs().config,
+				}).servers.filter(isSlurmServer);
+
+	const kitPresent = clioKit.presence === "present" && clioKit.binary !== undefined;
+	const schedulerPresent = sbatch.presence === "present" || squeue.presence === "present";
+	if (!kitPresent && declared.length === 0 && !schedulerPresent) {
+		return [
+			{
+				ok: true,
+				level: "info",
+				name: "slurm mcp",
+				detail: `not set up: clio-kit, sbatch, and squeue are not on PATH and no mcp.yaml declares the Slurm server; see ${GUIDE}`,
+			},
+		];
+	}
+
+	const findings: DoctorFinding[] = [];
+	findings.push(
+		kitPresent
+			? { ok: true, level: "ok", name: "slurm clio-kit", detail: await clioKitDetail(clioKit.binary as string, timeoutMs) }
+			: { ok: true, level: "info", name: "slurm clio-kit", detail: `not on PATH; see ${GUIDE}` },
+	);
+	findings.push(
+		declared.length > 0
+			? {
+					ok: true,
+					level: declared.every((server) => server.trust.status === "trusted") ? "ok" : "info",
+					name: "slurm mcp server",
+					detail: declared
+						.map((server) => {
+							const trust =
+								server.trust.status === "trusted"
+									? `trusted, action class ${server.trust.actionClass}`
+									: `${server.trust.status}; run clio-coder mcp trust ${server.id}`;
+							return `${server.id} declared in ${server.path} (${server.scope}, ${trust})`;
+						})
+						.join("; "),
+				}
+			: {
+					ok: true,
+					level: "info",
+					name: "slurm mcp server",
+					detail: `no mcp.yaml entry runs clio-kit mcp-server slurm; see ${GUIDE}`,
+				},
+	);
+	const clients = [
+		["sbatch", sbatch],
+		["squeue", squeue],
+	] as const;
+	findings.push({
+		ok: true,
+		level: schedulerPresent ? "ok" : "info",
+		name: "slurm scheduler",
+		detail: clients
+			.map(([name, found]) => `${name} ${found.presence === "present" ? found.binary : "not on PATH"}`)
+			.join("; "),
+	});
+	return findings;
+}

package/src/cli/doctor-task-worktrees.ts

@@ -0,0 +1,88 @@
+import { readSettings } from "../core/config.js";
+import { rawDurationMs } from "../core/timers.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import { gitCheckoutRoot, listPreservedTaskWorktrees, type PreservedTaskWorktree } from "../tools/task-worktree.js";
+import {
+	allowedWorktreeParents,
+	HOST_WORKTREE_ROOT_FACTS,
+	resolveWorktreeRoot,
+	type WorktreeRootFacts,
+} from "../tools/worktree-root.js";
+
+function ageLabel(createdAt: string | null, now: number): string {
+	const created = createdAt === null ? Number.NaN : Date.parse(createdAt);
+	if (!Number.isFinite(created)) return "age unknown";
+	// A clock that stepped backwards renders as new, not as a negative age.
+	const minutes = Math.floor(Math.max(0, rawDurationMs(created, now)) / 60_000);
+	if (minutes < 60) return `${minutes}m old`;
+	const hours = Math.floor(minutes / 60);
+	return hours < 48 ? `${hours}h old` : `${Math.floor(hours / 24)}d old`;
+}
+
+function describe(entry: PreservedTaskWorktree, now: number): string {
+	return (
+		`${entry.branch} (${entry.state}, ${ageLabel(entry.createdAt, now)}, ${entry.reason}): ` +
+		`inspect with git log ${entry.base}..${entry.branch}; drop with git worktree remove --force ${entry.path} && ` +
+		`git branch -D ${entry.branch} && rm ${entry.claimPath}`
+	);
+}
+
+export interface TaskWorktreeFindingOptions {
+	now?: number;
+	/** `fleet.worktrees.root`; read from settings when absent. */
+	rootSetting?: string;
+	remoteEligible?: boolean;
+	facts?: WorktreeRootFacts;
+}
+
+function configuredRoot(): { setting: string; remoteEligible: boolean } {
+	try {
+		const fleet = readSettings().fleet;
+		return { setting: fleet.worktrees.root, remoteEligible: fleet.nodes.length > 0 };
+	} catch {
+		return { setting: "disk", remoteEligible: false };
+	}
+}
+
+function formatGiB(bytes: number | null): string {
+	return bytes === null ? "free space unknown" : `${(bytes / 1024 ** 3).toFixed(1)} GiB free`;
+}
+
+/**
+ * Task worktrees (`worktree: true` dispatch): where the next one would be
+ * created, and every one that outlived its run. Doctor only reads: it never
+ * removes one, because each may hold the only copy of a worker's changes.
+ */
+export function taskWorktreeFindings(workspaceRoot: string, options: TaskWorktreeFindingOptions = {}): DoctorFinding[] {
+	const root = gitCheckoutRoot(workspaceRoot);
+	if (root === null) return [];
+	const now = options.now ?? Date.now();
+	const facts = options.facts ?? HOST_WORKTREE_ROOT_FACTS;
+	const configured = options.rootSetting === undefined ? configuredRoot() : null;
+	const setting = options.rootSetting ?? configured?.setting ?? "disk";
+	const remoteEligible = options.remoteEligible ?? configured?.remoteEligible ?? false;
+	const resolved = resolveWorktreeRoot({ setting, projectRoot: root, remoteEligible, facts });
+	const measured = resolved.base ?? root;
+	const rootFinding: DoctorFinding = {
+		ok: true,
+		level: resolved.notice === undefined ? "ok" : "warn",
+		name: "task worktree root",
+		detail:
+			`fleet.worktrees.root ${setting}: ${resolved.parent} (${facts.filesystemType(measured) ?? "unknown filesystem"}, ` +
+			`${formatGiB(facts.freeBytes(measured))})${resolved.notice === undefined ? "" : `; ${resolved.notice}`}`,
+	};
+	const preserved = listPreservedTaskWorktrees(root, allowedWorktreeParents(setting, root, facts));
+	if (preserved.length === 0) {
+		return [rootFinding, { ok: true, name: "task worktrees", detail: "none preserved" }];
+	}
+	return [
+		rootFinding,
+		...preserved.map((entry) => ({
+			ok: true,
+			// A run keeps its worktree on purpose; a crash leaving work behind wants a look.
+			level: entry.state === "settled" ? ("info" as const) : ("warn" as const),
+			name: `task worktree ${entry.runId}`,
+			detail: describe(entry, now),
+		})),
+	];
+}

package/src/cli/doctor.ts

@@ -1,5 +1,6 @@
 import { readSettings } from "../core/config.js";
 import {
+	type DoctorFinding,
 	formatDoctorReport,
 	isUninitializedHome,
 	runDoctor,
@@ -8,14 +9,19 @@ import {
 	runDoctorModelChecks,
 	runDoctorRuntimeChecks,
 } from "../domains/lifecycle/doctor.js";
+import type { ProvidersContract } from "../domains/providers/contract.js";
+import { type AutonomyLevel, DEFAULT_AUTONOMY_LEVEL } from "../domains/safety/autonomy.js";
+import { hpcToolchainFindings } from "./doctor-hpc.js";
 import { namingFootprintFindings } from "./doctor-naming.js";
 import { panesFindings } from "./doctor-panes.js";
+import { slurmMcpFindings } from "./doctor-slurm.js";
 import { stateStorageFinding } from "./doctor-state-size.js";
+import { taskWorktreeFindings } from "./doctor-task-worktrees.js";
 import { toolchainFindings } from "./doctor-toolchain.js";
 import { validationContractFinding } from "./doctor-validation-contract.js";
 import { printError } from "./shared.js";
 
-const HELP = `clio-coder doctor [--fix] [--json]
+const HELP = `clio-coder doctor [--fix] [--json] [--deep [--tools-timeout <seconds>]]
 
 Diagnose Clio Coder state without creating files. On a home Clio has never
 written to, doctor says so in one row and exits 0. Use --fix to repair structure:
@@ -24,21 +30,86 @@ missing directories, missing template files, and credential permissions.
 dispatch for the current project root; plain doctor only reports it.
 Settings are validated directly against the current schema.
 Pass --json to emit a machine-readable report on stdout.
+--deep adds a live tool-call probe on every configured target, which can load
+a cold local model and releases it afterwards, and a dry run of the workspace
+validation contract that resolves each validator command and reports whether
+it would run without an approval ask at the configured autonomy. The dry run
+executes nothing. --tools-timeout bounds each tool probe (default 120).
 `;
 
-export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promise<number> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(HELP);
-		return 0;
+export interface DoctorDeepOptions {
+	/** The providers contract to probe with; the CLI loads its own when absent. */
+	providers?: ProvidersContract;
+	/** Tool-probe generation timeout in ms. */
+	toolsTimeoutMs?: number;
+	/** Autonomy the dry run judges against; the configured level when absent. */
+	autonomy?: AutonomyLevel;
+}
+
+export interface DoctorCollectOptions {
+	fix?: boolean;
+	/** Run the deep checks as well. */
+	deep?: DoctorDeepOptions | false;
+	workspaceRoot?: string;
+}
+
+function configuredAutonomy(): AutonomyLevel {
+	try {
+		return readSettings().safety.autonomy;
+	} catch {
+		return DEFAULT_AUTONOMY_LEVEL;
 	}
-	const fix = args.includes("--fix");
-	const json = args.includes("--json");
-	const unknown = args.find((arg) => arg !== "--fix" && arg !== "--json");
-	if (unknown) {
-		printError(`unknown flag: ${unknown}`);
-		process.stderr.write(HELP);
-		return 2;
+}
+
+async function deepFindings(
+	untouched: boolean,
+	workspaceRoot: string,
+	deep: DoctorDeepOptions,
+): Promise<DoctorFinding[]> {
+	// Loaded on demand, as the model sweep loads the runtimes: plain doctor
+	// never pays for the providers domain or the policy engine.
+	const { contractDryRunFindings, deepToolProbeFindings } = await import("./doctor-deep.js");
+	const probeOptions = deep.toolsTimeoutMs !== undefined ? { toolsTimeoutMs: deep.toolsTimeoutMs } : {};
+	let toolRows: DoctorFinding[] = [];
+	if (deep.providers) {
+		toolRows = await deepToolProbeFindings(deep.providers, probeOptions);
+	} else if (!untouched) {
+		// The providers domain is loaded only when there is a target to probe:
+		// loading it on a home with no targets would cost a domain boot for
+		// nothing, and on an untouched home there are no settings to read.
+		let targetCount = 0;
+		try {
+			targetCount = readSettings().targets.length;
+		} catch {
+			// The settings row already reports an unreadable document.
+		}
+		if (targetCount > 0) {
+			const [{ loadDomains }, { ConfigDomainModule }, { ProvidersDomainModule }] = await Promise.all([
+				import("../core/domain-loader.js"),
+				import("../domains/config/index.js"),
+				import("../domains/providers/index.js"),
+			]);
+			const loaded = await loadDomains([ConfigDomainModule, ProvidersDomainModule]);
+			try {
+				const providers = loaded.getContract<ProvidersContract>("providers");
+				if (providers) toolRows = await deepToolProbeFindings(providers, probeOptions);
+			} finally {
+				await loaded.stop();
+			}
+		}
 	}
+	const contractRows = contractDryRunFindings({ workspaceRoot, autonomy: deep.autonomy ?? configuredAutonomy() });
+	return [...toolRows, ...contractRows];
+}
+
+/**
+ * Every doctor check in report order. The CLI prints these; the TUI's
+ * `/doctor` renders the same list in-session and passes its own providers
+ * contract so the deep probe runs against the session's targets.
+ */
+export async function collectDoctorFindings(options: DoctorCollectOptions = {}): Promise<DoctorFinding[]> {
+	const fix = options.fix === true;
+	const workspaceRoot = options.workspaceRoot ?? process.cwd();
 	// Decided before runDoctor so a --fix run, which initializes the home, still
 	// gets every check on the home it just built.
 	const untouched = !fix && isUninitializedHome();
@@ -65,11 +136,18 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	const interopChecks = untouched ? [] : await runDoctorInteropChecks();
 	// Fleet preflight probes each configured node over SSH and persists the
 	// per-node eligibility verdicts dispatch placement enforces.
-	const fleetChecks = untouched ? [] : await runDoctorFleetChecks(process.cwd(), { fix });
+	const fleetChecks = untouched ? [] : await runDoctorFleetChecks(workspaceRoot, { fix });
 	// Resolution reads PATH and the vendor root and creates nothing, but on an
 	// untouched home there is no vendor root to look at and the answer would be
 	// "none" for every row regardless, so the sweep stays with the others.
 	const toolChecks = untouched ? [] : toolchainFindings({ panesEnabled, filesEnabled });
+	// Compilers, MPI, build systems, and the scheduler. Each probe resolves PATH
+	// and runs a bounded `--version` in a scratch directory, so it creates
+	// nothing and runs on an untouched home too.
+	const hpcChecks = await hpcToolchainFindings({ workspaceRoot });
+	// Slurm through the clio-kit MCP server. PATH lookups and two bounded
+	// clio-kit spawns; the mcp.yaml lookup is skipped on an untouched home.
+	const slurmChecks = await slurmMcpFindings({ workspaceRoot, untouched });
 	// The pane sweep pings a socket and reads PATH; it creates nothing except the
 	// journal directory it is asked about, which is inside the state root doctor
 	// has already agreed not to build on an untouched home.
@@ -77,8 +155,12 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	const namingChecks = namingFootprintFindings({ fix, yaziEnabled: filesEnabled });
 	// The validation contract lives in the workspace, not the home, so it is
 	// checked on every run: a broken contract is why rigor stayed normal.
-	const contractChecks = [validationContractFinding()];
-	const all = [
+	const contractChecks = [validationContractFinding(workspaceRoot)];
+	// Task worktrees live in the workspace too. The sweep reads claims and asks
+	// git; it removes nothing.
+	const worktreeChecks = taskWorktreeFindings(workspaceRoot);
+	const deepChecks = options.deep ? await deepFindings(untouched, workspaceRoot, options.deep) : [];
+	return [
 		...findings,
 		...storageChecks,
 		...runtimeChecks,
@@ -86,13 +168,80 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 		...interopChecks,
 		...fleetChecks,
 		...toolChecks,
+		...hpcChecks,
+		...slurmChecks,
 		...paneChecks,
 		...namingChecks,
 		...contractChecks,
+		...worktreeChecks,
+		...deepChecks,
 	];
+}
+
+/**
+ * In-session diagnostics: structured findings for the TUI card, plus the plain
+ * report for hosts without a card renderer, at the level of the worst row.
+ */
+export function doctorNotice(findings: ReadonlyArray<DoctorFinding>): {
+	level: "success" | "warn" | "error";
+	text: string;
+	findings: ReadonlyArray<DoctorFinding>;
+} {
+	const errors = findings.filter((f) => !f.ok).length;
+	const warnings = findings.filter((f) => f.ok && f.level === "warn").length;
+	const level = errors > 0 ? "error" : warnings > 0 ? "warn" : "success";
+	const head = `doctor: ${findings.length} checks, ${errors} error(s), ${warnings} warning(s)`;
+	return { level, text: `${head}\n${formatDoctorReport([...findings])}`, findings };
+}
+
+interface DoctorArgs {
+	fix: boolean;
+	json: boolean;
+	deep: boolean;
+	toolsTimeoutMs?: number;
+}
+
+function parseDoctorArgs(args: ReadonlyArray<string>): DoctorArgs {
+	const parsed: DoctorArgs = { fix: false, json: false, deep: false };
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--fix") parsed.fix = true;
+		else if (arg === "--json") parsed.json = true;
+		else if (arg === "--deep") parsed.deep = true;
+		else if (arg === "--tools-timeout") {
+			const value = args[i + 1];
+			const seconds = value === undefined ? Number.NaN : Number(value);
+			if (!Number.isFinite(seconds) || seconds <= 0)
+				throw new Error("--tools-timeout requires a positive number of seconds");
+			parsed.toolsTimeoutMs = Math.round(seconds * 1000);
+			i += 1;
+		} else throw new Error(`unknown flag: ${arg}`);
+	}
+	if (parsed.toolsTimeoutMs !== undefined && !parsed.deep) throw new Error("--tools-timeout requires --deep");
+	return parsed;
+}
+
+export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	let parsed: DoctorArgs;
+	try {
+		parsed = parseDoctorArgs(args);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		process.stderr.write(HELP);
+		return 2;
+	}
+	const { fix, json } = parsed;
+	const all = await collectDoctorFindings({
+		fix,
+		deep: parsed.deep ? (parsed.toolsTimeoutMs !== undefined ? { toolsTimeoutMs: parsed.toolsTimeoutMs } : {}) : false,
+	});
 	const ok = all.every((f) => f.ok);
 	if (json) {
-		process.stdout.write(`${JSON.stringify({ ok, fix, findings: all }, null, 2)}\n`);
+		process.stdout.write(`${JSON.stringify({ ok, fix, deep: parsed.deep, findings: all }, null, 2)}\n`);
 	} else {
 		process.stdout.write(`${formatDoctorReport(all)}\n`);
 	}

package/src/cli/fleet-verify.ts

@@ -9,8 +9,9 @@
  * rather than inside it.
  *
  * Like `evidence inspect --json` it takes an identifier, because an operator
- * names the run. A GUI host may only pass back a run id it served inside its
- * current bounded window; see `apps/workbench/artifact-allowlist.ts`.
+ * names the run. The identifier is validated for shape here; a GUI host that
+ * echoes operator-supplied ids owes its own served-id window on top of that,
+ * because shape alone does not prove the id was ever served.
  */
 
 import { readFileSync } from "node:fs";

package/src/cli/gui.ts

@@ -0,0 +1,111 @@
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolvePackageRoot } from "../core/package-root.js";
+import { printError } from "./argv.js";
+
+const HELP = `Clio Coder graphical application
+
+Usage:
+  clio-coder gui [--open] [--port <0-65535>]
+  clio-coder gui background install [--open] [--port <1-65535>]
+  clio-coder gui background status|start|open|stop|uninstall
+  clio-coder gui launcher install|status|uninstall
+
+The foreground server prints a private launch link. --open opens your default
+browser. Press Ctrl+C to stop. --no-open explicitly disables browser opening.
+Optional --idle-exit <milliseconds> stops an idle foreground server.
+Use --path </app/path> to open a particular page. --reuse-background uses this
+installation's background app when configured, or starts a foreground server.
+
+On Linux with a systemd user session, background install keeps the app available
+at login. Open its launch link once, then install it from your browser. Background
+stop stops it now; background uninstall also removes its login and desktop entries.
+Other platforms can run the foreground app. Your CLI, terminal interface,
+headless runs, and graphical app use the same Clio runtime and configuration.
+`;
+
+export async function runGuiCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	try {
+		const root = resolvePackageRoot();
+		process.env.CLIO_CODER_PACKAGE_ROOT = root;
+		const entry = join(root, "dist/gui/server.js");
+		if (!existsSync(entry)) {
+			printError("The graphical application has not been built here. Run `pnpm run build` in this checkout.");
+			return 2;
+		}
+		// A URL keeps this a separate entry; bundling it into the command chunk
+		// would change import.meta.url and the worker/client paths beside it.
+		const server = await import(pathToFileURL(entry).href);
+		await server.main(args);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not start the graphical application.");
+		return 1;
+	}
+}
+
+/** Separate packaged entry; inspection never starts a listener or opens a browser. */
+export interface GuiUninstallPlan {
+	items: Array<{ label: string; path: string }>;
+	/**
+	 * Graphical-application files this build can see and cannot remove, because it
+	 * carries no application bundle to verify their ownership or stop their service.
+	 * Uninstall reports them and leaves them, together with the state they depend on.
+	 */
+	unmanaged: Array<{ label: string; path: string }>;
+	remove(): Promise<void>;
+}
+
+/** The command that removes what `unmanaged` lists, from a build that includes the application. */
+export const GUI_UNINSTALL_ADVICE = {
+	lead: "To remove them, run from a build that includes the graphical application:",
+	command: "clio-coder gui background uninstall && clio-coder gui launcher uninstall",
+} as const;
+
+export async function prepareGuiUninstall(options: {
+	stateDir: string;
+	desktopPrefix: string;
+	packageRoot?: string;
+}): Promise<GuiUninstallPlan> {
+	// Most CLI-only installs have no web lifecycle files. Keep that path lazy,
+	// including checkouts whose optional web bundle has not been built yet.
+	const paths = [
+		{ label: "Graphical background service", path: join(options.stateDir, "gui/background") },
+		{ label: "Desktop launcher", path: join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop") },
+		{
+			label: "Desktop launcher ownership record",
+			path: join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop.owner.json"),
+		},
+	];
+	const present = paths.filter(({ path }) => {
+		try {
+			lstatSync(path);
+			return true;
+		} catch (error) {
+			if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+			throw error;
+		}
+	});
+	if (!present.length)
+		return {
+			items: [],
+			unmanaged: [],
+			remove: async () => {
+				if ((await prepareGuiUninstall(options)).items.length)
+					throw new Error("A web installation appeared during confirmation; run uninstall again.");
+			},
+		};
+	const packageRoot = options.packageRoot ?? resolvePackageRoot();
+	const entry = join(packageRoot, "dist/gui/server.js");
+	// A terminal-only build has no bundle. Deleting these files blind could strand a running systemd
+	// unit or remove a launcher another installation owns, so they are reported and left alone.
+	if (!existsSync(entry)) return { items: [], unmanaged: present, remove: async () => {} };
+	const server = await import(pathToFileURL(entry).href);
+	const plan = await server.prepareGuiUninstall({ ...options, packageRoot });
+	return { ...plan, unmanaged: [] };
+}

package/src/cli/index.ts

@@ -30,7 +30,7 @@ science. CLIO stands for Context Layer for Input/Output, named for the Greek mus
 
 Usage:
   clio-coder                      start interactive repository chat
-  clio-coder web [--open]         start the browser application
+  clio-coder gui [--open]         start the graphical application
   clio-coder acp                  serve Clio as an ACP v1 agent over stdio
   clio-coder --acp                alias for clio-coder acp
   clio-coder run [flags] <task>   run one headless main-agent turn
@@ -79,8 +79,9 @@ Usage:
   clio-coder tools list|status|install|remove <id>  pinned external programs Clio can drive
   clio-coder interop inspect --json  detected external coding agents and how far each one is wired
   clio-coder panes install|theme  install the pane multiplexer (alias for 'tools install herdr'), or print Clio's theme as a herdr block
-  clio-coder docs [topic]         open documentation in the web app (--no-open to print the launch link)
+  clio-coder docs [topic]         open documentation in the graphical app (--no-open to print the launch link)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
+  clio-coder --demo|--no-demo      enable or disable interactive guidance for this session
   clio-coder --help, -h           this message
   clio-coder --help --all         this message plus every command under 'clio-coder dev'
 `;
@@ -158,6 +159,7 @@ async function main(argv: string[]): Promise<number> {
 		noSkills,
 		skillPaths,
 		panes,
+		demo,
 		autonomy,
 		rest,
 		error: globalFlagError,
@@ -187,6 +189,10 @@ async function main(argv: string[]): Promise<number> {
 		...(skillPaths.length > 0 ? { skillPaths } : {}),
 		...(panes === undefined ? {} : { panes }),
 	};
+	if (demo !== undefined && subcommand) {
+		printError("--demo and --no-demo apply to interactive sessions only; start clio-coder without a subcommand.");
+		return 2;
+	}
 	if (autonomy !== undefined && subcommand) {
 		// Silently dropping a safety level would be worse than refusing it.
 		printError(
@@ -197,7 +203,11 @@ async function main(argv: string[]): Promise<number> {
 	if (!subcommand) {
 		await enableBootCompileCache();
 		const { runClioCommand } = await import("./clio.js");
-		return runClioCommand({ ...bootOptions, ...(autonomy === undefined ? {} : { autonomy }) });
+		return runClioCommand({
+			...bootOptions,
+			...(demo === undefined ? {} : { demo }),
+			...(autonomy === undefined ? {} : { autonomy }),
+		});
 	}
 
 	return dispatch(subcommand, subArgs, bootOptions);
@@ -274,7 +284,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["tasks", async (subArgs) => (await import("./tasks.js")).runTasksCommand(subArgs)],
 	["mcp", async (subArgs) => (await import("./mcp.js")).runMcpCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
-	["web", async (subArgs) => (await import("./web.js")).runWebCommand(subArgs)],
+	["gui", async (subArgs) => (await import("./gui.js")).runGuiCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],
 	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],

package/src/cli/library.ts

@@ -288,6 +288,7 @@ export async function runLibraryCommand(
 							{
 								...entry,
 								provenance: record.origin,
+								copies: record.copies.filter((copy) => !options.scope || copy.scope === options.scope),
 								...(record.format ? { format: record.format } : {}),
 								...(record.provides ? { provides: record.provides } : {}),
 							},
@@ -297,13 +298,7 @@ export async function runLibraryCommand(
 			if (parsed.json) emit({ entries, diagnostics: discovery.diagnostics });
 			else {
 				for (const entry of entries) {
-					const states =
-						entry.installed
-							.map(
-								(item) =>
-									`${item.scope}:${item.loadable ? "loadable" : !item.enabled ? "disabled" : !item.effective ? "shadowed" : "unloadable"}`,
-							)
-							.join(", ") || "available";
+					const states = entry.copies.map((item) => `${item.scope}:${item.state}`).join(", ") || "available";
 					process.stdout.write(
 						`${libraryEntryRef(entry)}\t${entry.version ?? ""}\t${states}\t${originLabel(entry.provenance)}\t${entry.description}\n`,
 					);