@explyt/ai-agent 0.2.0 → 0.3.0-dogfood.1

package/README.md

@@ -17,8 +17,8 @@ explyt update                # install the newer latest, then restart open sessi
 For a one-off pinned run:
 
 ```bash
-npx -y "@explyt/ai-agent@0.2.0"          # start the terminal UI
-npx -y "@explyt/ai-agent@0.2.0" login    # store a provider credential, once
+npx -y "@explyt/ai-agent@0.3.0"          # start the terminal UI
+npx -y "@explyt/ai-agent@0.3.0" login    # store a provider credential, once
 ```
 
 The agent runs with exactly the extensions this build ships with and ignores any
@@ -28,4 +28,4 @@ you get.
 IDE (ACP) integration is not part of this package: it is provided by the Explyt
 managed backend, which the Neo plugin downloads and manages.
 
-Run `npx -y @explyt/ai-agent@0.2.0 --help` for the available options.
+Run `npx -y @explyt/ai-agent@0.3.0 --help` for the available options.

package/THIRD-PARTY-NOTICES.md

@@ -20,7 +20,8 @@ License or other written license agreements with the Company.
 > depends on or redistributes. The release pipeline additionally generates a
 > machine-collected list of license metadata for every runtime npm dependency of the
 > artifact, marking which of them are bundled inside it. The public npm package bundles
-> none of them: npm installs them beside it. The managed backend archive redistributes its
+> none of them as packages: npm installs them beside it; it does carry compiled copies of
+> `model-probe` and `typebox` (section 5) and of `pi-web-access` (section 3) under `dist/vendor/`. The managed backend archive redistributes its
 > whole installed tree. The generated list is not a substitute for reviewing the licenses
 > and NOTICE files of all transitive dependencies before a commercial release.
 
@@ -88,6 +89,12 @@ License or other written license agreements with the Company.
   the unmodified `pi-mcp-adapter` entrypoint (`index.ts`) together with the package's
   small runtime helper files, so that Node can load it outside the engine's TypeScript
   loader.
