@krtclcdy/tersio 2.22.1 → 2.24.0

package/README.md

@@ -1,6 +1,6 @@
 ![Banner](/assets/Banner.webp)
 
-# ✂️ Tersio — Token-saving OMP Add-ons
+# ✂️ Tersio — Token Saver OMP & Usage Tracker
 
 [![npm version](https://shieldcn.dev/npm/@krtclcdy%2Ftersio.svg?variant=branded&size=xs&logo=npm)](https://www.npmjs.com/package/@krtclcdy/tersio)
 [![node](https://shieldcn.dev/badge/node-%3E%3D20.12-22c55e.svg?variant=branded&size=xs&logo=nodedotjs)](https://nodejs.org)
@@ -8,29 +8,38 @@
 [![Build](https://shieldcn.dev/github/ci/KurutoDenzeru/tersio.svg?variant=branded&size=xs&logo=githubactions&label=Build)](https://github.com/KurutoDenzeru/tersio/actions)
 [![MIT](https://shieldcn.dev/badge/license-MIT-2563eb.svg?variant=branded&size=xs&logo=opensourceinitiative)](./LICENSE)
 
- Terse replies, compact shell output, and minimal code decisions for [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) — one-command combo presets.
+Token-saving add-ons for Oh My Pi and pi: terse caveman replies, compact
+RTK shell output, lean Ponytail code calls, usage tracking with a gain
+dashboard — one-command combo presets, one shared extension tree.
 
 ## ⚡ Getting Started
 
+All install paths in one table, with update and remove commands: [INSTALL.md](./INSTALL.md).
+
 **Default** (macOS/Linux/WSL) — one line. Installs the CLI via npm, then runs the main installer (scope + Combo preset menus) in the same pass:
 
 ```bash
 curl -fsSL https://github.com/KurutoDenzeru/tersio/releases/latest/download/install.sh | sh
 ```
 
-Prefer OMP-managed updates? Install as an OMP plugin instead:
+Then run the CLI. Bare `tersio` opens a menu and asks which agent to install into:
 
 ```bash
-omp plugin install @krtclcdy/tersio
+tersio                      # menu — picks Oh My Pi or pi
+tersio install --host pi    # pi, non-interactive
+tersio install --host omp   # Oh My Pi, non-interactive
 ```
 
-All modes load always. Only the updater stays toggleable:
+Or let the host install the package itself. Same result, host-managed updates:
 
 ```bash
-omp plugin features @krtclcdy/tersio --disable updater
+omp plugin install @krtclcdy/tersio
+pi install npm:@krtclcdy/tersio
 ```
 
-Then restart OMP and enable a preset:
+Both hosts load the same five extensions from the same sources, and both read their session-start defaults from `~/.tersio/settings.json`. All five load always.
+
+Then restart the agent and enable a preset:
 
 ```text
 /combo balanced
@@ -38,13 +47,7 @@ Then restart OMP and enable a preset:
 
 Individual toggles: `/caveman full` · `/rtk on` · `/ponytail full`. Everything starts off until you enable it.
 
-Session-start defaults (prompted during `install`, or flags):
-
-```bash
-tersio install --combo-default balanced --caveman-default lite --rtk-default on
-```
-
-Defaults apply to fresh sessions only — anything persisted with `/combo`, `/caveman`, or `/rtk` wins. Stored as plugin settings (`omp plugin config get @krtclcdy/tersio comboDefault`).
+When Tersio is installed through OMP, the first interactive launch asks for a session-start Combo preset once (`off`, `medium`, `balanced`, or `max`) and saves it as `comboDefault`. Running `tersio install` performs the same setup through the CLI.
 
 One-off use without installing:
 
@@ -54,30 +57,33 @@ npm exec --yes --prefer-online --package=@krtclcdy/tersio@latest -- tersio insta
 
 ### Requirements
 
-- [OMP](https://github.com/can1357/oh-my-pi)
+- [OMP](https://github.com/can1357/oh-my-pi) or [pi](https://github.com/earendil-works/pi)
 - Node.js 20.12+ with npm
 
 Windows/WSL have separate OMP homes — install from the environment where OMP runs. Inside WSL, `command -v npm` must resolve to a Linux path, not `/mnt/c/`.
 
 ## 📊 Benchmarks
 
-Measured savings against the same workload without the modes. Token counts are real `o200k_base` BPE tokens (js-tiktoken), not chars÷4 estimates. Sample protocol, per-sample data, and caveats in [BENCHMARK.md](./BENCHMARK.md).
+Every mode is measured against a base run with all modes off. Measured surfaces use different boundaries. Do not treat reply-text, code-output, and shell-output reductions as total bill savings. Full protocol and caveats are in [BENCHMARK.md](./BENCHMARK.md).
 
-| Measured surface (n) | Baseline → Tersio | Δ |
-|---|---|---|
-| Terse reply, caveman lite — BPE tok (3 samples, p50) | 173 → 69 tok | **−60.1%** |
-| Terse reply, caveman full — BPE tok (3 samples, p50) | 173 → 49 tok | **−71.7%** |
-| Terse reply, caveman ultra — BPE tok (3 samples, p50) | 173 → 25 tok | **−85.5%** |
-| Code diff, ponytail lite — BPE tok (2 tasks) | 326–462 → 57–121 tok | **−73.8…−82.5%** |
-| Code diff, ponytail full — BPE tok (2 tasks) | 326–462 → 55–88 tok | **−81.0…−83.1%** |
-| Code diff, ponytail ultra — BPE tok (2 tasks) | 326–462 → 40–88 tok | **−81.0…−87.7%** |
-| Shell output, rtk — `git status` — BPE tok | 182 → 72 tok | **−60.4%** |
-| Shell output, rtk — repo `grep` — BPE tok | 376 → 274 tok | **−27.1%** |
-| Shell output, rtk — `find` — BPE tok | 205 → 168 tok | **−18.0%** |
-| Shell output, rtk — `git diff` — BPE tok | 12,684 → 8,504 tok | **−33.0%** |
-| Shell output, rtk — `npm test` (passthrough) — BPE tok | 2,597 → 2,577 tok | **−0.8%** |
-
-Break-even math, balanced preset (caveman full + rtk + ponytail): a mixed turn costs 941 tok baseline vs 399 with Tersio (0.42×, **−57.6% per turn**). Overhead repays in turn 1 with the bundled floor (464 tok); turn 4 with the real installed Ponytail plugin (v4.9.0, 1,264 tok). RTK concentrates savings where noise lives — hook-wired sessions record **−97.5% on summarized test suites** (rtk `history.db`, 4 runs).
+| Mode | Surface (n) | Base → Tersio | Δ |
+|---|---|---|---|
+| `/caveman full` | Terse reply, o200k tokens (3 samples, p50) | 124 → 107 | **−13.7% reply text** |
+| `/caveman ultra` | Terse reply, o200k tokens (3 samples, p50) | 124 → 109 | **−12.1% reply text** |
+| `/ponytail lite` | Code reply, o200k tokens (3 samples, p50) | 306 → 177 | **−42.2% code** |
+| `/ponytail full` | Code reply, o200k tokens (3 samples, p50) | 306 → 208 | **−32.0% code** |
+| `/ponytail ultra` | Code reply, o200k tokens (3 samples, p50) | 306 → 112 | **−63.4% code** |
+| `/combo medium` | Code reply, o200k tokens (3 samples, p50) | 306 → 132 | **−56.9% code** |
+| `/rtk on` — `bun run test` | Command output (3 runs, p50) | 4,003 → 54 | **−98.7% output** |
+| `/rtk on` — `find . -name '*.test.ts'` | Command output (3 runs, p50) | 10,908 → 248 | **−97.7% output** |
+| `/rtk on` — `ls -la .` | Command output (3 runs, p50) | 983 → 275 | **−72.0% output** |
+| `/rtk on` — `git status` | Command output (3 runs, p50) | 72 → 18 | **−75.0% output** |
+| `/rtk on` — `bun run build` | Command output (3 runs, p50) | 140 → 114 | **−18.6% output** |
+
+Prompt overhead is included in [BENCHMARK.md](./BENCHMARK.md) with a full prompt-base example. Summary: `/rtk on` pays back immediately, `/ponytail ultra` repays in about 7 code tasks, `/combo medium` in about 8, and every Caveman level costs more in prompt than it saves in reply text.
+
+The Command tools dashboard reports weighted RTK command-output savings and OMP-specific adoption from executed Bash records. It does not estimate provider billing.
+Upstream Ponytail's fair agentic benchmark reports 54% less code, 22% fewer tokens, 20% lower cost, and 100% retained safety. RTK estimates command-output tokens, not bill savings. Caveman and Ponytail compliance varies by model. Measure your own sessions with `tersio usage` and the dashboard.
 
 ## 📈 Dashboard
 
@@ -106,12 +112,11 @@ Break-even math, balanced preset (caveman full + rtk + ponytail): a mixed turn c
 |---|---|
 | `tersio install` | Install (user scope: all OMP sessions) |
 | `tersio update` | Refresh the CLI, extensions, and add-ons (RTK binary, Caveman rule, Ponytail) |
-| `tersio reinstall` | Fresh install, preserving the Ponytail package |
 | `tersio doctor` | Check OMP, extension, Ponytail, and RTK health (`--fix` repairs, `--fix=<scope>` one scope, `--dry-run` previews) |
 | `tersio usage` | Ledger-backed usage + savings report |
 | `tersio dashboard` | Open the Dashboard (`--open`, `--export <file>`, `--port <n>`, `--currency <code>`; serves localhost only) |
 | `tersio reset` | Clear tersio statistics: usage ledger + a watermark that hides pre-reset rows from every derived view (Y/N confirm, `--dry-run`, `--yes`) — session transcripts and RTK history stay intact on disk |
-| `tersio uninstall` | Remove extensions, registration, and the Ponytail plugin (`--keep-ponytail` keeps Ponytail; `--remove-rtk` also removes the RTK binary and its `rtk.ts` OMP wiring) |
+| `tersio uninstall` | Remove extensions, registrations, the Ponytail plugin, and the `rtk.ts` OMP wiring (`--keep-ponytail` keeps Ponytail; `--remove-rtk` also removes the RTK binary) |
 | `tersio version` | Print version |
 
 Flags: `--dry-run`, `--yes`/`-y`, `--verbose`, `--combo-default`/`--caveman-default`/`--rtk-default`/`--ponytail-default`, `--currency <code>` (usage/dashboard display currency; flag wins, then the `tersio settings` default, then USD). Legacy `--doctor` / `--uninstall` forms still work.
@@ -123,9 +128,9 @@ Mode switches live on their own commands; bare `/tersio` prints status.
 | Command | Purpose |
 |---|---|
 | `/combo off\|medium\|balanced\|max\|status` | One preset for all three (start here): medium = lite/lite/on, balanced = full/full/on, max = ultra/ultra/on; per-mode tweaks drop to `custom`. |
-| `/caveman lite\|full\|ultra\|wenyan\|off\|status` | Terse replies (substance stays); `ultra` uses fragments only, `wenyan` a compressed classical-Chinese-inspired register. |
-| `/rtk on\|off\|status` | Compact shell output via the real `rtk` binary; exact bytes (checksums, patches) bypass it by policy. |
-| `/ponytail off\|lite\|full\|ultra\|review\|status` | Minimal code (YAGNI): `lite` nudges, `full` enforces, `ultra` challenges the requirement, `review` audits for over-engineering (upstream command). |
+| `/caveman lite\|full\|ultra\|wenyan-lite\|wenyan-full\|wenyan-ultra\|off\|status` | Terse replies with upstream-aligned Caveman levels. Legacy `wenyan` restores as `wenyan-full`. |
+| `/rtk on\|off\|status` | Controls RTK session guidance, `rtk_run`, and the automatic hook through shared `RTK_DISABLED` state. Exact bytes bypass RTK. |
+| `/ponytail off\|lite\|full\|ultra\|status` | Minimal code using upstream Ponytail modes. Review runs separately through `/ponytail-review`. |
 | `/tersio status` | Active modes + combo level; state persists, propagates to subagents, and lights the Combo footer indicator. |
 | `/tersio check` | Add-on version check |
 | `/tersio update <ponytail\|rtk\|caveman\|all> [--dry-run]` | Update add-ons, preview with dry-run |
@@ -136,25 +141,36 @@ Mode switches live on their own commands; bare `/tersio` prints status.
 
 ## 🗂️ Files and backups
 
+Shared, and identical for every host:
+
 | What | Path |
 |---|---|
-| Caveman / RTK / Updater / Combo extensions | `~/.omp/agent/extensions/{caveman-session,rtk-session,ai-addons-updater,combo-toggle}/` |
-| RTK OMP wiring (rtk-owned) | `~/.omp/agent/extensions/rtk.ts` — written by the installer via `rtk init -g --agent omp`; auto-loads, no config entry |
-| Ponytail package (bundled tersio dependency — one Plugins row, updates with `tersio update`) | `~/.omp/plugins/node_modules/@dietrichgebert/ponytail/` |
-| RTK binary | `~/.bun/bin/rtk` (`rtk.exe` on Windows) |
-| Extension registrations | `~/.omp/agent/config.yml` |
+| Session-start defaults | `~/.tersio/settings.json` — combo, caveman, rtk, ponytail, and the display currency |
+| RTK binary | `~/.bun/bin/rtk` (`rtk.exe` on Windows). The runtime resolves `PATH` first, then this managed path. |
+| Usage ledger and price cache | `~/.tersio/` — local only, nothing leaves the machine |
+
+Per host, written by `tersio install --host <omp|pi>`:
 
-The installer writes `<file>.bak` before replacing an extension source; the updater keeps `rtk.bak` / `rule.md.bak` and restores them if the replacement fails validation.
+| Host | Extensions | Ponytail |
+|---|---|---|
+| Oh My Pi | `~/.omp/agent/extensions/{caveman-session,rtk-session,combo-toggle,tersio-commands,ai-addons-updater}/` | nested plugin dependency under `~/.omp/plugins/node_modules/`, one Plugins row |
+| pi | `~/.pi/agent/extensions/{caveman-session,rtk-session,combo-toggle,tersio-commands,ai-addons-updater}/` — pi auto-discovers `<agent-dir>/extensions`, so there is nothing to register | `npm:@dietrichgebert/ponytail`, installed as a pi package |
+
+Both hosts carry the same `shared/` and `lib/` modules beside those directories, and both load the same five extensions from the same sources.
 
-User-level installs also register the package in `~/.omp/plugins` (visible in OMP **Settings → Plugins**), directly through the plugin manifest. Active modes reassert after Ponytail's prompt block on every top-level turn, including after history compaction.
+The installer writes `<file>.bak` before replacing an extension source; the updater keeps `rtk.bak` / `rule.md.bak` and restores them if the replacement fails validation. `tersio doctor --fix extensions` restores a damaged tree, and `doctor --fix registrations` drops retired or duplicate `config.yml` entries.
+
+An OMP install also registers the package in `~/.omp/plugins`, so it shows under OMP **Settings → Plugins**. Active modes reassert after Ponytail's prompt block on every top-level turn, including after history compaction.
 
 ## 🛠️ Troubleshooting
 
-**Ponytail or Combo command missing:** run `tersio reinstall` in OMP's environment, restart OMP, then `tersio doctor` (repairs `config.yml` registrations).
+**Ponytail or Combo command missing on OMP:** confirm `~/.omp/plugins/package.json` lists `@krtclcdy/tersio`, then run `tersio install`, restart OMP, and check `tersio doctor`. A damaged tree is repaired by `tersio doctor --fix extensions`.
+
+**Commands missing on pi:** check the `Hosts` section of `tersio doctor` — it reports whether pi is installed and where. Then run `tersio install --host pi` and restart pi.
 
-**RTK missing or not executable:** run `tersio reinstall`, then `tersio doctor`. On Linux/macOS: `chmod +x ~/.bun/bin/rtk`.
+**RTK missing or not executable:** run `tersio install`, then `tersio doctor`. On Linux/macOS: `chmod +x ~/.bun/bin/rtk`.
 
-**RTK commands not metered in the Dashboard:** check `tersio doctor` — the `RTK OMP wiring (rtk.ts)` row must be ok. Missing: run `rtk init -g --agent omp` (needs rtk ≥ 0.49) and restart OMP. Native tool calls (`read`/`edit`/`eval`) stay unmetered — only bash tool calls pass through rtk.
+**RTK commands not metered in the Dashboard:** only bash calls routed through rtk's OMP wiring (`~/.omp/agent/extensions/rtk.ts`, written by `rtk init -g --agent omp`) are metered. Missing: run that command (needs rtk ≥ 0.49) or `tersio doctor --fix rtk`, then restart OMP. Native tool calls (`read`/`edit`/`eval`) stay unmetered.
 
 **Checksum warning or failure:** the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; `/tersio update rtk` aborts when metadata is missing.
 

package/cli/agent-hosts.js

@@ -0,0 +1,42 @@
+// The host registry: one entry per agent, carrying only what the CLI needs to find it, install it and undo it.
+// How the shell rewrite reaches the model. Every host routes it through rtk's own module (`rtk init -g --agent <id>`), so...
+export const REWRITE_WIRING = 'rtk extension · auto-rewrite';
+const HOSTS = [
+    {
+        id: 'omp',
+        label: 'Oh My Pi (OMP)',
+        autoDetect: false,
+        configDir: '.omp',
+        binaries: ['omp'],
+        // Earlier versions wrote these. The tree injects the modes every turn, so a skill is a second copy and a rules file is...
+        retired: [
+            { path: '.omp/agent/AGENTS.md', kind: 'merged' },
+            { path: '.omp/agent/skills/tersio-caveman', kind: 'ours' },
+            { path: '.omp/agent/skills/tersio-ponytail', kind: 'ours' },
+            { path: '.omp/agent/skills/tersio-rtk', kind: 'ours' },
+        ],
+        caveats: 'Reference host. The modes are injected by the extension tree in ~/.omp/agent/extensions, so no static copy is written and the rewrite is rtk\'s own module (rtk init -g --agent omp).',
+        source: 'https://omp.sh/docs/context-files',
+        nativeInstall: { command: 'omp install @krtclcdy/tersio', note: 'or let `tersio install` write the layer for you' },
+    },
+    {
+        id: 'pi',
+        label: 'Pi',
+        configDir: '.pi/agent',
+        configDirEnv: 'PI_CODING_AGENT_DIR',
+        binaries: ['pi'],
+        retired: [
+            { path: '.pi/agent/AGENTS.md', kind: 'merged' },
+            { path: '.pi/agent/skills/tersio-caveman', kind: 'ours' },
+            { path: '.pi/agent/skills/tersio-ponytail', kind: 'ours' },
+            { path: '.pi/agent/skills/tersio-rtk', kind: 'ours' },
+        ],
+        caveats: 'AGENTS.override.md replaces rather than merges. Never write SYSTEM.md — it replaces the default system prompt outright. The rewrite is rtk\'s own module, written by `rtk init -g --agent pi`; rtk owns that format, so no tersio release is needed when it changes.',
+        source: 'https://pi.dev/docs/latest/extensions',
+        nativeInstall: { command: 'pi install npm:@krtclcdy/tersio', note: 'declares the `pi` manifest in package.json' },
+    },
+];
+function byId(id) {
+    return HOSTS.find((h) => h.id === id);
+}
+export { HOSTS, byId };

package/cli/agents.js

@@ -0,0 +1,266 @@
+// Host selection, persistence, and the filesystem side of asking what a host has on disk.
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { HOSTS, REWRITE_WIRING } from './agent-hosts.js';
+import { reportOmpLayer } from './omp-layer.js';
+import { reportPiLayer } from './pi-layer.js';
+const SELECTION_FILE = 'agents.json';
+// Marker pair for the one file we still merge into: a user's own AGENTS.md.
+const START = '<!-- tersio:start -->';
+const END = '<!-- tersio:end -->';
+function selectionPath(home) {
+    return path.join(home, '.tersio', SELECTION_FILE);
+}
+// Host ids only, in registry order, de-duplicated, unknown ids dropped.
+export function normalizeIds(ids) {
+    const wanted = new Set(ids);
+    return HOSTS.filter((h) => wanted.has(h.id)).map((h) => h.id);
+}
+// `$HOME`-relative form of a path, for previews that must stay readable.
+export function displayPath(target, home) {
+    if (!home)
+        return target;
+    const prefix = home.endsWith(path.sep) ? home : `${home}${path.sep}`;
+    if (!target.startsWith(prefix))
+        return target;
+    return `~/${target.slice(prefix.length).split(path.sep).join('/')}`;
+}
+// The install marker goes in the *label*: clack renders hints on the cursor row only.
+export function agentChoices(state) {
+    return HOSTS.map((host) => {
+        const info = state?.get(host.id);
+        if (!info) {
+            return {
+                value: host.id,
+                label: host.id === 'omp' ? `${host.label} (extensions + Ponytail)` : host.label,
+                hint: REWRITE_WIRING,
+            };
+        }
+        const mark = info.installed ? 'installed' : 'not installed';
+        const size = info.dirs > 0 ? `${info.dirs} dir${info.dirs === 1 ? '' : 's'}` : 'nothing';
+        return { value: host.id, label: `${host.label} — ${size} · ${mark}`, hint: REWRITE_WIRING };
+    });
+}
+// An uninstall row for a host with nothing of ours answers a question nobody asked.
+export function installedRows(state) {
+    return agentChoices(state).filter((choice) => state.get(choice.value)?.installed !== false);
+}
+// True when the path is a directory. The layer's artifacts are directories.
+function isDir(target) {
+    try {
+        return fsSync.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// Reads one host's layer off the filesystem.
+export function hostLayer(host, home) {
+    if (host.id === 'omp') {
+        const report = reportOmpLayer(home, isDir);
+        return {
+            extDir: path.join(home, '.omp', 'agent', 'extensions'),
+            plugin: report.pluginPath,
+            present: report.extensions,
+            missing: report.missing,
+            installed: report.installed,
+        };
+    }
+    const report = reportPiLayer(home, isDir);
+    return {
+        extDir: path.join(home, '.pi', 'agent', 'extensions'),
+        plugin: null,
+        present: report.extensions,
+        missing: report.missing,
+        installed: report.installed,
+    };
+}
+// Both menus seed from the disk, not from the saved selection.
+export function installedState(home) {
+    const state = new Map();
+    for (const host of HOSTS) {
+        const layer = hostLayer(host, home);
+        // A partial tree is a partial install; omp's row also needs its plugin registration, which can be pruned while the...
+        state.set(host.id, {
+            dirs: layer.present.length,
+            installed: layer.installed && layer.present.length > 0,
+        });
+    }
+    return state;
+}
+// Host ids tersio has already installed something for.
+export function installedHostIds(state) {
+    return normalizeIds([...state].filter(([, info]) => info.installed).map(([id]) => id));
+}
+// An explicit `--agent` wins outright, even for a host not installed.
+export async function resolveAgentSelection(opts) {
+    const fromFlag = normalizeIds(opts.flag ?? []);
+    if (fromFlag.length > 0) {
+        return { ids: fromFlag, source: 'flag', addedByDetection: [] };
+    }
+    const stored = normalizeIds(opts.stored);
+    const detected = normalizeIds(opts.detected);
+    const union = normalizeIds([...stored, ...detected]);
+    const addedByDetection = union.filter((id) => !stored.includes(id));
+    if (opts.ask) {
+        const answer = await opts.ask();
+        if (answer !== null) {
+            return { ids: normalizeIds(answer), source: 'prompt', addedByDetection };
+        }
+    }
+    return { ids: union, source: union.length > 0 ? 'auto' : 'none', addedByDetection };
+}
+export function readSelection(home) {
+    try {
+        const raw = fsSync.readFileSync(selectionPath(home), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object')
+            return { hosts: [], updatedAt: 0 };
+        const record = parsed;
+        const hosts = Array.isArray(record.hosts) ? record.hosts.filter((h) => typeof h === 'string') : [];
+        const updatedAt = typeof record.updatedAt === 'number' ? record.updatedAt : 0;
+        return { hosts: normalizeIds(hosts), updatedAt };
+    }
+    catch {
+        return { hosts: [], updatedAt: 0 };
+    }
+}
+export function writeSelection(home, ids) {
+    const target = selectionPath(home);
+    fsSync.mkdirSync(path.dirname(target), { recursive: true });
+    const payload = { hosts: normalizeIds(ids), updatedAt: Date.now() };
+    fsSync.writeFileSync(target, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+// A config dir, or a binary on PATH. Detection only widens the default set.
+export function detectHosts(home, env = process.env) {
+    const found = [];
+    for (const host of HOSTS) {
+        if (host.autoDetect === false)
+            continue;
+        const dir = path.join(home, host.configDir);
+        if (isDir(dir)) {
+            found.push(host.id);
+            continue;
+        }
+        const relocated = host.configDirEnv ? env[host.configDirEnv] : undefined;
+        const onPath = relocated && relocated.trim() !== ''
+            ? false
+            : host.binaries.some((b) => hasBinary(b, env));
+        if (onPath)
+            found.push(host.id);
+    }
+    return found;
+}
+// A host's binary on PATH, or null. Shared with the dashboard.
+export function findHostBinary(host, env = process.env) {
+    if (process.platform === 'win32') {
+        const relocated = host.configDirEnv ? env[host.configDirEnv] : undefined;
+        if (relocated && relocated.trim() !== '')
+            return null;
+    }
+    const raw = env.PATH ?? env.Path ?? env.path ?? '';
+    if (!raw)
+        return null;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const binary of host.binaries) {
+        if (process.platform === 'win32' && binary === 'cmd')
+            continue;
+        for (const dir of raw.split(sep)) {
+            if (!dir)
+                continue;
+            for (const ext of exts) {
+                const candidate = path.join(dir, binary + ext);
+                try {
+                    if (fsSync.statSync(candidate).isFile())
+                        return candidate;
+                }
+                catch { /* keep looking */ }
+            }
+        }
+    }
+    return null;
+}
+function hasBinary(name, env) {
+    // A bare `cmd` resolves to the system shell on Windows.
+    if (process.platform === 'win32' && name === 'cmd')
+        return false;
+    const raw = env.PATH ?? env.Path ?? env.path ?? '';
+    if (!raw)
+        return false;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const dir of raw.split(sep)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            try {
+                if (fsSync.statSync(path.join(dir, name + ext)).isFile())
+                    return true;
+            }
+            catch { /* keep looking */ }
+        }
+    }
+    return false;
+}
+// Paths an earlier version wrote and this one no longer does. `ours` is removed outright;
+export function clearRetiredPaths(host, home, options = {}) {
+    const removed = [];
+    for (const entry of host.retired ?? []) {
+        const target = path.join(home, entry.path);
+        if (entry.kind === 'merged') {
+            let current = null;
+            try {
+                current = fsSync.readFileSync(target, 'utf8');
+            }
+            catch {
+                current = null;
+            }
+            if (current === null)
+                continue;
+            const stripped = removeMarkedBlock(current);
+            if (stripped === current)
+                continue;
+            if (!options.dryRun) {
+                if (stripped === null)
+                    fsSync.rmSync(target, { force: true });
+                else
+                    fsSync.writeFileSync(target, stripped, 'utf8');
+            }
+            removed.push(target);
+            continue;
+        }
+        if (!isDir(target) && !existsSyncSafe(target))
+            continue;
+        if (!options.dryRun) {
+            try {
+                fsSync.rmSync(target, { recursive: true, force: true });
+            }
+            catch {
+                continue;
+            }
+        }
+        removed.push(target);
+    }
+    return removed;
+}
+// Removes the marked block and the blank line it introduced. Null when nothing is left.
+function removeMarkedBlock(existing) {
+    const from = existing.indexOf(START);
+    const to = existing.indexOf(END);
+    if (from === -1 || to === -1 || to <= from)
+        return existing;
+    const before = existing.slice(0, from).replace(/\n+$/, '\n');
+    const after = existing.slice(to + END.length).replace(/^\n+/, '');
+    const merged = `${before}${after}`;
+    return merged.trim() ? merged : null;
+}
+function existsSyncSafe(p) {
+    try {
+        return fsSync.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+export { selectionPath };