@indigoai-us/hq-cli 5.322.0 → 5.324.0

package/dist/lib/registry/registry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Repo-to-company registry (hq-anywhere US-004).
+ *
+ * `~/.hq/registry.json` maps a folder to the HQ company it belongs to so a
+ * session started outside the HQ tree can bind without the user naming the
+ * company. Keys are either a normalised git remote (`remote:github.com/o/n`)
+ * or an absolute folder path (`path:/abs/dir`). Resolution never guesses:
+ * a folder with no matching entry resolves to `company: null` with a reason.
+ */
+import { type CompaniesManifestMap } from "../work-context/repo-remote.js";
+export type RegistrySource = "link" | "manifest" | "prompt";
+export interface RegistryEntry {
+    company: string;
+    source: RegistrySource;
+    linkedAt: string;
+}
+export interface Registry {
+    version: 1;
+    entries: Record<string, RegistryEntry>;
+}
+export type ResolveResult = {
+    company: string;
+    key: string;
+    source: RegistrySource;
+} | {
+    company: null;
+    reason: string;
+};
+export declare class RegistryFormatError extends Error {
+    constructor(file: string, detail: string);
+}
+/** Directory holding registry.json: HQ_REGISTRY_DIR, else ~/.hq (same parent as the work-mesh cache). */
+export declare function registryDir(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function registryFile(dir?: string): string;
+export declare function emptyRegistry(): Registry;
+/** Read the registry. A missing file is an empty registry; a malformed one throws. */
+export declare function readRegistry(file?: string): Registry;
+export declare function writeRegistry(registry: Registry, file?: string): void;
+export declare function remoteKey(normalized: string): string;
+export declare function pathKey(dir: string): string;
+/** Absolute, symlink-resolved directory path (falls back to path.resolve when missing). */
+export declare function canonicalDir(dir: string): string;
+/** Normalised origin remote for the repo enclosing `dir`, or null. */
+export declare function remoteForDir(dir: string): string | null;
+/**
+ * The key `hq link` writes for `dir`: the remote key when inside a git repo
+ * with a recognised origin, otherwise the path key (work-tree root when inside
+ * a repo without an origin, else the folder itself).
+ */
+export declare function keyForDir(dir: string): string;
+/** Every key that could describe `dir`, most specific first. */
+export declare function candidateKeys(dir: string): string[];
+/**
+ * Resolve the company for `dir`. Among matching keys the highest-ranked source
+ * wins (link > prompt > manifest); ties go to the more specific key.
+ */
+export declare function resolveCompanyForDir(registry: Registry, dir: string): ResolveResult;
+export declare function setEntry(registry: Registry, key: string, company: string, source: RegistrySource, now?: Date): RegistryEntry;
+/** Remove every key that describes `dir`. Returns the removed keys. */
+export declare function removeEntriesForDir(registry: Registry, dir: string): string[];
+export interface SeedResult {
+    added: string[];
+    owned: string[];
+    skippedLinked: string[];
+    ambiguous: string[];
+}
+/**
+ * Seed manifest-sourced entries from companies/manifest.yaml repos[]. Entries
+ * may be HQ-relative paths (`repos/private/x`), `owner/name`, or remote URLs.
+ * A local path seeds both its path key and, when it has an origin, its remote
+ * key. Never overwrites a `link` or `prompt` entry, and skips any key claimed
+ * by more than one company.
+ */
+export declare function seedFromManifest(registry: Registry, hqRoot: string, companies: CompaniesManifestMap, now?: Date): SeedResult;
+//# sourceMappingURL=registry.d.ts.map

package/dist/lib/registry/registry.js

@@ -0,0 +1,261 @@
+/**
+ * Repo-to-company registry (hq-anywhere US-004).
+ *
+ * `~/.hq/registry.json` maps a folder to the HQ company it belongs to so a
+ * session started outside the HQ tree can bind without the user naming the
+ * company. Keys are either a normalised git remote (`remote:github.com/o/n`)
+ * or an absolute folder path (`path:/abs/dir`). Resolution never guesses:
+ * a folder with no matching entry resolves to `company: null` with a reason.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { atomicWriteJson } from "../work-context/atomic.js";
+import { findEnclosingGitDir, findWorkTreeRoot, readOriginRemoteUrl, } from "../work-context/repo-remote.js";
+import { normalizeManifestRepo, normalizeRemoteUrl } from "./normalize-remote.js";
+/** Higher wins. An explicit `hq link` beats a prompt answer beats the manifest seed. */
+const SOURCE_RANK = { link: 3, prompt: 2, manifest: 1 };
+export class RegistryFormatError extends Error {
+    constructor(file, detail) {
+        super(`HQ registry at ${file} is unreadable: ${detail}`);
+        this.name = "RegistryFormatError";
+    }
+}
+/** Directory holding registry.json: HQ_REGISTRY_DIR, else ~/.hq (same parent as the work-mesh cache). */
+export function registryDir(home = os.homedir(), env = process.env) {
+    const override = env.HQ_REGISTRY_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(home, ".hq");
+}
+export function registryFile(dir = registryDir()) {
+    return path.join(dir, "registry.json");
+}
+export function emptyRegistry() {
+    return { version: 1, entries: {} };
+}
+function isSource(value) {
+    return value === "link" || value === "manifest" || value === "prompt";
+}
+/** Read the registry. A missing file is an empty registry; a malformed one throws. */
+export function readRegistry(file = registryFile()) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return emptyRegistry();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RegistryFormatError(file, err.message);
+    }
+    const rawEntries = parsed?.entries;
+    if (!rawEntries || typeof rawEntries !== "object" || Array.isArray(rawEntries)) {
+        throw new RegistryFormatError(file, "missing `entries` object");
+    }
+    const entries = {};
+    for (const [key, value] of Object.entries(rawEntries)) {
+        const rec = value;
+        if (!rec || typeof rec.company !== "string" || !rec.company || !isSource(rec.source)) {
+            throw new RegistryFormatError(file, `invalid entry for ${key}`);
+        }
+        entries[key] = {
+            company: rec.company,
+            source: rec.source,
+            linkedAt: typeof rec.linkedAt === "string" ? rec.linkedAt : "",
+        };
+    }
+    return { version: 1, entries };
+}
+export function writeRegistry(registry, file = registryFile()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const sorted = {};
+    for (const key of Object.keys(registry.entries).sort())
+        sorted[key] = registry.entries[key];
+    atomicWriteJson(file, { version: 1, entries: sorted });
+}
+export function remoteKey(normalized) {
+    return `remote:${normalized}`;
+}
+export function pathKey(dir) {
+    return `path:${canonicalDir(dir)}`;
+}
+/** Absolute, symlink-resolved directory path (falls back to path.resolve when missing). */
+export function canonicalDir(dir) {
+    const abs = path.resolve(dir);
+    try {
+        return fs.realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** Normalised origin remote for the repo enclosing `dir`, or null. */
+export function remoteForDir(dir) {
+    const gitDir = findEnclosingGitDir(dir);
+    if (!gitDir)
+        return null;
+    // Linked worktrees keep their config in the common dir.
+    const commonFile = path.join(gitDir, "commondir");
+    let configDir = gitDir;
+    try {
+        const common = fs.readFileSync(commonFile, "utf8").trim();
+        if (common)
+            configDir = path.resolve(gitDir, common);
+    }
+    catch {
+        // Not a linked worktree.
+    }
+    const origin = readOriginRemoteUrl(configDir) ?? readOriginRemoteUrl(gitDir);
+    return origin ? normalizeRemoteUrl(origin) : null;
+}
+/**
+ * The key `hq link` writes for `dir`: the remote key when inside a git repo
+ * with a recognised origin, otherwise the path key (work-tree root when inside
+ * a repo without an origin, else the folder itself).
+ */
+export function keyForDir(dir) {
+    const remote = remoteForDir(dir);
+    if (remote)
+        return remoteKey(remote);
+    return pathKey(findWorkTreeRoot(dir) ?? dir);
+}
+/** Every key that could describe `dir`, most specific first. */
+export function candidateKeys(dir) {
+    const keys = [pathKey(dir)];
+    const workTree = findWorkTreeRoot(dir);
+    if (workTree)
+        keys.push(pathKey(workTree));
+    const remote = remoteForDir(dir);
+    if (remote)
+        keys.push(remoteKey(remote));
+    return [...new Set(keys)];
+}
+/**
+ * Resolve the company for `dir`. Among matching keys the highest-ranked source
+ * wins (link > prompt > manifest); ties go to the more specific key.
+ */
+export function resolveCompanyForDir(registry, dir) {
+    let best = null;
+    for (const key of candidateKeys(dir)) {
+        const entry = registry.entries[key];
+        if (!entry)
+            continue;
+        if (!best || SOURCE_RANK[entry.source] > SOURCE_RANK[best.entry.source]) {
+            best = { key, entry };
+        }
+    }
+    if (!best) {
+        return {
+            company: null,
+            reason: `No HQ company is linked to ${canonicalDir(dir)}. Run \`hq link <company>\` there.`,
+        };
+    }
+    return { company: best.entry.company, key: best.key, source: best.entry.source };
+}
+export function setEntry(registry, key, company, source, now = new Date()) {
+    const entry = { company, source, linkedAt: now.toISOString() };
+    registry.entries[key] = entry;
+    return entry;
+}
+/** Remove every key that describes `dir`. Returns the removed keys. */
+export function removeEntriesForDir(registry, dir) {
+    const removed = [];
+    for (const key of candidateKeys(dir)) {
+        if (registry.entries[key]) {
+            delete registry.entries[key];
+            removed.push(key);
+        }
+    }
+    return removed;
+}
+/**
+ * Seed manifest-sourced entries from companies/manifest.yaml repos[]. Entries
+ * may be HQ-relative paths (`repos/private/x`), `owner/name`, or remote URLs.
+ * A local path seeds both its path key and, when it has an origin, its remote
+ * key. Never overwrites a `link` or `prompt` entry, and skips any key claimed
+ * by more than one company.
+ */
+export function seedFromManifest(registry, hqRoot, companies, now = new Date()) {
+    const claimGroups = [];
+    for (const [company, entry] of Object.entries(companies)) {
+        const repos = entry && typeof entry === "object" ? entry.repos : undefined;
+        if (!Array.isArray(repos))
+            continue;
+        for (const raw of repos) {
+            if (typeof raw !== "string" || !raw.trim())
+                continue;
+            const trimmed = raw.trim();
+            const local = path.isAbsolute(trimmed) ? trimmed : path.join(hqRoot, trimmed);
+            let isDir;
+            try {
+                isDir = fs.statSync(local).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (isDir) {
+                const keys = [pathKey(local)];
+                const remote = remoteForDir(local);
+                if (remote)
+                    keys.push(remoteKey(remote));
+                claimGroups.push({ company, keys });
+                continue;
+            }
+            const normalized = normalizeManifestRepo(trimmed);
+            if (normalized)
+                claimGroups.push({ company, keys: [remoteKey(normalized)] });
+        }
+    }
+    const claims = new Map();
+    for (const group of claimGroups) {
+        for (const key of group.keys) {
+            const set = claims.get(key) ?? new Set();
+            set.add(group.company);
+            claims.set(key, set);
+        }
+    }
+    const ambiguous = new Set([...claims].filter(([, companies]) => companies.size > 1).map(([key]) => key));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const group of claimGroups) {
+            if (group.keys.some((key) => ambiguous.has(key))) {
+                for (const key of group.keys) {
+                    if (!ambiguous.has(key)) {
+                        ambiguous.add(key);
+                        changed = true;
+                    }
+                }
+            }
+        }
+    }
+    const result = { added: [], owned: [], skippedLinked: [], ambiguous: [...ambiguous].sort() };
+    const unambiguousClaims = new Map();
+    for (const group of claimGroups) {
+        if (group.keys.some((key) => ambiguous.has(key)))
+            continue;
+        for (const key of group.keys)
+            unambiguousClaims.set(key, group.company);
+    }
+    for (const [key, company] of unambiguousClaims) {
+        const existing = registry.entries[key];
+        if (existing && existing.source !== "manifest") {
+            result.skippedLinked.push(key);
+            continue;
+        }
+        if (existing?.company !== company) {
+            setEntry(registry, key, company, "manifest", now);
+            result.added.push(key);
+        }
+        result.owned.push(key);
+    }
+    return result;
+}
+//# sourceMappingURL=registry.js.map

package/dist/main.js

@@ -44,7 +44,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliFirstSyncNextStepOutcome, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
+import { emitCliFirstSyncNextStepOutcome, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliInviteNudgeEvent, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takeCliInviteNudgeEvents, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -313,6 +313,7 @@ export async function runCli() {
             // slice even when the command itself was long-running.
             const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
             const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
+            const inviteNudgeOutcomeFlushes = takeCliInviteNudgeEvents().map((event) => emitCliInviteNudgeEvent(event, releaseHealthTimeoutMs));
             const inviteTeammateExposureFlushes = takePlanLimitInviteTeammateExposures().map((companyUid) => emitPlanLimitInviteTeammateExposure(companyUid, releaseHealthTimeoutMs));
             const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
             const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
@@ -322,6 +323,7 @@ export async function runCli() {
                     : [refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs })]),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
+                ...inviteNudgeOutcomeFlushes,
                 ...inviteTeammateExposureFlushes,
                 ...limitNoticeExposureFlushes,
                 ...limitNoticeEngagementFlushes,

package/dist/utils/cli-telemetry.d.ts

@@ -9,8 +9,14 @@ export declare const TELEMETRY_TIMEOUT_MS = 1200;
  */
 export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 export declare const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; first-sync guidance shown or followed, with the identifier cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export declare const CLI_INVITE_NUDGE_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when it shows the teammate invite prompt (your company UID and whether you saw, clicked, or dismissed the prompt; no invitee details, command names, file contents, or secrets). Set HQ_TELEMETRY=0 to turn this off.";
 export declare const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
 export declare const CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE = "HQ sends a feature-use event when you run a supported CLI feature (feature kind and outcome, plus your company UID when available; never command names, file contents, or secrets). The hq-flags key cli.feature-used-telemetry-v1 controls these events. Set HQ_TELEMETRY=0 to turn this off.";
+export type CliInviteNudgeOutcome = "shown" | "clicked" | "dismissed";
+export interface CliInviteNudgeEvent {
+    companyUid: string;
+    outcome: CliInviteNudgeOutcome;
+}
 export declare const CLI_LIMIT_AT_ACTION_PROMPT_FLAG = "billing.limit-at-action-prompt";
 export type CliLimitResourceKind = "users" | "integrations" | "secrets" | "agents" | "deployments" | "storageBytes";
 export type CliLimitPresentationKind = "advisory" | "refusal";
@@ -33,6 +39,11 @@ export declare function takeCliLimitNoticeEngagements(): CliLimitNoticeEngagemen
 export declare function queuePlanLimitInviteTeammateExposure(companyUid: string): void;
 /** Drain invite-suggestion exposures for the bounded command-finalization flush. */
 export declare function takePlanLimitInviteTeammateExposures(): string[];
+/** Queue one company-keyed CLI invite prompt outcome; no person UID is included in the event. */
+export declare function queueCliInviteNudgeEvent(companyUid: string, outcome: CliInviteNudgeOutcome): void;
+export declare function takeCliInviteNudgeEvents(): CliInviteNudgeEvent[];
+/** Emit a bounded CLI session fact through the existing product-telemetry path. */
+export declare function emitCliInviteNudgeEvent(event: CliInviteNudgeEvent, timeoutMs?: number): Promise<void>;
 export type CliFeatureKind = "secret_read" | "lane_create" | "lane_resume";
 export type CliFeatureOutcome = "success" | "failure";
 export interface CliFeatureUsage {

package/dist/utils/cli-telemetry.js

@@ -17,14 +17,17 @@ export const TELEMETRY_TIMEOUT_MS = 1_200;
  */
 export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 export const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; first-sync guidance shown or followed, with the identifier cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const CLI_INVITE_NUDGE_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when it shows the teammate invite prompt (your company UID and whether you saw, clicked, or dismissed the prompt; no invitee details, command names, file contents, or secrets). Set HQ_TELEMETRY=0 to turn this off.";
 export const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
 export const CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE = "HQ sends a feature-use event when you run a supported CLI feature (feature kind and outcome, plus your company UID when available; never command names, file contents, or secrets). The hq-flags key cli.feature-used-telemetry-v1 controls these events. Set HQ_TELEMETRY=0 to turn this off.";
 const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
 const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
 const FIRST_SYNC_DISCLOSURE_MARKER = "cli-telemetry-disclosed-first-sync-v1";
+const INVITE_NUDGE_DISCLOSURE_MARKER = "cli-telemetry-disclosed-invite-nudge-v1";
 const FEATURE_USED_DISCLOSURE_MARKER = "cli-telemetry-disclosed-feature-used-v1";
 let cliSessionStartedPromise;
 const pendingPlanLimitInviteTeammateExposures = [];
+const pendingCliInviteNudgeEvents = [];
 export const CLI_LIMIT_AT_ACTION_PROMPT_FLAG = "billing.limit-at-action-prompt";
 const pendingCliLimitNoticeExposures = [];
 const pendingCliLimitNoticeEngagements = [];
@@ -68,6 +71,73 @@ export function queuePlanLimitInviteTeammateExposure(companyUid) {
 export function takePlanLimitInviteTeammateExposures() {
     return pendingPlanLimitInviteTeammateExposures.splice(0, pendingPlanLimitInviteTeammateExposures.length);
 }
+/** Queue one company-keyed CLI invite prompt outcome; no person UID is included in the event. */
+export function queueCliInviteNudgeEvent(companyUid, outcome) {
+    if (!/^cmp_[A-Za-z0-9_-]{1,128}$/.test(companyUid))
+        return;
+    pendingCliInviteNudgeEvents.push({ companyUid, outcome });
+}
+export function takeCliInviteNudgeEvents() {
+    return pendingCliInviteNudgeEvents.splice(0, pendingCliInviteNudgeEvents.length);
+}
+/** Emit a bounded CLI session fact through the existing product-telemetry path. */
+export async function emitCliInviteNudgeEvent(event, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        const cached = loadCachedTokens();
+        if (!cached || isExpiring(cached, 120) || !cached.accessToken ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity: isMachineIdentity(),
+            }) || process.stdin.isTTY !== true)
+            return;
+        if (!maybeDiscloseInviteNudgeTelemetry())
+            return;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token: cached.accessToken,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [{
+                            eventName: "cli_session_started",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis: "disclosed",
+                            schemaVersion: 1,
+                            companyUid: event.companyUid,
+                            properties: {
+                                version: CLI_VERSION,
+                                step: "invite_teammate_nudge",
+                                outcome: event.outcome,
+                            },
+                        }],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                console.error(`hq: Could not send invite prompt telemetry (http_${response.status}).`);
+            }
+        }
+        catch (error) {
+            const errorClass = error instanceof Error ? error.name : "unknown";
+            console.error(`hq: Could not send invite prompt telemetry (${errorClass}).`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        console.error(`hq: Could not prepare invite prompt telemetry (${errorClass}).`);
+    }
+}
 const COMPANY_UID_PATTERN = /^cmp_[A-Za-z0-9_-]{1,128}$/;
 export function isCliLimitResourceKind(value) {
     return ["users", "integrations", "secrets", "agents", "deployments", "storageBytes"].includes(value);
@@ -172,6 +242,9 @@ export function telemetryDisclosureMarkerPath() {
 function firstSyncTelemetryDisclosureMarkerPath() {
     return path.join(hqConfigDir(), FIRST_SYNC_DISCLOSURE_MARKER);
 }
+function inviteNudgeTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), INVITE_NUDGE_DISCLOSURE_MARKER);
+}
 function featureUsedTelemetryDisclosureMarkerPath() {
     return path.join(hqConfigDir(), FEATURE_USED_DISCLOSURE_MARKER);
 }
