@indigoai-us/hq-cli 5.304.0 → 5.305.0

package/dist/lib/mesh/live/spool.js

@@ -5,6 +5,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { ensureOwnerDir } from "../../work-context/atomic.js";
 import { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "./paths.js";
 /** Linux PIPE_BUF is typically 4096; keep a conservative ceiling for one line. */
@@ -65,12 +66,160 @@ export function appendSpoolLine(line, root) {
 }
 export function appendHeldLine(line, root) {
     const held = workMeshHeldPath(root ?? workMeshRoot());
-    appendJsonlLine(held, line);
+    appendHeldLineIfAbsent(line, root);
     return held;
 }
+/** Append a held envelope only when its eventId is not already held. */
+export function appendHeldLineIfAbsent(line, root) {
+    return appendHeldLinesIfAbsent([line], root) === 1;
+}
+/** Append a deduplicated held batch under one file lock and one write. */
+export function appendHeldLinesIfAbsent(lines, root) {
+    const heldPath = workMeshHeldPath(root ?? workMeshRoot());
+    ensureSpoolFile(heldPath);
+    return withJsonlLock(heldPath, () => {
+        const seen = readEventIds(heldPath);
+        const append = [];
+        for (const line of lines) {
+            const eventId = heldEventId(line);
+            if (eventId) {
+                if (seen.has(eventId))
+                    continue;
+                seen.add(eventId);
+            }
+            append.push(line);
+        }
+        appendJsonlLines(heldPath, append);
+        return append.length;
+    });
+}
+function heldEventId(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        const event = record.event && typeof record.event === "object" && !Array.isArray(record.event)
+            ? record.event
+            : record;
+        return typeof event.eventId === "string" && event.eventId.trim() ? event.eventId.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readEventIds(filePath) {
+    const ids = new Set();
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return ids;
+        throw error;
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId)
+            ids.add(eventId);
+    }
+    return ids;
+}
+function appendJsonlLines(filePath, lines) {
+    if (lines.length === 0)
+        return;
+    ensureSpoolFile(filePath);
+    fs.appendFileSync(filePath, `${lines.join("\n")}\n`, { encoding: "utf8", mode: 0o600 });
+    chmodOwnerFile(filePath);
+}
+const JSONL_LOCK_STALE_MS = 5 * 60_000;
+const JSONL_LOCK_TIMEOUT_MS = 5_000;
+/** Serialize check-and-append with claims; stale locks expire after five minutes. */
+function withJsonlLock(filePath, fn) {
+    const lockPath = `${filePath}.lock`;
+    const token = randomBytes(12).toString("hex");
+    const deadline = Date.now() + JSONL_LOCK_TIMEOUT_MS;
+    const waitCell = new Int32Array(new SharedArrayBuffer(4));
+    while (true) {
+        try {
+            const fd = fs.openSync(lockPath, "wx", 0o600);
+            try {
+                fs.writeSync(fd, JSON.stringify({ pid: process.pid, token, at: Date.now() }));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            try {
+                const before = fs.statSync(lockPath);
+                stale = Date.now() - before.mtimeMs >= JSONL_LOCK_STALE_MS;
+                if (stale) {
+                    const after = fs.statSync(lockPath);
+                    if (before.dev === after.dev && before.ino === after.ino && after.mtimeMs === before.mtimeMs) {
+                        fs.unlinkSync(lockPath);
+                    }
+                    else {
+                        stale = false;
+                    }
+                }
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (stale)
+                continue;
+            if (Date.now() >= deadline)
+                throw new SpoolWriteError(`Timed out waiting for ${path.basename(filePath)} lock`);
+            Atomics.wait(waitCell, 0, 0, 10);
+        }
+    }
+    let result;
+    let operationError;
+    let operationFailed = false;
+    try {
+        result = fn();
+    }
+    catch (error) {
+        operationError = error;
+        operationFailed = true;
+    }
+    let cleanupError;
+    try {
+        const record = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (record.token === token)
+            fs.unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            cleanupError = error;
+    }
+    if (operationFailed && cleanupError !== undefined) {
+        throw new AggregateError([operationError, cleanupError], "JSONL write and lock cleanup failed");
+    }
+    if (operationFailed)
+        throw operationError;
+    if (cleanupError !== undefined)
+        throw cleanupError;
+    return result;
+}
 export function appendDeadLetterLine(line, root) {
     const dl = workMeshDeadLetterPath(root ?? workMeshRoot());
-    appendJsonlLine(dl, line);
+    withJsonlLock(dl, () => {
+        ensureSpoolFile(dl);
+        const ids = readEventIds(dl);
+        const eventId = heldEventId(line);
+        if (!eventId || !ids.has(eventId))
+            appendJsonlLine(dl, line);
+    });
     return dl;
 }
 export function appendDroppedReceipt(receipt, root) {
@@ -108,7 +257,8 @@ export function claimSpool(root, ts = `${Date.now()}`) {
 }
 export function claimHeld(root, ts = `${Date.now()}`) {
     ensureOwnerDir(root);
-    return claimJsonlByRename(workMeshHeldPath(root), workMeshClaimPath("held", ts, root));
+    const heldPath = workMeshHeldPath(root);
+    return withJsonlLock(heldPath, () => claimJsonlByRename(heldPath, workMeshClaimPath("held", ts, root)));
 }
 /** Match leftover claim files: spool.<ts>.claimed / held.<ts>.claimed (and held.<ts>.held.claimed). */
 const ORPHAN_CLAIM_RE = /^(spool|held)\..+\.claimed$/;
@@ -195,6 +345,31 @@ export function countJsonlLines(filePath) {
     }
     return n;
 }
+/** Count held eventIds once; legacy rows without an eventId remain line-counted. */
+export function countDistinctHeldEvents(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        // A concurrent claim can rename held.jsonl between existence and read checks.
+        return 0;
+    }
+    const seen = new Set();
+    let count = 0;
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId) {
+            if (seen.has(eventId))
+                continue;
+            seen.add(eventId);
+        }
+        count += 1;
+    }
+    return count;
+}
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -258,8 +433,32 @@ function countUnattributedJsonlLines(filePath) {
 export function countUnattributedEvents(root) {
     const meshRoot = root ?? workMeshRoot();
     const spool = countUnattributedJsonlLines(workMeshSpoolPath(meshRoot));
-    const held = countUnattributedJsonlLines(workMeshHeldPath(meshRoot));
+    const held = countUnattributedHeldEvents(workMeshHeldPath(meshRoot));
     const deadLetter = countUnattributedJsonlLines(workMeshDeadLetterPath(meshRoot));
     return { spool, held, deadLetter, total: spool + held + deadLetter };
 }
+function countUnattributedHeldEvents(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        // A concurrent held claim may rename this file between the read and open.
+        return 0;
+    }
+    const seen = new Set();
+    let count = 0;
+    for (const line of raw.split("\n")) {
+        if (!line.trim() || !isUnattributedLine(line))
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId) {
+            if (seen.has(eventId))
+                continue;
+            seen.add(eventId);
+        }
+        count += 1;
+    }
+    return count;
+}
 //# sourceMappingURL=spool.js.map

