@xlaunch/cli 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Portions Copyright (c) 2026 Northlatch Labs LLC
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# `@xlaunch/cli`
+
+Xlaunch is an AI agent that runs on your own computer. Give it a job and it does the work: it reads and writes files, runs the shell, browses the web, hands parts of the job to other agents, and keeps working on a schedule while you are away. This package is the `xlaunch` command.
+
+```sh
+npm install -g @xlaunch/cli
+xlaunch web
+```
+
+`xlaunch web` starts the Web UI at `http://127.0.0.1:3080` and opens it in your browser. On first run it asks for your Xlaunch Gateway address and key. Xlaunch needs Node.js 22.19 or newer. It is a product of Northlatch Labs LLC, released under the MIT licence.
+
+## For developers
+
+The `xlaunch` command is the sole supported Node application launcher: profiles are ordered stacks of plugin-bundle patch layers under the user's own overrides. SDK and ACP are profiles, not separate public bins. The Python runtime wheel packages this same command; the SDK defaults to `sdk`, and the minimal example selects `sdk-minimal`. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, configuration errors, and boot failures exit nonzero.
+
+## Entry modes
+
+| Command | Purpose |
+|---|---|
+| `xlaunch --profile <name>` | Boot the named profile under `$XLAUNCH_HOME/profiles/<name>`. |
+| `xlaunch --profile acp` | Serve automation clients over ACP stdio until disconnect. |
+| `xlaunch --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
+| `xlaunch --profile sdk-minimal` | Serve SDK clients with the standalone minimal agent tree. |
+| `xlaunch web` | Alias of `--profile web`. |
+| `xlaunch plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
+
+The invoking directory is the default workspace root. The `web`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates; any other profile must be created through `xlaunch plugin`.
+
+## App arguments
+
+The launcher parses only its own flags and hands everything after them to the booted profile, where any injected app plugin may parse the shared immutable snapshot ([`xlaunch-cmdline`](../../packages/boot/cmdline/README.md)). The first token the launcher does not recognize starts the app's arguments:
+
+```sh
+xlaunch --profile web --port 8080       # --port belongs to the web app
+xlaunch --profile tui --resume <id>     # example, assuming the tui profile is installed; --resume belongs to the terminal app
+xlaunch --profile sdk                   # the SDK JSON-RPC server reads its own flags after the launcher flags
+xlaunch --profile web --help            # the web app's flags, not the launcher's
+xlaunch --help                          # the launcher's own help
+```
+
+<a id="profiles"></a>
+## Profiles
+
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `xlaunch.profile` with its ordered `bundles` list and `patchReload` lifecycle) and a `cordis.patch.yml` (the user's own patch layer). `patchReload: live` watches the profile and home-level patch files; `startup` applies them once.
+
+The tree composes over an empty root:
+- each bundle's patch in `xlaunch.profile.bundles` order
+- then the profile's `cordis.patch.yml`, then the home-level `$XLAUNCH_HOME/cordis.patch.yml`
+- then `--patch` overlays
+
+Bundles named in `xlaunch.profile.bundles` resolve from the xlaunch installation first (`@xlaunch/base`, `@xlaunch/web-app`, `@xlaunch/sdk-app`, `@xlaunch/sdk-minimal`, `@xlaunch/acp-app`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins.
+
+Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
+
+The [CLI behavior reference](reference/README.md) owns exact layer precedence, flags, shutdown behavior, deployment defaults, and source execution.
+
+## Optional overlays
+
+`config/examples/` ships opt-in overlays for GitHub review webhooks, session-local Schedule, memory MCP servers, and runtime Cordis tools. They are never part of a default profile; the [user guides](../../docs/user/guide/index.md) and [developer practice guides](../../docs/user/develop/practice/index.md) own setup and safety instructions.
+
+## Development
+
+Production runs require built package and frontend artifacts. From the repository root, run `pnpm run build` separately, then use `pnpm xlaunch <args...>` to run the TypeScript entry and forward every argument; the [source-execution reference](reference/README.md#source-execution) owns the module-resolution contract.

package/lib/bin.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadLayeredEnv } from "@xlaunch/app-boot";
+import { Command, CommanderError } from "commander";
+//#region lib/types/args.js
+/**
+* Commander adapter for the `xlaunch` command line.
+*
+* The launcher parses only what it owns — which profile to boot, which extra
+* patch overlays to apply, and the config dumps — and hands **everything after
+* its own flags** to the booted tree verbatim, where injected app plugins parse
+* their own flag families and print their own `--help` (see
+* `@xlaunch/cmdline`). Launcher flags therefore come first: the first
+* token this parser does not recognize starts the inner arguments, so
+* `xlaunch --profile tui --resume abc` boots the tui profile with `--resume abc`,
+* and `xlaunch --profile web -h` prints the web app's help, not this one's.
+*
+* `web` is a hardcoded alias for `--profile web`; `plugin` manages a profile's
+* plugin dependencies by forwarding to pnpm.
+* @module @xlaunch/cli/args
+*/
+/**
+* Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
+* variadic — a variadic `--patch` would swallow the inner arguments.
+*/
+const collect = (value, previous = []) => [...previous, value];
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  xlaunch --profile web                          boot the web profile (same as: xlaunch web)
+  xlaunch --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
+  xlaunch --profile tui --resume <session>       arguments after the launcher flags reach the app
+  xlaunch --profile web --help                   the web app's own flags and help
+  xlaunch plugin --profile tui add <package>     install a plugin into the tui profile
+`;
+/**
+* Resolve a boot or dump invocation from the launcher flags and the leftover
+* inner arguments.
+* @param program - the command whose options were parsed (the root, or the `web` alias).
+* @param profile - the profile these flags boot.
+* @param options - the launcher flags commander collected.
+* @param args - the leftover arguments, in argv order.
+* @returns the resolved invocation.
+*/
+function resolveBoot(program, profile, options, args) {
+	const patches = options.patch ?? [];
+	if (patches.includes("")) program.error("error: --patch needs a path");
+	if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) return {
+		mode: "profile",
+		profile,
+		patches,
+		args
+	};
+	if (options.dumpConfig === true && options.dumpDefaultConfig === true) program.error("error: --dump-config and --dump-default-config are mutually exclusive");
+	if (args.length > 0) program.error(`error: config dumps take no app arguments, got ${args.map((argument) => JSON.stringify(argument)).join(" ")}`);
+	const defaultOnly = options.dumpDefaultConfig === true;
+	if (defaultOnly && patches.length > 0) program.error("error: --dump-default-config prints the bundle layers and takes no --patch");
+	return {
+		mode: "dump-config",
+		profile,
+		defaultOnly,
+		patches
+	};
+}
+/**
+* Resolve argv into one invocation, or print and exit for help, version, or an
+* error.
+* @param argv - arguments after the Node binary and script.
+* @param version - version string printed by `--version`.
+* @returns the resolved invocation.
+*/
+function parseXlaunchArgs(argv, version) {
+	let resolved;
+	const program = new Command();
+	program.name("xlaunch").version(version, "-V, --version", "output the version number").description("xlaunch: boot a Xlaunch profile — an ordered stack of plugin-bundle patch layers under your own overrides.").addHelpText("after", HELP_EXAMPLES).exitOverride().helpOption(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the booted profile's app (see: xlaunch --profile <name> --help)").option("--profile <name>", "the profile under $XLAUNCH_HOME/profiles to boot").option("--patch <path>", "extra patch-list overlay applied after the profile layer (repeatable)", collect).option("--dump-config", "print the composed profile tree and exit").option("--dump-default-config", "print the profile tree without its user layer or --patch overlays and exit").action((args, options) => {
+		if (options.profile === void 0) {
+			if (args.some((argument) => argument === "-h" || argument === "--help")) program.help();
+			program.error("error: --profile <name> is required");
+		}
+		const profile = options.profile;
+		if (profile === "") program.error("error: --profile needs a name");
+		resolved = resolveBoot(program, profile, options, args);
+	});
+	/** Reject parent options supplied before a subcommand. */
+	const rejectParentOptions = (command) => {
+		const parent = program.opts();
+		if (parent.profile !== void 0 || parent.patch !== void 0 || parent.dumpConfig !== void 0 || parent.dumpDefaultConfig !== void 0) program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`);
+	};
+	const web = program.command("web").description("boot the web profile (alias of --profile web); the web app's own flags follow");
+	web.helpOption(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the web app (see: xlaunch web --help)").option("--patch <path>", "extra patch-list overlay applied after the profile layer (repeatable)", collect).option("--dump-config", "print the composed web-profile tree (with the user layer and any --patch) and exit").option("--dump-default-config", "print the web profile's bundle layers (no user layer) and exit").action((args, options) => {
+		rejectParentOptions("web");
+		resolved = resolveBoot(web, "web", options, args);
+	});
+	program.command("plugin").description("manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory").requiredOption("--profile <name>", "the profile whose plugins to manage (initialized on first use)").allowUnknownOption().argument("[args...]", "pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)").action((args, options) => {
+		rejectParentOptions("plugin");
+		if (options.profile === "") program.error("error: --profile needs a name");
+		if (args.length === 0) program.error("error: plugin needs pnpm arguments to forward (e.g. add <package>)");
+		resolved = {
+			mode: "plugin",
+			profile: options.profile,
+			args
+		};
+	});
+	try {
+		program.parse(argv, { from: "user" });
+	} catch (error) {
+		return process.exit(error instanceof CommanderError ? error.exitCode : 1);
+	}
+	/* v8 ignore next -- an action resolves or Commander throws */
+	if (resolved === void 0) throw new Error("xlaunch: no invocation resolved");
+	return resolved;
+}
+//#endregion
+//#region lib/types/bin.js
+/**
+* Command-line entry for xlaunch.
+* @module @xlaunch/cli/bin
+*/
+/* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
+function readVersion() {
+	const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+	return typeof manifest.version === "string" ? manifest.version : "0.0.0";
+}
+/**
+* Run the public xlaunch command-line interface.
+* @returns a promise that settles when the selected command mode finishes.
+*/
+async function runCli() {
+	const invocation = parseXlaunchArgs(process.argv.slice(2), readVersion());
+	switch (invocation.mode) {
+		case "profile": {
+			const { runProfile } = await import("./profile-boot-CaxJ0Q_q.js");
+			await runProfile({
+				environment: loadLayeredEnv("xlaunch"),
+				profile: invocation.profile,
+				patchFiles: invocation.patches,
+				args: invocation.args
+			});
+			break;
+		}
+		case "plugin": {
+			const { runPlugin } = await import("./plugin-CHlQ3vHX.js");
+			process.exit(runPlugin(invocation.profile, invocation.args));
+			break;
+		}
+		case "dump-config": {
+			const { runDumpConfig } = await import("./dump-config-CMEroLOU.js");
+			runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches);
+			break;
+		}
+		default: throw new Error(`xlaunch: unhandled invocation mode ${JSON.stringify(invocation)}`);
+	}
+}
+if (import.meta.main) await runCli();
+//#endregion
+export { runCli };

