@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/platform/posixpath.js

@@ -1,38 +1,10 @@
-/**
- * POSIX login-PATH primitives for making the `agents` command resolvable.
- *
- * The Unix analog of winpath.ts. `agents`/`ag` land on PATH only via npm's
- * bin symlink into the npm global-bin dir; under nvm (and other per-user node
- * prefixes) that dir is absent from a *non-interactive login* shell's PATH, so
- * `bash -lc 'agents …'` fails with command-not-found. That breaks every
- * consumer that drives a login shell on the box: `agents secrets export --device`
- * (which runs `bash -lc 'agents secrets import …'` on the remote) and the
- * routines daemon (`src/lib/daemon/daemon.ts`, which falls back to bare `agents`).
- *
- * The fix mirrors the Windows postinstall branch (which registers npm's
- * global-bin dir on the user PATH): symlink the entrypoint into ~/.local/bin —
- * the XDG user-bin dir that mainstream distros auto-add to the login PATH when
- * it exists (Debian/Ubuntu via ~/.profile, Fedora via /etc/profile.d) — and,
- * where it is not yet on PATH, the caller adds it.
- *
- * Leaf module — imports only child_process / fs / os / path so it is cheap to
- * load from the npm lifecycle script without pulling the rest of the CLI.
- */
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-/** The XDG user-bin dir, `~/.local/bin`. */
 export function localBinDir(home = os.homedir()) {
     return path.join(home, '.local', 'bin');
 }
-/**
- * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
- * pre-existing real file or a symlink that already points elsewhere — most
- * importantly a developer's `scripts/install.sh` dev build at
- * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
- * `target`, is created/treated as ok. Idempotent.
- */
 export function ensureLocalBinSymlink(name, target, dir = localBinDir()) {
     const linkPath = path.join(dir, name);
     const want = path.resolve(target);
@@ -43,35 +15,22 @@ export function ensureLocalBinSymlink(name, target, dir = localBinDir()) {
     catch (err) {
         const code = err.code;
         if (code === 'EINVAL') {
-            // The path exists but is not a symlink — a real file/dir. Never clobber.
             return { ok: false, created: false, skippedReason: 'a non-symlink file already exists here', path: linkPath };
         }
         if (code !== 'ENOENT') {
             return { ok: false, created: false, skippedReason: err.message, path: linkPath };
         }
-        // ENOENT — nothing there; fall through to create.
     }
     if (current !== null) {
         const resolved = path.isAbsolute(current) ? current : path.resolve(dir, current);
         if (resolved === want)
             return { ok: true, created: false, path: linkPath };
-        // Points somewhere else (e.g. a dev build) — the existing link wins.
         return { ok: false, created: false, skippedReason: `symlink already points to ${current}`, path: linkPath };
     }
     fs.mkdirSync(dir, { recursive: true });
     fs.symlinkSync(target, linkPath);
     return { ok: true, created: true, path: linkPath };
 }
-/**
- * Absolute path to `bash`. We probe bash specifically — NOT the user's $SHELL —
- * because the consumers we are healing run `bash -lc` regardless of login shell:
- * `secrets export --device` builds `bash -lc 'agents secrets import …'` for the
- * remote, and the routines daemon resolves `agents` the same way. On a box whose
- * login shell is zsh, zsh's login PATH may lack ~/.local/bin while bash's
- * includes it (Debian/Ubuntu ~/.profile) — so probing $SHELL would give the
- * wrong answer for what the consumer actually sees. Resolve from the *current*
- * PATH (the install process has one) and fall back to /bin/bash.
- */
 function bashPath() {
     const found = (process.env.PATH || '')
         .split(path.delimiter)
@@ -89,20 +48,6 @@ function bashPath() {
     });
     return found || '/bin/bash';
 }
