nexos-connect 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,66 +1,33 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { createRequire } from "module";
 import os from "os";
-import path24 from "path";
+import path25 from "path";
 import crossSpawn from "cross-spawn";
-import pc12 from "picocolors";
-import * as v15 from "valibot";
-
-// src/cli/classify-failure.ts
-import { match } from "ts-pattern";
-
-// src/shared/text/describe-error.ts
-function describeError(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-// src/ui/cancelled-error.ts
-import * as clack from "@clack/prompts";
-var CancelledError = class extends Error {
-  constructor() {
-    super("cancelled by the user");
-    this.name = "CancelledError";
-  }
-};
-async function throwIfCancelled(pending) {
-  const value = await pending;
-  if (clack.isCancel(value)) throw new CancelledError();
-  return value;
-}
-
-// src/cli/exit-code.ts
-var EXIT_CODE = { ok: 0, failed: 1, usage: 2, cancelled: 130 };
-
-// src/cli/usage-error.ts
-var UsageError = class extends Error {
-  name = "UsageError";
-};
-
-// src/cli/classify-failure.ts
-var UNEXPECTED_NEXT_STEP = "Run again with --dry-run to see what would change. If this keeps happening, it is a bug \u2014 please report it.";
-function classifyFailure(error, masker2) {
-  if (error instanceof CancelledError) return { kind: "cancelled" };
-  const message = masker2.maskText(describeError(error));
-  if (error instanceof UsageError) return { kind: "usage", message };
-  return { kind: "unexpected", message: `${message}
-${UNEXPECTED_NEXT_STEP}` };
-}
-function exitCodeForFailure(failure) {
-  return match(failure.kind).with("usage", () => EXIT_CODE.usage).with("cancelled", () => EXIT_CODE.cancelled).with("unexpected", () => EXIT_CODE.failed).exhaustive();
-}
+import pc14 from "picocolors";
+import * as v16 from "valibot";
 
 // src/cli/environment.ts
 import * as v from "valibot";
 
-// src/product/gateway/gateway-errors.ts
-import { match as match2 } from "ts-pattern";
-
 // src/product/gateway/desired-config.ts
 var GATEWAY_HOST = "https://api.nexos.ai";
+var GATEWAY_ENV_VARIABLE = "NEXOS_BASE_URL";
 var API_KEYS_URL = "https://workspace.nexos.ai/gateway/api-keys";
+var TRAILING_SLASHES = /\/+$/;
+var LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+function isAllowedGatewayHost(host) {
+  if (!URL.canParse(host)) return false;
+  const { protocol, hostname, pathname } = new URL(host);
+  if (pathname !== "/" && pathname !== "") return false;
+  return protocol === "https:" || protocol === "http:" && LOOPBACK_HOSTNAMES.includes(hostname);
+}
+function resolveGatewayHost(env) {
+  const configured = env[GATEWAY_ENV_VARIABLE]?.trim().replace(TRAILING_SLASHES, "") ?? "";
+  return isAllowedGatewayHost(configured) ? configured : GATEWAY_HOST;
+}
 var OPENAI_PATH = "/v1";
 function buildGatewayUrls(host) {
   return { anthropicBaseUrl: host, openaiBaseUrl: `${host}${OPENAI_PATH}` };
@@ -70,6 +37,7 @@ function buildDesiredConfig({ gatewayUrls, apiKey, model }) {
 }
 
 // src/product/gateway/gateway-errors.ts
+import { match } from "ts-pattern";
 var GatewayUnreachableError = class extends Error {
   kind = "unreachable";
   endpoint;
@@ -97,7 +65,7 @@ function isGatewayFailure(error) {
 }
 var NETWORK_NEXT_STEP = "check your network or proxy, or rerun with --no-verify";
 function describeGatewayFailure(failure, masker2) {
-  return match2(failure).with({ kind: "unreachable" }, ({ reason }) => describeUnreachable(reason, masker2)).with(
+  return match(failure).with({ kind: "unreachable" }, ({ reason }) => describeUnreachable(reason, masker2)).with(
     { kind: "timed-out" },
     ({ timeoutMs }) => `no response within ${formatSeconds(timeoutMs)} \u2014 ${NETWORK_NEXT_STEP}`
   ).exhaustive();
@@ -110,7 +78,7 @@ function formatHttpFailure(status, explanation, masker2) {
 var REDIRECT_DESCRIPTION = "the gateway answered with a redirect, which is refused \u2014 check for a proxy or captive portal, or rerun with --no-verify";
 var INVALID_HEADER_DESCRIPTION = `the key holds a character an HTTP header cannot carry, so it was not sent \u2014 copy it again from ${API_KEYS_URL}`;
 function describeUnreachable(reason, masker2) {
-  return match2(reason).with(
+  return match(reason).with(
     { kind: "network" },
     ({ causeCode, causeMessage }) => masker2.maskText(`could not connect (${causeCode ?? causeMessage}) \u2014 ${NETWORK_NEXT_STEP}`)
   ).with({ kind: "redirect" }, () => REDIRECT_DESCRIPTION).with({ kind: "invalid-header" }, () => INVALID_HEADER_DESCRIPTION).exhaustive();
@@ -224,10 +192,14 @@ function readNonBlank(value) {
   return trimmed === "" ? void 0 : trimmed;
 }
 
+// src/cli/errors/usage-error.ts
+var UsageError = class extends Error {
+  name = "UsageError";
+};
+
 // src/cli/environment.ts
 var KEY_ENV_VARIABLE = "NEXOS_API_KEY";
 var MODEL_ENV_VARIABLE = "NEXOS_MODEL";
-var GATEWAY_ENV_VARIABLE = "NEXOS_BASE_URL";
 var BlankAsAbsentSchema = v.pipe(v.optional(v.string()), v.transform(readNonBlank));
 var ModelSchema = v.pipe(
   BlankAsAbsentSchema,
@@ -254,21 +226,58 @@ function parseEnvironmentKey(key) {
   return key;
 }
 var UNSET_HINT = "Unset it to use the nexos.ai gateway.";
-var LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
 function parseGatewayHost(value) {
   if (value === void 0) return void 0;
   const host = trimTrailingSlashes(value);
   if (!URL.canParse(host)) throw new UsageError(`$${GATEWAY_ENV_VARIABLE} is not a URL. ${UNSET_HINT}`);
-  const { protocol, hostname } = new URL(host);
-  const isEncrypted = protocol === "https:";
-  const isLocalPlainHttp = protocol === "http:" && LOOPBACK_HOSTNAMES.includes(hostname);
-  if (isEncrypted || isLocalPlainHttp) return host;
-  throw new UsageError(`$${GATEWAY_ENV_VARIABLE} must be an https:// URL, or http:// on this machine. ${UNSET_HINT}`);
+  if (!isAllowedGatewayHost(host)) {
+    throw new UsageError(`$${GATEWAY_ENV_VARIABLE} must be an https:// URL, or http:// on this machine. ${UNSET_HINT}`);
+  }
+  return host;
+}
+
+// src/cli/errors/classify-failure.ts
+import { match as match2 } from "ts-pattern";
+
+// src/shared/text/describe-error.ts
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/ui/terminal/cancelled-error.ts
+import * as clack from "@clack/prompts";
+var CancelledError = class extends Error {
+  constructor() {
+    super("cancelled by the user");
+    this.name = "CancelledError";
+  }
+};
+async function throwIfCancelled(pending) {
+  const value = await pending;
+  if (clack.isCancel(value)) throw new CancelledError();
+  return value;
+}
+
+// src/cli/exit-code.ts
+var EXIT_CODE = { ok: 0, failed: 1, usage: 2, cancelled: 130 };
+
+// src/cli/errors/classify-failure.ts
+var UNEXPECTED_NEXT_STEP = "Run again with --dry-run to see what would change. If this keeps happening, it is a bug \u2014 please report it.";
+function classifyFailure(error, masker2) {
+  if (error instanceof CancelledError) return { kind: "cancelled" };
+  const message = masker2.maskText(describeError(error));
+  if (error instanceof UsageError) return { kind: "usage", message };
+  return { kind: "unexpected", message: `${message}
+${UNEXPECTED_NEXT_STEP}` };
+}
+function exitCodeForFailure(failure) {
+  return match2(failure.kind).with("usage", () => EXIT_CODE.usage).with("cancelled", () => EXIT_CODE.cancelled).with("unexpected", () => EXIT_CODE.failed).exhaustive();
 }
 
 // src/cli/help.ts
 var COMMAND_NAME = "nexos-connect";
 var RESTORE_COMMAND = "restore";
+var STATUS_COMMAND = "status";
 var TAGLINE = `${COMMAND_NAME} \u2014 point your coding agents at the nexos.ai Gateway`;
 function renderHelp({
   harnessIds,
@@ -285,6 +294,7 @@ Usage
   npx ${COMMAND_NAME} <agent> [options] [-- <agent arguments>]
   npx ${COMMAND_NAME} forget-key
   npx ${COMMAND_NAME} ${RESTORE_COMMAND} [options]   put back what it changed in each agent's config
+  npx ${COMMAND_NAME} ${STATUS_COMMAND} [options]    report what is configured, and whether it still matches
 
   <agent> starts one agent once, pointed at the gateway, without changing its config.
   One of: ${launchBinaries.join(", ")}.
@@ -296,6 +306,9 @@ ${RESTORE_COMMAND} puts every key ${COMMAND_NAME} set back the way it was before
 setup, and keeps everything added since. It takes --harnesses, --scope, --yes,
 --dry-run and --backup-dir; --yes restores every agent it has a record of.
 
+${STATUS_COMMAND} is read-only: it reports the key, the env file, the backup folders and every
+agent, at user and project scope. It takes --harnesses, --verify and --json.
+
 Options
   --harnesses <ids>    Comma-separated agent ids; skips the picker.
                        One of: ${harnessIds.join(", ")}
@@ -308,6 +321,9 @@ Options
                        the picker: ${predefinedModels}, or any id from GET /v1/models.
   --save-model         Save the model as the default of each agent it is used for,
                        without asking. Never on a dry run.
+  --install            Install a not-installed agent with npm. Setup installs the
+                       ones you pick in the list; starting an agent installs the
+                       named one first. --yes never installs.
   --scope <scope>      Where to write: user (the default \u2014 your home directory,
                        applying everywhere) or project (this directory only).
   -y, --yes            Answer every question with its default: user scope, the
@@ -321,16 +337,19 @@ Options
                        then shows no model list; ${predefinedModels} is not offered.
   --backup-dir <path>  Where originals are copied, in a <timestamp> folder.
                        Default: ${backupDirectories.user} (user scope), ${backupDirectories.project} (project).
+  --verify             With ${STATUS_COMMAND}: check the resolved key against the gateway once.
+  --json               With ${STATUS_COMMAND}: print the report as one JSON object.
   -h, --help           Show this help.
   -v, --version        Show the version.
 
-Starting an agent takes --key, --model, --save-key, --save-model, --no-verify
-and --yes only. Its model is --model, else $${MODEL_ENV_VARIABLE}, else the agent's saved default, else
+Starting an agent takes --key, --model, --save-key, --save-model, --install,
+--no-verify and --yes only. Its model is --model, else $${MODEL_ENV_VARIABLE}, else the agent's saved default, else
 the picker (--yes: ${defaultModel}).
 
 Exit codes
   ${EXIT_CODE.ok}    done
-  ${EXIT_CODE.failed}    an agent failed, while planning or while writing; or an agent could not start
+  ${EXIT_CODE.failed}    an agent failed, while planning or while writing; or an agent could not start.
+                       With ${STATUS_COMMAND}: an agent drifted, a config could not be read, or --verify rejected the key.
   ${EXIT_CODE.usage}    usage error, or a question asked with no terminal to answer it
   ${EXIT_CODE.cancelled}  cancelled, by Ctrl-C or by declining a confirmation
   Once an agent has started, its own exit code passes through unchanged.
@@ -393,13 +412,13 @@ function buildIdentityMatching(secrets) {
   if (masksByForm.size === 0) return () => [];
   const alternatives = [...masksByForm.keys()].sort((first, second) => second.length - first.length);
   const pattern = new RegExp(alternatives.map(buildFormPattern).join("|"), "g");
-  return (text2) => [...text2.matchAll(pattern)].map((match27) => toSpan(match27, masksByForm.get(match27[0]) ?? match27[0]));
+  return (text2) => [...text2.matchAll(pattern)].map((match29) => toSpan(match29, masksByForm.get(match29[0]) ?? match29[0]));
 }
 function findShapeSpans(text2) {
-  return [...text2.matchAll(KEY_SHAPE_PATTERN)].map((match27) => toSpan(match27, maskKey(match27[0])));
+  return [...text2.matchAll(KEY_SHAPE_PATTERN)].map((match29) => toSpan(match29, maskKey(match29[0])));
 }
-function toSpan(match27, mask) {
-  return { start: match27.index, end: match27.index + match27[0].length, mask };
+function toSpan(match29, mask) {
+  return { start: match29.index, end: match29.index + match29[0].length, mask };
 }
 function pickOuterSpans(spans) {
   const picked = [];
@@ -451,7 +470,7 @@ import { match as match3 } from "ts-pattern";
 // src/shared/file-system/is-file.ts
 import fs from "fs";
 
-// src/shared/file-system/is-missing-file-error.ts
+// src/shared/file-system/errors/is-missing-file-error.ts
 var MISSING_FILE_CODES = ["ENOENT", "ENOTDIR"];
 function isMissingFileError(error) {
   return error instanceof Error && "code" in error && MISSING_FILE_CODES.includes(error.code);
@@ -520,15 +539,18 @@ function parseCliArguments(argv) {
   const { values, tokens } = parseFlags(argv);
   return {
     command: commandFrom(tokens, values),
-    harnessIds: parseHarnessIds(values.harnesses),
+    harnessIds: parseHarnessIds(values.harnesses ?? values.harness),
     key: values.key === void 0 ? void 0 : parseKeyFlag(values.key),
     model: parseModelFlag(values.model),
     scope: parseScope(values.scope),
     shouldAssumeYes: values.yes === true,
     shouldSaveKey: values["save-key"] === true,
     shouldSaveModel: values["save-model"] === true,
+    shouldInstall: values.install === true,
     isDryRun: values["dry-run"] === true,
     shouldVerify: values["no-verify"] !== true,
+    shouldVerifyStatus: values.verify === true,
+    isJson: values.json === true,
     backupDirectory: readNonBlank(values["backup-dir"]),
     shouldShowHelp: values.help === true,
     shouldShowVersion: values.version === true
@@ -536,14 +558,18 @@ function parseCliArguments(argv) {
 }
 var FLAGS = {
   harnesses: { type: "string" },
+  harness: { type: "string" },
   key: { type: "string" },
   model: { type: "string" },
   scope: { type: "string" },
   yes: { type: "boolean", short: "y" },
   "save-key": { type: "boolean" },
   "save-model": { type: "boolean" },
+  install: { type: "boolean" },
   "dry-run": { type: "boolean" },
   "no-verify": { type: "boolean" },
+  verify: { type: "boolean" },
+  json: { type: "boolean" },
   "backup-dir": { type: "string" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" }
@@ -589,6 +615,7 @@ function commandFrom(tokens, values) {
   if (positionals.length > 1) throw new UsageError(describeExtraCommands(positionals));
   const [name] = positionals;
   if (name === void 0 || name === FORGET_KEY_COMMAND) return commandWithoutAgent({ name, passthrough, values });
+  if (name === STATUS_COMMAND) return statusCommand({ passthrough, values });
   if (name === RESTORE_COMMAND) return restoreCommand({ name, passthrough, values });
   return launchCommand({ name, passthrough, values });
 }
@@ -599,29 +626,57 @@ function describeExtraCommands(positionals) {
 }
 function commandWithoutAgent({ name, passthrough, values }) {
   if (passthrough !== null) throw new UsageError(PASSTHROUGH_MISUSE);
-  if (name === void 0) return { kind: "setup" };
+  if (name === void 0) {
+    assertNotStatusFlags(values);
+    return { kind: "setup" };
+  }
   const flags = Object.keys(values).filter((flag) => flag !== "help" && flag !== "version");
   if (flags.length > 0) throw new UsageError(`${FORGET_KEY_COMMAND} takes no options (got --${flags[0]}).`);
   return { kind: "forget-key" };
 }
+var STATUS_UNSUPPORTED_FLAGS = [
+  "key",
+  "model",
+  "scope",
+  "yes",
+  "save-key",
+  "save-model",
+  "install",
+  "dry-run",
+  "no-verify",
+  "backup-dir"
+];
+function statusCommand({ passthrough, values }) {
+  if (passthrough !== null) throw new UsageError(PASSTHROUGH_MISUSE);
+  const unsupported = STATUS_UNSUPPORTED_FLAGS.find((flag) => flag in values);
+  if (unsupported !== void 0) throw new UsageError(`--${unsupported} does not apply to ${STATUS_COMMAND}.`);
+  return { kind: "status" };
+}
+var STATUS_ONLY_FLAGS = ["verify", "json"];
+function assertNotStatusFlags(values) {
+  const flag = STATUS_ONLY_FLAGS.find((name) => values[name] === true);
+  if (flag !== void 0) throw new UsageError(`--${flag} is for ${STATUS_COMMAND} only.`);
+}
 function restoreCommand({ passthrough, values }) {
   if (passthrough !== null) throw new UsageError(PASSTHROUGH_MISUSE);
   assertRestoreFlags(values);
   return { kind: "restore" };
 }
-var LAUNCH_UNSUPPORTED_FLAGS = ["harnesses", "scope", "dry-run", "backup-dir"];
+var LAUNCH_UNSUPPORTED_FLAGS = ["harnesses", "harness", "scope", "dry-run", "backup-dir"];
 function launchCommand({ name, passthrough, values }) {
+  assertNotStatusFlags(values);
   const unsupported = LAUNCH_UNSUPPORTED_FLAGS.filter((flag) => flag in values);
   if (unsupported.length > 0) {
     const shown = isAgentName(name) ? name : "<agent>";
     throw new UsageError(
-      `--${unsupported[0]} is for setup only. npx ${COMMAND_NAME} ${shown} takes --key, --model, --save-key, --save-model, --no-verify and --yes.`
+      `--${unsupported[0]} is for setup only. npx ${COMMAND_NAME} ${shown} takes --key, --model, --save-key, --save-model, --install, --no-verify and --yes.`
     );
   }
   return { kind: "launch", binary: name, passthrough: passthrough ?? [] };
 }
-var RESTORE_UNSUPPORTED_FLAGS = ["key", "model", "save-model", "no-verify"];
+var RESTORE_UNSUPPORTED_FLAGS = ["key", "model", "save-model", "no-verify", "install"];
 function assertRestoreFlags(flags) {
+  assertNotStatusFlags(flags);
   const unsupported = RESTORE_UNSUPPORTED_FLAGS.find((name) => flags[name] !== void 0);
   if (unsupported !== void 0) throw new UsageError(`--${unsupported} does not apply to ${RESTORE_COMMAND}.`);
 }
@@ -715,6 +770,48 @@ function refuse({ question, answers }) {
   };
 }
 
+// src/flows/install/install-harness.ts
+var NPM = "npm";
+var NPM_INSTALL_ARGUMENTS = ["install", "--global", "--no-audit", "--no-fund"];
+async function installHarness(params) {
+  const { label, binary, packageName, shouldInstall, shouldAssumeYes, ui, ctx, runNpm: runNpm2 } = params;
+  if (!shouldInstall && !shouldAssumeYes && !ctx.isInteractive) {
+    throw new UsageError(`Cannot install ${label} without a terminal. Pass --install.`);
+  }
+  if (!shouldInstall) {
+    if (shouldAssumeYes) return { kind: "skipped" };
+    if (!await ui.confirm(askToInstall({ label, packageName }), false)) return { kind: "declined" };
+  }
+  if (!ctx.hasBinary(NPM)) return { kind: "failed", message: describeNpmMissing({ label, packageName }) };
+  const result = await runNpm2([...NPM_INSTALL_ARGUMENTS, packageName]);
+  if (result.kind === "could-not-start") {
+    return { kind: "failed", message: describeNpmNotStarted({ label, packageName }) };
+  }
+  if (result.code !== 0) {
+    return { kind: "failed", message: describeNpmFailure({ label, packageName, exitCode: result.code }) };
+  }
+  if (!ctx.hasBinary(binary)) return { kind: "not-on-path", packageName };
+  return { kind: "installed" };
+}
+function describeMissingBinary({ label, binary }) {
+  return `${binary} not found on PATH. Install ${label} first.`;
+}
+function describeNotOnPath({ label, binary }) {
+  return `Installed ${label}, but ${binary} is still not on PATH. Check npm's global bin is on PATH (npm prefix -g).`;
+}
+function askToInstall({ label, packageName }) {
+  return `${label} isn't on your PATH. Install it now? (npm install -g ${packageName})`;
+}
+function describeNpmMissing({ label, packageName }) {
+  return `Couldn't install ${label}: npm was not found on PATH. Install it yourself: npm install -g ${packageName}.`;
+}
+function describeNpmNotStarted({ label, packageName }) {
+  return `Couldn't install ${label}: npm could not be started. Install it yourself: npm install -g ${packageName}.`;
+}
+function describeNpmFailure({ label, packageName, exitCode }) {
+  return `Couldn't install ${label} (npm exited ${exitCode}). Install it yourself: npm install -g ${packageName}.`;
+}
+
 // src/flows/key/find-existing-keys.ts
 import * as v9 from "valibot";
 
@@ -740,7 +837,7 @@ function findFirstExistingFile(candidates) {
   return candidates.find((candidate) => isFile(candidate)) ?? null;
 }
 
-// src/harnesses/detect-config-file.ts
+// src/harnesses/config/detect-config-file.ts
 function detectConfigFile(candidates, home) {
   const existing = findFirstExistingFile(candidates);
   if (existing === null) {
@@ -750,7 +847,29 @@ function detectConfigFile(candidates, home) {
   return { isFound: true, detail: displayPath(existing, home) };
 }
 
-// src/harnesses/read-jsonc-file.ts
+// src/harnesses/config/detect-config-or-binary.ts
+function detectConfigOrBinary({ candidates, binary, ctx }) {
+  const detected = detectConfigFile(candidates, ctx.home);
+  if (detected.isFound || ctx.scope === "project" || !ctx.hasBinary(binary)) return detected;
+  return { isFound: true, detail: `${binary} found on PATH` };
+}
+
+// src/harnesses/config/is-gateway-url.ts
+function isGatewayUrl(url, gatewayHost) {
+  const parsed = parseUrl(url);
+  const gateway = parseUrl(gatewayHost);
+  if (parsed === void 0 || gateway === void 0) return false;
+  return parsed.origin === gateway.origin;
+}
+function parseUrl(value) {
+  if (value === void 0 || !URL.canParse(value)) return void 0;
+  return new URL(value);
+}
+function gatewayHostOf(ctx) {
+  return resolveGatewayHost(ctx.env);
+}
+
+// src/harnesses/config/read-jsonc-file.ts
 import * as v3 from "valibot";
 
 // src/shared/file-formats/config-errors.ts
@@ -821,7 +940,7 @@ function describeLocation(keyPath) {
   return `"${keyPath.join(".")}"`;
 }
 
-// src/shared/file-formats/jsonc.ts
+// src/shared/file-formats/json/jsonc.ts
 import {
   applyEdits,
   findNodeAtLocation,
@@ -940,7 +1059,7 @@ function splitByteOrderMark(text2) {
   return { byteOrderMark: BYTE_ORDER_MARK, body: text2.slice(BYTE_ORDER_MARK.length) };
 }
 
-// src/shared/file-formats/jsonc.ts
+// src/shared/file-formats/json/jsonc.ts
 var PARSE_OPTIONS = { allowTrailingComma: true, disallowComments: false };
 function parseJsonc(text2) {
   const { body } = splitByteOrderMark(text2 ?? "");
@@ -973,7 +1092,7 @@ function renderJsonc(current, updates) {
     (text2, [keyPath, value]) => setValue({ text: text2, keyPath, value, formattingOptions }),
     body.trim() === "" ? EMPTY_DOCUMENT : body
   );
-  return byteOrderMark + endWithLineEnding(edited, formattingOptions.eol);
+  return byteOrderMark + matchFinalLineEnding(edited, formattingOptions.eol, isNewOrEndsWithLineEnding(body));
 }
 function readJsoncOriginals(current, keyPaths) {
   const { body } = splitByteOrderMark(current ?? "");
@@ -1039,8 +1158,12 @@ function detectFormatting(text2) {
     eol: detectLineEnding(text2) ?? DEFAULT_LINE_ENDING
   };
 }
-function endWithLineEnding(text2, lineEnding) {
-  return text2.endsWith("\n") ? text2 : text2 + lineEnding;
+function isNewOrEndsWithLineEnding(body) {
+  return body.trim() === "" || body.endsWith("\n");
+}
+function matchFinalLineEnding(text2, lineEnding, shouldEndWithLineEnding) {
+  if (shouldEndWithLineEnding) return text2.endsWith("\n") ? text2 : text2 + lineEnding;
+  return text2.replace(/\r?\n$/, "");
 }
 function findNode(text2, keyPath) {
   const root = parseTree(text2, [], PARSE_OPTIONS);
@@ -1072,7 +1195,7 @@ function setValue({ text: text2, keyPath, value, formattingOptions }) {
 // src/shared/file-system/read-file-if-exists.ts
 import fs2 from "fs";
 
-// src/shared/file-system/utf16-file-error.ts
+// src/shared/file-system/errors/utf16-file-error.ts
 var Utf16FileError = class extends Error {
   filePath;
   constructor(filePath) {
@@ -1106,7 +1229,7 @@ function hasUtf16ByteOrderMark(bytes) {
   return UTF16_BYTE_ORDER_MARKS.some((byteOrderMark) => bytes.subarray(0, byteOrderMark.length).equals(byteOrderMark));
 }
 
-// src/harnesses/read-jsonc-file.ts
+// src/harnesses/config/read-jsonc-file.ts
 function readJsoncFile(filePath, schema) {
   return parseJsoncConfig(readFileIfExists(filePath), schema);
 }
@@ -1128,11 +1251,13 @@ var claudeCode = {
   id: "claude-code",
   label: "Claude Code",
   binary: BINARY,
+  installPackage: "@anthropic-ai/claude-code",
   protocols: ["anthropic"],
   projectSupport: { kind: "supported" },
-  detect: (ctx) => detectConfigFile(listSettingsCandidates(ctx), ctx.home),
+  detect: (ctx) => detectConfigOrBinary({ candidates: listSettingsCandidates(ctx), binary: BINARY, ctx }),
   configPath: (ctx) => resolveSettingsPath(ctx),
   plan: (desired, ctx) => [planSettings(desired, ctx)],
+  inspect: (ctx) => inspectSettings(ctx),
   launch: (desired) => ({
     binary: BINARY,
     arguments: ["--settings", SETTINGS_PLACEHOLDER],
@@ -1225,7 +1350,7 @@ function planSettings(desired, ctx) {
 }
 function readGatewayToken(ctx) {
   const env = readSettingsEnv(ctx);
-  if (!isGatewayUrl(env?.[BASE_URL_VARIABLE])) return void 0;
+  if (!isGatewayUrl(env?.[BASE_URL_VARIABLE], gatewayHostOf(ctx))) return void 0;
   return env?.[AUTH_TOKEN_VARIABLE];
 }
 function readCredentials(ctx) {
@@ -1246,19 +1371,29 @@ var SettingsSchema = v4.looseObject({
       v4.looseObject({
         [BASE_URL_VARIABLE]: OptionalTextSchema,
         [AUTH_TOKEN_VARIABLE]: OptionalTextSchema,
-        [API_KEY_VARIABLE]: OptionalTextSchema
+        [API_KEY_VARIABLE]: OptionalTextSchema,
+        [MODEL_VARIABLE]: OptionalTextSchema
       })
     ),
     void 0
-  )
+  ),
+  [MODEL_SETTING]: OptionalTextSchema
 });
 function readSettingsEnv(ctx) {
   const settings2 = readJsoncFile(resolveSettingsPath(ctx), SettingsSchema);
   return settings2.kind === "valid" ? settings2.value[ENV_BLOCK] : void 0;
 }
-var GATEWAY_HOSTNAME = new URL(GATEWAY_HOST).hostname;
-function isGatewayUrl(url) {
-  return url !== void 0 && URL.canParse(url) && new URL(url).hostname === GATEWAY_HOSTNAME;
+function inspectSettings(ctx) {
+  const settings2 = readJsoncFile(resolveSettingsPath(ctx), SettingsSchema);
+  if (settings2.kind === "absent") return { isConfigured: false, model: void 0, isUnreadable: false };
+  if (settings2.kind === "invalid") return { isConfigured: false, model: void 0, isUnreadable: true };
+  const env = settings2.value[ENV_BLOCK];
+  const model = settings2.value[MODEL_SETTING] ?? env?.[MODEL_VARIABLE];
+  return {
+    isConfigured: isGatewayUrl(env?.[BASE_URL_VARIABLE], gatewayHostOf(ctx)),
+    model: model === void 0 ? void 0 : normalizeModel(model),
+    isUnreadable: false
+  };
 }
 
 // src/harnesses/codex/codex.ts
@@ -1388,14 +1523,14 @@ function listKeyValues(program) {
 }
 function listInBody(keyValues, tablePath) {
   return keyValues.flatMap((keyValue) => {
-    const path25 = [...tablePath, ...keyValue.key.keys.map(readKeyName)];
-    const entry = { path: path25, keyValue, tablePath };
+    const path26 = [...tablePath, ...keyValue.key.keys.map(readKeyName)];
+    const entry = { path: path26, keyValue, tablePath };
     if (keyValue.value.type !== "TOMLInlineTable") return [entry];
-    return [entry, ...listInBody(keyValue.value.body, path25)];
+    return [entry, ...listInBody(keyValue.value.body, path26)];
   });
 }
-function isSamePath(path25, other) {
-  return path25.length === other.length && path25.every((key, index) => key === other[index]);
+function isSamePath(path26, other) {
+  return path26.length === other.length && path26.every((key, index) => key === other[index]);
 }
 function replaceValue(source, node, value) {
   if (node.type === "TOMLValue" && node.value === value) return source.text;
@@ -1597,15 +1732,17 @@ var codex = {
   id: "codex",
   label: "OpenAI Codex",
   binary: BINARY2,
+  installPackage: "@openai/codex",
   protocols: ["openai-responses"],
   projectSupport: { kind: "unsupported", reason: "a repo-level config.toml cannot set the provider or its base_url" },
   keyEnvVariable: API_KEY_VARIABLE2,
-  detect: (ctx) => detectConfigFile([resolveConfigPath(ctx)], ctx.home),
+  detect: (ctx) => detectConfigOrBinary({ candidates: [resolveConfigPath(ctx)], binary: BINARY2, ctx }),
   configPath: (ctx) => resolveConfigPath(ctx),
   plan: (desired, ctx) => [
     planConfig(desired, ctx),
     { kind: "env", variables: { [API_KEY_VARIABLE2]: desired.apiKey } }
   ],
+  inspect: (ctx) => inspectConfig(ctx),
   launch: (desired) => {
     const overrides = [
       `model=${JSON.stringify(desired.model)}`,
@@ -1628,6 +1765,7 @@ var codex = {
     "Running /model saves that model to ~/.codex/config.toml.",
     'A later plain `codex resume` of this session points at a "nexos-run" provider that no longer exists.'
   ],
+  postSetupNote: (model) => `If Codex reports \`Missing environment variable: ${API_KEY_VARIABLE2}\`, try \`${BINARY2} -c '${escapePosixSingleQuoted(`model=${JSON.stringify(model)}`)}'\`. This is a reported workaround, not a required launch command or a guaranteed fix.`,
   postSetupNotes: [
     `OpenAI Codex requires wire_api = "${WIRE_API}": if the gateway does not serve /v1/responses, Codex fails even though its config is correct.`
   ]
@@ -1679,6 +1817,28 @@ function listLeftoverRemovals({ desired, current }) {
   const isRouterLeftover = readPath(parseToml(current ?? ""), WEB_SEARCH_KEY_PATH) === WEB_SEARCH_DISABLED;
   return isRouterLeftover ? [[WEB_SEARCH_KEY_PATH, void 0]] : [];
 }
+function inspectConfig(ctx) {
+  const filePath = resolveConfigPath(ctx);
+  const text2 = readFileIfExists(filePath);
+  if (text2 === null) return { isConfigured: false, model: void 0, isUnreadable: false };
+  let document;
+  try {
+    document = parseToml(text2);
+  } catch (error) {
+    if (!(error instanceof ConfigFormatError)) throw error;
+    return { isConfigured: false, model: void 0, isUnreadable: true };
+  }
+  const baseUrl = readString(document, ["model_providers", PROVIDER_ID, "base_url"]);
+  return {
+    isConfigured: readString(document, ["model_provider"]) === PROVIDER_ID && isGatewayUrl(baseUrl, gatewayHostOf(ctx)),
+    model: readString(document, ["model"]),
+    isUnreadable: false
+  };
+}
+function readString(document, keyPath) {
+  const value = readPath(document, keyPath);
+  return typeof value === "string" ? value : void 0;
+}
 
 // src/harnesses/copilot-cli/copilot-cli.ts
 var BINARY3 = "copilot";
@@ -1706,6 +1866,7 @@ var copilotCli = {
   id: "copilot-cli",
   label: "GitHub Copilot CLI",
   binary: BINARY3,
+  installPackage: "@github/copilot",
   protocols: ["openai-chat"],
   projectSupport: {
     kind: "unsupported",
@@ -1756,22 +1917,38 @@ function isConfigSubstitution(value) {
   return value.startsWith(COMMAND_PREFIX) || value.includes(VARIABLE_MARKER);
 }
 
+// src/harnesses/launch/launch-recipe.ts
+var LAUNCH_DIRECTORY_PLACEHOLDER = "{launchDirectory}";
+
 // src/harnesses/crush/crush.ts
 var BINARY4 = "crush";
 var PROVIDER_ID2 = "nexos";
 var PROVIDER_NAME2 = "nexos.ai";
 var PROVIDER_TYPE2 = "openai-compat";
 var CONFIG_SCHEMA_URL = "https://charm.land/crush.json";
+var GLOBAL_CONFIG_VARIABLE = "CRUSH_GLOBAL_CONFIG";
 var crush = {
   kind: "configurable",
   id: "crush",
   label: "Crush",
   binary: BINARY4,
+  installPackage: "@charmland/crush",
   protocols: ["openai-chat"],
   projectSupport: { kind: "supported" },
   detect: (ctx) => detectCrush(ctx),
   configPath: (ctx) => resolveConfigPath2(ctx),
   plan: (desired, ctx) => [planConfig2(desired, ctx)],
+  inspect: (ctx) => inspectConfig2(ctx),
+  launch: (desired) => ({
+    binary: BINARY4,
+    arguments: [],
+    env: { [GLOBAL_CONFIG_VARIABLE]: LAUNCH_DIRECTORY_PLACEHOLDER },
+    files: [{ name: USER_FILE, content: renderJsonc(null, listUpdates(desired)) }]
+  }),
+  launchNotes: [
+    "Crush reads crush.json from a temporary config directory for this run; your own Crush config is untouched.",
+    "This session is kept in your Crush history like any other."
+  ],
   readKey: (ctx) => readProviderKey(ctx),
   readSecrets: (ctx) => readProviderSecrets(ctx),
   postSetupNotes: [
@@ -1819,9 +1996,23 @@ function listUpdates(desired) {
 }
 var ConfigSchema = v5.looseObject({
   providers: v5.optional(
-    v5.looseObject({ [PROVIDER_ID2]: v5.optional(v5.looseObject({ api_key: v5.optional(v5.string()) })) })
-  )
+    v5.looseObject({
+      [PROVIDER_ID2]: v5.optional(v5.looseObject({ api_key: v5.optional(v5.string()), base_url: v5.optional(v5.string()) }))
+    })
+  ),
+  models: v5.optional(v5.looseObject({ large: v5.optional(v5.looseObject({ model: v5.optional(v5.string()) })) }))
 });
+function inspectConfig2(ctx) {
+  const config = readJsoncFile(resolveConfigPath2(ctx), ConfigSchema);
+  if (config.kind === "absent") return { isConfigured: false, model: void 0, isUnreadable: false };
+  if (config.kind === "invalid") return { isConfigured: false, model: void 0, isUnreadable: true };
+  const provider = config.value.providers?.[PROVIDER_ID2];
+  return {
+    isConfigured: isGatewayUrl(provider?.base_url, gatewayHostOf(ctx)),
+    model: config.value.models?.large?.model,
+    isUnreadable: false
+  };
+}
 function readProviderKey(ctx) {
   const config = readJsoncFile(resolveConfigPath2(ctx), ConfigSchema);
   const apiKey = config.kind === "valid" ? config.value.providers?.[PROVIDER_ID2]?.api_key : void 0;
@@ -1874,11 +2065,13 @@ var opencode = {
   id: "opencode",
   label: "OpenCode",
   binary: BINARY5,
+  installPackage: "opencode-ai",
   protocols: ["openai-chat"],
   projectSupport: { kind: "supported" },
-  detect: (ctx) => detectOpenCode(ctx),
+  detect: (ctx) => detectConfigOrBinary({ candidates: listConfigCandidates(ctx), binary: BINARY5, ctx }),
   configPath: (ctx) => resolveConfigPath3(ctx),
   plan: (desired, ctx) => [planConfig3(desired, ctx)],
+  inspect: (ctx) => inspectConfig3(ctx),
   launch: (desired) => {
     const config = renderJsonc(null, [
       ...providerUpdates({ providerId: RUN_PROVIDER_ID2, apiKey: `{env:${RUN_KEY_VARIABLE}}`, desired }),
@@ -1904,11 +2097,6 @@ var opencode = {
     "OpenCode keeps its own credentials in its auth.json; this key goes in the provider block instead, so no /connect step is needed."
   ]
 };
-function detectOpenCode(ctx) {
-  const detected = detectConfigFile(listConfigCandidates(ctx), ctx.home);
-  if (detected.isFound || ctx.scope === "project" || !ctx.hasBinary(BINARY5)) return detected;
-  return { isFound: true, detail: `${BINARY5} found on PATH` };
-}
 var USER_CONFIG_DIRECTORY = path7.join(".config", "opencode");
 var JSON_CONFIG_FILE = "opencode.json";
 var JSONC_CONFIG_FILE = "opencode.jsonc";
@@ -1989,14 +2177,33 @@ function readProviderSecrets2(ctx) {
 }
 var ConfigSchema2 = v6.looseObject({
   $schema: v6.optional(v6.unknown()),
+  model: v6.optional(v6.string()),
   provider: v6.optional(
     v6.looseObject({
       [PROVIDER_ID3]: v6.optional(
-        v6.looseObject({ options: v6.optional(v6.looseObject({ apiKey: v6.optional(v6.string()) })) })
+        v6.looseObject({
+          options: v6.optional(v6.looseObject({ apiKey: v6.optional(v6.string()), baseURL: v6.optional(v6.string()) }))
+        })
       )
     })
   )
 });
+function inspectConfig3(ctx) {
+  const config = readJsoncFile(resolveConfigPath3(ctx), ConfigSchema2);
+  if (config.kind === "absent") return { isConfigured: false, model: void 0, isUnreadable: false };
+  if (config.kind === "invalid") return { isConfigured: false, model: void 0, isUnreadable: true };
+  const options = config.value.provider?.[PROVIDER_ID3]?.options;
+  return {
+    isConfigured: isGatewayUrl(options?.baseURL, gatewayHostOf(ctx)),
+    model: readOpenCodeModel(config.value.model),
+    isUnreadable: false
+  };
+}
+function readOpenCodeModel(model) {
+  if (model === void 0) return void 0;
+  const separatorIndex = model.indexOf("/");
+  return separatorIndex === -1 ? model : model.slice(separatorIndex + 1);
+}
 
 // src/harnesses/pi/pi.ts
 import path8 from "path";
@@ -2005,11 +2212,14 @@ var BINARY6 = "pi";
 var PROVIDER_ID4 = "nexos";
 var PROVIDER_NAME4 = "nexos.ai";
 var API_TYPE = "openai-completions";
+var AGENT_DIRECTORY_VARIABLE = "PI_CODING_AGENT_DIR";
+var SESSION_DIRECTORY_VARIABLE = "PI_CODING_AGENT_SESSION_DIR";
 var pi = {
   kind: "configurable",
   id: "pi",
   label: "Pi",
   binary: BINARY6,
+  installPackage: "@earendil-works/pi-coding-agent",
   protocols: ["openai-chat"],
   projectSupport: {
     kind: "unsupported",
@@ -2018,6 +2228,20 @@ var pi = {
   detect: (ctx) => detectBinary2(ctx),
   configPath: (ctx) => resolveModelsPath(ctx),
   plan: (desired, ctx) => [planModels(desired, ctx), planSettings2(desired, ctx)],
+  inspect: (ctx) => inspectConfig4(ctx),
+  launch: (desired) => ({
+    binary: BINARY6,
+    arguments: ["--provider", PROVIDER_ID4, "--model", desired.model],
+    env: {
+      [AGENT_DIRECTORY_VARIABLE]: LAUNCH_DIRECTORY_PLACEHOLDER,
+      [SESSION_DIRECTORY_VARIABLE]: SESSION_DIRECTORY
+    },
+    files: [{ name: MODELS_FILE, content: renderJsonc(null, listModelUpdates(desired)) }]
+  }),
+  launchNotes: [
+    "Pi reads models.json from a temporary agent directory for this run; your ~/.pi/agent files are untouched.",
+    "This session is kept in your Pi history like any other."
+  ],
   readKey: (ctx) => readProviderKey3(ctx),
   readSecrets: (ctx) => readProviderSecrets3(ctx),
   postSetupNotes: [
@@ -2029,6 +2253,7 @@ function detectBinary2(ctx) {
   return { isFound, detail: isFound ? `${BINARY6} found on PATH` : `${BINARY6} not found on PATH` };
 }
 var DEFAULT_AGENT_DIRECTORY = path8.join(".pi", "agent");
+var SESSION_DIRECTORY = path8.join("~", DEFAULT_AGENT_DIRECTORY, "sessions");
 var MODELS_FILE = "models.json";
 var SETTINGS_FILE = "settings.json";
 var HOME_PREFIX = "~";
@@ -2088,9 +2313,25 @@ function listModelUpdates(desired) {
 }
 var ModelsSchema = v7.looseObject({
   providers: v7.optional(
-    v7.looseObject({ [PROVIDER_ID4]: v7.optional(v7.looseObject({ apiKey: v7.optional(v7.string()) })) })
+    v7.looseObject({
+      [PROVIDER_ID4]: v7.optional(v7.looseObject({ apiKey: v7.optional(v7.string()), baseUrl: v7.optional(v7.string()) }))
+    })
   )
 });
+var SettingsSchema2 = v7.looseObject({
+  defaultProvider: v7.optional(v7.string()),
+  defaultModel: v7.optional(v7.string())
+});
+function inspectConfig4(ctx) {
+  const models = readJsoncFile(resolveModelsPath(ctx), ModelsSchema);
+  const settings2 = readJsoncFile(resolveSettingsPath2(ctx), SettingsSchema2);
+  const provider = models.kind === "valid" ? models.value.providers?.[PROVIDER_ID4] : void 0;
+  return {
+    isConfigured: isGatewayUrl(provider?.baseUrl, gatewayHostOf(ctx)),
+    model: settings2.kind === "valid" ? settings2.value.defaultModel : void 0,
+    isUnreadable: models.kind === "invalid" || settings2.kind === "invalid"
+  };
+}
 function readProviderKey3(ctx) {
   const models = readJsoncFile(resolveModelsPath(ctx), ModelsSchema);
   const apiKey = models.kind === "valid" ? models.value.providers?.[PROVIDER_ID4]?.apiKey : void 0;
@@ -2113,17 +2354,26 @@ import { match as match10 } from "ts-pattern";
 import * as v8 from "valibot";
 var BINARY7 = "qwen";
 var KEY_VARIABLE = "NEXOS_API_KEY";
+var OPENAI_KEY_VARIABLE = "OPENAI_API_KEY";
 var AUTH_TYPE = "openai";
 var qwen = {
   kind: "configurable",
   id: "qwen-code",
   label: "Qwen Code",
   binary: BINARY7,
+  installPackage: "@qwen-code/qwen-code",
   protocols: ["openai-chat"],
   projectSupport: { kind: "supported" },
   detect: (ctx) => detectQwen(ctx),
   configPath: (ctx) => resolveSettingsPath3(ctx),
   plan: (desired, ctx) => [planSettings3(desired, ctx)],
+  inspect: (ctx) => inspectSettings2(ctx),
+  launch: (desired) => ({
+    binary: BINARY7,
+    arguments: ["--auth-type", AUTH_TYPE, "--openai-base-url", desired.openaiBaseUrl, "--model", desired.model],
+    env: { [OPENAI_KEY_VARIABLE]: desired.apiKey }
+  }),
+  launchNotes: ["This session is kept in your Qwen Code history like any other."],
   readKey: (ctx) => readProviderKey4(ctx),
   readSecrets: (ctx) => readProviderSecrets4(ctx),
   postSetupNotes: [
@@ -2170,7 +2420,7 @@ function listUpdates3(desired, current) {
 var ModelProvidersSchema = v8.looseObject({
   modelProviders: v8.optional(v8.looseObject({ openai: v8.optional(v8.unknown()) }))
 });
-var NexosEntrySchema = v8.looseObject({ envKey: v8.literal(KEY_VARIABLE) });
+var NexosEntrySchema = v8.looseObject({ envKey: v8.literal(KEY_VARIABLE), baseUrl: v8.optional(v8.string()) });
 function listOtherOpenAiProviders(current) {
   const parsed = parseJsoncConfig(current, ModelProvidersSchema);
   if (parsed.kind !== "valid") return [];
@@ -2179,11 +2429,26 @@ function listOtherOpenAiProviders(current) {
   if (!Array.isArray(openai)) throw new MergeConflictError();
   return openai.filter((entry) => !v8.is(NexosEntrySchema, entry));
 }
-var SettingsSchema2 = v8.looseObject({
-  env: v8.optional(v8.looseObject({ [KEY_VARIABLE]: v8.optional(v8.string()) }))
+var SettingsSchema3 = v8.looseObject({
+  env: v8.optional(v8.looseObject({ [KEY_VARIABLE]: v8.optional(v8.string()) })),
+  model: v8.optional(v8.looseObject({ name: v8.optional(v8.string()) })),
+  modelProviders: v8.optional(v8.looseObject({ openai: v8.optional(v8.unknown()) }))
 });
+function inspectSettings2(ctx) {
+  const settings2 = readJsoncFile(resolveSettingsPath3(ctx), SettingsSchema3);
+  if (settings2.kind === "absent") return { isConfigured: false, model: void 0, isUnreadable: false };
+  if (settings2.kind === "invalid") return { isConfigured: false, model: void 0, isUnreadable: true };
+  const openai = settings2.value.modelProviders?.openai;
+  const entry = Array.isArray(openai) ? openai.find((candidate) => v8.is(NexosEntrySchema, candidate)) : void 0;
+  const baseUrl = v8.is(NexosEntrySchema, entry) ? entry.baseUrl : void 0;
+  return {
+    isConfigured: isGatewayUrl(baseUrl, gatewayHostOf(ctx)),
+    model: settings2.value.model?.name,
+    isUnreadable: false
+  };
+}
 function readProviderKey4(ctx) {
-  const settings2 = readJsoncFile(resolveSettingsPath3(ctx), SettingsSchema2);
+  const settings2 = readJsoncFile(resolveSettingsPath3(ctx), SettingsSchema3);
   return readLiteralKey(settings2.kind === "valid" ? settings2.value.env?.[KEY_VARIABLE] : void 0);
 }
 var SecretsSchema = v8.looseObject({
@@ -2552,13 +2817,9 @@ async function replaceRejectedKey({
 
 // src/product/gateway/models/protocol.ts
 var PROTOCOLS = ["anthropic", "openai-chat", "openai-responses"];
-var PROTOCOL_ENDPOINTS = {
-  anthropic: "messages",
-  "openai-chat": "chat_completion",
-  "openai-responses": "responses"
-};
+var CONVERSATIONAL_ENDPOINTS = ["chat_completion", "messages", "responses"];
 
-// src/ui/report/format-probes.ts
+// src/ui/report/detection/format-probes.ts
 import pc2 from "picocolors";
 
 // src/ui/glyphs.ts
@@ -2586,11 +2847,11 @@ function indentLines({ text: text2, indent }) {
   return lines.map((line) => line === "" ? "" : indent + line);
 }
 
-// src/ui/report/format-probes.ts
+// src/ui/report/detection/format-probes.ts
 function formatProbes(results) {
   return [...formatHeading("Key check"), ...results.flatMap(formatProbe)];
 }
-var SURFACE_COLUMN_WIDTH = 10;
+var SURFACE_COLUMN_WIDTH = 16;
 function formatProbe(result) {
   const colour = result.kind === "passed" ? pc2.dim : pc2.yellow;
   const glyph = result.kind === "passed" ? pc2.green(GLYPHS.success) : pc2.yellow(GLYPHS.warning);
@@ -2611,6 +2872,11 @@ function formatCount(count, noun) {
   return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 
+// src/product/gateway/error-codes.ts
+var INVALID_API_KEY_ERROR_CODE = "invalid_api_key";
+var MODEL_NOT_FOUND_ERROR_CODE = 100110;
+var MODEL_NOT_SUPPORTED_ERROR_CODE = 100800;
+
 // src/product/gateway/model-schema.ts
 import * as v11 from "valibot";
 var OptionalTextSchema2 = v11.fallback(v11.optional(v11.pipe(v11.string(), v11.nonEmpty())), void 0);
@@ -2641,7 +2907,7 @@ var OpenAiErrorSchema = v11.object({
   error: v11.object({
     message: v11.string(),
     type: v11.optional(v11.string()),
-    code: v11.optional(v11.nullable(v11.string()))
+    code: v11.optional(v11.nullable(v11.union([v11.string(), v11.number()])))
   })
 });
 var AnthropicErrorSchema = v11.object({
@@ -2718,12 +2984,15 @@ function readListing({ status, text: text2 }, masker2) {
   const detail = `HTTP ${status} \u2014 authenticated, ${formatCount(models.length, "model")} available`;
   return { kind: "passed", detail, models, status };
 }
-var INVALID_KEY_ERROR_CODE = "invalid_api_key";
 function classifyRejection(status, errorCode) {
-  return match12({ status, errorCode }).returnType().with({ status: P2.union(...KEY_REJECTED_STATUSES) }, { errorCode: INVALID_KEY_ERROR_CODE }, () => "key-rejected").otherwise(() => "bad-status");
+  return match12({ status, errorCode }).returnType().with(
+    { status: P2.union(...KEY_REJECTED_STATUSES) },
+    { errorCode: INVALID_API_KEY_ERROR_CODE },
+    () => "key-rejected"
+  ).otherwise(() => "bad-status");
 }
 
-// src/product/gateway/probe-result.ts
+// src/product/gateway/probes/probe-result.ts
 import { match as match13 } from "ts-pattern";
 function isKeyAccepted(probe) {
   return match13(probe.kind).with("passed", "bad-response", () => true).with("key-rejected", "model-rejected", "unreachable", "timed-out", "bad-status", () => false).exhaustive();
@@ -2823,16 +3092,13 @@ function findContinuation({ shouldAssumeYes, requestedModel, masker: masker2 })
   return masker2.maskText(`Continuing despite the failed check \u2014 "${requestedModel}" was named explicitly.`);
 }
 
-// src/product/gateway/models/model-compatibility.ts
-function isModelCompatible(model, protocols) {
-  return findUnservedProtocols(model, protocols).length === 0;
-}
-function findUnservedProtocols(model, protocols) {
-  if (model.endpoints.length === 0) return [];
-  return protocols.filter((protocol) => !model.endpoints.includes(PROTOCOL_ENDPOINTS[protocol]));
+// src/product/gateway/models/model-capability.ts
+function isConversationalModel(model) {
+  if (model.endpoints.length === 0) return true;
+  return CONVERSATIONAL_ENDPOINTS.some((endpoint) => model.endpoints.includes(endpoint));
 }
 
-// src/ui/model-choices.ts
+// src/ui/prompts/model/model-choices.ts
 var BROWSE_VALUE = "\0browse";
 var MANUAL_VALUE = "\0manual";
 var MANUAL_ROW = {
@@ -2840,9 +3106,9 @@ var MANUAL_ROW = {
   label: "Type a model id\u2026",
   hint: "no model list available"
 };
-function buildModelChoices(models, protocols, isRouterOffered) {
-  const compatible = models.filter((model) => isModelCompatible(model, protocols));
-  const usable = compatible.length > 0 ? compatible : models;
+function buildModelChoices(models, isRouterOffered) {
+  const conversational = models.filter(isConversationalModel);
+  const usable = conversational.length > 0 ? conversational : models;
   const browsable = [...usable].sort((first, second) => first.id.localeCompare(second.id));
   const hiddenCount = models.length - usable.length;
   const routerRows = isRouterOffered ? PREDEFINED_MODELS.map(({ id, hint }) => ({ value: id, label: id, hint })) : [];
@@ -2878,7 +3144,6 @@ async function chooseModel({
   requestedModel,
   routerAvailability,
   shouldAssumeYes,
-  protocols,
   suggestions,
   ui
 }) {
@@ -2892,34 +3157,19 @@ async function chooseModel({
     }
     return DEFAULT_MODEL;
   }
-  return await ui.selectModel(
-    addSuggestionRows(buildModelChoices(keyCheck.models, protocols, isRouterOffered), suggestions)
-  );
+  return await ui.selectModel(addSuggestionRows(buildModelChoices(keyCheck.models, isRouterOffered), suggestions));
 }
-function findModelWarnings({
-  model,
-  models,
-  configurable,
-  routerAvailability
-}) {
+function findModelWarnings({ model, models, routerAvailability }) {
   if (isPredefinedModel(model)) {
     return routerAvailability === "unavailable" ? [`"${model}" is not available for this key. Continuing because you named it.`] : [];
   }
   if (models.length === 0) return [];
-  const listed = models.find((candidate) => candidate.id === model);
-  if (listed === void 0) {
-    return [`"${model}" is not in the list this key can see. Continuing \u2014 the gateway may still accept it.`];
-  }
-  return configurable.flatMap((harness) => {
-    const unserved = findUnservedProtocols(listed, harness.protocols);
-    if (unserved.length === 0) return [];
-    const endpoints = unserved.map((protocol) => PROTOCOL_ENDPOINTS[protocol]).join(", ");
-    return [`${harness.label}: "${model}" does not advertise ${endpoints}. It may still work.`];
-  });
+  if (models.some((candidate) => candidate.id === model)) return [];
+  return [`"${model}" is not in the list this key can see. Continuing \u2014 the gateway may still accept it.`];
 }
 
 // src/flows/model/model-probe.ts
-import { match as match17 } from "ts-pattern";
+import { match as match18 } from "ts-pattern";
 
 // src/product/gateway/models/router-availability.ts
 import { match as match15 } from "ts-pattern";
@@ -2927,7 +3177,7 @@ function classifyRouterAvailability(probe) {
   return match15(probe.kind).returnType().with("passed", () => "available").with("model-rejected", () => "unavailable").otherwise(() => "unknown");
 }
 
-// src/product/gateway/probe-anthropic.ts
+// src/product/gateway/probes/probe-anthropic.ts
 import { P as P3, match as match16 } from "ts-pattern";
 var MESSAGES_PATH = "/v1/messages";
 var ANTHROPIC_VERSION = "2023-06-01";
@@ -2991,16 +3241,109 @@ function classifyRejection2(status, errorType) {
   ).with({ status: MODEL_NOT_FOUND_STATUS }, { errorType: MODEL_NOT_FOUND_ERROR_TYPE }, () => "model-rejected").otherwise(() => "bad-status");
 }
 
+// src/product/gateway/probes/probe-openai.ts
+import { P as P4, match as match17 } from "ts-pattern";
+var CHAT_COMPLETIONS_PATH = "/chat/completions";
+var RESPONSES_PATH = "/responses";
+var BEARER_PREFIX2 = "Bearer ";
+var PING_TEXT2 = "ping";
+var CHAT_MAX_TOKENS = 1;
+var RESPONSES_MAX_OUTPUT_TOKENS = 16;
+async function probeOpenAi({
+  openaiBaseUrl,
+  apiKey,
+  model,
+  protocol,
+  masker: masker2,
+  fetch: fetch2,
+  signal
+}) {
+  const endpoint = `${trimTrailingSlashes(openaiBaseUrl)}${endpointPath(protocol)}`;
+  const probe = (kind, detail, status) => ({
+    kind,
+    surface: protocol,
+    endpoint,
+    detail,
+    ...status === void 0 ? {} : { status }
+  });
+  try {
+    const response = await requestGateway({
+      url: endpoint,
+      init: {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `${BEARER_PREFIX2}${apiKey}` },
+        body: JSON.stringify(buildBody(protocol, model))
+      },
+      fetch: fetch2,
+      timeoutMs: GATEWAY_TIMEOUT_MS,
+      signal
+    });
+    if (isSuccessStatus(response.status)) {
+      return probe("passed", `HTTP ${response.status} \u2014 authenticated`, response.status);
+    }
+    const rejection = parseJsonBody(OpenAiErrorSchema, response.text)?.error;
+    const detail = formatHttpFailure(response.status, rejection?.message ?? response.text, masker2);
+    return probe(classifyRejection3(response.status, rejection?.code ?? void 0), detail, response.status);
+  } catch (error) {
+    if (!isGatewayFailure(error)) throw error;
+    return probe(error.kind, describeGatewayFailure(error, masker2), void 0);
+  }
+}
+function endpointPath(protocol) {
+  return match17(protocol).with("openai-chat", () => CHAT_COMPLETIONS_PATH).with("openai-responses", () => RESPONSES_PATH).exhaustive();
+}
+function buildBody(protocol, model) {
+  return match17(protocol).with("openai-chat", () => ({
+    model,
+    max_tokens: CHAT_MAX_TOKENS,
+    messages: [{ role: "user", content: PING_TEXT2 }]
+  })).with("openai-responses", () => ({
+    model,
+    input: PING_TEXT2,
+    max_output_tokens: RESPONSES_MAX_OUTPUT_TOKENS
+  })).exhaustive();
+}
+function classifyRejection3(status, errorCode) {
+  return match17({ status, errorCode }).returnType().with(
+    { status: P4.union(...KEY_REJECTED_STATUSES) },
+    { errorCode: INVALID_API_KEY_ERROR_CODE },
+    () => "key-rejected"
+  ).with(
+    { errorCode: MODEL_NOT_FOUND_ERROR_CODE },
+    { errorCode: MODEL_NOT_SUPPORTED_ERROR_CODE },
+    () => "model-rejected"
+  ).otherwise(() => "bad-status");
+}
+
 // src/flows/model/model-probe.ts
 async function probeModel(params) {
-  const { anthropicBaseUrl, key, model, ui, masker: masker2, fetch: fetch2 } = params;
+  const { model, protocols, ui, masker: masker2 } = params;
   const spinner = ui.spinner();
   spinner.start(masker2.maskText(`Checking "${model}" against the gateway\u2026`));
-  const probe = await spinner.waitFor(
-    (signal) => probeAnthropic({ anthropicBaseUrl, apiKey: key, model, masker: masker2, fetch: fetch2, signal })
+  const probes = await spinner.waitFor(
+    (signal) => Promise.all(protocols.map((protocol) => probeProtocol({ ...params, protocol, signal })))
   );
-  spinner.stop(summarizeModelProbe(probe));
-  return probe;
+  spinner.stop(summarizeModelProbes(probes));
+  return probes;
+}
+function probeProtocol({
+  anthropicBaseUrl,
+  openaiBaseUrl,
+  key,
+  model,
+  protocol,
+  reuse,
+  masker: masker2,
+  fetch: fetch2,
+  signal
+}) {
+  const reused = reuse?.[protocol];
+  if (reused !== void 0) return Promise.resolve(reused);
+  return match18(protocol).with("anthropic", () => probeAnthropic({ anthropicBaseUrl, apiKey: key, model, masker: masker2, fetch: fetch2, signal })).with(
+    "openai-chat",
+    "openai-responses",
+    (openAiProtocol) => probeOpenAi({ openaiBaseUrl, apiKey: key, model, protocol: openAiProtocol, masker: masker2, fetch: fetch2, signal })
+  ).exhaustive();
 }
 async function probeRouter({
   anthropicBaseUrl,
@@ -3027,8 +3370,9 @@ async function shouldContinueAfterProbe({
   }
   return await ui.confirm(`Continue anyway? ${consequence}`, false);
 }
-function summarizeModelProbe(probe) {
-  return match17(probe.kind).with("passed", () => "Model verified.").otherwise((kind) => PROBE_SUMMARIES[kind]);
+function summarizeModelProbes(probes) {
+  const failed = probes.find((probe) => probe.kind !== "passed");
+  return failed === void 0 ? "Model verified." : PROBE_SUMMARIES[failed.kind];
 }
 
 // src/product/storage/preferences/preferences.ts
@@ -3036,6 +3380,18 @@ import { randomUUID } from "crypto";
 import fs4 from "fs";
 import path12 from "path";
 import * as v12 from "valibot";
+
+// src/shared/file-formats/json/parse-json.ts
+function parseJson2(text2) {
+  try {
+    return JSON.parse(text2);
+  } catch (error) {
+    if (error instanceof SyntaxError) return void 0;
+    throw error;
+  }
+}
+
+// src/product/storage/preferences/preferences.ts
 var PREFERENCES_FILE = "preferences.json";
 function resolvePreferencesPath(home) {
   return path12.join(home, ENV_DIRECTORY_NAME, PREFERENCES_FILE);
@@ -3069,14 +3425,6 @@ function readPreferences(home) {
   }
   return parsed.output;
 }
-function parseJson2(text2) {
-  try {
-    return JSON.parse(text2);
-  } catch (error) {
-    if (error instanceof SyntaxError) return void 0;
-    throw error;
-  }
-}
 function writeAtomically(filePath, content) {
   fs4.mkdirSync(path12.dirname(filePath), { recursive: true });
   const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
@@ -3089,7 +3437,7 @@ function writeAtomically(filePath, content) {
   }
 }
 
-// src/shared/file-system/describe-file-error.ts
+// src/shared/file-system/errors/describe-file-error.ts
 import * as v13 from "valibot";
 function describeFileError({ error, action, home }) {
   const failure = readFileFailure(error);
@@ -3112,18 +3460,18 @@ function findOwnDefaults(defaultModels, targets) {
   return groupByModel(defaultModels, targets);
 }
 function findBorrowedDefaults(params) {
-  const { defaultModels, targets, models, protocols } = params;
+  const { defaultModels, targets, models } = params;
   const targetIds = new Set(targets.map((harness) => harness.id));
   const ownModels = new Set(targets.flatMap((harness) => defaultModels[harness.id] ?? []));
   const others = params.harnesses.filter((harness) => !targetIds.has(harness.id));
   return groupByModel(defaultModels, others).filter(
-    ({ model }) => !ownModels.has(model) && !isPredefinedModel(model) && isServed({ model, models, protocols })
+    ({ model }) => !ownModels.has(model) && !isPredefinedModel(model) && isServed({ model, models })
   );
 }
-function isServed({ model, models, protocols }) {
+function isServed({ model, models }) {
   if (models.length === 0) return true;
   const listed = models.find((candidate) => candidate.id === model);
-  return listed !== void 0 && isModelCompatible(listed, protocols);
+  return listed !== void 0 && isConversationalModel(listed);
 }
 function groupByModel(defaultModels, harnesses2) {
   const labelsByModel = /* @__PURE__ */ new Map();
@@ -3210,8 +3558,8 @@ async function chooseCheckedModel(params) {
     requestedModel,
     shouldAssumeYes: options.shouldAssumeYes,
     resolved: keyStep.resolved,
-    onSavedKeyRejected: async (rejected, probe2) => {
-      const replaced = await replaceRejectedKey({ input: keyStep.input, rejected, probe: probe2, deps: keyStep.deps });
+    onSavedKeyRejected: async (rejected, probe) => {
+      const replaced = await replaceRejectedKey({ input: keyStep.input, rejected, probe, deps: keyStep.deps });
       if (replaced === null) return null;
       if (!isKeyUsable(replaced.key)) return null;
       adoptKey(replaced.key, { ui, masker: masker2 });
@@ -3233,8 +3581,7 @@ async function chooseCheckedModel(params) {
     defaultModels: preferences.defaultModels,
     targets: configurable,
     harnesses,
-    models: keyCheck.models,
-    protocols
+    models: keyCheck.models
   });
   const { shouldAssumeYes } = options;
   const model = await chooseModel({
@@ -3242,11 +3589,10 @@ async function chooseCheckedModel(params) {
     requestedModel,
     routerAvailability,
     shouldAssumeYes,
-    protocols,
     suggestions,
     ui
   });
-  for (const warning of findModelWarnings({ model, models: keyCheck.models, configurable, routerAvailability })) {
+  for (const warning of findModelWarnings({ model, models: keyCheck.models, routerAvailability })) {
     ui.log.warn(masker2.maskText(warning));
   }
   const source = requested?.source ?? "picked";
@@ -3258,21 +3604,26 @@ async function chooseCheckedModel(params) {
     check: keyCheck.outcome,
     modelSave
   };
-  if (!options.shouldVerify || !protocols.includes("anthropic")) {
+  if (!options.shouldVerify || protocols.length === 0) {
     printProbes(keyCheck.probes, ui);
     return chosen;
   }
   const reusedRouterProbe = model === DEFAULT_MODEL ? routerProbe : void 0;
-  const probe = reusedRouterProbe === void 0 ? await probeModel({
+  const probes = await probeModel({
     ...gatewayParams,
     anthropicBaseUrl: gatewayUrls.anthropicBaseUrl,
+    openaiBaseUrl: gatewayUrls.openaiBaseUrl,
     model,
-    key: keyCheck.resolvedKey.key
-  }) : reusedRouterProbe.probe;
-  printProbes([...keyCheck.probes, probe], ui);
+    key: keyCheck.resolvedKey.key,
+    protocols,
+    ...reusedRouterProbe === void 0 ? {} : { reuse: { anthropic: reusedRouterProbe.probe } }
+  });
+  printProbes([...keyCheck.probes, ...probes], ui);
   if (reusedRouterProbe !== void 0 && routerAvailability === "unknown") return chosen;
+  const failed = probes.find((probe) => probe.kind !== "passed");
+  if (failed === void 0) return chosen;
   const shouldContinue = await shouldContinueAfterProbe({
-    probe,
+    probe: failed,
     shouldAssumeYes,
     consequence: params.probeConsequence,
     ui
@@ -3308,8 +3659,8 @@ async function launch(input, rawDeps) {
   const { masker: masker2, ctx } = rawDeps;
   const ui = ctx.isInteractive ? rawDeps.ui : refusePrompts(rawDeps.ui);
   if (!ctx.hasBinary(harness.binary)) {
-    ui.log.error(`${harness.binary} not found on PATH. Install ${harness.label} first.`);
-    return { code: EXIT_CODE.failed };
+    const stopped = await offerInstall({ harness, options, ui, ctx, runNpm: rawDeps.runNpm });
+    if (stopped !== null) return stopped;
   }
   const environment = readEnvironmentInputs(input.env);
   const gatewayUrls = buildGatewayUrls(environment.gatewayHost ?? GATEWAY_HOST);
@@ -3350,13 +3701,44 @@ async function launch(input, rawDeps) {
   }
   return await rawDeps.runLaunch(recipe, input.passthrough);
 }
-function aKeyStepInput({ ctx, options, environmentKey, masker: masker2 }) {
-  const shell = resolveShell(ctx.platform);
-  const existingKeys = findExistingKeys({ ctx, envPath: resolveEnvFilePath(ctx.home, shell), shell });
-  masker2.registerSecrets(existingKeys.all);
-  return {
-    flagKey: options.key,
-    envKey: options.key === void 0 ? parseEnvironmentKey(environmentKey) : void 0,
+async function offerInstall({ harness, options, ui, ctx, runNpm: runNpm2 }) {
+  if (harness.installPackage === void 0) {
+    ui.log.error(describeMissingBinary(harness));
+    return { code: EXIT_CODE.failed };
+  }
+  const outcome = await installHarness({
+    label: harness.label,
+    binary: harness.binary,
+    packageName: harness.installPackage,
+    shouldInstall: options.shouldInstall,
+    shouldAssumeYes: options.shouldAssumeYes,
+    ui,
+    ctx,
+    runNpm: runNpm2
+  });
+  if (outcome.kind === "installed") return null;
+  if (outcome.kind === "declined") {
+    ui.cancel("Aborted \u2014 the agent was not started.");
+    return { code: EXIT_CODE.cancelled };
+  }
+  if (outcome.kind === "skipped") {
+    ui.log.error(describeMissingBinary(harness));
+    return { code: EXIT_CODE.failed };
+  }
+  if (outcome.kind === "not-on-path") {
+    ui.log.error(describeNotOnPath(harness));
+    return { code: EXIT_CODE.failed };
+  }
+  ui.log.error(outcome.message);
+  return { code: EXIT_CODE.failed };
+}
+function aKeyStepInput({ ctx, options, environmentKey, masker: masker2 }) {
+  const shell = resolveShell(ctx.platform);
+  const existingKeys = findExistingKeys({ ctx, envPath: resolveEnvFilePath(ctx.home, shell), shell });
+  masker2.registerSecrets(existingKeys.all);
+  return {
+    flagKey: options.key,
+    envKey: options.key === void 0 ? parseEnvironmentKey(environmentKey) : void 0,
     shouldSaveKey: options.shouldSaveKey,
     shouldAssumeYes: options.shouldAssumeYes,
     isDryRun: false,
@@ -3381,7 +3763,7 @@ function resolveNamedHarnesses(ids) {
 
 // src/product/storage/backups/resolve-backup-root.ts
 import path14 from "path";
-import { match as match18 } from "ts-pattern";
+import { match as match19 } from "ts-pattern";
 var PROJECT_BACKUP_DIRECTORY = ".nexos-backup";
 var USER_BACKUP_DIRECTORY = path14.join(".nexos", "backups");
 function formatBackupTimestamp(now) {
@@ -3391,7 +3773,7 @@ function resolveBackupRoot({ scope, home, cwd, stamp, backupDirectory }) {
   if (backupDirectory !== void 0) {
     return { path: path14.join(path14.resolve(cwd, backupDirectory), stamp), gitIgnoredDirectory: null };
   }
-  return match18(scope).returnType().with("user", () => ({ path: path14.join(home, USER_BACKUP_DIRECTORY, stamp), gitIgnoredDirectory: null })).with("project", () => {
+  return match19(scope).returnType().with("user", () => ({ path: path14.join(home, USER_BACKUP_DIRECTORY, stamp), gitIgnoredDirectory: null })).with("project", () => {
     const directory = path14.join(cwd, PROJECT_BACKUP_DIRECTORY);
     return { path: path14.join(directory, stamp), gitIgnoredDirectory: directory };
   }).exhaustive();
@@ -3403,31 +3785,31 @@ import path16 from "path";
 import * as v14 from "valibot";
 
 // src/shared/file-formats/config-format.ts
-import { match as match19 } from "ts-pattern";
+import { match as match20 } from "ts-pattern";
 var CONFIG_FORMATS = ["jsonc", "toml"];
 function renderConfig(current, edits) {
-  return match19(edits).with({ format: "jsonc" }, ({ updates }) => renderJsonc(current, updates)).with({ format: "toml" }, ({ updates }) => renderToml(current, updates)).exhaustive();
+  return match20(edits).with({ format: "jsonc" }, ({ updates }) => renderJsonc(current, updates)).with({ format: "toml" }, ({ updates }) => renderToml(current, updates)).exhaustive();
 }
 function readOriginals(current, edits) {
   const keyPaths = edits.updates.map(([keyPath]) => keyPath);
-  return match19(edits.format).with("jsonc", () => readJsoncOriginals(current, keyPaths)).with("toml", () => readTomlOriginals(current, keyPaths)).exhaustive();
+  return match20(edits.format).with("jsonc", () => readJsoncOriginals(current, keyPaths)).with("toml", () => readTomlOriginals(current, keyPaths)).exhaustive();
 }
 function restoreConfig({ format, current, originals }) {
-  return match19(format).with("jsonc", () => restoreJsonc(current, originals)).with("toml", () => restoreToml(current, originals)).exhaustive();
+  return match20(format).with("jsonc", () => restoreJsonc(current, originals)).with("toml", () => restoreToml(current, originals)).exhaustive();
 }
 function isEmptyConfig(format, text2) {
-  const document = match19(format).with("jsonc", () => parseJsonc(text2)).with("toml", () => parseToml(text2)).exhaustive();
+  const document = match20(format).with("jsonc", () => parseJsonc(text2)).with("toml", () => parseToml(text2)).exhaustive();
   return Object.keys(document).length === 0;
 }
 function parseValueSource(format, source) {
-  return match19(format).with("jsonc", () => parseJsoncValue(source)).with("toml", () => parseTomlValue(source)).exhaustive();
+  return match20(format).with("jsonc", () => parseJsoncValue(source)).with("toml", () => parseTomlValue(source)).exhaustive();
 }
 
 // src/shared/file-system/resolve-owner-only-mode.ts
-import { match as match20 } from "ts-pattern";
+import { match as match21 } from "ts-pattern";
 var OWNER_ONLY_MODE = 384;
 function resolveOwnerOnlyMode(platform) {
-  return match20(platform).returnType().with("win32", () => null).otherwise(() => OWNER_ONLY_MODE);
+  return match21(platform).returnType().with("win32", () => null).otherwise(() => OWNER_ONLY_MODE);
 }
 
 // src/shared/file-system/write-file-with-mode.ts
@@ -3467,10 +3849,11 @@ var HarnessRecordSchema = v14.object({
 });
 var RestoreRecordSchema = v14.object({
   version: v14.literal(RECORD_VERSION),
-  harnesses: v14.record(v14.string(), HarnessRecordSchema)
+  harnesses: v14.record(v14.string(), HarnessRecordSchema),
+  userEnvironment: v14.optional(v14.pipe(v14.array(RecordedEnvVariableSchema), v14.readonly()), [])
 });
 function createEmptyRestoreRecord() {
-  return { version: RECORD_VERSION, harnesses: {} };
+  return { version: RECORD_VERSION, harnesses: {}, userEnvironment: [] };
 }
 var RestoreRecordError = class extends Error {
   name = "RestoreRecordError";
@@ -3479,7 +3862,7 @@ function readRestoreRecord({ filePath, home }) {
   const text2 = readFileIfExists(filePath);
   if (text2 === null) return null;
   const shownPath = displayPath(filePath, home);
-  const json = parseJson3(text2);
+  const json = parseJson2(text2);
   if (isNewerRecord(json)) {
     throw new RestoreRecordError(`${shownPath} was written by a newer nexos-connect. Update it, then run again.`);
   }
@@ -3491,14 +3874,6 @@ function readRestoreRecord({ filePath, home }) {
   }
   return parsed.output;
 }
-function parseJson3(text2) {
-  try {
-    return JSON.parse(text2);
-  } catch (error) {
-    if (error instanceof SyntaxError) return void 0;
-    throw error;
-  }
-}
 var VersionSchema = v14.object({ version: v14.number() });
 function isNewerRecord(json) {
   const parsed = v14.safeParse(VersionSchema, json);
@@ -3506,23 +3881,23 @@ function isNewerRecord(json) {
 }
 var RECORD_DIRECTORY_MODE = 448;
 var JSON_INDENT3 = 2;
-function writeRestoreRecord({ filePath, record: record8, platform }) {
-  if (Object.keys(record8.harnesses).length === 0) {
+function writeRestoreRecord({ filePath, record: record9, platform }) {
+  if (Object.keys(record9.harnesses).length === 0 && record9.userEnvironment.length === 0) {
     fs6.rmSync(filePath, { force: true });
     return;
   }
   fs6.mkdirSync(path16.dirname(filePath), { recursive: true, mode: RECORD_DIRECTORY_MODE });
-  const content = `${JSON.stringify(record8, null, JSON_INDENT3)}
+  const content = `${JSON.stringify(record9, null, JSON_INDENT3)}
 `;
   writeFileWithMode({ filePath, content, mode: resolveOwnerOnlyMode(platform) });
 }
 
 // src/product/storage/restore-record/restore-record-location.ts
 import path17 from "path";
-import { match as match21 } from "ts-pattern";
+import { match as match22 } from "ts-pattern";
 var RESTORE_RECORD_FILE = "restore-record.json";
 function resolveRestoreRecordLocation(ctx) {
-  return match21(ctx.scope).returnType().with("user", () => ({
+  return match22(ctx.scope).returnType().with("user", () => ({
     filePath: path17.join(ctx.home, ENV_DIRECTORY_NAME, RESTORE_RECORD_FILE),
     root: ctx.home,
     gitIgnoredDirectory: null
@@ -3553,11 +3928,24 @@ function isInsideRoot(filePath, root) {
   return relativePath !== "" && first !== ".." && !path17.isAbsolute(relativePath);
 }
 
-// src/ui/report/format-restore-preview.ts
-import pc5 from "picocolors";
+// src/ui/report/preview/format-restore-preview.ts
+import pc6 from "picocolors";
 
-// src/ui/report/format-preview.ts
-import pc4 from "picocolors";
+// src/ui/report/format-user-environment.ts
+import pc3 from "picocolors";
+var HEADING = "Windows user environment";
+function formatUserEnvironmentPreview({ userEnvironment: userEnvironment2, masker: masker2 }) {
+  const lines = Object.entries(userEnvironment2.after).flatMap(([name, value]) => {
+    if (userEnvironment2.before[name] === value) return [];
+    if (value === void 0) return [`${INDENT}${pc3.red(`- ${name}`)}`];
+    return [`${INDENT}${pc3.green(`+ ${name}=${masker2.maskText(value)}`)}`];
+  });
+  if (lines.length === 0) return [];
+  return ["", `  ${pc3.bold(HEADING)}`, ...lines];
+}
+
+// src/ui/report/preview/format-preview.ts
+import pc5 from "picocolors";
 
 // src/ui/diff/diff-lines.ts
 function diffLines({ before, after }) {
@@ -3618,15 +4006,15 @@ function buildCommonLengthTable({ beforeLines, afterLines }) {
 }
 
 // src/ui/diff/render-diff.ts
-import pc3 from "picocolors";
-import { match as match22 } from "ts-pattern";
+import pc4 from "picocolors";
+import { match as match23 } from "ts-pattern";
 var DIFF_CONTEXT_LINES = 2;
 var ADDED_PREFIX = "  + ";
 var REMOVED_PREFIX = "  - ";
 var UNCHANGED_PREFIX = "    ";
 function renderDiff(lines) {
   const visibleIndexes = findVisibleIndexes(lines);
-  if (visibleIndexes.size === 0) return [pc3.dim(`${UNCHANGED_PREFIX}(no change)`)];
+  if (visibleIndexes.size === 0) return [pc4.dim(`${UNCHANGED_PREFIX}(no change)`)];
   const rendered = [];
   let isSkipping = false;
   for (const [index, line] of lines.entries()) {
@@ -3635,7 +4023,7 @@ function renderDiff(lines) {
       isSkipping = false;
       continue;
     }
-    if (!isSkipping) rendered.push(pc3.dim(`${UNCHANGED_PREFIX}${GLYPHS.elided}`));
+    if (!isSkipping) rendered.push(pc4.dim(`${UNCHANGED_PREFIX}${GLYPHS.elided}`));
     isSkipping = true;
   }
   return rendered;
@@ -3651,54 +4039,65 @@ function findVisibleIndexes(lines) {
   return visibleIndexes;
 }
 function renderLine(line) {
-  return match22(line.kind).with("added", () => pc3.green(`${ADDED_PREFIX}${line.text}`)).with("removed", () => pc3.red(`${REMOVED_PREFIX}${line.text}`)).with("unchanged", () => pc3.dim(`${UNCHANGED_PREFIX}${line.text}`)).exhaustive();
+  return match23(line.kind).with("added", () => pc4.green(`${ADDED_PREFIX}${line.text}`)).with("removed", () => pc4.red(`${REMOVED_PREFIX}${line.text}`)).with("unchanged", () => pc4.dim(`${UNCHANGED_PREFIX}${line.text}`)).exhaustive();
 }
 
-// src/ui/report/format-preview.ts
+// src/ui/report/preview/format-preview.ts
 var NOTHING_TO_CHANGE = "Nothing to change \u2014 every selected agent is already configured or was skipped.";
 var NOTHING_TO_CHANGE_AFTER_FAILURE = "Nothing to change \u2014 an agent failed while planning; the report below says why.";
-function formatPreview({ changes, model, scope, hasFailedAgent, home, masker: masker2 }) {
-  const heading = formatHeading(`Planned changes ${pc4.dim(`(scope: ${scope}, model: ${masker2.maskText(model)})`)}`);
-  if (changes.length === 0) {
+function formatPreview({
+  changes,
+  userEnvironment: userEnvironment2,
+  model,
+  scope,
+  hasFailedAgent,
+  home,
+  masker: masker2
+}) {
+  const heading = formatHeading(`Planned changes ${pc5.dim(`(scope: ${scope}, model: ${masker2.maskText(model)})`)}`);
+  const userEnvironmentLines = userEnvironment2 === null ? [] : formatUserEnvironmentPreview({ userEnvironment: userEnvironment2, masker: masker2 });
+  if (changes.length === 0 && userEnvironmentLines.length === 0) {
     const note4 = hasFailedAgent ? NOTHING_TO_CHANGE_AFTER_FAILURE : NOTHING_TO_CHANGE;
-    return [...heading, `  ${pc4.dim(note4)}`];
+    return [...heading, `  ${pc5.dim(note4)}`];
   }
-  return [...heading, ...changes.flatMap((change) => formatFileDiff({ change, home, masker: masker2 }))];
+  return [...heading, ...changes.flatMap((change) => formatFileDiff({ change, home, masker: masker2 })), ...userEnvironmentLines];
 }
 function formatFileDiff({ change, home, masker: masker2 }) {
   const diff = diffLines({ before: masker2.maskText(change.before ?? ""), after: masker2.maskText(change.after) });
   const lineCount = formatCount(countChangedLines(diff), "line");
   const lineCountNote = change.before === null ? `new file, ${lineCount}` : lineCount;
-  return ["", `  ${pc4.bold(displayPath(change.path, home))} ${pc4.dim(`(${lineCountNote})`)}`, ...renderDiff(diff)];
+  return ["", `  ${pc5.bold(displayPath(change.path, home))} ${pc5.dim(`(${lineCountNote})`)}`, ...renderDiff(diff)];
 }
 
-// src/ui/report/format-restore-preview.ts
+// src/ui/report/preview/format-restore-preview.ts
 var NOTHING_TO_RESTORE = "Nothing to change \u2014 every selected agent is already as it was.";
 var NOTHING_TO_RESTORE_AFTER_FAILURE = "Nothing to change \u2014 an agent failed while planning; the report below says why.";
 function formatRestorePreview(params) {
-  const { files, envFile, scope, hasFailedAgent, home, masker: masker2 } = params;
-  const heading = formatHeading(`Planned restore ${pc5.dim(`(scope: ${scope})`)}`);
+  const { files, envFile, userEnvironment: userEnvironment2, scope, hasFailedAgent, home, masker: masker2 } = params;
+  const heading = formatHeading(`Planned restore ${pc6.dim(`(scope: ${scope})`)}`);
   const changedFiles = files.filter((file) => file.isChanged);
   const changedEnvFile = envFile?.isChanged === true ? [envFile] : [];
-  if (changedFiles.length === 0 && changedEnvFile.length === 0) {
-    return [...heading, `  ${pc5.dim(hasFailedAgent ? NOTHING_TO_RESTORE_AFTER_FAILURE : NOTHING_TO_RESTORE)}`];
+  const userEnvironmentLines = userEnvironment2 === null ? [] : formatUserEnvironmentPreview({ userEnvironment: userEnvironment2, masker: masker2 });
+  if (changedFiles.length === 0 && changedEnvFile.length === 0 && userEnvironmentLines.length === 0) {
+    return [...heading, `  ${pc6.dim(hasFailedAgent ? NOTHING_TO_RESTORE_AFTER_FAILURE : NOTHING_TO_RESTORE)}`];
   }
   return [
     ...heading,
     ...changedFiles.flatMap((file) => formatRestoredFile({ file, home, masker: masker2 })),
-    ...changedEnvFile.flatMap((change) => formatFileDiff({ change, home, masker: masker2 }))
+    ...changedEnvFile.flatMap((change) => formatFileDiff({ change, home, masker: masker2 })),
+    ...userEnvironmentLines
   ];
 }
 var DELETION_NOTE = "deleted \u2014 nexos-connect created it";
 function formatRestoredFile({ file, home, masker: masker2 }) {
-  if (file.after === null) return ["", `  ${pc5.bold(displayPath(file.path, home))} ${pc5.dim(`(${DELETION_NOTE})`)}`];
+  if (file.after === null) return ["", `  ${pc6.bold(displayPath(file.path, home))} ${pc6.dim(`(${DELETION_NOTE})`)}`];
   const change = { path: file.path, before: file.before, after: file.after, isChanged: file.isChanged };
   return formatFileDiff({ change, home, masker: masker2 });
 }
 
-// src/ui/report/format-restore-result.ts
-import pc6 from "picocolors";
-import { P as P4, match as match23 } from "ts-pattern";
+// src/ui/report/result/format-restore-result.ts
+import pc7 from "picocolors";
+import { P as P5, match as match24 } from "ts-pattern";
 
 // src/commands/restore/restore-result.ts
 var RESTORE_OUTCOME_KINDS = ["restored", "unchanged", "nothing-to-restore", "failed"];
@@ -3710,7 +4109,7 @@ function exitCodeForRestore(outcomes) {
   return isFailed ? EXIT_CODE.failed : EXIT_CODE.ok;
 }
 
-// src/ui/report/format-restore-result.ts
+// src/ui/report/result/format-restore-result.ts
 function formatRestoreResult(params) {
   const heading = params.mode.kind === "dry-run" ? "Result (dry run)" : "Result";
   return [
@@ -3722,45 +4121,51 @@ function formatRestoreResult(params) {
   ];
 }
 var RESTORE_OUTCOME_STYLE = {
-  restored: { glyph: GLYPHS.success, colour: pc6.green, label: "restored" },
-  unchanged: { glyph: GLYPHS.unchanged, colour: pc6.green, label: "already as it was" },
-  "nothing-to-restore": { glyph: GLYPHS.absent, colour: pc6.yellow, label: "nothing to restore" },
-  failed: { glyph: GLYPHS.failure, colour: pc6.red, label: "failed" }
+  restored: { glyph: GLYPHS.success, colour: pc7.green, label: "restored" },
+  unchanged: { glyph: GLYPHS.unchanged, colour: pc7.green, label: "already as it was" },
+  "nothing-to-restore": { glyph: GLYPHS.absent, colour: pc7.yellow, label: "nothing to restore" },
+  failed: { glyph: GLYPHS.failure, colour: pc7.red, label: "failed" }
 };
 var NO_RECORD = "nexos-connect has no record of setting it up at this scope.";
 function formatOutcome(outcome, { home, masker: masker2 }) {
   const style = RESTORE_OUTCOME_STYLE[outcome.kind];
-  const body = match23(outcome).with({ kind: P4.union("restored", "unchanged") }, (planned) => formatPlannedRestore(planned, home, masker2)).with({ kind: "nothing-to-restore" }, () => [`${INDENT}${pc6.dim(NO_RECORD)}`]).with({ kind: "failed" }, ({ error }) => [`${INDENT}${pc6.red(masker2.maskText(error))}`]).exhaustive();
+  const body = match24(outcome).with({ kind: P5.union("restored", "unchanged") }, (planned) => formatPlannedRestore(planned, home, masker2)).with({ kind: "nothing-to-restore" }, () => [`${INDENT}${pc7.dim(NO_RECORD)}`]).with({ kind: "failed" }, ({ error }) => [`${INDENT}${pc7.red(masker2.maskText(error))}`]).exhaustive();
   return ["", `  ${style.colour(`${style.glyph} ${outcome.target.label} \u2014 ${style.label}`)}`, ...body];
 }
 function formatPlannedRestore(outcome, home, masker2) {
   const restartNote = `Restart ${outcome.target.label} so it reads the restored config.`;
   return [
-    ...outcome.files.filter((file) => file.isChanged).map((file) => `${INDENT}${pc6.dim(describeFile(file, home))}`),
-    ...outcome.warnings.map((warning) => `${INDENT}${pc6.yellow(`${GLYPHS.warning} ${masker2.maskText(warning)}`)}`),
-    ...outcome.kind === "restored" ? [`${INDENT}${pc6.cyan(`${GLYPHS.next} ${restartNote}`)}`] : []
+    ...outcome.files.filter((file) => file.isChanged).map((file) => `${INDENT}${pc7.dim(describeFile(file, home))}`),
+    ...outcome.warnings.map((warning) => `${INDENT}${pc7.yellow(`${GLYPHS.warning} ${masker2.maskText(warning)}`)}`),
+    ...outcome.kind === "restored" ? [`${INDENT}${pc7.cyan(`${GLYPHS.next} ${restartNote}`)}`] : []
   ];
 }
 function describeFile(file, home) {
   const action = file.after === null ? "deleted" : "put back";
   return `${displayPath(file.path, home)} \u2014 ${action}`;
 }
-function formatEnvFileStep({ envFile, mode, home }) {
-  if (mode.kind === "dry-run" || envFile === null || !envFile.isChanged) return [];
+function formatEnvFileStep({ envFile, userEnvironment: userEnvironment2, mode, home }) {
+  if (mode.kind === "dry-run") return [];
+  const envFileLines = envFile !== null && envFile.isChanged ? describeEnvFile(envFile, home) : [];
+  const userEnvironmentLines = userEnvironment2 === null ? [] : [`  ${pc7.dim("The Windows user environment changed; open a new terminal to pick it up.")}`];
+  if (envFileLines.length === 0 && userEnvironmentLines.length === 0) return [];
+  return [...formatHeading("One more step"), ...envFileLines, ...userEnvironmentLines];
+}
+function describeEnvFile(envFile, home) {
   const isEmpty = parseEnvFile(envFile.after, envFile.shell).size === 0;
   const emptyNote = `${displayPath(envFile.path, home)} no longer sets anything: you can delete it, and the line that loads it.`;
   return [
-    ...formatHeading("One more step"),
     ...isEmpty ? [`  ${emptyNote}`] : [],
-    `  ${pc6.dim("Shells open now keep the variables it set; a new shell starts without them.")}`
+    `  ${pc7.dim("Shells open now keep the variables it set; a new shell starts without them.")}`
   ];
 }
 function formatBackups({ mode, home, masker: masker2 }) {
   if (mode.kind === "dry-run" || mode.backupRoot === null) return [];
   const backupRoot = masker2.maskText(displayPath(mode.backupRoot, home));
-  return [...formatHeading("Backups"), `  Current versions copied to ${pc6.bold(backupRoot)}`];
+  return [...formatHeading("Backups"), `  Current versions copied to ${pc7.bold(backupRoot)}`];
 }
 function formatSummary(outcomes) {
+  if (outcomes.length === 0) return [];
   const countsByKind = /* @__PURE__ */ new Map();
   for (const { kind } of outcomes) countsByKind.set(kind, (countsByKind.get(kind) ?? 0) + 1);
   const counts = RESTORE_OUTCOME_KINDS.map(
@@ -3831,9 +4236,102 @@ function writeEnvFile({ filePath, content, platform }) {
 }
 
 // src/product/storage/restore-record/remove-harness-records.ts
-function removeHarnessRecords(record8, harnessIds) {
-  const harnesses2 = Object.fromEntries(Object.entries(record8.harnesses).filter(([id]) => !harnessIds.includes(id)));
-  return { ...record8, harnesses: harnesses2 };
+function removeHarnessRecords(record9, harnessIds) {
+  const harnesses2 = Object.fromEntries(Object.entries(record9.harnesses).filter(([id]) => !harnessIds.includes(id)));
+  return { ...record9, harnesses: harnesses2, userEnvironment: pruneUserEnvironment(record9, harnesses2) };
+}
+function pruneUserEnvironment(record9, harnesses2) {
+  const referencedNames = new Set(
+    Object.values(harnesses2).flatMap((harness) => harness.envVariables.map(({ name }) => name))
+  );
+  return record9.userEnvironment.filter(({ name }) => referencedNames.has(name));
+}
+
+// src/product/storage/windows-environment/describe-user-environment-failure.ts
+function describeUserEnvironmentFailure({
+  action,
+  envPath,
+  home
+}) {
+  const fallback4 = displayPath(envPath, home);
+  if (action === "read") {
+    return `Could not read the Windows user environment, so it was left as it is. The key is still in ${fallback4}.`;
+  }
+  return `Could not set the key in the Windows user environment, so a new terminal will not see it yet. The key is still in ${fallback4} \u2014 load it there, or set the variable yourself.`;
+}
+
+// src/product/storage/windows-environment/user-environment.ts
+import * as v15 from "valibot";
+var UserEnvironmentError = class extends Error {
+  name = "UserEnvironmentError";
+};
+var NO_OP_USER_ENVIRONMENT = {
+  read: () => ({}),
+  write: () => {
+  }
+};
+function createUserEnvironment({ platform, runPowerShell: runPowerShell2 }) {
+  if (platform !== "win32") return NO_OP_USER_ENVIRONMENT;
+  return {
+    read: (names) => readUserEnvironment({ names, runPowerShell: runPowerShell2 }),
+    write: (values) => writeUserEnvironment({ values, runPowerShell: runPowerShell2 })
+  };
+}
+function planUserEnvironment({
+  values,
+  userEnvironment: userEnvironment2
+}) {
+  const names = Object.keys(values);
+  if (names.length === 0) return null;
+  const before = userEnvironment2.read(names);
+  return { before, after: values, isChanged: names.some((name) => before[name] !== values[name]) };
+}
+function replanUserEnvironment({ plan, names }) {
+  if (plan === null) return null;
+  if (names === null) return plan;
+  const after = Object.fromEntries(Object.entries(plan.after).filter(([name]) => names.has(name)));
+  if (Object.keys(after).length === 0) return null;
+  const isChanged = Object.entries(after).some(([name, value]) => plan.before[name] !== value);
+  return { before: plan.before, after, isChanged };
+}
+var READ_SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$names = ([Console]::In.ReadToEnd() | ConvertFrom-Json).names",
+  "$result = [ordered]@{}",
+  "foreach ($name in $names) { $result[$name] = [Environment]::GetEnvironmentVariable($name, 'User') }",
+  "$result | ConvertTo-Json -Compress"
+].join("\n");
+var WRITE_SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$values = ([Console]::In.ReadToEnd() | ConvertFrom-Json).values",
+  "foreach ($property in $values.PSObject.Properties) {",
+  "  [Environment]::SetEnvironmentVariable($property.Name, $property.Value, 'User')",
+  "}"
+].join("\n");
+var REPLY_SCHEMA = v15.record(v15.string(), v15.nullable(v15.string()));
+function readUserEnvironment({ names, runPowerShell: runPowerShell2 }) {
+  const result = runPowerShell2({ script: READ_SCRIPT, input: JSON.stringify({ names }) });
+  if (result.code !== 0) {
+    throw new UserEnvironmentError(`the Windows user environment could not be read (PowerShell exited ${result.code})`);
+  }
+  const reply = parseReply(result.stdout);
+  return Object.fromEntries(names.map((name) => [name, reply[name] ?? void 0]));
+}
+function parseReply(stdout) {
+  const parsed = v15.safeParse(REPLY_SCHEMA, parseJson2(stdout));
+  if (!parsed.success) throw new UserEnvironmentError("the Windows user environment replied with something unexpected");
+  return parsed.output;
+}
+function writeUserEnvironment({ values, runPowerShell: runPowerShell2 }) {
+  const payload = JSON.stringify({
+    values: Object.fromEntries(Object.entries(values).map(([name, value]) => [name, value ?? null]))
+  });
+  const result = runPowerShell2({ script: WRITE_SCRIPT, input: payload });
+  if (result.code !== 0) {
+    throw new UserEnvironmentError(
+      `the Windows user environment could not be written (PowerShell exited ${result.code})`
+    );
+  }
 }
 
 // src/product/storage/env-file/render-env-file.ts
@@ -3942,10 +4440,12 @@ function applyRestore(params) {
   const outcomes = agentWrites.map(({ outcome }) => outcome);
   const envFile = replanEnvFile(params.plan.envFile, outcomes);
   const envWrite = restoreSharedEnvFile({ outcomes, envFile, params });
+  const userEnvironmentWrite = restoreUserEnvironment({ outcomes: envWrite.outcomes, params });
   const writtenFiles = [...agentWrites.flatMap(({ writtenFiles: writtenFiles2 }) => writtenFiles2), ...envWrite.writtenFiles];
   return {
-    outcomes: forgetRestored(envWrite.outcomes, params.ctx),
+    outcomes: forgetRestored(userEnvironmentWrite.outcomes, params.ctx, userEnvironmentWrite.written !== null),
     envFile,
+    userEnvironment: userEnvironmentWrite.written,
     writtenCount: writtenFiles.length,
     backupRoot: writtenFiles.some((file) => file.isBackedUp) ? params.backupRoot.path : null
   };
@@ -4003,14 +4503,36 @@ function failIfRestoringEnvFile(outcome, error) {
   if (!isPlannedRestore(outcome) || outcome.envVariables.length === 0) return outcome;
   return { kind: "failed", target: outcome.target, error };
 }
-function forgetRestored(outcomes, ctx) {
+function restoreUserEnvironment({ outcomes, params }) {
+  const { userEnvironment: userEnvironment2, envPath, ctx } = params;
+  const plan = replanUserEnvironment({ plan: params.plan.userEnvironment, names: userEnvironmentNames(outcomes) });
+  if (plan === null || !plan.isChanged) return { outcomes: [...outcomes], written: null };
+  try {
+    userEnvironment2.write(plan.after);
+    return { outcomes: [...outcomes], written: plan };
+  } catch {
+    const warning = describeUserEnvironmentFailure({ action: "write", envPath, home: ctx.home });
+    return { outcomes: outcomes.map((outcome) => addUserEnvironmentWarningTo(outcome, warning)), written: null };
+  }
+}
+function addUserEnvironmentWarningTo(outcome, warning) {
+  if (!isPlannedRestore(outcome) || outcome.envVariables.length === 0) return outcome;
+  return { ...outcome, warnings: [...outcome.warnings, warning] };
+}
+function userEnvironmentNames(outcomes) {
+  if (outcomes.length === 0) return null;
+  return new Set(
+    outcomes.flatMap((outcome) => isPlannedRestore(outcome) ? outcome.envVariables.map(({ name }) => name) : [])
+  );
+}
+function forgetRestored(outcomes, ctx, isUserEnvironmentRestored) {
   const restoredIds = outcomes.filter(isPlannedRestore).map(({ target }) => target.id);
-  if (restoredIds.length === 0) return [...outcomes];
+  if (restoredIds.length === 0 && !isUserEnvironmentRestored) return [...outcomes];
   const { filePath } = resolveRestoreRecordLocation(ctx);
   try {
-    const record8 = readRestoreRecord({ filePath, home: ctx.home });
-    if (record8 !== null) {
-      writeRestoreRecord({ filePath, record: removeHarnessRecords(record8, restoredIds), platform: ctx.platform });
+    const record9 = readRestoreRecord({ filePath, home: ctx.home });
+    if (record9 !== null) {
+      writeRestoreRecord({ filePath, record: removeHarnessRecords(record9, restoredIds), platform: ctx.platform });
     }
     return [...outcomes];
   } catch (error) {
@@ -4025,7 +4547,7 @@ function failIfPlanned(outcome, error) {
 
 // src/commands/restore/restore-plan.ts
 import path20 from "path";
-import { match as match24 } from "ts-pattern";
+import { match as match25 } from "ts-pattern";
 
 // src/product/storage/env-file/read-env-file.ts
 var NO_ENV_FILE = { kind: "read", text: null };
@@ -4040,28 +4562,79 @@ function readEnvFile({ envPath, home }) {
 // src/commands/restore/restore-plan.ts
 function planRestore(params) {
   const { candidates, ctx, envPath } = params;
-  const hasEnvVariables2 = candidates.some(({ record: record8 }) => (record8?.envVariables.length ?? 0) > 0);
+  const hasEnvVariables2 = candidates.some(({ record: record9 }) => (record9?.envVariables.length ?? 0) > 0);
   const envFileRead = hasEnvVariables2 ? readEnvFile({ envPath, home: ctx.home }) : NO_ENV_FILE;
   const namesKept = listNamesRecordedElsewhere(params);
-  const outcomes = candidates.map((candidate) => planCandidate({ candidate, envFileRead, namesKept, params }));
-  return { outcomes, envFile: planEnvFile({ outcomes, envFileRead, params }) };
+  const userEnvironment2 = planRestoreUserEnvironment({ candidates, record: params.record, namesKept, params });
+  const outcomes = candidates.map(
+    (candidate) => planCandidate({ candidate, envFileRead, namesKept, userEnvironment: userEnvironment2.plan, params })
+  );
+  return {
+    outcomes: addUserEnvironmentWarning({ outcomes, warning: userEnvironment2.warning }),
+    envFile: planEnvFile({ outcomes, envFileRead, params }),
+    userEnvironment: userEnvironment2.plan
+  };
 }
-function listNamesRecordedElsewhere({ candidates, record: record8 }) {
+function listNamesRecordedElsewhere({ candidates, record: record9 }) {
   const selectedIds = candidates.map(({ target }) => target.id);
-  const others = Object.entries(record8.harnesses).filter(([id]) => !selectedIds.includes(id));
+  const others = Object.entries(record9.harnesses).filter(([id]) => !selectedIds.includes(id));
   return new Set(others.flatMap(([, harness]) => harness.envVariables.map(({ name }) => name)));
 }
-function planCandidate({ candidate, envFileRead, namesKept, params }) {
-  const { target, record: record8 } = candidate;
-  if (record8 === null) return { kind: "nothing-to-restore", target };
-  const envVariables = record8.envVariables.filter(({ name }) => !namesKept.has(name));
+function planRestoreUserEnvironment({
+  candidates,
+  record: record9,
+  namesKept,
+  params
+}) {
+  if (params.ctx.platform !== "win32") return { plan: null, warning: null };
+  const originals = new Map(record9.userEnvironment.map(({ name, original }) => [name, original]));
+  const names = listRestorableNames({ candidates, record: record9 });
+  const values = Object.fromEntries(
+    names.flatMap(
+      (name) => !namesKept.has(name) && originals.has(name) ? [[name, originals.get(name) ?? void 0]] : []
+    )
+  );
+  if (Object.keys(values).length === 0) return { plan: null, warning: null };
+  try {
+    return { plan: planUserEnvironment({ values, userEnvironment: params.userEnvironment }), warning: null };
+  } catch (error) {
+    if (!(error instanceof UserEnvironmentError)) throw error;
+    return {
+      plan: null,
+      warning: describeUserEnvironmentFailure({ action: "read", envPath: params.envPath, home: params.ctx.home })
+    };
+  }
+}
+function listRestorableNames({ candidates, record: record9 }) {
+  if (candidates.length === 0) return record9.userEnvironment.map(({ name }) => name);
+  return candidates.flatMap(({ record: harness }) => (harness?.envVariables ?? []).map(({ name }) => name));
+}
+function addUserEnvironmentWarning({ outcomes, warning }) {
+  if (warning === null) return [...outcomes];
+  return outcomes.map(
+    (outcome) => isPlannedRestore(outcome) && outcome.envVariables.length > 0 ? { ...outcome, warnings: [...outcome.warnings, warning] } : outcome
+  );
+}
+function planCandidate({
+  candidate,
+  envFileRead,
+  namesKept,
+  userEnvironment: userEnvironment2,
+  params
+}) {
+  const { target, record: record9 } = candidate;
+  if (record9 === null) return { kind: "nothing-to-restore", target };
+  const envVariables = record9.envVariables.filter(({ name }) => !namesKept.has(name));
   if (envVariables.length > 0 && envFileRead.kind === "failed") {
     return { kind: "failed", target, error: envFileRead.error };
   }
   try {
-    const { files, warnings } = planRecordedFiles(record8.files, params.ctx);
+    const { files, warnings } = planRecordedFiles(record9.files, params.ctx);
     const hasEnvChange = hasOwnEnvChange({ envFileRead, envVariables, shell: params.shell });
-    const isChanged = hasEnvChange || files.some((file) => file.isChanged);
+    const hasUserEnvironmentChange = userEnvironment2 !== null && envVariables.some(
+      ({ name }) => name in userEnvironment2.after && userEnvironment2.before[name] !== userEnvironment2.after[name]
+    );
+    const isChanged = hasEnvChange || hasUserEnvironmentChange || files.some((file) => file.isChanged);
     return { kind: isChanged ? "restored" : "unchanged", target, files, envVariables, warnings };
   } catch (error) {
     return { kind: "failed", target, error: describeFileError({ error, action: "read", home: params.ctx.home }) };
@@ -4091,7 +4664,7 @@ function planRecordedFile(file, ctx) {
   };
 }
 function describeMissingFile(filePath, ctx) {
-  const backups = match24(ctx.scope).with("user", () => path20.join(ctx.home, USER_BACKUP_DIRECTORY)).with("project", () => path20.join(ctx.cwd, PROJECT_BACKUP_DIRECTORY)).exhaustive();
+  const backups = match25(ctx.scope).with("user", () => path20.join(ctx.home, USER_BACKUP_DIRECTORY)).with("project", () => path20.join(ctx.cwd, PROJECT_BACKUP_DIRECTORY)).exhaustive();
   return `${displayPath(filePath, ctx.home)} no longer exists, so it was left as it is. Copies from before each run are under ${displayPath(backups, ctx.home)}, unless --backup-dir put them elsewhere.`;
 }
 function restoreFile2({ file, before, filePath, home }) {
@@ -4113,12 +4686,16 @@ function planEnvFile({ outcomes, envFileRead, params }) {
 }
 
 // src/commands/restore/restore-secrets.ts
-function listRestoreSecrets({ record: record8, ctx, envPath, shell }) {
-  const recorded = Object.values(record8.harnesses).flatMap((harness) => [
+function listRestoreSecrets({ record: record9, ctx, envPath, shell }) {
+  const recorded = Object.values(record9.harnesses).flatMap((harness) => [
     ...harness.files.flatMap(listFileSecrets),
     ...listEnvSecrets(harness)
   ]);
-  return [...findExistingKeys({ ctx, envPath, shell }).all, ...recorded];
+  return [
+    ...findExistingKeys({ ctx, envPath, shell }).all,
+    ...recorded,
+    ...listUserEnvironmentSecrets(record9.userEnvironment)
+  ];
 }
 function listFileSecrets(file) {
   return file.keys.flatMap(({ original, holdsSecret }) => {
@@ -4143,6 +4720,11 @@ function listEnvSecrets(harness) {
     ({ name, original }) => KEY_ENV_VARIABLES.includes(name) && original !== null ? [original] : []
   );
 }
+function listUserEnvironmentSecrets(variables) {
+  return variables.flatMap(
+    ({ name, original }) => KEY_ENV_VARIABLES.includes(name) && original !== null ? [original] : []
+  );
+}
 
 // src/commands/restore/run-restore.ts
 var FINISHED_WITH_ERRORS = "Finished with errors.";
@@ -4161,27 +4743,28 @@ async function runRestore(params) {
     ui.outro(FINISHED_WITH_ERRORS);
     return EXIT_CODE.failed;
   }
-  const { record: record8 } = recordRead;
-  if (namedHarnesses.length === 0 && Object.keys(record8.harnesses).length === 0) {
+  const { record: record9 } = recordRead;
+  const hasRecordedHarnesses = Object.keys(record9.harnesses).length > 0;
+  if (namedHarnesses.length === 0 && !hasRecordedHarnesses && record9.userEnvironment.length === 0) {
     const recordPath = displayPath(resolveRestoreRecordLocation(ctx).filePath, ctx.home);
     ui.outro(`Nothing to restore \u2014 nexos-connect has not set up any agent at ${scope} scope (${recordPath}).`);
     return EXIT_CODE.ok;
   }
   const candidates = await selectCandidates({
     namedHarnesses,
-    record: record8,
+    record: record9,
     ctx,
     shouldAssumeYes: options.shouldAssumeYes,
     ui
   });
-  if (candidates.length === 0) {
+  if (candidates.length === 0 && hasRecordedHarnesses) {
     ui.cancel("No agents selected \u2014 nothing to do.");
     return EXIT_CODE.ok;
   }
   const run = { ...params, ui, ctx };
-  const plan = planSelected({ run, candidates, record: record8 });
+  const plan = planSelected({ run, candidates, record: record9 });
   if (options.isDryRun) return report({ run, plan, mode: { kind: "dry-run" }, outro: DRY_RUN_OUTRO });
-  const hasChanges = plan.outcomes.some((outcome) => outcome.kind === "restored");
+  const hasChanges = plan.outcomes.some((outcome) => outcome.kind === "restored") || plan.userEnvironment?.isChanged === true;
   if (hasChanges && !options.shouldAssumeYes && !await ui.confirm(CONFIRMATION, true)) {
     ui.cancel("Aborted \u2014 nothing was restored.");
     return EXIT_CODE.cancelled;
@@ -4189,7 +4772,12 @@ async function runRestore(params) {
   const applied = applySelected(run, plan);
   const outro3 = exitCodeForRestore(applied.outcomes) === EXIT_CODE.ok ? "Done." : FINISHED_WITH_ERRORS;
   const mode = { kind: "written", backupRoot: applied.backupRoot };
-  return report({ run, plan: { outcomes: applied.outcomes, envFile: applied.envFile }, mode, outro: outro3 });
+  return report({
+    run,
+    plan: { outcomes: applied.outcomes, envFile: applied.envFile, userEnvironment: applied.userEnvironment },
+    mode,
+    outro: outro3
+  });
 }
 async function resolveRestoreScope({ options, baseContext, ui }) {
   if (options.scope !== void 0) return options.scope;
@@ -4206,8 +4794,8 @@ function listRecordedLabels(ctx) {
 }
 function readRecord(ctx) {
   try {
-    const record8 = readRestoreRecord({ filePath: resolveRestoreRecordLocation(ctx).filePath, home: ctx.home });
-    return { kind: "read", record: record8 ?? createEmptyRestoreRecord() };
+    const record9 = readRestoreRecord({ filePath: resolveRestoreRecordLocation(ctx).filePath, home: ctx.home });
+    return { kind: "read", record: record9 ?? createEmptyRestoreRecord() };
   } catch (error) {
     if (!(error instanceof RestoreRecordError)) throw error;
     return { kind: "failed", error: error.message };
@@ -4217,34 +4805,43 @@ function labelOf(harnessId) {
   return findHarness(harnessId)?.label ?? harnessId;
 }
 async function selectCandidates(params) {
-  const { namedHarnesses, record: record8, ctx, ui } = params;
-  if (namedHarnesses.length > 0) return namedHarnesses.map((harness) => toCandidate(harness.id, record8));
-  const recordedIds = Object.keys(record8.harnesses);
-  if (params.shouldAssumeYes) return recordedIds.map((id) => toCandidate(id, record8));
-  const chosenIds = await ui.selectRestoreHarnesses(recordedIds.map((id) => describeChoice({ id, record: record8, ctx })));
-  return chosenIds.map((id) => toCandidate(id, record8));
+  const { namedHarnesses, record: record9, ctx, ui } = params;
+  if (namedHarnesses.length > 0) return namedHarnesses.map((harness) => toCandidate(harness.id, record9));
+  const recordedIds = Object.keys(record9.harnesses);
+  if (recordedIds.length === 0) return [];
+  if (params.shouldAssumeYes) return recordedIds.map((id) => toCandidate(id, record9));
+  const chosenIds = await ui.selectRestoreHarnesses(recordedIds.map((id) => describeChoice({ id, record: record9, ctx })));
+  return chosenIds.map((id) => toCandidate(id, record9));
 }
-function toCandidate(id, record8) {
-  return { target: { id, label: labelOf(id) }, record: record8.harnesses[id] ?? null };
+function toCandidate(id, record9) {
+  return { target: { id, label: labelOf(id) }, record: record9.harnesses[id] ?? null };
 }
 var ENV_VARIABLES_HINT = "environment variables";
-function describeChoice({ id, record: record8, ctx }) {
-  const harness = record8.harnesses[id];
+function describeChoice({ id, record: record9, ctx }) {
+  const harness = record9.harnesses[id];
   const root = resolveRestoreRecordLocation(ctx).root;
   const files = (harness?.files ?? []).map((file) => displayPath(path21.join(root, ...file.path), ctx.home));
   const variables = (harness?.envVariables.length ?? 0) > 0 ? [ENV_VARIABLES_HINT] : [];
   return { value: id, label: labelOf(id), hint: [...files, ...variables].join(", ") };
 }
-function planSelected({ run, candidates, record: record8 }) {
+function planSelected({ run, candidates, record: record9 }) {
   const { ctx, masker: masker2, ui } = run;
   const shell = resolveShell(ctx.platform);
   const envPath = resolveEnvFilePath(ctx.home, shell);
-  masker2.registerSecrets(listRestoreSecrets({ record: record8, ctx, envPath, shell }));
-  const plan = planRestore({ candidates, record: record8, ctx, envPath, shell });
+  masker2.registerSecrets(listRestoreSecrets({ record: record9, ctx, envPath, shell }));
+  const plan = planRestore({ candidates, record: record9, ctx, envPath, shell, userEnvironment: run.userEnvironment });
   const files = plan.outcomes.flatMap((outcome) => isPlannedRestore(outcome) ? outcome.files : []);
   const hasFailedAgent = plan.outcomes.some((outcome) => outcome.kind === "failed");
   ui.print(
-    formatRestorePreview({ files, envFile: plan.envFile, scope: ctx.scope, hasFailedAgent, home: ctx.home, masker: masker2 })
+    formatRestorePreview({
+      files,
+      envFile: plan.envFile,
+      userEnvironment: plan.userEnvironment,
+      scope: ctx.scope,
+      hasFailedAgent,
+      home: ctx.home,
+      masker: masker2
+    })
   );
   return plan;
 }
@@ -4257,21 +4854,71 @@ function applySelected(run, plan) {
     stamp: formatBackupTimestamp(run.now()),
     backupDirectory: options.backupDirectory
   });
+  const shell = resolveShell(ctx.platform);
+  const envPath = resolveEnvFilePath(ctx.home, shell);
   const spinner = ui.spinner();
   spinner.start("Backing up current versions and restoring\u2026");
-  const applied = applyRestore({ plan, ctx, backupRoot });
+  const applied = applyRestore({ plan, ctx, backupRoot, userEnvironment: run.userEnvironment, envPath });
   spinner.stop(`Restored ${formatCount(applied.writtenCount, "file")}.`);
   return applied;
 }
 function report({ run, plan, mode, outro: outro3 }) {
   const { ui, ctx, masker: masker2 } = run;
-  ui.print(formatRestoreResult({ outcomes: plan.outcomes, envFile: plan.envFile, mode, home: ctx.home, masker: masker2 }));
+  ui.print(
+    formatRestoreResult({
+      outcomes: plan.outcomes,
+      envFile: plan.envFile,
+      userEnvironment: plan.userEnvironment,
+      mode,
+      home: ctx.home,
+      masker: masker2
+    })
+  );
   ui.outro(outro3);
   return exitCodeForRestore(plan.outcomes);
 }
 
-// src/ui/report/format-detection.ts
-import pc7 from "picocolors";
+// src/flows/install/install-missing-harnesses.ts
+var NOTHING_INSTALLED = { installedCount: 0, hasFailure: false };
+async function installMissingHarnesses(params) {
+  const { notInstalled, isPickerDriven, options, ctx, ui, runNpm: runNpm2 } = params;
+  if (ctx.scope !== "user") return NOTHING_INSTALLED;
+  const missing = notInstalled.filter(isInstallable);
+  if (missing.length === 0) return NOTHING_INSTALLED;
+  if (options.isDryRun) {
+    ui.dim("Dry run \u2014 the missing agents were not installed.");
+    return NOTHING_INSTALLED;
+  }
+  let installedCount = 0;
+  let hasFailure = false;
+  for (const harness of missing) {
+    const outcome = await installHarness({
+      label: harness.label,
+      binary: harness.binary,
+      packageName: harness.installPackage,
+      shouldInstall: options.shouldInstall || isPickerDriven,
+      shouldAssumeYes: options.shouldAssumeYes,
+      ui,
+      ctx,
+      runNpm: runNpm2
+    });
+    if (outcome.kind === "installed") installedCount += 1;
+    else if (outcome.kind === "not-on-path") {
+      ui.log.error(describeNotOnPath(harness));
+      hasFailure = true;
+    } else if (outcome.kind === "failed") {
+      ui.log.error(outcome.message);
+      hasFailure = true;
+    }
+  }
+  return { installedCount, hasFailure };
+}
+function isInstallable(harness) {
+  return harness.kind === "configurable" && harness.installPackage !== void 0;
+}
+
+// src/ui/report/detection/format-detection.ts
+import pc8 from "picocolors";
 function formatDetection(rows, masker2) {
   return [
     ...formatHeading("Where each agent keeps its settings"),
@@ -4280,16 +4927,16 @@ function formatDetection(rows, masker2) {
 }
 var LABEL_COLUMN_WIDTH = 24;
 var DETECTION_STYLE = {
-  found: { glyph: GLYPHS.success, colour: pc7.green, label: "found" },
-  "not-found": { glyph: GLYPHS.absent, colour: pc7.dim, label: "not found" },
-  failed: { glyph: GLYPHS.failure, colour: pc7.red, label: "could not check" },
-  "not-configurable": { glyph: GLYPHS.failure, colour: pc7.yellow, label: "not configurable" }
+  found: { glyph: GLYPHS.success, colour: pc8.green, label: "found" },
+  "not-found": { glyph: GLYPHS.absent, colour: pc8.dim, label: "not found" },
+  failed: { glyph: GLYPHS.failure, colour: pc8.red, label: "could not check" },
+  "not-configurable": { glyph: GLYPHS.failure, colour: pc8.yellow, label: "not configurable" }
 };
 function formatDetectionRow({ harness, detection }, masker2) {
   const style = DETECTION_STYLE[findDetectionStatus(harness, detection)];
   return [
     `  ${style.colour(style.glyph)} ${harness.label.padEnd(LABEL_COLUMN_WIDTH)} ${style.colour(style.label)}`,
-    `${INDENT}${pc7.dim(masker2.maskText(detection.detail))}`
+    `${INDENT}${pc8.dim(masker2.maskText(detection.detail))}`
   ];
 }
 function findDetectionStatus(harness, detection) {
@@ -4297,9 +4944,9 @@ function findDetectionStatus(harness, detection) {
   return detection.kind;
 }
 
-// src/ui/report/format-result.ts
-import pc9 from "picocolors";
-import { P as P5, match as match25 } from "ts-pattern";
+// src/ui/report/result/format-result.ts
+import pc10 from "picocolors";
+import { P as P6, match as match26 } from "ts-pattern";
 
 // src/commands/setup/setup-result.ts
 var OUTCOME_KINDS = ["updated", "unchanged", "not-found", "unsupported", "failed"];
@@ -4317,16 +4964,16 @@ function formatList(items) {
 }
 
 // src/ui/report/outcome-style.ts
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 var OUTCOME_STYLE = {
-  updated: { glyph: GLYPHS.success, colour: pc8.green, label: "updated" },
-  unchanged: { glyph: GLYPHS.unchanged, colour: pc8.green, label: "already configured" },
-  "not-found": { glyph: GLYPHS.absent, colour: pc8.dim, label: "not found" },
-  unsupported: { glyph: GLYPHS.failure, colour: pc8.yellow, label: "not configurable" },
-  failed: { glyph: GLYPHS.failure, colour: pc8.red, label: "failed" }
+  updated: { glyph: GLYPHS.success, colour: pc9.green, label: "updated" },
+  unchanged: { glyph: GLYPHS.unchanged, colour: pc9.green, label: "already configured" },
+  "not-found": { glyph: GLYPHS.absent, colour: pc9.dim, label: "not found" },
+  unsupported: { glyph: GLYPHS.failure, colour: pc9.yellow, label: "not configurable" },
+  failed: { glyph: GLYPHS.failure, colour: pc9.red, label: "failed" }
 };
 
-// src/ui/report/format-result.ts
+// src/ui/report/result/format-result.ts
 function formatResult(params) {
   const heading = params.mode.kind === "dry-run" ? "Result (dry run)" : "Result";
   return [
@@ -4341,21 +4988,21 @@ function formatResult(params) {
 function formatOutcome2(outcome, params) {
   const { masker: masker2 } = params;
   const style = OUTCOME_STYLE[outcome.kind];
-  const body = match25(outcome).with({ kind: P5.union("updated", "unchanged") }, (planned) => formatPlannedOutcome(planned, params)).with({ kind: "not-found" }, ({ detail }) => [`${INDENT}${pc9.dim(masker2.maskText(detail))}`]).with({ kind: "unsupported" }, ({ harness }) => [`${INDENT}${pc9.dim(harness.reason)}`]).with({ kind: "failed" }, ({ error }) => [`${INDENT}${pc9.red(masker2.maskText(error))}`]).exhaustive();
+  const body = match26(outcome).with({ kind: P6.union("updated", "unchanged") }, (planned) => formatPlannedOutcome(planned, params)).with({ kind: "not-found" }, ({ detail }) => [`${INDENT}${pc10.dim(masker2.maskText(detail))}`]).with({ kind: "unsupported" }, ({ harness }) => [`${INDENT}${pc10.dim(harness.reason)}`]).with({ kind: "failed" }, ({ error }) => [`${INDENT}${pc10.red(masker2.maskText(error))}`]).exhaustive();
   return ["", `  ${style.colour(`${style.glyph} ${outcome.harness.label} \u2014 ${style.label}`)}`, ...body];
 }
-function formatPlannedOutcome(outcome, { envFile, home, masker: masker2 }) {
+function formatPlannedOutcome(outcome, { envFile, home, masker: masker2, model }) {
   return [
-    `${INDENT}${pc9.dim(masker2.maskText(outcome.detail))}`,
-    ...outcome.warnings.map((warning) => `${INDENT}${pc9.yellow(`${GLYPHS.warning} ${masker2.maskText(warning)}`)}`),
+    `${INDENT}${pc10.dim(masker2.maskText(outcome.detail))}`,
+    ...outcome.warnings.map((warning) => `${INDENT}${pc10.yellow(`${GLYPHS.warning} ${masker2.maskText(warning)}`)}`),
     ...outcome.files.filter((file) => file.isChanged).flatMap((file) => formatResultingFile(file.after, masker2)),
     ...envFile === null ? [] : formatEnvVariables({ outcome, envFile, home, masker: masker2 }),
-    ...formatPostSetupNotes(outcome)
+    ...formatPostSetupNotes(outcome, model, masker2)
   ];
 }
 function formatResultingFile(content, masker2) {
   return [
-    `${INDENT}${pc9.dim("resulting file:")}`,
+    `${INDENT}${pc10.dim("resulting file:")}`,
     ...indentLines({ text: masker2.maskText(content), indent: NESTED_INDENT })
   ];
 }
@@ -4366,34 +5013,44 @@ function formatEnvVariables({ outcome, envFile, home, masker: masker2 }) {
   if (variables.length === 0) return [];
   const syntax = ENV_SYNTAXES[envFile.shell];
   return [
-    `${INDENT}${pc9.dim(`variables in ${displayPath(envFile.path, home)}:`)}`,
+    `${INDENT}${pc10.dim(`variables in ${displayPath(envFile.path, home)}:`)}`,
     ...variables.map(([name, value]) => `${NESTED_INDENT}${masker2.maskText(syntax.formatAssignment({ name, value }))}`)
   ];
 }
-function formatPostSetupNotes({ kind, harness }) {
-  if (kind === "unchanged") return [];
-  return (harness.postSetupNotes ?? []).map((note4) => `${INDENT}${pc9.cyan(`${GLYPHS.next} ${note4}`)}`);
+function formatPostSetupNotes({ kind, harness }, model, masker2) {
+  const notes = kind === "unchanged" ? [harness.postSetupNote?.(model)] : [...harness.postSetupNotes ?? [], harness.postSetupNote?.(model)];
+  return notes.filter((note4) => note4 !== void 0).map((note4) => `${INDENT}${pc10.cyan(`${GLYPHS.next} ${masker2.maskText(note4)}`)}`);
 }
-function formatLoadStep({ outcomes, envFile, mode }) {
-  if (mode.kind === "dry-run" || envFile === null || !envFile.isChanged) return [];
+function formatLoadStep({ outcomes, envFile, userEnvironment: userEnvironment2, mode }) {
+  if (mode.kind === "dry-run") return [];
+  const hasEnvFileChange = envFile !== null && envFile.isChanged;
+  if (userEnvironment2 === null && !hasEnvFileChange) return [];
   const readers = outcomes.filter((outcome) => outcome.kind === "updated" && Object.keys(outcome.envVariables).length > 0).map((outcome) => outcome.harness.label);
-  if (readers.length === 0) return [];
+  if (readers.length === 0 || envFile === null) return [];
   const [verb, pronoun] = readers.length === 1 ? ["reads", "it"] : ["read", "they"];
   const { loadCommand } = ENV_SYNTAXES[envFile.shell];
+  if (userEnvironment2 !== null) {
+    return [
+      ...formatHeading("One more step"),
+      `  ${formatList(readers)} ${verb} the key from the environment. Open a new terminal to pick it up.`,
+      `  ${pc10.dim("Or load it now for this session:")}`,
+      `${INDENT}${pc10.bold(loadCommand)}`
+    ];
+  }
   return [
     ...formatHeading("One more step"),
     `  ${formatList(readers)} ${verb} the key from the environment. Load it with:`,
-    `${INDENT}${pc9.bold(loadCommand)}`,
-    `  ${pc9.dim(`Until then ${pronoun} will not see the key.`)}`,
-    ...match25(envFile.shell).with("powershell", () => [
-      `  ${pc9.dim("That lasts for this session only. Add the same line to $PROFILE to keep it.")}`
+    `${INDENT}${pc10.bold(loadCommand)}`,
+    `  ${pc10.dim(`Until then ${pronoun} will not see the key.`)}`,
+    ...match26(envFile.shell).with("powershell", () => [
+      `  ${pc10.dim("That lasts for this session only. Add the same line to $PROFILE to keep it.")}`
     ]).with("posix", () => []).exhaustive()
   ];
 }
 function formatBackups2({ mode, home, masker: masker2 }) {
   if (mode.kind === "dry-run" || mode.backupRoot === null) return [];
   const backupRoot = masker2.maskText(displayPath(mode.backupRoot, home));
-  return [...formatHeading("Backups"), `  Originals copied to ${pc9.bold(backupRoot)}`];
+  return [...formatHeading("Backups"), `  Originals copied to ${pc10.bold(backupRoot)}`];
 }
 function formatSummary2(outcomes) {
   const countsByKind = /* @__PURE__ */ new Map();
@@ -4401,16 +5058,22 @@ function formatSummary2(outcomes) {
   const counts = OUTCOME_KINDS.map((kind) => `${countsByKind.get(kind) ?? 0} ${OUTCOME_STYLE[kind].label}`);
   return [...formatHeading("Summary"), `  ${counts.join(", ")}`];
 }
-function formatRunHints({ runHints, mode }) {
+function formatRunHints({ runHints, mode, model, shell }) {
   if (mode.kind !== "written" || runHints.length === 0) return [];
-  return ["", "You're all set up.", ...runHints.map(formatRunHint)];
+  return ["", "You're all set up.", ...runHints.map((runHint) => formatRunHint({ runHint, model, shell }))];
+}
+function formatRunHint({ runHint: { binary, label }, model, shell }) {
+  const command = binary === "codex" ? `${binary} ${formatModelOverride(model, shell)}` : binary;
+  return `  Run \`${command}\` to use ${label} with the nexos.ai Gateway.`;
 }
-function formatRunHint({ binary, label }) {
-  return `  Run \`${binary}\` to use ${label} with the nexos.ai Gateway.`;
+function formatModelOverride(model, shell) {
+  const quotedValue = JSON.stringify(model);
+  const escapedValue = match26(shell).with("posix", () => escapePosixSingleQuoted(`model=${quotedValue}`)).with("powershell", () => escapePowerShellSingleQuoted(`model=${quotedValue}`)).exhaustive();
+  return `-c '${escapedValue}'`;
 }
 
 // src/commands/setup/answers/describe-key-destination.ts
-import { match as match26 } from "ts-pattern";
+import { match as match27 } from "ts-pattern";
 
 // src/commands/setup/answers/scope.ts
 async function resolveScope({
@@ -4458,7 +5121,7 @@ function describeKeyDestination({ configurable, ctx, envPath }) {
   return `It will be written to ${formatList(configFiles)}, and to ${envFile}.`;
 }
 function displayScopedPath(filePath, ctx) {
-  return match26(ctx.scope).with("user", () => displayPath(filePath, ctx.home)).with("project", () => displayRelativePath(filePath, ctx.cwd)).exhaustive();
+  return match27(ctx.scope).with("user", () => displayPath(filePath, ctx.home)).with("project", () => displayRelativePath(filePath, ctx.cwd)).exhaustive();
 }
 
 // src/commands/setup/answers/harness-selection.ts
@@ -4510,15 +5173,23 @@ var DETECTION_HINTS = {
   "not-found": "not found",
   failed: "could not check"
 };
+var INSTALL_FIRST_HINT = "not installed \u2014 will be installed first";
 function describeHarnessChoice(candidate, scope) {
   const ineligibility = findIneligibility(candidate.harness, scope);
   return {
     value: candidate.harness.id,
     label: candidate.harness.label,
-    hint: ineligibility ?? DETECTION_HINTS[candidate.detection.kind],
+    hint: ineligibility ?? describeDetection(candidate, scope),
     isDisabled: ineligibility !== void 0
   };
 }
+function describeDetection({ harness, detection }, scope) {
+  if (scope === "user" && detection.kind === "not-found" && isInstallable2(harness)) return INSTALL_FIRST_HINT;
+  return DETECTION_HINTS[detection.kind];
+}
+function isInstallable2(harness) {
+  return harness.kind === "configurable" && harness.installPackage !== void 0;
+}
 function isDefaultChoice({ harness, detection }, scope) {
   return findIneligibility(harness, scope) === void 0 && detection.kind === "found";
 }
@@ -4537,8 +5208,15 @@ function planChanges(params) {
   const { envPath, shell } = params;
   const drafts = params.selected.map((candidate) => planHarness(candidate, params));
   const envFileRead = drafts.some(hasEnvVariables) ? readEnvFile({ envPath, home: params.ctx.home }) : NO_ENV_FILE;
-  const outcomes = drafts.map((draft) => settleOutcome({ draft, envFileRead, shell }));
-  return { outcomes, envFile: planEnvFile2({ outcomes, envFileRead, envPath, shell }) };
+  const userEnvironment2 = planSetupUserEnvironment({ drafts, params });
+  const outcomes = drafts.map(
+    (draft) => settleOutcome({ draft, envFileRead, shell, userEnvironment: userEnvironment2.plan })
+  );
+  return {
+    outcomes: addUserEnvironmentWarning2({ outcomes, warning: userEnvironment2.warning }),
+    envFile: planEnvFile2({ outcomes, envFileRead, envPath, shell }),
+    userEnvironment: userEnvironment2.plan
+  };
 }
 function listChangedFiles({ outcomes, envFile }) {
   const changedFiles = outcomes.flatMap(
@@ -4623,14 +5301,37 @@ function collectEnvVariables(contributions) {
 function hasEnvVariables(draft) {
   return draft.kind === "planned" && Object.keys(draft.envVariables).length > 0;
 }
-function settleOutcome({ draft, envFileRead, shell }) {
+function settleOutcome({ draft, envFileRead, shell, userEnvironment: userEnvironment2 }) {
   if (draft.kind !== "planned") return draft;
   if (envFileRead.kind === "failed" && hasEnvVariables(draft)) return failWith(draft, envFileRead.error);
   const envText = envFileRead.kind === "read" ? envFileRead.text : null;
   const hasOwnEnvChange2 = hasEnvVariables(draft) && renderEnvFile({ current: envText, variables: draft.envVariables, shell }) !== envText;
-  const isChanged = hasOwnEnvChange2 || draft.files.some((file) => file.isChanged);
+  const hasOwnUserEnvironmentChange = userEnvironment2 !== null && Object.keys(draft.envVariables).some((name) => userEnvironment2.before[name] !== userEnvironment2.after[name]);
+  const isChanged = hasOwnEnvChange2 || hasOwnUserEnvironmentChange || draft.files.some((file) => file.isChanged);
   return { ...draft, kind: isChanged ? "updated" : "unchanged" };
 }
+function planSetupUserEnvironment({ drafts, params }) {
+  if (params.ctx.platform !== "win32") return { plan: null, warning: null };
+  const values = Object.fromEntries(
+    drafts.flatMap((draft) => draft.kind === "planned" ? Object.entries(draft.envVariables) : [])
+  );
+  if (Object.keys(values).length === 0) return { plan: null, warning: null };
+  try {
+    return { plan: planUserEnvironment({ values, userEnvironment: params.userEnvironment }), warning: null };
+  } catch (error) {
+    if (!(error instanceof UserEnvironmentError)) throw error;
+    return {
+      plan: null,
+      warning: describeUserEnvironmentFailure({ action: "read", envPath: params.envPath, home: params.ctx.home })
+    };
+  }
+}
+function addUserEnvironmentWarning2({ outcomes, warning }) {
+  if (warning === null) return [...outcomes];
+  return outcomes.map(
+    (outcome) => isPlanned(outcome) && Object.keys(outcome.envVariables).length > 0 ? { ...outcome, warnings: [...outcome.warnings, warning] } : outcome
+  );
+}
 function failWith({ harness }, error) {
   return { kind: "failed", harness, error };
 }
@@ -4644,32 +5345,37 @@ function classifyFileOrigin(before) {
   if (before === null) return "absent";
   return before.trim() === "" ? "blank" : "content";
 }
-function addFileOriginals({ record: record8, harnessId, file }) {
-  const harness = readHarnessRecord(record8, harnessId);
+function addFileOriginals({ record: record9, harnessId, file }) {
+  const harness = readHarnessRecord(record9, harnessId);
   const existing = harness.files.find((recorded) => isSamePath2(recorded.path, file.path));
   const others = harness.files.filter((recorded) => recorded !== existing);
-  return withHarnessRecord(record8, harnessId, { ...harness, files: [...others, mergeFile(existing, file)] });
+  return withHarnessRecord(record9, harnessId, { ...harness, files: [...others, mergeFile(existing, file)] });
 }
-function addEnvOriginals({ record: record8, harnessId, variables, isFileAbsent }) {
-  const harness = readHarnessRecord(record8, harnessId);
+function addEnvOriginals({ record: record9, harnessId, variables, isFileAbsent }) {
+  const harness = readHarnessRecord(record9, harnessId);
   const kept = isFileAbsent ? [] : harness.envVariables;
   const added = variables.filter((variable) => !kept.some(({ name }) => name === variable.name));
-  return withHarnessRecord(record8, harnessId, { ...harness, envVariables: [...kept, ...added] });
+  return withHarnessRecord(record9, harnessId, { ...harness, envVariables: [...kept, ...added] });
+}
+function addUserEnvironmentOriginals({ record: record9, variables }) {
+  const kept = record9.userEnvironment;
+  const added = variables.filter((variable) => !kept.some(({ name }) => name === variable.name));
+  return { ...record9, userEnvironment: [...kept, ...added] };
 }
 var EMPTY_HARNESS_RECORD = { files: [], envVariables: [] };
-function readHarnessRecord(record8, harnessId) {
-  return record8.harnesses[harnessId] ?? EMPTY_HARNESS_RECORD;
+function readHarnessRecord(record9, harnessId) {
+  return record9.harnesses[harnessId] ?? EMPTY_HARNESS_RECORD;
 }
-function withHarnessRecord(record8, harnessId, harness) {
-  return { ...record8, harnesses: { ...record8.harnesses, [harnessId]: harness } };
+function withHarnessRecord(record9, harnessId, harness) {
+  return { ...record9, harnesses: { ...record9.harnesses, [harnessId]: harness } };
 }
 function mergeFile(existing, file) {
   if (existing === void 0 || file.origin === "absent") return file;
   const added = file.keys.filter((key) => !existing.keys.some(({ keyPath }) => isSamePath2(keyPath, key.keyPath)));
   return { ...existing, keys: [...existing.keys, ...added] };
 }
-function isSamePath2(path25, other) {
-  return path25.length === other.length && path25.every((segment, index) => segment === other[index]);
+function isSamePath2(path26, other) {
+  return path26.length === other.length && path26.every((segment, index) => segment === other[index]);
 }
 
 // src/commands/setup/changes/record-originals.ts
@@ -4681,7 +5387,7 @@ function recordFileOriginals({ harnessId, file, ctx }) {
     origin: classifyFileOrigin(file.before),
     keys: file.originals
   };
-  updateRestoreRecord(location, ctx, (record8) => addFileOriginals({ record: record8, harnessId, file: recordedFile }));
+  updateRestoreRecord(location, ctx, (record9) => addFileOriginals({ record: record9, harnessId, file: recordedFile }));
 }
 function recordEnvOriginals({ outcomes, envFile, ctx }) {
   const syntax = ENV_SYNTAXES[envFile.shell];
@@ -4690,7 +5396,7 @@ function recordEnvOriginals({ outcomes, envFile, ctx }) {
   updateRestoreRecord(
     resolveRestoreRecordLocation(ctx),
     ctx,
-    (record8) => outcomes.reduce((updated, outcome) => {
+    (record9) => outcomes.reduce((updated, outcome) => {
       if (outcome.kind !== "updated") return updated;
       const variables = Object.keys(outcome.envVariables).map((name) => ({
         name,
@@ -4698,13 +5404,25 @@ function recordEnvOriginals({ outcomes, envFile, ctx }) {
       }));
       if (variables.length === 0) return updated;
       return addEnvOriginals({ record: updated, harnessId: outcome.harness.id, variables, isFileAbsent });
-    }, record8)
+    }, record9)
+  );
+}
+function recordUserEnvironmentOriginals({ userEnvironment: userEnvironment2, ctx }) {
+  const variables = Object.keys(userEnvironment2.after).map((name) => ({
+    name,
+    original: userEnvironment2.before[name] ?? null
+  }));
+  if (variables.length === 0) return;
+  updateRestoreRecord(
+    resolveRestoreRecordLocation(ctx),
+    ctx,
+    (record9) => addUserEnvironmentOriginals({ record: record9, variables })
   );
 }
 function updateRestoreRecord(location, ctx, update) {
   if (location.gitIgnoredDirectory !== null) ignoreBackupsInGit(location.gitIgnoredDirectory);
-  const record8 = readRestoreRecord({ filePath: location.filePath, home: ctx.home }) ?? createEmptyRestoreRecord();
-  writeRestoreRecord({ filePath: location.filePath, record: update(record8), platform: ctx.platform });
+  const record9 = readRestoreRecord({ filePath: location.filePath, home: ctx.home }) ?? createEmptyRestoreRecord();
+  writeRestoreRecord({ filePath: location.filePath, record: update(record9), platform: ctx.platform });
 }
 
 // src/commands/setup/changes/apply-changes.ts
@@ -4713,10 +5431,12 @@ function applyChanges(params) {
   const outcomes = agentWrites.map(({ outcome }) => outcome);
   const envFile = replanEnvFile2(params.plan.envFile, outcomes);
   const envWrite = writeSharedEnvFile({ outcomes, envFile, params });
+  const userEnvironmentWrite = writeUserEnvironment2({ outcomes: envWrite.outcomes, params });
   const writtenFiles = [...agentWrites.flatMap(({ writtenFiles: writtenFiles2 }) => writtenFiles2), ...envWrite.writtenFiles];
   return {
-    outcomes: envWrite.outcomes,
+    outcomes: userEnvironmentWrite.outcomes,
     envFile,
+    userEnvironment: userEnvironmentWrite.written,
     writtenCount: writtenFiles.length,
     backupRoot: writtenFiles.some((file) => file.isBackedUp) ? params.backupRoot.path : null
   };
@@ -4727,9 +5447,9 @@ function writeAgentFiles(outcome, params) {
   for (const file of outcome.files.filter((plan) => plan.isChanged)) {
     try {
       const relativePath = path22.join(outcome.harness.id, path22.basename(file.path));
-      const record8 = () => recordFileOriginals({ harnessId: outcome.harness.id, file, ctx: params.ctx });
+      const record9 = () => recordFileOriginals({ harnessId: outcome.harness.id, file, ctx: params.ctx });
       const write = () => writeFileWithMode({ filePath: file.path, content: file.after, mode: resolveWriteMode(file, params.ctx) });
-      writtenFiles.push(backUpThenWrite({ file, relativePath, record: record8, write, params }));
+      writtenFiles.push(backUpThenWrite({ file, relativePath, record: record9, write, params }));
     } catch (error) {
       const reason = describeFileError({ error, action: "write", home: params.ctx.home });
       return { outcome: { kind: "failed", harness: outcome.harness, error: reason }, writtenFiles };
@@ -4746,9 +5466,9 @@ function writeSharedEnvFile({ outcomes, envFile, params }) {
   try {
     const relativePath = path22.join(ENV_FILE_BACKUP_DIRECTORY, path22.basename(envFile.path));
     const { ctx } = params;
-    const record8 = () => recordEnvOriginals({ outcomes, envFile, ctx });
+    const record9 = () => recordEnvOriginals({ outcomes, envFile, ctx });
     const write = () => writeEnvFile({ filePath: envFile.path, content: envFile.after, platform: ctx.platform });
-    return { outcomes, writtenFiles: [backUpThenWrite({ file: envFile, relativePath, record: record8, write, params })] };
+    return { outcomes, writtenFiles: [backUpThenWrite({ file: envFile, relativePath, record: record9, write, params })] };
   } catch (error) {
     const reason = describeFileError({ error, action: "write", home: params.ctx.home });
     return { outcomes: outcomes.map((outcome) => failIfWritingEnvFile(outcome, reason)), writtenFiles: [] };
@@ -4758,10 +5478,31 @@ function failIfWritingEnvFile(outcome, error) {
   if (outcome.kind !== "updated" || Object.keys(outcome.envVariables).length === 0) return outcome;
   return { kind: "failed", harness: outcome.harness, error };
 }
-function backUpThenWrite({ file, relativePath, record: record8, write, params }) {
+function writeUserEnvironment2({ outcomes, params }) {
+  const { userEnvironment: userEnvironment2, envPath, ctx } = params;
+  const plan = replanUserEnvironment({ plan: params.plan.userEnvironment, names: userEnvironmentNames2(outcomes) });
+  if (plan === null || !plan.isChanged) return { outcomes: [...outcomes], written: null };
+  try {
+    recordUserEnvironmentOriginals({ userEnvironment: plan, ctx });
+    userEnvironment2.write(plan.after);
+    return { outcomes: [...outcomes], written: plan };
+  } catch {
+    const warning = describeUserEnvironmentFailure({ action: "write", envPath, home: ctx.home });
+    return { outcomes: outcomes.map((outcome) => addUserEnvironmentWarningTo2(outcome, warning)), written: null };
+  }
+}
+function addUserEnvironmentWarningTo2(outcome, warning) {
+  if (outcome.kind !== "updated" || Object.keys(outcome.envVariables).length === 0) return outcome;
+  return { ...outcome, warnings: [...outcome.warnings, warning] };
+}
+function userEnvironmentNames2(outcomes) {
+  if (outcomes.length === 0) return null;
+  return new Set(outcomes.flatMap((outcome) => isPlanned(outcome) ? Object.keys(outcome.envVariables) : []));
+}
+function backUpThenWrite({ file, relativePath, record: record9, write, params }) {
   const { ctx, backupRoot } = params;
   const backup = backUpBeforeWriting({ filePath: file.path, before: file.before, backupRoot, relativePath, ctx });
-  record8();
+  record9();
   write();
   return backup;
 }
@@ -4791,11 +5532,26 @@ async function runSetup(params) {
     ui
   });
   const ctx = { ...params.baseContext, scope };
-  const selected = await selectHarnesses({ namedHarnesses, ctx, shouldAssumeYes: options.shouldAssumeYes, ui });
-  assertProjectSupport({ selected, scope, isScopeNamed: options.scope !== void 0 });
+  if (options.shouldInstall && scope !== "user") {
+    throw new UsageError("--install installs globally; it applies to user scope only.");
+  }
+  const detected = await selectHarnesses({ namedHarnesses, ctx, shouldAssumeYes: options.shouldAssumeYes, ui });
+  assertProjectSupport({ selected: detected, scope, isScopeNamed: options.scope !== void 0 });
+  const install = await installMissingHarnesses({
+    notInstalled: detected.flatMap(({ harness, detection }) => detection.kind === "not-found" ? [harness] : []),
+    isPickerDriven: namedHarnesses.length === 0 && !options.shouldAssumeYes,
+    options,
+    ctx,
+    ui,
+    runNpm: params.runNpm
+  });
+  const selected = install.installedCount > 0 ? detectHarnesses(
+    detected.map(({ harness }) => harness),
+    ctx
+  ) : detected;
   if (selected.length === 0) {
     ui.cancel("No agents selected \u2014 nothing to do.");
-    return EXIT_CODE.ok;
+    return install.hasFailure ? EXIT_CODE.failed : EXIT_CODE.ok;
   }
   warnAboutUnsupported(selected, ui);
   if (!selected.some(({ harness }) => harness.kind === "configurable")) {
@@ -4803,7 +5559,7 @@ async function runSetup(params) {
     return EXIT_CODE.ok;
   }
   const found = selected.flatMap(listFoundConfigurable);
-  if (found.length === 0) return endWithNothingFound(selected, ui, masker2);
+  if (found.length === 0) return endWithNothingFound({ selected, ui, masker: masker2, hasInstallFailure: install.hasFailure });
   const shell = resolveShell(ctx.platform);
   const run = { ...params, ui, ctx, shell, envPath: resolveEnvFilePath(ctx.home, shell), gatewayUrls };
   const keyStep = await establishKey({ run, configurable: found, environment });
@@ -4830,21 +5586,46 @@ async function runSetup(params) {
   const key = resolvedKey.key;
   ui.print(formatDetection(selected, masker2));
   const desired = buildDesiredConfig({ gatewayUrls, apiKey: key, model });
-  const plan = planChanges({ selected, desired, ctx, envPath: run.envPath, shell, isDryRun: options.isDryRun });
+  const plan = planChanges({
+    selected,
+    desired,
+    ctx,
+    envPath: run.envPath,
+    shell,
+    isDryRun: options.isDryRun,
+    userEnvironment: run.userEnvironment
+  });
   const changes = listChangedFiles(plan);
   const isPlanFailed = exitCodeFor(plan.outcomes) !== EXIT_CODE.ok;
-  ui.print(formatPreview({ changes, model, scope, hasFailedAgent: isPlanFailed, home: ctx.home, masker: masker2 }));
+  ui.print(
+    formatPreview({
+      changes,
+      userEnvironment: plan.userEnvironment,
+      model,
+      scope,
+      hasFailedAgent: isPlanFailed,
+      home: ctx.home,
+      masker: masker2
+    })
+  );
   if (options.isDryRun) {
     if (resolvedKey.shouldSave) ui.dim("Dry run \u2014 the key was not saved.");
     if (modelSave.length > 0) ui.dim("Dry run \u2014 the default model was not saved.");
-    return reportResult({ run, plan, mode: { kind: "dry-run" }, outro: "Dry run \u2014 nothing was written." });
+    return reportResult({
+      run,
+      plan,
+      model,
+      mode: { kind: "dry-run" },
+      outro: "Dry run \u2014 nothing was written.",
+      hasInstallFailure: install.hasFailure
+    });
   }
-  if (changes.length === 0) {
+  if (changes.length === 0 && plan.userEnvironment?.isChanged !== true) {
     await commitSave(resolvedKey, check4, keyStep.deps);
     saveModelFor(plan.outcomes);
     const mode2 = { kind: "written", backupRoot: null };
     const outro4 = isPlanFailed ? FINISHED_WITH_ERRORS2 : "Nothing to do \u2014 already configured.";
-    return reportResult({ run, plan, mode: mode2, outro: outro4 });
+    return reportResult({ run, plan, model, mode: mode2, outro: outro4, hasInstallFailure: install.hasFailure });
   }
   if (!options.shouldAssumeYes && !await ui.confirm("Write these changes? Originals are backed up first.", true)) {
     return abort(ui);
@@ -4854,7 +5635,14 @@ async function runSetup(params) {
   saveModelFor(applied.outcomes);
   const outro3 = exitCodeFor(applied.outcomes) === EXIT_CODE.ok ? "Done." : FINISHED_WITH_ERRORS2;
   const mode = { kind: "written", backupRoot: applied.backupRoot };
-  return reportResult({ run, plan: { outcomes: applied.outcomes, envFile: applied.envFile }, mode, outro: outro3 });
+  return reportResult({
+    run,
+    plan: { outcomes: applied.outcomes, envFile: applied.envFile, userEnvironment: applied.userEnvironment },
+    model,
+    mode,
+    outro: outro3,
+    hasInstallFailure: install.hasFailure
+  });
 }
 function warnAboutUnsupported(selected, ui) {
   for (const { harness } of selected) {
@@ -4865,10 +5653,10 @@ function listFoundConfigurable({ harness, detection }) {
   if (harness.kind !== "configurable" || detection.kind !== "found") return [];
   return [harness];
 }
-function endWithNothingFound(selected, ui, masker2) {
+function endWithNothingFound({ selected, ui, masker: masker2, hasInstallFailure }) {
   ui.print(formatDetection(selected, masker2));
   const hasFailedCheck = selected.some(({ harness, detection }) => isConfigurableUnchecked(harness, detection));
-  if (hasFailedCheck) {
+  if (hasFailedCheck || hasInstallFailure) {
     ui.outro(FINISHED_WITH_ERRORS2);
     return EXIT_CODE.failed;
   }
@@ -4915,24 +5703,32 @@ function writeChanges(run, plan) {
   });
   const spinner = ui.spinner();
   spinner.start("Backing up originals and writing configs\u2026");
-  const applied = applyChanges({ plan, ctx, backupRoot });
-  spinner.stop(`Wrote ${formatCount(applied.writtenCount, "file")}.`);
+  const applied = applyChanges({ plan, ctx, backupRoot, userEnvironment: run.userEnvironment, envPath: run.envPath });
+  spinner.stop(describeWritten(applied));
   return applied;
 }
-function reportResult({ run, plan, mode, outro: outro3 }) {
+function describeWritten(applied) {
+  if (applied.writtenCount > 0) return `Wrote ${formatCount(applied.writtenCount, "file")}.`;
+  if (applied.userEnvironment !== null) return "Updated the Windows user environment.";
+  return "Wrote 0 files.";
+}
+function reportResult({ run, plan, model, mode, outro: outro3, hasInstallFailure }) {
   const { ui, ctx, masker: masker2 } = run;
   ui.print(
     formatResult({
       outcomes: plan.outcomes,
       envFile: plan.envFile,
+      userEnvironment: plan.userEnvironment,
       mode,
+      model,
+      shell: run.shell,
       home: ctx.home,
       masker: masker2,
       runHints: listRunHints(plan.outcomes, ctx)
     })
   );
   ui.outro(outro3);
-  return exitCodeFor(plan.outcomes);
+  return hasInstallFailure ? EXIT_CODE.failed : exitCodeFor(plan.outcomes);
 }
 function listRunHints(outcomes, ctx) {
   return outcomes.filter(isPlanned).flatMap(({ harness }) => ctx.hasBinary(harness.binary) ? [{ binary: harness.binary, label: harness.label }] : []);
@@ -4942,9 +5738,473 @@ function abort(ui) {
   return EXIT_CODE.cancelled;
 }
 
-// src/harnesses/run-launch.ts
-import fs10 from "fs";
+// src/ui/report/result/format-status.ts
+import pc11 from "picocolors";
+var TITLE = "nexos-connect status";
+var HEADER_LABEL_WIDTH = 11;
+var SCOPE_WIDTH = 9;
+var STATE_WIDTH = 15;
+var SCOPE_STATE_COLOUR = {
+  configured: pc11.green,
+  drifted: pc11.yellow,
+  "not configured": pc11.dim,
+  "not installed": pc11.dim,
+  unreadable: pc11.red
+};
+function formatStatus({ report: report2, masker: masker2 }) {
+  return [
+    pc11.bold(TITLE),
+    "",
+    ...formatHeader(report2, masker2),
+    ...report2.harnesses.flatMap((harness) => formatHarness(harness, masker2)),
+    ...formatErrors(report2.errors, masker2)
+  ];
+}
+function formatHeader(report2, masker2) {
+  return [
+    formatHeaderRow("Key", describeKey(report2.key)),
+    formatHeaderRow("Env file", describeEnvFile2(report2.envFile)),
+    formatHeaderRow("Backups", `${report2.backups.user}  \xB7  ${report2.backups.project}`),
+    formatHeaderRow("Defaults", describeDefaults(report2.defaults, masker2))
+  ];
+}
+function formatHeaderRow(label, value) {
+  return `${label.padEnd(HEADER_LABEL_WIDTH)}${value}`;
+}
+function describeKey({ isSaved, masked, isValid }) {
+  if (masked === null) return "none";
+  const source = isSaved ? "keychain" : "found";
+  if (isValid === null) return `${source} \xB7 ${masked}`;
+  return `${source} \xB7 ${masked} \xB7 ${isValid ? "valid" : "rejected"}`;
+}
+function describeEnvFile2({ path: path26, isPresent }) {
+  return `${path26} \xB7 ${isPresent ? "present" : "absent"}`;
+}
+function describeDefaults(defaults, masker2) {
+  const entries = Object.entries(defaults);
+  if (entries.length === 0) return "none";
+  return entries.map(([id, model]) => `${id} ${masker2.maskText(model)}`).join(" \xB7 ");
+}
+function formatHarness(harness, masker2) {
+  return ["", `  ${pc11.bold(harness.label)}  ${pc11.dim(`(${harness.id})`)}`, ...formatHarnessBody(harness, masker2)];
+}
+function formatHarnessBody(harness, masker2) {
+  if (!harness.isSupported) return [`  ${pc11.yellow(`unsupported \u2014 ${harness.reason ?? ""}`)}`];
+  if (harness.scopes === null) return [];
+  return [
+    ...formatScopeRow("user", harness.scopes.user, masker2),
+    ...formatScopeRow("project", harness.scopes.project, masker2),
+    `  ${"undo".padEnd(SCOPE_WIDTH)}${harness.isUndoable ? "yes" : "no"}`,
+    ...harness.warnings.map((warning) => `  ${pc11.yellow(`${GLYPHS.warning} ${warning}`)}`)
+  ];
+}
+function formatScopeRow(scopeName, status, masker2) {
+  const colour = SCOPE_STATE_COLOUR[status.state];
+  const path26 = status.path === null ? "" : status.path;
+  const model = status.model === null ? "" : `${INDENT}model ${masker2.maskText(status.model)}`;
+  const detail = status.detail === null ? [] : [`${NESTED_INDENT}${pc11.dim(masker2.maskText(status.detail))}`];
+  return [`  ${scopeName.padEnd(SCOPE_WIDTH)}${colour(status.state.padEnd(STATE_WIDTH))}${path26}${model}`, ...detail];
+}
+function formatErrors(errors, masker2) {
+  return errors.flatMap((error) => ["", `  ${pc11.red(`${GLYPHS.failure} ${masker2.maskText(error)}`)}`]);
+}
+
+// src/ui/report/result/format-status-json.ts
+var JSON_INDENT4 = 2;
+function formatStatusJson(report2, masker2) {
+  return JSON.stringify(toStatusJson(report2, masker2), null, JSON_INDENT4);
+}
+function toStatusJson(report2, masker2) {
+  return {
+    version: report2.version,
+    key: { saved: report2.key.isSaved, masked: report2.key.masked, valid: report2.key.isValid },
+    envFile: { path: report2.envFile.path, present: report2.envFile.isPresent },
+    backups: report2.backups,
+    defaults: maskValues(report2.defaults, masker2),
+    harnesses: report2.harnesses.map((harness) => toHarnessJson(harness, masker2))
+  };
+}
+function toHarnessJson(harness, masker2) {
+  return {
+    id: harness.id,
+    label: harness.label,
+    supported: harness.isSupported,
+    detected: harness.isDetected,
+    undoable: harness.isUndoable,
+    status: harness.status,
+    reason: harness.reason,
+    scopes: harness.scopes === null ? null : { user: toScopeJson(harness.scopes.user, masker2), project: toScopeJson(harness.scopes.project, masker2) },
+    warnings: harness.warnings
+  };
+}
+function toScopeJson(scope, masker2) {
+  return {
+    state: scope.state,
+    path: scope.path,
+    model: maskValue(scope.model, masker2),
+    keyMasked: scope.keyMasked,
+    detail: maskValue(scope.detail, masker2),
+    drifted: scope.isDrifted,
+    changedPaths: scope.changedPaths
+  };
+}
+function maskValues(values, masker2) {
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, masker2.maskText(value)]));
+}
+function maskValue(value, masker2) {
+  return value === null ? null : masker2.maskText(value);
+}
+
+// src/commands/status/inspect-harness.ts
+import { match as match28 } from "ts-pattern";
+
+// src/commands/status/display-scope-path.ts
+function displayScopePath(filePath, ctx) {
+  return ctx.scope === "user" ? displayPath(filePath, ctx.home) : displayRelativePath(filePath, ctx.cwd);
+}
+
+// src/commands/status/read-config-key.ts
+function readConfigKey({ harness, ctx, envPath, shell }) {
+  const fromConfig = harness.readKey?.(ctx);
+  if (fromConfig !== void 0) return fromConfig;
+  if (harness.keyEnvVariable === void 0) return void 0;
+  const envRead = readEnvFile({ envPath, home: ctx.home });
+  if (envRead.kind === "failed" || envRead.text === null) return void 0;
+  return readNonBlank(parseEnvFile(envRead.text, shell).get(harness.keyEnvVariable));
+}
+
+// src/commands/status/detect-drift.ts
+function detectDrift(params) {
+  const { harness, ctx, envPath, shell, model } = params;
+  const desired = buildDesiredConfig({
+    gatewayUrls: buildGatewayUrls(resolveGatewayHost(ctx.env)),
+    apiKey: readConfigKey({ harness, ctx, envPath, shell }) ?? "",
+    model
+  });
+  const contributions = harness.plan(desired, ctx);
+  const changedPaths = [
+    ...contributions.flatMap((contribution) => contribution.kind === "file" ? listFileDrift(contribution, ctx) : []),
+    ...listEnvDrift(collectEnvVariables2(contributions), { ctx, envPath, shell })
+  ];
+  return { isDrifted: changedPaths.length > 0, changedPaths };
+}
+function listFileDrift(contribution, ctx) {
+  const current = readFileIfExists(contribution.path);
+  try {
+    return renderConfig(current, contribution.edits(current)) === current ? [] : [displayScopePath(contribution.path, ctx)];
+  } catch (error) {
+    if (!(error instanceof ConfigFormatError)) throw error;
+    return [displayScopePath(contribution.path, ctx)];
+  }
+}
+function listEnvDrift(variables, params) {
+  if (Object.keys(variables).length === 0) return [];
+  const { ctx, envPath, shell } = params;
+  const envRead = readEnvFile({ envPath, home: ctx.home });
+  if (envRead.kind === "failed") return [displayScopePath(envPath, ctx)];
+  const after = renderEnvFile({ current: envRead.text, variables, shell });
+  return after === envRead.text ? [] : [displayScopePath(envPath, ctx)];
+}
+function collectEnvVariables2(contributions) {
+  return Object.fromEntries(
+    contributions.flatMap(
+      (contribution) => contribution.kind === "env" ? Object.entries(contribution.variables) : []
+    )
+  );
+}
+
+// src/commands/status/status-result.ts
+var WORST_FIRST = ["unreadable", "drifted", "configured", "not configured", "not installed"];
+function worstScopeState(states) {
+  return WORST_FIRST.find((state) => states.includes(state)) ?? "not installed";
+}
+function exitCodeForStatus(report2, namedIds) {
+  if (report2.errors.length > 0) return EXIT_CODE.failed;
+  if (report2.key.isValid === false) return EXIT_CODE.failed;
+  if (report2.harnesses.some(isUnhealthy)) return EXIT_CODE.failed;
+  const isNamedAndUnsetUp = (harness) => namedIds.includes(harness.id) && (harness.status === "not configured" || harness.status === "not installed");
+  return report2.harnesses.some(isNamedAndUnsetUp) ? EXIT_CODE.failed : EXIT_CODE.ok;
+}
+function isUnhealthy(harness) {
+  return harness.status === "drifted" || harness.status === "unreadable";
+}
+
+// src/commands/status/inspect-harness.ts
+function inspectHarness(params) {
+  const { harness } = params;
+  if (harness.kind === "unsupported") {
+    return {
+      id: harness.id,
+      label: harness.label,
+      isSupported: false,
+      isDetected: isDetected(harness, params.baseContext),
+      isUndoable: params.undoableIds.has(harness.id),
+      status: "unsupported",
+      reason: harness.reason,
+      scopes: null,
+      warnings: []
+    };
+  }
+  const user = inspectScope({ ...params, harness, ctx: { ...params.baseContext, scope: "user" } });
+  const project = inspectProjectScope({ ...params, harness, ctx: { ...params.baseContext, scope: "project" } });
+  return {
+    id: harness.id,
+    label: harness.label,
+    isSupported: true,
+    isDetected: user.isDetected || project.isDetected,
+    isUndoable: params.undoableIds.has(harness.id),
+    status: worstScopeState([user.scope.state, project.scope.state]),
+    reason: null,
+    scopes: { user: user.scope, project: project.scope },
+    warnings: listWarnings({ harness, masker: params.masker }, user.ctx, project.ctx)
+  };
+}
+function isDetected(harness, ctx) {
+  try {
+    return harness.detect({ ...ctx, scope: "user" }).isFound;
+  } catch {
+    return false;
+  }
+}
+function inspectScope(params) {
+  const { harness, ctx } = params;
+  const detection = detectAt(harness, ctx);
+  const { inspection, error } = inspectionFor(params);
+  const key = readConfigKey({ harness, ctx, envPath: params.envPath, shell: params.shell });
+  const scopeCase = match28({
+    detectionKind: detection.kind,
+    isUnreadable: inspection.isUnreadable,
+    isConfigured: inspection.isConfigured
+  }).with({ detectionKind: "failed" }, () => unreadableScope(detection.detail)).with({ isUnreadable: true }, () => unreadableScope(error)).with({ isConfigured: true }, () => {
+    try {
+      const drift = detectDrift({
+        harness,
+        ctx,
+        envPath: params.envPath,
+        shell: params.shell,
+        model: params.defaults[harness.id] ?? inspection.model ?? DEFAULT_MODEL
+      });
+      return {
+        state: drift.isDrifted ? "drifted" : "configured",
+        changedPaths: drift.changedPaths,
+        detail: null
+      };
+    } catch (error2) {
+      return unreadableScope(describeFileError({ error: error2, action: "read", home: ctx.home }));
+    }
+  }).with({ detectionKind: "not-found" }, () => notInstalledScope(detection.detail)).otherwise(() => ({ state: "not configured", changedPaths: [], detail: null }));
+  return {
+    scope: {
+      ...scopeCase,
+      path: displayScopePath(harness.configPath?.(ctx) ?? params.envPath, ctx),
+      model: inspection.model ?? null,
+      keyMasked: key === void 0 ? null : params.masker.maskText(key),
+      isDrifted: scopeCase.state === "drifted"
+    },
+    isDetected: detection.kind === "found",
+    ctx
+  };
+}
+function inspectProjectScope(params) {
+  if (params.harness.projectSupport.kind === "unsupported") {
+    return {
+      scope: {
+        state: "not installed",
+        path: null,
+        model: null,
+        keyMasked: null,
+        isDrifted: false,
+        changedPaths: [],
+        detail: params.harness.projectSupport.reason
+      },
+      isDetected: false,
+      ctx: params.ctx
+    };
+  }
+  return inspectScope(params);
+}
+function detectAt(harness, ctx) {
+  try {
+    const result = harness.detect(ctx);
+    return { kind: result.isFound ? "found" : "not-found", detail: result.detail };
+  } catch (error) {
+    return { kind: "failed", detail: describeFileError({ error, action: "read", home: ctx.home }) };
+  }
+}
+function inspectionFor(params) {
+  try {
+    return { inspection: params.harness.inspect?.(params.ctx) ?? fallbackInspection(params), error: null };
+  } catch (error) {
+    return {
+      inspection: { isConfigured: false, model: void 0, isUnreadable: true },
+      error: describeFileError({ error, action: "read", home: params.ctx.home })
+    };
+  }
+}
+function fallbackInspection(params) {
+  const key = readConfigKey({
+    harness: params.harness,
+    ctx: params.ctx,
+    envPath: params.envPath,
+    shell: params.shell
+  });
+  return { isConfigured: key !== void 0, model: void 0, isUnreadable: false };
+}
+function unreadableScope(detail) {
+  return { state: "unreadable", changedPaths: [], detail };
+}
+function notInstalledScope(detail) {
+  return { state: "not installed", changedPaths: [], detail };
+}
+function listWarnings({ harness, masker: masker2 }, ...contexts) {
+  const warnings = contexts.flatMap((ctx) => readWarnings(harness, ctx));
+  return [...new Set(warnings.map((warning) => masker2.maskText(warning)))];
+}
+function readWarnings(harness, ctx) {
+  try {
+    return harness.warnings?.(ctx) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+// src/commands/status/read-global-status.ts
 import path23 from "path";
+async function readGlobalStatus(params) {
+  const { ctx, masker: masker2 } = params;
+  const shell = resolveShell(ctx.platform);
+  const envPath = resolveEnvFilePath(ctx.home, shell);
+  const envKey = parseEnvironmentKey(readEnvironmentInputs(ctx.env).key);
+  const existing = findExistingKeys({ ctx, envPath, shell });
+  masker2.registerSecrets(existing.all);
+  const errors = [];
+  const saved = await loadSavedKey(params.keystore, errors);
+  const resolvedKey = envKey ?? saved ?? existing.offered;
+  if (resolvedKey !== void 0) masker2.registerSecrets([resolvedKey]);
+  const defaults = readDefaults(ctx.home, errors);
+  const undoableIds = readUndoableIds(ctx, errors);
+  return {
+    key: {
+      isSaved: saved !== void 0,
+      masked: resolvedKey === void 0 ? null : masker2.maskText(resolvedKey),
+      isValid: null
+    },
+    resolvedKey,
+    envFile: { path: displayPath(envPath, ctx.home), isPresent: isFilePresent(envPath) },
+    backups: {
+      user: `${displayPath(path23.join(ctx.home, USER_BACKUP_DIRECTORY), ctx.home)}${path23.sep}`,
+      project: `${displayRelativePath(path23.join(ctx.cwd, PROJECT_BACKUP_DIRECTORY), ctx.cwd)}${path23.sep}`
+    },
+    defaults,
+    undoableIds,
+    errors
+  };
+}
+async function loadSavedKey(keystore2, errors) {
+  const availability = await keystore2.availability();
+  if (availability.kind !== "available") return void 0;
+  try {
+    return readNonBlank(await keystore2.load());
+  } catch (error) {
+    errors.push(
+      `Could not read the saved key from your system keychain: ${describeError(error)}. Run \`npx ${COMMAND_NAME} ${FORGET_KEY_COMMAND}\` if this keeps happening.`
+    );
+    return void 0;
+  }
+}
+function isFilePresent(filePath) {
+  try {
+    return readFileIfExists(filePath) !== null;
+  } catch {
+    return false;
+  }
+}
+function readDefaults(home, errors) {
+  try {
+    return readDefaultModels(home);
+  } catch (error) {
+    if (!(error instanceof PreferencesError)) throw error;
+    errors.push(error.message);
+    return {};
+  }
+}
+function readUndoableIds(ctx, errors) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const scope of CONFIG_SCOPES) {
+    const record9 = readRecord2({ ...ctx, scope }, errors);
+    for (const id of Object.keys(record9?.harnesses ?? {})) ids.add(id);
+  }
+  return ids;
+}
+function readRecord2(ctx, errors) {
+  try {
+    const { filePath } = resolveRestoreRecordLocation(ctx);
+    return readRestoreRecord({ filePath, home: ctx.home });
+  } catch (error) {
+    if (!(error instanceof RestoreRecordError)) throw error;
+    errors.push(error.message);
+    return null;
+  }
+}
+
+// src/commands/status/run-status.ts
+async function runStatus(params) {
+  const { options, baseContext, masker: masker2, ui } = params;
+  const named = resolveNamedHarnesses(options.harnessIds);
+  const shell = resolveShell(baseContext.platform);
+  const envPath = resolveEnvFilePath(baseContext.home, shell);
+  const global = await readGlobalStatus({ ctx: baseContext, keystore: params.keystore, masker: masker2 });
+  const report2 = {
+    version: 1,
+    key: await resolveKeyStatus({ global, options, baseContext, masker: masker2, fetch: params.fetch }),
+    envFile: global.envFile,
+    backups: global.backups,
+    defaults: global.defaults,
+    harnesses: (named.length > 0 ? named : [...harnesses]).map(
+      (harness) => inspectFor({ harness, params, global, envPath, shell })
+    ),
+    errors: global.errors
+  };
+  if (options.isJson) {
+    ui.print([formatStatusJson(report2, masker2)]);
+    for (const error of global.errors) ui.writeError(masker2.maskText(error));
+  } else {
+    ui.print(formatStatus({ report: report2, masker: masker2 }));
+  }
+  return exitCodeForStatus(report2, options.harnessIds);
+}
+function inspectFor({ harness, params, global, envPath, shell }) {
+  return inspectHarness({
+    harness,
+    baseContext: params.baseContext,
+    envPath,
+    shell,
+    defaults: global.defaults,
+    undoableIds: global.undoableIds,
+    masker: params.masker
+  });
+}
+async function resolveKeyStatus({
+  global,
+  options,
+  baseContext,
+  masker: masker2,
+  fetch: fetch2
+}) {
+  if (!options.shouldVerifyStatus || global.resolvedKey === void 0) return global.key;
+  const gatewayUrls = buildGatewayUrls(resolveGatewayHost(baseContext.env));
+  const { probe } = await listModels({
+    openaiBaseUrl: gatewayUrls.openaiBaseUrl,
+    apiKey: global.resolvedKey,
+    masker: masker2,
+    fetch: fetch2
+  });
+  return { ...global.key, isValid: isKeyAccepted(probe) };
+}
+
+// src/harnesses/launch/run-launch.ts
+import fs10 from "fs";
+import path24 from "path";
 var LAUNCH_DIRECTORY_PREFIX = "nexos-connect-";
 var STALE_DIRECTORY_PATTERN = new RegExp(`^${LAUNCH_DIRECTORY_PREFIX}(\\d+)-`);
 var OWNER_ONLY_MODE2 = 384;
@@ -4957,11 +6217,11 @@ function sweepStaleDirectories(deps) {
     return;
   }
   for (const name of names) {
-    const match27 = STALE_DIRECTORY_PATTERN.exec(name);
-    if (match27 === null) continue;
-    const directory = path23.join(root, name);
+    const match29 = STALE_DIRECTORY_PATTERN.exec(name);
+    if (match29 === null) continue;
+    const directory = path24.join(root, name);
     try {
-      if (deps.isAlive(Number(match27[1]))) continue;
+      if (deps.isAlive(Number(match29[1]))) continue;
       if (deps.uid !== void 0 && fs10.statSync(directory).uid !== deps.uid) continue;
       fs10.rmSync(directory, { recursive: true, force: true });
     } catch {
@@ -4978,15 +6238,11 @@ async function runLaunch(recipe, passthrough, deps) {
   };
   deps.signals.on("exit", cleanup);
   let commandArguments = recipe.arguments;
+  let byPlaceholder = /* @__PURE__ */ new Map();
   if (recipe.files !== void 0 && recipe.files.length > 0) {
     try {
-      directory = fs10.mkdtempSync(path23.join(deps.tmpdir(), `${LAUNCH_DIRECTORY_PREFIX}${deps.pid}-`));
-      const byPlaceholder = /* @__PURE__ */ new Map();
-      for (const file of recipe.files) {
-        const target = path23.join(directory, file.name);
-        fs10.writeFileSync(target, file.content, { mode: OWNER_ONLY_MODE2, flag: "wx" });
-        byPlaceholder.set(file.placeholder, target);
-      }
+      directory = fs10.mkdtempSync(path24.join(deps.tmpdir(), `${LAUNCH_DIRECTORY_PREFIX}${deps.pid}-`));
+      byPlaceholder = writeLaunchFiles({ files: recipe.files, directory });
       commandArguments = commandArguments.map((argument) => byPlaceholder.get(argument) ?? argument);
     } catch (error) {
       cleanup();
@@ -5000,7 +6256,7 @@ async function runLaunch(recipe, passthrough, deps) {
   const env = { ...deps.env };
   for (const [name, value] of Object.entries(recipe.env)) {
     if (value === void 0) delete env[name];
-    else env[name] = value;
+    else env[name] = byPlaceholder.get(value) ?? value;
   }
   if (deps.stdin.isTTY) deps.stdin.setRawMode(false);
   deps.stdin.pause();
@@ -5044,6 +6300,15 @@ async function runLaunch(recipe, passthrough, deps) {
     child.once("exit", (code, signal) => finish2(signal !== null ? { signal } : { code: code ?? 1 }));
   });
 }
+function writeLaunchFiles({ files, directory }) {
+  const byPlaceholder = /* @__PURE__ */ new Map([[LAUNCH_DIRECTORY_PLACEHOLDER, directory]]);
+  for (const file of files) {
+    const target = path24.join(directory, file.name);
+    fs10.writeFileSync(target, file.content, { mode: OWNER_ONLY_MODE2, flag: "wx" });
+    if (file.placeholder !== void 0) byPlaceholder.set(file.placeholder, target);
+  }
+  return byPlaceholder;
+}
 function joinArguments({ recipeArguments, subcommands, passthrough }) {
   const [first, ...rest] = passthrough;
   if (first !== void 0 && subcommands.includes(first)) return [first, ...recipeArguments, ...rest];
@@ -5137,9 +6402,18 @@ function createKeystore(deps) {
   };
 }
 
+// src/product/storage/windows-environment/powershell-user-environment.ts
+import { spawnSync } from "child_process";
+var POWERSHELL_EXECUTABLE = "powershell.exe";
+var POWERSHELL_ARGUMENTS = ["-NoProfile", "-NonInteractive", "-Command"];
+function runPowerShell({ script, input }) {
+  const result = spawnSync(POWERSHELL_EXECUTABLE, [...POWERSHELL_ARGUMENTS, script], { input, encoding: "utf8" });
+  return { code: result.status ?? 1, stdout: result.stdout };
+}
+
 // src/ui/output.ts
 import * as clack2 from "@clack/prompts";
-import pc10 from "picocolors";
+import pc12 from "picocolors";
 function intro2(message, io) {
   clack2.intro(message, { output: io.output });
 }
@@ -5161,8 +6435,13 @@ function printLines(lines, io) {
   io.output.write(`${lines.join("\n")}
 `);
 }
+function writeError(message, io) {
+  const stream = io.errorOutput ?? io.output;
+  stream.write(`${message}
+`);
+}
 function dim(message, io) {
-  clack2.log.message(pc10.dim(message), { output: io.output });
+  clack2.log.message(pc12.dim(message), { output: io.output });
 }
 function note2(message, title, io) {
   clack2.note(message, title, { output: io.output });
@@ -5259,7 +6538,7 @@ async function chooseSavedKey(maskedKey, io) {
 // src/ui/prompts/model/ask-for-model-id.ts
 import * as clack9 from "@clack/prompts";
 
-// src/ui/back-keys.ts
+// src/ui/terminal/back-keys.ts
 import * as clack8 from "@clack/prompts";
 var ESCAPE_KEY = "escape";
 var EDITING_BACK_KEYS = ["left", "backspace", "delete"];
@@ -5433,8 +6712,9 @@ async function selectModel(choices, io) {
   }
 }
 function formatHiddenModelsNote(hiddenCount) {
-  const subject = hiddenCount === 1 ? "it does" : "they do";
-  return `${formatCount(hiddenCount, "model")} hidden \u2014 ${subject} not serve the API your selected agents use.`;
+  const subject = hiddenCount === 1 ? "it is" : "they are";
+  const object6 = hiddenCount === 1 ? "a chat model" : "chat models";
+  return `${formatCount(hiddenCount, "model")} hidden \u2014 ${subject} not ${object6}.`;
 }
 
 // src/ui/prompts/select-harnesses.ts
@@ -5505,9 +6785,9 @@ async function selectScope({ userPaths, projectPaths }, io) {
   );
 }
 
-// src/ui/spinner.ts
+// src/ui/terminal/spinner.ts
 import * as clack18 from "@clack/prompts";
-import pc11 from "picocolors";
+import pc13 from "picocolors";
 function createSpinner(io) {
   const taskController = new AbortController();
   const cancelled = new Promise((_resolve, reject) => {
@@ -5540,7 +6820,7 @@ function createSpinner(io) {
     stop: (message) => {
       if (stopSpinning === null) return;
       end();
-      io.output.write(`${pc11.green(clack18.S_STEP_SUBMIT)}  ${message}
+      io.output.write(`${pc13.green(clack18.S_STEP_SUBMIT)}  ${message}
 `);
     },
     waitFor,
@@ -5555,7 +6835,7 @@ function createSpinner(io) {
   };
 }
 function spin({ io, message, onCancel }) {
-  io.output.write(`${pc11.gray(clack18.S_BAR)}
+  io.output.write(`${pc13.gray(clack18.S_BAR)}
 `);
   const stopAnimating = isTerminalOutput(io.output) ? animate(io.output, message) : () => {
   };
@@ -5575,7 +6855,7 @@ function animate(output, message) {
   const text2 = fitToWidth(message, output.columns);
   let frameIndex = 0;
   const drawFrame = () => {
-    output.write(`${CLEAR_LINE}${pc11.magenta(FRAMES[frameIndex % FRAMES.length] ?? "")}  ${text2}`);
+    output.write(`${CLEAR_LINE}${pc13.magenta(FRAMES[frameIndex % FRAMES.length] ?? "")}  ${text2}`);
     frameIndex += 1;
   };
   output.write(HIDE_CURSOR);
@@ -5627,6 +6907,7 @@ function createTerminalUi(io) {
     cancel: (message) => cancel2(message, io),
     log: createLog(io),
     print: (lines) => printLines(lines, io),
+    writeError: (message) => writeError(message, io),
     dim: (message) => dim(message, io),
     note: (message, title) => note2(message, title, io),
     spinner: () => createSpinner(io),
@@ -5654,11 +6935,12 @@ var keystore = createKeystore({
   importKeyring: () => import("@napi-rs/keyring"),
   platform: process.platform,
   isWsl: () => process.env.WSL_DISTRO_NAME !== void 0 || /microsoft/i.test(os.release()),
-  hasMacKeychain: () => spawnSync("security", ["default-keychain"], { stdio: "ignore", timeout: KEYCHAIN_PROBE_TIMEOUT_MS }).status === 0,
+  hasMacKeychain: () => spawnSync2("security", ["default-keychain"], { stdio: "ignore", timeout: KEYCHAIN_PROBE_TIMEOUT_MS }).status === 0,
   isEnabled: process.env[KEYCHAIN_ENV_VARIABLE] !== KEYCHAIN_DISABLED,
   probeTimeoutMs: KEYCHAIN_PROBE_TIMEOUT_MS,
   interactionTimeoutMs: KEYCHAIN_INTERACTION_TIMEOUT_MS
 });
+var userEnvironment = createUserEnvironment({ platform: process.platform, runPowerShell });
 var runnerDeps = {
   spawn: (command, commandArguments, options) => crossSpawn(command, commandArguments, options),
   tmpdir: os.tmpdir,
@@ -5678,13 +6960,25 @@ function isProcessAlive(pid) {
     return error.code === "EPERM";
   }
 }
+function runNpm(npmArguments) {
+  return new Promise((resolve) => {
+    const child = crossSpawn("npm", [...npmArguments], { stdio: "inherit" });
+    child.once("error", () => resolve({ kind: "could-not-start" }));
+    child.once("exit", (code) => resolve({ kind: "exited", code: code ?? 1 }));
+  });
+}
 async function main() {
-  const ui = createTerminalUi({ input: process.stdin, output: process.stdout, onInterrupt: listenForSigint });
+  const ui = createTerminalUi({
+    input: process.stdin,
+    output: process.stdout,
+    errorOutput: process.stderr,
+    onInterrupt: listenForSigint
+  });
   try {
     return await runCommand(ui);
   } catch (error) {
     const failure = classifyFailure(error, masker);
-    if (failure.kind === "usage") console.error(pc12.red(failure.message));
+    if (failure.kind === "usage") console.error(pc14.red(failure.message));
     if (failure.kind === "cancelled") ui.cancel("Cancelled.");
     if (failure.kind === "unexpected") ui.log.error(failure.message);
     return exitCodeForFailure(failure);
@@ -5700,8 +6994,8 @@ var HELP = renderHelp({
   predefinedModelIds: PREDEFINED_MODELS.map((model) => model.id),
   defaultModel: DEFAULT_MODEL,
   backupDirectories: {
-    user: path24.join("~", USER_BACKUP_DIRECTORY),
-    project: `.${path24.sep}${PROJECT_BACKUP_DIRECTORY}`
+    user: path25.join("~", USER_BACKUP_DIRECTORY),
+    project: `.${path25.sep}${PROJECT_BACKUP_DIRECTORY}`
   }
 });
 function isLaunchingHarness(harness) {
@@ -5715,7 +7009,7 @@ function describeUnknownAgent(binary) {
   if (isAgentName(binary)) return `Unknown agent "${binary}". ${oneOf}`;
   return `Unknown agent. ${oneOf}. To pass a key, use --key or set $${KEY_ENV_VARIABLE}.`;
 }
-var PackageSchema = v15.object({ version: v15.string() });
+var PackageSchema = v16.object({ version: v16.string() });
 async function runCommand(ui) {
   const options = parseCliArguments(process.argv.slice(NODE_AND_SCRIPT_ARGUMENT_COUNT));
   if (options.shouldShowHelp) {
@@ -5723,20 +7017,24 @@ async function runCommand(ui) {
     return EXIT_CODE.ok;
   }
   if (options.shouldShowVersion) {
-    console.log(v15.parse(PackageSchema, createRequire(import.meta.url)("../package.json")).version);
+    console.log(v16.parse(PackageSchema, createRequire(import.meta.url)("../package.json")).version);
     return EXIT_CODE.ok;
   }
   if (options.command.kind === "forget-key") return await forgetKey({ keystore, ui, masker });
   if (options.command.kind === "launch") return await runLaunchCommand({ command: options.command, options, ui });
+  if (options.command.kind === "status") {
+    return await runStatus({ options, baseContext: createContext(), ui, keystore, masker, fetch });
+  }
   const commandParams = {
     options,
     baseContext: createContext(),
     ui,
     now: () => /* @__PURE__ */ new Date(),
-    masker
+    masker,
+    userEnvironment
   };
   if (options.command.kind === "restore") return await runRestore(commandParams);
-  return await runSetup({ ...commandParams, fetch, keystore });
+  return await runSetup({ ...commandParams, fetch, keystore, runNpm });
 }
 function createContext() {
   return createPlatformContext({
@@ -5751,14 +7049,14 @@ async function runLaunchCommand({ command, options, ui }) {
   const { binary, passthrough } = command;
   const harness = findHarnessByBinary(binary);
   if (harness === void 0) {
-    console.error(pc12.red(masker.maskText(describeUnknownAgent(binary))));
+    console.error(pc14.red(masker.maskText(describeUnknownAgent(binary))));
     console.error(`
 ${HELP}`);
     return EXIT_CODE.usage;
   }
   if (!isLaunchingHarness(harness)) {
     const reason = harness.kind === "unsupported" ? `not configurable \u2014 ${harness.reason}` : "cannot be started this way";
-    console.error(pc12.red(`${harness.label}: ${reason}`));
+    console.error(pc14.red(`${harness.label}: ${reason}`));
     return EXIT_CODE.usage;
   }
   const ctx = createContext();
@@ -5771,7 +7069,8 @@ ${HELP}`);
       masker,
       ctx,
       fetch,
-      runLaunch: (recipe, recipePassthrough) => runLaunch(recipe, recipePassthrough, runnerDeps)
+      runLaunch: (recipe, recipePassthrough) => runLaunch(recipe, recipePassthrough, runnerDeps),
+      runNpm
     }
   );
   if ("signal" in result) {
@@ -5785,7 +7084,7 @@ function finish(exitCode) {
   process.exitCode = exitCode;
 }
 void main().then(finish).catch((error) => {
-  console.error(pc12.red(masker.maskText(describeError(error))));
+  console.error(pc14.red(masker.maskText(describeError(error))));
   finish(EXIT_CODE.failed);
 });
 //# sourceMappingURL=index.js.map