@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/utils/self-update.js

@@ -57,12 +57,19 @@
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
 import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import semver from "semver";
 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, inOwnProcessGroup, isLocalDependencyInstall, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } 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";
+import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -70,8 +77,453 @@ import { markLatestIneffective } from "./version-check.js";
 export const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
 const FETCH_TIMEOUT_MS = 3_000;
-/** Tail of captured package-manager stderr kept for the failure warning. */
-const DETAIL_MAX_CHARS = 400;
+/**
+ * Move the working CLI package beside itself before asking the package manager
+ * to replace it. If the move is unavailable, the caller proceeds without
+ * rollback protection. pnpm's .pnpm package tree is immutable store content,
+ * so only its selecting public link is moved.
+ */
+function findPnpmPublicLink(packageRoot) {
+    const home = derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot });
+    if (!home)
+        return null;
+    let resolvedPackageRoot;
+    let storeVersions;
+    try {
+        resolvedPackageRoot = fs.realpathSync(packageRoot);
+        storeVersions = fs.readdirSync(path.join(home, "global"));
+    }
+    catch {
+        return null;
+    }
+    const packageSegments = CLI_NAME.split("/");
+    for (const storeVersion of storeVersions) {
+        const storeRoot = path.join(home, "global", storeVersion);
+        const candidates = [path.join(storeRoot, "node_modules", ...packageSegments)];
+        if (/^v\d+$/.test(storeVersion)) {
+            try {
+                for (const hash of fs.readdirSync(storeRoot)) {
+                    candidates.push(path.join(storeRoot, hash, "node_modules", ...packageSegments));
+                }
+            }
+            catch {
+                // Ignore inaccessible pnpm store versions and try the remaining roots.
+            }
+        }
+        for (const candidate of candidates) {
+            if (candidate === packageRoot)
+                continue;
+            try {
+                if (!fs.lstatSync(candidate).isSymbolicLink())
+                    continue;
+                if (fs.realpathSync(candidate) !== resolvedPackageRoot)
+                    continue;
+                return { path: candidate, target: fs.readlinkSync(candidate) };
+            }
+            catch {
+                // A missing or dangling candidate is not the public link for this install.
+            }
+        }
+    }
+    return null;
+}
+function isPathInside(candidate, parent) {
+    const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function readNpmBinMap(packageRoot) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        if (manifest.bin === undefined)
+            return {};
+        const entries = typeof manifest.bin === "string"
+            ? [["hq", manifest.bin]]
+            : manifest.bin && typeof manifest.bin === "object" && !Array.isArray(manifest.bin)
+                ? Object.entries(manifest.bin)
+                : null;
+        if (!entries)
+            return null;
+        const bins = {};
+        for (const [name, target] of entries) {
+            if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") ||
+                typeof target !== "string" || target.length === 0 || path.isAbsolute(target) ||
+                !isPathInside(path.resolve(packageRoot, target), packageRoot)) {
+                return null;
+            }
+            bins[name] = target;
+        }
+        return bins;
+    }
+    catch {
+        return null;
+    }
+}
+function symlinkTargetIsInsidePackage(linkPath, target, packageRoot) {
+    return isPathInside(path.resolve(path.dirname(linkPath), target), packageRoot);
+}
+function snapshotNpmBinLinks(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return [];
+    const binMap = readNpmBinMap(packageRoot);
+    if (!binMap)
+        return [];
+    const binDirectory = path.join(prefix, "bin");
+    const links = [];
+    for (const name of Object.keys(binMap)) {
+        const linkPath = path.join(binDirectory, name);
+        try {
+            if (!fs.lstatSync(linkPath).isSymbolicLink())
+                continue;
+            const target = fs.readlinkSync(linkPath);
+            const resolved = fs.realpathSync(linkPath);
+            if (!isPathInside(resolved, packageRoot))
+                continue;
+            links.push({ path: linkPath, target });
+        }
+        catch {
+            // A missing or dangling entry was not a working npm bin link to snapshot.
+        }
+    }
+    return links;
+}
+function restoreNpmBinLinks(snapshot) {
+    if (!snapshot.npmBinDirectory || !snapshot.npmBinPackageRoot || !snapshot.npmBinLinks?.length)
+        return true;
+    if (process.platform === "win32")
+        return true;
+    let restored = true;
+    for (const bin of snapshot.npmBinLinks) {
+        if (path.dirname(bin.path) !== snapshot.npmBinDirectory) {
+            reportBinLinkConflict(bin.path, "the saved path is outside the npm bin directory");
+            restored = false;
+            continue;
+        }
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(bin.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                reportBinLinkConflict(bin.path, errorMessage(error));
+                restored = false;
+                continue;
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                reportBinLinkConflict(bin.path, "a regular file owns this command name");
+                restored = false;
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(bin.path);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(bin.path, currentTarget, snapshot.npmBinPackageRoot)) {
+                reportBinLinkConflict(bin.path, "the existing symlink points outside hq-cli");
+                restored = false;
+                continue;
+            }
+            try {
+                if (currentTarget === bin.target &&
+                    isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot))
+                    continue;
+            }
+            catch {
+                // A dangling link into the package is safe to replace with the snapshot.
+            }
+        }
+        if (!symlinkTargetIsInsidePackage(bin.path, bin.target, snapshot.npmBinPackageRoot)) {
+            reportBinLinkConflict(bin.path, "the saved npm link target is outside the restored hq-cli package");
+            restored = false;
+            continue;
+        }
+        const temporary = `${bin.path}.hq-cli-restore-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(snapshot.npmBinDirectory, { recursive: true });
+            if (!existing) {
+                // Creating the link directly is deliberately no-clobber: if another
+                // tool claimed the command name after lstat, EEXIST preserves it.
+                fs.symlinkSync(bin.target, bin.path);
+            }
+            else {
+                fs.symlinkSync(bin.target, temporary);
+                const current = fs.lstatSync(bin.path);
+                if (!current.isSymbolicLink() || fs.readlinkSync(bin.path) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being restored");
+                }
+                fs.renameSync(temporary, bin.path);
+            }
+            try {
+                if (!isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot)) {
+                    throw new Error("restored link does not resolve into the restored hq-cli package");
+                }
+            }
+            catch (error) {
+                fs.rmSync(bin.path, { force: true });
+                throw error;
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            reportBinLinkConflict(bin.path, errorMessage(error));
+            restored = false;
+        }
+    }
+    return restored;
+}
+function reportBinLinkConflict(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Could not restore hq-cli bin link at ${linkPath}; left it untouched (${reason}).`));
+}
+function reportForeignNpmBin(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Leaving hq-cli bin entry at ${linkPath} untouched; another tool owns it (${reason}).`));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function verifyOrRepairNpmBins(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return { ok: true };
+    let livePackageRoot;
+    try {
+        livePackageRoot = fs.realpathSync(packageRoot);
+    }
+    catch (error) {
+        return { ok: false, detail: `the installed hq-cli package is missing: ${errorMessage(error)}` };
+    }
+    const bins = readNpmBinMap(livePackageRoot);
+    if (!bins || typeof bins.hq !== "string" || bins.hq.length === 0) {
+        return { ok: false, detail: "the installed hq-cli package does not declare a valid hq bin" };
+    }
+    const binDirectory = path.join(prefix, "bin");
+    for (const [name, target] of Object.entries(bins)) {
+        const linkPath = path.join(binDirectory, name);
+        const expected = path.resolve(livePackageRoot, target);
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(linkPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                return { ok: false, detail: `could not inspect ${linkPath}: ${errorMessage(error)}` };
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: a regular file owns this command name` };
+                }
+                reportForeignNpmBin(linkPath, "a regular file owns this command name");
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(linkPath);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(linkPath, currentTarget, livePackageRoot)) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: the existing symlink points outside hq-cli` };
+                }
+                reportForeignNpmBin(linkPath, "the existing symlink points outside hq-cli");
+                continue;
+            }
+            try {
+                if (fs.realpathSync(linkPath) === expected && fs.statSync(linkPath).isFile())
+                    continue;
+            }
+            catch {
+                // Missing and dangling hq-cli links are repaired below.
+            }
+        }
+        const temporary = `${linkPath}.hq-cli-repair-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(binDirectory, { recursive: true });
+            const targetPath = path.relative(binDirectory, expected);
+            if (!existing) {
+                // A direct symlink create does not replace a file that appeared after
+                // lstat; EEXIST is surfaced as an update failure instead.
+                fs.symlinkSync(targetPath, linkPath);
+            }
+            else {
+                fs.symlinkSync(targetPath, temporary);
+                const current = fs.lstatSync(linkPath);
+                if (!current.isSymbolicLink() || fs.readlinkSync(linkPath) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being repaired");
+                }
+                fs.renameSync(temporary, linkPath);
+            }
+            if (fs.realpathSync(linkPath) !== expected || !fs.statSync(linkPath).isFile()) {
+                throw new Error("repaired link does not resolve to its declared package bin");
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            return { ok: false, detail: `could not repair ${linkPath}: ${errorMessage(error)}` };
+        }
+    }
+    return { ok: true };
+}
+function isInsideNodeModules(candidate) {
+    const segments = path.resolve(candidate).replace(/\\/g, "/").split("/").filter(Boolean);
+    const index = process.platform === "win32"
+        ? segments.map((segment) => segment.toLowerCase()).lastIndexOf("node_modules")
+        : segments.lastIndexOf("node_modules");
+    return index >= 0 && index < segments.length - 1;
+}
+function isRecognizedGlobalInstall(install, packageRoot) {
+    if (!isInsideNodeModules(packageRoot))
+        return false;
+    if (install.manager === "pnpm")
+        return isPnpmManagedPackageDir(packageRoot, true);
+    if (install.manager === "bun")
+        return isBunManagedPackageDir(packageRoot);
+    if (!install.prefix)
+        return false;
+    const globalNodeModules = process.platform === "win32"
+        ? path.join(install.prefix, "node_modules")
+        : path.join(install.prefix, "lib", "node_modules");
+    return isPathInside(packageRoot, globalNodeModules);
+}
+function snapshotPathsAreSafe(snapshot) {
+    const paths = [
+        snapshot.installPath,
+        snapshot.backupPath,
+        snapshot.movedPath,
+        snapshot.resolvedTarget,
+        snapshot.publicLinkPath,
+        snapshot.npmBinPackageRoot,
+    ].filter((value) => value !== undefined);
+    if (!paths.every(isInsideNodeModules))
+        return false;
+    if (snapshot.npmBinLinks?.some((bin) => !snapshot.npmBinDirectory || path.dirname(bin.path) !== snapshot.npmBinDirectory ||
+        !isPathInside(bin.path, snapshot.npmBinDirectory)))
+        return false;
+    return true;
+}
+function snapshotInstall(install, renamePath = fs.renameSync) {
+    const packageRoot = install.packageRoot;
+    if (!packageRoot)
+        return null;
+    let movedPath;
+    let backupPath;
+    let didMove = false;
+    try {
+        const entry = fs.lstatSync(packageRoot);
+        let sourcePath = packageRoot;
+        let symlinkTarget;
+        let resolvedTarget;
+        if (entry.isSymbolicLink()) {
+            symlinkTarget = fs.readlinkSync(packageRoot);
+            resolvedTarget = fs.realpathSync(packageRoot);
+            sourcePath = resolvedTarget;
+        }
+        else if (!entry.isDirectory()) {
+            return null;
+        }
+        // The running package root can be a source checkout (for example `npm
+        // link` or `node dist/...`). Only recognized global layouts are safe to
+        // move; the package manager update itself still proceeds without rollback.
+        if (!isRecognizedGlobalInstall(install, sourcePath))
+            return null;
+        const publicLink = install.manager === "pnpm" && !entry.isSymbolicLink()
+            ? findPnpmPublicLink(packageRoot)
+            : null;
+        if (!fs.statSync(sourcePath).isDirectory())
+            return null;
+        // pnpm's .pnpm tree contains the package store. Moving a package directory
+        // out of that tree can invalidate pnpm's global project, so back up only
+        // the public link that selects the running store package.
+        const isPnpmStorePath = sourcePath.split(path.sep).includes(".pnpm");
+        const backupKind = install.manager === "pnpm" && isPnpmStorePath ? "pnpm-public-link" : "package";
+        const pnpmPublicLinkPath = publicLink?.path ?? (entry.isSymbolicLink() ? packageRoot : undefined);
+        if (backupKind === "pnpm-public-link" && !pnpmPublicLinkPath)
+            return null;
+        const npmBinLinks = backupKind === "package" && install.manager === "npm" && install.prefix
+            ? snapshotNpmBinLinks(install.prefix, sourcePath)
+            : undefined;
+        movedPath = backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : sourcePath;
+        backupPath = path.join(path.dirname(movedPath), `.hq-cli-backup-${process.pid}-${randomBytes(8).toString("hex")}`);
+        renamePath(movedPath, backupPath);
+        didMove = true;
+        return {
+            installPath: packageRoot,
+            backupPath,
+            movedPath: backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : sourcePath,
+            backupKind,
+            symlinkTarget,
+            resolvedTarget,
+            publicLinkPath: backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : publicLink?.path,
+            publicLinkTarget: backupKind === "pnpm-public-link"
+                ? publicLink?.target ?? symlinkTarget
+                : publicLink?.target,
+            npmBinDirectory: npmBinLinks ? path.join(install.prefix, "bin") : undefined,
+            npmBinPackageRoot: npmBinLinks ? sourcePath : undefined,
+            npmBinLinks,
+        };
+    }
+    catch {
+        if (didMove && movedPath && backupPath) {
+            try {
+                fs.renameSync(backupPath, movedPath);
+            }
+            catch {
+                // The update may proceed without rollback if the move cannot be undone.
+            }
+        }
+        return null;
+    }
+}
+function restoreInstall(snapshot, renamePath = fs.renameSync) {
+    if (!snapshotPathsAreSafe(snapshot)) {
+        reportFailedRestore(snapshot);
+        return false;
+    }
+    try {
+        if (snapshot.backupKind === "pnpm-public-link") {
+            const publicLinkPath = snapshot.publicLinkPath ?? snapshot.movedPath;
+            fs.rmSync(publicLinkPath, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(publicLinkPath), { recursive: true });
+            renamePath(snapshot.backupPath, publicLinkPath);
+            return true;
+        }
+        fs.rmSync(snapshot.installPath, { recursive: true, force: true });
+        if (snapshot.symlinkTarget !== undefined && snapshot.resolvedTarget !== undefined) {
+            fs.rmSync(snapshot.resolvedTarget, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(snapshot.resolvedTarget), { recursive: true });
+            renamePath(snapshot.backupPath, snapshot.resolvedTarget);
+            fs.mkdirSync(path.dirname(snapshot.installPath), { recursive: true });
+            const target = process.platform === "win32" ? snapshot.resolvedTarget : snapshot.symlinkTarget;
+            fs.symlinkSync(target, snapshot.installPath, process.platform === "win32" ? "junction" : "dir");
+        }
+        else {
+            fs.mkdirSync(path.dirname(snapshot.installPath), { recursive: true });
+            renamePath(snapshot.backupPath, snapshot.installPath);
+        }
+        if (snapshot.publicLinkPath && snapshot.publicLinkTarget !== undefined) {
+            fs.rmSync(snapshot.publicLinkPath, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(snapshot.publicLinkPath), { recursive: true });
+            fs.symlinkSync(snapshot.publicLinkTarget, snapshot.publicLinkPath, process.platform === "win32" ? "junction" : "dir");
+        }
+        return restoreNpmBinLinks(snapshot);
+    }
+    catch {
+        reportFailedRestore(snapshot);
+        return false;
+    }
+}
+function discardInstallSnapshot(snapshot) {
+    if (!snapshotPathsAreSafe(snapshot)) {
+        console.error(chalk.yellow(`⚠ Could not remove the hq-cli install backup at ${snapshot.backupPath}.`));
+        return;
+    }
+    try {
+        fs.rmSync(snapshot.backupPath, { recursive: true, force: true });
+    }
+    catch {
+        console.error(chalk.yellow(`⚠ Could not remove the hq-cli install backup at ${snapshot.backupPath}.`));
+    }
+}
+function reportFailedRestore(snapshot) {
+    console.error(chalk.yellow(`⚠ Could not restore the previous hq-cli install; its backup is at ${snapshot.backupPath}.`));
+}
 /** npm `latest` for this package, or null on any failure (offline, 5xx, bad body). */
 async function fetchLatestVersion() {
     try {
@@ -115,33 +567,7 @@ export function runUpdateQuiet(cmd, args, env) {
     // the installer down with it mid-write. See `openInstallOutput`.
     const output = openInstallOutput(false);
     try {
-        const plan = buildSpawnPlan(cmd, args);
-        // `inOwnProcessGroup`: the install must survive a signal aimed at this
-        // process, or a killed `hq` leaves a corrupted global install behind.
-        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
-            stdio: output.stdio,
-            shell: plan.shell,
-            ...(env ? { env } : {}),
-        }));
-        if (result.error) {
-            const code = result.error.code;
-            return { ok: false, code, detail: result.error.message };
-        }
-        if (result.status !== 0) {
-            const tail = output.stderrTail().slice(-DETAIL_MAX_CHARS);
-            return {
-                ok: false,
-                detail: tail || `exit ${result.status ?? "signal"}`,
-            };
-        }
-        return { ok: true };
-    }
-    catch (err) {
-        return {
-            ok: false,
-            code: err?.code,
-            detail: err instanceof Error ? err.message : String(err),
-        };
+        return runSupervisedUpdateCommand(cmd, args, output, env);
     }
     finally {
         output.dispose();
@@ -236,6 +662,37 @@ async function updateAndReexec(argv, flavor, known, deps) {
     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.
+    const supervisor = staged ? null : (deps.detachSupervisor ?? detachUpdateSupervisor)();
+    // The staged install keeps the running package in place until the swap and
+    // restores it itself, so it takes no snapshot.
+    const installSnapshot = staged ? null : snapshotInstall(install, renamePath);
+    if (!staged && !installSnapshot) {
+        console.error(chalk.dim("  No backup could be made for this hq-cli install; proceeding without rollback protection."));
+    }
     let result;
     const plan = buildSelfUpdatePlan(install);
     // A pnpm global install needs PNPM_HOME to find its global bin dir. A
@@ -246,6 +703,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
     // regardless of the parent environment. No-op for npm/bun and when the
     // parent already sets PNPM_HOME.
     const updateEnv = pnpmUpdateEnv(install, env);
+    let restoredAfterFailure = false;
     try {
         console.error(chalk.dim(`Updating hq-cli ${current} → ${latest}…`));
         const defaultRunner = flavor.verbose ? runUpdateCommand : runUpdateQuiet;
@@ -253,27 +711,68 @@ async function updateAndReexec(argv, flavor, known, deps) {
         // Forward env only when PNPM_HOME had to be injected, so the common path
         // spawns with the inherited environment and keeps the two-argument runner
         // call it has always made.
-        result =
-            updateEnv === undefined
-                ? runner(plan.cmd, plan.args)
-                : runner(plan.cmd, plan.args, updateEnv);
+        if (staged) {
+            result = stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
+        }
+        else if (updateEnv === undefined) {
+            result = runner(plan.cmd, plan.args);
+        }
+        else {
+            result = runner(plan.cmd, plan.args, updateEnv);
+        }
+        if (result.ok && !staged && install.manager === "npm" && install.prefix && install.packageRoot) {
+            const bins = verifyOrRepairNpmBins(install.prefix, install.packageRoot);
+            if (!bins.ok)
+                result = bins;
+        }
+        if (!result.ok && installSnapshot) {
+            restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
+            if (restoredAfterFailure)
+                discardInstallSnapshot(installSnapshot);
+        }
+    }
+    catch (error) {
+        if (installSnapshot) {
+            if (restoreInstall(installSnapshot, renamePath))
+                discardInstallSnapshot(installSnapshot);
+        }
+        throw error;
     }
     finally {
+        supervisor?.dispose();
         releaseLock();
     }
     if (!result.ok) {
+        if (restoredAfterFailure) {
+            console.error(chalk.dim("  The previous hq-cli install was restored."));
+        }
         // The one case that still warrants the old yellow banner: we could not get
         // the user onto the new version, so they need to know it exists and how to
         // install it by hand.
         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
@@ -284,8 +783,13 @@ 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}.`));
+        if (!npmPrefixNotWritable) {
+            await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
+        }
         return { action: "update-failed", latest };
     }
+    if (installSnapshot)
+        discardInstallSnapshot(installSnapshot);
     // Read-your-writes: a "successful" `npm install -g` proves only that the
     // prefix was rewritten, NOT that the `hq` this user's PATH resolves is the
     // copy we just wrote. When a ghost/shadowing install keeps winning PATH
@@ -304,8 +808,26 @@ async function updateAndReexec(argv, flavor, known, deps) {
     if (converged === false) {
         (deps.markIneffective ?? markLatestIneffective)(latest);
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
+        await captureSelfUpdateOutcome("update-ineffective", current, latestValid, install.manager, undefined, env, flavor.noun === "rescue");
         return { action: "update-ineffective", latest };
     }
+    // A resident mesh daemon keeps the old JS loaded after a global install.
+    // Service restart is best-effort and cannot turn a successful update red.
+    try {
+        const restart = (deps.restartDaemon ?? (() => restartDaemonServiceIfInstalled({
+            env,
+            hqRoot: env.HQ_ROOT,
+        })))();
+        if (restart?.message)
+            console.error(chalk.yellow(`  ${restart.message}`));
+    }
+    catch {
+        // Defensive only; the default helper already absorbs manager failures.
+    }
+    if (!flavor.reexec) {
+        console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
+        return { action: "updated", latest };
+    }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
     const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
     if (status === null) {
@@ -316,6 +838,93 @@ async function updateAndReexec(argv, flavor, known, deps) {
     console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
     return { action: "reexec", reexecStatus: status, latest };
 }
+const SELF_UPDATE_ERROR_CLASSES = new Set([
+    "MODULE_NOT_FOUND",
+    "ENOENT",
+    "EACCES",
+    "EEXIST",
+    "E404",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EPERM",
+    "ETARGET",
+    "ETIMEDOUT",
+]);
+function selfUpdateErrorReason(code, failureKind) {
+    switch (code) {
+        case "MODULE_NOT_FOUND":
+            return "module_missing";
+        case "ENOENT":
+            return "program_not_found";
+        case "EACCES":
+        case "EPERM":
+            return "permission_denied";
+        case "EEXIST":
+            return "file_collision";
+        case "E404":
+            return "npm_package_not_found";
+        case "ETARGET":
+            return "npm_target_unavailable";
+        case "EAI_AGAIN":
+        case "ECONNREFUSED":
+        case "ECONNRESET":
+        case "ENOTFOUND":
+            return "registry_network_error";
+        case "ETIMEDOUT":
+            return "timed_out";
+        default:
+            if (failureKind === "package_manager_exit")
+                return "package_manager_exit";
+            return code ? "other_error" : "unknown";
+    }
+}
+async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, installFlavor, failure, env, flushBeforeExit) {
+    if (isCliTelemetryDisabled(env))
+        return;
+    const code = failure?.diagnosticCode ?? failure?.code;
+    const error = new Error(action === "update-failed" ? "Self-update failed" : "Self-update ineffective");
+    // This event needs no stack: frames would expose the machine's install path.
+    error.stack = undefined;
+    Sentry.captureException(error, {
+        fingerprint: ["self-update", action],
+        tags: {
+            from_version: fromVersion,
+            target_version: targetVersion,
+            install_flavor: installFlavor,
+            error_class: code && SELF_UPDATE_ERROR_CLASSES.has(code)
+                ? code
+                : failure?.failureKind === "package_manager_exit"
+                    ? "package_manager_exit"
+                    : "other",
+            error_reason: selfUpdateErrorReason(code, failure?.failureKind),
+        },
+    });
+    if (flushBeforeExit) {
+        try {
+            if (!(await Sentry.flush(500))) {
+                console.error(chalk.dim("hq: Sentry flush timed out after self-update."));
+            }
+        }
+        catch {
+            console.error(chalk.dim("hq: Sentry flush failed after self-update."));
+        }
+    }
+}
+async function readStagedSelfUpdateFlag(deps, env) {
+    try {
+        if (deps.stagedSelfUpdate)
+            return await deps.stagedSelfUpdate();
+        // Loaded here so the startup path pays for the flag client only when an
+        // update is actually due.
+        const { readDaemonFlag, STAGED_SELF_UPDATE_FLAG } = await import("../lib/daemon/flag.js");
+        return await readDaemonFlag(STAGED_SELF_UPDATE_FLAG, { env });
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and
  * re-run the user's command on the new version. `latest` is normally the cached
@@ -323,7 +932,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
  * this resolve it from the registry.
  */
 export async function autoUpdateAndReexec(argv, latest, deps = {}) {
-    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true, onlyWhenAttended: true }, latest, deps);
+    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true, onlyWhenAttended: true, reexec: true }, latest, deps);
 }
 /**
  * Rescue path: update to npm latest and re-exec the rescue on the new version.
@@ -332,6 +941,15 @@ export async function autoUpdateAndReexec(argv, latest, deps = {}) {
  * are preserved.
  */
 export async function selfUpdateAndReexec(argv, deps = {}) {
-    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true, onlyWhenAttended: false }, null, deps);
+    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true, onlyWhenAttended: false, reexec: true }, null, deps);
+}
+/**
+ * `hq daemon` updater service: update to npm latest with nobody at a terminal
+ * and no re-exec. It runs as its own short-lived child of the daemon, so no
+ * user command is waiting on the package being replaced; after an "updated"
+ * outcome the daemon restarts itself onto the new version.
+ */
+export async function daemonSelfUpdate(deps = {}) {
+    return updateAndReexec([], { noun: "daemon update", verbose: false, lock: true, onlyWhenAttended: false, reexec: false }, null, deps);
 }
 //# sourceMappingURL=self-update.js.map