@indigoai-us/hq-cli 5.313.0 → 5.315.0

package/dist/lib/lanes/keep-alive-audit.js

@@ -0,0 +1,370 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS } from "./keep-alive.js";
+import { LanesError } from "./errors.js";
+import { laneRunDir } from "./spawn.js";
+import { readAllLanes } from "./store.js";
+function readDoneClassifications(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const watcherLog = path.join(laneRunDir(root, laneId), "logs", "watcher.out");
+    if (!withinRoot(root, watcherLog)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher log path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(watcherLog);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher log must be a regular file: ${watcherLog}`, { lane_id: laneId, path: watcherLog });
+        }
+        const realPath = fs.realpathSync(watcherLog);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher log escapes the HQ root for ${laneId}`, { lane_id: laneId, path: watcherLog });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const atTimes = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.includes('"classification"'))
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (!isRecord(value) || value.state !== "done")
+                continue;
+            const at = parseTime(value.at);
+            if (at !== undefined)
+                atTimes.push(at);
+        }
+        catch (err) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Cannot parse lane watcher classification in ${watcherLog}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: watcherLog });
+        }
+    }
+    return atTimes.sort((a, b) => a - b);
+}
+const KEEP_ALIVE_ON_TIME_TOLERANCE_MS = 60_000;
+const KEEP_ALIVE_NOT_RESTARTED_GRACE_MS = 5 * 60_000;
+const LATE_KPI_THRESHOLD_MS = 10 * 60_000;
+const MAX_NEXT_CHECK_DELAY_MS = 24 * 60 * 60_000;
+const VERDICTS = [
+    "on_time",
+    "late",
+    "early_wake",
+    "message_wake",
+    "self_wake",
+    "early_by_keep_alive",
+    "not_restarted",
+    "waiting",
+];
+function parseTime(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function readStopEnvelopes(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const envelopeDir = path.join(laneRunDir(root, laneId), "envelopes");
+    if (!withinRoot(root, envelopeDir)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane envelope path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let names;
+    try {
+        const realDir = fs.realpathSync(envelopeDir);
+        if (!withinRoot(root, realDir)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane envelope directory escapes the HQ root for ${laneId}`, { lane_id: laneId });
+        }
+        names = fs.readdirSync(realDir).filter((name) => /^\d+\.json$/.test(name)).sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { allMtimes: [], stops: [] };
+        throw err;
+    }
+    const allMtimes = [];
+    const stops = [];
+    for (const name of names) {
+        const file = path.join(envelopeDir, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_envelope_invalid", `Lane envelope must be a regular file: ${file}`, { lane_id: laneId, path: file });
+        }
+        allMtimes.push(stat.mtimeMs);
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            throw new LanesError("keep_alive_audit_envelope_invalid", `Cannot parse lane envelope ${file}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: file });
+        }
+        if (!isRecord(raw) || raw.schema_version !== "hq-lane-envelope.v1") {
+            throw new LanesError("keep_alive_audit_envelope_invalid", `Lane envelope is not hq-lane-envelope.v1: ${file}`, { lane_id: laneId, path: file });
+        }
+        if (raw.decision !== "done" || raw.story_complete !== false)
+            continue;
+        stops.push({
+            mtimeMs: stat.mtimeMs,
+            ...(typeof raw.next_check_at === "string" ? { nextCheckAt: raw.next_check_at } : {}),
+        });
+    }
+    return { allMtimes: allMtimes.sort((a, b) => a - b), stops: stops.sort((a, b) => a.mtimeMs - b.mtimeMs) };
+}
+function readKeepAliveResumeEvents(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const eventsPath = path.join(laneRunDir(root, laneId), "watcher", "events.jsonl");
+    if (!withinRoot(root, eventsPath)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(eventsPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher events must be a regular file: ${eventsPath}`, { lane_id: laneId, path: eventsPath });
+        }
+        const realPath = fs.realpathSync(eventsPath);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event file escapes the HQ root for ${laneId}`, { lane_id: laneId, path: eventsPath });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const events = [];
+    const lines = text.split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (err) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Cannot parse lane watcher event ${eventsPath}:${index + 1}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        if (!isRecord(value) || value.event !== "keep_alive_resume")
+            continue;
+        const at = parseTime(value.at);
+        if (at === undefined) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Keep-alive resume event has invalid timing fields: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        const nextEligibleAt = parseTime(value.next_eligible_at);
+        if (nextEligibleAt === undefined && value.resumed_from === "blocked")
+            continue;
+        if (nextEligibleAt === undefined) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Keep-alive resume event has invalid timing fields: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        const reason = value.reason === "pending_work" || value.reason === "next_check_at_due" || value.reason === "backoff"
+            ? value.reason
+            : undefined;
+        events.push({ at, nextEligibleAt, ...(reason === undefined ? {} : { reason }) });
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
+function dueTime(stop, resumeEvents) {
+    const previousResume = resumeEvents.filter((event) => event.at <= stop.mtimeMs).at(-1);
+    const terminalPlusBackoff = stop.mtimeMs + LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS;
+    let due = Math.max(terminalPlusBackoff, previousResume?.nextEligibleAt ?? 0);
+    let reason = "backoff";
+    const nextCheck = parseTime(stop.nextCheckAt);
+    if (nextCheck !== undefined && nextCheck > stop.mtimeMs) {
+        due = Math.max(due, Math.min(nextCheck, stop.mtimeMs + MAX_NEXT_CHECK_DELAY_MS));
+        reason = "next_check_at";
+    }
+    return { at: due, reason };
+}
+function hasDeliveredDropboxEvidence(hqRoot, laneId, stoppedAt, restartAt) {
+    const root = fs.realpathSync(hqRoot);
+    const delivered = path.join(laneRunDir(root, laneId), "dropbox", "delivered");
+    if (!withinRoot(root, delivered)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane delivered dropbox path escapes the HQ root for ${laneId}`, { lane_id: laneId, path: delivered });
+    }
+    let names;
+    try {
+        const stat = fs.lstatSync(delivered);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane delivered dropbox path must be a directory: ${delivered}`, { lane_id: laneId, path: delivered });
+        }
+        const realDir = fs.realpathSync(delivered);
+        if (!withinRoot(root, realDir)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane delivered dropbox path escapes the HQ root for ${laneId}`, { lane_id: laneId, path: delivered });
+        }
+        names = fs.readdirSync(realDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    return names.some((name) => {
+        const file = path.join(delivered, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return false;
+        const realFile = fs.realpathSync(file);
+        if (!withinRoot(root, realFile))
+            return false;
+        return stat.mtimeMs >= stoppedAt && stat.mtimeMs <= restartAt + 2 * 60_000;
+    });
+}
+function firstRestartAfter(lane, stop, nextEnvelopeMs) {
+    const restart = (lane.resume_history ?? [])
+        .map((entry) => ({ entry, at: parseTime(entry.at) }))
+        .filter(({ entry, at }) => at !== undefined && at > stop.mtimeMs && (nextEnvelopeMs === undefined || at < nextEnvelopeMs) && typeof entry.trigger === "string")
+        .sort((a, b) => a.at - b.at)[0];
+    if (!restart || restart.at === undefined)
+        return null;
+    return {
+        at: iso(restart.at),
+        trigger: restart.entry.trigger,
+        caller: typeof restart.entry.caller === "string" ? restart.entry.caller : null,
+    };
+}
+function classifyVerdict(input) {
+    const { dueAt, restart, lane, nowMs } = input;
+    if (restart) {
+        const restartAt = Date.parse(restart.at);
+        if (restart.caller === lane.lane_id)
+            return "self_wake";
+        if (restart.trigger === "keep_alive") {
+            const event = input.resumeEvents
+                .filter((candidate) => candidate.at > input.stoppedAt && Math.abs(candidate.at - restartAt) <= 2 * 60_000)
+                .sort((left, right) => Math.abs(left.at - restartAt) - Math.abs(right.at - restartAt))[0];
+            if (event?.reason === "pending_work")
+                return "message_wake";
+            if (event?.reason === undefined && hasDeliveredDropboxEvidence(input.hqRoot, lane.lane_id, input.stoppedAt, restartAt)) {
+                return "message_wake";
+            }
+            const nextCheckAt = parseTime(input.nextCheckAt);
+            if (nextCheckAt !== undefined && nextCheckAt > input.stoppedAt && restartAt < Math.min(nextCheckAt, input.stoppedAt + MAX_NEXT_CHECK_DELAY_MS)) {
+                return "early_by_keep_alive";
+            }
+            if (restartAt < dueAt - KEEP_ALIVE_ON_TIME_TOLERANCE_MS)
+                return "early_by_keep_alive";
+            if (restartAt <= dueAt + KEEP_ALIVE_ON_TIME_TOLERANCE_MS)
+                return "on_time";
+            return "late";
+        }
+        if (restartAt < dueAt)
+            return "early_wake";
+        return "late";
+    }
+    if (lane.state === "done" && nowMs > dueAt + KEEP_ALIVE_NOT_RESTARTED_GRACE_MS)
+        return "not_restarted";
+    return "waiting";
+}
+export function buildKeepAliveAudit(input) {
+    const nowMs = input.now.getTime();
+    const sinceMs = input.since === undefined
+        ? nowMs - 24 * 60 * 60_000
+        : parseTime(input.since);
+    if (sinceMs === undefined || !Number.isFinite(sinceMs)) {
+        throw new LanesError("invalid_since", "--since must be a valid ISO date-time", { since: input.since });
+    }
+    const lanes = readAllLanes(input.hqRoot).filter((lane) => (input.laneId === undefined || lane.lane_id === input.laneId) &&
+        typeof lane.hire_grant === "number" && Number.isFinite(lane.hire_grant) && lane.hire_grant > 0);
+    const rows = [];
+    const errors = [];
+    for (const lane of lanes) {
+        try {
+            const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
+            const keepAliveResumeEvents = readKeepAliveResumeEvents(input.hqRoot, lane.lane_id);
+            const doneClassifications = readDoneClassifications(input.hqRoot, lane.lane_id);
+            for (const stop of stops) {
+                if (stop.mtimeMs < sinceMs || stop.mtimeMs > nowMs)
+                    continue;
+                if (!doneClassifications.some((at) => at >= stop.mtimeMs && at - stop.mtimeMs <= 10 * 60_000))
+                    continue;
+                const nextEnvelopeMs = allMtimes.find((mtime) => mtime > stop.mtimeMs);
+                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs);
+                const due = dueTime(stop, keepAliveResumeEvents);
+                rows.push({
+                    lane: lane.lane_id,
+                    project: lane.project_id,
+                    profile: lane.worker_profile ?? lane.worker ?? null,
+                    stopped_at: iso(stop.mtimeMs),
+                    next_check_at: stop.nextCheckAt ?? null,
+                    due_at: iso(due.at),
+                    due_reason: due.reason,
+                    restart,
+                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, hqRoot: input.hqRoot }),
+                });
+            }
+        }
+        catch (err) {
+            const auditError = err instanceof LanesError
+                ? err
+                : new LanesError("keep_alive_audit_read_failed", `Unable to read keep-alive audit inputs for ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: lane.lane_id, path: laneRunDir(input.hqRoot, lane.lane_id) });
+            errors.push({
+                lane: lane.lane_id,
+                error: auditError.error,
+                path: typeof auditError.details.path === "string" ? auditError.details.path : laneRunDir(input.hqRoot, lane.lane_id),
+                message: auditError.message,
+            });
+        }
+    }
+    rows.sort((a, b) => a.stopped_at.localeCompare(b.stopped_at) || a.lane.localeCompare(b.lane));
+    const byVerdict = Object.fromEntries(VERDICTS.map((verdict) => [verdict, 0]));
+    let lateOverTenMinutes = 0;
+    for (const row of rows) {
+        byVerdict[row.verdict] += 1;
+        if (row.verdict === "late" && row.restart && Date.parse(row.restart.at) - Date.parse(row.due_at) > LATE_KPI_THRESHOLD_MS) {
+            lateOverTenMinutes += 1;
+        }
+    }
+    return {
+        ok: true,
+        since: iso(sinceMs),
+        rows,
+        summary: {
+            by_verdict: byVerdict,
+            not_restarted: byVerdict.not_restarted,
+            late_over_10m: lateOverTenMinutes,
+            early_wake_by_others: byVerdict.early_wake,
+            self_wake: byVerdict.self_wake,
+            stopped_and_not_restarted_on_their_own: byVerdict.not_restarted + lateOverTenMinutes,
+        },
+        errors,
+    };
+}
+export function formatKeepAliveAuditText(result) {
+    const headings = ["LANE", "PROJECT", "PROFILE", "STOPPED", "NEXT_CHECK", "DUE", "RESTART", "VERDICT"];
+    const values = result.rows.map((row) => [
+        row.lane,
+        row.project,
+        row.profile ?? "—",
+        row.stopped_at,
+        row.next_check_at ?? "—",
+        row.due_at,
+        row.restart ? `${row.restart.at} ${row.restart.trigger}${row.restart.caller ? ` (${row.restart.caller})` : ""}` : "—",
+        row.verdict,
+    ]);
+    const widths = headings.map((heading, index) => Math.max(heading.length, ...values.map((row) => row[index].length)));
+    const tableLine = (row) => row.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
+    const counts = VERDICTS.map((verdict) => `${verdict}=${result.summary.by_verdict[verdict]}`).join(", ");
+    return [
+        tableLine(headings),
+        ...values.map(tableLine),
+        "",
+        `Since ${result.since}; ${counts}`,
+        `not_restarted=${result.summary.not_restarted}, late_over_10m=${result.summary.late_over_10m}, early_wake_by_others=${result.summary.early_wake_by_others}, self_wake=${result.summary.self_wake}`,
+        `Stopped and not restarted on their own: ${result.summary.stopped_and_not_restarted_on_their_own}`,
+        ...result.errors.map((error) => `Error ${error.lane} (${error.error}) at ${error.path}: ${error.message}`),
+    ].join("\n");
+}
+//# sourceMappingURL=keep-alive-audit.js.map