+- The public npm package contains `dist/vendor/pi-web-access.js`, an unobfuscated
+  compilation of the unmodified `pi-web-access` entrypoint (`dist/index.js`) carrying the
+  package's name, version and licence in a banner, so that its imports of the engine and
+  `typebox` resolve to the product's files under `dist/vendor/`; and small generated files
+  under `dist/vendor/pi-web-access-deps/` that import the package's own installed copy of
+  `@modelcontextprotocol/sdk`. The package's own files are not altered.
 - In the managed backend archive only, `pi-mcp-adapter` is redistributed with one
   textual modification made at build time: in its `index.ts`, the slash-command alias
   registered as `pi-mcp` (a second name for the package's `mcp` status command) is
@@ -97,6 +104,8 @@ License or other written license agreements with the Company.
   here as required by the MIT License; the original copyright and license notice above
   apply to the modified package unchanged. The public npm package does not carry the
   adapter and therefore carries no modification of it.
+- The public npm package contains `dist/vendor/pi-coding-agent.js`, a generated file that
+  re-exports the engine's own bundled entry point by name; it contains no engine code.
 - The formerly bundled `pi-subagents` package was removed by spec 008; references to it in
   older release history are historical and do not describe the current artifact.
 - Seven units of `@earendil-works/pi-coding-agent` 0.84.4 are **copied** (from the TypeScript in
@@ -133,7 +142,7 @@ License or other written license agreements with the Company.
 - local Explyt extension with current `@earendil-works` imports
 - shell API-key execution removed; credential files use locked atomic writes and private permissions
 
-### 5. model-probe, @opencode-ai/models, yaml, minimatch and semver
+### 5. model-probe, @opencode-ai/models, yaml, minimatch, semver and typebox
 
 - `model-probe` 0.6.0, MIT, https://www.npmjs.com/package/model-probe
   - Copyright (c) 2025 ratatulieoi
@@ -146,9 +155,18 @@ License or other written license agreements with the Company.
   - Copyright Isaac Z. Schlueter <i@izs.me> and minimatch contributors
 - `semver` 7.8.5, ISC, https://www.npmjs.com/package/semver
   - Copyright (c) Isaac Z. Schlueter and Contributors
-
-The MIT text below applies to the derivative, `model-probe` and `@opencode-ai/models`
-with the copyright notices above. The ISC text immediately below applies to `yaml` and
+- `typebox` (the version pinned in the development manifest, which the build compiles; the
+  build-time metadata below and each compiled file's banner name it), MIT, https://www.npmjs.com/package/typebox
+  - Copyright (c) 2017-2026 Haydn Paterson
+
+`model-probe` and `typebox` are also redistributed compiled, unobfuscated and unmodified:
+the public npm package contains `dist/vendor/model-probe/` (the installed `model-probe`
+compiled from its TypeScript, with its `rules.json`) and `dist/vendor/typebox/` (the pinned
+`typebox` in one ESM build), each file carrying the package's name, version and
+licence in a banner that names the exact version compiled.
+
+The MIT text below applies to the derivative, `model-probe`, `@opencode-ai/models` and
+`typebox` with the copyright notices above. The ISC text immediately below applies to `yaml` and
 `semver`, each with its own copyright holder listed above (the ISC terms are identical);
 `minimatch` is covered by the separate Blue Oak Model License text further down, and its
 copyright holder is the one listed for it above rather than the one named in the ISC text:
@@ -511,17 +529,28 @@ Consult each package for its complete license text.
 - @modelcontextprotocol/client@2.0.0: license metadata = MIT (installed by npm beside this package)
 - @modelcontextprotocol/core@2.0.0: license metadata = MIT (installed by npm beside this package)
 - @modelcontextprotocol/ext-apps@1.7.5: license metadata = MIT (installed by npm beside this package)
+- @mozilla/readability@0.6.0: license metadata = Apache-2.0 (installed by npm beside this package)
 - @napi-rs/keyring@1.3.0: license metadata = MIT (installed by npm beside this package)
 - ajv@8.20.0: license metadata = MIT (installed by npm beside this package)
 - ajv-formats@3.0.1: license metadata = MIT (installed by npm beside this package)
 - cross-spawn@7.0.6: license metadata = MIT (installed by npm beside this package)
+- defuddle@0.19.3: license metadata = MIT (installed by npm beside this package)
+- linkedom@0.16.11: license metadata = ISC (installed by npm beside this package)
 - minimatch@10.2.6: license metadata = BlueOak-1.0.0 (installed by npm beside this package)
 - model-probe@0.6.0: license metadata = MIT (installed by npm beside this package)
 - open@10.2.0: license metadata = MIT (installed by npm beside this package)
+- p-limit@6.2.0: license metadata = MIT (installed by npm beside this package)
 - pi-mcp-adapter@2.31.0: license metadata = MIT (installed by npm beside this package)
 - pi-web-access@0.31.0: license metadata = MIT (installed by npm beside this package)
+- promise.try@2.0.2: license metadata = MIT (installed by npm beside this package)
 - recheck@4.5.0: license metadata = MIT (installed by npm beside this package)
 - semver@7.8.5: license metadata = ISC (installed by npm beside this package)
 - smol-toml@1.9.0: license metadata = BSD-3-Clause (installed by npm beside this package)
 - strip-json-comments@5.0.3: license metadata = MIT (installed by npm beside this package)
+- turndown@7.2.4: license metadata = MIT (installed by npm beside this package)
+- undici@8.11.2: license metadata = MIT (installed by npm beside this package)
+- unpdf@1.8.1: license metadata = MIT (installed by npm beside this package)
 - yaml@2.9.0: license metadata = ISC (installed by npm beside this package)
+- typebox@1.3.24: license metadata = MIT (compiled into dist/vendor/typebox)
+- model-probe@0.6.0: license metadata = MIT (compiled into dist/vendor/model-probe)
+- pi-web-access@0.31.0: license metadata = MIT (compiled into dist/vendor/pi-web-access.js)

package/agent-docs/README.md

@@ -9,6 +9,7 @@ it. Read the whole file before editing anything it describes.
 | File | Covers |
 |---|---|
 | `settings.md` | `settings.json`, its two layers, and every setting that exists |
+| `updates.md` | the managed installation, automatic updates, `updateChannel` and `autoUpdate` |
 | `rules.md` | persistent instructions: where rule files live, their frontmatter, how to disable one |
 | `skills.md` | Skills: where they are found, the `SKILL.md` frontmatter, how to disable one |
 | `mcp.md` | MCP servers: the two `mcp.json` files, the entry shape, disabling a server or a tool |
@@ -39,9 +40,11 @@ not under `.explyt/`. `web-search.md` says where that directory is and what goes
 
 ## Updates of the agent itself
 
-The terminal UI shows one line when a newer version is published; nothing updates on its own.
-The user updates with `explyt update` (a global npm install) and silences the check with
-`PI_OFFLINE=1`. Neither is a `.explyt/` setting.
+The agent updates itself: the terminal UI checks its channel at most once a day and installs a newer
+version in the background, used from the next start. `explyt update` updates at once, and
+`PI_OFFLINE=1` turns the check off. The update channel and the automatic update switch
+(`updateChannel`, `autoUpdate`) are not `.explyt/` settings: they live in the engine's own
+`settings.json` and are changed with `explyt config`. `updates.md` has the details.
 
 ## Do not create or edit `.pi/` files
 

package/agent-docs/updates.md

@@ -0,0 +1,56 @@
+# Installing and updating the agent
+
+The agent lives in one **managed installation** per user, shared by the terminal (`explyt`) and the
+IDE plugin. The Explyt installer creates and updates it; the user never installs it with `npm`.
+
+## Where it is
+
+```
+<root> = $XDG_DATA_HOME/explyt-ai-agent   (default: ~/.local/share/explyt-ai-agent,
+                                            on Windows %USERPROFILE%\.local\share\explyt-ai-agent)
+<root>/agent/                 credentials, sessions, the engine's settings.json
+<root>/node/<version>/        the Node the installed release runs with
+<root>/install/current.json   which installed release is current
+<root>/install/launch.js      the fixed entry the terminal command and the IDE start
+~/.local/bin/explyt           the terminal command (explyt.cmd on Windows)
+```
+
+Do not edit anything under `<root>/install/` or `<root>/node/` by hand; the installer owns it.
+A shell and an IDE that see different `XDG_DATA_HOME` values use two different roots; the installer
+and `explyt --version` warn when a second one exists.
+
+## Installing
+
+- Linux, macOS: `curl -fsSL https://raw.githubusercontent.com/explyt/explyt-ai-agent-distribution/main/install.sh | sh`
+- Windows (PowerShell): `irm https://raw.githubusercontent.com/explyt/explyt-ai-agent-distribution/main/install.ps1 | iex`
+- From an existing installation: `explyt install`.
+
+`npm i -g @explyt/ai-agent` is not an install path. A global npm copy found on `PATH` is reported as a
+conflict, and the installer offers to remove it.
+
+## Updates
+
+Updates are automatic: the terminal UI checks its channel at most once a day and installs a newer
+version in the background. The new version is used from the next start; the terminal UI then says so,
+and `explyt --continue` resumes the session on it. A running session keeps its version until it exits.
+`explyt update` updates at once. `PI_OFFLINE=1` turns every check off.
+
+## The two update settings
+
+They live in the engine's settings file, `<root>/agent/settings.json`, **not** in `.explyt/`. Change them
+with `explyt config`, which keeps every other key of that file:
+
+| Key | Values | Default | Meaning |
+|---|---|---|---|
+| `updateChannel` | `"stable"`, `"dogfood"` | `"stable"` | which versions the installer takes; `dogfood` gets prereleases first |
+| `autoUpdate` | `true`, `false` | `true` | `false` stops the background check; `explyt update` still works |
+
+```
+explyt config set updateChannel dogfood
+explyt config set autoUpdate false
+explyt config get updateChannel
+```
+
+Any other value is refused by `explyt config` and read as the default, with a warning. Moving from
+`dogfood` back to `stable` keeps the current (newer) version until stable catches up;
+`explyt update --channel stable --allow-downgrade` installs the older stable version at once.

package/dist/cli/engine.js

@@ -19,10 +19,10 @@ import {
   symlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, delimiter, dirname, isAbsolute, join, posix, resolve, sep, win32 } from "node:path";
 import { homedir, platform, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 
 export const ENGINE_PACKAGE = "@earendil-works/pi-coding-agent";
 
@@ -252,19 +252,20 @@ export function isUsableShim(path, os = platform()) {
 }
 
 /**
- * PATH with `binDir` in front.
- *
- * This is how the bundled engine is handed to the ACP adapter: the adapter spawns
- * the bare command `pi`, so putting our own shim first makes it pick the version
- * that ships with this package instead of whatever the user may have installed
- * globally. The alternative — the adapter's `PI_ACP_PI_COMMAND` override — cannot
- * be used here, because one of our IDE clients can only pass `command` and `args`
- * to a backend and never environment variables.
+ * Leave `env` with exactly one PATH key: `dirs` (in order, empty ones skipped) in front
+ * of the inherited value (RQ-6). In place, and never a missing value: the inherited
+ * search path is read under any spelling (`PATH`, `Path`, ...), every spelling is then
+ * removed and one `PATH` is written. On Windows `process.env` is case-insensitive, so
+ * this rewrites `Path`; on POSIX a caller that hands us both spellings stops leaving it
+ * unspecified which one a child sees. Assigning a missing value to `process.env` would
+ * store the string "undefined" (#219), so the value written is always a string.
  */
-export function withEnginePath(env, binDir) {
-  if (!binDir) return { ...env };
-  const current = env.PATH ?? env.Path ?? "";
-  return { ...env, PATH: current ? `${binDir}${delimiter}${current}` : binDir };
+export function setProductPath(env, dirs) {
+  const spellings = Object.keys(env).filter((key) => key.toUpperCase() === "PATH");
+  const inherited = env.PATH ?? (spellings.length > 0 ? env[spellings[0]] : undefined);
+  for (const key of spellings) delete env[key];
+  const parts = [...dirs.filter(Boolean), ...(inherited ? [inherited] : [])];
+  env.PATH = parts.join(delimiter);
 }
 
 /**
@@ -361,10 +362,36 @@ function explicitAgentDir(value, home) {
  * package would be walked as one. Next to it keeps it under the one parent this project
  * owns, and moves with an explicit `PI_CODING_AGENT_DIR` (the agent directory's parent
  * is what a developer relocating the state relocates).
+ *
+ * The name is KEYED by the engine root of the running install (spec 019, RQ-47): the
+ * terminal and the IDE share one state root, and with one unkeyed directory two installs
+ * with different engines rebuilt it on every alternate start -- and removed it while the
+ * other one's engine still read its docs and version through it. The key is a hash of
+ * the engine root's real path; on Windows the path is normalised and lower-cased first,
+ * because the same directory has many spellings there.
+ *
+ * @param {object} env the environment the agent directory is read from
+ * @param {string} [home] home directory, injectable for tests
+ * @param {string} engineDir the engine root of the running install
  */
-export function engineShimDir(env = process.env, home = homedir()) {
+export function engineShimDir(env = process.env, home = homedir(), engineDir) {
   const agentDir = withAgentDir(env, home)[AGENT_DIR_ENV];
-  return join(dirname(agentDir), "engine");
+  return join(dirname(agentDir), `engine-${engineShimKey(engineDir)}`);
+}
+
+/** The per-install part of the shim directory name: a short hash of the engine root. */
+export function engineShimKey(engineDir, os = platform()) {
+  if (typeof engineDir !== "string" || engineDir === "") throw new Error("engineShimDir needs the engine root of the running install");
+  let real = engineDir;
+  try {
+    real = realpathSync(engineDir);
+  } catch {
+    // A root that cannot be resolved still gets a stable key from its spelling.
+  }
+  // The target platform's own path rules, not the host's: a win32 key computed on
+  // Linux (tests, cross-packed trees) must equal the one Windows computes.
+  const key = os === "win32" ? win32.resolve(real).toLowerCase() : posix.resolve(real);
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
 }
 
 /**
@@ -899,7 +926,7 @@ export function withIsolation(rest, packageRoot) {
  * debug artifacts, where the adapter ships next to the wrapper; the public terminal
  * package answers it with a migration error.
  */
-export const COMMANDS = new Set(["acp", "login", "logout", "tui", "update"]);
+export const COMMANDS = new Set(["acp", "config", "install", "login", "logout", "tui", "update"]);
 
 /**
  * Engine flags that confine a terminal run to a single package: ours.
@@ -994,6 +1021,54 @@ export function terminalEngineArgs(entrypoint, packageRoot, extra = [], { login
  */
 export const ADAPTER_LOGIN_FLAG = "--terminal-login";
 
+/**
+ * The launch file of the installed release `packageRoot` belongs to, or null outside one.
+ * An installed release is `<root>/install/releases/<cli>+<adapter>/`, and its launch file
+ * is `<root>/install/launch.js` (spec 019, RQ-42, RQ-43): derived from the path, so no
+ * variable has to carry it.
+ */
+export function launchFileFor(packageRoot) {
+  let dir = packageRoot;
+  for (;;) {
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    if (basename(parent) === "releases" && basename(dirname(parent)) === "install") {
+      return join(dirname(parent), "launch.js");
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * The positionals a `--terminal-login` launch forwards to `login`, without the repeated
+ * launch path (spec 019, RQ-28).
+ *
+ * A client that follows the protocol appends the terminal-auth method's `args` -- the
+ * launch file and `--terminal-login` -- to its own launch command, so what runs is
+ * `node <entry> acp <entry> --terminal-login`. `parseArgs` keeps the second `<entry>` as
+ * a positional, and the engine would take it as the user's first prompt. A positional is
+ * dropped when it names the same file as this process's `argv[1]` or as the launch file
+ * of the installed release this CLI runs from (`launchFileFor`); every other argument is
+ * kept.
+ *
+ * @param {string[]} rest the positionals `parseArgs` returned
+ * @param {{ argv1?: string, launchFile?: string | null, cwd?: string }} self
+ */
+export function withoutLaunchPath(rest, { argv1, launchFile, cwd = process.cwd() } = {}) {
+  const same = (a, b) => {
+    if (!a || !b) return false;
+    const left = resolve(cwd, a);
+    const right = resolve(cwd, b);
+    if (left === right) return true;
+    try {
+      return realpathSync(left) === realpathSync(right);
+    } catch {
+      return false;
+    }
+  };
+  return rest.filter((arg) => arg.startsWith("-") || !(same(arg, argv1) || same(arg, launchFile)));
+}
+
 /**
  * Flags belonging to other programs that consume the NEXT argument as their value.
  *
@@ -1017,6 +1092,7 @@ export function parseArgs(argv) {
   let help = false;
   let version = false;
   let seenPositional = false;
+  let terminalLogin = false;
   const rest = [];
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -1037,7 +1113,7 @@ export function parseArgs(argv) {
     // to the `acp` invocation from its own config -- see ADAPTER_LOGIN_FLAG. It is also
     // consumed rather than forwarded: the entrypoint re-adds it for the adapter, so
     // passing it through as well would hand the adapter the same flag twice.
-    if (arg === ADAPTER_LOGIN_FLAG) { command = "login"; continue; }
+    if (arg === ADAPTER_LOGIN_FLAG) { command = "login"; terminalLogin = true; continue; }
 
     // A foreign flag plus its value: forward both, and never read the value as a
     // subcommand.
@@ -1058,29 +1134,32 @@ export function parseArgs(argv) {
     rest.push(arg);
   }
 
-  return { command, help, version, rest };
+  return { command, help, version, rest, terminalLogin };
 }
 
 export function helpText() {
   return [
     "Explyt AI Agent",
     "",
-    "Install globally: npm i -g @explyt/ai-agent, then run explyt",
+    "Install with the Explyt installer, then run explyt:",
+    "  explyt install [--channel stable|dogfood]      install or update the managed installation",
     "Or run a pinned version without installing:",
     "  npx -y @explyt/ai-agent@<version>             start the terminal UI",
     "  npx -y @explyt/ai-agent@<version> tui         start the terminal UI",
     "  npx -y @explyt/ai-agent@<version> login       store a provider credential",
     "  npx -y @explyt/ai-agent@<version> logout      remove stored credentials",
     "",
-    "Global commands: explyt tui | login | logout | update",
-    "  explyt update      check npm latest and update a global installation",
+    "Commands: explyt tui | login | logout | install | update | config",
+    "  explyt update      update the managed installation now (same as install)",
+    "  explyt config set updateChannel stable|dogfood | autoUpdate true|false",
     "  -h, --help         show this message",
     "  -v, --version      print the version",
     "",
     "Credentials and sessions are separate from other agents: logging in to a pi you run",
     "by hand does not log in here, so run login once for this agent.",
     "The terminal UI notes a newer version at startup; PI_OFFLINE=1 turns the check off.",
-    "IDE (ACP) integration ships in the Explyt managed backend, not this package.",
+    "IDE (ACP) integration is set up by the Explyt installer, which places the adapter",
+    "next to this package; it is not part of this package.",
     "",
   ].join("\n");
 }

package/dist/cli/index.js

@@ -8,12 +8,11 @@
 //   npx @explyt/ai-agent login    a human, once: store a provider credential
 //   npx @explyt/ai-agent logout   a human: remove the stored credentials
 //
-// ACP is NOT part of the public package. The `acp` subcommand still parses so an old
-// IDE configuration fails with a migration message instead of "Unknown command", but
-// the public artifact ships no adapter: IDE integration lives in the Explyt managed
-// backend, which Neo downloads, verifies and launches locally. The SAME wrapper file
-// also ships inside that backend artifact, where the adapter IS present next to it --
-// there `acp` works exactly as before.
+// ACP is NOT part of this package: the adapter is the separate package
+// `@explyt/acp-adapter` (spec 019). `acp` loads it when the installer placed it next to
+// this CLI in an installed release, or from the backend and debug trees, which carry it
+// inside this package root; otherwise `acp` refuses and names the installer. The CLI
+// never depends on the adapter (RQ-1).
 //
 // There is deliberately no `install`. The agent registers nothing and writes to no
 // user configuration: every run isolates the engine to the extensions WE ship, so
@@ -30,11 +29,14 @@
 // only. Any stray write corrupts the stream and the client drops the connection, so
 // all diagnostics in this file go to stderr.
 
-import { signalEnv, updateArgsError, updateCommand, UPDATE_ENV } from "./update.js";
+import { installationRoot, secondRootWarning } from "./install-roots.js";
+import { signalEnv, updateArgsError, UPDATE_ENV } from "./update.js";
+import { runInstaller } from "./install-run.js";
+import { configCommand } from "./install-config.js";
 import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, openSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, realpathSync } from "node:fs";
 import { readFile, rm } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   AGENT_DIR_ENV,
@@ -52,15 +54,22 @@ import {
   helpText,
   interactiveStdin,
   parseArgs,
+  setProductPath,
   terminalEngineArgs,
   withAgentDir,
-  withEnginePath,
   withIsolation,
+  withoutLaunchPath,
+  launchFileFor,
 } from "./engine.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = findPackageRoot(here);
 const args = parseArgs(process.argv.slice(2));
+// A terminal-auth launch repeats the launch path as a positional (spec 019, RQ-28);
+// without this it would reach the engine as the user's first prompt.
+if (args.terminalLogin) {
+  args.rest = withoutLaunchPath(args.rest, { argv1: process.argv[1], launchFile: packageRoot ? launchFileFor(packageRoot) : null });
+}
 
 function fail(message, code = 1) {
   process.stderr.write(`explyt: ${message}\n`);
@@ -95,7 +104,7 @@ async function findEngine() {
   // The engine presents itself under our name from a manifest copy in a directory we
   // own, handed to it through PI_PACKAGE_DIR; see `ensureEngineShim` for why that and not
   // the installed manifest. A failed shim is reported and the engine runs unbranded.
-  const shim = ensureEngineShim(engineDir, engineShimDir(process.env));
+  const shim = ensureEngineShim(engineDir, engineShimDir(process.env, undefined, engineDir));
   if (shim.status === "failed") {
     process.stderr.write(`explyt: engine keeps its own name: ${shim.detail}\n`);
   }
@@ -142,20 +151,28 @@ if (args.version) {
   const version = await selfVersion();
   if (!version) fail("cannot read the package version");
   process.stdout.write(`${version}\n`);
+  // RQ-46: a second installation root is named on stderr; stdout stays the version.
+  const secondRoot = secondRootWarning({ root: installationRoot() });
+  if (secondRoot) process.stderr.write(`explyt: warning: ${secondRoot}\n`);
   process.exit(0);
 }
 
-if (args.command === "update") {
-  const refused = updateArgsError(args.rest);
-  if (refused) fail(refused, 2);
-  const version = await selfVersion();
-  if (!version) fail("cannot read the package version");
-  process.exit(await updateCommand({ root: packageRoot, current: version }));
+// `install` and `update` run the installer of the managed installation (spec 019, RQ-18,
+// RQ-33, RQ-36): `update` never runs `npm install -g`, also from a global npm install.
+if (args.command === "install" || args.command === "update") {
+  // The engine's `update --extensions` is explained, not treated as an installer argument.
+  const engineUpdate = updateArgsError(args.rest);
+  if (engineUpdate && engineUpdate !== "update takes no arguments") fail(engineUpdate, 2);
+  process.exit(await runInstaller(args.rest));
+}
+
+if (args.command === "config") {
+  process.exit(await configCommand(args.rest, { agentDir: withAgentDir(process.env)[AGENT_DIR_ENV] }));
 }
 
 // A bare invocation is the terminal UI. It used to mean "ACP when stdin is a pipe";
-// that heuristic is gone with the public ACP surface -- an IDE that wants ACP runs
-// the managed backend, which passes `acp` explicitly.
+// that heuristic is gone -- an IDE that wants ACP passes `acp` explicitly, through the
+// installation's launch file or a backend/debug tree (spec 019, RQ-5).
 const wantsAcp = args.command === "acp";
 const wantsLogin = args.command === "login";
 const wantsLogout = args.command === "logout";
@@ -239,24 +256,76 @@ if (wantsTui || wantsLogin) {
   process.exit(child.status ?? 1);
 }
 
-// ACP MODE. Only reachable with an explicit `acp`, and only functional in the
-// managed-backend (or debug) artifact, where the adapter ships next to this file:
-//   backend artifact: dist/cli/index.js  ->  dist/acp/index.js
-//   dev source:       cli/index.mjs      ->  vendor/pi-acp/dist/index.js
+// ACP MODE (spec 019, RQ-5). The CLI prepares the engine environment and then loads
+// the adapter, which starts the server on import. The adapter is accepted from exactly
+// these places, in this order:
+//   1. the candidate paths inside this package root -- the backend and debug trees:
+//        backend artifact: dist/cli/index.js  ->  dist/acp/index.js
+//        dev source:       cli/index.mjs      ->  vendor/pi-acp/dist/index.js
+//   2. an installed release npm produced from `@explyt/acp-adapter`:
+//        hoisted  <modules>/@explyt/acp-adapter next to <modules>/@explyt/ai-agent
+//        nested   the package whose node_modules holds this CLI
+// Never NODE_PATH, the working directory, PATH, a workspace link or a global prefix:
+// plain Node resolution would honour NODE_PATH and would follow this checkout's
+// workspace link to the unobfuscated submodule.
+const ADAPTER_PACKAGE = "@explyt/acp-adapter";
+
+/** The adapter's `main` entry in `dir`, or null when `dir` is not the adapter package. */
+function adapterMain(dir) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    if (manifest.name !== ADAPTER_PACKAGE || typeof manifest.main !== "string" || manifest.main === "") return null;
+    const main = join(dir, manifest.main);
+    return existsSync(main) ? main : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The adapter of an installed release, found from this package's own real location. A
+ * directory that is a symlink (a workspace link) is not an installed release.
+ */
+function installedReleaseAdapter(root) {
+  let real;
+  try {
+    real = realpathSync(root);
+  } catch {
+    return null;
+  }
+  const scope = dirname(real);
+  const modules = dirname(scope);
+  if (basename(scope) !== "@explyt" || basename(modules) !== "node_modules") return null;
+  const accept = (dir) => {
+    try {
+      // The package directory itself must be real: npm installs packages, a link is a workspace.
+      if (realpathSync(dir) !== dir) return null;
+    } catch {
+      return null;
+    }
+    return adapterMain(dir);
+  };
+  // hoisted: a sibling in the same node_modules
+  const hoisted = accept(join(modules, "@explyt", "acp-adapter"));
+  if (hoisted) return hoisted;
+  // nested: the package whose node_modules holds this CLI
+  const owner = dirname(modules);
+  if (owner.split(sep).includes("node_modules")) return accept(owner);
+  return null;
+}
+
 const adapterCandidates = [
   join(here, "..", "acp", "index.js"),
   join(packageRoot, "dist", "acp", "index.js"),
   join(packageRoot, "vendor", "pi-acp", "dist", "index.js"),
 ];
-const adapter = adapterCandidates.find((candidate) => existsSync(candidate));
+const adapter = adapterCandidates.find((candidate) => existsSync(candidate)) ?? installedReleaseAdapter(packageRoot);
 if (!adapter) {
-  // The public terminal package: fail with a migration message rather than
-  // "unknown command", because this is exactly what an old IDE entry runs.
+  // What an old IDE entry, or a terminal-only install, runs (RQ-27).
   fail(
-    "ACP is not included in the public terminal package.\n" +
-    "  IDE integration is provided by the Explyt managed backend, which the Neo plugin\n" +
-    "  downloads and manages. Update the IDE configuration to use it, or pin the last\n" +
-    "  ACP-capable version of this package.",
+    "no ACP adapter is installed next to this package.\n" +
+    "  IDE integration is set up by the Explyt installer, which installs the adapter\n" +
+    "  together with this CLI; the Neo plugin runs it for you. See `explyt --help`.",
   );
 }
 
@@ -265,7 +334,19 @@ if (!adapter) {
 // one place the `.bin` shim is still needed, and the adapter handles the Windows
 // `.cmd` case itself.
 const engine = await requireEngine();
-process.env.PATH = withEnginePath(process.env, engine.binDir).PATH;
+// The adapter's own `PI_ACP_PI_COMMAND` names the engine command explicitly (the Neo
+// plugin sets it for the managed backend, whose win32 tree is packed on Linux and has
+// no `pi.cmd`, #219). A missing shim is excused only when that variable names a file
+// that exists: subagents and bash tools pass the variable on to child processes, so a
+// value inherited from an unrelated session must not mask a broken install (RQ-6, RQ-50).
+const explicitEngineCommand = process.env.PI_ACP_PI_COMMAND;
+if (!engine.binDir && !(explicitEngineCommand && existsSync(explicitEngineCommand))) {
+  fail(`the agent engine's pi bin is missing (looked for node_modules/.bin/pi next to ${engine.engineDir}); reinstall with the Explyt installer`);
+}
+// Exactly one PATH key (RQ-6): the engine's `.bin` first, then this Node's directory, so
+// the engine's `#!/usr/bin/env node` finds the same Node even when the caller's PATH has
+// none, then the inherited value. Never a missing value (#219).
+setProductPath(process.env, [engine.binDir, dirname(process.execPath)]);
 
 // Point the engine at THIS agent's configuration directory rather than the
 // `~/.pi/agent` of a pi the user may also run by hand. Set here, in our own process,