-/**
- * Environment for the probe shell that reproduces a *fresh* `bash -lc` — the
- * PATH that `ssh host 'bash -lc …'` and the routines daemon actually get — and
- * NOT the nvm/npm-augmented PATH of the install process.
- *
- * This is the crux: `npm i -g` (and a dev `bun run`) execute under nvm, so the
- * caller's PATH already contains nvm's bin. A spawned shell inherits that PATH,
- * so it would resolve `agents` and the heal would skip — during the very nvm
- * install it exists to fix. We strip PATH (and nvm's hint vars) so the login
- * profile rebuilds PATH from scratch, exactly as an incoming SSH command shell
- * does. Login bash still sources /etc/profile + ~/.profile (which adds
- * ~/.local/bin) but bails out of ~/.bashrc's nvm block early because it is
- * non-interactive — which is precisely why bare `agents` is missing there.
- */
 function loginProbeEnv() {
     const env = { ...process.env };
     delete env.PATH;
@@ -113,12 +58,6 @@ function loginProbeEnv() {
             delete env[k];
     return env;
 }
-/**
- * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
- * for the consumers we heal. Best-effort: any probe failure returns false so
- * the caller heals rather than wrongly assuming success. `command -v` is a
- * POSIX builtin.
- */
 export function loginShellResolves(cmd) {
     try {
         const res = spawnSync(bashPath(), ['-lc', `command -v ${cmd}`], {
@@ -133,7 +72,6 @@ export function loginShellResolves(cmd) {
         return false;
     }
 }
-/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
 export function dirOnLoginPath(dir) {
     try {
         const res = spawnSync(bashPath(), ['-lc', 'printf %s "$PATH"'], {

package/dist/lib/platform/process.d.ts

@@ -1,38 +1,4 @@
-/**
- * Forcefully terminate a process AND its descendant tree.
- *
- * Windows: `taskkill /F /T /PID` — the only reliable way to take down the whole
- * tree (a bare TerminateProcess leaves children orphaned, which is exactly the
- * "stop reported success but the tree is still alive" bug). POSIX: SIGKILL to the
- * pid (matching the existing hard-kill behavior; callers that own a process group
- * can pass the negative pid). Best-effort — never throws; an already-exited
- * process counts as success.
- */
 export declare function killTree(pid: number): void;
-/**
- * Spawn options for a long-lived background child (daemon, detached worker,
- * sidecar server, fire-and-forget job).
- *
- * POSIX: `detached: true` — the child leads its own process group, so it
- * survives the parent and group kills (`kill(-pid)`) still reach it.
- *
- * Windows: the child must not share the launcher's console (a console-close
- * event when the launcher exits would tear it down, #556) and must not flash
- * a window. How to get there depends on the child's stdio:
- *
- * - All stdio non-inherited ('ignore'/'pipe'): `windowsHide: true`, NOT
- *   detached. CREATE_NO_WINDOW gives the child its own hidden console that
- *   every console-subsystem descendant (powershell, git, a .cmd shim's cmd.exe
- *   wrapper) inherits — no window anywhere down the tree. `detached` would
- *   defeat it: DETACHED_PROCESS makes CreateProcess ignore CREATE_NO_WINDOW.
- *
- * - Any stdio slot redirected to an fd (log files — `fdStdio: true`): libuv
- *   skips CREATE_NO_WINDOW whenever a stdio fd is inherited, so windowsHide
- *   cannot engage and a non-detached child would share the launcher's console
- *   and die with it. Keep DETACHED_PROCESS: the child runs console-less and
- *   windowless; its console-tool spawns stay invisible because the leaf call
- *   sites pass their own `windowsHide` with piped stdio.
- */
 export declare function backgroundSpawnOptions(opts?: {
     cwd?: string;
     fdStdio?: boolean;
@@ -42,42 +8,9 @@ export declare function backgroundSpawnOptions(opts?: {
     detached: boolean;
     windowsHide: boolean;
 };
-/**
- * Whether `pid` has stopped serving — dead, or a ZOMBIE awaiting reap.
- *
- * `isAlive` is a bare `kill(pid, 0)`, which succeeds for a zombie. That matters
- * here because {@link waitForExit} blocks the event loop, so a daemon that is
- * this process's own child can never be reaped while we wait: it would read as
- * alive for the entire timeout and then be hard-killed after it had already
- * exited. A zombie holds no socket and serves no request, so for stop purposes
- * it has exited.
- */
 export declare function hasExited(pid: number): boolean;
-/**
- * Block until `pid` stops serving or `timeoutMs` elapses. Synchronous on purpose:
- * the callers are short-lived CLI/postinstall processes that exit before any
- * async timer would fire, which is exactly how a SIGTERMed daemon used to outlive
- * the `stopDaemon()` that was supposed to have reaped it. Returns true if it is
- * gone.
- */
 export declare function waitForExit(pid: number, timeoutMs: number): boolean;
 export declare function isAlive(pid: number): boolean;
-/**
- * A stable identifier for the process at `pid` as of when it started, or null if
- * unknowable. Used to defeat PID reuse: acting on a pid is only safe when the
- * process still occupies the slot we observed earlier. The value is only ever
- * compared for equality against an earlier capture of the SAME pid, so the format
- * need only be stable, not parseable.
- *
- * Linux:   field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:   `ps -o lstart= -p <pid>`.
- * Windows: CreationDate from Win32_Process, as a culture-independent FILETIME.
- *
- * This is the single source of truth. `pty-server.ts` and `teams/agents.ts` each
- * carried their own copy; the Windows branch was missing from both, so every
- * caller there silently ran with NO pid-reuse protection — including
- * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
- */
 export declare function captureProcessStartTime(pid: number, opts?: {
     fresh?: boolean;
 }): string | null;

package/dist/lib/platform/process.js

@@ -1,20 +1,7 @@
-/**
- * Process liveness / control, platform-aware.
- */
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
 import * as os from 'os';
 import { sleepSync } from '../fs-atomic.js';
-/**
- * Forcefully terminate a process AND its descendant tree.
- *
- * Windows: `taskkill /F /T /PID` — the only reliable way to take down the whole
- * tree (a bare TerminateProcess leaves children orphaned, which is exactly the
- * "stop reported success but the tree is still alive" bug). POSIX: SIGKILL to the
- * pid (matching the existing hard-kill behavior; callers that own a process group
- * can pass the negative pid). Best-effort — never throws; an already-exited
- * process counts as success.
- */
 export function killTree(pid) {
     if (!pid || pid <= 0)
         return;
@@ -22,39 +9,15 @@ export function killTree(pid) {
         try {
             execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
         }
-        catch { /* already gone, or no such pid */ }
+        catch { }
     }
     else {
         try {
             process.kill(pid, 'SIGKILL');
         }
-        catch { /* already gone */ }
+        catch { }
     }
 }
-/**
- * Spawn options for a long-lived background child (daemon, detached worker,
- * sidecar server, fire-and-forget job).
- *
- * POSIX: `detached: true` — the child leads its own process group, so it
- * survives the parent and group kills (`kill(-pid)`) still reach it.
- *
- * Windows: the child must not share the launcher's console (a console-close
- * event when the launcher exits would tear it down, #556) and must not flash
- * a window. How to get there depends on the child's stdio:
- *
- * - All stdio non-inherited ('ignore'/'pipe'): `windowsHide: true`, NOT
- *   detached. CREATE_NO_WINDOW gives the child its own hidden console that
- *   every console-subsystem descendant (powershell, git, a .cmd shim's cmd.exe
- *   wrapper) inherits — no window anywhere down the tree. `detached` would
- *   defeat it: DETACHED_PROCESS makes CreateProcess ignore CREATE_NO_WINDOW.
- *
- * - Any stdio slot redirected to an fd (log files — `fdStdio: true`): libuv
- *   skips CREATE_NO_WINDOW whenever a stdio fd is inherited, so windowsHide
- *   cannot engage and a non-detached child would share the launcher's console
- *   and die with it. Keep DETACHED_PROCESS: the child runs console-less and
- *   windowless; its console-tool spawns stay invisible because the leaf call
- *   sites pass their own `windowsHide` with piped stdio.
- */
 export function backgroundSpawnOptions(opts = {}) {
     const platform = opts.platform ?? process.platform;
     const cwd = opts.cwd ?? os.homedir();
@@ -65,57 +28,26 @@ export function backgroundSpawnOptions(opts = {}) {
     }
     return { cwd, detached: true, windowsHide: false };
 }
-/**
- * Is a process with this PID currently alive?
- *
- * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
- * it maps to OpenProcess). Returns false on any error (no such process, or no
- * permission to signal it), matching the long-standing call sites that treat a
- * throw from `process.kill(pid, 0)` as "not running".
- */
-/** Poll interval while waiting for a pid to disappear. */
 const EXIT_POLL_MS = 50;
-/**
- * Whether `pid` has stopped serving — dead, or a ZOMBIE awaiting reap.
- *
- * `isAlive` is a bare `kill(pid, 0)`, which succeeds for a zombie. That matters
- * here because {@link waitForExit} blocks the event loop, so a daemon that is
- * this process's own child can never be reaped while we wait: it would read as
- * alive for the entire timeout and then be hard-killed after it had already
- * exited. A zombie holds no socket and serves no request, so for stop purposes
- * it has exited.
- */
 export function hasExited(pid) {
     if (!isAlive(pid))
         return true;
     if (process.platform === 'win32')
-        return false; // no zombie state to unwrap
+        return false;
     try {
         const state = execFileSync('ps', ['-o', 'state=', '-p', String(pid)], { encoding: 'utf-8' }).trim();
         return state.startsWith('Z');
     }
     catch (err) {
-        // `ps` exiting non-zero because the pid is unknown means gone. Any OTHER
-        // failure (ps missing from PATH, a permission error) is NOT evidence of
-        // death, and isAlive already said this pid is live — so fail CLOSED and keep
-        // treating it as alive. Failing open here would clear the pid file under a
-        // running daemon and recreate this very bug through a different door.
         if (err?.code === 'ENOENT' && err?.syscall === 'spawnSync ps')
             return false;
         const out = String(err?.stdout ?? '').trim();
         const errOut = String(err?.stderr ?? '').trim();
         if (err?.status === 1 && out === '' && errOut === '')
-            return true; // no such pid
+            return true;
         return false;
     }
 }
-/**
- * Block until `pid` stops serving or `timeoutMs` elapses. Synchronous on purpose:
- * the callers are short-lived CLI/postinstall processes that exit before any
- * async timer would fire, which is exactly how a SIGTERMed daemon used to outlive
- * the `stopDaemon()` that was supposed to have reaped it. Returns true if it is
- * gone.
- */
 export function waitForExit(pid, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
@@ -123,7 +55,7 @@ export function waitForExit(pid, timeoutMs) {
             return true;
         if (Date.now() >= deadline)
             return false;
-        sleepSync(EXIT_POLL_MS); // blocks this thread outright; no busy-loop
+        sleepSync(EXIT_POLL_MS);
     }
 }
 export function isAlive(pid) {
@@ -137,27 +69,7 @@ export function isAlive(pid) {
         return false;
     }
 }
-/** Memoized per pid: a process's start time cannot change while it lives, and a
- *  recycled pid is precisely what the caller is trying to detect — so a stale
- *  hit still compares unequal against the recorded value. Bounded by the pids a
- *  single CLI invocation asks about. */
 const startTimeByPid = new Map();
-/**
- * A stable identifier for the process at `pid` as of when it started, or null if
- * unknowable. Used to defeat PID reuse: acting on a pid is only safe when the
- * process still occupies the slot we observed earlier. The value is only ever
- * compared for equality against an earlier capture of the SAME pid, so the format
- * need only be stable, not parseable.
- *
- * Linux:   field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:   `ps -o lstart= -p <pid>`.
- * Windows: CreationDate from Win32_Process, as a culture-independent FILETIME.
- *
- * This is the single source of truth. `pty-server.ts` and `teams/agents.ts` each
- * carried their own copy; the Windows branch was missing from both, so every
- * caller there silently ran with NO pid-reuse protection — including
- * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
- */
 export function captureProcessStartTime(pid, opts = {}) {
     if (!Number.isInteger(pid) || pid <= 0)
         return null;
@@ -171,9 +83,6 @@ export function captureProcessStartTime(pid, opts = {}) {
 function readProcessStartTime(pid) {
     try {
         if (process.platform === 'win32') {
-            // ToFileTimeUtc() rather than the raw DateTime: the default string form is
-            // rendered in the current culture, so a persisted fingerprint would stop
-            // comparing equal across a locale change.
             const out = execFileSync('powershell.exe', [
                 '-NoProfile',
                 '-NonInteractive',
@@ -185,13 +94,10 @@ function readProcessStartTime(pid) {
         }
         if (process.platform === 'linux') {
             const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
-            // The comm field (#2) is parenthesized and may contain spaces, so split
-            // off everything after the last ')' to get a clean field list.
             const lastParen = stat.lastIndexOf(')');
             if (lastParen < 0)
                 return null;
             const fields = stat.slice(lastParen + 2).split(' ');
-            // After comm we are at field 3; starttime is field 22, so index 19 here.
             return fields[19] || null;
         }
         const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {

package/dist/lib/platform/winpath.d.ts

@@ -1,65 +1,15 @@
 interface WinPathResult {
     success: boolean;
-    /** True when `dir` was already the first PATH entry (no write performed). */
     alreadyPresent?: boolean;
     error?: string;
 }
-/**
- * Compute the new User PATH from the RAW (unexpanded) current value. Pure and
- * OS-independent — the single source of truth for the prepend/dedup logic.
- *
- * Idempotent: returns `{ changed: false }` (value unchanged, verbatim) when
- * `dir` is already the first `;`-split entry. Otherwise removes every existing
- * occurrence of `dir` and prepends it, dropping empty segments — matching POSIX
- * `export PATH="${dir}:$PATH"`. `%VAR%` segments are preserved verbatim (never
- * expanded), which is the #308 regression this fix targets.
- */
 export declare function computeNewUserPath(currentRaw: string, dir: string): {
     changed: boolean;
     value: string;
 };
-/**
- * Decide whether to write the User PATH back as REG_EXPAND_SZ (ExpandString) vs
- * REG_SZ (String). Pure — testable on any host.
- *
- * True (expandable) when the original value was already ExpandString, when the
- * raw value contains a `%VAR%` reference, or when `Path` was absent (default to
- * ExpandString — Windows' native Path type). Only a plain String value with no
- * `%` stays REG_SZ. `originalKind` is the .NET RegistryValueKind name
- * (`ExpandString`/`String`/…) or `null`/`Absent` when `Path` had no value.
- */
 export declare function shouldWriteExpandable(originalKind: string | null, rawValue: string): boolean;
-/**
- * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
- * already first; moves it to the front when it exists but is positioned later
- * (e.g. appended by an older install) so it overrides conflicting entries.
- *
- * Reads the RAW registry value (preserving `%VAR%` and the REG_EXPAND_SZ type),
- * computes the new value in TS via `computeNewUserPath`, and only writes when
- * the value actually changes — preserving the original value type and
- * broadcasting WM_SETTINGCHANGE. `dir` and the computed value are passed via env
- * vars so they are never interpolated into the script text.
- */
 export declare function prependToWindowsUserPath(dir: string): WinPathResult;
-/**
- * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
- * or null if it can't be determined (PowerShell missing / errored).
- */
 export declare function getEffectiveExecutionPolicy(): string | null;
-/**
- * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
- * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
- * `agents` / `npm` commands fail in PowerShell with a security error even when
- * on PATH. Pure — testable on any host.
- */
 export declare function blocksLocalScripts(policy: string | null): boolean;
-/**
- * Resolve the npm global-bin directory (where the generated `agents` /
- * `agents.cmd` launchers live, and where npm expects PATH to point) from the
- * package entrypoint. On Windows npm places bin launchers directly in the
- * prefix root, so the bin dir is the prefix itself.
- *
- * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
- */
 export declare function npmGlobalBinFromEntry(entryJsPath: string): string;
 export {};

package/dist/lib/platform/winpath.js

@@ -1,34 +1,5 @@
-/**
- * Windows User PATH + execution-policy primitives.
- *
- * The single place that mutates the Windows User PATH. It reads and writes the
- * RAW registry value via `Microsoft.Win32.Registry` (NOT the .NET
- * `[Environment]::*Environment*Variable` API, which expands `%VAR%` references
- * on read and downgrades REG_EXPAND_SZ to REG_SZ on write — issue #308,
- * dotnet/runtime#89695 / #1442). The prepend/dedup itself is computed in TS
- * (`computeNewUserPath`, the single source of truth) so it has unit coverage on
- * every OS; PowerShell is used only for the registry primitives. Because a raw
- * `SetValue` does NOT broadcast the change (the old `[Environment]` API did), the
- * write script broadcasts WM_SETTINGCHANGE itself so a new terminal picks up the
- * PATH without re-login.
- * Consumers: `shims.ts` (shims dir) and `scripts/postinstall.js` (npm global-bin
- * dir, so the `agents` command itself resolves).
- *
- * Leaf module — imports only `child_process` and `path` so it is cheap to load
- * from the npm lifecycle script without pulling the rest of the CLI.
- */
 import { execFileSync } from 'child_process';
 import * as path from 'path';
-/**
- * Compute the new User PATH from the RAW (unexpanded) current value. Pure and
- * OS-independent — the single source of truth for the prepend/dedup logic.
- *
- * Idempotent: returns `{ changed: false }` (value unchanged, verbatim) when
- * `dir` is already the first `;`-split entry. Otherwise removes every existing
- * occurrence of `dir` and prepends it, dropping empty segments — matching POSIX
- * `export PATH="${dir}:$PATH"`. `%VAR%` segments are preserved verbatim (never
- * expanded), which is the #308 regression this fix targets.
- */
 export function computeNewUserPath(currentRaw, dir) {
     const parts = currentRaw.split(';').filter((p) => p !== '');
     if (parts.length > 0 && parts[0] === dir) {
@@ -37,16 +8,6 @@ export function computeNewUserPath(currentRaw, dir) {
     const others = parts.filter((p) => p !== dir);
     return { changed: true, value: [dir, ...others].join(';') };
 }
-/**
- * Decide whether to write the User PATH back as REG_EXPAND_SZ (ExpandString) vs
- * REG_SZ (String). Pure — testable on any host.
- *
- * True (expandable) when the original value was already ExpandString, when the
- * raw value contains a `%VAR%` reference, or when `Path` was absent (default to
- * ExpandString — Windows' native Path type). Only a plain String value with no
- * `%` stays REG_SZ. `originalKind` is the .NET RegistryValueKind name
- * (`ExpandString`/`String`/…) or `null`/`Absent` when `Path` had no value.
- */
 export function shouldWriteExpandable(originalKind, rawValue) {
     if (originalKind === null || originalKind === 'Absent')
         return true;
@@ -54,13 +15,7 @@ export function shouldWriteExpandable(originalKind, rawValue) {
         return true;
     return rawValue.includes('%');
 }
-// Sentinel separating the value kind from the (possibly '%'-laden) raw value in
-// the read script's stdout — PATH entries never contain a newline, so an
-// exclusive line marker parses unambiguously.
 const READ_MARKER = '===AGENTS-PATH-VALUE===';
-// Reads the RAW User PATH preserving REG_EXPAND_SZ: DoNotExpandEnvironmentNames
-// keeps `%VAR%` literal, and GetValueKind reports the original type (throws when
-// 'Path' is absent -> caught, reported as Absent).
 const READ_SCRIPT = [
     "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $false)",
     'if ($null -eq $key) {',
@@ -75,10 +30,6 @@ const READ_SCRIPT = [
     '  Write-Output $val',
     '}',
 ].join('\n');
-// Writes the computed value back with the preserved kind and broadcasts
-// WM_SETTINGCHANGE (raw SetValue does not, unlike the old [Environment] API).
-// The value comes in via AGENTS_WINPATH_VALUE so it is never interpolated into
-// the script text (preserves the no-injection property for '%'-laden paths).
 const WRITE_SCRIPT = [
     "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)",
     "if ($null -eq $key) { $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment') }",
@@ -98,7 +49,6 @@ const WRITE_SCRIPT = [
     '}',
     '"@',
     '$res = [UIntPtr]::Zero',
-    // HWND_BROADCAST=0xffff, WM_SETTINGCHANGE=0x1a, SMTO_ABORTIFHUNG=2, 5s timeout
     "[AgentsWinPath]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$res) | Out-Null",
     "Write-Output 'written'",
 ].join('\n');
@@ -110,7 +60,6 @@ function runPowerShell(script, extraEnv) {
         windowsHide: true,
     });
 }
-/** Parse the read script's stdout into the original value kind and RAW value. */
 function parseReadOutput(out) {
     const idx = out.indexOf(READ_MARKER);
     if (idx === -1)
@@ -118,24 +67,12 @@ function parseReadOutput(out) {
     const head = out.slice(0, idx);
     const kindMatch = head.match(/KIND:(\S+)/);
     const kind = kindMatch ? kindMatch[1] : null;
-    // Everything after the marker line, minus the leading/trailing newline PS adds.
     const raw = out
         .slice(idx + READ_MARKER.length)
         .replace(/^\r?\n/, '')
         .replace(/\r?\n$/, '');
     return { kind, raw };
 }
-/**
- * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
- * already first; moves it to the front when it exists but is positioned later
- * (e.g. appended by an older install) so it overrides conflicting entries.
- *
- * Reads the RAW registry value (preserving `%VAR%` and the REG_EXPAND_SZ type),
- * computes the new value in TS via `computeNewUserPath`, and only writes when
- * the value actually changes — preserving the original value type and
- * broadcasting WM_SETTINGCHANGE. `dir` and the computed value are passed via env
- * vars so they are never interpolated into the script text.
- */
 export function prependToWindowsUserPath(dir) {
     try {
         const readOut = runPowerShell(READ_SCRIPT);
@@ -155,10 +92,6 @@ export function prependToWindowsUserPath(dir) {
         return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
     }
 }
-/**
- * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
- * or null if it can't be determined (PowerShell missing / errored).
- */
 export function getEffectiveExecutionPolicy() {
     try {
         const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy'], {
@@ -172,26 +105,12 @@ export function getEffectiveExecutionPolicy() {
         return null;
     }
 }
-/**
- * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
- * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
- * `agents` / `npm` commands fail in PowerShell with a security error even when
- * on PATH. Pure — testable on any host.
- */
 export function blocksLocalScripts(policy) {
     if (!policy)
         return false;
     const p = policy.trim().toLowerCase();
     return p === 'restricted' || p === 'allsigned';
 }
-/**
- * Resolve the npm global-bin directory (where the generated `agents` /
- * `agents.cmd` launchers live, and where npm expects PATH to point) from the
- * package entrypoint. On Windows npm places bin launchers directly in the
- * prefix root, so the bin dir is the prefix itself.
- *
- * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
- */
 export function npmGlobalBinFromEntry(entryJsPath) {
     return path.resolve(path.dirname(entryJsPath), '..', '..', '..', '..');
 }