@indigoai-us/hq-cli 5.345.47 → 5.345.49

package/dist/lib/lanes/registry-flag.js

@@ -8,6 +8,7 @@ export function readLanesFlagLocalOverride(flagKey, env = process.env) {
 }
 const registryReads = new Map();
 const reportedThrownFlagReads = new Set();
+const reportedRegistryFailureFallbacks = new Set();
 class MissingFlagTokenError extends Error {
     constructor() {
         super("No cached HQ identity token is available");
@@ -17,13 +18,13 @@ class MissingFlagTokenError extends Error {
 function errorClass(error) {
     return error instanceof Error ? error.name : "UnknownError";
 }
-function reportReadFailure(flagKey, error) {
+function reportReadFailure(flagKey, error, fallback) {
     const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
     process.stderr.write(`${JSON.stringify({
         event: `lanes.${suffix}.flag_read_failed`,
         flag: flagKey,
         error: errorClass(error),
-        fallback: false,
+        fallback,
     })}\n`);
 }
 function reportInvalidCompanyUid(flagKey, source) {
@@ -46,27 +47,42 @@ function cacheKey(flagKey, company, endpoint) {
 }
 /**
  * Read a lanes flag once for each company identity in this CLI process. The
- * cache contains only an in-flight or settled boolean promise; it is never
+ * cache contains only an in-flight or settled decision result; it is never
  * written to disk. A local override is checked on every call and wins first.
  */
 export async function readLanesRegistryFlag(flagKey, options = {}) {
+    const result = await readLanesRegistryFlagResult(flagKey, options);
+    return result.state === "resolved" ? result.value : false;
+}
+/** Read a lanes flag while preserving registry failure as an explicit unknown state. */
+export async function readLanesRegistryFlagResult(flagKey, options = {}) {
+    const outcome = await readRegistryFlagOutcome(flagKey, options, false);
+    return outcome.result;
+}
+async function readRegistryFlagOutcome(flagKey, options, failOpen) {
     const env = options.env ?? process.env;
     const localOverride = readLanesFlagLocalOverride(flagKey, env);
     if (localOverride !== null)
-        return localOverride;
+        return { result: { state: "resolved", value: localOverride } };
     const companyUid = options.company?.uid?.trim();
     if (companyUid && !companyUid.startsWith("cmp_")) {
         reportInvalidCompanyUid(flagKey, options.companyUidSource ?? "company.uid");
-        return false;
+        return { result: { state: "resolved", value: false } };
     }
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);
     const key = cacheKey(flagKey, options.company, endpoint);
     const cached = registryReads.get(key);
-    if (cached)
-        return cached;
-    const pending = readRegistryValue(flagKey, endpoint, options);
-    registryReads.set(key, pending);
-    return pending;
+    const pending = cached ?? readRegistryValue(flagKey, endpoint, options);
+    if (!cached)
+        registryReads.set(key, pending);
+    const outcome = await pending;
+    reportRegistryFailure(flagKey, key, outcome, options, failOpen);
+    return outcome;
+}
+/** Delivery and wake call sites opt in to availability when the registry is unreadable. */
+export async function readLanesRegistryFlagFailOpen(flagKey, options = {}) {
+    const outcome = await readRegistryFlagOutcome(flagKey, options, true);
+    return outcome.result.state === "unknown" ? true : outcome.result.value;
 }
 /**
  * Flag readers normally report their own failures and return the safe default.
@@ -97,15 +113,10 @@ async function readRegistryValue(flagKey, endpoint, options) {
     const companyUid = company?.uid?.trim();
     const companySlug = company?.slug?.trim();
     let client;
-    let enabled = false;
-    let failed = false;
-    let reported = false;
-    const reportFailure = (error) => {
-        failed = true;
-        if (reported)
-            return;
-        reported = true;
-        (options.reportFailure ?? ((cause) => reportReadFailure(flagKey, cause)))(error);
+    let resolution;
+    let failure;
+    const rememberFailure = (error) => {
+        failure ??= { error };
     };
     try {
         const acquireToken = options.getToken ?? (async () => {
@@ -135,30 +146,58 @@ async function readRegistryValue(flagKey, endpoint, options) {
             requestTimeoutMs: LANES_FLAG_READ_TIMEOUT_MS,
             ...(companyUid ? { companyUid } : {}),
             ...(companySlug ? { companyIdentifiers: [companySlug] } : {}),
-            onError: reportFailure,
+            onError: rememberFailure,
         });
-        await client.ready();
-        const resolution = client.explain(flagKey, { fallback: false });
-        if (failed)
-            return false;
-        if (resolution.source === "snapshot" || resolution.source === "local-override") {
-            enabled = resolution.value;
+        try {
+            await client.ready();
+        }
+        catch (error) {
+            rememberFailure(error);
+        }
+        try {
+            resolution = client.explain(flagKey, { fallback: false });
+        }
+        catch (error) {
+            rememberFailure(error);
         }
     }
     catch (error) {
-        reportFailure(error);
+        rememberFailure(error);
     }
     finally {
         try {
             client?.close();
         }
         catch (error) {
-            reportFailure(error);
+            rememberFailure(error);
         }
     }
-    return failed ? false : enabled;
+    if (resolution?.source === "snapshot" || resolution?.source === "local-override") {
+        return { result: { state: "resolved", value: resolution.value }, ...(failure ? { failure } : {}) };
+    }
+    if (failure)
+        return { result: { state: "unknown" }, failure };
+    return { result: { state: "resolved", value: resolution?.value ?? false } };
+}
+function reportRegistryFailure(flagKey, key, outcome, options, failOpen) {
+    if (!outcome.failure)
+        return;
+    const fallback = outcome.result.state === "resolved"
+        ? outcome.result.value
+        : failOpen;
+    const reportKey = `${key}:${fallback}`;
+    if (reportedRegistryFailureFallbacks.has(reportKey))
+        return;
+    reportedRegistryFailureFallbacks.add(reportKey);
+    const reportFailure = options.reportFailure;
+    if (reportFailure) {
+        reportFailure(outcome.failure.error);
+        return;
+    }
+    reportReadFailure(flagKey, outcome.failure.error, fallback);
 }
 export function _resetLanesRegistryFlagCacheForTests() {
     registryReads.clear();
+    reportedRegistryFailureFallbacks.clear();
 }
 //# sourceMappingURL=registry-flag.js.map

package/dist/lib/lanes/watcher.js

@@ -398,8 +398,69 @@ function applyTerminalToLaneWithResult(hqRoot, laneId, classification, opts = {}
             current.state === "interrupted" ||
             current.state === "cancelled" ||
             current.state === "killed";
-        if (terminal)
-            return current;
+        if (terminal) {
+            // A terminal state may have been recorded before the worker's final
+            // report arrived. The report is durable output from work that already
+            // ran, so preserve it without reopening the lane or rechecking admission.
+            if (opts.envelope === undefined || opts.envelope === null)
+                return current;
+            const approvalGate = enforceRegistryApprovalGate(current, opts.envelope);
+            effectiveEnvelope = approvalGate.envelope;
+            effectiveClassification = approvalGate.violation
+                ? { state: "blocked", reason: "approval_gate_violated" }
+                : terminalClassification;
+            const envelope = effectiveEnvelope;
+            const storySwitch = applyStorySwitchEnvelope(current, envelope, at, envelopeRef);
+            const next = {
+                ...current,
+                last_envelope: {
+                    ref: envelopeRef,
+                    decision: envelope.decision,
+                    at,
+                    artifacts: envelope.artifacts,
+                    ...(envelope.blocked_reason !== undefined ? { blocked_reason: envelope.blocked_reason } : {}),
+                    ...(envelope.next_check_at !== undefined ? { next_check_at: envelope.next_check_at } : {}),
+                },
+                ...(envelope.decision !== "blocked" ? { keep_alive_blocked_resume_streak: 0 } : {}),
+                envelope_validation_errors: opts.envelopeValidationErrors,
+            };
+            if (!approvalGate.violation && approvalGate.approvedIdsToConsume.length > 0) {
+                next.registry_worker_approval_history = approvalGate.approvedIdsToConsume.reduce((history, approvalId) => appendCappedHistory(history, {
+                    event: "consumed",
+                    approval_id: approvalId,
+                    envelope_ref: envelopeRef,
+                    at,
+                }), current.registry_worker_approval_history ?? []);
+            }
+            if (current.state === "cancelled" || current.state === "killed") {
+                return JSON.stringify(next) !== JSON.stringify(current) ? next : current;
+            }
+            const storyStatus = storySwitch.suppressCompletion
+                ? "in_progress"
+                : terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
+            if (storyStatus !== undefined) {
+                next.story_status = storySwitch.suppressCompletion ? "in_progress" : envelope.story_status;
+                next.story_complete = storySwitch.suppressCompletion ? false : envelope.story_complete;
+                next.story_complete_reason = storySwitch.suppressCompletion ? undefined : envelope.story_complete_reason;
+                next.stories = laneStories(current).map((story) => story.project_id === current.project_id && story.story_id === current.story_id
+                    ? {
+                        ...story,
+                        status: storyStatus,
+                        updated_at: at,
+                        ...(envelope.decision === "blocked"
+                            ? { blocked_reason: envelope.blocked_reason ?? "" }
+                            : { blocked_reason: undefined }),
+                    }
+                    : story);
+            }
+            if (storySwitch.clearPending)
+                next.story_switch_pending = undefined;
+            if (storySwitch.storySwitchUnacknowledged !== undefined) {
+                next.story_switch_unacknowledged = storySwitch.storySwitchUnacknowledged;
+                next.attribution_history = storySwitch.attributionHistory ?? current.attribution_history;
+            }
+            return JSON.stringify(next) !== JSON.stringify(current) ? next : current;
+        }
         if (current.state === "awaiting_input" || current.state === "blocked") {
             if (current.state === effectiveClassification.state)
                 return current;

package/dist/utils/resident-package-preload.js

@@ -40,7 +40,7 @@ export const RESIDENT_PACKAGE_MODULES = {
         "@indigoai-us/hq-cloud",
     ],
     "bot-logs-follow": [],
-    mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js", "../utils/cognito-session.js", "@indigoai-us/hq-cloud", "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client"],
+    mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js", "../lib/anywhere-person-setting.js", "../utils/cognito-session.js", "@indigoai-us/hq-cloud", "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client"],
     childWrapper: ["../main.js"],
     coreJobRun: ["../lib/flag-registry.js"],
     "daemon-call": ["../lib/daemon/protocol.js"],
@@ -76,6 +76,7 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../utils/plan-gate-error.js",
         "open",
         "../commands/mcp-serve.js",
+        "../lib/anywhere-person-setting.js",
         "../lib/daemon/mcp-oauth.js",
         "../lib/mcp/tools.js",
         "../lib/mcp/prompts.js",
@@ -83,6 +84,8 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../utils/cli-telemetry.js",
         "../utils/cognito-session.js",
         "../lib/first-sync-next-step.js",
+        "../lib/process-flag-company-context.js",
+        "../lib/flag-snapshot-file.js",
         "@indigoai-us/hq-cloud",
     ],
 };
@@ -185,6 +188,7 @@ const LOADERS = {
     mcp: [
         () => import("../lib/mcp/tools.js"),
         () => import("../lib/mcp/prompts.js"),
+        () => import("../lib/anywhere-person-setting.js"),
         () => import("../utils/cognito-session.js"),
         () => import("@indigoai-us/hq-cloud"),
         async () => {
@@ -345,6 +349,7 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
         () => import("../commands/mcp-serve.js"),
+        () => import("../lib/anywhere-person-setting.js"),
         () => import("../lib/daemon/mcp-oauth.js"),
         () => import("../lib/mcp/tools.js"),
         () => import("../lib/mcp/prompts.js"),
@@ -352,6 +357,8 @@ const LOADERS = {
         () => import("../utils/cli-telemetry.js"),
         () => import("../utils/cognito-session.js"),
         () => import("../lib/first-sync-next-step.js"),
+        () => import("../lib/process-flag-company-context.js"),
+        () => import("../lib/flag-snapshot-file.js"),
         () => import("@indigoai-us/hq-cloud"),
     ],
 };

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, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmPathConflict, pnpmUpdateEnv, pnpmInstalledVersion, performPnpmUpdate, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, UPDATE_RECURSION_GUARD_ENV, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, resolvePnpmPathInstall, pnpmUpdateEnv, pnpmInstalledVersion, performPnpmUpdate, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, UPDATE_RECURSION_GUARD_ENV, } 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";
@@ -926,17 +926,18 @@ async function attemptUpdateAndReexec(argv, flavor, known, deps, env) {
     // actually running would stay exactly as stale as it started while the CLI
     // reported success and re-exec'd into the same build. That is the shape of
     // the 2026-09-02 gate loop — see isLocalDependencyInstall in version-gate.ts.
-    const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    let install = (deps.resolveInstall ?? resolveRunningInstall)();
     if (isLocalDependencyInstall(install)) {
         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 };
     }
     if (install.manager === "pnpm") {
-        const conflict = pnpmPathConflict(install);
-        if (conflict) {
-            console.error(chalk.yellow(`⚠ hq self-update refused: ${conflict}`));
+        const pathTarget = resolvePnpmPathInstall(install);
+        if (pathTarget.refusal) {
+            console.error(chalk.yellow(`⚠ hq self-update refused: ${pathTarget.refusal}`));
             return { action: "skipped", latest };
         }
+        install = pathTarget.install;
     }
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)

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

@@ -194,6 +194,8 @@ export declare function isPrefixWritable(prefix: string, access?: (target: strin
  * existing ancestor: npm can create a child only if that ancestor is writable.
  */
 export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void, platform?: NodeJS.Platform): boolean;
+/** Check whether pnpm can replace its global package and PATH shim. */
+export declare function canWritePnpmInstall(install: RunningInstall, 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. */
@@ -223,10 +225,12 @@ export declare function derivePnpmHome(install: RunningInstall): string | null;
  * Environment for the pnpm self-update spawn. pnpm requires its configured
  * global bin directory to be on PATH; pnpm 12.5.1 reports
  * `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` otherwise. Minimal-environment parents
- * may also lack PNPM_HOME, so derive it from the running install when needed.
+ * may also lack PNPM_HOME, so derive it from the selected install when needed.
  *
- * A no-op for npm/bun installs. Never override a caller's PNPM_HOME. Returns
- * `undefined` only when the inherited environment already has both values.
+ * A no-op for npm/bun installs. The selected install's home owns its global
+ * bin directory, so it takes precedence over an inherited PNPM_HOME after the
+ * updater retargets the install. Returns `undefined` only when the inherited
+ * environment already has the required values.
  */
 export declare function pnpmUpdateEnv(install: RunningInstall, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv | undefined;
 export declare function buildPrefixedInstallArgv(prefix: string): string[];
@@ -436,7 +440,10 @@ declare function probeCliVersion(bin: string): string | null;
  * shims, so writing one home cannot change a different home that appears first
  * on PATH.
  */
-export declare function pnpmPathConflict(install: RunningInstall): string | null;
+export declare function resolvePnpmPathInstall(install: RunningInstall, canWrite?: (target: RunningInstall) => boolean): {
+    install: RunningInstall;
+    refusal: string | null;
+};
 /**
  * Read-your-writes convergence check, run after an install reports success.
  *

package/dist/utils/version-gate.js

@@ -101,11 +101,11 @@ function findRunningPackageRoot() {
     return findCliPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
 }
 /** Resolve an on-PATH executable back to the installed hq-cli package it loads. */
-function findPackageRootForExecutable(bin) {
+function resolvePackageRootForExecutable(bin) {
     try {
         const packageRoot = findCliPackageRoot(path.dirname(realpathSync(bin)));
         if (packageRoot)
-            return packageRoot;
+            return { packageRoot, candidates: [packageRoot] };
     }
     catch {
         // A missing or inaccessible executable may still be recoverable from the
@@ -115,25 +115,26 @@ function findPackageRootForExecutable(bin) {
     // resolves symlinks, but a generated shim is a regular file, so walking up
     // from its real path never reaches the package it invokes. Look up only the
     // hq-cli package under the matching PNPM_HOME/global layout instead.
-    const binDir = path.dirname(bin);
+    const shimBinDir = path.dirname(bin);
     const configuredHome = process.env.PNPM_HOME;
-    const inferredHome = path.basename(binDir).toLowerCase() === "bin"
-        ? path.dirname(binDir)
-        : binDir;
+    const inferredHome = path.basename(shimBinDir).toLowerCase() === "bin"
+        ? path.dirname(shimBinDir)
+        : shimBinDir;
     const candidateHomes = [configuredHome, inferredHome].filter((home, index, homes) => Boolean(home) && homes.findIndex((candidate) => candidate === home) === index);
-    const home = candidateHomes.find((candidate) => samePath(binDir, candidate) ||
-        samePath(binDir, path.join(candidate, "bin")));
+    const home = candidateHomes.find((candidate) => samePath(shimBinDir, candidate) ||
+        samePath(shimBinDir, path.join(candidate, "bin")));
     if (!home)
-        return null;
+        return { packageRoot: null, candidates: [] };
     const globalRoot = path.join(home, "global");
     let storeVersions;
     try {
         storeVersions = readdirSync(globalRoot);
     }
     catch {
-        return null;
+        return { packageRoot: null, candidates: [] };
     }
     const packageSegments = CLI_NAME.split("/");
+    const candidates = new Set();
     for (const storeVersion of storeVersions) {
         const storeRoot = path.join(globalRoot, storeVersion);
         const packageRoots = [
@@ -156,11 +157,38 @@ function findPackageRootForExecutable(bin) {
             if (packageRoot &&
                 samePath(packageRoot, candidate) &&
                 isPnpmManagedPackageDir(packageRoot)) {
-                return packageRoot;
+                candidates.add(packageRoot);
             }
         }
     }
-    return null;
+    const roots = [...candidates];
+    if (roots.length <= 1)
+        return { packageRoot: roots[0] ?? null, candidates: roots };
+    // pnpm's generated shim identifies the package entry point it will execute.
+    // Use that target to select among v11 hash directories instead of letting
+    // directory enumeration order choose the global project and virtual store.
+    let shimContents;
+    try {
+        shimContents = readFileSync(bin, "utf8").replace(/\\/g, "/");
+    }
+    catch {
+        return { packageRoot: null, candidates: roots };
+    }
+    const selected = roots.filter((root) => {
+        const entryPoint = installedHqEntryPoint({ manager: "pnpm", prefix: null, packageRoot: root });
+        if (!entryPoint)
+            return false;
+        const absolute = entryPoint.replace(/\\/g, "/");
+        const relative = path.relative(shimBinDir, entryPoint).replace(/\\/g, "/");
+        return shimContents.includes(absolute) || shimContents.includes(relative);
+    });
+    return {
+        packageRoot: selected.length === 1 ? selected[0] : null,
+        candidates: roots,
+    };
+}
+function findPackageRootForExecutable(bin) {
+    return resolvePackageRootForExecutable(bin).packageRoot;
 }
 function samePath(left, right) {
     const canonical = (value) => {
@@ -507,6 +535,39 @@ export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode)
         }
     });
 }
+/** Check whether pnpm can replace its global package and PATH shim. */
+export function canWritePnpmInstall(install, access = (target, mode) => accessSync(target, mode)) {
+    const home = derivePnpmHome(install);
+    if (!home || !install.packageRoot)
+        return false;
+    const mode = fsConstants.W_OK | fsConstants.X_OK;
+    const dirs = pnpmInstallDirs(install);
+    const targets = [
+        home,
+        path.join(home, "global"),
+        path.join(home, "store"),
+        ...(dirs ? [dirs.globalDir, dirs.storeDir, dirs.virtualStoreDir] : []),
+        path.dirname(install.packageRoot),
+    ];
+    return targets.every((target) => {
+        let candidate = path.resolve(target);
+        while (true) {
+            try {
+                access(candidate, mode);
+                return true;
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT")
+                    return false;
+                // pnpm creates missing targets under the nearest existing writable ancestor.
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    return false;
+                candidate = parent;
+            }
+        }
+    });
+}
 const nonWritablePrefixNotices = new Set();
 /** Claim the one local warning/report for this installed version and prefix. */
 export function claimNonWritableNpmPrefixNotice(install, fromVersion, homeDir = os.homedir(), kind = "user") {
@@ -601,18 +662,22 @@ export function derivePnpmHome(install) {
  * Environment for the pnpm self-update spawn. pnpm requires its configured
  * global bin directory to be on PATH; pnpm 12.5.1 reports
  * `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` otherwise. Minimal-environment parents
- * may also lack PNPM_HOME, so derive it from the running install when needed.
+ * may also lack PNPM_HOME, so derive it from the selected install when needed.
  *
- * A no-op for npm/bun installs. Never override a caller's PNPM_HOME. Returns
- * `undefined` only when the inherited environment already has both values.
+ * A no-op for npm/bun installs. The selected install's home owns its global
+ * bin directory, so it takes precedence over an inherited PNPM_HOME after the
+ * updater retargets the install. Returns `undefined` only when the inherited
+ * environment already has the required values.
  */
 export function pnpmUpdateEnv(install, base = process.env) {
     if (install.manager !== "pnpm")
         return undefined;
-    const home = base.PNPM_HOME || derivePnpmHome(install);
+    const home = derivePnpmHome(install) ?? base.PNPM_HOME;
     if (!home)
         return undefined;
-    const binDir = path.join(home, "bin");
+    // pnpm's own `bin -g` command reports PNPM_HOME itself as the global bin
+    // directory; it must be that directory, not a guessed `<home>/bin` child.
+    const binDir = home;
     const pathKey = Object.keys(base).find((key) => key.toLowerCase() === "path") ?? "PATH";
     const currentPath = base[pathKey] ?? "";
     const normalizedBinDir = path.resolve(binDir);
@@ -633,7 +698,7 @@ export function pnpmUpdateEnv(install, base = process.env) {
         COREPACK_DEFAULT_TO_LATEST: "0",
         COREPACK_ENABLE_AUTO_PIN: "0",
     };
-    if (!base.PNPM_HOME)
+    if (base.PNPM_HOME !== home)
         result.PNPM_HOME = home;
     if (!alreadyOnPath)
         result[pathKey] = [currentPath, binDir].filter(Boolean).join(path.delimiter);
@@ -1401,36 +1466,62 @@ function probeCliVersion(bin) {
  * shims, so writing one home cannot change a different home that appears first
  * on PATH.
  */
-export function pnpmPathConflict(install) {
+export function resolvePnpmPathInstall(install, canWrite = canWritePnpmInstall) {
     if (install.manager !== "pnpm" || !install.packageRoot)
-        return null;
+        return { install, refusal: null };
     const bin = resolveHqOnPath();
     if (!bin)
-        return null;
-    const pathPackageRoot = findPackageRootForExecutable(bin);
-    if (!pathPackageRoot ||
-        globalInstallManagerForPath(bin, pathPackageRoot) !== "pnpm") {
-        return null;
-    }
-    // The fallback resolver scans every hash in a PNPM_HOME because generated
-    // shims do not expose their target. Multiple installs in the SAME home can
-    // therefore produce an arbitrary package root; only a different home means
-    // that updating this install cannot change which global shim wins PATH.
+        return { install, refusal: null };
     const runningHome = derivePnpmHome(install);
+    const packageRootLookup = resolvePackageRootForExecutable(bin);
+    const pathPackageRoot = packageRootLookup.packageRoot;
+    if (!pathPackageRoot) {
+        if (packageRootLookup.candidates.length > 1) {
+            return {
+                install,
+                refusal: `could not identify which pnpm package PATH binary ${bin} resolves to; matching global packages: ${packageRootLookup.candidates.join(", ")}`,
+            };
+        }
+        const binDirectory = path.dirname(bin);
+        const binHome = path.basename(binDirectory).toLowerCase() === "bin"
+            ? path.dirname(binDirectory)
+            : binDirectory;
+        if (runningHome && binHome && samePath(runningHome, binHome)) {
+            if (canWrite(install))
+                return { install, refusal: null };
+            return {
+                install,
+                refusal: `cannot update the pnpm install resolved by PATH at ${bin}: its pnpm home is not writable`,
+            };
+        }
+        return { install, refusal: `could not identify the pnpm-managed install resolved by PATH at ${bin}` };
+    }
+    const pathManager = globalInstallManagerForPath(bin, pathPackageRoot);
+    if (pathManager !== "pnpm") {
+        if (pathManager === "npm" || pathManager === "bun") {
+            // Updating the running pnpm install still makes progress when a known
+            // npm/Bun install shadows it; refusing would guarantee no convergence.
+            return { install, refusal: null };
+        }
+        return { install, refusal: `PATH resolves ${bin} to an install that is not verified as pnpm-managed` };
+    }
+    // The resolver uses the generated shim's target when a pnpm v11 home has
+    // multiple package hashes. Its selected package root must drive the global
+    // directory and virtual store used by the update.
     const pathHome = derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot: pathPackageRoot });
-    if (!runningHome || !pathHome || samePath(runningHome, pathHome))
-        return null;
-    let resolvedBin = bin;
-    try {
-        resolvedBin = realpathSync(bin);
+    if (!runningHome || !pathHome) {
+        return { install, refusal: `could not identify the PNPM_HOME for PATH binary ${bin}` };
     }
-    catch {
-        // Keep the PATH entry when a platform shim cannot be canonicalized.
+    const targetInstall = samePath(runningHome, pathHome)
+        ? install
+        : { manager: "pnpm", prefix: null, packageRoot: pathPackageRoot };
+    if (!canWrite(targetInstall)) {
+        return {
+            install,
+            refusal: `cannot update the pnpm install resolved by PATH at ${bin}: its pnpm home is not writable`,
+        };
     }
-    const version = probeCliVersion(bin) ?? "unknown";
-    return (`PATH resolves ${resolvedBin} at version ${version} (manager: pnpm), ` +
-        `but this process is running from a different pnpm install at ${install.packageRoot}. ` +
-        "Refusing to update one pnpm home while another hq-cli install wins PATH resolution.");
+    return { install: targetInstall, refusal: null };
 }
 /**
  * Read-your-writes convergence check, run after an install reports success.

package/docs/anywhere-runtime.md

@@ -5,7 +5,9 @@ local hqd daemon on macOS, Linux, and Windows. On Windows, hqd uses a bundled
 PowerShell pipe host that applies and verifies a user-only named-pipe DACL
 before becoming ready. A per-user
 registry links repositories to HQ companies. The `hq-anywhere-runtime` flag
-is the operator kill switch and is off by default. Runtime access also
+is an operator kill switch that defaults on when its registry row is absent,
+archived, or unreadable. An explicit registry false or the local
+`HQ_FLAG_HQ_ANYWHERE_RUNTIME=false|0` override turns it off. Runtime access also
 requires the current person to enable the `hq-anywhere` setting in HQ. If that
 setting cannot be read, runtime access stays off.
 
@@ -34,8 +36,8 @@ stored in a repository or synced HQ folder.
 Windows requires Windows PowerShell 5.1 or PowerShell 7 for the bundled pipe
 host. If it is unavailable, the pipe cannot be created with a verified
 current-user-only DACL, or another process already owns the pipe name, hqd
-refuses to start. The `hq-anywhere-runtime` flag remains off by default on all
-platforms.
+refuses to start. The flag's missing-row fallback is on across platforms; an
+explicit false remains the operator kill switch.
 
 On macOS and Linux, hqd checks the socket directory and socket path with
 `lstat` before serving. It refuses symlinked, shared, or foreign-owned paths.

package/package.json

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