package/lib/dump-config-CMEroLOU.js

@@ -0,0 +1,52 @@
+import { i as prepareProfile, n as PROFILE_ROOT_FILENAME, r as homePatchPath } from "./profile-boot-BSCjR7FQ.js";
+import { existsSync } from "node:fs";
+import { loadOptionalPatches, loadOverlayPatches, renderConfigDump } from "@xlaunch/app-boot";
+import { join, resolve } from "node:path";
+//#region lib/types/dump-config.js
+/**
+* Config-dump entry for `xlaunch --profile <name> --dump-config`: compose the
+* profile's patch layers through the include plugin's patch algorithm without
+* booting or evaluating `!!js`, with one source layer per bundle, the
+* profile's own patch file, and each `--patch` overlay.
+* @module @xlaunch/cli/dump-config
+*/
+const NAME = "xlaunch";
+/* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
+/**
+* Print a profile composition with comments naming each source file and patch layer.
+* @param profile - the profile name.
+* @param defaultOnly - omit the profile's user layer and `--patch` overlays
+* (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+* never parsed).
+* @param patches - `--patch` overlay paths, in argv order.
+*/
+function runDumpConfig(profile, defaultOnly, patches) {
+	const loaded = prepareProfile(profile, !defaultOnly);
+	const layers = loaded.layers.map((layer) => ({
+		label: layer.packageName,
+		patches: layer.patches
+	}));
+	if (!defaultOnly) {
+		if (existsSync(loaded.patchPath)) layers.push({
+			label: loaded.patchPath,
+			patches: loaded.patches
+		});
+		const homePatchFile = homePatchPath();
+		const homePatches = loadOptionalPatches(NAME, homePatchFile);
+		if (homePatches !== void 0) layers.push({
+			label: homePatchFile,
+			patches: homePatches
+		});
+		for (const file of patches) {
+			const absolute = resolve(file);
+			layers.push({
+				label: absolute,
+				patches: loadOverlayPatches(NAME, absolute)
+			});
+		}
+	}
+	process.stdout.write(renderConfigDump(NAME, join(loaded.dir, PROFILE_ROOT_FILENAME), layers));
+}
+/* v8 ignore stop */
+//#endregion
+export { runDumpConfig };

