@indigoai-us/hq-cli 5.345.36 → 5.345.38

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.345.38] — 2026-10-07
+- Windows CI parity suites now derive their shell-subprocess time budget from a warm-up measured on the same runner instead of a fixed 7-second deadline.
+
+## [5.345.37] — 2026-10-07
+- Keep pnpm's public global package link readable while self-update scans and replaces existing global installs, so Corepack-managed updates can complete with rollback protection intact.
+
+- Add published-package parity coverage for native core commands and align help output and symlinked project indexing with the bundled scripts.
+- When Windows blocks writing the derived workers registry, `hq core` now reports a partial result instead of terminating on an uncaught filesystem error.
+- Lane story ledger updates now keep state and status aligned, clear stale single-lane assignments, and use the canonical `review` state.
+- Add `hq provider launch` for noninteractive Claude Code and Codex CLI runs. When either provider reports the known unauthenticated response, the launcher prints the matching sign-in command.
+
 ## [5.345.36] — 2026-10-07
 - A queued `hq sync` no longer pins the installed `hq` version while it waits its turn, so `hq pkg update` is no longer blocked for the length of somebody else's sync.
 - The flag-registry background refresh no longer throws as it starts, so running any `hq` command stops filing a crash report that nothing in the command caused.

package/assets/scaffold/core/scripts/detect-stale-core-policy-mirror.sh

@@ -44,7 +44,8 @@ case "${1:-}" in
   --check)            MODE="check" ;;
   --prune-identical)  MODE="prune" ;;
   -h|--help)
-    sed -n '2,45p' "$0"
+    help_end="$(awk 'NR == 1 { next } /^#/ { last = NR; next } /^[[:space:]]*$/ { next } { exit } END { print last }' "$0")"
+    sed -n "2,${help_end}p" "$0"
     exit 0 ;;
   *)
     printf 'detect-stale-core-policy-mirror: unknown argument: %s\n' "$1" >&2

package/dist/command-catalog.generated.d.ts

@@ -1286,6 +1286,40 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly hidden: false;
     }];
     readonly subcommands: readonly [];
+}, {
+    readonly name: "provider";
+    readonly description: "Launch supported AI provider CLIs";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly helpOption: true;
+    readonly helpCommand: true;
+    readonly usage: "[options] [command]";
+    readonly helpText: readonly [];
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "launch";
+        readonly description: "Run a noninteractive Claude Code or Codex command with sign-in guidance";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] <name> [args...]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "name";
+            readonly required: true;
+            readonly variadic: false;
+            readonly description: "";
+        }, {
+            readonly name: "args";
+            readonly required: false;
+            readonly variadic: true;
+            readonly description: "";
+        }];
+        readonly options: readonly [];
+        readonly subcommands: readonly [];
+    }];
 }, {
     readonly name: "version";
     readonly description: "Show HQ, CLI, and latest hq-core versions";

package/dist/command-catalog.generated.js

@@ -1542,6 +1542,46 @@ export const COMMAND_CATALOG = [
         ],
         "subcommands": []
     },
+    {
+        "name": "provider",
+        "description": "Launch supported AI provider CLIs",
+        "aliases": [],
+        "hidden": false,
+        "helpOption": true,
+        "helpCommand": true,
+        "usage": "[options] [command]",
+        "helpText": [],
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "launch",
+                "description": "Run a noninteractive Claude Code or Codex command with sign-in guidance",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <name> [args...]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "name",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    },
+                    {
+                        "name": "args",
+                        "required": false,
+                        "variadic": true,
+                        "description": ""
+                    }
+                ],
+                "options": [],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "version",
         "description": "Show HQ, CLI, and latest hq-core versions",

package/dist/command-registration-plan.d.ts

@@ -201,6 +201,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/link.js";
     readonly exportName: "registerResolveCompanyCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "provider";
+    readonly parent: "program";
+    readonly module: "./commands/provider.js";
+    readonly exportName: "registerProviderCommand";
 }, {
     readonly type: "registrar";
     readonly root: "version";

package/dist/command-registration-plan.js

@@ -36,6 +36,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "unlink", parent: "program", module: "./commands/link.js", exportName: "registerUnlinkCommand" },
     { type: "registrar", root: "uninstall", parent: "program", module: "./commands/install-global.js", exportName: "registerUninstallCommand" },
     { type: "registrar", root: "resolve-company", parent: "program", module: "./commands/link.js", exportName: "registerResolveCompanyCommand" },
