@explyt/ai-agent 0.2.1 → 0.3.0-dogfood.2

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.1"          # start the terminal UI
-npx -y "@explyt/ai-agent@0.2.1" 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.1 --help` for the available options.
+Run `npx -y @explyt/ai-agent@0.3.0 --help` for the available options.

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/settings.md

@@ -46,7 +46,10 @@ rest of the file as it is.
 | `sessionTitle.enabled` | boolean | `true` | whether a new chat gets a short title generated by the model after its first turn succeeds |
 | `subagents.maxConcurrency` | positive integer | `20` | Maximum simultaneously running or waiting children |
 | `subagents.permission` | `inherit` \| `yolo` \| `ask-permissions` | `inherit` | Permission mode resolved for child tools |
-| `tui.mascot` | string | `"cat"` | the animated mascot in the terminal's working row: `cat`, `snake`, `pacman`, `tetris`, `fishing`, `robot`, `pong` or `crab` |
+| `tui.mascot` | string | `"cat"` | the animated mascot in the terminal's working row: `cat`, `snake`, `pacman`, `tetris`, `fishing`, `robot`, `pong`, `crab`, or `custom` for the user's own |
+| `tui.customMascotFrames` | array of strings | `[]` | the frames of the custom mascot, one string per frame, played in order |
+| `tui.customMascotText` | string | `"Working…"` | the breathing word in front of the custom mascot |
+| `tui.tips` | boolean | `true` | whether a usage tip is shown under the working row while the agent works |
 
 The rule and Skill list settings take exact, case-sensitive entries. Neither supports globs or
 prefixes: `"pdf-*"` matches nothing. An entry matching nothing is kept, not an error.
@@ -66,11 +69,45 @@ project's `.explyt/settings.json` is ignored, so write it to `~/.explyt/settings
 turns generation off everywhere; the chat then keeps the truncated first prompt as its title. A
 name the user sets with `/name` is never replaced either way.
 
-`tui.mascot` is also read from the **global** layer only; write it to `~/.explyt/settings.json`.
-The value is one of the eight ids above, lowercase and exact. Any other value, or a value that is
-not a string, shows the cat. The terminal command `/mascot` writes this key and switches the
-mascot at once; a hand edit applies from the next session. It has no effect in an IDE, which has no
-working row.
+The four `tui.*` keys are also read from the **global** layer only; write them to
+`~/.explyt/settings.json`. An edit applies from the user's next prompt; the terminal command
+`/mascot` writes `tui.mascot` and switches the mascot at once. None of them has an effect in an IDE,
+which has no working row.
+
+`tui.mascot` is one of the nine ids above, lowercase and exact. Any other value, or a value that is
+not a string, shows the cat.
+
+### Drawing a custom mascot
+
+When the user asks for a mascot of their own, write all three keys: the frames, the word, and
+`tui.mascot: "custom"`. The custom keys stay in the file when the user later picks another
+mascot, and `/mascot custom` brings it back.
+
+```json
+{
+  "tui": {
+    "mascot": "custom",
+    "customMascotText": "Quacking…",
+    "customMascotFrames": ["🦆      ", " 🦆     ", "  🦆    ", "   🦆   "]
+  }
+}
+```
+
+- Each string is one frame, shown for 120 ms, in order, then the list repeats. Draw a loop: the
+  last frame should lead back into the first.
+- Keep every frame the same width, measured in terminal columns; an emoji or a CJK character is
+  two columns. Shorter frames are padded with spaces at their end.
+- A frame or a text wider than **40 columns** is cut to 40.
+- Plain characters only: escape sequences, colour codes, tabs and line breaks are removed. The
+  product paints the frames orange and the word in a breathing orange itself.
+- Without `customMascotText` the word is `Working…`. Use one short word with `…` (U+2026), like
+  the built-in mascots.
+- With no frames, an empty list, or only blank frames, `custom` shows the cat.
+
+### Tips
+
+`tui.tips: false` hides the tip line under the working row. The tips themselves are part of the
+product and cannot be edited.
 
 ## How the two layers combine
 

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,22 +252,20 @@ export function isUsableShim(path, os = platform()) {
 }
 
 /**
- * Put `binDir` in front of PATH, in place.
- *
- * 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.
- *
- * In place, and nothing at all without a `binDir`: assigning a missing value to
- * `process.env` stores the string "undefined". `env.PATH` is read on the env itself,
- * which on Windows finds `Path` too; a copy of it would not.
+ * 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 prependEnginePath(env, binDir) {
-  if (!binDir) return;
-  env.PATH = env.PATH ? `${binDir}${delimiter}${env.PATH}` : 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);
 }
 
 /**
@@ -364,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);
 }
 
 /**
@@ -902,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.
@@ -997,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.
  *
@@ -1020,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) {
@@ -1040,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.
@@ -1061,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,
-  prependEnginePath,
+  setProductPath,
   terminalEngineArgs,
   withAgentDir,
   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();
-prependEnginePath(process.env, engine.binDir);
+// 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,