omnirush 0.8.6 → 0.9.1

package/src/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omnirush — launcher for the Omnirush coding agent (pi core).
+// omnirush — launcher for the Omnirush coding agent.
 //
 // The CLI is a thin client of the Omnirush manager (a single public
 // HTTPS origin, real cert — no helper proxy, no custom CA):
@@ -8,15 +8,18 @@
 //                     stored 0600 in ~/.omnirush/auth.json)
 //   omnirush logout   forget the stored tokens
 //   omnirush whoami   show the signed-in device identity
-//   omnirush doctor   check auth (or pending login), manager, pi config
+//   omnirush doctor   check auth (or pending login), manager, agent config
 //   omnirush collect  one-shot workspace snapshot upload
-//   omnirush          run the agent (default; forwards to pi)
+//   omnirush update   update omnirush from npm
+//   omnirush          run the agent (default; forwards to the agent core)
 //
 // Environment:
 //   OMNIRUSH_ORIGIN       manager origin override (default
 //                         https://omnirush.ai/omnirush)
 //   OMNIRUSH_GATEWAY_URL  provider base URL override ({origin}/v1)
 //   OMNIRUSH_DIR          state dir override (default ~/.omnirush)
+//   OMNIRUSH_AGENT_DIR    agent data dir override (default <state dir>/agent;
+//                         OMNIRUSH_PI_AGENT_DIR is the older spelling)
 //   OMNIRUSH_MODEL        model override for plain runs (default
 //                         gpt-6-astra; gpt-6-sol, gpt-5.6-sol and the Muse
 //                         models also available; user
@@ -47,8 +50,12 @@ import {
   withModelDefaults,
   withDefaultThinkingLevel,
   resolveModelDefaults,
+  resolveYolo,
+  yoloBanner,
 } from "./lib.js";
 import { installManagedTools } from "./tools.js";