package/dist/lib/work-context/bind-best.js

@@ -57,6 +57,17 @@ function readJson(filePath) {
         return null;
     }
 }
+function isInactiveProject(hqRoot, project) {
+    if (!hqRoot || !project.prdPath)
+        return false;
+    const state = readJson(path.join(hqRoot, "workspace", "orchestrator", project.projectId, "state.json"));
+    const status = typeof state?.status === "string" ? state.status.trim().toLowerCase() : "";
+    if (status !== "archived" && status !== "retired")
+        return false;
+    if (typeof state?.prd_path !== "string" || !state.prd_path.trim())
+        return false;
+    return path.resolve(hqRoot, state.prd_path) === path.resolve(project.prdPath);
+}
 function reposFromMetadata(metadata) {
     if (!metadata || typeof metadata !== "object")
         return [];
@@ -225,7 +236,8 @@ export function refineProjectBinding(input) {
     const hint = input.hint?.trim();
     if (!hint)
         return { action: "keep" };
-    const catalog = discoverProjectsCached(input, input.nowMs ?? Date.now());
+    const catalog = discoverProjectsCached(input, input.nowMs ?? Date.now())
+        .filter((project) => !isInactiveProject(input.hqRoot?.trim(), project));
     const exact = catalog.find((row) => row.projectId === hint);
     if (exact?.hasBoard) {
         return { action: "bind", projectId: hint, reason: "exact slug has a Board" };

package/dist/main.js

@@ -38,7 +38,7 @@ import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
-import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
+import { printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
@@ -161,7 +161,8 @@ const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version(CLI_VERSION);
+    .version(CLI_VERSION)
+    .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
 program.hook("preAction", async () => {
     // A host that pinned HQ_AGENT_DIR has declared that it IS that agent, so
     // every command — `hq dm`, `hq secrets`, not only `hq agent …` — must
@@ -206,6 +207,7 @@ export async function runCli() {
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
+    let versionNudgeHandled = false;
     try {
         runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
             category: "command",
@@ -248,6 +250,15 @@ export async function runCli() {
         });
         if (versionAction === "reexec")
             return;
+        // Commander exits immediately for its built-in --version action, before a
+        // nudge can be appended. Handle the global version-only form here so the
+        // installed semver stays the first stdout line and optional guidance follows.
+        if (process.argv.length === 3 &&
+            ["--version", "-V"].includes(process.argv[2] ?? "")) {
+            versionNudgeHandled = true;
+            await printVersionAndNudge();
+            return;
+        }
         // Register every contributor for the selected root only. Root help and
         // unknown-command recovery use generated metadata, so they keep the full
         // Commander surface without evaluating every command implementation.
@@ -298,7 +309,9 @@ export async function runCli() {
             const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
             const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
             await settleWithin([
-                refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+                ...(versionNudgeHandled
+                    ? []
+                    : [refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs })]),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
                 ...inviteTeammateExposureFlushes,

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

@@ -137,6 +137,10 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
+    /** Permission preflight for an npm global prefix (tests inject a read-only result). */
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    /** Home directory used for the durable per-install permission notice marker. */
+    homeDir?: string;
     /** Same-filesystem install rename, injectable for rollback tests. */
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;

package/dist/utils/self-update.js

@@ -65,7 +65,7 @@ import chalk from "chalk";
 import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
 import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
@@ -659,10 +659,30 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
         return { action: "skipped", latest };
     }
-    const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
+    if (install.manager === "npm" &&
+        install.prefix &&
+        install.packageRoot &&
+        !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install)) {
+        const claimed = flavor.noun === "daemon update"
+            ? false
+            : claimNonWritableNpmPrefixNotice(install, current, deps.homeDir);
+        if (flavor.noun === "rescue" || claimed) {
+            console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+        }
+        await captureNonWritableNpmPrefixNotice({
+            fromVersion: current,
+            targetVersion: latestValid,
+            install,
+            env,
+            homeDir: deps.homeDir,
+        });
+        releaseLock();
+        return { action: "update-failed", latest };
+    }
+    const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const renamePath = deps.renamePath ?? fs.renameSync;
     // The in-place update moves the package aside, and the installer's
     // supervisor ships inside it, so run the installer through a copy.
@@ -732,12 +752,27 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.yellow(`⚠ hq-cli ${latest} is available but the update failed` +
             `${result.detail ? `: ${result.detail}` : ""}`));
         console.error(chalk.dim(`  Try manually: ${plan.cmd} ${plan.args.join(" ")}`));
-        // A root-owned npm prefix the running user cannot write is the agent-box
-        // case (the CLI is a /usr global install and the runtime is unprivileged),
-        // and the startup path has no sudo fallback — say so plainly so a failed
-        // update on a box reads as the permission wall it is, not a transient error.
-        if (install.manager === "npm" && install.prefix && !isPrefixWritable(install.prefix)) {
-            console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+        // A permission wall discovered after npm fails is handled as an expected
+        // install-state warning. The preflight normally catches it before spawn;
+        // this check covers ACL changes and other races after the preflight.
+        const npmPrefixNotWritable = install.manager === "npm" &&
+            install.prefix &&
+            install.packageRoot &&
+            !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install);
+        if (npmPrefixNotWritable) {
+            const prefixNoticeClaimed = flavor.noun === "daemon update"
+                ? false
+                : claimNonWritableNpmPrefixNotice(install, current, deps.homeDir);
+            if (flavor.noun === "rescue" || prefixNoticeClaimed) {
+                console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+            }
+            await captureNonWritableNpmPrefixNotice({
+                fromVersion: current,
+                targetVersion: latestValid,
+                install,
+                env,
+                homeDir: deps.homeDir,
+            });
         }
         // A manager-level failure often means the install layout itself is broken
         // (e.g. a hand-rolled pnpm store nested inside the app's bin dir). The
@@ -748,7 +783,9 @@ async function updateAndReexec(argv, flavor, known, deps) {
             console.error(chalk.dim(`  Or repair the install: hq rescue`));
         }
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
-        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
+        if (!npmPrefixNotWritable) {
+            await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
+        }
         return { action: "update-failed", latest };
     }
     if (installSnapshot)

package/dist/utils/version-check.d.ts

@@ -1,3 +1,4 @@
+export declare const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
 /**
  * The cached npm `latest` when it is newer than the running version, else null.
@@ -21,6 +22,12 @@ export interface RefreshVersionCacheOptions {
     timeoutMs?: number;
 }
 export declare function refreshVersionCache(options?: RefreshVersionCacheOptions): Promise<void>;
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export declare function printCachedVersionNudge(stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
+export declare function printVersionAndNudge(stdout?: Pick<NodeJS.WriteStream, "write">, stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;
     isKnownNoninteractiveStatusProbe: typeof isKnownNoninteractiveStatusProbe;

package/dist/utils/version-check.js

@@ -9,6 +9,7 @@ const CACHE_TTL_MS = 60 * 60 * 1000; // 1h — catch fresh releases within the h
 const CACHE_TTL_JITTER_MS = 5 * 60 * 1000; // up to 5m early, to spread a fleet's refreshes off a single instant
 const FETCH_TIMEOUT_MS = 3_000;
 const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+export const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 /**
  * How long to stop auto-retrying an `ineffectiveLatest` target. Long enough to
  * break the per-invocation loop on a busy agent box, short enough that a box
@@ -67,7 +68,7 @@ function isKnownNoninteractiveStatusProbe(argv = process.argv) {
     const json = args.includes("--json") || !process.stdout.isTTY;
     if (!json)
         return false;
-    if (positional[0] === "mcp" && positional[1] === "status")
+    if (positional[0] === "mcp" && (positional[1] === "status" || positional[1] === "list"))
         return true;
     if (positional[0] === "packs" && (positional[1] === "list" || positional[1] === "ls"))
         return true;
@@ -199,6 +200,34 @@ export async function refreshVersionCache(options = {}) {
         releaseLock();
     }
 }
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export async function printCachedVersionNudge(stderr = process.stderr) {
+    if (isOptedOut())
+        return;
+    let resolveProcessFlagGate;
+    try {
+        ({ resolveProcessFlagGate } = await import("../lib/flag-registry.js"));
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        stderr.write(`hq: Update nudge unavailable (${errorClass}).\n`);
+        return;
+    }
+    const enabled = resolveProcessFlagGate(CLI_VERSION_NUDGE_FLAG, { fallback: false }, () => false);
+    if (!enabled)
+        return;
+    const latest = staleAgainstCachedLatest();
+    if (latest) {
+        stderr.write(`Update available: ${latest}. Update with npm install -g @indigoai-us/hq-cli@latest, pnpm add -g @indigoai-us/hq-cli@latest, or bun add -g @indigoai-us/hq-cli@latest.\n`);
+    }
+}
+export async function printVersionAndNudge(stdout = process.stdout, stderr = process.stderr) {
+    stdout.write(`${CLI_VERSION}\n`);
+    await printCachedVersionNudge(stderr);
+}
 export const __test__ = {
     CACHE_TTL_MS,
     isKnownNoninteractiveStatusProbe,

package/dist/utils/version-gate.d.ts

@@ -151,9 +151,9 @@ export declare function resolveRunningManager(): InstallManager;
 /** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
 export declare function resolveRunningPrefix(): string | null;
 /**
- * Whether the current process can write the npm global `prefix` — i.e. whether
- * an `npm install -g --prefix <prefix>` could actually replace the installed
- * CLI, or would fail with EACCES.
+ * Whether the current process can write the npm global install targets — i.e.
+ * whether an `npm install -g --prefix <prefix>` could actually replace the
+ * installed CLI, or would fail with EACCES.
  *
  * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
  * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
@@ -167,13 +167,27 @@ export declare function resolveRunningPrefix(): string | null;
  */
 export declare function isPrefixWritable(prefix: string, access?: (target: string, mode: number) => void): boolean;
 /**
- * One-line operator explanation for a failed global update whose prefix the
- * running user cannot write. This is the agent-box case: the CLI is a
- * root-owned `/usr` global install and the runtime is unprivileged, so the
- * update genuinely cannot converge from here and re-trying it silently would
- * loop. Says so plainly and points at the paths that CAN update it.
+ * Check the directories an npm global update must mutate before spawning npm.
+ * Npm replaces the package under node_modules and writes executable links
+ * under prefix/bin. The package's parent must be writable because npm renames
+ * the old package there.
+ *
+ * When one of those directories has not been created yet, check its nearest
+ * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export declare function nonWritablePrefixNote(prefix: string): string;
+export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void): boolean;
+/** Claim the one local warning/report for this installed version and prefix. */
+export declare function claimNonWritableNpmPrefixNotice(install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">, fromVersion: string, homeDir?: string, kind?: "user" | "report"): boolean;
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export declare function captureNonWritableNpmPrefixNotice(input: {
+    fromVersion: string;
+    targetVersion: string;
+    install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}): Promise<void>;
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export declare function nonWritablePrefixNote(prefix: string, platform?: NodeJS.Platform): string;
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
  * global bin directory from `PNPM_HOME` (or an explicit `global-bin-dir`), and
@@ -411,6 +425,8 @@ export declare function checkUpdateConvergence(targetVersion: string, deps?: {
 interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
     resolveInstall?: () => RunningInstall;
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    homeDir?: string;
     runner?: UpdateRunner;
     platform?: NodeJS.Platform;
     cleanStale?: (prefix: string) => string[];
@@ -442,7 +458,7 @@ interface EnforceUpdateDeps {
  * A timed-out updater is the exception: it has been forcibly reaped, so the
  * gate returns and lets the user's command run on the current version.
  */
-declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void | Promise<void>;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -484,6 +500,8 @@ export declare const __test__: {
     buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
     buildSpawnPlan: typeof buildSpawnPlan;
+    canWriteNpmInstall: typeof canWriteNpmInstall;
+    claimNonWritableNpmPrefixNotice: typeof claimNonWritableNpmPrefixNotice;
     cleanStalePartialInstall: typeof cleanStalePartialInstall;
     derivePnpmHome: typeof derivePnpmHome;
     enforceUpdateRequired: typeof enforceUpdateRequired;