package/lib/plugin-CHlQ3vHX.js

@@ -0,0 +1,130 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-BSCjR7FQ.js";
+import { existsSync } from "node:fs";
+import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest } from "@xlaunch/app-boot";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region lib/types/plugin.js
+/**
+* `xlaunch plugin --profile <name> <args...>` — profile plugin management as a
+* thin pnpm forwarder: initialize the profile on first use, run
+* `pnpm <args...>` in the profile directory, then reconcile the
+* `xlaunch.profile.bundles` layer list against the installed state (a dependency
+* resolving to a package that declares `xlaunch.bundle` joins the layer stack; a
+* removed or bundle-less dependency leaves it). Reconciling by installed
+* state, not by dependency diff, means `update` activates a package that
+* gained its `xlaunch.bundle` declaration in a newer version.
+* @module @xlaunch/cli/plugin
+*/
+const NAME = "xlaunch";
+/**
+* Whether a resolved dependency exports a profile patch, i.e. is a bundle.
+* @param packageName - the dependency's package name.
+* @param profileDir - the profile directory (resolution anchor).
+* @returns true when the package manifest declares `xlaunch.bundle`.
+*/
+function exportsPatch(packageName, profileDir) {
+	let dir;
+	try {
+		dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir);
+	} catch {
+		return false;
+	}
+	return readProfileManifest(NAME, dir).xlaunch?.bundle?.patch !== void 0;
+}
+/**
+* Reconcile `xlaunch.profile.bundles` against the installed state: pnpm has
+* already written the real installed names (so a git/path/tarball/alias spec
+* on the command line reconciles by its true package name) and materialized
+* the packages. A dependency that resolves to a `xlaunch.bundle`-declaring
+* package joins the layer stack (appended in dependency order); a
+* dependency-listed name that no longer does — removed, or the installed
+* version dropped the declaration — leaves it. In-box bundles from the
+* profile template are not dependencies and are never touched. Warns once
+* per newly-added bundle-less dependency (a plain library is fine; the
+* warning is orientation).
+*/
+function reconcilePlugins(before, profileDir) {
+	const after = readProfileManifest(NAME, profileDir);
+	const beforeDeps = new Set(Object.keys(before.dependencies ?? {}));
+	const dependencies = Object.keys(after.dependencies ?? {});
+	const plugins = after.xlaunch?.profile?.bundles ?? [];
+	let changed = false;
+	for (const packageName of dependencies) {
+		const isBundle = exportsPatch(packageName, profileDir);
+		if (isBundle && !plugins.includes(packageName)) {
+			plugins.push(packageName);
+			changed = true;
+		} else if (!isBundle && !beforeDeps.has(packageName)) process.stderr.write(`${NAME}: warning: ${packageName} declares no xlaunch.bundle — installed as a plain dependency, not a profile layer (a later update that gains one activates it automatically)
+`);
+	}
+	const dependencySet = new Set(dependencies);
+	for (const packageName of [...plugins]) {
+		const wasDependency = beforeDeps.has(packageName) || dependencySet.has(packageName);
+		const stillBundle = dependencySet.has(packageName) && exportsPatch(packageName, profileDir);
+		if (wasDependency && !stillBundle) {
+			plugins.splice(plugins.indexOf(packageName), 1);
+			changed = true;
+		}
+	}
+	if (!changed) return;
+	after.xlaunch = {
+		...after.xlaunch,
+		profile: {
+			...after.xlaunch?.profile,
+			bundles: plugins
+		}
+	};
+	writeProfileManifest(profileDir, after);
+}
+/**
+* Rewrite relative filesystem specs against the user's invoking directory.
+* pnpm runs with cwd = the profile directory, so a bare `.` or `../plugin`
+* (or their `file:`/`link:` forms) would silently resolve inside the profile
+* — `add .` from a plugin checkout would self-link the profile. Absolute
+* specs, registry names, and every other pnpm argument pass through
+* untouched.
+* @param argument - one pnpm argument, verbatim from argv.
+* @param cwd - the directory `xlaunch` was invoked from.
+* @returns the argument with a relative path spec anchored to `cwd`.
+*/
+function anchorPathSpec(argument, cwd) {
+	const match = /^(?<prefix>(?:file|link):)?(?<path>\.{1,2}(?:[/\\].*)?)$/.exec(argument);
+	if (match?.groups?.path === void 0) return argument;
+	return `${match.groups.prefix ?? ""}${resolve(cwd, match.groups.path)}`;
+}
+/**
+* Run one `xlaunch plugin` invocation: init if needed, forward to pnpm, reconcile.
+* @param profile - the profile name.
+* @param args - pnpm arguments with relative path specs anchored to the invoking directory.
+* @returns the pnpm exit code.
+*/
+function runPlugin(profile, args) {
+	const dir = resolveProfileDir(profile);
+	if (!existsSync(join(dir, "package.json"))) {
+		const template = PROFILE_TEMPLATES[profile];
+		initProfile(dir, template?.bundles ?? DEFAULT_PROFILE_BUNDLES, template?.patchReload);
+		process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`);
+	}
+	const before = readProfileManifest(NAME, dir);
+	const result = spawnSync("pnpm", args.map((argument) => anchorPathSpec(argument, process.cwd())), {
+		cwd: dir,
+		stdio: "inherit",
+		shell: process.platform === "win32"
+	});
+	if (result.error !== void 0) {
+		if (result.error.code === "ENOENT") {
+			process.stderr.write(`${NAME}: pnpm not found on PATH — install pnpm to manage profile plugins\n`);
+			return 127;
+		}
+		throw result.error;
+	}
+	const exitCode = result.status ?? 1;
+	if (exitCode === 0) reconcilePlugins(before, dir);
+	else {
+		process.stderr.write(`${NAME}: pnpm failed in profile directory ${dir}\n`);
+		if (args.some((argument) => /^git\+|^github:|\.git(?:#|$)/.test(argument))) process.stderr.write(`${NAME}: git-hosted plugins build on install via their prepare script, which pnpm blocks until allowed — add the exact key pnpm printed above under allowBuilds in ${join(dir, "pnpm-workspace.yaml")}, then re-run\n`);
+	}
+	return exitCode;
+}
+//#endregion
+export { runPlugin };

package/lib/profile-boot-BSCjR7FQ.js

@@ -0,0 +1,308 @@
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { PROFILE_PATCH_FILENAME, boot, composeEntries, healProfilesModuleFallback, installFailLoud, loadOptionalPatches, loadOverlayPatches, loadProfile, watchUserPatches } from "@xlaunch/app-boot";
+import { join, resolve } from "node:path";
+import { resolveXlaunchHome } from "@xlaunch/home-paths";
+import { installProxyFromEnvironment } from "@xlaunch/http-proxy";
+import { XLAUNCH_LAUNCH_ENVIRONMENT_KEY } from "@xlaunch/launch-environment";
+import { provideCmdline } from "@xlaunch/cmdline";
+//#region lib/types/process-shutdown.js
+/** Bounded, escalating process shutdown for the long-lived CLI surfaces. */
+/** Maximum grace allowed for the application tree to dispose before process exit. */
+const PROCESS_SHUTDOWN_TIMEOUT_MS = 5e3;
+/**
+* Create one process-exit controller around an application disposer.
+* @param dispose - Whole-application teardown that resolves at quiescence.
+* @param forceExit - Function that exits the process immediately, replaceable by tests.
+* @param complete - Function that records the natural completion code, replaceable by tests.
+* @param timeoutMs - Grace before forced exit, replaceable by tests.
+* @returns A controller whose normal calls coalesce and whose repeated signal call escalates.
+*/
+function createProcessShutdown(dispose, forceExit = (code) => {
+	process.exit(code);
+}, complete = (code) => {
+	process.exitCode = code;
+}, timeoutMs = PROCESS_SHUTDOWN_TIMEOUT_MS) {
+	let pending;
+	let timeout;
+	let completed = false;
+	let forceExited = false;
+	const clearExitTimeout = () => {
+		/* v8 ignore else -- shutdown() arms the timer before any asynchronous exit path can run. */
+		if (timeout !== void 0) clearTimeout(timeout);
+	};
+	const forceExitOnce = (code) => {
+		if (forceExited) return;
+		forceExited = true;
+		clearExitTimeout();
+		forceExit(code);
+	};
+	const completeOnce = (code) => {
+		if (completed || forceExited) return;
+		completed = true;
+		clearExitTimeout();
+		complete(code);
+	};
+	const start = (code, forceAfterDispose) => {
+		if (pending !== void 0) return pending;
+		timeout = setTimeout(() => {
+			forceExitOnce(code);
+		}, timeoutMs);
+		pending = Promise.resolve().then(dispose).then(() => {
+			if (forceAfterDispose) forceExitOnce(code);
+			else completeOnce(code);
+		}, () => {
+			forceExitOnce(code);
+		});
+		return pending;
+	};
+	return {
+		shutdown(code) {
+			return start(code, false);
+		},
+		interrupt(code) {
+			if (pending !== void 0) {
+				forceExitOnce(code);
+				return;
+			}
+			start(code, true);
+		}
+	};
+}
+//#endregion
+//#region lib/types/profile-boot.js
+/**
+* Shared profile boot for every `xlaunch` surface: resolve the profile, stack its
+* patch layers (bundle layers in `xlaunch.profile.bundles` order, the profile's
+* own `cordis.patch.yml`, `--patch` overlays, the telemetry switch), mount the
+* tree over the profile's empty root config, apply its selected patch-reload
+* lifecycle, and wire fail-loud plus bounded shutdown.
+*
+* App flags are not the launcher's business: the invocation's inner arguments
+* are provided to the tree through `ctx.cmdlineArgs`, where any injected app
+* plugin may read the same immutable snapshot.
+* @module @xlaunch/cli/profile-boot
+*/
+const NAME = "xlaunch";
+/** Launcher-owned readiness signal committed only after boot and host setup succeed. */
+function createAppReady() {
+	let ready = false;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		service: { onReady(listener) {
+			if (ready) {
+				listener();
+				return () => {};
+			}
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		} },
+		commit() {
+			if (ready) return;
+			ready = true;
+			for (const listener of [...listeners]) listener();
+			listeners.clear();
+		}
+	};
+}
+/**
+* The home-level user patch layer (`$XLAUNCH_HOME/cordis.patch.yml`), applied
+* over every profile's own layer. Resolved per call, not at module load:
+* `$XLAUNCH_HOME` may be set by the test or launcher after import.
+* @returns the absolute patch-file path.
+*/
+function homePatchPath() {
+	return join(resolveXlaunchHome(), PROFILE_PATCH_FILENAME);
+}
+/** Absolute path of this xlaunch installation's package.json (both anchors: src/ and lib/ sit one level under apps/cli). */
+const INSTALL_ANCHOR = fileURLToPath(new URL("../package.json", import.meta.url));
+/**
+* The row id the XLAUNCH_TELEMETRY_DISABLED switch targets: the session-telemetry
+* exporter row a deployment may mount over the base bundle. The shipped bundles
+* mount no exporter, so the switch is a no-op unless a later layer inserts one.
+*/
+const TELEMETRY_ROW_ID = "session-telemetry";
+/** The empty root entry list every profile tree patches over. */
+const PROFILE_ROOT_CONFIG = `# xlaunch profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's xlaunch.profile.bundles, then cordis.patch.yml, then any
+# --patch overlays. Edit cordis.patch.yml, not this file.
+[]
+`;
+/** Root config filename inside a profile directory. */
+const PROFILE_ROOT_FILENAME = "cordis.yml";
+/**
+* Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
+* value (including `'0'`/`'false'`) disables: a privacy switch prefers
+* off-by-mistake over on-by-mistake. A composition without the telemetry row
+* exports nothing, so the switch is then trivially satisfied and no patch is
+* generated — custom profiles need not mount telemetry to run with the
+* switch set.
+* @param disabledEnv - the raw `XLAUNCH_TELEMETRY_DISABLED` value (`undefined` when unset).
+* @param hasRow - whether the composition carries the telemetry row.
+* @returns the disable patch, or `undefined` when no hard-disable patch is required.
+*/
+function resolveTelemetryPatch(disabledEnv, hasRow) {
+	if ((disabledEnv ?? "") === "" || !hasRow) return void 0;
+	return {
+		id: TELEMETRY_ROW_ID,
+		disabled: true
+	};
+}
+/**
+* Load a resolved profile for `name` and (re)write the empty root config. The
+* root is always rewritten: the whole composition is patch layers, and the
+* vendored Loader's tree write-back (a plugin self-disposing persists the
+* current tree) can bake composed rows into this file — which would duplicate
+* every bundle insert on the next boot. The file exists on disk only because
+* the Loader needs a real include root to anchor `baseUrl` at the profile
+* directory (the config dump anchors on the same file, so both compose over
+* the identical base).
+* @param name - the profile name.
+* @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
+* @returns the loaded profile.
+*/
+function prepareProfile(name, userLayer = true) {
+	const profile = loadProfile(NAME, name, INSTALL_ANCHOR, void 0, { userLayer });
+	writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	return profile;
+}
+/** The full patch stack of one composed profile, in application order. */
+function allPatches(composed) {
+	return [
+		...composed.bundlePatches,
+		...composed.profile.patches,
+		...composed.homePatches,
+		...composed.overlays
+	];
+}
+/**
+* Load `name` and compose its effective patch stack: bundle layers in
+* `xlaunch.profile.bundles` order (a base-backed profile gets the base bundle's
+* platform-gated shell rows), the profile's user layer, the home-level user
+* layer (`$XLAUNCH_HOME/cordis.patch.yml` — machine-local preferences that apply
+* to every profile, so it outranks the per-profile layer), `--patch` overlays,
+* then the telemetry switch.
+* @param name - the profile name.
+* @param patchFiles - `--patch` overlay paths, in argv order.
+* @returns the profile and its patch layers.
+*/
+async function composeProfile(name, patchFiles) {
+	const profile = prepareProfile(name);
+	await healProfilesModuleFallback({
+		installAnchor: INSTALL_ANCHOR,
+		profile
+	});
+	const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? [];
+	const overlays = patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)));
+	const bundlePatches = profile.layers.flatMap((layer) => layer.patches);
+	const rows = /* @__PURE__ */ new Map();
+	for (const row of composeEntries([
+		bundlePatches,
+		profile.patches,
+		homePatches,
+		overlays
+	])) if (typeof row.id === "string") rows.set(row.id, row);
+	const composedOverlays = [...overlays];
+	const telemetryPatch = resolveTelemetryPatch(process.env.XLAUNCH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID));
+	if (telemetryPatch !== void 0) composedOverlays.push(telemetryPatch);
+	return {
+		profile,
+		bundlePatches,
+		homePatches,
+		overlays: composedOverlays
+	};
+}
+/**
+* Re-throw a watcher-setup failure unless a shutdown already owns the tree:
+* a signal aborted this invocation, or an app requested exit (`ctx.appExit`
+* from a fast one-shot) and the root's disposal rejected the in-flight setup
+* await. Either way the failure describes a tree that is exiting as asked,
+* not a broken watch.
+* @param ctx - the booted root context.
+* @param signal - this invocation's signal-shutdown fact.
+* @param error - the setup failure.
+*/
+function suppressShutdownError(ctx, signal, error) {
+	if (signal.aborted) return;
+	if (ctx.fiber.state !== 2 || ctx.get("loader") === void 0) return;
+	throw error;
+}
+/**
+* Boot one profile invocation end to end and leave process lifetime to the
+* mounted plugins (or to a one-shot runner the composition mounts).
+* @param options - environment snapshot, profile name, overlays, and the booted app's own arguments.
+* @returns the settled root context and the shutdown controller.
+*/
+async function runProfile(options) {
+	const disposeProxy = await installProxyFromEnvironment(options.environment, (message) => {
+		process.stderr.write(`${NAME}: ${message}\n`);
+	});
+	const composed = await composeProfile(options.profile, options.patchFiles);
+	const app = {};
+	const appReady = createAppReady();
+	const shutdown = createProcessShutdown(async () => {
+		await app.current?.fiber.dispose();
+		await disposeProxy();
+	});
+	const signalShutdown = new AbortController();
+	const interrupt = (code) => {
+		signalShutdown.abort();
+		shutdown.interrupt(code);
+	};
+	process.on("SIGTERM", () => {
+		interrupt(0);
+	});
+	process.on("SIGINT", () => {
+		interrupt(130);
+	});
+	installFailLoud(NAME, process, async () => {
+		await app.current?.fiber.dispose();
+	});
+	const rootConfig = join(composed.profile.dir, PROFILE_ROOT_FILENAME);
+	const composeLive = () => structuredClone([
+		...composed.bundlePatches,
+		...loadOptionalPatches(NAME, composed.profile.patchPath) ?? [],
+		...loadOptionalPatches(NAME, homePatchPath()) ?? [],
+		...composed.overlays
+	]);
+	const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => {
+		app.current = hostCtx;
+		hostCtx.provide(XLAUNCH_LAUNCH_ENVIRONMENT_KEY, options.environment);
+		provideCmdline(hostCtx, {
+			args: options.args,
+			exit: (code) => void shutdown.shutdown(code),
+			ready: appReady.service
+		});
+	});
+	app.current = ctx;
+	if (composed.profile.patchReload === "live" && !signalShutdown.signal.aborted && ctx.fiber.state === 2 && ctx.get("loader") !== void 0) try {
+		if (ctx.get("hmr") === void 0) {
+			if (ctx.get("timer") === void 0) await ctx.loader.create({ name: "@xlaunch/cordis-plugin-timer" });
+			await ctx.loader.create({
+				name: "@xlaunch/cordis-plugin-hmr",
+				config: { root: [] }
+			});
+		}
+		await watchUserPatches(ctx, {
+			binName: NAME,
+			filename: composed.profile.patchPath,
+			compose: composeLive
+		});
+		await watchUserPatches(ctx, {
+			binName: NAME,
+			filename: homePatchPath(),
+			compose: composeLive
+		});
+	} catch (error) {
+		suppressShutdownError(ctx, signalShutdown.signal, error);
+	}
+	if (!signalShutdown.signal.aborted && ctx.fiber.state === 2 && ctx.get("loader") !== void 0) appReady.commit();
+	return {
+		ctx,
+		shutdown
+	};
+}
+//#endregion
+export { resolveTelemetryPatch as a, prepareProfile as i, PROFILE_ROOT_FILENAME as n, runProfile as o, homePatchPath as r, INSTALL_ANCHOR as t };

package/lib/profile-boot-CaxJ0Q_q.js

@@ -0,0 +1,2 @@
+import { o as runProfile } from "./profile-boot-BSCjR7FQ.js";
+export { runProfile };

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@xlaunch/cli",
+  "description": "xlaunch CLI: profile boot, plugin management, and the browser UI alias",
+  "version": "0.2.0-beta.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Northlatch-Labs-LLC/xlaunch-agent.git",
+    "directory": "apps/cli"
+  },
+  "type": "module",
+  "bin": {
+    "xlaunch": "lib/bin.js"
+  },
+  "files": [
+    "lib/*.js"
+  ],
+  "xlaunch": {
+    "configTrees": [
+      {
+        "mount": "config/agent-presets",
+        "path": "../../packages/preset/agent-presets/presets",
+        "scanRoster": true
+      }
+    ]
+  },
+  "license": "MIT",
+  "author": "Northlatch Labs LLC",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "js-yaml": "^4.2.0",
+    "node-addon-require-builtin": "^0.1.4",
+    "@xlaunch/acp-app": "^0.2.0-beta.1",
+    "@xlaunch/agent-tool-presentation": "^0.2.0-beta.1",
+    "@xlaunch/api-files-controller": "^0.2.0-beta.1",
+    "@xlaunch/agent-instructions": "^0.2.0-beta.1",
+    "@xlaunch/app-boot": "^0.2.0-beta.1",
+    "@xlaunch/base": "^0.2.0-beta.1",
+    "@xlaunch/client-ui-agent-preset": "^0.2.0-beta.1",
+    "@xlaunch/client-ui-cordis": "^0.2.0-beta.1",
+    "@xlaunch/client-ui-workbench": "^0.2.0-beta.1",
+    "@xlaunch/client-ui-workbench-files": "^0.2.0-beta.1",
+    "@xlaunch/cmdline": "^0.2.0-beta.1",
+    "@xlaunch/command-compact": "^0.2.0-beta.1",
+    "@xlaunch/command-goal": "^0.2.0-beta.1",
+    "@xlaunch/compaction-basic": "^0.2.0-beta.1",
+    "@xlaunch/cordis": "^4.0.2",
+    "@xlaunch/compaction-tool-result-pruner": "^0.2.0-beta.1",
+    "@xlaunch/cordis-client-runner": "^0.2.0-beta.1",
+    "@xlaunch/cordis-plugin-hmr": "^1.0.17",
+    "@xlaunch/cordis-plugin-include": "^1.0.7",
+    "@xlaunch/cordis-plugin-loader": "^1.0.3",
+    "@xlaunch/cordis-plugin-timer": "^1.1.4",
+    "@xlaunch/fs-local": "^0.2.0-beta.1",
+    "@xlaunch/goal": "^0.2.0-beta.1",
+    "@xlaunch/goal-round-driver": "^0.2.0-beta.1",
+    "@xlaunch/home-paths": "^0.2.0-beta.1",
+    "@xlaunch/hooks-claude-code": "^0.2.0-beta.1",
+    "@xlaunch/http-proxy": "^0.2.0-beta.1",
+    "@xlaunch/jobs-local": "^0.2.0-beta.1",
+    "@xlaunch/launch-environment": "^0.2.0-beta.1",
+    "@xlaunch/hooks-codex": "^0.2.0-beta.1",
+    "@xlaunch/mcp-client": "^0.2.0-beta.1",
+    "@xlaunch/persona": "^0.2.0-beta.1",
+    "@xlaunch/plan-mode": "^0.2.0-beta.1",
+    "@xlaunch/pwsh-local": "^0.2.0-beta.1",
+    "@xlaunch/pwsh-sandbox": "^0.2.0-beta.1",
+    "@xlaunch/schedule": "^0.2.0-beta.1",
+    "@xlaunch/schemastery": "^3.18.2",
+    "@xlaunch/sdk-minimal": "^0.2.0-beta.1",
+    "@xlaunch/session-projection": "^0.2.0-beta.1",
+    "@xlaunch/sdk-app": "^0.2.0-beta.1",
+    "@xlaunch/session-reference": "^0.2.0-beta.1",
+    "@xlaunch/skill": "^0.2.0-beta.1",
+    "@xlaunch/terminal": "^0.2.0-beta.1",
+    "@xlaunch/skill-filesystem": "^0.2.0-beta.1",
+    "@xlaunch/time-context": "^0.2.0-beta.1",
+    "@xlaunch/terminal-bash": "^0.2.0-beta.1",
+    "@xlaunch/tmux-context": "^0.2.0-beta.1",
+    "@xlaunch/token-meter": "^0.2.0-beta.1",
+    "@xlaunch/tool-ask-user": "^0.2.0-beta.1",
+    "@xlaunch/tool-bash": "^0.2.0-beta.1",
+    "@xlaunch/tool-bash-persistent": "^0.2.0-beta.1",
+    "@xlaunch/tool-cordis": "^0.2.0-beta.1",
+    "@xlaunch/tool-fs": "^0.2.0-beta.1",
+    "@xlaunch/tool-goal": "^0.2.0-beta.1",
+    "@xlaunch/tool-fs-search": "^0.2.0-beta.1",
+    "@xlaunch/tool-pwsh": "^0.2.0-beta.1",
+    "@xlaunch/tool-jobs": "^0.2.0-beta.1",
+    "@xlaunch/tool-pwsh-persistent": "^0.2.0-beta.1",
+    "@xlaunch/tool-ralph": "^0.2.0-beta.1",
+    "@xlaunch/tool-skill": "^0.2.0-beta.1",
+    "@xlaunch/tool-str-replace-editor": "^0.2.0-beta.1",
+    "@xlaunch/tool-subagent-control": "^0.2.0-beta.1",
+    "@xlaunch/tool-web": "^0.2.0-beta.1",
+    "@xlaunch/tool-subagent": "^0.2.0-beta.1",
+    "@xlaunch/tool-todo": "^0.2.0-beta.1",
+    "@xlaunch/web-app": "^0.2.0-beta.1",
+    "@xlaunch/tool-workflow": "^0.2.0-beta.1",
+    "@xlaunch/webhook": "^0.2.0-beta.1",
+    "@xlaunch/webhook-github": "^0.2.0-beta.1",
+    "@xlaunch/workflow-worker-thread": "^0.2.0-beta.1",
+    "@xlaunch/api-capabilities-controller": "^0.2.0-beta.1",
+    "@xlaunch/hook-protocol": "^0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/ws": "8.18.1",
+    "execa": "^10.0.0",
+    "ws": "8.21.0",
+    "@xlaunch/acp": "^0.2.0-beta.1",
+    "@xlaunch/agent": "^0.2.0-beta.1",
+    "@xlaunch/agent-loop": "^0.2.0-beta.1",
+    "@xlaunch/attachment-local": "^0.2.0-beta.1",
+    "@xlaunch/agent-loop-testkit": "^0.2.0-beta.1",
+    "@xlaunch/bash-local": "^0.2.0-beta.1",
+    "@xlaunch/credentials-local": "^0.2.0-beta.1",
+    "@xlaunch/fs-observation-policy": "^0.2.0-beta.1",
+    "@xlaunch/fs-sandbox": "^0.2.0-beta.1",
+    "@xlaunch/host-frontend-static": "^0.2.0-beta.1",
+    "@xlaunch/host-webserver": "^0.2.0-beta.1",
+    "@xlaunch/llm": "^0.2.0-beta.1",
+    "@xlaunch/llm-mock-server": "^0.2.0-beta.1",
+    "@xlaunch/sandbox-local": "^0.2.0-beta.1",
+    "@xlaunch/sandbox-policy": "^0.2.0-beta.1",
+    "@xlaunch/llm-gateway": "^0.2.0-beta.1",
+    "@xlaunch/session": "^0.2.0-beta.1",
+    "@xlaunch/session-checkpoint-policy": "^0.2.0-beta.1",
+    "@xlaunch/session-persistence-jsonl": "^0.2.0-beta.1",
+    "@xlaunch/session-query": "^0.2.0-beta.1",
+    "@xlaunch/shell-env": "^0.2.0-beta.1",
+    "@xlaunch/loader-smoke": "^0.2.0-beta.1",
+    "@xlaunch/settings-file": "^0.2.0-beta.1",
+    "@xlaunch/settings": "^0.2.0-beta.1",
+    "@xlaunch/subagent-spawn-in-process": "^0.2.0-beta.1",
+    "@xlaunch/subagent-fork-in-process": "^0.2.0-beta.1",
+    "@xlaunch/llm-replay": "^0.2.0-beta.1",
+    "@xlaunch/subagent": "^0.2.0-beta.1",
+    "@xlaunch/subprocess-local": "^0.2.0-beta.1",
+    "@xlaunch/system-prompt": "^0.2.0-beta.1",
+    "@xlaunch/tools": "^0.2.0-beta.1",
+    "@xlaunch/user-approval": "^0.2.0-beta.1"
+  }
+}