@aragon-agent/cli 0.5.9 → 0.5.11

package/dist/update/install-lock.js

@@ -0,0 +1,184 @@
+/**
+ * The cross-process install lock (cli-auto-update section 3.7).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INHERITS `skills/lock.ts`'s PAYLOAD DISCIPLINE, NOT ITS ACQUISITION LOOP
+ * (C-9). The payload shape, the TTL, the liveness probe, the
+ * `LOCK_UNREADABLE_CONFIRMATIONS` rule and the uuid-guarded release are all the
+ * same and are imported rather than restated. The retry loop is NOT:
+ *
+ * INVARIANT U-5b - ACQUISITION IS A SINGLE NON-BLOCKING ATTEMPT.
+ * `acquireRootLock` busy-waits SYNCHRONOUSLY through `Atomics.wait` for up to
+ * `LOCK_MAX_WAIT_MS = 5_000` and then THROWS. That is right for `aragon skills
+ * install`, where a human typed the command and there is nothing else to do.
+ * Here it would freeze the Ink render loop for five seconds, from a background
+ * timer, in the feature whose entire requirement is that it is invisible. So:
+ * one `wx` attempt, no sleep, no retry, no throw - `tryAcquireInstallLock()`
+ * returns `null` on `EEXIST` after the staleness check, and the caller treats
+ * that as INFORMATION (someone else is already installing) rather than failure.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import process from 'node:process';
+import { getUpdateLockPath } from '../config/app-paths.js';
+import { LOCK_UNREADABLE_CONFIRMATIONS } from '../skills/lock.js';
+import { UPDATE_LIMITS } from './limits.js';
+/**
+ * `ESRCH` means gone. `EPERM` means the process EXISTS but belongs to another
+ * user - treating that as dead would let one user steal another's lock, so it
+ * reports alive. Verbatim from `skills/lock.ts`.
+ */
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.pid !== 'number' || typeof parsed.startedAt !== 'number')
+            return null;
+        if (typeof parsed.uuid !== 'string' || typeof parsed.host !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** `wx` - atomic exclusive create. THIS SINGLE CALL IS THE MUTUAL EXCLUSION;
+ *  everything else in this file is recovery policy. */
+function tryCreate(path, payload) {
+    let fd;
+    try {
+        fd = openSync(path, 'wx');
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        // An unwritable home is not a lock conflict, but it is equally a reason not
+        // to install; the caller cannot act on the difference.
+        return false;
+    }
+    try {
+        writeSync(fd, JSON.stringify(payload));
+    }
+    finally {
+        // Closed IMMEDIATELY: on Windows an open handle blocks `unlink`, so holding
+        // it would make our own release fail and turn every lock into a
+        // ten-minute stall for the next process.
+        closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Take the install lock, or report that someone else has it. NEVER SLEEPS,
+ * NEVER THROWS (U-5b / AC-27).
+ *
+ * The payload written here carries the PARENT's pid, and that is not a mistake:
+ * INVARIANT U-4 says the lock must name the CHILD, but the lock has to be held
+ * BEFORE the spawn (or the race it exists to close is wide open) and `child.pid`
+ * does not exist UNTIL AFTER it. `skills/lock.ts::tryCreate` writes its payload
+ * at create time, so a literal mirror can only ever write the parent's. Hence
+ * two phases: this call, then `adoptChild(child.pid)` the moment `execFile`
+ * returns.
+ *
+ * The window between them is SAFE rather than merely narrow: a crash inside it
+ * leaves a lock naming a DEAD PARENT, which is exactly the case the liveness
+ * probe below already reclaims.
+ */
+export function tryAcquireInstallLock(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
+    const path = opts.path ?? getUpdateLockPath();
+    const payload = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: now(),
+        uuid: randomUUID(),
+    };
+    if (tryCreate(path, payload))
+        return makeHandle(path, payload);
+    // Held. The ONLY thing we may do about it is decide whether the holder is
+    // plausibly dead - and even then we get exactly one more `wx` attempt, because
+    // two processes can judge the same lock stale at the same moment and `wx` is
+    // the only thing entitled to decide between them.
+    const holder = readLock(path);
+    let stale;
+    if (holder === null) {
+        // One unreadable read is indistinguishable from a lock that is mid-creation
+        // (create and write are two syscalls), so it is NOT evidence of abandonment.
+        // With a single attempt there is no second probe to accumulate, so an
+        // unreadable lock is left alone unless the discipline says one look is
+        // enough - which, at `LOCK_UNREADABLE_CONFIRMATIONS = 2`, it is not.
+        stale = LOCK_UNREADABLE_CONFIRMATIONS <= 1;
+    }
+    else {
+        stale =
+            now() - holder.startedAt > UPDATE_LIMITS.lockTtlMs ||
+                (holder.host === payload.host && !isAlive(holder.pid));
+    }
+    if (!stale)
+        return null;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Another process won the race to clean it up, or the file is pinned by a
+        // scanner holding a handle open on Windows. Either way: not ours this tick.
+        return null;
+    }
+    return tryCreate(path, payload) ? makeHandle(path, payload) : null;
+}
+function makeHandle(path, payload) {
+    let released = false;
+    let current = payload;
+    return {
+        adoptChild(pid) {
+            if (released)
+                return;
+            const next = { ...current, pid };
+            try {
+                // A plain overwrite and NOT `wx`: we already own this file, and a
+                // rename-based atomic swap would break the `wx` invariant for whoever is
+                // probing it at this instant.
+                writeFileSync(path, JSON.stringify(next), 'utf-8');
+                current = next;
+            }
+            catch {
+                // The lock keeps naming the parent. That degrades to the pre-U-4
+                // behaviour for this one install - a lock that may be judged stale early
+                // - and is strictly better than aborting an install that is already
+                // running.
+            }
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                const holder = readLock(path);
+                // THE UUID CHECK IS NOT DEFENSIVE PADDING (D-A10's argument, verbatim).
+                // If this process was judged stale and preempted, an unconditional
+                // `unlink` here would delete the NEW holder's lock and open a second
+                // concurrency window - the classic file-lock bug, and one that only
+                // shows up under exactly the contention the lock exists to handle.
+                if (holder?.uuid !== current.uuid)
+                    return;
+                unlinkSync(path);
+            }
+            catch {
+                // A failed release costs at most one TTL of waiting for the next
+                // process. Letting it throw would end a SUCCESSFUL install in an error.
+            }
+        },
+    };
+}

