@indigoai-us/hq-cli 5.321.0 → 5.323.0

package/dist/lib/cli-invite-nudge.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { isExpiring, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
+import { queueCliInviteNudgeEvent } from "../utils/cli-telemetry.js";
+import { resolveCompanyFlagGate } from "./flag-registry.js";
+import { isHumanInteractiveCliSession } from "./first-sync-next-step.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+export const CLI_INVITE_NUDGE_FLAG = "cli.first-sync-invite-teammate-v1";
+function reportFailure(operation, error) {
+    const name = error instanceof Error ? error.name : "unknown";
+    const code = /^[A-Za-z][A-Za-z0-9]{0,39}$/.test(name) ? name : "unknown";
+    console.error(`hq: Could not ${operation} (${code}); invite prompt stays hidden.`);
+}
+/** One eligible, successful work-bearing company sync can show one prompt per company. */
+export async function runCliInviteNudge(input) {
+    if (!input.interactive || !input.canPrompt || input.alreadyShown || !/^cmp_[A-Za-z0-9_-]{1,128}$/.test(input.companyUid)) {
+        return false;
+    }
+    let enabled;
+    try {
+        enabled = await input.flagEnabled();
+    }
+    catch (error) {
+        (input.reportFailure ?? reportFailure)("resolve the invite flag", error);
+        return false;
+    }
+    if (!enabled)
+        return false;
+    let humanMemberCount;
+    try {
+        humanMemberCount = await input.readHumanMemberCount();
+    }
+    catch (error) {
+        (input.reportFailure ?? reportFailure)("check company membership", error);
+        return false;
+    }
+    if (humanMemberCount !== 1 || !input.claimShown())
+        return false;
+    input.write("Your company has one member. Invite a teammate to share the workspace.");
+    input.record(input.companyUid, "shown");
+    let clicked;
+    try {
+        clicked = await input.ask("Show the existing invite command? [y/N] ");
+    }
+    catch (error) {
+        (input.reportFailure ?? reportFailure)("read the invite choice", error);
+        return true;
+    }
+    input.record(input.companyUid, clicked ? "clicked" : "dismissed");
+    if (clicked) {
+        input.write(`Run: hq members invite <email> --company ${input.companyRef} --role member`);
+    }
+    return true;
+}
+function inviteNudgeMarkerPath(companyUid, home = process.env.HOME?.trim() || os.homedir()) {
+    const digest = createHash("sha256").update(companyUid).digest("hex");
+    return path.join(home, ".hq", "cli-invite-nudge", `${digest}.shown`);
+}
+function markerExists(companyUid) {
+    try {
+        return fs.existsSync(inviteNudgeMarkerPath(companyUid));
+    }
+    catch (error) {
+        reportFailure("read invite prompt state", error);
+        return true;
+    }
+}
+function claimMarker(companyUid) {
+    const marker = inviteNudgeMarkerPath(companyUid);
+    const homeHq = path.join(process.env.HOME?.trim() || os.homedir(), ".hq");
+    try {
+        // Do not create ~/.hq for a machine without a signed-in person profile.
+        if (!fs.existsSync(homeHq))
+            return false;
+        fs.mkdirSync(path.dirname(marker), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(marker, `${new Date().toISOString()}\n`, { flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") {
+            return false;
+        }
+        reportFailure("write invite prompt state", error);
+        return false;
+    }
+}
+async function readActiveHumanMemberCount(accessToken, companyUid) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1_200);
+    try {
+        const response = await vaultApiFetch({
+            token: accessToken,
+            path: `/membership/company/${encodeURIComponent(companyUid)}`,
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`http_${response.status}`);
+        const body = await response.json();
+        if (!Array.isArray(body.members))
+            throw new Error("invalid_roster_shape");
+        return body.members.filter((member) => typeof member === "object" && member !== null &&
+            member.status === "active" &&
+            typeof member.personUid === "string" &&
+            member.personUid.startsWith("prs_")).length;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function askInviteChoice(prompt) {
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await terminal.question(prompt);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        terminal.close();
+    }
+}
+/** Called after a successful work-bearing company sync; every dependency remains fail-closed. */
+export async function maybeShowCliInviteNudge(input) {
+    const companyUid = input.companyUid?.trim() ?? "";
+    const companyRef = input.companyRef?.trim() ?? "";
+    if (!companyUid || !companyRef)
+        return false;
+    const cached = loadCachedTokens();
+    if (!cached || isExpiring(cached, 120) ||
+        !isHumanInteractiveCliSession({
+            stdoutIsTTY: Boolean(process.stdout.isTTY),
+            argv: process.argv,
+            env: process.env,
+            machineIdentity: isMachineIdentity(),
+        }))
+        return false;
+    return runCliInviteNudge({
+        companyUid,
+        companyRef,
+        interactive: true,
+        canPrompt: process.stdin.isTTY === true,
+        alreadyShown: markerExists(companyUid),
+        flagEnabled: () => resolveCompanyFlagGate(companyUid, cached.idToken ?? "", CLI_INVITE_NUDGE_FLAG, { fallback: false }, () => false),
+        readHumanMemberCount: () => readActiveHumanMemberCount(input.accessToken, companyUid),
+        claimShown: () => claimMarker(companyUid),
+        ask: askInviteChoice,
+        write: (line) => console.log(line),
+        record: queueCliInviteNudgeEvent,
+    });
+}
+//# sourceMappingURL=cli-invite-nudge.js.map

package/dist/lib/daemon/requests.d.ts

@@ -22,6 +22,7 @@ export type ControlRequest = {
 /** Restart the whole daemon, for example after the updater installed a new CLI. */
  | {
     action: "restart-daemon";
+    deferUntilSyncIdle?: boolean;
 };
 export declare function writeControlRequest(dir: string, request: ControlRequest, now?: () => number): string;
 export declare function takeControlRequests(dir: string): ControlRequest[];

package/dist/lib/daemon/requests.js

@@ -18,7 +18,7 @@ function isControlRequest(value) {
     if (v.action === "trigger" || v.action === "stop")
         return typeof v.unit === "string";
     if (v.action === "restart-daemon")
-        return true;
+        return v.deferUntilSyncIdle === undefined || typeof v.deferUntilSyncIdle === "boolean";
     if (v.action === "reconcile")
         return true;
     return false;

package/dist/lib/daemon/run.js

@@ -594,7 +594,7 @@ export async function runDaemon(opts) {
         }
     };
     // Set once the shutdown path exists below; a restart request before then is dropped.
-    let restartDaemon = () => { };
+    let restartDaemon = () => false;
     const supervisor = createSupervisor({
         machineType,
         host: opts.host,
@@ -730,12 +730,12 @@ export async function runDaemon(opts) {
         restartDaemon = () => {
             if (!restartsForParent(opts)) {
                 log("warn", "a restart was requested, but no service manager would start this daemon again; restart it yourself");
-                return;
+                return false;
             }
             if (stopping || restartPending)
-                return;
+                return true;
             restartPending = true;
-            void handoffWanted()
+            return handoffWanted()
                 .catch((err) => {
                 log("warn", `could not decide on a handoff; restarting every service: ${err.message}`);
                 return false;
@@ -745,6 +745,7 @@ export async function runDaemon(opts) {
                     handOver();
                 else
                     shutdown("restarting onto the updated CLI", RESTART_EXIT_CODE);
+                return true;
             });
         };
         process.on("SIGTERM", () => shutdown("received SIGTERM"));

package/dist/lib/daemon/succession.js

@@ -202,7 +202,7 @@ export async function stopOrphans(orphans, deps) {
         remaining = remaining.filter(same);
     }
     for (const r of remaining) {
-        deps.log("warn", `${r.id} (pid ${r.pid}) ignored SIGTERM; sending SIGKILL`);
+        deps.log("warn", `${r.id} (pid ${r.pid}) did not exit within ${graceMs / 1_000} s of SIGTERM; sending SIGKILL`);
         send(r, "SIGKILL");
     }
 }

package/dist/lib/daemon/supervisor.d.ts

@@ -26,6 +26,7 @@ import type { MachineType } from "./machine-type.js";
 import type { ControlRequest } from "./requests.js";
 import { syncPassResult } from "./sync-runner.js";
 export declare const STOP_ESCALATION_MS = 10000;
+export declare const CLI_UPDATE_SYNC_IDLE_MAX_MS: number;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export declare const HANDOFF_STAGGER_MS = 15000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
@@ -94,7 +95,7 @@ export interface SupervisorDeps {
     runInternal: (task: string) => Promise<boolean>;
     takeRequests: () => ControlRequest[];
     /** Restart the whole daemon process (a `restart-daemon` request). */
-    restartDaemon?: () => void;
+    restartDaemon?: () => void | boolean | Promise<boolean | void>;
     writeState: (state: DaemonState) => void;
     log: (level: "info" | "warn" | "error", msg: string) => void;
     now?: () => number;

package/dist/lib/daemon/supervisor.js

@@ -27,6 +27,7 @@ const BACKOFF_BASE_MS = 1_000;
 const BACKOFF_MAX_MS = 60_000;
 const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
+export const CLI_UPDATE_SYNC_IDLE_MAX_MS = 10 * 60_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
 const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
@@ -61,6 +62,13 @@ export function planKey(plan, cliVersion) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function lastProtocolHint(slot) {
+    if (slot.lastProtocolStatus)
+        return ` (last status: ${slot.lastProtocolStatus})`;
+    if (slot.lastProtocolLine)
+        return ` (last protocol line: ${slot.lastProtocolLine})`;
+    return "";
+}
 export function createSupervisor(deps) {
     const now = deps.now ?? Date.now;
     const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
@@ -81,6 +89,9 @@ export function createSupervisor(deps) {
     const live = new Set();
     let drained = null;
     let onDrained = null;
+    let deferredCliRestart = false;
+    let deferredCliRestartTimer;
+    let cliRestartInProgress = false;
     const snapshot = () => ({
         version: 1,
         pid: deps.pid,
@@ -108,6 +119,71 @@ export function createSupervisor(deps) {
             clearT(slot.heartbeatTimer);
         slot.heartbeatTimer = undefined;
     };
+    const clearDeferredCliRestart = () => {
+        deferredCliRestart = false;
+        if (deferredCliRestartTimer !== undefined)
+            clearT(deferredCliRestartTimer);
+        deferredCliRestartTimer = undefined;
+    };
+    const runDeferredCliRestart = () => {
+        if (!deferredCliRestart)
+            return;
+        clearDeferredCliRestart();
+        cliRestartInProgress = true;
+        const sync = [...slots.values()].find((slot) => slot.plan.service === "sync" && slot.child);
+        if (sync)
+            terminate(sync);
+        deps.log("info", "sync runner is between passes; restarting daemon onto the updated CLI");
+        const releaseHold = () => {
+            cliRestartInProgress = false;
+            const currentSync = [...slots.values()].find((slot) => slot.plan.service === "sync");
+            if (!currentSync)
+                return;
+            if (currentSync.child)
+                terminate(currentSync, () => activate(currentSync));
+            else
+                activate(currentSync);
+        };
+        try {
+            const result = deps.restartDaemon?.();
+            if (result === false)
+                releaseHold();
+            else if (result && typeof result === "object" && "then" in result) {
+                void Promise.resolve(result).then((accepted) => {
+                    if (accepted === false)
+                        releaseHold();
+                }).catch((err) => {
+                    deps.log("error", `CLI-update restart handoff failed: ${errorMessage(err)}`);
+                    releaseHold();
+                });
+            }
+        }
+        catch (err) {
+            deps.log("error", `CLI-update restart handoff failed: ${errorMessage(err)}`);
+            releaseHold();
+        }
+    };
+    const requestCliUpdateRestart = () => {
+        if (!deps.restartDaemon)
+            return;
+        const sync = [...slots.values()].find((slot) => slot.plan.service === "sync" && slot.child);
+        if (!sync) {
+            void deps.restartDaemon();
+            return;
+        }
+        if (sync.syncPassActive === false) {
+            deferredCliRestart = true;
+            runDeferredCliRestart();
+            return;
+        }
+        if (deferredCliRestart) {
+            deps.log("info", "coalescing CLI-update restart while waiting for sync to become idle");
+            return;
+        }
+        deferredCliRestart = true;
+        deps.log("info", "deferring CLI-update restart until sync is idle (maximum 10 minutes)");
+        deferredCliRestartTimer = setT(runDeferredCliRestart, CLI_UPDATE_SYNC_IDLE_MAX_MS);
+    };
     const setBlocked = (slot) => {
         const block = slot.plan.blocked;
         slot.state.status = block.state;
@@ -136,6 +212,12 @@ export function createSupervisor(deps) {
             then?.();
             return;
         }
+        if (slot.expectingExit) {
+            // Keep the original stop deadline and signal; only update the action
+            // that runs after exit (for example, start the changed command).
+            slot.afterExit = then;
+            return;
+        }
         slot.expectingExit = true;
         slot.afterExit = then;
         if (slot.killTimer !== undefined)
@@ -145,7 +227,7 @@ export function createSupervisor(deps) {
                 slot.killTimer = undefined;
                 if (slot.child !== child)
                     return;
-                deps.log("warn", `${slot.plan.id} ignored SIGTERM; sending SIGKILL`);
+                deps.log("warn", `${slot.plan.id} did not exit within ${STOP_ESCALATION_MS / 1_000} s of SIGTERM; sending SIGKILL${lastProtocolHint(slot)}`);
                 signalChild(slot, child, "SIGKILL");
             }, STOP_ESCALATION_MS);
         };
@@ -211,6 +293,25 @@ export function createSupervisor(deps) {
             }
             if (!event)
                 return;
+            slot.lastProtocolLine = line.length > 240 ? `${line.slice(0, 237)}...` : line;
+            if (slot.plan.service === "sync") {
+                if (event.type === "fanout-plan")
+                    slot.syncPassActive = true;
+                else if (event.type === "all-complete")
+                    slot.syncPassActive = false;
+                else if (event.type === "status" && typeof event.state === "string") {
+                    slot.lastProtocolStatus = event.state;
+                    if (event.state === "stopped" || event.state === "waiting-for-lock")
+                        slot.syncPassActive = false;
+                    else if (slot.syncPassActive === undefined && (event.state === "starting" || event.state === "running")) {
+                        // Before the first pass boundary, status heartbeats cannot prove
+                        // that startup work has not already entered a pass.
+                        slot.syncPassActive = true;
+                    }
+                }
+                if (deferredCliRestart && slot.syncPassActive === false)
+                    runDeferredCliRestart();
+            }
             const at = now();
             slot.state.lastHeartbeatAt = new Date(at).toISOString();
             const pass = syncPassResult(event, slot.state.lastHeartbeatAt);
@@ -358,6 +459,15 @@ export function createSupervisor(deps) {
     const startLong = (slot) => {
         if (stopped)
             return;
+        if (cliRestartInProgress && slot.plan.service === "sync") {
+            slot.state.status = "waiting";
+            slot.state.reason = "daemon restart pending";
+            delete slot.state.nextRunAt;
+            return;
+        }
+        delete slot.lastProtocolLine;
+        delete slot.lastProtocolStatus;
+        delete slot.syncPassActive;
         let child;
         try {
             child = deps.spawn(slot.plan);
@@ -550,7 +660,10 @@ export function createSupervisor(deps) {
                 deps.log("info", `restarting ${plan.id}: its command changed`);
                 existing.attempts = 0;
                 existing.state.restarts = 0;
-                terminate(existing, () => activate(existing));
+                if (cliRestartInProgress && plan.service === "sync")
+                    terminate(existing);
+                else
+                    terminate(existing, () => activate(existing));
             }
         }
         slots = next;
@@ -650,11 +763,19 @@ export function createSupervisor(deps) {
             return;
         }
         if (req.action === "restart-daemon") {
-            deps.log("info", "restarting the daemon (requested)");
-            if (deps.restartDaemon)
-                deps.restartDaemon();
-            else
+            if (req.deferUntilSyncIdle && deps.restartDaemon) {
+                deps.log("info", "CLI-update daemon restart requested");
+                requestCliUpdateRestart();
+            }
+            else if (deps.restartDaemon) {
+                deps.log("info", "restarting the daemon (requested)");
+                clearDeferredCliRestart();
+                void deps.restartDaemon();
+            }
+            else {
+                deps.log("info", "restarting the daemon (requested)");
                 deps.log("warn", "this daemon cannot restart itself; restart it to load the new version");
+            }
             return;
         }
         // A bot created since the last plan read is asked for before the timer
@@ -756,7 +877,11 @@ export function createSupervisor(deps) {
                 clearT(requestTimer);
             if (handoffTimer !== undefined)
                 clearT(handoffTimer);
+            clearDeferredCliRestart();
+            const childOwners = new Map();
             for (const slot of slots.values()) {
+                if (slot.child)
+                    childOwners.set(slot.child, slot);
                 clearTimer(slot);
                 clearHeartbeatTimer(slot);
                 slot.child = undefined;
@@ -784,7 +909,8 @@ export function createSupervisor(deps) {
                 }
                 const escalation = setT(() => {
                     for (const child of live) {
-                        deps.log("warn", `pid ${child.pid ?? "?"} ignored SIGTERM; sending SIGKILL`);
+                        const owner = childOwners.get(child);
+                        deps.log("warn", `${owner?.plan.id ?? `pid ${child.pid ?? "?"}`} did not exit within ${STOP_ESCALATION_MS / 1_000} s of SIGTERM; sending SIGKILL${owner ? lastProtocolHint(owner) : ""}`);
                         try {
                             child.kill("SIGKILL");
                         }
@@ -818,6 +944,7 @@ export function createSupervisor(deps) {
                 clearT(requestTimer);
             if (handoffTimer !== undefined)
                 clearT(handoffTimer);
+            clearDeferredCliRestart();
             for (const slot of slots.values()) {
                 clearTimer(slot);
                 if (slot.killTimer !== undefined)

package/dist/lib/first-sync-next-step.d.ts

@@ -12,7 +12,15 @@ export declare function shouldConfirmFirstWorkBearingSync(input: {
     alreadyCompleted: boolean;
     workBearing: boolean;
 }): boolean;
-export declare function isWorkBearingSyncResult(result: Record<string, unknown>): boolean;
+interface WorkBearingSyncResult {
+    aborted?: unknown;
+    filesUploaded?: unknown;
+    filesDownloaded?: unknown;
+    sessionLogUploadedCount?: unknown;
+    filesDeleted?: unknown;
+    tombstonedCount?: unknown;
+}
+export declare function isWorkBearingSyncResult(result: WorkBearingSyncResult): boolean;
 export declare function isHumanInteractiveCliSession(input: {
     stdoutIsTTY: boolean;
     argv: readonly string[];
@@ -31,4 +39,5 @@ export declare function maybeShowFirstSyncNextStep(): boolean;
 export declare function recordFirstWorkBearingSync(result: Record<string, unknown>): boolean;
 /** Drain outcomes once so each shown/followed event is sent at most once per run. */
 export declare function takeFirstSyncStepOutcomes(): FirstSyncStepOutcome[];
+export {};
 //# sourceMappingURL=first-sync-next-step.d.ts.map

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -24,6 +24,8 @@ export declare const FLUSH_INTERVAL_MS = 10000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export declare const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
 export declare const DEVICE_DEFAULT_MEMBERSHIP_TIMEOUT_MS = 2000;
+/** Three sequential async shutdown steps must finish within six seconds. */
+export declare const SHUTDOWN_STEP_TIMEOUT_MS = 2000;
 /** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */
 export declare const DAEMON_VERSION_DRIFT_EXIT_CODE = 75;
 /**

package/dist/lib/mesh/live/daemon/run.js

@@ -45,6 +45,8 @@ export const FLUSH_INTERVAL_MS = 10_000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
 export const DEVICE_DEFAULT_MEMBERSHIP_TIMEOUT_MS = 2_000;
+/** Three sequential async shutdown steps must finish within six seconds. */
+export const SHUTDOWN_STEP_TIMEOUT_MS = 2_000;
 /** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */
 export const DAEMON_VERSION_DRIFT_EXIT_CODE = 75;
 /**
@@ -871,29 +873,48 @@ export async function runMeshDaemon(deps = {}) {
         catch {
             /* ignore */
         }
-        // Final flush, then clean MQTT DISCONNECT so the broker emits the
-        // lifecycle event; offline is published server-side only.
-        await doFlushCycle("shutdown", { force: true });
-        if (workCache) {
+        const stopStep = async (name, action) => {
+            let deadline;
+            let timedOut = false;
+            const timeout = new Promise((resolve) => {
+                deadline = timers.setTimeout(() => {
+                    timedOut = true;
+                    resolve();
+                }, SHUTDOWN_STEP_TIMEOUT_MS);
+            });
             try {
-                await workCache.stop();
+                await Promise.race([Promise.resolve().then(action), timeout]);
+                if (timedOut)
+                    log(dir, `${name} did not finish within ${SHUTDOWN_STEP_TIMEOUT_MS / 1_000} s; continuing shutdown`);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                log(dir, `work cache stop error: ${msg.slice(0, 120)}`);
+                log(dir, `${name} error: ${msg.slice(0, 120)}`);
+            }
+            finally {
+                if (deadline !== undefined)
+                    timers.clearTimeout(deadline);
             }
+        };
+        // Final flush, then clean MQTT DISCONNECT so the broker emits the
+        // lifecycle event; offline is published server-side only.
+        await stopStep("shutdown flush", () => doFlushCycle("shutdown", { force: true }));
+        if (workCache) {
+            await stopStep("work cache stop", () => workCache.stop());
         }
         if (presence) {
-            try {
-                await presence.stop();
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                log(dir, `presence stop error: ${msg.slice(0, 120)}`);
-            }
+            await stopStep("presence stop", () => presence.stop());
+        }
+        try {
+            patchDaemonState(dir, { mqttState: "closed", companiesOnline: [] }, now);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log(dir, `daemon shutdown state update error: ${msg.slice(0, 120)}`);
+        }
+        finally {
+            releasePidLock(dir, lockDeps);
         }
-        patchDaemonState(dir, { mqttState: "closed", companiesOnline: [] }, now);
-        releasePidLock(dir, lockDeps);
         log(dir, "daemon stopped");
     };
     const onSignal = () => {

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 {