+import { engineEnvAliases, migrateAgentDir, projectConfigDirName, resolveAgentDir } from "./compat.js";
+import { customSessionDir, moveLegacySubagentSessions } from "./sessions.js";
 import { ensureRuntime, managedBunPath } from "../scripts/postinstall.js";
 import {
   clearAuth,
@@ -70,14 +77,43 @@ import {
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const OMNI_DIR = omniDir();
-// OMNIRUSH_PI_AGENT_DIR overrides where pi's config/extensions live
-// (tests use it to keep the real ~/.pi untouched).
-const PI_AGENT_DIR = process.env.OMNIRUSH_PI_AGENT_DIR
-  ? path.resolve(process.env.OMNIRUSH_PI_AGENT_DIR)
-  : path.join(os.homedir(), ".pi", "agent");
-const PI_MODELS_JSON = path.join(PI_AGENT_DIR, "models.json");
-const PI_SETTINGS_JSON = path.join(PI_AGENT_DIR, "settings.json");
-const PI_EXT_DIR = path.join(PI_AGENT_DIR, "extensions", "omnirush");
+process.title = "omnirush";
+// The agent core's data (settings, models.json, provider auth, sessions,
+// extensions): <state dir>/agent, or OMNIRUSH_AGENT_DIR. Releases up to
+// 0.8.x used the core's upstream default folder; ensureDirs() copies it
+// over once (src/compat.js) and falls back to it for a run whose copy failed.
+const AGENT = resolveAgentDir(process.env, { stateDir: OMNI_DIR });
+let PI_AGENT_DIR, PI_MODELS_JSON, PI_SETTINGS_JSON, PI_EXT_DIR;
+function useAgentDir(dir) {
+  PI_AGENT_DIR = dir;
+  PI_MODELS_JSON = path.join(dir, "models.json");
+  PI_SETTINGS_JSON = path.join(dir, "settings.json");
+  PI_EXT_DIR = path.join(dir, "extensions", "omnirush");
+}
+useAgentDir(AGENT.dir);
+
+/** One-time copy of the pre-0.9 agent data into the new folder (see src/compat.js). */
+function migrateLegacyAgentData() {
+  if (!AGENT.legacyDir) return;
+  const result = migrateAgentDir({
+    from: AGENT.legacyDir,
+    to: AGENT.dir,
+    onStart: () => console.error(`omnirush: copying your sessions and agent settings to ${AGENT.dir} (one time)...`),
+  });
+  if (result.status === "migrated") {
+    console.error(
+      `omnirush: done (${result.copied} files copied${result.merged ? `, ${result.merged} merged` : ""}; ` +
+        "the previous folder was left as it was).",
+    );
+  } else if (result.status === "failed") {
+    // Never lose data: run on the previous folder and retry next launch.
+    console.error(
+      `omnirush: could not copy your agent data to ${AGENT.dir} (${result.error?.message ?? result.error}); ` +
+        "using the previous folder for this run, retrying next time.",
+    );
+    useAgentDir(AGENT.legacyDir);
+  }
+}
 
 function managerOrigin() {
   return (
@@ -111,11 +147,12 @@ function piPackage() {
 function piEntry() {
   const found = piPackage();
   if (found?.pkg?.bin?.pi) return path.join(found.dir, found.pkg.bin.pi);
-  throw new Error("could not locate the pinned pi CLI (@earendil-works/pi-coding-agent)");
+  throw new Error("could not locate the pinned agent core (broken install). Fix: npm install -g omnirush@latest");
 }
 
 function ensureDirs() {
   fs.mkdirSync(OMNI_DIR, { recursive: true, mode: 0o700 });
+  migrateLegacyAgentData();
   fs.mkdirSync(PI_AGENT_DIR, { recursive: true });
   fs.mkdirSync(PI_EXT_DIR, { recursive: true });
   try {
@@ -126,6 +163,23 @@ function ensureDirs() {
   installDefaultThinkingLevel();
 }
 
+/**
+ * Sub-agent sessions older releases wrote next to the user's are moved to
+ * their session dir's subagents/ folder before the core picks a session,
+ * so /resume lists only the user's sessions and --continue resumes the
+ * user's last one (src/sessions.js). Not on a run that fell back to the
+ * pre-0.9 folder, which is left as it was.
+ */
+function tidySubagentSessions(args) {
+  if (AGENT.legacyDir && PI_AGENT_DIR === AGENT.legacyDir) return;
+  try {
+    const custom = customSessionDir(args, process.env, PI_SETTINGS_JSON, os.homedir());
+    moveLegacySubagentSessions({ agentDir: PI_AGENT_DIR, extraDirs: custom ? [custom] : [] });
+  } catch {
+    /* best effort */
+  }
+}
+
 // Product default effort (P2): xhigh. Fills an ABSENT
 // defaultThinkingLevel in the agent settings only — an explicit user
 // choice always wins; the models' thinkingLevelMap is untouched.
@@ -233,7 +287,7 @@ function installExtensions() {
     fs.mkdirSync(to, { recursive: true });
     for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
       if (entry.isDirectory()) copy(path.join(from, entry.name), path.join(to, entry.name));
-      else if (entry.name.endsWith(".ts") || entry.name.endsWith(".js")) {
+      else if (entry.name.endsWith(".ts") || entry.name.endsWith(".js") || entry.name.endsWith(".cjs")) {
         fs.copyFileSync(path.join(from, entry.name), path.join(to, entry.name));
       }
     }
@@ -729,6 +783,8 @@ function childEnv(auth) {
   const origin = (process.env.OMNIRUSH_ORIGIN || "").trim().replace(/\/+$/, "") ||
     gateway.replace(/\/+$/, "").replace(/\/v1$/, ""); // provider base -> manager origin
   return {
+    // OMNIRUSH_* spellings of the core's own settings (PI_* still work).
+    ...engineEnvAliases(process.env),
     // Bootstrap values only: the agent (and every sub-agent it spawns)
     // re-reads the shared auth file in OMNIRUSH_DIR for each request, so
     // these never go stale in a way that matters.
@@ -738,15 +794,22 @@ function childEnv(auth) {
     OMNIRUSH_GATEWAY_URL: gateway,
     OMNIRUSH_DIR: OMNI_DIR,
     // /status shows the CLI version; extensions have no package.json of
-    // their own in ~/.pi, so the launcher hands it over.
+    // their own in the agent dir, so the launcher hands it over.
     OMNIRUSH_VERSION: ownVersion(),
     // The collector reports it as the environment's engine_version.
     OMNIRUSH_ENGINE_VERSION: engineVersion(),
+    // Where this package lives: extensions (copied to the agent dir) load optional
+    // native dependencies from here (voice: @picovoice/pvrecorder-node).
+    OMNIRUSH_PACKAGE_ROOT: path.resolve(__dirname, ".."),
     // The agent resolves its config dir from <APP>_CODING_AGENT_DIR. The
     // branding patch renames the app to omnirush, so set the omnirush
     // spelling; the pi spelling stays for unpatched cores.
     OMNIRUSH_CODING_AGENT_DIR: PI_AGENT_DIR,
     PI_CODING_AGENT_DIR: PI_AGENT_DIR,
+    // Project settings live in <project>/.omnirush; a project that only
+    // has the pre-0.9 folder keeps using that one (the branding patch
+    // makes the core read this variable).
+    OMNIRUSH_PROJECT_CONFIG_DIR: projectConfigDirName(process.cwd()),
     // The agent core is a fork/rebrand: never phone home to pi.dev.
     // PI_OFFLINE kills startup update checks (the "Update Available —
     // pi.dev/changelog" banner), package updates, and install/update
@@ -804,6 +867,32 @@ function spawnAgent(cmd, args, opts) {
   return child;
 }
 
+/** The saved /yolo setting ("yolo": true in <state dir>/settings.json). */
+function yoloSetting() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(OMNI_DIR, "settings.json"), "utf8"))?.yolo === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Yolo mode for an agent launch: strips --yolo/--no-yolo, adds the core's
+ * --approve (project trusted for the run) and hands the state to the
+ * extensions (OMNIRUSH_YOLO). Non-interactive runs get the banner on
+ * stderr here; the TUI shows it itself (yolo.ts).
+ */
+function launchYolo(args) {
+  const resolved = resolveYolo(args, { env: process.env, setting: yoloSetting() });
+  const env = { OMNIRUSH_YOLO: resolved.yolo ? "1" : "0", OMNIRUSH_YOLO_SOURCE: resolved.source };
+  if (resolved.yolo) {
+    env.OMNIRUSH_YOLO_TRUSTED = resolved.trusted ? "1" : "0";
+    const headless = resolved.args.some((a) => a === "-p" || a === "--print" || a === "--mode") || !process.stdout.isTTY;
+    if (headless) console.error(`omnirush: ${yoloBanner(resolved)}`);
+  }
+  return { args: resolved.args, env };
+}
+
 async function cmdRun() {
   ensureDirs();
   const auth = requireAuth();
@@ -813,11 +902,14 @@ async function cmdRun() {
   const { cmd, args } = await runtimeFor(entry);
   // Plain `omnirush` always runs the SOTA model (charter rule 1); user
   // flags win when present.
-  const piArgs = withModelDefaults([], resolveModelDefaults(process.env));
+  // `omnirush run` takes no other arguments; only yolo's --approve passes.
+  const yolo = launchYolo(process.argv.slice(3).filter((a) => a === "--yolo" || a === "--no-yolo"));
+  tidySubagentSessions([]);
+  const piArgs = withModelDefaults(yolo.args, resolveModelDefaults(process.env));
   spawnAgent(cmd, [...args, ...piArgs], {
     stdio: "inherit",
     // The pair may have rotated during launch (model catalog refresh).
-    env: { ...process.env, ...childEnv(loadAuth(OMNI_DIR) ?? auth) },
+    env: { ...process.env, ...childEnv(loadAuth(OMNI_DIR) ?? auth), ...yolo.env },
   });
 }
 
@@ -854,8 +946,18 @@ Options:
                                     gpt-5.6-sol, meta-muse-spark, muse-spark-1.1;
                                     effort: minimal..max)
   --thinking <level>                reasoning effort override
+  --subagent-model <id|same>        model the sub-agents run on for this run
+                                    (one of your account's models; default: the
+                                    one picked with /subagents, else the main model)
+  --subagent-effort <level|same>    sub-agent effort for this run (limited to
+                                    that model's levels)
   --strict-sota                     exit non-zero if the served model is not
                                     the requested SOTA model
+  --yolo                            yolo mode for this run: nothing asks, the
+                                    project folder is trusted, every command is
+                                    allowed (default: guarded mode, where git
+                                    writes, destructive commands and sudo ask
+                                    first; --no-yolo turns a saved /yolo on off)
   --session <file> | --continue     session options (forwarded to the agent)
   -p, --print "<prompt>"            print-mode: answer once and exit
   -h, --help                        show this help
@@ -865,6 +967,16 @@ Session commands (inside the agent):
   /usage   detailed usage from the manager (counters + devices)
   /status  session status (identity, model, grant, collector)
   /mcp     MCP server state (/mcp reconnect [server])
+  /subagents  model and effort of the sub-agents (/subagents model <id|same>,
+              /subagents effort <level|same>; saved for the next runs)
+  /agents  sub-agents of this session (/agents cancel <id|all>,
+           /agents memory: the memory they may use)
+  /jobs    background shell commands (/jobs kill <id|all>)
+  /voice   dictate prompts: hold Space to talk (/voice hold|tap|off|status)
+  /mode    approval mode: guarded (asks before git writes and destructive
+           commands) or yolo (/mode guarded|yolo; saved); /approvals reset
+           forgets this session's "allow for this session" answers
+  /yolo    yolo mode: no prompts, project trusted (/yolo on|off; saved)
   /verify  model attestation (arrives with the gateway lane)
 
 Environment:
@@ -872,11 +984,113 @@ Environment:
   OMNIRUSH_MODEL         default model override (e.g. gpt-6-sol)
   OMNIRUSH_STATIC_MODELS=1  use the shipped model list (no GET /v1/models)
   OMNIRUSH_DIR           state dir override (default ~/.omnirush)
+  OMNIRUSH_AGENT_DIR     agent data dir override (default ~/.omnirush/agent)
   OMNIRUSH_DEBUG=1       verbose diagnostics (raw gateway errors on failure)
+  OMNIRUSH_SUBAGENT_MODEL / OMNIRUSH_SUBAGENT_EFFORT
+                         sub-agent model / effort for this run (as the flags)
+  OMNIRUSH_YOLO=1        yolo mode (as --yolo; OMNIRUSH_YOLO=0 turns it off)
+  OMNIRUSH_BASH_FOREGROUND_SECONDS
+                         how long a shell command runs in the foreground before
+                         it continues in the background (default 300)
+  OMNIRUSH_AGENT_MIN_FREE / OMNIRUSH_AGENT_MEMORY_BUDGET / OMNIRUSH_AGENT_CRITICAL_FREE
+                         sub-agents start while this much RAM stays free
+                         (default 20%), all agents stay under this budget
+                         (default 50% of RAM), and none start below this
+                         (default 10%); e.g. 25% or 6G. OMNIRUSH_AGENT_MEMORY=off
+                         starts them without checking memory
+  OMNIRUSH_<SETTING>     the agent core's own settings (e.g. OMNIRUSH_CACHE_RETENTION;
+                         the older PI_<SETTING> names still work)
 
 Docs: https://omnirush.ai/omnirush — state is stored 0600 in ~/.omnirush`);
 }
 
+/**
+ * `omnirush update` updates omnirush itself from npm. The agent core's own
+ * self-update would install its stock upstream package instead, so only
+ * package and model-catalog updates (--extensions, --extension <source>,
+ * --models, a package source) are handed to the core; --all does both.
+ */
+async function cmdUpdate(args) {
+  if (args.includes("-h") || args.includes("--help")) return runCore(["update", ...args]);
+  const coreArgs = [];
+  let self = false;
+  let coreTarget = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    // "pi" is the core's own alias for self: never let it reach the core.
+    if (arg === "--self" || arg === "self" || arg === "omnirush" || arg === "pi") self = true;
+    else if (arg === "--all") {
+      self = true;
+      coreTarget = true;
+      coreArgs.push("--extensions");
+    } else if (arg === "--force") continue;
+    else {
+      if (arg === "--extensions" || arg === "--models" || arg === "--extension" || !arg.startsWith("-")) coreTarget = true;
+      coreArgs.push(arg);
+      if (arg === "--extension" && i + 1 < args.length) coreArgs.push(args[++i]);
+    }
+  }
+  if (!coreTarget) self = true;
+  if (self) {
+    const status = selfUpdate();
+    if (status !== 0) process.exit(status);
+  }
+  if (coreTarget) await runCore(["update", ...coreArgs]);
+}
+
+function selfUpdate() {
+  const { spawnSync } = require("node:child_process");
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const packageRoot = path.resolve(__dirname, "..");
+  let globalRoot = "";
+  try {
+    globalRoot = String(
+      spawnSync(npm, ["root", "-g"], { encoding: "utf8", shell: process.platform === "win32", timeout: 30_000 }).stdout || "",
+    ).trim();
+  } catch {
+    /* npm missing: handled below */
+  }
+  const npmManaged =
+    !!globalRoot && path.relative(path.resolve(globalRoot), packageRoot) === "omnirush";
+  if (!npmManaged) {
+    console.error(
+      `omnirush: this copy (${packageRoot}) was not installed with \`npm install -g omnirush\`. ` +
+        "Update it the way you installed it, or switch to the npm package: npm install -g omnirush@latest",
+    );
+    return 1;
+  }
+  console.log(`Updating omnirush ${ownVersion()}: npm install -g omnirush@latest`);
+  const result = spawnSync(npm, ["install", "-g", "omnirush@latest"], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  if (result.status !== 0) {
+    console.error("omnirush update failed. Run it yourself: npm install -g omnirush@latest");
+    return result.status || 1;
+  }
+  return 0;
+}
+
+// Forward everything else (including argv[0] — e.g. `-p prompt`,
+// `--provider x`, package subcommands) to the agent core, defaulting the
+// model the same way `omnirush run` does; user-specified --provider/--model
+// are never duplicated and core subcommands pass through untouched.
+async function runCore(args) {
+  ensureDirs();
+  const auth = requireAuth();
+  installModelsJson(agentGatewayUrl(auth), await launchModels(agentGatewayUrl(auth), auth.accessToken));
+  installExtensions();
+  const entry = piEntry();
+  const { cmd: bin, args: runtimeArgs } = await runtimeFor(entry);
+  const yolo = launchYolo(args);
+  const piArgs = withModelDefaults(yolo.args, resolveModelDefaults(process.env));
+  tidySubagentSessions(piArgs);
+  spawnAgent(bin, [...runtimeArgs, ...piArgs], {
+    stdio: "inherit",
+    env: { ...process.env, ...childEnv(auth), ...yolo.env },
+  });
+}
+
 const [, , ...argv] = process.argv;
 const cmd = argv[0];
 if (cmd === "-h" || cmd === "--help" || cmd === "help") printHelp();
@@ -887,20 +1101,5 @@ else if (cmd === "doctor") await cmdDoctor();
 else if (cmd === "--version" || cmd === "-v") console.log(`omnirush ${ownVersion()}`);
 else if (cmd === "collect") await cmdCollect(argv.slice(1));
 else if (cmd === undefined || cmd === "run") await cmdRun();
-else {
-  // Forward everything (including argv[0] — e.g. `--help`, `-p prompt`,
-  // `--provider x`) to pi, defaulting the model the same way
-  // `omnirush run` does; user-specified --provider/--model are never
-  // duplicated and pi admin subcommands pass through untouched.
-  ensureDirs();
-  const auth = requireAuth();
-  installModelsJson(agentGatewayUrl(auth), await launchModels(agentGatewayUrl(auth), auth.accessToken));
-  installExtensions();
-  const entry = piEntry();
-  const { cmd: bin, args } = await runtimeFor(entry);
-  const piArgs = withModelDefaults(argv, resolveModelDefaults(process.env));
-  spawnAgent(bin, [...args, ...piArgs], {
-    stdio: "inherit",
-    env: { ...process.env, ...childEnv(auth) },
-  });
-}
+else if (cmd === "update") await cmdUpdate(argv.slice(1));
+else await runCore(argv);

package/src/compat.js

@@ -0,0 +1,272 @@
+// Compatibility with installs made before the 0.9.0 rebrand.
+//
+// Up to 0.8.x the agent core kept its data (settings.json, models.json,
+// provider auth.json, sessions/, installed packages) in its upstream
+// default folder, ~/.pi/agent, and read project settings from <project>/.pi.
+// From 0.9.0 everything the user sees is named omnirush:
+//
+//   agent data      ~/.omnirush/agent   (inside the state dir, so
+//                                        OMNIRUSH_DIR moves it too)
+//   project config  <project>/.omnirush
+//   env variables   OMNIRUSH_*          (the core's PI_* names still work)
+//
+// This module holds the pure pieces the launcher uses to get there
+// without losing anything:
+//
+//   resolveAgentDir      where the agent data lives this run (and the
+//                        legacy folder to migrate from)
+//   migrateAgentDir      one-time COPY of the legacy folder into the new
+//                        one (the old folder is left untouched, so an
+//                        older omnirush keeps working); never overwrites,
+//                        merges the three JSON config files key by key,
+//                        writes a marker so it runs once, resumes after a
+//                        crash, and reports failure so the launcher can
+//                        fall back to the legacy folder for that run
+//   projectConfigDirName the project config folder name for a cwd: a
+//                        project that only has a legacy .pi folder keeps
+//                        using it
+//   engineEnvAliases     OMNIRUSH_* spellings of the core's PI_* settings
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Marker written into the new agent dir once the legacy data was copied. */
+export const MIGRATION_MARKER = ".migrated.json";
+
+/** Project config folder (the core's configDir after the branding patch). */
+export const PROJECT_CONFIG_DIR = ".omnirush";
+const LEGACY_PROJECT_CONFIG_DIR = ".pi";
+/** Entries that make a project config folder live (the core's trust-gated resources). */
+const PROJECT_RESOURCES = ["settings.json", "extensions", "skills", "prompts", "themes", "SYSTEM.md", "APPEND_SYSTEM.md"];
+
+/** Top-level JSON files merged key by key when both folders have them (the new folder's keys win). */
+const MERGED_JSON = new Set(["settings.json", "models.json", "auth.json"]);
+
+/**
+ * The core's own PI_* settings a user may set, accepted as OMNIRUSH_<NAME>
+ * (the launcher hands them to the core under the name it reads). The
+ * original PI_<NAME> keeps working unchanged. PI_OFFLINE / PI_TELEMETRY
+ * are always forced by the launcher and are not listed.
+ */
+export const ENGINE_ENV_NAMES = [
+  "CACHE_RETENTION",
+  "CLEAR_ON_SHRINK",
+  "EXPERIMENTAL",
+  "HARDWARE_CURSOR",
+  "HYPERLINKS",
+  "IMAGE_PROTOCOL",
+  "OAUTH_CALLBACK_HOST",
+  "PACKAGE_DIR",
+  "RADIUS_GATEWAY",
+  "SHARE_VIEWER_URL",
+  "SKIP_VERSION_CHECK",
+  "STARTUP_BENCHMARK",
+  "TIMING",
+  "TRUE_COLOR",
+  "TUI_DEBUG",
+  "TUI_DEBUG_REDRAW",
+  "TUI_ESC_TIMEOUT",
+  "TUI_WRITE_LOG",
+];
+
+/**
+ * Where the agent data lives: OMNIRUSH_AGENT_DIR (or its pre-0.9 spelling
+ * OMNIRUSH_PI_AGENT_DIR, or the core's own OMNIRUSH_CODING_AGENT_DIR, which
+ * nested runs inherit) when set — then nothing is migrated — else
+ * <stateDir>/agent, with ~/.pi/agent as the legacy folder to migrate from.
+ */
+export function resolveAgentDir(env = process.env, { stateDir, home = os.homedir() } = {}) {
+  const override = String(env.OMNIRUSH_AGENT_DIR || env.OMNIRUSH_PI_AGENT_DIR || env.OMNIRUSH_CODING_AGENT_DIR || "").trim();
+  if (override) return { dir: path.resolve(override), legacyDir: null };
+  const base = stateDir || path.join(home, ".omnirush");
+  return { dir: path.join(base, "agent"), legacyDir: path.join(home, ".pi", "agent") };
+}
+
+function isInside(parent, child, pathImpl) {
+  const relative = pathImpl.relative(parent, child);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !pathImpl.isAbsolute(relative));
+}
+
+function writeAtomic(fsImpl, dest, data, mode) {
+  const tmp = `${dest}.${process.pid}.migrating`;
+  fsImpl.writeFileSync(tmp, data, mode === undefined ? undefined : { mode });
+  fsImpl.renameSync(tmp, dest);
+}
+
+function readJson(fsImpl, file) {
+  try {
+    const value = JSON.parse(fsImpl.readFileSync(file, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Old keys fill the gaps of the new file; models.json merges its providers map the same way. */
+function mergeJson(name, older, newer) {
+  const merged = { ...older, ...newer };
+  if (name === "models.json" && older.providers && typeof older.providers === "object") {
+    merged.providers = { ...older.providers, ...(newer.providers || {}) };
+  }
+  return merged;
+}
+
+/**
+ * A session file's header names its parent session by absolute path; a
+ * copied session points at the copied parent instead.
+ */
+export function rebaseSessionHeader(content, from, to, pathImpl = path) {
+  const newline = content.indexOf("\n");
+  const first = newline === -1 ? content : content.slice(0, newline);
+  let header;
+  try {
+    header = JSON.parse(first);
+  } catch {
+    return content;
+  }
+  if (!header || header.type !== "session" || typeof header.parentSession !== "string") return content;
+  if (!isInside(from, header.parentSession, pathImpl)) return content;
+  header.parentSession = pathImpl.join(to, pathImpl.relative(from, header.parentSession));
+  return JSON.stringify(header) + (newline === -1 ? "" : content.slice(newline));
+}
+
+/**
+ * Copy the legacy agent folder into the new one, once. Never overwrites a
+ * file the new folder already has (the three JSON config files are merged
+ * instead), keeps modes and timestamps (the core orders sessions by them),
+ * skips lock files and our own extension folder (reinstalled at every
+ * launch), and writes MIGRATION_MARKER last: an interrupted copy resumes
+ * on the next start, a finished one never runs again.
+ *
+ * Returns { status: "migrated" | "already" | "none" | "failed", copied,
+ * merged, skipped, error? }.
+ */
+export function migrateAgentDir({ from, to, fsImpl = fs, pathImpl = path, now = () => new Date(), onStart } = {}) {
+  const result = { status: "none", copied: 0, merged: 0, skipped: 0 };
+  const marker = pathImpl.join(to, MIGRATION_MARKER);
+  if (fsImpl.existsSync(marker)) return { ...result, status: "already" };
+  try {
+    fsImpl.mkdirSync(to, { recursive: true });
+    let legacy = null;
+    try {
+      legacy = from && pathImpl.resolve(from) !== pathImpl.resolve(to) ? fsImpl.statSync(from) : null;
+    } catch {
+      legacy = null;
+    }
+    if (legacy?.isDirectory()) {
+      onStart?.();
+      copyTree(from, to, "");
+      result.status = "migrated";
+    }
+    const record = { version: 1, from: legacy?.isDirectory() ? from : null, at: now().toISOString(), copied: result.copied, merged: result.merged, skipped: result.skipped };
+    writeAtomic(fsImpl, marker, JSON.stringify(record, null, 2) + "\n");
+    return result;
+  } catch (error) {
+    return { ...result, status: "failed", error };
+  }
+
+  function copyTree(srcDir, destDir, rel) {
+    for (const entry of fsImpl.readdirSync(srcDir, { withFileTypes: true })) {
+      const name = entry.name;
+      const relPath = rel ? `${rel}/${name}` : name;
+      if (name === MIGRATION_MARKER || name.endsWith(".lock") || name.endsWith(".migrating")) continue;
+      if (relPath === "extensions/omnirush") continue;
+      const src = pathImpl.join(srcDir, name);
+      const dest = pathImpl.join(destDir, name);
+      const stat = fsImpl.lstatSync(src);
+      if (stat.isDirectory()) {
+        fsImpl.mkdirSync(dest, { recursive: true });
+        copyTree(src, dest, relPath);
+        continue;
+      }
+      const exists = (() => {
+        try {
+          fsImpl.lstatSync(dest);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      if (stat.isSymbolicLink()) {
+        if (exists) {
+          result.skipped++;
+          continue;
+        }
+        try {
+          fsImpl.symlinkSync(fsImpl.readlinkSync(src), dest);
+          result.copied++;
+        } catch {
+          result.skipped++; // e.g. Windows without symlink rights
+        }
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (exists) {
+        if (!rel && MERGED_JSON.has(name)) {
+          const older = readJson(fsImpl, src);
+          const newer = readJson(fsImpl, dest);
+          if (older && newer) {
+            const merged = mergeJson(name, older, newer);
+            if (JSON.stringify(merged) !== JSON.stringify(newer)) {
+              writeAtomic(fsImpl, dest, JSON.stringify(merged, null, 2) + "\n", fsImpl.statSync(dest).mode & 0o777);
+              result.merged++;
+              continue;
+            }
+          }
+        }
+        result.skipped++;
+        continue;
+      }
+      const tmp = `${dest}.${process.pid}.migrating`;
+      if (relPath.startsWith("sessions/") && name.endsWith(".jsonl")) {
+        const content = fsImpl.readFileSync(src, "utf8");
+        fsImpl.writeFileSync(tmp, rebaseSessionHeader(content, from, to, pathImpl));
+      } else {
+        fsImpl.copyFileSync(src, tmp);
+      }
+      try {
+        fsImpl.chmodSync(tmp, stat.mode & 0o777);
+      } catch {
+        /* modes are advisory on Windows */
+      }
+      fsImpl.utimesSync(tmp, stat.atime, stat.mtime);
+      fsImpl.renameSync(tmp, dest);
+      result.copied++;
+    }
+  }
+}
+
+/**
+ * The project config folder the core should read in `cwd`: .omnirush, or
+ * the legacy .pi when the project has one with settings or resources and
+ * no .omnirush yet (the launcher passes it as OMNIRUSH_PROJECT_CONFIG_DIR).
+ */
+export function projectConfigDirName(cwd, fsImpl = fs) {
+  try {
+    if (fsImpl.existsSync(path.join(cwd, PROJECT_CONFIG_DIR))) return PROJECT_CONFIG_DIR;
+    const legacy = path.join(cwd, LEGACY_PROJECT_CONFIG_DIR);
+    if (PROJECT_RESOURCES.some((entry) => fsImpl.existsSync(path.join(legacy, entry)))) return LEGACY_PROJECT_CONFIG_DIR;
+  } catch {
+    /* unreadable cwd: the default */
+  }
+  return PROJECT_CONFIG_DIR;
+}
+
+/**
+ * The core-facing variables for the OMNIRUSH_* spellings the user set:
+ * OMNIRUSH_<NAME> -> PI_<NAME> (the OMNIRUSH_ value wins over a PI_ one),
+ * and the pre-0.9 PI_CODING_AGENT_SESSION_DIR -> the OMNIRUSH_ name the
+ * rebranded core reads.
+ */
+export function engineEnvAliases(env = process.env) {
+  const out = {};
+  for (const name of ENGINE_ENV_NAMES) {
+    const value = env[`OMNIRUSH_${name}`];
+    if (value !== undefined && value !== "") out[`PI_${name}`] = value;
+  }
+  if (env.PI_CODING_AGENT_SESSION_DIR && !env.OMNIRUSH_CODING_AGENT_SESSION_DIR) {
+    out.OMNIRUSH_CODING_AGENT_SESSION_DIR = env.PI_CODING_AGENT_SESSION_DIR;
+  }
+  return out;
+}