package/dist/update/install-source.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The eligibility ladder (cli-auto-update section 3.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE DANGEROUS VERSION OF THIS FEATURE RUNS `npm i -g` ON A MACHINE WHERE
+ * `aragon` CAME FROM SOMEWHERE ELSE. From `npx`, from a pnpm store, from a
+ * project's `node_modules`, from volta, or from a clone of this monorepo - in
+ * every one of those the global install either does not exist, is not what is
+ * running, or is actively wrong to touch. This module classifies the running
+ * installation from its own real path and reports which of those it is; the
+ * service auto-installs for exactly one classification and degrades everything
+ * else to a one-line notice carrying the correct command for THAT manager.
+ */
+import type { InstallSource } from './types.js';
+/** The package this CLI publishes as. Read from the manifest, never hardcoded
+ *  into the registry URL, so a fork keeps working (U-1). */
+export interface SelfManifest {
+    name: string;
+    version: string;
+}
+/**
+ * The package root, resolved from THIS MODULE's own URL.
+ *
+ * INVARIANT U-1 - THE LEVEL COUNT IS LOAD-BEARING AND THE FAILURE IS SILENT.
+ *
+ * The count is only correct because this package is compiled by plain `tsc` with
+ * `rootDir: ./src` and NO BUNDLER (C-16), so `src/update/install-source.ts`
+ * really does land at `dist/update/install-source.js`. If a bundler is ever
+ * introduced, `import.meta.url` collapses to `dist/cli.js` and this ascent
+ * becomes off-by-one - so that build property is a dependency of this module,
+ * not a background detail. `cli.tsx::readVersion()` goes up ONE level because it
+ * lives at `dist/cli.js`; this module lives two deep and goes up TWO.
+ *
+ * An off-by-one yields a directory whose `package.json` may still parse (the
+ * monorepo root's does), so the updater would silently check a package that is
+ * not us. `readSelfManifest()` therefore refuses a manifest without both a
+ * `name` and a `version`, and AC-3 asserts the name it reads.
+ *
+ * `realpathSync` is MANDATORY: nvm, volta and `npm link` all put symlinks on
+ * this path, and every rung of the ladder below is path-shaped.
+ */
+export declare function selfPackageRoot(): string | null;
+/**
+ * `<root>/package.json`, or `null` when it is absent, unparseable, or missing
+ * either of the two fields that make it OURS rather than some ancestor's.
+ */
+export declare function readSelfManifest(root?: string | null): SelfManifest | null;
+/**
+ * Classify the running installation. FIRST MATCH WINS, and the order is the
+ * table in section 3.2 read top to bottom.
+ *
+ * D-4 - THE GLOBAL/LOCAL CRITERION IS "DOES A MANIFEST PIN US", NOT "IS THIS THE
+ * NPM PREFIX". The obvious implementation derives the global prefix from
+ * `process.execPath`. That is wrong on Windows, where the bundled npm's default
+ * prefix is `%APPDATA%\npm` and has nothing to do with `C:\Program Files\nodejs`.
+ * It is also semantically weaker than what we actually need to know: auto-update
+ * is legitimate exactly when NO PROJECT MANIFEST PINS OUR VERSION. A
+ * `node_modules` with a sibling `package.json` is a project; one without is a
+ * global root (`%APPDATA%\npm\node_modules`, `/usr/local/lib/node_modules`,
+ * `~/.nvm/versions/node/vX/lib/node_modules` - none of them has a sibling
+ * manifest). The rule needs no subprocess, no prefix arithmetic and no platform
+ * branch.
+ */
+export declare function classifyInstallSource(root: string, env?: NodeJS.ProcessEnv): InstallSource;
+/**
+ * Can we actually write the directory the install would replace?
+ *
+ * A path can look global and still be unwritable - the ordinary Linux case,
+ * where the global root belongs to root and the user has no sudo (R-2). Probing
+ * BEFORE spawning npm turns a confusing EACCES deep in npm's output into an
+ * actionable one-line notice.
+ */
+export declare function probeWritable(root: string): boolean;
+/** Whether this classification may be auto-installed at all (D-5). */
+export declare function isAutoInstallable(source: InstallSource): boolean;
+/**
+ * Whether a classification is worth telling the user about when it is NOT
+ * auto-installable.
+ *
+ * THREE ARE SILENT, and the third is the one a reader is most likely to drop.
+ * `dev-monorepo` and `npx` are the obvious pair (AC-6 / AC-7): a developer's
+ * clone is not out of date, it is checked out; and an `npx` invocation already
+ * resolved `latest` seconds ago. `npm-local` belongs with them for the reason
+ * D-4 exists at all - a project manifest PINS our version, so upgrading is not
+ * the user's decision to make from inside this session, and `adviceFor` returns
+ * `undefined` for it because there is no command we could honestly suggest.
+ *
+ * WITHOUT `npm-local` HERE THE ROW RENDERS `0.6.0 available` WITH NO COMMAND
+ * AFTER IT, once per session, forever, on every project that depends on this
+ * package - a persistent notice carrying no action, which is precisely the
+ * notification fatigue D-7 and R-8 spend the rest of this feature avoiding.
+ * The section 3.2 table and `manual-test.md` row 10 both say "silent".
+ */
+export declare function isReportableSource(source: InstallSource): boolean;
+/** The copy-pasteable command for a source we will not install ourselves. */
+export declare function adviceFor(source: InstallSource, packageName: string): string | undefined;

package/dist/update/install-source.js

@@ -0,0 +1,218 @@
+/**
+ * The eligibility ladder (cli-auto-update section 3.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE DANGEROUS VERSION OF THIS FEATURE RUNS `npm i -g` ON A MACHINE WHERE
+ * `aragon` CAME FROM SOMEWHERE ELSE. From `npx`, from a pnpm store, from a
+ * project's `node_modules`, from volta, or from a clone of this monorepo - in
+ * every one of those the global install either does not exist, is not what is
+ * running, or is actively wrong to touch. This module classifies the running
+ * installation from its own real path and reports which of those it is; the
+ * service auto-installs for exactly one classification and degrades everything
+ * else to a one-line notice carrying the correct command for THAT manager.
+ */
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, resolve, sep } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+/**
+ * The package root, resolved from THIS MODULE's own URL.
+ *
+ * INVARIANT U-1 - THE LEVEL COUNT IS LOAD-BEARING AND THE FAILURE IS SILENT.
+ *
+ * The count is only correct because this package is compiled by plain `tsc` with
+ * `rootDir: ./src` and NO BUNDLER (C-16), so `src/update/install-source.ts`
+ * really does land at `dist/update/install-source.js`. If a bundler is ever
+ * introduced, `import.meta.url` collapses to `dist/cli.js` and this ascent
+ * becomes off-by-one - so that build property is a dependency of this module,
+ * not a background detail. `cli.tsx::readVersion()` goes up ONE level because it
+ * lives at `dist/cli.js`; this module lives two deep and goes up TWO.
+ *
+ * An off-by-one yields a directory whose `package.json` may still parse (the
+ * monorepo root's does), so the updater would silently check a package that is
+ * not us. `readSelfManifest()` therefore refuses a manifest without both a
+ * `name` and a `version`, and AC-3 asserts the name it reads.
+ *
+ * `realpathSync` is MANDATORY: nvm, volta and `npm link` all put symlinks on
+ * this path, and every rung of the ladder below is path-shaped.
+ */
+export function selfPackageRoot() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return realpathSync(resolve(here, '..', '..'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `<root>/package.json`, or `null` when it is absent, unparseable, or missing
+ * either of the two fields that make it OURS rather than some ancestor's.
+ */
+export function readSelfManifest(root = selfPackageRoot()) {
+    if (!root)
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf-8'));
+        if (typeof parsed?.name !== 'string' || parsed.name.length === 0)
+            return null;
+        if (typeof parsed?.version !== 'string' || parsed.version.length === 0)
+            return null;
+        return { name: parsed.name, version: parsed.version };
+    }
+    catch {
+        return null;
+    }
+}
+function segments(path) {
+    return path.split(/[\\/]/).filter((s) => s.length > 0);
+}
+/** The nearest ancestor directory named `node_modules`, or `null`. */
+function nearestNodeModules(root) {
+    let current = root;
+    for (;;) {
+        if (basename(current) === 'node_modules')
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function isMonorepoCheckout(root) {
+    if (basename(root) !== 'cli')
+        return false;
+    if (basename(dirname(root)) !== 'packages')
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(root, '..', '..', 'package.json'), 'utf-8'));
+        return Array.isArray(parsed?.workspaces);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify the running installation. FIRST MATCH WINS, and the order is the
+ * table in section 3.2 read top to bottom.
+ *
+ * D-4 - THE GLOBAL/LOCAL CRITERION IS "DOES A MANIFEST PIN US", NOT "IS THIS THE
+ * NPM PREFIX". The obvious implementation derives the global prefix from
+ * `process.execPath`. That is wrong on Windows, where the bundled npm's default
+ * prefix is `%APPDATA%\npm` and has nothing to do with `C:\Program Files\nodejs`.
+ * It is also semantically weaker than what we actually need to know: auto-update
+ * is legitimate exactly when NO PROJECT MANIFEST PINS OUR VERSION. A
+ * `node_modules` with a sibling `package.json` is a project; one without is a
+ * global root (`%APPDATA%\npm\node_modules`, `/usr/local/lib/node_modules`,
+ * `~/.nvm/versions/node/vX/lib/node_modules` - none of them has a sibling
+ * manifest). The rule needs no subprocess, no prefix arithmetic and no platform
+ * branch.
+ */
+export function classifyInstallSource(root, env = process.env) {
+    const parts = segments(root);
+    if (isMonorepoCheckout(root))
+        return 'dev-monorepo';
+    // `npx` already resolves `latest` on every run, so there is nothing here that
+    // could be out of date tomorrow.
+    if (parts.includes('_npx'))
+        return 'npx';
+    if (parts.includes('.pnpm') || existsSync(resolve(root, '..', '..', '.pnpm')))
+        return 'pnpm';
+    // `.yarn` (berry) or the classic `yarn/global` PAIR - adjacency matters, or a
+    // `/opt/yarn/lib/node_modules` install plus an unrelated `global` segment
+    // somewhere else on the path would misclassify.
+    if (parts.includes('.yarn'))
+        return 'yarn';
+    if (parts.some((part, i) => part === 'yarn' && parts[i + 1] === 'global'))
+        return 'yarn';
+    if (parts.includes('.bun'))
+        return 'bun';
+    if (parts.includes('.volta'))
+        return 'volta';
+    const voltaHome = env.VOLTA_HOME?.trim();
+    if (voltaHome && voltaHome.length > 0) {
+        const prefix = realpathQuiet(voltaHome);
+        if (prefix && (root === prefix || root.startsWith(prefix + sep)))
+            return 'volta';
+    }
+    const nm = nearestNodeModules(root);
+    if (!nm)
+        return 'unknown';
+    // THE WHOLE OF D-4, in one line: a sibling manifest means a project pins our
+    // version and an auto-upgrade would fight it.
+    return existsSync(resolve(dirname(nm), 'package.json')) ? 'npm-local' : 'npm-global';
+}
+function realpathQuiet(path) {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Can we actually write the directory the install would replace?
+ *
+ * A path can look global and still be unwritable - the ordinary Linux case,
+ * where the global root belongs to root and the user has no sudo (R-2). Probing
+ * BEFORE spawning npm turns a confusing EACCES deep in npm's output into an
+ * actionable one-line notice.
+ */
+export function probeWritable(root) {
+    try {
+        accessSync(dirname(root), constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this classification may be auto-installed at all (D-5). */
+export function isAutoInstallable(source) {
+    return source === 'npm-global';
+}
+/**
+ * Whether a classification is worth telling the user about when it is NOT
+ * auto-installable.
+ *
+ * THREE ARE SILENT, and the third is the one a reader is most likely to drop.
+ * `dev-monorepo` and `npx` are the obvious pair (AC-6 / AC-7): a developer's
+ * clone is not out of date, it is checked out; and an `npx` invocation already
+ * resolved `latest` seconds ago. `npm-local` belongs with them for the reason
+ * D-4 exists at all - a project manifest PINS our version, so upgrading is not
+ * the user's decision to make from inside this session, and `adviceFor` returns
+ * `undefined` for it because there is no command we could honestly suggest.
+ *
+ * WITHOUT `npm-local` HERE THE ROW RENDERS `0.6.0 available` WITH NO COMMAND
+ * AFTER IT, once per session, forever, on every project that depends on this
+ * package - a persistent notice carrying no action, which is precisely the
+ * notification fatigue D-7 and R-8 spend the rest of this feature avoiding.
+ * The section 3.2 table and `manual-test.md` row 10 both say "silent".
+ */
+export function isReportableSource(source) {
+    return source !== 'dev-monorepo' && source !== 'npx' && source !== 'npm-local';
+}
+/** The copy-pasteable command for a source we will not install ourselves. */
+export function adviceFor(source, packageName) {
+    switch (source) {
+        case 'pnpm':
+            return `pnpm add -g ${packageName}`;
+        case 'yarn':
+            return `yarn global add ${packageName}`;
+        case 'bun':
+            return `bun add -g ${packageName}`;
+        case 'volta':
+            return `volta install ${packageName}`;
+        case 'npm-global':
+        case 'unknown':
+            return `npm i -g ${packageName}`;
+        // A project manifest pins us; upgrading behind its back is the one thing a
+        // package manager exists to prevent (D-4).
+        case 'npm-local':
+        case 'dev-monorepo':
+        case 'npx':
+        default:
+            return undefined;
+    }
+}

package/dist/update/installer.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The install (cli-auto-update section 3.5).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INVARIANT U-2 - INVOKE NPM'S JS ENTRY THROUGH `process.execPath`, NEVER THE
+ * `npm` SHIM. On Windows `npm` is `npm.cmd`, and since the CVE-2024-27980 fix
+ * Node refuses to spawn a `.cmd` without `shell: true` - which C-7 forbids
+ * outright. Running node's own binary also guarantees the update is installed by
+ * the same runtime that will execute it.
+ *
+ * INVARIANT U-5 - THE CHILD'S OUTPUT GOES TO A FILE, AND ITS LIFETIME IS NEVER
+ * BOUNDED BY US. `'ignore'` leaves nothing to put in `update_install_failed`'s
+ * `stderrTail`, which is the one diagnostic a feature whose contract is silence
+ * actually needs; a PIPE would break D-10, because a detached child whose parent
+ * has exited takes `EPIPE` on its next write. A real file descriptor is
+ * inherited across the detach and keeps working after the parent is gone.
+ *
+ * `spawn`, NOT `execFile`, AND THAT IS A CORRECTION TO THE DESIGN (IF-3).
+ * Section 3.5 spelled this call as `execFile(..., { detached: true, stdio:
+ * [...], timeout: 0 })`, but `execFile` forwards NEITHER `detached` NOR `stdio`
+ * to `spawn` - it always builds its own pipes so it can buffer the output it
+ * hands to its callback. Measured on this package's own Node: with
+ * `stdio: ['ignore', fd, fd]` the log file stays EMPTY and the bytes arrive in
+ * the callback's `stdout` instead. Written as designed, U-5 loses its
+ * `stderrTail` AND D-10 loses the detach, silently and on every platform.
+ * `spawn` with an argv array and an explicit `shell: false` satisfies C-7's
+ * actual requirement ("argv array, never a shell, never a concatenated command
+ * line"), and it has no `timeout` option at all - so P1-5's "the limit must
+ * never become the child's bound" holds STRUCTURALLY here rather than by
+ * remembering to leave a field at `0`.
+ */
+import { type SpawnOptions } from 'node:child_process';
+/** The child handle this module needs. Injectable so no test spawns npm. */
+export interface SpawnedChild {
+    pid?: number | undefined;
+    on(event: 'exit', listener: (code: number | null) => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+    unref?: () => void;
+}
+export type SpawnImpl = (file: string, args: string[], options: SpawnOptions) => SpawnedChild;
+export interface InstallResult {
+    /** `true` only when npm exited 0 AND the classified root actually moved. */
+    ok: boolean;
+    /**
+     * Why not, when not. `'ineffective'` is U-6's case and is NOT a failure of
+     * npm - it is a failure of our assumption about WHERE npm writes.
+     */
+    failure?: 'spawn' | 'exit' | 'ineffective';
+    /** What `<root>/package.json` reported after the install. */
+    observedVersion?: string;
+    /** Bounded tail of the install log. The caller redacts before logging it. */
+    stderrTail?: string;
+    exitCode?: number;
+    elapsedMs?: number;
+}
+export interface InstallDeps {
+    spawnImpl?: SpawnImpl;
+    now?: () => number;
+    /** `null` forces the "no npm entry point" branch; `undefined` probes. */
+    npmCliPath?: string | null;
+    logPath?: string;
+    /** Injected so U-6's re-read can be exercised without a real install. */
+    readVersionAt?: (root: string) => string | null;
+    env?: NodeJS.ProcessEnv;
+}
+export interface RunNpmInstallInput {
+    packageName: string;
+    version: string;
+    /** The root section 3.2 classified; U-6 re-reads its manifest afterwards. */
+    root: string;
+    /** Called with the child's pid the instant it exists - phase two of U-4. */
+    onSpawn?: (pid: number) => void;
+    deps?: InstallDeps;
+}
+/**
+ * Where npm's JS entry point lives, or `null`.
+ *
+ * Probes the Windows / nvm4w layout first and the POSIX one second. There is
+ * deliberately NO bare-`npm`-on-PATH fallback: on Windows that resolves to
+ * `npm.cmd`, which is exactly what U-2 forbids, and a fallback that is correct
+ * on one platform and forbidden on another is the kind of branch that gets
+ * copied without its condition. A machine with no reachable `npm-cli.js`
+ * degrades to notify-only, which is the honest outcome.
+ */
+export declare function resolveNpmCli(execPath?: string): string | null;
+/**
+ * `env` minus `NODE_OPTIONS`, plus the three switches that keep npm's
+ * postinstall banners from spawning anything interactive.
+ *
+ * `NODE_OPTIONS` is dropped because a `--require` hook inherited into npm is an
+ * unnecessary surface on a process we start unattended and never watch.
+ */
+export declare function cleanInstallEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The argv this feature is allowed to build. Exported for AC-24's assertion. */
+export declare function buildInstallArgs(npmCliJs: string, packageName: string, version: string): string[];
+/**
+ * Install `packageName@version` globally, detached, and verify it landed HERE.
+ *
+ * Resolves when the child exits (or fails to start). The child is `unref()`ed
+ * either way, so if the user quits mid-install the install COMPLETES rather than
+ * leaving a global package half-written; the next launch's check then finds
+ * local === remote and does nothing. Convergence, not bookkeeping (D-10).
+ *
+ * NEVER REJECTS. Every failure is an `InstallResult` with `ok: false`, because
+ * the only caller is a background timer whose contract is silence.
+ */
+export declare function runNpmInstall(input: RunNpmInstallInput): Promise<InstallResult>;