+    { type: "registrar", root: "provider", parent: "program", module: "./commands/provider.js", exportName: "registerProviderCommand" },
     { type: "registrar", root: "version", parent: "program", module: "./commands/version.js", exportName: "registerVersionCommand" },
     { type: "registrar", root: "auth", parent: "program", module: "./commands/auth.js", exportName: "registerAuthCommands" },
     { type: "registrar", root: "secrets", parent: "program", module: "./commands/secrets.js", exportName: "registerSecretsCommand" },

package/dist/commands/core.js

@@ -532,7 +532,7 @@ export function registerCoreCommands(program) {
                 ? generateWorkersRegistry(hqRoot)
                 : scanPackages(hqRoot, { quiet: process.env.HQ_SCAN_QUIET === "1" });
             if (result.status !== 0)
-                process.exit(result.status);
+                process.exitCode = result.status;
         });
         describeCoreCommand(command, {
             execution: "native",

package/dist/commands/provider.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+import { type ProviderLauncherDependencies } from "../lib/provider-launcher.js";
+export interface ProviderCommandDependencies extends ProviderLauncherDependencies {
+    setExitCode?: (code: number) => void;
+}
+export declare function registerProviderCommand(program: Command, dependencies?: ProviderCommandDependencies): void;
+//# sourceMappingURL=provider.d.ts.map

package/dist/commands/provider.js

@@ -0,0 +1,14 @@
+import { runProviderLauncher } from "../lib/provider-launcher.js";
+export function registerProviderCommand(program, dependencies = {}) {
+    program
+        .command("provider")
+        .description("Launch supported AI provider CLIs")
+        .command("launch <name> [args...]")
+        .description("Run a noninteractive Claude Code or Codex command with sign-in guidance")
+        .allowUnknownOption()
+        .action(async (name, args) => {
+        const exitCode = await runProviderLauncher(name, args, dependencies);
+        (dependencies.setExitCode ?? ((code) => { process.exitCode = code; }))(exitCode);
+    });
+}
+//# sourceMappingURL=provider.js.map

package/dist/lib/core-utils/token-usage-report.js

@@ -164,7 +164,7 @@ export function tokenUsageReport(args = [], options = {}) {
             index += 2;
         }
         else if (arg === "-h" || arg === "--help") {
-            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\n  scripts/token-usage-report.sh --project-dir <path> # use one Claude activity folder\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
+            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\n  scripts/token-usage-report.sh --project-dir <path> # read one activity folder\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\nResolve roots in the same precedence order as the native command. Explicit\nproject directories and environment overrides select one exact activity root;\notherwise include standard, desktop-saved, and discovered Claude roots.\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
             return 0;
         }
         else {

package/dist/lib/index-render/companies.js

@@ -15,7 +15,8 @@ function description(root, company, name) {
         case "knowledge": return exists(root, `${base}/.git`) ? "Embedded git repo" : `Inline knowledge (${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} subdirs)`;
         case "settings": return `${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} integration(s)`;
         case "policies": return `${countImmediate(root, base, (n) => n.endsWith(".md"))} policy file(s)`;
-        case "projects": return `${countImmediate(root, base, (n, f) => !n.startsWith("_") && !isHidden(n) && fs.statSync(f).isDirectory())} project(s)`;
+        // Match `find -type d`: count actual directories, not symlinks to directories.
+        case "projects": return `${countImmediate(root, base, (n, f) => !n.startsWith("_") && !isHidden(n) && fs.lstatSync(f).isDirectory())} project(s)`;
         case "workers": return `${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} worker(s)`;
         case "repos": return `${countImmediate(root, base, (n, f) => { const s = fs.lstatSync(f); return !isHidden(n) && (s.isDirectory() || s.isSymbolicLink()); })} repo link(s)`;
         case "registry": return `Resource registry (${countImmediate(root, `${base}/resources`, (n) => n.endsWith(".yaml"))} resource(s))`;

package/dist/lib/lanes/story-ledger.d.ts

@@ -1,6 +1,6 @@
 import { type LaneRecord, type LaneState } from "./types.js";
 export declare const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
-declare const STORY_STATES: readonly ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
+declare const STORY_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
 export interface ProjectStoryLedger {
     projectId: string;
     companySlug?: string;

package/dist/lib/lanes/story-ledger.js

@@ -8,8 +8,8 @@ export const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
 const LOCK_TIMEOUT_MS = 10_000;
 const LOCK_STALE_MS = 60_000;
 const LOCK_RETRY_MS = 10;
-const STORY_STATES = ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
-const MANAGER_OWNED_STATES = new Set(["in_review", "verification", "done", "dropped"]);
+const STORY_STATES = ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
+const MANAGER_OWNED_STATES = new Set(["review", "done", "dropped"]);
 const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
 export function laneStoryLedgerEnabled() {
     return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false);
@@ -515,7 +515,7 @@ function validPriorQuestions(value, storyId) {
     }
     return value;
 }
-function setLaneStatusFields(story, lane, laneStoryStatus) {
+function setLaneStatusFields(story, lane, laneStoryStatus, isCurrentAttribution) {
     const laneStatus = story.lane_status;
     if (laneStatus !== undefined && !isJsonObject(laneStatus)) {
         throw new LanesError("story_ledger_invalid", "lane_status must be an object for story " + String(story.id), { story_id: story.id });
@@ -569,6 +569,9 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
     else {
         delete story.pending_questions;
     }
+    if (story.state === "in_review" || story.state === "verification") {
+        story.state = "review";
+    }
     if (MANAGER_OWNED_STATES.has(String(story.state))) {
         // A manager decision always wins over lane-derived status.
     }
@@ -576,7 +579,7 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
         story.state = "blocked";
     }
     else if (laneStoryStatus === "review") {
-        story.state = "in_review";
+        story.state = "review";
     }
     else if (laneStoryStatus === "done") {
         story.state = "done";
@@ -590,6 +593,22 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
             ? previous
             : "in_progress";
     }
+    if (typeof story.state === "string" && STORY_STATES.includes(story.state)) {
+        story.status = story.state;
+    }
+    if (story.state === "blocked") {
+        const reasons = blockers.map((entry) => {
+            const reason = typeof entry.blocked_on === "string" ? entry.blocked_on.trim() : "";
+            return reason || `Lane ${String(entry.lane_id)} is blocked`;
+        });
+        if (reasons.length > 0)
+            story.blocked_reason = [...new Set(reasons)].join("\n");
+    }
+    else {
+        delete story.blocked_reason;
+    }
+    if (!isCurrentAttribution && story.lane === lane.lane_id)
+        delete story.lane;
     if (blockers.length > 0)
         story.lane_status = { saved };
     else
@@ -611,7 +630,7 @@ function updateOneStory(current, ledger, lane, storyId, projectId, questionRefs)
         (laneStoriesForLedger(lane).length <= 1 ? lane.last_envelope?.blocked_reason : undefined);
     const laneState = storyLaneState(lane, laneStory?.status, pendingQuestionIds);
     setLaneEntry(story, lane, laneState, laneStory?.status, prLinks, pendingQuestionIds, blockedReason);
-    setLaneStatusFields(story, lane, laneStory?.status);
+    setLaneStatusFields(story, lane, laneStory?.status, lane.project_id === projectId && lane.story_id === storyId);
     if (prLinks.length > 0) {
         if (story.prs === undefined)
             story.prs = [];
@@ -695,6 +714,8 @@ function storyLaneState(lane, laneStoryStatus, pendingQuestionIds) {
 }
 function storyState(story) {
     const state = story.state;
+    if (state === "in_review" || state === "verification")
+        return "review";
     if (typeof state === "string" && STORY_STATES.includes(state)) {
         return state;
     }

package/dist/lib/provider-launcher.d.ts

@@ -0,0 +1,11 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { Writable } from "node:stream";
+export type ProviderName = "claude" | "codex";
+export interface ProviderLauncherDependencies {
+    spawn?: typeof nodeSpawn;
+    stdout?: Writable;
+    stderr?: Writable;
+}
+export declare function providerLoginGuidance(provider: ProviderName, output: string): string | null;
+export declare function runProviderLauncher(providerValue: string, args: readonly string[], dependencies?: ProviderLauncherDependencies): Promise<number>;
+//# sourceMappingURL=provider-launcher.d.ts.map

package/dist/lib/provider-launcher.js

@@ -0,0 +1,59 @@
+import { spawn as nodeSpawn } from "node:child_process";
+export function providerLoginGuidance(provider, output) {
+    if (provider === "claude" && /not logged in|please run\s+\/login/i.test(output)) {
+        return "Claude Code is not signed in. Sign in with the provider command: claude /login";
+    }
+    if (provider === "codex" &&
+        /(?:http\s*)?401\b/i.test(output) &&
+        /missing bearer or basic authentication in header/i.test(output)) {
+        return "Codex is not signed in. Sign in with the provider command: codex login";
+    }
+    return null;
+}
+export async function runProviderLauncher(providerValue, args, dependencies = {}) {
+    const provider = providerValue;
+    if (provider !== "claude" && provider !== "codex") {
+        write(dependencies.stderr, `Unsupported provider '${providerValue}'. Choose claude or codex.\n`);
+        return 64;
+    }
+    if (provider === "claude" && !args.some((arg) => arg === "-p" || arg === "--print")) {
+        write(dependencies.stderr, "Provider launch supports noninteractive Claude Code commands. Include -p or --print after --.\n");
+        return 64;
+    }
+    if (provider === "codex" && args[0] !== "exec") {
+        write(dependencies.stderr, "Provider launch supports noninteractive Codex commands. Start the arguments after -- with exec.\n");
+        return 64;
+    }
+    const child = (dependencies.spawn ?? nodeSpawn)(provider, [...args], {
+        stdio: ["inherit", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let outputTail = "";
+    const capture = (stream, destination) => {
+        if (!stream)
+            return;
+        stream.on("data", (chunk) => {
+            const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+            outputTail = `${outputTail}${text}`.slice(-16_384);
+            destination?.write(text);
+        });
+    };
+    capture(child.stdout, dependencies.stdout ?? process.stdout);
+    capture(child.stderr, dependencies.stderr ?? process.stderr);
+    return await new Promise((resolve) => {
+        child.once("error", () => {
+            write(dependencies.stderr, `Could not start ${provider === "claude" ? "Claude Code" : "Codex"}. Confirm the CLI is installed and available on PATH.\n`);
+            resolve(127);
+        });
+        child.once("close", (code) => {
+            const guidance = providerLoginGuidance(provider, outputTail);
+            if (guidance)
+                write(dependencies.stderr, `${guidance}\n`);
+            resolve(code ?? 1);
+        });
+    });
+}
+function write(stream, message) {
+    (stream ?? process.stderr).write(message);
+}
+//# sourceMappingURL=provider-launcher.js.map

package/dist/lib/workers-registry/index.js

@@ -241,18 +241,43 @@ export function generateWorkersRegistry(hqRoot, options = {}) {
     const output = registryText(options.now ?? new Date(), kept);
     const registry = path.join(hqRoot, 'core/workers/registry.yaml');
     let written = true;
+    let writeFailed = false;
     if (fs.existsSync(registry) && withoutTimestamp(fs.readFileSync(registry, 'utf8')) === withoutTimestamp(output))
         written = false;
     if (written) {
-        fs.mkdirSync(path.dirname(registry), { recursive: true });
-        fs.writeFileSync(registry, output);
-        log('generate-workers-registry: wrote core/workers/registry.yaml');
+        try {
+            fs.mkdirSync(path.dirname(registry), { recursive: true });
+            fs.writeFileSync(registry, output);
+            log('generate-workers-registry: wrote core/workers/registry.yaml');
+        }
+        catch (error) {
+            writeFailed = true;
+            written = false;
+            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : 'unknown';
+            log(`generate-workers-registry: WARNING unable to write ${registry} (${code}) — grant write access to the registry path and re-run; a later run will rewrite the derived file once access is restored.`);
+            void import('../../sentry.js')
+                .then(({ Sentry }) => Sentry.captureMessage('generate-workers-registry: registry write failed; partial result returned', {
+                level: 'warning',
+                fingerprint: ['workers-registry', 'write-failed'],
+                tags: { registry_write_error: code },
+            }))
+                .catch(() => {
+                log('generate-workers-registry: WARNING unable to send the registry write failure report to Sentry.');
+            });
+        }
     }
     else {
         log('generate-workers-registry: core/workers/registry.yaml unchanged');
     }
     if (quarantined > 0) {
         log(`generate-workers-registry: wrote registry for all VALID workers; quarantined ${quarantined} problem(s) above (loud + partial, never a silent total block). Fix the reported worker.yaml file(s) and re-run to register them.`);
+    }
+    if (writeFailed) {
+        log('generate-workers-registry: registry was not written; the command completed with a partial result.');
+    }
+    if (quarantined > 0 || writeFailed) {
         return { status: 1, written, quarantined };
     }
     return { status: 0, written, quarantined };

package/dist/utils/self-update.js

@@ -79,10 +79,11 @@ export const REEXEC_GUARD_ENV = UPDATE_RECURSION_GUARD_ENV;
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
 const FETCH_TIMEOUT_MS = 3_000;
 /**
- * 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.
+ * Back up the working CLI package before asking the package manager to replace
+ * it. If the backup is unavailable, the caller proceeds without rollback
+ * protection. pnpm's .pnpm package tree is immutable store content, so back up
+ * its selecting public link while leaving that link available for pnpm's scan
+ * of existing global installs.
  */
 function findPnpmPublicLink(packageRoot) {
     const home = derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot });
@@ -187,6 +188,114 @@ function snapshotNpmBinLinks(prefix, packageRoot) {
     }
     return links;
 }
+function snapshotPnpmBinShims(pnpmHome, packageRoot) {
+    const binMap = readNpmBinMap(packageRoot);
+    if (!binMap)
+        return [];
+    const binDirectory = path.join(pnpmHome, "bin");
+    const shims = [];
+    for (const name of Object.keys(binMap)) {
+        for (const suffix of ["", ".cmd", ".ps1"]) {
+            const shimPath = path.join(binDirectory, `${name}${suffix}`);
+            try {
+                const stat = fs.lstatSync(shimPath);
+                if (!stat.isFile())
+                    continue;
+                const content = fs.readFileSync(shimPath);
+                if (!pnpmShimTargetsPackage(content.toString("utf8"), packageRoot))
+                    continue;
+                shims.push({ path: shimPath, content, mode: stat.mode & 0o777 });
+            }
+            catch {
+                // A missing or unreadable command shim cannot be safely snapshotted.
+            }
+        }
+    }
+    return shims;
+}
+function pnpmShimTarget(content) {
+    const match = content.match(/^# cmd-shim-target=(.+)$/m);
+    return match?.[1]?.trim() || null;
+}
+function pnpmShimTargetsPackage(content, packageRoot) {
+    const target = pnpmShimTarget(content);
+    if (!target)
+        return false;
+    try {
+        return isPathInside(fs.realpathSync(target), packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+function pnpmShimTargetsGlobalInstall(content, binDirectory) {
+    const target = pnpmShimTarget(content);
+    if (!target)
+        return false;
+    return isPathInside(path.resolve(target), path.join(path.dirname(binDirectory), "global"));
+}
+function restorePnpmBinShims(snapshot) {
+    if (!snapshot.pnpmBinDirectory || !snapshot.pnpmBinPackageRoot || !snapshot.pnpmBinShims?.length)
+        return true;
+    let restored = true;
+    for (const shim of snapshot.pnpmBinShims) {
+        if (path.dirname(shim.path) !== snapshot.pnpmBinDirectory) {
+            reportBinLinkConflict(shim.path, "the saved pnpm shim path is outside the pnpm bin directory");
+            restored = false;
+            continue;
+        }
+        let existing;
+        try {
+            existing = fs.lstatSync(shim.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                reportBinLinkConflict(shim.path, errorMessage(error));
+                restored = false;
+                continue;
+            }
+        }
+        if (existing) {
+            if (!existing.isFile() || existing.isSymbolicLink()) {
+                reportBinLinkConflict(shim.path, "another entry owns this command name");
+                restored = false;
+                continue;
+            }
+            const currentText = fs.readFileSync(shim.path, "utf8");
+            if (!pnpmShimTargetsGlobalInstall(currentText, snapshot.pnpmBinDirectory)) {
+                reportBinLinkConflict(shim.path, "the existing file is not a pnpm global command shim");
+                restored = false;
+                continue;
+            }
+        }
+        const temporary = `${shim.path}.hq-cli-restore-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(snapshot.pnpmBinDirectory, { recursive: true });
+            fs.writeFileSync(temporary, shim.content, { mode: shim.mode, flag: "wx" });
+            if (!existing) {
+                fs.linkSync(temporary, shim.path);
+                fs.rmSync(temporary, { force: true });
+            }
+            else {
+                const current = fs.lstatSync(shim.path);
+                if (!current.isFile() || current.isSymbolicLink()) {
+                    throw new Error("the pnpm shim changed while it was being restored");
+                }
+                const currentText = fs.readFileSync(shim.path, "utf8");
+                if (!pnpmShimTargetsGlobalInstall(currentText, snapshot.pnpmBinDirectory)) {
+                    throw new Error("the pnpm shim changed while it was being restored");
+                }
+                fs.renameSync(temporary, shim.path);
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            reportBinLinkConflict(shim.path, errorMessage(error));
+            restored = false;
+        }
+    }
+    return restored;
+}
 function restoreNpmBinLinks(snapshot) {
     if (!snapshot.npmBinDirectory || !snapshot.npmBinPackageRoot || !snapshot.npmBinLinks?.length)
         return true;
@@ -391,12 +500,16 @@ function snapshotPathsAreSafe(snapshot) {
         snapshot.resolvedTarget,
         snapshot.publicLinkPath,
         snapshot.npmBinPackageRoot,
+        snapshot.pnpmBinPackageRoot,
     ].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;
+    if (snapshot.pnpmBinShims?.some((shim) => !snapshot.pnpmBinDirectory || path.dirname(shim.path) !== snapshot.pnpmBinDirectory ||
+        !isPathInside(shim.path, snapshot.pnpmBinDirectory)))
+        return false;
     return true;
 }
 function snapshotInstall(install, renamePath = fs.renameSync) {
@@ -406,6 +519,7 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
     let movedPath;
     let backupPath;
     let didMove = false;
+    let copiedPnpmLink = false;
     try {
         const entry = fs.lstatSync(packageRoot);
         let sourcePath = packageRoot;
@@ -440,9 +554,25 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
         const npmBinLinks = backupKind === "package" && install.manager === "npm" && install.prefix
             ? snapshotNpmBinLinks(install.prefix, sourcePath)
             : undefined;
+        const pnpmHome = backupKind === "pnpm-public-link"
+            ? derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot: sourcePath }) ?? undefined
+            : undefined;
+        const pnpmBinShims = pnpmHome ? snapshotPnpmBinShims(pnpmHome, 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);
+        if (backupKind === "pnpm-public-link") {
+            // `pnpm add -g` scans every existing global package before it can update
+            // this one. Moving the active link makes its package.json disappear
+            // during that scan, so preserve a duplicate link for rollback instead.
+            const backupTarget = publicLink?.target ?? resolvedTarget ?? symlinkTarget;
+            if (!backupTarget)
+                return null;
+            fs.symlinkSync(backupTarget, backupPath, process.platform === "win32" ? "junction" : "dir");
+            copiedPnpmLink = true;
+        }
+        else {
+            renamePath(movedPath, backupPath);
+        }
         didMove = true;
         return {
             installPath: packageRoot,
@@ -458,12 +588,18 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
             npmBinDirectory: npmBinLinks ? path.join(install.prefix, "bin") : undefined,
             npmBinPackageRoot: npmBinLinks ? sourcePath : undefined,
             npmBinLinks,
+            pnpmBinDirectory: pnpmBinShims?.length ? path.join(pnpmHome, "bin") : undefined,
+            pnpmBinPackageRoot: pnpmBinShims?.length ? sourcePath : undefined,
+            pnpmBinShims,
         };
     }
     catch {
         if (didMove && movedPath && backupPath) {
             try {
-                fs.renameSync(backupPath, movedPath);
+                if (copiedPnpmLink)
+                    fs.rmSync(backupPath, { recursive: true, force: true });
+                else
+                    fs.renameSync(backupPath, movedPath);
             }
             catch {
                 // The update may proceed without rollback if the move cannot be undone.
@@ -483,7 +619,7 @@ function restoreInstall(snapshot, renamePath = fs.renameSync) {
             fs.rmSync(publicLinkPath, { recursive: true, force: true });
             fs.mkdirSync(path.dirname(publicLinkPath), { recursive: true });
             renamePath(snapshot.backupPath, publicLinkPath);
-            return true;
+            return restorePnpmBinShims(snapshot);
         }
         fs.rmSync(snapshot.installPath, { recursive: true, force: true });
         if (snapshot.symlinkTarget !== undefined && snapshot.resolvedTarget !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.36",
+  "version": "5.345.38",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {