@indigoai-us/hq-cli 5.345.43 → 5.345.45

package/dist/lib/lanes/store.js

@@ -392,6 +392,10 @@ export function parseLaneRecord(raw, filePath) {
             path: filePath,
         });
     }
+    // Company attribution was added after lane records already existed on disk.
+    // Treat its historical absence as the same unbound state as an explicit null.
+    if (raw.company === undefined)
+        raw.company = null;
     for (const field of REQUIRED_LANE_RECORD_FIELDS) {
         if (!(field in raw)) {
             throw new LaneSchemaError(`Missing required lane record field ${field}`, { path: filePath, field });
@@ -423,6 +427,31 @@ export function parseLaneRecord(raw, filePath) {
     requireInt(raw.version, "version");
     requireInt(raw.depth, "depth");
     requireInt(raw.priority, "priority");
+    if (raw.focus_overrides !== undefined) {
+        if (!Array.isArray(raw.focus_overrides) || raw.focus_overrides.length > 100) {
+            throw new LaneSchemaError("focus_overrides must be an array with at most 100 entries", {
+                path: filePath,
+                field: "focus_overrides",
+            });
+        }
+        for (const [index, entry] of raw.focus_overrides.entries()) {
+            if (!isPlainObject(entry)) {
+                throw new LaneSchemaError("focus_overrides entries must be objects", {
+                    path: filePath,
+                    field: `focus_overrides[${index}]`,
+                });
+            }
+            for (const field of ["reason", "by_lane", "story"]) {
+                if (typeof entry[field] !== "string" || !entry[field].trim()) {
+                    throw new LaneSchemaError(`focus_overrides[${index}].${field} must be non-empty`, {
+                        path: filePath,
+                        field: `focus_overrides[${index}].${field}`,
+                    });
+                }
+            }
+            requireTimestamp(entry.at, `focus_overrides[${index}].at`, filePath);
+        }
+    }
     if (raw.ended_at !== undefined) {
         requireTimestamp(raw.ended_at, "ended_at", filePath);
     }
@@ -442,6 +471,16 @@ export function parseLaneRecord(raw, filePath) {
             value: raw.hire_grant,
         });
     }
+    if (raw.released_hire_grant !== undefined &&
+        (typeof raw.released_hire_grant !== "number" ||
+            !Number.isSafeInteger(raw.released_hire_grant) ||
+            raw.released_hire_grant < 0)) {
+        throw new LaneSchemaError("Expected non-negative safe integer for released_hire_grant", {
+            path: filePath,
+            field: "released_hire_grant",
+            value: raw.released_hire_grant,
+        });
+    }
     if (raw.keep_alive !== undefined && typeof raw.keep_alive !== "boolean") {
         throw new LaneSchemaError("keep_alive must be a boolean", {
             path: filePath,
@@ -1603,6 +1642,31 @@ export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, dep
                 throw new LanesError("lane_writer_unauthorized", `Writer ${writer} cannot write lane field ${key}`, { writer, field: key });
             }
         }
+        if (!isTerminalLaneState(current.state) && isTerminalLaneState(updated.state)) {
+            const releasedGrant = updated.hire_grant ?? current.hire_grant ?? 0;
+            return {
+                ...updated,
+                released_hire_grant: releasedGrant,
+                hire_grant: 0,
+            };
+        }
+        if (isTerminalLaneState(current.state) && !isTerminalLaneState(updated.state) &&
+            current.released_hire_grant !== undefined) {
+            return {
+                ...updated,
+                hire_grant: current.released_hire_grant,
+                released_hire_grant: undefined,
+            };
+        }
+        if (isTerminalLaneState(updated.state) &&
+            (updated.hire_grant !== current.hire_grant ||
+                updated.released_hire_grant !== current.released_hire_grant)) {
+            return {
+                ...updated,
+                hire_grant: 0,
+                released_hire_grant: updated.released_hire_grant ?? updated.hire_grant ?? 0,
+            };
+        }
         return updated;
     }, deps, {
         beforeWrite: (current) => assertLaneStoreWriteAllowed(current, laneId, writer),

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

@@ -24,6 +24,20 @@ export interface StoryLedgerQuestionRef {
     project_id: string;
     story_id: string;
 }
+export interface ProjectFocusOverride {
+    reason: string;
+    by_lane: string;
+    at: string;
+    story: string;
+}
+export declare function readProjectStoryFocusData(hqRoot: string, projectId: string, companySlug?: string): {
+    path: string;
+    metadata: Record<string, unknown>;
+    userStories: Array<Record<string, unknown>>;
+    focusOverrides: ProjectFocusOverride[];
+};
+export declare function appendProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
+export declare function removeProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
 export interface LaneStatusSnapshot {
     schema_version: "hq-lanes-status.v1";
     project_id: string;

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

@@ -11,6 +11,52 @@ const LOCK_RETRY_MS = 10;
 const STORY_STATES = ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
 const MANAGER_OWNED_STATES = new Set(["review", "done", "dropped"]);
 const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
+function projectFocusOverrides(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 100) {
+        throw new LanesError("project_focus_overrides_invalid", "Project focus_overrides must be an array with at most 100 entries", {});
+    }
+    return value.map((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} must be an object`, {});
+        }
+        const entry = item;
+        if (["reason", "by_lane", "at", "story"].some((key) => typeof entry[key] !== "string" || !entry[key].trim())) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} is incomplete`, {});
+        }
+        if (!Number.isFinite(Date.parse(entry.at))) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} has an invalid timestamp`, {});
+        }
+        return entry;
+    });
+}
+export function readProjectStoryFocusData(hqRoot, projectId, companySlug) {
+    const ledger = resolveProjectStoryLedger(hqRoot, projectId, companySlug);
+    const parsed = readLedger(ledger);
+    const metadata = parsed.metadata;
+    return {
+        path: ledger.path,
+        metadata: metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+            ? metadata
+            : {},
+        userStories: parsed.userStories,
+        focusOverrides: projectFocusOverrides(parsed.focus_overrides),
+    };
+}
+export function appendProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const existing = projectFocusOverrides(current.focus_overrides);
+        return { ...current, focus_overrides: [...existing, override].slice(-100) };
+    });
+}
+export function removeProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const remaining = projectFocusOverrides(current.focus_overrides).filter((entry) => entry.reason !== override.reason || entry.by_lane !== override.by_lane ||
+            entry.at !== override.at || entry.story !== override.story);
+        return { ...current, focus_overrides: remaining };
+    });
+}
 export function laneStoryLedgerEnabled(companyUid) {
     return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false, companyUid);
 }

package/dist/lib/lanes/tracker-report.d.ts

@@ -12,10 +12,20 @@ interface TrackerReportStory {
     id: string;
     title: string;
     status: ReportStoryStatus;
+    focus_id?: unknown;
+    kpi?: unknown;
+    owner?: string | null;
+    deadline?: string | null;
     references?: string[];
     updated_at?: string;
     source_path: string;
 }
+export interface TrackerReportFocusOverride {
+    reason: string;
+    by_lane: string;
+    at: string;
+    story: string;
+}
 export interface TrackerReportIssue {
     path: string;
     field: string;
@@ -47,6 +57,7 @@ export interface TrackerReportTeamInput {
     team: string;
     project_id: string;
     stories: readonly TrackerReportStory[];
+    focus_overrides?: readonly TrackerReportFocusOverride[];
     pull_requests: readonly TrackerReportPullRequest[];
     releases: readonly TrackerReportRelease[];
     blockers: readonly TrackerReportRecord[];
@@ -61,8 +72,42 @@ export interface TrackerReportInput {
     generated_at: string;
     since: string;
     since_source: "explicit" | "previous_report" | "first_run";
+    focus_dashboard_enabled?: boolean;
     teams: readonly TrackerReportTeamInput[];
 }
+interface TrackerFocusItem {
+    team: string;
+    project_id: string;
+    story_id: string;
+    title: string;
+    owner: string | null;
+    deadline: string | null;
+    state: ReportStoryStatus;
+    focus_id: unknown;
+    kpi: unknown;
+    override_reason: string | null;
+}
+interface TrackerTeamFocusShare {
+    team: string;
+    project_id: string;
+    window_start: string;
+    window_end: string;
+    work_story_count: number;
+    focused_story_count: number;
+    share_percent: number | null;
+    status: "red" | "ok" | "no_work";
+}
+interface TrackerFocusOverride extends TrackerReportFocusOverride {
+    team: string;
+    project_id: string;
+}
+interface TrackerFocusDashboard {
+    window_start: string;
+    window_end: string;
+    focus_list: TrackerFocusItem[];
+    team_focus_shares: TrackerTeamFocusShare[];
+    overrides: TrackerFocusOverride[];
+}
 interface ReportTimedStory {
     id: string;
     title: string;
@@ -140,6 +185,7 @@ export interface TrackerOwnerReport {
     generated_at: string;
     since: string;
     since_source: TrackerReportInput["since_source"];
+    focus_dashboard?: TrackerFocusDashboard;
     teams: TrackerOwnerTeamReport[];
 }
 interface TrackerTeamKpi {

package/dist/lib/lanes/tracker-report.js

@@ -231,6 +231,73 @@ function validatedWindow(input) {
     }
     return { generatedAt, since, sinceTime, generatedAtTime };
 }
+function hasFocus(story) {
+    const present = (value) => typeof value === "string"
+        ? value.trim().length > 0
+        : value !== undefined && value !== null;
+    return present(story.focus_id) || present(story.kpi);
+}
+function recentlyWorked(story, sinceTime, throughTime) {
+    if (story.updated_at === undefined)
+        return false;
+    const at = Date.parse(validTimestamp(story.updated_at, "updated_at", story.source_path, { story_id: story.id }));
+    return at >= sinceTime && at <= throughTime;
+}
+function buildFocusDashboard(teams, generatedAt, generatedAtTime) {
+    const windowStartTime = generatedAtTime - 24 * 60 * 60 * 1000;
+    const windowStart = new Date(windowStartTime).toISOString();
+    const focusList = [];
+    const teamFocusShares = [];
+    const overrides = [];
+    for (const team of teams) {
+        const teamOverrides = [...(team.focus_overrides ?? [])]
+            .filter((override) => Number.isFinite(Date.parse(override.at)) && Date.parse(override.at) <= generatedAtTime)
+            .sort((a, b) => a.at.localeCompare(b.at) || a.story.localeCompare(b.story));
+        overrides.push(...teamOverrides.map((override) => ({ ...override, team: team.team, project_id: team.project_id })));
+        const latestOverrideByStory = new Map();
+        for (const override of teamOverrides)
+            latestOverrideByStory.set(override.story, override.reason);
+        for (const story of team.stories) {
+            if (story.status === "dropped")
+                continue;
+            const activeOrRecentlyWorked = story.status === "in_progress" || recentlyWorked(story, windowStartTime, generatedAtTime);
+            const overrideReason = latestOverrideByStory.get(story.id) ?? null;
+            if (activeOrRecentlyWorked && (hasFocus(story) || overrideReason !== null)) {
+                focusList.push({
+                    team: team.team,
+                    project_id: team.project_id,
+                    story_id: story.id,
+                    title: story.title,
+                    owner: story.owner ?? null,
+                    deadline: story.deadline ?? null,
+                    state: story.status,
+                    focus_id: story.focus_id ?? null,
+                    kpi: story.kpi ?? null,
+                    override_reason: overrideReason,
+                });
+            }
+        }
+        const workStories = team.stories.filter((story) => story.status === "in_progress" || (story.status !== "dropped" && recentlyWorked(story, windowStartTime, generatedAtTime)));
+        const focusedStoryCount = workStories.filter(hasFocus).length;
+        const sharePercent = workStories.length === 0
+            ? null
+            : Math.round((focusedStoryCount / workStories.length) * 1000) / 10;
+        teamFocusShares.push({
+            team: team.team,
+            project_id: team.project_id,
+            window_start: windowStart,
+            window_end: generatedAt,
+            work_story_count: workStories.length,
+            focused_story_count: focusedStoryCount,
+            share_percent: sharePercent,
+            status: sharePercent === null ? "no_work" : focusedStoryCount / workStories.length < 0.8 ? "red" : "ok",
+        });
+    }
+    focusList.sort((a, b) => (a.deadline ?? "\uffff").localeCompare(b.deadline ?? "\uffff") || a.team.localeCompare(b.team) || a.story_id.localeCompare(b.story_id));
+    teamFocusShares.sort((a, b) => a.team.localeCompare(b.team));
+    overrides.sort((a, b) => a.at.localeCompare(b.at) || a.team.localeCompare(b.team) || a.story.localeCompare(b.story));
+    return { window_start: windowStart, window_end: generatedAt, focus_list: focusList, team_focus_shares: teamFocusShares, overrides };
+}
 function removeInvalidEntity(team, err) {
     if (!(err instanceof LanesError))
         return null;
@@ -316,7 +383,7 @@ export function buildTrackerOwnerReport(input) {
         }
         seen.add(team.team);
     }
-    return {
+    const report = {
         schema_version: "hq-lanes-owner-report.v1",
         company: input.company,
         generated_at: window.generatedAt,
@@ -326,6 +393,10 @@ export function buildTrackerOwnerReport(input) {
             .map((team) => withRecoverableTeamErrors(team, (safeTeam) => teamOwnerReport(safeTeam, input.company, window.sinceTime, window.generatedAtTime)))
             .sort((a, b) => a.team.localeCompare(b.team)),
     };
+    if (input.focus_dashboard_enabled === true) {
+        report.focus_dashboard = buildFocusDashboard(eligibleTeams, window.generatedAt, window.generatedAtTime);
+    }
+    return report;
 }
 function teamKpis(team, company, throughTime) {
     return team.kpis
@@ -460,6 +531,19 @@ export function renderTrackerOwnerReportText(report) {
         `Owner report for ${report.company}`,
         `Reporting window: ${report.since} through ${report.generated_at} (${report.since_source.replaceAll("_", " ")})`,
     ];
+    if (report.focus_dashboard) {
+        lines.push("", `Focus dashboard (last 24h: ${report.focus_dashboard.window_start} through ${report.focus_dashboard.window_end})`, "Focus list:");
+        lines.push(...listOrNone(report.focus_dashboard.focus_list, (item) => `${item.team}/${item.story_id} — ${item.title}; owner: ${item.owner ?? "unknown"}; deadline: ${item.deadline ?? "none"}; state: ${item.state}${item.override_reason ? `; override: ${item.override_reason}` : ""}`));
+        lines.push("Team focus share:");
+        lines.push(...listOrNone(report.focus_dashboard.team_focus_shares, (share) => {
+            if (share.share_percent === null)
+                return `${share.team}: no in-progress or worked stories`;
+            const color = share.status === "red" ? "RED under 80%" : "OK";
+            return `${share.team}: ${share.share_percent}% (${share.focused_story_count}/${share.work_story_count}); ${color}`;
+        }));
+        lines.push("Focus guard overrides:");
+        lines.push(...listOrNone(report.focus_dashboard.overrides, (override) => `${override.team}/${override.story} by ${override.by_lane} (${override.at}): ${override.reason}`));
+    }
     for (const team of report.teams) {
         lines.push("", `${team.team} (${team.project_id})`, "Progress:", "  Stories moved to done:");
         lines.push(...listOrNone(team.progress.stories_moved_to_done, (story) => `${story.id} — ${story.title} (${story.at})${story.references.length ? `; references: ${story.references.join(", ")}` : ""}`));

package/dist/lib/lanes/types.d.ts

@@ -525,6 +525,13 @@ export interface LaneRecord {
     story_id: string;
     /** Explicit reason a lane was created without a project story. */
     no_story_reason?: string;
+    /** Human-authored focus guard overrides used to launch this lane onto a story. */
+    focus_overrides?: Array<{
+        reason: string;
+        by_lane: string;
+        at: string;
+        story: string;
+    }>;
     /** Last failed story-ledger synchronization, cleared after a successful retry. */
     ledger_sync_error?: string;
     /** Pending question ids owned by this lane. */
@@ -584,6 +591,8 @@ export interface LaneRecord {
     keep_alive_exhausted_at?: string;
     /** Maximum number of direct child lanes this lane may keep alive; old records default to 0. */
     hire_grant?: number;
+    /** Hire grant returned to the senior while this terminal lane is inactive. */
+    released_hire_grant?: number;
     /** Content hash of the profile last applied to this lane. */
     worker_profile_hash?: string;
     /** Registry persona selected by the profile, pinned at lane creation. */
@@ -756,8 +765,9 @@ export interface LaneRecord {
     /** Last successful lane_progress mesh delivery, preserved across watcher restarts. */
     last_progress_event_at?: string;
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
-export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "company", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
+export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
 export declare const LANE_WRITERS: readonly ["creator", "command", "watcher", "reconcile", "spawn", "story-ledger"];
 export type LaneWriter = (typeof LANE_WRITERS)[number];
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */

package/dist/lib/lanes/types.js

@@ -215,9 +215,10 @@ export function parseSeniorKind(value) {
         return value;
     throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
 export const REQUIRED_LANE_RECORD_FIELDS = [
-    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "schema_version", "lane_id", "project_id", "story_id", "depth",
     "senior", "senior_history", "state", "priority", "provider", "host",
     "version", "created_at", "updated_at", "attribution_history",
 ];
@@ -225,9 +226,10 @@ export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spaw
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */
 export const LANE_FIELD_WRITERS = {
     schema_version: ["creator"], lane_id: ["creator"], written_by_version: [], owner_written_by_version: [], company: ["creator", "command"], company_history: ["command"],
-    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
+    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], focus_overrides: ["command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
     depth: ["command"], senior: ["command"], senior_history: ["command"],
     hire_grant: ["creator", "command"],
+    released_hire_grant: ["command"],
     state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_details: ["command", "reconcile", "spawn", "watcher"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],

package/dist/main.js

@@ -43,7 +43,7 @@ import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
 import { printCachedVersionNudge, printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
-import { enforceVersionGate, isLocalDependencyInstall, resolveRunningInstall, shouldSkipGate, } from "./utils/version-gate.js";
+import { enforceVersionGate, getVersionGatePhase, isLocalDependencyInstall, resolveRunningInstall, 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";
@@ -262,6 +262,10 @@ export async function runCli() {
             env: process.env,
             entryPath: RUNNING_ENTRY_PATH,
             stderr: process.stderr,
+            deps: {
+                resolveInstall: resolveRunningInstall,
+                versionGatePhase: getVersionGatePhase,
+            },
         });
         if (registration.reexecStatus !== undefined) {
             // The re-exec'd child ran the command on the settled tree; carry its exit

package/dist/startup-registration.d.ts

@@ -16,6 +16,7 @@
  * style of handleTopLevelError so the whole seam is unit-testable without real
  * spawns, waits, or a real install tree.
  */
+import type { VersionGatePhase } from "./utils/version-gate.js";
 import { type InstallRewriteSignalArgs, type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
 /**
  * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
@@ -74,6 +75,8 @@ export interface RegisterRecoveryDeps {
     waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
     /** Positive writer-signal probe for the eval-throw gate (defaults to installRewriteInProgress). */
     rewriteInProgress?: (args: InstallRewriteSignalArgs) => boolean;
+    /** Current version-gate phase for diagnostics; defaults to unknown for early entry recovery. */
+    versionGatePhase?: () => VersionGatePhase;
     /** node flags to forward to the re-exec child (defaults to process.execArgv). */
     execArgv?: readonly string[];
 }

package/dist/startup-registration.js

@@ -17,7 +17,6 @@
  * spawns, waits, or a real install tree.
  */
 import { spawnSync } from "node:child_process";
-import { getVersionGatePhase, resolveRunningInstall } from "./utils/version-gate.js";
 import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
 import { updateLockPath, UPDATE_LOCK_STALE_MS } from "./utils/update-lock.js";
 import { classifyEvalThrow, classifyModuleNotFound, installRewriteInProgress, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
@@ -122,7 +121,7 @@ export async function registerCommandsWithRecovery(args) {
                 cause: err,
                 classified,
                 packageRoot,
-                versionGatePhase: getVersionGatePhase(),
+                versionGatePhase: readVersionGatePhase(deps),
                 outcome: "guarded",
                 treeState: env[INSTALL_TREE_RECOVERY_TREE_STATE_ENV] === "stale" ? "stale" : "in_flight",
                 attempt: 2,
@@ -193,7 +192,7 @@ export async function registerCommandsWithRecovery(args) {
                 cause: err,
                 classified,
                 packageRoot,
-                versionGatePhase: getVersionGatePhase(),
+                versionGatePhase: readVersionGatePhase(deps),
                 outcome: "reexec-failed",
                 treeState,
                 attempt: 1,
@@ -225,11 +224,19 @@ export async function registerCommandsWithRecovery(args) {
 function resolvePackageRoot(deps) {
     let root;
     try {
-        root = (deps.resolveInstall ?? resolveRunningInstall)().packageRoot;
+        root = deps.resolveInstall?.().packageRoot ?? null;
     }
     catch {
         root = null;
     }
     return root ?? (deps.deriveInstallRoot ?? stringDerivedPackageRoot)();
 }
+function readVersionGatePhase(deps) {
+    try {
+        return deps.versionGatePhase?.() ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 //# sourceMappingURL=startup-registration.js.map

package/dist/utils/package-use-lease.d.ts

@@ -48,6 +48,7 @@ export declare function currentPackageUseUpdatePending(): boolean;
 export declare function currentPackageUseUpdateRequested(): boolean;
 export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
+    setPackageUseLeaseHeartbeatIntervalMs(intervalMs: number): void;
     setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
 /**

package/dist/utils/package-use-lease.js

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { utimes } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +9,8 @@ const CLI_NAME = "@indigoai-us/hq-cli";
 const UPDATE_REQUEST = "update.pending.json";
 export const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 const HANDOFF_TIMEOUT_MS = 2_000;
+const PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
+let packageUseLeaseHeartbeatIntervalMs = PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS;
 export const PACKAGE_USE_LEASE_PURPOSES = [
     "command",
     "resident-preload",
@@ -180,10 +183,32 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpos
     const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
     const tempPath = `${leasePath}.${Math.random().toString(36).slice(2)}.tmp`;
     let released = false;
+    let heartbeatInFlight = false;
+    let heartbeat = null;
+    const startHeartbeat = () => {
+        heartbeat = setInterval(() => {
+            if (released || heartbeatInFlight)
+                return;
+            heartbeatInFlight = true;
+            const now = new Date();
+            void utimes(leasePath, now, now)
+                .catch((error) => {
+                if (!released) {
+                    process.stderr.write(`hq-cli package-use lease heartbeat failed (${errorLabel(error)})\n`);
+                }
+            })
+                .finally(() => {
+                heartbeatInFlight = false;
+            });
+        }, packageUseLeaseHeartbeatIntervalMs);
+        heartbeat.unref();
+    };
     const release = () => {
         if (released)
             return;
         released = true;
+        if (heartbeat)
+            clearInterval(heartbeat);
         process.removeListener("exit", releaseOnExit);
         try {
             rmSync(leasePath, { force: true });
@@ -204,6 +229,7 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpos
             throw new Error(`Unable to publish the HQ CLI package-use lease (${errorLabel(error)})`, { cause: error });
         }
         if (!exists(requestPath)) {
+            startHeartbeat();
             process.once("exit", releaseOnExit);
             return { leasePath, release };
         }
@@ -409,6 +435,9 @@ export function currentPackageUseUpdateRequested() {
 }
 export const __test__ = {
     waitForUpdateRequest,
+    setPackageUseLeaseHeartbeatIntervalMs(intervalMs) {
+        packageUseLeaseHeartbeatIntervalMs = intervalMs;
+    },
     setCurrentPackageUseLease(lease) {
         currentPackageUseLease = lease;
     },

package/dist/utils/self-update-backoff.d.ts

@@ -0,0 +1,17 @@
+export declare const SELF_UPDATE_FAILURE_BACKOFF_MS: number;
+export interface SelfUpdateFailureRecord {
+    /** Version the failed attempt tried to install. */
+    target: string;
+    /** Epoch milliseconds of the failed attempt. */
+    failedAt: number;
+}
+export interface SelfUpdateBackoff {
+    /** The recorded failure when it is still inside the backoff window, else null. */
+    active(now?: number): SelfUpdateFailureRecord | null;
+    record(target: string, now?: number): void;
+    clear(): void;
+}
+export declare function selfUpdateBackoffPath(homeDir?: string): string;
+/** File-backed backoff under `~/.hq`. Every operation is best-effort. */
+export declare function fileSelfUpdateBackoff(homeDir?: string): SelfUpdateBackoff;
+//# sourceMappingURL=self-update-backoff.d.ts.map