@explyt/ai-agent 0.1.0-rc.1 → 0.1.4

package/dist/cli/engine.js

@@ -1,167 +1,138 @@
 // Pure helpers for the user-facing CLI. Kept free of side effects so they can be
 // unit-tested without spawning anything.
 
-import { accessSync, constants, existsSync } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
-import { platform } from "node:os";
+import { writeAtomically } from "./atomic-write.js";
+import {
+  accessSync,
+  constants,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { homedir, platform } from "node:os";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
 
 export const ENGINE_PACKAGE = "@earendil-works/pi-coding-agent";
 
-export const SELF_PACKAGE = "@explyt/ai-agent";
-
 /**
- * Did npm fetch this copy from the registry?
+ * The name the engine presents itself under: its TUI header, terminal title, `/help`,
+ * dialog texts, process title and debug-log name.
  *
- * Single predicate shared by registration and removal: when the two disagreed, an
- * install could write a path while the matching uninstall looked for an `npm:`
- * spec and silently missed it.
+ * ONE WORD, deliberately. The engine derives the name of its configuration-directory
+ * variable from this string (`${name.toUpperCase()}_CODING_AGENT_DIR`,
+ * `dist/config.js`), and a space would put a space into an environment variable
+ * name. The full product name goes into the header our own extension draws.
  */
-export function isRegistryInstall(resolvedFrom) {
-  return typeof resolvedFrom === "string" && /^https?:\/\//.test(resolvedFrom);
-}
+export const ENGINE_BRAND = "explyt";
 
 /**
- * Directory holding the copy of ourselves that gets registered with the agent.
- *
- * Honours `XDG_DATA_HOME`, falling back to `~/.local/share` as the spec prescribes.
- * A sibling of the `local-release` directory that `scripts/setup.mjs` manages, so
- * the published wrapper and a locally built release never overwrite each other.
+ * Engine variable naming the directory it keeps its configuration in, as the
+ * UNBRANDED engine and the third-party extensions we bundle spell it.
  *
- * The same layout is used on every platform, deliberately. The agent we plug into
- * is itself home-relative (`~/.pi/agent`) with no platform branching, and the
- * closest comparable ACP tool (opencode) applies the XDG layout everywhere too.
- * Native placement such as `%LOCALAPPDATA%` would also split this directory from
- * `local-release`, leaving two places to look on Windows instead of one.
+ * The engine resolves it as `$PI_CODING_AGENT_DIR ?? ~/.pi/agent`
+ * (`@earendil-works/pi-coding-agent/dist/config.js`, `getAgentDir`), and the whole
+ * configuration tree hangs off that one root: `auth.json`, `models.json`,
+ * `settings.json`, `sessions/`, `bin/`, `prompts/`, `tools/`.
  *
- * A relative `XDG_DATA_HOME` is ignored: the spec requires an absolute path, and
- * honouring a relative one would silently resolve it against the current working
- * directory, scattering installs wherever the command happened to be run.
+ * This spelling stays even though the engine is rebranded: `pi-subagents` reads the
+ * literal `PI_CODING_AGENT_DIR` (`src/shared/utils.ts`), `pi-mcp-adapter` falls back to
+ * it, and so does the ACP adapter fork (`vendor/pi-acp/src/acp/agent-dir.ts`). All of
+ * them live in the same engine process and must agree on one directory.
  */
-export function installDir({ home, xdgDataHome } = {}) {
-  const configured = typeof xdgDataHome === "string" ? xdgDataHome.trim() : "";
-  const base = configured && isAbsolute(configured) ? configured : join(home, ".local", "share");
-  return join(base, "explyt-ai-agent", "installed");
-}
+export const AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
 
 /**
- * Should `install` copy this package into its own directory before registering?
+ * The same variable as the BRANDED engine spells it.
  *
- * Yes when npm put us inside a `node_modules` tree, no for a source checkout.
+ * The engine builds this name from `piConfig.name` at load time, so it follows
+ * ENGINE_BRAND mechanically. Set alongside AGENT_DIR_ENV with the same value: with only
+ * the old name the engine silently falls back to `~/.pi/agent`; with only the new one
+ * the bundled extensions do. A test pins that the engine really derives THIS name.
  *
- * The distinction preserves two different needs. An npm-installed copy may live in
- * `~/.npm/_npx/<hash>/`, which `npm cache clean` deletes, so registering that path
- * would leave a dangling entry -- it has to be copied somewhere we control. A
- * checkout, by contrast, is registered in place ON PURPOSE: edits to the sources
- * are then picked up live, which is the whole point of developing against it.
+ * The engine derives `${NAME}_CODING_AGENT_SESSION_DIR` the same way. It is not
+ * mirrored here because this project never sets it -- sessions live under the agent
+ * directory above -- but a developer exporting `PI_CODING_AGENT_SESSION_DIR` by hand
+ * should know the branded engine no longer reads that spelling.
  */
-export function shouldCopyBeforeRegistering(packageRoot) {
-  return lockPathFor(packageRoot) !== null;
-}
+export const BRANDED_AGENT_DIR_ENV = `${ENGINE_BRAND.toUpperCase()}_CODING_AGENT_DIR`;
 
 /**
- * Paths inside the package that must NOT be copied into the registered directory.
+ * Silences the engine's "New version X is available. Run `<name> update`" banner.
  *
- * The engine is excluded deliberately. The registered copy is loaded BY the engine,
- * so it never needs its own: our extensions import it only as `import type`, which
- * disappears at compile time. Copying it would waste ~177 MB per install.
+ * The banner reports the engine's own version and links to its changelog,
+ * not the wrapper package version. Our separate terminal notice handles that. The engine's
+ * version is pinned by the wrapper's release, so the check is meaningless here anyway.
  */
-export function isExcludedFromInstall(relativePath) {
-  const normalised = relativePath.split(sep).join("/");
-  return normalised === "node_modules/@earendil-works"
-    || normalised.startsWith("node_modules/@earendil-works/");
-}
+export const SKIP_VERSION_CHECK_ENV = "PI_SKIP_VERSION_CHECK";
 
 /**
- * What to hand the engine's `install` as the package source.
+ * Backend defaults for `recheck`, the ReDoS checker `pi-mcp-adapter` runs on a regex MCP
+ * tool search (`proxy-modes.ts`, `checkSync`). Only filled in when the user set nothing.
  *
- * Always a filesystem path, never an `npm:<name>@<version>` spec, even though the
- * engine accepts both (docs/packages.md, "Package Sources"). The spec looks tempting
- * because the engine then keeps its own copy -- but it reaches that copy by running
- * `npm install` in its own store, which re-resolves our dependency graph and drags
- * in a SECOND ~177 MB engine. Registering a path installs nothing at all (verified:
- * the agent's `npm` store directory is not even created), so a path plus a directory
- * we control is strictly cheaper.
+ * Left on its default (`auto`), `checkSync` starts an external `recheck agent` process, or
+ * `java -jar` when a JVM is on PATH (~120-185 MB RSS), for one ReDoS verdict. The pure
+ * Scala.js path gives the same verdict in-process: measured with recheck@4.5.0,
+ * `^(a+)+$` stays `vulnerable`, no child process appears, ~100 ms per call.
  *
- * @param packageRoot absolute path to this package's root.
- * @param installedRoot directory the package was copied into, when it was copied.
+ * The published package can no longer keep recheck's binaries out: without bundling, npm
+ * installs `recheck-<os>` and `recheck-jar` (~51 MB) as the adapter's own optional
+ * dependencies, and neither `--omit=optional` under `-g` nor `overrides` in a non-root
+ * package stops it. What we still control is that nothing launches them. recheck reads
+ * both variables on every call, and the adapter's sidecar runs inside the engine process,
+ * so the engine's environment is where they have to be.
  */
-export function registrationSource({ packageRoot, installedRoot }) {
-  return installedRoot
-    ? { source: installedRoot, kind: "copied" }
-    : { source: packageRoot, kind: "in-place" };
-}
+export const RECHECK_ENV_DEFAULTS = Object.freeze({ RECHECK_SYNC_BACKEND: "pure", RECHECK_BACKEND: "pure" });
 
 /**
- * Every source `remove` should be tried with, most likely first.
- *
- * Returning a LIST rather than one source is deliberate. The engine matches
- * registrations by key -- `npm:<name>` for specs, the resolved path for paths --
- * so a registration made through one channel is invisible to the other. Verified:
- * registering a path and then removing `npm:@explyt/ai-agent` reports "No matching
- * package found" AND STILL EXITS 0, so a single-source uninstall silently leaves
- * the entry behind while claiming success.
+ * Engine variable overriding where it looks for ITS OWN package directory.
  *
- * All three channels are attempted because a machine can legitimately carry a
- * registration from any of them: the current copied directory, a checkout
- * registered in place, or an `npm:` spec written by an older build of this wrapper.
+ * `getPackageDir()` in the engine's `dist/config.js` returns this when set, and
+ * everything the engine reads about itself hangs off that one directory: its
+ * `package.json` (name, version, `piConfig`), `docs/`, `examples/`, `README.md`,
+ * `CHANGELOG.md`, and under `dist/` its themes, export template and assets. Upstream
+ * added it for Nix/Guix store paths; it is also the one supported way to hand the engine
+ * a manifest that is not the installed one -- see `ensureEngineShim`.
  *
- * The spec is intentionally unversioned. The engine matches npm packages by name
- * (verified: an unversioned remove clears a versioned entry), which lets a newer
- * build uninstall a registration written by an older one.
+ * The name is literal, not derived from `piConfig.name`: it has to be readable before
+ * the manifest is.
  */
-export function removalSources({ packageRoot, installedRoot }) {
-  const sources = [];
-  if (installedRoot) sources.push(installedRoot);
-  if (packageRoot !== installedRoot) sources.push(packageRoot);
-  sources.push(`npm:${SELF_PACKAGE}`);
-  return sources;
-}
+export const PACKAGE_DIR_ENV = "PI_PACKAGE_DIR";
 
 /**
- * Path of the lockfile describing how THIS package was installed, or null when it
- * cannot exist.
+ * Everything the engine resolves relative to `getPackageDir()`, and therefore
+ * everything the shim directory must contain.
  *
- * The lockfile belongs to the project that installed us, not to us: our own
- * manifest never records `resolved`. A path without a `node_modules` segment means
- * a source checkout, which npm did not install at all.
+ * Taken from `dist/config.js`: `getPackageJsonPath`, `getReadmePath`, `getDocsPath`,
+ * `getExamplesPath`, `getChangelogPath`, plus `getThemesDir`, `getExportTemplateDir`
+ * and `getInteractiveAssetsDir`, which all resolve under `dist/` in the node layout
+ * (the bare `theme`, `export-html`, `assets` spellings in that file are the Bun-binary
+ * layout, which we never run). `package.json` is the shim's own file, so it is not a
+ * link. A test greps that file for `join(getPackageDir(), "<x>")` and fails when an
+ * entry appears here that is not covered -- an upstream addition would otherwise be a
+ * silent ENOENT at some later feature.
  */
-export function lockPathFor(packageRoot) {
-  const at = packageRoot.lastIndexOf(`node_modules${sep}`);
-  if (at === -1) return null;
-  return join(packageRoot.slice(0, at), "node_modules", ".package-lock.json");
-}
+export const ENGINE_SHIM_LINKS = Object.freeze(["dist", "docs", "examples", "README.md", "CHANGELOG.md"]);
 
 /**
- * `resolved` recorded for THIS package, or null when absent.
+ * Flag that pins the agent to exactly one package of resources: ours.
  *
- * The key is derived from the real location instead of matching any key that ends
- * with our package name: a nested duplicate
- * (`node_modules/other/node_modules/@explyt/ai-agent`) would otherwise win when it
- * happens to come first in the object, and report a different origin than ours.
+ * The name is historical -- it was introduced for developing against a checkout --
+ * and it is INTERNAL, travelling only from this wrapper to the ACP adapter we ship
+ * in the same tarball. The adapter expands it into the engine's isolation flags plus
+ * `--extension <path>` for every engine process it spawns; `devPackageArgs()` in
+ * vendor/pi-acp/src/cli.ts is the authoritative list.
  */
-export function resolvedFromLock(lock, packageRoot) {
-  const at = packageRoot.lastIndexOf(`node_modules${sep}`);
-  if (at === -1) return null;
-  const key = packageRoot.slice(at).split(sep).join("/");
-  return lock?.packages?.[key]?.resolved ?? null;
-}
-
-/**
- * Entries in settings' `packages` that refer to THIS agent.
- *
- * Used to tell a real uninstall from the engine's silent no-op. Path entries are
- * stored relative to the settings file, so they are resolved before comparison.
- */
-export function selfRegistrations(packages, { packageRoot, installedRoot, settingsDir }) {
-  const ourPaths = [packageRoot, installedRoot].filter(Boolean).map((p) => resolve(p));
-  return (Array.isArray(packages) ? packages : []).filter((entry) => {
-    const source = typeof entry === "string" ? entry : entry?.source;
-    if (typeof source !== "string") return false;
-    if (source.startsWith(`npm:${SELF_PACKAGE}`)) return true;
-    if (source.startsWith("npm:") || source.startsWith("git:") || source.startsWith("http")) return false;
-    return ourPaths.includes(resolve(settingsDir, source));
-  });
-}
+export const ISOLATION_FLAG = "--dev-package";
 
 /** npm writes `pi` on POSIX and `pi.cmd` on Windows. */
 export function engineShimName(os = platform()) {
@@ -293,8 +264,569 @@ export function withEnginePath(env, binDir) {
   return { ...env, PATH: current ? `${binDir}${delimiter}${current}` : binDir };
 }
 
-/** Subcommands this CLI understands. */
-export const COMMANDS = new Set(["install", "uninstall", "acp"]);
+/**
+ * The one parent directory everything this project writes lives under.
+ *
+ * The layout is XDG-like on EVERY platform -- no `%LOCALAPPDATA%`, no
+ * `~/Library/Application Support` -- so that every directory this project owns is a
+ * sibling of the others: one place to inspect, one to delete. The engine we embed is
+ * home-relative and free of platform branches itself, so a platform-specific layout
+ * here would make us the odd one out rather than the native one.
+ *
+ * A RELATIVE `XDG_DATA_HOME` is ignored, as the XDG specification requires: honouring
+ * it would resolve the path against the current working directory and scatter our
+ * data wherever the program happened to be started from.
+ *
+ * This function exists so that rule lives in exactly ONE place. It did not, and the
+ * two halves disagreed: the agent's own state followed `XDG_DATA_HOME` while the
+ * local-release installer in `scripts/setup.mjs` ignored it, so relocating user data
+ * split this project's tree across two parents. A copy of the rule is what allowed
+ * that, which is why callers must derive their directory from here rather than
+ * rebuilding the base themselves.
+ */
+export function appDataDir(env = process.env, home = homedir()) {
+  const dataHome = env.XDG_DATA_HOME;
+  const base = typeof dataHome === "string" && isAbsolute(dataHome)
+    ? dataHome
+    : join(home, ".local", "share");
+  return join(base, "explyt-ai-agent");
+}
+
+/**
+ * Directory this agent keeps ITS engine configuration in.
+ *
+ * The agent is a product of its own, so its credentials, model catalogue, settings
+ * and sessions are its own too: they live here rather than in the `~/.pi/agent`
+ * directory belonging to a pi the user may also run by hand. Sharing that directory
+ * made the agent read and rewrite another program's credential file, and left the
+ * model choice a property of the machine rather than of the pinned version.
+ */
+export function agentConfigDir(env = process.env, home = homedir()) {
+  return join(appDataDir(env, home), "agent");
+}
+
+/**
+ * Env with the engine pointed at this agent's own configuration directory.
+ *
+ * Set once in our own process before the adapter is imported: the adapter passes
+ * `env: process.env` to every engine it spawns, so the child inherits it. That is the
+ * only channel available -- one of our IDE clients can pass a backend nothing but
+ * `command` and `args`, and the ACP host it embeds forwards a fixed whitelist of
+ * variables (HOME, PATH, SHELL, TERM, USER), so nothing set outside would reach us.
+ *
+ * An explicit value is never overwritten, for the same reason `withIsolation` never
+ * overwrites an explicit `--dev-package`: a developer pointing the agent at a
+ * scratch directory must not have it silently replaced by the product default.
+ *
+ * An explicit value IS normalised, the way the engine normalises it (`getAgentDir` ->
+ * `expandTildePath` -> `normalizePath` in `dist/utils/paths.js`): `~` and `~/x` expand
+ * against the home directory, a `file://` URL becomes a path, and the result is made
+ * absolute. The wrapper reads this directory itself -- `ensureAgentSettings` writes
+ * into it and `engineShimDir` builds next to it -- so it has to read the SAME directory
+ * the engine will: with `PI_CODING_AGENT_DIR=~/x` taken literally, the settings landed
+ * in a directory named `~` while the engine read `$HOME/x`. A whitespace-only value is
+ * treated as absent, like the empty string the engine already ignores.
+ *
+ * Not reproduced: the engine's `normalizeWindowsShellPath` (Git Bash `/c/x` -> `C:\x`),
+ * a win32-only branch this project has no way to exercise; a user who spells the
+ * directory in MSYS form on Windows gets a split until that is confirmed on a machine.
+ */
+export function withAgentDir(env, home = homedir()) {
+  // The unbranded name wins when both are set and disagree: it is the one every
+  // reader in the process understands, and two different directories in one process
+  // is the split this function exists to prevent.
+  const explicit = explicitAgentDir(env[AGENT_DIR_ENV], home) ?? explicitAgentDir(env[BRANDED_AGENT_DIR_ENV], home);
+  const dir = explicit ?? agentConfigDir(env, home);
+  return { ...env, [AGENT_DIR_ENV]: dir, [BRANDED_AGENT_DIR_ENV]: dir };
+}
+
+/** The engine's reading of an explicit agent-directory value; null when it counts as unset. */
+function explicitAgentDir(value, home) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  let path = value;
+  if (path === "~") path = home;
+  else if (path.startsWith("~/") || (platform() === "win32" && path.startsWith("~\\"))) path = join(home, path.slice(2));
+  else if (/^file:\/\//.test(path)) path = fileURLToPath(path);
+  return resolve(path);
+}
+
+/**
+ * Directory the engine shim lives in: a SIBLING of the agent directory, never inside it.
+ *
+ * Inside would make it a resource root -- the engine scans its agent directory for
+ * `extensions/`, `skills/`, `prompts/`, and a `dist/` link pointing at the whole engine
+ * 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).
+ */
+export function engineShimDir(env = process.env, home = homedir()) {
+  const agentDir = withAgentDir(env, home)[AGENT_DIR_ENV];
+  return join(dirname(agentDir), "engine");
+}
+
+/**
+ * Env for an engine we spawn: our configuration directory under both names, no update
+ * banner, and -- when the shim exists -- the shim as the engine's package directory.
+ * See the constants for why each is there.
+ *
+ * @param {object} env the environment to extend
+ * @param {string} [home] home directory, injectable for tests
+ * @param {{ shimDir?: string | null }} [options] `shimDir` is the result of
+ *   `ensureEngineShim`; null (shim not created) REMOVES any inherited PI_PACKAGE_DIR so
+ *   the engine runs from its installed directory and shows its own name. Inherited is
+ *   not hypothetical: the ACP path assigns this env into `process.env`, and a user may
+ *   have exported one -- either would point a shim-less engine at a foreign or stale
+ *   directory instead of its own.
+ */
+export function engineEnv(env, home = homedir(), { shimDir = null } = {}) {
+  const result = { ...withAgentDir(env, home), [SKIP_VERSION_CHECK_ENV]: "1" };
+  // `??=` keeps a value the user exported, including an empty one they set on purpose.
+  for (const [name, value] of Object.entries(RECHECK_ENV_DEFAULTS)) result[name] ??= value;
+  if (shimDir) result[PACKAGE_DIR_ENV] = shimDir;
+  else delete result[PACKAGE_DIR_ENV];
+  return result;
+}
+
+/**
+ * Settings the engine must start with in a configuration directory we own.
+ *
+ * `quietStartup` suppresses the engine's built-in startup header. Our own header
+ * replaces it through `ctx.ui.setHeader()` from the identity extension, but that hook
+ * runs on `session_start`, which the engine fires AFTER it has drawn its header and
+ * finished downloading its managed tools -- so for up to a second on a first run the
+ * user sees the engine's own name and its "Pi can explain its own features" sentence
+ * before ours appears. With the setting on, the engine mounts an empty header instead
+ * (`interactive-mode.js`, "Minimal header when silenced") and ours is the first thing
+ * drawn. The setting also hides the loaded-resources listing, which names the bundled
+ * packages by directory; it stays reachable through the engine's expand key.
+ */
+export const SEEDED_SETTINGS = Object.freeze({ quietStartup: true });
+
+/**
+ * Writes SEEDED_SETTINGS into the agent directory's `settings.json`, adding only the
+ * keys that are absent.
+ *
+ * Absent, not different: a user who set `quietStartup: false` by hand asked for the
+ * engine's header and keeps it. The engine itself merges only the fields it modified
+ * into this file (`settings-manager.js`, `persistScopedSettings`), so a key seeded here
+ * survives the engine's own writes. Same temp+rename discipline as the manifest: the
+ * engine reads this file at every start and a truncated one is a load error.
+ *
+ * @param {string} agentDir the engine configuration directory
+ * @returns {{ status: "unchanged" | "seeded" | "failed", detail?: string }}
+ */
+export function ensureAgentSettings(agentDir, {
+  read = readFileSync,
+  write = writeFileSync,
+  rename = renameSync,
+  remove = rmSync,
+  mkdir = mkdirSync,
+} = {}) {
+  const settingsPath = join(agentDir, "settings.json");
+  let current = {};
+  try {
+    current = JSON.parse(read(settingsPath, "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      // Malformed or unreadable: the engine will report that itself; do not paper over it.
+      return { status: "failed", detail: `cannot read ${settingsPath}: ${error.message}` };
+    }
+  }
+  if (current === null || typeof current !== "object" || Array.isArray(current)) {
+    return { status: "failed", detail: `${settingsPath} is not a JSON object` };
+  }
+  const missing = Object.entries(SEEDED_SETTINGS).filter(([key]) => !(key in current));
+  if (missing.length === 0) return { status: "unchanged" };
+
+  const seeded = { ...current, ...Object.fromEntries(missing) };
+  const tempPath = join(agentDir, `.settings.json.${process.pid}.${Date.now()}.tmp`);
+  try {
+    mkdir(agentDir, { recursive: true });
+  } catch (error) {
+    return { status: "failed", detail: `cannot create ${agentDir}: ${error.message}` };
+  }
+  const written = writeAtomically(settingsPath, tempPath, `${JSON.stringify(seeded, null, 2)}\n`, { write, rename, remove });
+  if (written !== null) return { status: "failed", detail: `cannot write ${settingsPath}: ${written.message}` };
+  return { status: "seeded" };
+}
+
+/**
+ * Builds (or refreshes) the directory the engine is told is its own package.
+ *
+ * ## Why a shim and not the installed manifest
+ *
+ * The engine reads its `package.json` once at load and takes its display name, terminal
+ * title and the name of its configuration-directory variable from `piConfig.name` -- a
+ * mechanism upstream documents for forks. That file belongs to a peer dependency that
+ * npm installs into whatever prefix runs us (`release/`, an IDE's private prefix, the
+ * `npx` cache), sometimes deduplicated with a `pi` the user installed globally. Editing
+ * it in place worked but meant rewriting a file we do not own, in a directory that may
+ * be shared with another program: a global `pi` next to a global install of this package
+ * would silently start answering as ours.
+ *
+ * `PI_PACKAGE_DIR` is the engine's own override of where that manifest lives. So the
+ * wrapper keeps a directory of its own next to the agent directory holding a COPY of the
+ * engine's manifest with `piConfig.name` set, and links for everything else the engine
+ * resolves relative to its package directory (`ENGINE_SHIM_LINKS`). The engine runs
+ * from its installed `dist/`, reads its identity from our copy, and finds its docs,
+ * themes and assets through the links. Nothing under `node_modules` is touched, and the
+ * paths the engine prints about itself ("see .../docs/providers.md") are ours.
+ *
+ * ## Idempotence
+ *
+ * Rebuilt only when the shim no longer describes the installed engine; what "describes"
+ * checks is in `shimIsCurrent`. A version bump of the engine, an install in a new
+ * prefix, a reinstall of the same version with a changed manifest, or a link whose
+ * target is gone all rebuild the whole directory. The copy is `version`-exact on
+ * purpose -- the engine prints that version, and the self-update code compares it.
+ *
+ * ## Concurrency
+ *
+ * The rebuild is STAGED in a sibling directory and PUBLISHED by rename, never built in
+ * place: two wrappers (the IDE adapter and a terminal `login`) can start together on a
+ * first run or right after an engine bump, and an in-place `rm -rf` + rebuild would let
+ * one delete the directory the other was filling -- or the one an engine was already
+ * reading. With staging, the live directory is replaced by a whole one in a single
+ * rename; the loser of the race finds the winner's directory in the way, and if that
+ * directory is current, that is the result it wanted. No lock file: one that survives a
+ * crash would have to be aged out, and a wait loop belongs in neither of these
+ * launches.
+ *
+ * ## Failure
+ *
+ * Reported, not thrown, and the caller launches WITHOUT `PI_PACKAGE_DIR`: the engine then
+ * shows its own name, which is a cosmetic defect; a refused login is not. The manifest
+ * copy goes through temp + rename (same reason as `ensureAgentSettings`: the engine
+ * reads it at every start and a truncated one is a load error).
+ *
+ * ## Links and copies
+ *
+ * Directories are linked as `"junction"` so Windows needs no privilege (a junction is
+ * the one reparse type an unprivileged user may create; Node maps the type to a plain
+ * symlink elsewhere). Files (`README.md`, `CHANGELOG.md`) are COPIED, not linked: a file
+ * symlink on Windows needs Developer Mode or elevation, and failing the whole shim over
+ * two small text files the engine only shows on request would be the wrong trade. The
+ * copies are compared by size on every launch (see `shimIsCurrent`); a same-size edit
+ * of a file the engine only shows on request is the accepted blind spot.
+ *
+ * @param {string} engineDir directory of the installed engine (holds its package.json)
+ * @param {string} shimDir where the shim lives; see `engineShimDir`
+ * @param {object} [io] file operations, injectable for tests
+ * @returns {{ status: "unchanged" | "built" | "failed", shimDir: string | null, detail?: string }}
+ */
+export function ensureEngineShim(engineDir, shimDir, {
+  read = readFileSync,
+  write = writeFileSync,
+  rename = renameSync,
+  remove = rmSync,
+  mkdir = mkdirSync,
+  symlink = symlinkSync,
+  copy = copyFileSync,
+  readlink = readlinkSync,
+  lstat = lstatSync,
+  stat = statSync,
+} = {}) {
+  const installedPath = join(engineDir, "package.json");
+  const shimManifestPath = join(shimDir, "package.json");
+  let installed;
+  try {
+    installed = JSON.parse(read(installedPath, "utf8"));
+  } catch (error) {
+    return { status: "failed", shimDir: null, detail: `cannot read ${installedPath}: ${error.message}` };
+  }
+
+  const branded = { ...installed, piConfig: { ...(installed.piConfig ?? {}), name: ENGINE_BRAND } };
+  const brandedText = `${JSON.stringify(branded, null, 2)}\n`;
+  const fsOps = { read, readlink, lstat, stat };
+  const linksOf = (dir) => ENGINE_SHIM_LINKS.map((entry) => [join(dir, entry), join(engineDir, entry)]);
+
+  if (shimIsCurrent(brandedText, shimManifestPath, linksOf(shimDir), fsOps)) {
+    return { status: "unchanged", shimDir };
+  }
+
+  // Stage in a sibling, publish by rename: see "Concurrency" above. The random part
+  // keeps two builds in one process (or two processes in one millisecond) apart.
+  const stamp = `${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`;
+  const staging = join(dirname(shimDir), `.${basename(shimDir)}.${stamp}.tmp`);
+  const retired = join(dirname(shimDir), `.${basename(shimDir)}.${stamp}.old`);
+  const discard = (dir) => { try { remove(dir, { recursive: true, force: true }); } catch { /* a leftover is the lesser defect */ } };
+  const failed = (detail) => { discard(staging); return { status: "failed", shimDir: null, detail }; };
+
+  try {
+    mkdir(staging, { recursive: true });
+  } catch (error) {
+    return failed(`cannot create ${staging}: ${error.message}`);
+  }
+
+  const stagedManifest = join(staging, "package.json");
+  const written = writeAtomically(stagedManifest, join(staging, `.package.json.${stamp}.tmp`), brandedText, { write, rename, remove });
+  if (written !== null) return failed(`cannot write ${stagedManifest}: ${written.message}`);
+
+  for (const [linkPath, target] of linksOf(staging)) {
+    let isDirectory = false;
+    try {
+      isDirectory = stat(target).isDirectory();
+    } catch (error) {
+      return failed(`engine has no ${target}: ${error.message}`);
+    }
+    try {
+      if (isDirectory) symlink(target, linkPath, "junction");
+      else copy(target, linkPath);
+    } catch (error) {
+      return failed(`cannot ${isDirectory ? "link" : "copy"} ${linkPath}: ${error.message}`);
+    }
+  }
+
+  // Publish. The previous directory is moved aside first (a rename onto a non-empty
+  // directory fails on every platform), then removed once the new one is in place.
+  try {
+    try {
+      rename(shimDir, retired);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    rename(staging, shimDir);
+  } catch (error) {
+    discard(staging);
+    // Another wrapper published between our check and our rename: its directory is the
+    // one in the way. If it describes this engine, that is exactly the result we wanted.
+    if (shimIsCurrent(brandedText, shimManifestPath, linksOf(shimDir), fsOps)) {
+      discard(retired);
+      return { status: "built", shimDir };
+    }
+    // Nothing usable is in place and we moved a working shim aside a moment ago, so the
+    // publish failed for a reason of our own (EACCES, EIO, a full disk). Put the old
+    // directory back instead of discarding it: it was valid until we touched it, and
+    // destroying it would leave every LATER launch unbranded too, until a rebuild happens
+    // to succeed. THIS launch still reports failure -- the restored shim describes the
+    // engine we were replacing, so handing it over would make the engine read a stale
+    // version out of it.
+    try {
+      rename(retired, shimDir);
+    } catch {
+      discard(retired);
+    }
+    return { status: "failed", shimDir: null, detail: `cannot publish ${shimDir}: ${error.message}` };
+  }
+  discard(retired);
+  return { status: "built", shimDir };
+}
+
+/**
+ * Whether an existing shim already describes THIS installed engine.
+ *
+ * The check is what a launch can afford: everything it reads is either already in
+ * memory or a single `stat`.
+ *
+ * - The manifest copy must be byte-identical to what we would write now. The installed
+ *   manifest is read anyway, so this costs one string comparison, and it catches what a
+ *   `name` + `version` check let through: a reinstall of the same version whose manifest
+ *   changed (`npm link` to a checkout, a patched `bin`).
+ * - Every directory link must point at the installed engine AND its target must exist:
+ *   the text of a link says where it pointed, not whether anything is still there, so
+ *   an engine removed from under the shim (uninstall, `npx` cache eviction) is a
+ *   dangling link with the right text.
+ * - Every file copy must exist with the SAME SIZE as its source. Content is not compared
+ *   -- two file reads per launch for files the engine only shows on request -- so a
+ *   same-size edit is the accepted blind spot.
+ *
+ * `brandedText` is the exact text `ensureEngineShim` writes.
+ */
+function shimIsCurrent(brandedText, shimManifestPath, linkTargets, { read, readlink, lstat, stat }) {
+  try {
+    if (read(shimManifestPath, "utf8") !== brandedText) return false;
+  } catch {
+    return false;
+  }
+  for (const [linkPath, target] of linkTargets) {
+    try {
+      const entry = lstat(linkPath);
+      if (entry.isSymbolicLink()) {
+        if (resolve(readlink(linkPath)) !== resolve(target)) return false;
+        if (!stat(linkPath).isDirectory()) return false; // follows the link: throws when the target is gone
+      } else if (!entry.isFile() || entry.size !== stat(target).size) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Where an interactive engine should read the user's keystrokes from.
+ *
+ * Returns `0` when our own stdin is already a terminal, the descriptor of the
+ * controlling terminal when it is not, and `null` when there is no terminal at all.
+ *
+ * The middle case is the one that matters, and it is not a corner case: it is how an
+ * IDE runs the login. A client offers the "Authenticate" action by launching the
+ * command from its config with the auth method's `args` appended, and it wires the
+ * child's OUTPUT to a terminal panel while leaving stdin a pipe it controls. Judging
+ * "is there a terminal?" by `process.stdin.isTTY` therefore answers a different
+ * question than the one being asked, and refusing on that basis closes the window
+ * the user just opened.
+ *
+ * `/dev/tty` is the process's CONTROLLING terminal rather than one of its
+ * descriptors, so it stays reachable when fd 0 has been replaced -- and it fails with
+ * ENXIO precisely when the process has no terminal to fall back on, which is the
+ * genuinely unusable case (a headless pipe, cron, CI). That makes opening it both the
+ * fix and the test.
+ *
+ * `openTty` is injected so the decision can be exercised without depending on the
+ * machine the tests run on.
+ */
+export function interactiveStdin({ isTTY, openTty }) {
+  if (isTTY) return 0;
+  try {
+    return openTty();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Adapter arguments with resource isolation guaranteed.
+ *
+ * Every ACP run is isolated from the machine's own pi resources: the engine loads
+ * the extensions, skills and prompt templates of OUR package, and none of the user's.
+ * The flag list and its rationale live in `vendor/pi-acp/src/cli.ts` (`devPackageArgs`),
+ * which is the single source of truth for what isolation covers.
+ *
+ * Without this the engine merges its user-level registrations into the session, so
+ * the agent's tool set becomes a property of the machine it runs on -- and any
+ * pi package the user already registered collides with the copy we bundle. That is
+ * not hypothetical: a pre-existing `pi-subagents` registration makes the engine
+ * exit 1 with `Tool "subagent" conflicts`, killing the session before a single
+ * protocol frame is written.
+ *
+ * An explicit flag is never overwritten, so the wrapper's own root is a DEFAULT and
+ * not a policy. Every backend this project writes relies on that default and passes
+ * no path at all; the flag is for pointing a wrapper at some OTHER package root --
+ * an experiment, a bisect, a second build -- and silently rewriting it to the
+ * wrapper's own would run something different from what was asked for while
+ * reporting success.
+ *
+ * The scan is deliberately flat and does NOT stop at a `--` separator, even though
+ * that means data after `--` can look like the flag. Teaching it about `--` would be
+ * strictly worse: the adapter scans the whole argv the same way and rejects a second
+ * occurrence outright (`--dev-package may only be specified once`, vendor/pi-acp/src/
+ * cli.ts), so on `acp -- --dev-package x` we would add a duplicate and the agent would
+ * not start at all. Matching the consumer's parser beats being right in isolation.
+ */
+export function withIsolation(rest, packageRoot) {
+  if (!packageRoot) return [...rest];
+  if (rest.includes(ISOLATION_FLAG)) return [...rest];
+  return [ISOLATION_FLAG, packageRoot, ...rest];
+}
+
+/**
+ * Subcommands this CLI understands.
+ *
+ * `tui` (also the bare invocation) is the terminal product. `login` exists because
+ * the agent's configuration directory is its own: a fresh one holds no credentials,
+ * and the engine has no non-interactive command that writes them -- `pi auth ...`
+ * only prints and checks. So the one supported bootstrap is the engine's own
+ * interactive UI, started directly against our directory; `logout` removes what it
+ * stored. `acp` is parsed everywhere but only FUNCTIONS in the managed-backend and
+ * 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"]);
+
+/**
+ * Engine flags that confine a terminal run to a single package: ours.
+ *
+ * The same three flags the ACP adapter's `devPackageArgs()` passes (vendor/pi-acp/
+ * src/cli.ts), duplicated here DELIBERATELY: the public terminal artifact ships
+ * without the adapter and without `scripts/`, so nothing in the tarball can derive
+ * the list from the adapter source. A test compares the two where the submodule is
+ * present, so the copies cannot drift silently.
+ */
+export const TERMINAL_ISOLATION_FLAGS = ["--no-extensions", "--no-skills", "--no-prompt-templates"];
+
+/**
+ * Engine flag that keeps a run out of the session store.
+ *
+ * `login` is not a work session: nothing said in it is worth resuming, and the engine's
+ * exit hint ("To resume this session: explyt --session <id>") would advertise a session
+ * nobody wants back. Ephemeral, the engine writes no session file and prints no hint.
+ * The bare TUI keeps its sessions -- there resuming is a feature.
+ */
+export const NO_SESSION_FLAG = "--no-session";
+
+/**
+ * Engine flags that ask for a stored session, which `login` cannot honour.
+ *
+ * In the engine, `--no-session` is checked BEFORE `--session`, `--fork`, `--resume` and
+ * `--continue` (`dist/main.js`, `createSessionManager`): with NO_SESSION_FLAG present
+ * they parse fine and do nothing. Passing them through would therefore ACCEPT a
+ * `login --session <id>` and silently ignore it, so `terminalEngineArgs` refuses them
+ * for login instead. Spellings are the engine's own (`dist/cli/args.js`): the long
+ * flags, the `-c`/`-r` shorts, and the `--flag=value` form -- which the engine's parser
+ * does not even recognise as these flags, but the user meant it, and a mis-spelled
+ * request that is refused beats one that is quietly dropped. `--session-id` is NOT
+ * here: the engine honours it for an in-memory session too.
+ */
+export const LOGIN_SESSION_CONFLICTS = Object.freeze(["--session", "--fork", "--resume", "-r", "--continue", "-c"]);
+
+/**
+ * The first argument in `extra` that asks for a stored session, or null.
+ * Exported so the entrypoint can turn it into a message without repeating the list.
+ */
+export function loginSessionConflict(extra) {
+  const valueForm = LOGIN_SESSION_CONFLICTS.filter((flag) => flag.startsWith("--")).map((flag) => `${flag}=`);
+  return extra.find((arg) => LOGIN_SESSION_CONFLICTS.includes(arg) || valueForm.some((prefix) => arg.startsWith(prefix))) ?? null;
+}
+
+/**
+ * The engine argv for a terminal run (TUI or interactive login).
+ *
+ * Assembled as a WHOLE so a caller cannot spread the isolation flags and forget the
+ * `--extension` value, or vice versa: the engine would start fine either way and load
+ * something other than the product.
+ *
+ * Throws for `login` combined with a LOGIN_SESSION_CONFLICTS flag: the engine would
+ * take the flag and do nothing with it. The message is for a person.
+ *
+ * @param {string} entrypoint the engine's JS entrypoint
+ * @param {string} packageRoot the package the engine must load exclusively
+ * @param {string[]} extra flags the user passed through
+ * @param {{ login?: boolean }} [options] `login: true` adds NO_SESSION_FLAG
+ */
+export function terminalEngineArgs(entrypoint, packageRoot, extra = [], { login = false } = {}) {
+  if (login) {
+    const conflict = loginSessionConflict(extra);
+    if (conflict !== null) {
+      throw new Error(
+        `\`login\` does not accept ${conflict}: login is not a work session and stores nothing to resume.\n` +
+        "  Store the credential with `login` alone, then open the session with `tui` and that flag.",
+      );
+    }
+  }
+  const session = login && !extra.includes(NO_SESSION_FLAG) ? [NO_SESSION_FLAG] : [];
+  return [entrypoint, ...TERMINAL_ISOLATION_FLAGS, "--extension", packageRoot, ...session, ...extra];
+}
+
+/**
+ * The adapter's spelling of `login`, which we must answer to as well.
+ *
+ * Only the managed-backend artifact ever emits it: there the adapter advertises, in
+ * its `authMethods`, a terminal command built from `process.argv[0..1]`
+ * (`vendor/pi-acp/src/acp/auth.ts`) -- `<node> <wrapper> --terminal-login` -- and the
+ * client appends those args to the command line already in its config, so what runs
+ * is `... index.js acp --terminal-login`. `parseArgs` lets the flag OUTRANK the
+ * leading `acp`, mapping it to `command = "login"`; the wrapper then spawns the
+ * engine's interactive UI directly (`terminalEngineArgs`), exactly as a typed `login`
+ * does. Letting `acp` win would start a protocol server in the user's terminal,
+ * waiting for frames nobody types. In the public terminal artifact the flag is
+ * accepted as a harmless synonym: nothing there advertises it.
+ *
+ * Accepting the flag rather than teaching the fork to advertise `login` keeps the
+ * edit out of a file that merges with upstream.
+ */
+export const ADAPTER_LOGIN_FLAG = "--terminal-login";
 
 /**
  * Flags belonging to other programs that consume the NEXT argument as their value.
@@ -304,7 +836,7 @@ export const COMMANDS = new Set(["install", "uninstall", "acp"]);
  * which it rejects. Only pass-through flags need listing; our own flags are handled
  * explicitly below.
  */
-export const VALUE_FLAGS = new Set(["--dev-package", "--extension", "--model", "--cwd"]);
+export const VALUE_FLAGS = new Set([ISOLATION_FLAG, "--extension", "--model", "--cwd"]);
 
 /**
  * Argument shape of the user-facing CLI.
@@ -334,6 +866,13 @@ export function parseArgs(argv) {
     if (arg === "--help" || arg === "-h") { help = true; continue; }
     if (arg === "--version" || arg === "-v") { version = true; continue; }
 
+    // The flag form of `login`, which is what a client runs from `authMethods`. It
+    // overrides a subcommand instead of yielding to it, because the client appends it
+    // 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; }
+
     // A foreign flag plus its value: forward both, and never read the value as a
     // subcommand.
     if (VALUE_FLAGS.has(arg)) {
@@ -356,22 +895,26 @@ export function parseArgs(argv) {
   return { command, help, version, rest };
 }
 
-export function helpText(name = "explyt-ai-agent") {
+export function helpText() {
   return [
     "Explyt AI Agent",
     "",
-    "Usage:",
-    `  npx ${name} install     register the agent so IDEs and the terminal can use it`,
-    `  npx ${name} uninstall   remove the registration`,
-    `  npx ${name} acp         run as an ACP server (this is how an IDE starts it)`,
+    "Install globally: npm i -g @explyt/ai-agent, then run explyt",
+    "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",
     "",
-    "Options:",
-    "  -h, --help      show this message",
-    "  -v, --version   print the version",
+    "Global commands: explyt tui | login | logout | update",
+    "  explyt update      check npm latest and update a global installation",
+    "  -h, --help         show this message",
+    "  -v, --version      print the version",
     "",
-    "With no arguments the agent starts in ACP mode when its input is a pipe, which is",
-    "what IDE clients do. Configure a client with:",
-    `  {"command": "npx", "args": ["-y", "@explyt/ai-agent@<version>", "acp"]}`,
+    "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.",
     "",
   ].join("\n");
 }