package/dist/lib/lanes/reconcile.js

@@ -27,7 +27,7 @@ import { checkLaneDiskSpace, configuredCodexRolloutHomes, lowDiskGuardEnabledFor
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { appendDropboxMessage } from "./dropbox.js";
 import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
-import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
@@ -2303,6 +2303,7 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
                 at: now.toISOString(),
                 attempt: (lane.keep_alive_resume_count ?? 0) + 1,
                 resumed_from: "blocked",
+                reason: "backoff",
                 ...(accountSelection !== undefined
                     ? { account_selection: keepAliveAccountSelectionEvidence(accountSelection) }
                     : {}),
@@ -2733,6 +2734,23 @@ async function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, fla
             continue;
         }
         const nextEligibleAt = new Date(nowMs + leadLaneKeepAliveBackoffMs(immediateFirstResumeEnabled ? attempt : attempt + 1)).toISOString();
+        let resumeReason = "backoff";
+        if (initialState === "done") {
+            if (hasPendingKeepAliveWork(hqRoot, current, questions)) {
+                resumeReason = "pending_work";
+            }
+            else {
+                const finalEnvelope = readLatestEnvelopeRecord(hqRoot, current.lane_id)?.envelope;
+                const nextCheckMs = Date.parse(finalEnvelope?.next_check_at ?? "");
+                const anchorMs = Date.parse(current.last_envelope?.at ?? current.updated_at);
+                if (Number.isFinite(nextCheckMs) && Number.isFinite(anchorMs)) {
+                    const cappedNextCheckMs = Math.min(nextCheckMs, anchorMs + LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS);
+                    if (cappedNextCheckMs > nextEligibleMs && cappedNextCheckMs <= nowMs) {
+                        resumeReason = "next_check_at_due";
+                    }
+                }
+            }
+        }
         const queuedCount = loadLaneRecords(hqRoot, summary).filter((queuedLane) => queuedLane.state === "queued" &&
             queuedLane.provider === current.provider &&
             laneRunsHere(queuedLane, deps.host) &&
@@ -3007,6 +3025,7 @@ async function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, fla
                 attempt,
                 next_eligible_at: nextEligibleAt,
                 resumed_from: resumedFrom,
+                reason: resumeReason,
                 ...(accountSelection !== undefined
                     ? { account_selection: keepAliveAccountSelectionEvidence(accountSelection) }
                     : {}),

package/dist/sentry.d.ts

@@ -1,5 +1,11 @@
-import * as Sentry from "@sentry/node";
 import type { ErrorEvent, EventHint, NodeOptions } from "@sentry/node";
+type SentryModule = typeof import("@sentry/node");
+/**
+ * The command graph touches the Sentry facade on normal startup for a
+ * breadcrumb and a final flush. Keep those operations inert until the SDK
+ * module is loaded; the first capture that needs it loads the SDK synchronously.
+ */
+export declare const Sentry: SentryModule;
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -18,5 +24,5 @@ export declare function epipeAwareBeforeSend(event: ErrorEvent, hint: EventHint)
 export declare function initSentry(overrides?: Partial<Pick<NodeOptions, "transport">>): void;
 /** Finish HQ's one per-invocation release-health session. */
 export declare function finishSentrySession(): void;
-export { Sentry };
+export {};
 //# sourceMappingURL=sentry.d.ts.map

package/dist/sentry.js

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import { createRequire } from "node:module";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
@@ -9,6 +9,60 @@ import { companySkillWrapperSentryTagsFor } from "./lib/company-skill-wrapper.js
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { incompleteInstallCaptureContext, incompleteInstallMessage, } from "./utils/incomplete-install-error.js";
 import { installTreeTornSentryTagsFor, sentryFingerprintFor, sentryMcpCollisionContextFor, } from "./utils/sentry-fingerprint.js";
+const inertSentryScope = {
+    setTag: () => inertSentryScope,
+    setUser: () => inertSentryScope,
+    addBreadcrumb: () => inertSentryScope,
+    clearBreadcrumbs: () => inertSentryScope,
+    setLevel: () => inertSentryScope,
+    setFingerprint: () => inertSentryScope,
+};
+const requireSentry = createRequire(import.meta.url);
+let sentryModule;
+let pendingSentryBreadcrumbs = [];
+function loadSentryModule() {
+    sentryModule ??= requireSentry("@sentry/node");
+    return sentryModule;
+}
+/**
+ * The command graph touches the Sentry facade on normal startup for a
+ * breadcrumb and a final flush. Keep those operations inert until the SDK
+ * module is loaded; the first capture that needs it loads the SDK synchronously.
+ */
+export const Sentry = new Proxy({}, {
+    get(_target, property) {
+        if (property === Symbol.toStringTag)
+            return "Module";
+        if (property === "addBreadcrumb") {
+            return (breadcrumb) => {
+                if (sentryModule) {
+                    sentryModule.addBreadcrumb(breadcrumb);
+                    return;
+                }
+                if (pendingSentryBreadcrumbs.length >= 100)
+                    pendingSentryBreadcrumbs.shift();
+                pendingSentryBreadcrumbs.push(breadcrumb);
+            };
+        }
+        if (property === "withScope") {
+            return (callback) => {
+                if (sentryModule)
+                    return sentryModule.withScope(callback);
+                return callback(inertSentryScope);
+            };
+        }
+        if (property === "flush") {
+            return (timeout) => {
+                if (!sentryModule)
+                    return Promise.resolve(true);
+                return sentryModule.flush(timeout);
+            };
+        }
+        const sdk = loadSentryModule();
+        const value = Reflect.get(sdk, property);
+        return typeof value === "function" ? value.bind(sdk) : value;
+    },
+});
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -172,7 +226,8 @@ export function initSentry(overrides = {}) {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
         return;
-    Sentry.init({
+    const sdk = loadSentryModule();
+    sdk.init({
         dsn,
         // import-in-the-middle's async ESM loader makes every later CLI import
         // substantially slower. Keep HQ's explicit breadcrumbs, but give up
@@ -197,15 +252,17 @@ export function initSentry(overrides = {}) {
     // logged in). A CLI process is one user, so global setUser is correct here.
     const user = getCachedSentryUser();
     if (user)
-        Sentry.setUser(user);
+        sdk.setUser(user);
+    for (const breadcrumb of pendingSentryBreadcrumbs)
+        sdk.addBreadcrumb(breadcrumb);
+    pendingSentryBreadcrumbs = [];
     // Release health: one session per CLI run. Ended + flushed in index.ts's
     // finally (covers every exit path). A captured error auto-marks the session
     // "errored", so crash-free numbers per release stay accurate.
-    Sentry.startSession();
+    sdk.startSession();
 }
 /** Finish HQ's one per-invocation release-health session. */
 export function finishSentrySession() {
-    Sentry.endSession();
+    sentryModule?.endSession();
 }
-export { Sentry };
 //# sourceMappingURL=sentry.js.map

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

@@ -1,13 +1,14 @@
 import { type FirstSyncStepOutcome } from "../lib/first-sync-next-step.js";
-export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, type FirstSyncStepOutcome, } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, type FirstSyncStepOutcome, } from "../lib/first-sync-next-step.js";
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
  * `--json`. Keep this notice and its marker stable for session telemetry;
- * first-sync and feature-used fields have separate opt-in disclosures below.
+ * first-sync and feature-used fields have separate disclosures below; only
+ * feature-used telemetry remains opt-in.
  */
 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; when enabled, first-sync guidance shown or followed and the flag key 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 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_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 declare const CLI_LIMIT_AT_ACTION_PROMPT_FLAG = "billing.limit-at-action-prompt";

package/dist/utils/cli-telemetry.js

@@ -6,16 +6,17 @@ import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, loadMachineCachedTokens, } from "./cognito-session.js";
 import { resolveProcessFlagCompanyContext, resolveProcessFlagGate, } from "../lib/flag-registry.js";
 import { vaultApiFetch } from "./vault-api.js";
-import { firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
-export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
+import { firstSyncStepTelemetryProperties, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
  * `--json`. Keep this notice and its marker stable for session telemetry;
- * first-sync and feature-used fields have separate opt-in disclosures below.
+ * first-sync and feature-used fields have separate disclosures below; only
+ * feature-used telemetry remains opt-in.
  */
 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; when enabled, first-sync guidance shown or followed and the flag key 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 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_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"]);
@@ -289,8 +290,6 @@ export async function emitCliFirstSyncNextStepOutcome(outcome, timeoutMs = TELEM
     try {
         if (isCliTelemetryDisabled())
             return;
-        if (!isFirstSyncNextStepEnabled())
-            return;
         const cached = loadCachedTokens();
         const machineIdentity = isMachineIdentity();
         if (!cached ||

package/package.json

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