@phnx-labs/agents-cli 1.22.69 → 1.22.71

package/dist/lib/project-resources.js

@@ -34,6 +34,15 @@ export function syncProjectResourcesToAgent(agent, version, projectAgentsDir) {
     syncProjectWorkflows(agent, version, projectAgentsDir, projectRoot, agentRoot, result, next);
     if (next.size > 0 || manifest) {
         writeProjectManifest(agentRoot, Array.from(next).sort());
+        // The sync is a code generator: the per-harness dir it writes into the
+        // project tree (.factory/, .opencode/, …) is a regenerable copy of
+        // .agents/{commands,skills,…}, refreshed on every launch. Left untracked it
+        // dirties `git status` and can block `git merge`/`checkout` when a stray
+        // commit of the same path collides. So the generator owns its ignore rule:
+        // reconcile a per-agent marker block in <projectRoot>/.gitignore listing
+        // exactly the paths it manages. Passing the manifest set (empty when a sync
+        // clears a harness) also prunes the block. See PHNX-3717.
+        reconcileProjectGitignore(projectRoot, agent, agentRoot, Array.from(next).sort());
     }
     return result;
 }
@@ -57,6 +66,126 @@ function writeProjectManifest(agentRoot, paths) {
     fs.writeFileSync(tmp, JSON.stringify({ v: MANIFEST_VERSION, paths }, null, 2));
     fs.renameSync(tmp, p);
 }