@@ -212,6 +285,9 @@ export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = proc
 function maybeDiscloseFirstSyncTelemetry() {
     return maybeDiscloseTelemetry(FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE, firstSyncTelemetryDisclosureMarkerPath());
 }
+function maybeDiscloseInviteNudgeTelemetry() {
+    return maybeDiscloseTelemetry(CLI_INVITE_NUDGE_TELEMETRY_DISCLOSURE_LINE, inviteNudgeTelemetryDisclosureMarkerPath());
+}
 function maybeDiscloseFeatureUsedTelemetry() {
     return maybeDiscloseTelemetry(CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE, featureUsedTelemetryDisclosureMarkerPath());
 }

package/dist/utils/cognito-session.d.ts

@@ -237,6 +237,9 @@ export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?:
     home?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<T>;
+type MachineTokenValidityOptions = {
+    minValiditySeconds?: number;
+};
 /**
  * Ensure the current machine identity has a valid session and return only the
  * access/ID token pair needed by supported machine-session handoff scripts.
@@ -294,7 +297,8 @@ export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">): Promise<{
+type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource"> & MachineTokenValidityOptions;
+export declare function refreshCachedSession(options?: MachineRefreshOptions): Promise<{
     refreshed: boolean;
     reason?: string;
 }>;

package/dist/utils/cognito-session.js

@@ -837,8 +837,12 @@ function withTokenStateDirSection(fn) {
     tokenStateDirTail = run.catch(() => undefined);
     return run;
 }
-async function ensureMachineTokens() {
-    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO));
+const MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS = 1800;
+async function ensureMachineTokens(minValiditySeconds) {
+    const resolverMinimum = minValiditySeconds === undefined
+        ? undefined
+        : Math.min(minValiditySeconds, MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS);
+    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, resolverMinimum === undefined ? undefined : { minValiditySeconds: resolverMinimum }));
 }
 /**
  * Ensure the current machine identity has a valid session and return only the
@@ -857,7 +861,7 @@ async function ensureMachineTokensMaybeFallback(options = {}) {
     if (isDefaultMachineCredsFallback(options)) {
         logDefaultMachineCredsFallback();
     }
-    return ensureMachineTokens();
+    return ensureMachineTokens(options.minValiditySeconds);
 }
 /**
  * After a person-cache miss or refresh failure: if the default machine-creds
@@ -872,7 +876,7 @@ async function tryDefaultMachineCredsFallback(options = {}) {
     if (!isMachineIdentity())
         return null;
     logDefaultMachineCredsFallback();
-    return ensureMachineTokens();
+    return ensureMachineTokens(options.minValiditySeconds);
 }
 /**
  * True when a person-token refresh failed with a definitive Cognito auth
@@ -1114,14 +1118,6 @@ export function buildVaultConfig(authToken) {
         clientInfo: CLI_CLIENT_INFO,
     };
 }
-/**
- * Ensure a valid cached Cognito session exists right now, non-interactively,
- * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
- * bin. `refreshed: true` means a valid session is ensured now from a healthy
- * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
- * means no valid session could be ensured non-interactively; the caller gets a
- * reason string and can decide what to do next. Never opens a browser.
- */
 export async function refreshCachedSession(options = {}) {
     if (wantsMachineCognitoTokens(options))
         return refreshCachedSessionUnserialized(options);

package/dist/utils/feedback-diagnostics.d.ts

@@ -8,6 +8,8 @@ interface GitContext {
 }
 export interface DiagnosticsBlob {
     cliVersion: string;
+    /** Current npm release, included only when the feedback.latest-version flag is enabled. */
+    latestVersion?: string;
     /**
      * The hq-cli, hq-core, and hq-sync versions from the submitter's
      * environment. `cliVersion` above is retained for back-compat; new

package/dist/utils/run-bundled-script.d.ts

@@ -8,10 +8,11 @@
  *
  * Deliberate choices:
  *
- *   - `stdio: "inherit"`. Not piped. Piping would buffer output that callers
- *     stream, reorder stdout against stderr, and require re-emitting bytes we
- *     have no reason to touch. Inheriting also means a script that reads stdin
- *     (the hook payload pattern) gets the real fd, unbuffered and unconsumed.
+ *   - stdio inherits by default. Captured runs pipe only stdout/stderr, and
+ *     inherit stdin unless the caller supplies an explicit payload. Piping
+ *     output would buffer streams, reorder stdout against stderr, and require
+ *     re-emitting bytes, so capture remains an explicit opt-in for native
+ *     parity fallbacks that need the shell's exact output bytes.
  *
  *   - an explicit interpreter (`bash` or `node`) rather than executing the file
  *     directly. The executable bit does survive `npm publish` for files that
@@ -52,6 +53,8 @@ export type RunBundledScriptOptions = {
     env?: Record<string, string | undefined>;
     /** Capture stdout and stderr as bytes instead of inheriting those streams. */
     captureOutput?: boolean;
+    /** Bytes supplied on stdin. With no value, stdin is inherited as before. */
+    stdin?: string | Buffer;
 };
 export type RunBundledScriptResult = {
     /** The child's exit code, or 128+signal if it was terminated by one. */