+const GITIGNORE_MARKER = 'agents-cli project resources';
+function gitignoreMarkers(agent) {
+    return {
+        begin: `# >>> ${GITIGNORE_MARKER}: ${agent} (generated on launch — do not edit) >>>`,
+        end: `# <<< ${GITIGNORE_MARKER}: ${agent} <<<`,
+    };
+}
+/**
+ * Turn the manifest's managed paths (relative to agentRoot) into anchored,
+ * POSIX, projectRoot-relative `.gitignore` entries. Two guards keep it honest:
+ *   - drop any path that escapes the harness config dir (e.g. grok writes
+ *     commands back into the tracked `.agents/` tree via a `../` subdir —
+ *     ignoring that would hide tracked source; separate bug, PHNX-3718);
+ *   - the manifest only ever holds paths the sync itself generated (pre-existing
+ *     user/committed files are skipped and never recorded), so ignoring exactly
+ *     these never masks a hand-authored or committed file (e.g. a repo that
+ *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
+ */
+export function managedGitignoreEntries(agentRoot, projectRoot, managed) {
+    const root = path.resolve(agentRoot);
+    const entries = new Set();
+    for (const rel of managed) {
+        if (path.isAbsolute(rel))
+            continue;
+        const abs = path.resolve(agentRoot, rel);
+        if (abs !== root && !abs.startsWith(root + path.sep))
+            continue;
+        const fromProject = toPosixRel(path.relative(projectRoot, abs));
+        if (!fromProject || fromProject === '..' || fromProject.startsWith('../'))
+            continue;
+        entries.add('/' + fromProject);
+    }
+    return Array.from(entries).sort();
+}
+/** True when `dir` is inside a git working tree — walks up to the filesystem
+ *  root looking for a `.git` entry. `projectRoot` (the parent of the resolved
+ *  `.agents/` dir) is not guaranteed to be the git root: a monorepo subdir can
+ *  carry its own `.agents/` while `.git` lives several levels up. A root-only
+ *  check would silently no-op the whole feature there. */
+function isInsideGitRepo(dir) {
+    let cur = path.resolve(dir);
+    for (;;) {
+        if (pathExists(path.join(cur, '.git')))
+            return true;
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return false;
+        cur = parent;
+    }
+}
+/**
+ * Apply this agent's managed block to `.gitignore` content, IN PLACE.
+ *
+ * In-place replacement (not strip-then-append) is load-bearing: appending would
+ * move this agent's block behind every other agent's block on each resync, so in
+ * a repo synced by 2+ harnesses whichever one launched last would get bumped to
+ * the end — rewriting `.gitignore` on every launch forever. Replacing the block
+ * where it already sits keeps the file byte-stable once written.
+ *
+ * Returns the new content, `content` unchanged when there is nothing to do, or
+ * `null` when the block is unparseable (a begin marker with no matching end —
+ * hand-truncated or a botched merge). In that case we refuse to edit rather than
+ * treat everything to EOF as the block and silently delete the user's rules
+ * below the orphaned marker.
+ */
+function applyManagedBlock(content, begin, end, entries) {
+    const lines = content.split('\n');
+    const bi = lines.indexOf(begin);
+    if (bi !== -1) {
+        const ei = lines.indexOf(end, bi + 1);
+        if (ei === -1)
+            return null; // orphaned begin marker — never truncate to EOF
+        if (entries.length > 0) {
+            return [...lines.slice(0, bi), begin, ...entries, end, ...lines.slice(ei + 1)].join('\n');
+        }
+        // Prune the block, tidying the blank lines that hugged it.
+        const before = lines.slice(0, bi);
+        const after = lines.slice(ei + 1);
+        while (before.length && before[before.length - 1].trim() === '')
+            before.pop();
+        while (after.length && after[0].trim() === '')
+            after.shift();
+        const rest = [...before, ...after].join('\n').replace(/\n+$/, '');
+        return rest.length > 0 ? `${rest}\n` : '';
+    }
+    if (entries.length === 0)
+        return content; // no block, nothing to add
+    const body = content.replace(/\n+$/, '');
+    const block = [begin, ...entries, end].join('\n');
+    return body.length > 0 ? `${body}\n\n${block}\n` : `${block}\n`;
+}
+/**
+ * Reconcile a per-agent managed block in `<projectRoot>/.gitignore` so the
+ * generated per-harness resource dir never shows as untracked dirt. Idempotent
+ * and convergent: replaces the block in place and writes only when the content
+ * actually changes, so the launch hot path does not churn the file (or its
+ * watchers) every run — even in a project synced by several harnesses. Called
+ * with an empty `managed` set when a sync clears a harness, which prunes the
+ * block. Never creates a `.gitignore` outside a git working tree.
+ */
+function reconcileProjectGitignore(projectRoot, agent, agentRoot, managed) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    if (!isInsideGitRepo(projectRoot) && !pathExists(gitignorePath))
+        return;
+    const { begin, end } = gitignoreMarkers(agent);
+    const entries = managedGitignoreEntries(agentRoot, projectRoot, managed);
+    let original = '';
+    try {
+        original = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    catch {
+        original = '';
+    }
+    const next = applyManagedBlock(original, begin, end, entries);
+    if (next === null || next === original)
+        return;
+    const tmp = gitignorePath + '.tmp';
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, gitignorePath);
+}
 function removeManagedPath(agentRoot, rel) {
     if (path.isAbsolute(rel) || rel.includes('..'))
         return;

package/dist/lib/routine-process-cleanup.d.ts

@@ -2,8 +2,8 @@ import type { RunMeta } from './scheduling/routines.js';
 export interface RoutineProcessCleanupOptions {
     runsDir?: string;
     alive?: (pid: number) => boolean;
-    owns?: (meta: RunMeta) => boolean;
+    owns?: (meta: RunMeta) => Promise<boolean> | boolean;
     terminate?: (pid: number) => void;
 }
 /** Reap process groups whose durable run record is already terminal. */
-export declare function reapTerminalRoutineProcesses(opts?: RoutineProcessCleanupOptions): number[];
+export declare function reapTerminalRoutineProcesses(opts?: RoutineProcessCleanupOptions): Promise<number[]>;

package/dist/lib/routine-process-cleanup.js

@@ -1,57 +1,68 @@
-import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as path from 'path';
-import { execFileSync } from 'child_process';
+import { execFileBounded } from './exec-bounded.js';
 import { isAlive, killTree } from './platform/index.js';
 import { getRunsDir } from './state.js';
-function processMatchesRun(meta) {
+/** Bound the identity probe: a `ps`/`powershell` spawn on the heartbeat tick must never freeze the daemon's event loop. */
+const IDENTITY_PROBE_TIMEOUT_MS = 5_000;
+async function processMatchesRun(meta) {
     if (!meta.pid || !meta.spawnedAt)
         return false;
-    try {
-        if (process.platform === 'win32') {
-            const startedAt = execFileSync('powershell.exe', [
-                '-NoProfile',
-                '-NonInteractive',
-                '-Command',
-                `(Get-Process -Id ${meta.pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString("o")`,
-            ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
-            const processStart = Date.parse(startedAt);
-            return Number.isFinite(processStart) && Math.abs(processStart - meta.spawnedAt) < 30_000;
-        }
-        const elapsed = execFileSync('ps', ['-p', String(meta.pid), '-o', 'etime='], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
-        if (!elapsed)
+    if (process.platform === 'win32') {
+        const res = await execFileBounded('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `(Get-Process -Id ${meta.pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString("o")`,
+        ], { timeoutMs: IDENTITY_PROBE_TIMEOUT_MS });
+        if (res.code !== 0)
             return false;
-        const fields = elapsed.replace(/-/g, ':').split(':').reverse();
-        const seconds = Number(fields[0] ?? 0)
-            + Number(fields[1] ?? 0) * 60
-            + Number(fields[2] ?? 0) * 3600
-            + Number(fields[3] ?? 0) * 86400;
-        return Math.abs((Date.now() - seconds * 1000) - meta.spawnedAt) < 30_000;
+        const processStart = Date.parse(res.stdout.trim());
+        return Number.isFinite(processStart) && Math.abs(processStart - meta.spawnedAt) < 30_000;
     }
-    catch {
+    const res = await execFileBounded('ps', ['-p', String(meta.pid), '-o', 'etime='], { timeoutMs: IDENTITY_PROBE_TIMEOUT_MS });
+    if (res.code !== 0)
         return false;
-    }
+    const elapsed = res.stdout.trim();
+    if (!elapsed)
+        return false;
+    const fields = elapsed.replace(/-/g, ':').split(':').reverse();
+    const seconds = Number(fields[0] ?? 0)
+        + Number(fields[1] ?? 0) * 60
+        + Number(fields[2] ?? 0) * 3600
+        + Number(fields[3] ?? 0) * 86400;
+    return Math.abs((Date.now() - seconds * 1000) - meta.spawnedAt) < 30_000;
 }
 /** Reap process groups whose durable run record is already terminal. */
-export function reapTerminalRoutineProcesses(opts = {}) {
+export async function reapTerminalRoutineProcesses(opts = {}) {
     const runsDir = opts.runsDir ?? getRunsDir();
     const alive = opts.alive ?? isAlive;
     const owns = opts.owns ?? processMatchesRun;
     const terminate = opts.terminate ?? ((pid) => killTree(process.platform === 'win32' ? pid : -pid));
-    if (!fs.existsSync(runsDir))
-        return [];
+    let jobs;
+    try {
+        jobs = await fsp.readdir(runsDir, { withFileTypes: true });
+    }
+    catch {
+        return []; // runs dir absent — nothing to reap
+    }
     const reaped = [];
-    for (const job of fs.readdirSync(runsDir, { withFileTypes: true })) {
+    for (const job of jobs) {
         if (!job.isDirectory())
             continue;
         const jobDir = path.join(runsDir, job.name);
-        for (const run of fs.readdirSync(jobDir, { withFileTypes: true })) {
+        let runs;
+        try {
+            runs = await fsp.readdir(jobDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const run of runs) {
             if (!run.isDirectory())
                 continue;
             try {
-                const meta = JSON.parse(fs.readFileSync(path.join(jobDir, run.name, 'meta.json'), 'utf-8'));
+                const meta = JSON.parse(await fsp.readFile(path.join(jobDir, run.name, 'meta.json'), 'utf-8'));
                 if (!['failed', 'timeout'].includes(meta.status) || !meta.pid || meta.hostTaskId || meta.cloudTaskId)
                     continue;
                 const completedAt = Date.parse(meta.completedAt ?? '');
@@ -59,7 +70,7 @@ export function reapTerminalRoutineProcesses(opts = {}) {
                     continue;
                 if (!alive(meta.pid))
                     continue;
-                if (!owns(meta))
+                if (!(await owns(meta)))
                     continue;
                 terminate(meta.pid);
                 reaped.push(meta.pid);

package/dist/lib/rush-session.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rush session freshness — the ONE judgment shared by every consumer of
+ * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
+ *
+ * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
+ * expires" and MUST NOT be read as an absolute timestamp:
+ *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
+ *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
+ *                   the same fix RUSH-1310 landed for the daemon-less freshness
+ *                   check and PHNX-3637 landed for the release endpoints).
+ *   - `undefined` — a token written without an expiry.
+ *
+ * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
+ * had its valid, non-expiring session rejected as "Rush session expired at
+ * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
+ * and cloud session discovery all refused to run. Every consumer that parses
+ * freshness routes through this predicate so the special-case lives in one place.
+ */
+export declare function isRushSessionExpired(expiresAt: number | undefined): boolean;

package/dist/lib/rush-session.js

@@ -0,0 +1,24 @@
+/**
+ * Rush session freshness — the ONE judgment shared by every consumer of
+ * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
+ *
+ * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
+ * expires" and MUST NOT be read as an absolute timestamp:
+ *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
+ *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
+ *                   the same fix RUSH-1310 landed for the daemon-less freshness
+ *                   check and PHNX-3637 landed for the release endpoints).
+ *   - `undefined` — a token written without an expiry.
+ *
+ * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
+ * had its valid, non-expiring session rejected as "Rush session expired at
+ * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
+ * and cloud session discovery all refused to run. Every consumer that parses
+ * freshness routes through this predicate so the special-case lives in one place.
+ */
+export function isRushSessionExpired(expiresAt) {
+    // `0` (non-expiring pid_ bearer) and a missing value are never expired.
+    if (typeof expiresAt !== 'number' || expiresAt === 0)
+        return false;
+    return expiresAt <= Date.now() / 1000;
+}

package/dist/lib/secrets/drivers/rush.js

@@ -13,6 +13,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import { isRushSessionExpired } from '../../rush-session.js';
 const PROXY_BASE = 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
@@ -27,7 +28,7 @@ function readRushToken() {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
     const expiresAt = data.session?.expires_at;
-    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+    if (isRushSessionExpired(expiresAt)) {
         const expiredAt = new Date(expiresAt * 1000).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }

package/dist/lib/secrets/reaper.d.ts

@@ -83,8 +83,8 @@ export declare function resetKeychainReaperCandidatesForTest(): void;
  * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
  * never targeted. Returns on non-darwin without shelling anything.
  */
-export declare function reapOrphanedKeychainProcesses(): {
+export declare function reapOrphanedKeychainProcesses(): Promise<{
     reaped: number;
     details: string[];
     plan: ReapPlan;
-};
+}>;

package/dist/lib/secrets/reaper.js

@@ -6,8 +6,10 @@
  * without a real `ps`; the driver ({@link reapOrphanedKeychainProcesses}) shells
  * `ps` once per tick and kills through {@link killTree}.
  */
-import { execFileSync } from 'child_process';
 import { killTree, captureProcessStartTime } from '../platform/process.js';
+import { execFileBounded } from '../exec-bounded.js';
+/** Deadline for the whole-process-table `ps` on the keychain-reap tick. */
+const KEYCHAIN_PS_TIMEOUT_MS = 5_000;
 import { getKeychainHelperPath } from './install-helper.js';
 /** Grace before a helper whose parent exited is considered an orphan. */
 export const ORPHAN_GRACE_SEC = 30;
@@ -169,7 +171,7 @@ export function resetKeychainReaperCandidatesForTest() {
  * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
  * never targeted. Returns on non-darwin without shelling anything.
  */
-export function reapOrphanedKeychainProcesses() {
+export async function reapOrphanedKeychainProcesses() {
     const details = [];
     if (process.platform !== 'darwin') {
         return { reaped: 0, details, plan: { kill: [], nextCandidates: new Map() } };
@@ -182,14 +184,15 @@ export function reapOrphanedKeychainProcesses() {
         return { reaped: 0, details: [`helper path resolution failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
     }
     let out;
-    try {
-        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-    }
-    catch (err) {
-        return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
+    {
+        // Async, deadline-bounded: this whole-process-table `ps` runs on the daemon's
+        // shared event loop every keychain-reap tick, so a synchronous `execFileSync`
+        // (unbounded) would freeze it (PHNX-3695).
+        const res = await execFileBounded('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], { timeoutMs: KEYCHAIN_PS_TIMEOUT_MS });
+        if (res.code !== 0) {
+            return { reaped: 0, details: [`ps failed${res.timedOut ? ' (timed out)' : ''}: ${res.stderr.trim() || `exit ${res.code}`}`], plan: { kill: [], nextCandidates: new Map() } };
+        }
+        out = res.stdout;
     }
     const rows = [];
     for (const line of out.split('\n')) {

package/dist/lib/secrets/reserved-sync.d.ts

@@ -58,7 +58,7 @@ export interface PublishAuthVerdictResult {
     error: string | null;
 }
 /** Publish only safe readiness metadata; useful immediately before a repo push. */
-export declare function publishReservedAuthVerdict(options?: PublishAuthVerdictOptions): PublishAuthVerdictResult;
+export declare function publishReservedAuthVerdict(options?: PublishAuthVerdictOptions): Promise<PublishAuthVerdictResult>;
 /**
  * Publish local readiness, elect one ready source, then asynchronously provision
  * only peers whose shared verdict says the bundle is missing.

package/dist/lib/secrets/reserved-sync.js

@@ -13,7 +13,7 @@ import { isDialableDevice, loadDevicesSync } from '../devices/registry.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { isHostPinned, isDevicePinned, managedKnownHostsPath } from '../devices/known-hosts.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
-import { readFleetSharedDeviceStates, updateFleetSharedDeviceState, } from '../fleet-shared-state.js';
+import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
 import { getUserAgentsDir } from '../state.js';
 /** Each import/read-back SSH operation gets this deadline plus the SSH hard-kill grace. */
 export const AUTH_SYNC_PUSH_DEADLINE_MS = 20_000;
@@ -49,12 +49,12 @@ function authStatus(local) {
     return local.ok ? 'ready' : 'invalid';
 }
 /** Publish only safe readiness metadata; useful immediately before a repo push. */
-export function publishReservedAuthVerdict(options = {}) {
+export async function publishReservedAuthVerdict(options = {}) {
     const local = (options.inspectLocal ?? inspectReservedAuthBundle)();
     const status = authStatus(local);
     const device = options.localName ?? machineId();
     try {
-        const write = updateFleetSharedDeviceState(device, { auth: { status } }, options.userAgentsDir ?? getUserAgentsDir());
+        const write = await updateFleetSharedDeviceStateAsync(device, { auth: { status } }, options.userAgentsDir ?? getUserAgentsDir());
         return { device, status, changed: write.changed, error: null };
     }
     catch (err) {
@@ -73,7 +73,7 @@ export async function syncReservedAuthBundle(deps = {}) {
         skipped: [],
         errors: [],
     };
-    const published = publishReservedAuthVerdict(deps);
+    const published = await publishReservedAuthVerdict(deps);
     const localStatus = published.status;
     const localName = published.device;
     const localNorm = normalizeHost(localName);

package/dist/lib/self-update.d.ts

@@ -152,14 +152,21 @@ export declare function deriveGlobalPrefix(packageRoot: string): string;
  * basename), so an unrelated dotfile in the same directory is left alone.
  * Best-effort per entry: one unremovable sibling must not block the rest.
  */
-export declare function sweepStaleInstallStaging(packageRoot: string): string[];
+export declare function sweepStaleInstallStaging(packageRoot: string): Promise<string[]>;
 /**
  * Install `spec` into an explicit global prefix. `--prefix` pins the
  * destination no matter which npm binary PATH resolves. `--ignore-scripts`
  * skips lifecycle scripts; the caller refreshes alias shims afterwards via
  * refreshAliasShims().
+ *
+ * `signal`, when passed, is wired into `execFile`'s own `signal` option —
+ * Node kills the child process on abort and the returned promise rejects,
+ * rather than the caller merely giving up on awaiting an orphaned process
+ * (self-update-service.ts's daemon tick needs a real kill here: on a
+ * deadline abort an un-killed `npm install -g` keeps writing into the same
+ * global prefix a subsequent retry then installs into concurrently).
  */
-export declare function installPackageIntoPrefix(spec: string, prefix: string): Promise<void>;
+export declare function installPackageIntoPrefix(spec: string, prefix: string, signal?: AbortSignal): Promise<void>;
 /**
  * Install `spec` into bun's global store with `bun add -g`. bun writes to
  * `<bunGlobalDir>/node_modules/<pkg>`, which is exactly the running package
@@ -167,8 +174,10 @@ export declare function installPackageIntoPrefix(spec: string, prefix: string):
  * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
+ *
+ * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
-export declare function installPackageWithBun(spec: string): Promise<void>;
+export declare function installPackageWithBun(spec: string, signal?: AbortSignal): Promise<void>;
 /**
  * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
  * string of the form `sha512-<base64>` — npm's `dist.integrity`. Recomputes the
@@ -187,15 +196,19 @@ export declare function verifyTarballIntegrity(tarball: Buffer, integrity: strin
  * against the registry attestation. Fails closed: a non-200, a download error,
  * or a hash mismatch throws and no file path is returned, so the caller never
  * installs an unverified artifact.
+ *
+ * `signal`, when passed, aborts the fetch alongside the own `timeoutMs` timer
+ * (whichever fires first) — a real cancellation of the in-flight request, not
+ * just an abandoned await.
  */
-export declare function downloadVerifiedTarball(tarballUrl: string, integrity: string, timeoutMs?: number): Promise<string>;
+export declare function downloadVerifiedTarball(tarballUrl: string, integrity: string, timeoutMs?: number, signal?: AbortSignal): Promise<string>;
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
-export declare function readInstalledVersion(packageRoot: string): string;
+export declare function readInstalledVersion(packageRoot: string): Promise<string>;
 /**
  * Assert that the install at `packageRoot` now carries `expectedVersion`.
  * npm exiting 0 only proves it wrote *somewhere*; this proves it wrote *here*.
  */
-export declare function verifyInstalledVersion(packageRoot: string, expectedVersion: string): void;
+export declare function verifyInstalledVersion(packageRoot: string, expectedVersion: string): Promise<void>;
 /**
  * Re-run the freshly installed copy's postinstall in shims-only mode so the
  * bare-command aliases (secrets, sessions, ...) pick up the new entrypoint
@@ -203,7 +216,7 @@ export declare function verifyInstalledVersion(packageRoot: string, expectedVers
  * leaves the previous shims in place, which still point at the (now
  * upgraded) package root.
  */
-export declare function refreshAliasShims(packageRoot: string): void;
+export declare function refreshAliasShims(packageRoot: string, signal?: AbortSignal): Promise<void>;
 /** One global bin link the upgrade reconciled: what it is and what happened. */
 export interface BinLinkRepair {
     /** The `package.json#bin` key (`agents`, `ag`, `browser`, `computer`). */
@@ -245,7 +258,7 @@ export interface BinLinkRepair {
  * npm global prefix from {@link deriveGlobalPrefix}; the bun path uses its own
  * bin layout and is out of scope.
  */
-export declare function ensureGlobalBinLinks(packageRoot: string, prefix: string): BinLinkRepair[];
+export declare function ensureGlobalBinLinks(packageRoot: string, prefix: string): Promise<BinLinkRepair[]>;
 export interface AgentsCliInstall {
     /** The PATH entry (`<dir>/agents`) that resolves to this install, when found through PATH. */
     binPath?: string;