@indigoai-us/hq-cli 5.343.1 → 5.344.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.344.1] — 2026-10-05
+- Release the MCP server's package lease after its resident modules preload and record a bounded command purpose on CLI package leases.
+
+## [5.344.0] — 2026-10-04
+- Include a bounded reason in sync-failure client-health reports.
+- Add an explicit opt-in to count usage from HQ sessions with no company toward the default company: `hq mesh context default set` asks in a terminal (default No), takes `--count-usage` / `--no-count-usage`, and writes `usageAttribution` (company and signed-in person) to the work-context config. Changing or clearing the default, logging out, or signing in as another account withdraws it; `get` shows it; an automatic default never opts in.
+
 ## [5.343.1] — 2026-10-04
 
 - Include the bounded hq-cli version in `cli_feature_used` telemetry so feature-use rows can be grouped by release.

package/dist/command-catalog.generated.d.ts

@@ -9678,7 +9678,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly options: readonly [];
             readonly subcommands: readonly [{
                 readonly name: "get";
-                readonly description: "Show the device default company (never activeCompany)";
+                readonly description: "Show the device default company (never activeCompany) and whether usage is counted toward it";
                 readonly aliases: readonly [];
                 readonly hidden: false;
                 readonly helpOption: true;
@@ -9700,7 +9700,10 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly helpOption: true;
                 readonly helpCommand: false;
                 readonly usage: "[options] <slug>";
-                readonly helpText: readonly [];
+                readonly helpText: readonly [{
+                    readonly position: "after";
+                    readonly text: "\nWith neither --count-usage nor --no-count-usage, an interactive terminal asks (default No);\notherwise an existing opt-in is kept only when it is for the same company.\nChanging to a different company always stops counting usage toward the old one.";
+                }];
                 readonly arguments: readonly [{
                     readonly name: "slug";
                     readonly required: true;
@@ -9715,6 +9718,14 @@ export declare const COMMAND_CATALOG: readonly [{
                     readonly flags: "--repair-held-with-default";
                     readonly description: "Persist opt-in for lower-confidence historical held-session repair";
                     readonly hidden: false;
+                }, {
+                    readonly flags: "--count-usage";
+                    readonly description: "Count usage from HQ sessions with no company toward this company (its owner and admins can see it)";
+                    readonly hidden: false;
+                }, {
+                    readonly flags: "--no-count-usage";
+                    readonly description: "Do not count usage from HQ sessions with no company toward this company";
+                    readonly hidden: false;
                 }, {
                     readonly flags: "--company <slug|uid>";
                     readonly description: "Deprecated no-op; the selected company is verified directly";
@@ -9727,7 +9738,7 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly subcommands: readonly [];
             }, {
                 readonly name: "clear";
-                readonly description: "Clear the device default company";
+                readonly description: "Clear the device default company and any opt-in to count usage toward it";
                 readonly aliases: readonly [];
                 readonly hidden: false;
                 readonly helpOption: true;

package/dist/command-catalog.generated.js

@@ -11737,7 +11737,7 @@ export const COMMAND_CATALOG = [
                         "subcommands": [
                             {
                                 "name": "get",
-                                "description": "Show the device default company (never activeCompany)",
+                                "description": "Show the device default company (never activeCompany) and whether usage is counted toward it",
                                 "aliases": [],
                                 "hidden": false,
                                 "helpOption": true,
@@ -11762,7 +11762,12 @@ export const COMMAND_CATALOG = [
                                 "helpOption": true,
                                 "helpCommand": false,
                                 "usage": "[options] <slug>",
-                                "helpText": [],
+                                "helpText": [
+                                    {
+                                        "position": "after",
+                                        "text": "\nWith neither --count-usage nor --no-count-usage, an interactive terminal asks (default No);\notherwise an existing opt-in is kept only when it is for the same company.\nChanging to a different company always stops counting usage toward the old one."
+                                    }
+                                ],
                                 "arguments": [
                                     {
                                         "name": "slug",
@@ -11782,6 +11787,16 @@ export const COMMAND_CATALOG = [
                                         "description": "Persist opt-in for lower-confidence historical held-session repair",
                                         "hidden": false
                                     },
+                                    {
+                                        "flags": "--count-usage",
+                                        "description": "Count usage from HQ sessions with no company toward this company (its owner and admins can see it)",
+                                        "hidden": false
+                                    },
+                                    {
+                                        "flags": "--no-count-usage",
+                                        "description": "Do not count usage from HQ sessions with no company toward this company",
+                                        "hidden": false
+                                    },
                                     {
                                         "flags": "--company <slug|uid>",
                                         "description": "Deprecated no-op; the selected company is verified directly",
@@ -11797,7 +11812,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "name": "clear",
-                                "description": "Clear the device default company",
+                                "description": "Clear the device default company and any opt-in to count usage toward it",
                                 "aliases": [],
                                 "hidden": false,
                                 "helpOption": true,

package/dist/commands/cloud.js

@@ -20,7 +20,7 @@ import { share, sync, getStateDir, listJournals, VaultClient, computePersonalVau
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, loadCachedTokens, } from "../utils/cognito-session.js";
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
-import { beginSyncHealthReport, } from "../utils/client-health.js";
+import { beginSyncHealthReport, classifySyncFailure, } from "../utils/client-health.js";
 import { companySlugFromSyncPaths, warnAboutInvalidOntologyEntities, } from "../lib/sync-invalid-entity-warning.js";
 import { isWorkBearingSyncResult, recordFirstWorkBearingSync, } from "../lib/first-sync-next-step.js";
 import { maybeShowCliInviteNudge } from "../lib/cli-invite-nudge.js";
@@ -125,7 +125,7 @@ export async function withSyncHealthReport(run) {
             await health.succeeded();
         }
         else {
-            await health.failed();
+            await health.failed(classifySyncFailure(err));
         }
         if (err instanceof SyncExitError)
             process.exit(err.code);

package/dist/commands/login.js

@@ -8,7 +8,8 @@ import { browserLogin, loadCachedTokens, isExpiring } from '@indigoai-us/hq-clou
 import { cognitoConfigForLoginProvider } from '../utils/login-provider.js';
 import * as readline from "node:readline/promises";
 import { listActiveMembershipCompanies } from "../lib/mesh/api.js";
-import { setDefaultCompany } from "../lib/work-context/config.js";
+import { retainUsageAttributionForPerson, setDefaultCompany } from "../lib/work-context/config.js";
+import { personUidFromTokens } from "../lib/work-context/person-identity.js";
 import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 function peekIdToken(idToken) {
@@ -62,6 +63,16 @@ export function registerLoginCommand(program) {
             process.exitCode = 1;
             return;
         }
+        try {
+            // The usage-attribution opt-in belongs to the person who gave it. A
+            // different (or unknown) account signing in on this OS user drops it.
+            retainUsageAttributionForPerson(personUidFromTokens(loadCachedTokens()), {
+                root: workContextRoot(),
+            });
+        }
+        catch {
+            /* fail closed below: readers also require the signed-in person to match */
+        }
         try {
             const root = workContextRoot();
             const activation = await ensureDefaultCompany({

package/dist/commands/logout.js

@@ -3,6 +3,8 @@
  */
 import chalk from 'chalk';
 import { clearCachedTokens, loadCachedTokens } from '@indigoai-us/hq-cloud';
+import { retainUsageAttributionForPerson } from '../lib/work-context/config.js';
+import { workContextRoot } from '../lib/work-context/paths.js';
 export function registerLogoutCommand(program) {
     program
         .command('logout')
@@ -11,6 +13,14 @@ export function registerLogoutCommand(program) {
         try {
             const { clearMcpOAuthCaches } = await import('../lib/daemon/mcp-oauth.js');
             clearMcpOAuthCaches();
+            // Signing out withdraws the opt-in to count no-company usage toward the
+            // default company; the next account must opt in for itself.
+            try {
+                retainUsageAttributionForPerson(null, { root: workContextRoot() });
+            }
+            catch (error) {
+                console.error(chalk.yellow('Could not withdraw the usage opt-in:'), error instanceof Error ? error.message : 'Unknown error');
+            }
             const existing = loadCachedTokens();
             if (!existing) {
                 console.log(chalk.yellow('No cached HQ session'));

package/dist/commands/mcp-serve.js

@@ -73,11 +73,12 @@ export async function runMcpServe(opts = {}) {
             process.emitWarning("hq-cli resident package preload completion failed (class=Error, module=unknown)");
         });
     };
+    // Release before the stdio read can remain open indefinitely. The request
+    // handlers and their declared lazy modules are loaded before this point.
+    startResidentPreload();
     const send = (msg) => {
         const response = `${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`;
-        if (residentPreloadStarted)
-            return output.write(response);
-        return output.write(response, startResidentPreload);
+        return output.write(response);
     };
     const reply = (id, result) => send({ id, result });
     const replyError = (id, code, message) => send({ id, error: { code, message } });

package/dist/commands/mesh.d.ts

@@ -10,6 +10,30 @@ import { type MeshCompany, type MeshThread } from "../lib/mesh/api.js";
 import { type DaemonInstallPlatform, type InstallPaths } from "../lib/mesh/live/daemon/index.js";
 import { type RunCommand } from "../lib/service-manager/launchd.js";
 export declare function formatCheckLines(threads: MeshThread[], company: MeshCompany, projectId?: string): string[];
+/** Test seam for the usage-attribution question asked by `default set`. */
+export interface DefaultCompanyPromptDeps {
+    /** True when stdin and stdout are a terminal (a person can answer). */
+    isInteractive?: () => boolean;
+    /** Ask a yes/no question; resolves true only for an explicit yes. */
+    confirm?: (question: string) => Promise<boolean>;
+}
+export declare function usageOptInExplainer(company: string): string;
+export declare function usageOptInQuestion(company: string): string;
+export declare function usageCountedLine(company: string): string;
+export declare function usageNotCountedLine(company: string): string;
+/** Only "y" or "yes" (any case, surrounding space ignored) is a yes. EOF (null) is no. */
+export declare function parseYesNoAnswer(answer: string | null): boolean;
+/** A person can answer only when both stdin and stdout are a terminal. */
+export declare function isInteractiveTerminal(stdin?: {
+    isTTY?: boolean;
+}, stdout?: {
+    isTTY?: boolean;
+}): boolean;
+/** Ask one yes/no question. Resolves false on EOF or a closed input. */
+export declare function askYesNo(question: string, io?: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}): Promise<boolean>;
 /** Injectable confirmation seam for `hq mesh context correct` (stubbed in tests). */
 export type MeshConfirmFn = (message: string) => Promise<boolean>;
 /** Exported for confirmation-gate unit tests (US-017B). */
@@ -25,7 +49,9 @@ export declare function runContextCorrect(opts: {
 }, deps?: {
     confirm?: MeshConfirmFn;
 }): Promise<void>;
-export declare function registerMeshCommand(program: Command): void;
+export declare function registerMeshCommand(program: Command, deps?: {
+    defaultCompanyPrompt?: DefaultCompanyPromptDeps;
+}): void;
 export declare function runDaemonStatus(opts: {
     json?: boolean;
 }, deps?: {

package/dist/commands/mesh.js

@@ -18,9 +18,10 @@ import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectB
 import { mapSourceStoryStatus } from "../lib/mesh/story-status.js";
 import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
-import { clearDefaultCompany, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, } from "../lib/work-context/config.js";
+import { clearDefaultCompany, effectiveUsageAttribution, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, setUsageAttribution, } from "../lib/work-context/config.js";
 import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
-import { DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
+import { personUidFromTokens } from "../lib/work-context/person-identity.js";
+import { DefaultCompanyUnavailableError, WorkContextError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
 import { CLI_KIND_TO_SCHEMA, resolveEnqueueSessionId, } from "../lib/mesh/live/index.js";
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
@@ -1170,6 +1171,58 @@ async function runContextBackfillHeld(opts) {
             "the mesh daemon's held retry will re-attribute and post those events.");
     }
 }
+export function usageOptInExplainer(company) {
+    return `Opting in counts usage from HQ sessions started with no company toward ${company}. Sessions bound to a company count toward that company either way.`;
+}
+export function usageOptInQuestion(company) {
+    return `Count usage from HQ sessions with no company toward ${company}? Your company's owner and admins will see that usage, including tokens, models, and the repo and branch you worked in. [y/N] `;
+}
+export function usageCountedLine(company) {
+    return `Usage from HQ sessions with no company is counted toward ${company}.`;
+}
+export function usageNotCountedLine(company) {
+    return `Usage from HQ sessions with no company is not counted toward ${company}. To opt in, run: hq mesh context default set ${company} --count-usage`;
+}
+/** Only "y" or "yes" (any case, surrounding space ignored) is a yes. EOF (null) is no. */
+export function parseYesNoAnswer(answer) {
+    return answer !== null && /^y(es)?$/i.test(answer.trim());
+}
+/** A person can answer only when both stdin and stdout are a terminal. */
+export function isInteractiveTerminal(stdin = process.stdin, stdout = process.stdout) {
+    return stdin.isTTY === true && stdout.isTTY === true;
+}
+/** Ask one yes/no question. Resolves false on EOF or a closed input. */
+export async function askYesNo(question, io = {}) {
+    const rl = readline.createInterface({
+        input: io.input ?? process.stdin,
+        output: io.output ?? process.stderr,
+        terminal: false,
+    });
+    const closed = new Promise((resolve) => rl.once("close", () => resolve(null)));
+    try {
+        const answer = await Promise.race([
+            rl.question(question).catch(() => null),
+            closed,
+        ]);
+        return parseYesNoAnswer(answer);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The signed-in person's prs_ uid from the cached Cognito session, or null. */
+function currentPersonUid() {
+    try {
+        return personUidFromTokens(loadCachedTokens());
+    }
+    catch {
+        return null;
+    }
+}
+function usageAttributionJson(cfg, personUid) {
+    const effective = effectiveUsageAttribution(cfg, personUid);
+    return { countUsage: effective !== null, usageAttribution: effective };
+}
 async function runContextDefaultGet(opts) {
     const root = workContextHomeRoot();
     const cfg = readDeviceConfig({ root });
@@ -1189,6 +1242,7 @@ async function runContextDefaultGet(opts) {
             needsChoice: !current && !disabled && memberships.length > 1,
             memberships,
             repairHeldWithDefault: cfg.repairHeldWithDefault === true,
+            ...usageAttributionJson(cfg, currentPersonUid()),
         }, null, 2));
         return;
     }
@@ -1201,10 +1255,20 @@ async function runContextDefaultGet(opts) {
         return;
     }
     console.log(`Default company: ${current.slug}${current.uid ? ` (${current.uid})` : ""} enabled=${current.enabled} source=${source}`);
+    console.log(effectiveUsageAttribution(cfg, currentPersonUid())
+        ? usageCountedLine(current.slug)
+        : usageNotCountedLine(current.slug));
 }
-async function runContextDefaultSet(slug, opts) {
+async function runContextDefaultSet(slug, opts, promptDeps = {}) {
     const root = workContextHomeRoot();
     void opts.company; // retained for CLI compatibility
+    const usageChoice = opts.countUsage === true
+        ? "opt-in"
+        : opts.countUsage === false
+            ? "opt-out"
+            : "keep-if-same";
+    const personUid = currentPersonUid();
+    const priorOptIn = effectiveUsageAttribution(readDeviceConfig({ root }), personUid);
     let token;
     try {
         token = await requireToken();
@@ -1244,6 +1308,8 @@ async function runContextDefaultSet(slug, opts) {
         const cfg = await setDefaultCompany(slug, {
             root,
             migrationCapability,
+            usageAttribution: usageChoice,
+            personUid,
             validateMembership: async (candidate) => {
                 if (!token) {
                     throw new DefaultCompanyUnavailableError(`Cannot verify membership for company "${candidate}" (no Cognito session; offline or not logged in)`);
@@ -1261,19 +1327,55 @@ async function runContextDefaultSet(slug, opts) {
                 return { uid: membership.companyUid };
             },
         });
-        const configured = opts.repairHeldWithDefault
+        let configured = opts.repairHeldWithDefault
             ? setRepairHeldWithDefault(true, { root })
             : cfg;
+        const stored = configured.defaultCompany;
+        const company = stored?.slug ?? slug;
         if (opts.json) {
-            console.log(JSON.stringify({ ok: true, config: configured, migrationWarning }, null, 2));
+            // Machine output never prompts; the opt-in changes only with a flag.
+            console.log(JSON.stringify({
+                ok: true,
+                config: configured,
+                migrationWarning,
+                ...usageAttributionJson(configured, personUid),
+            }, null, 2));
             return;
         }
-        const stored = configured.defaultCompany;
-        console.log(`Default company set to ${stored?.slug ?? slug}${stored?.uid ? ` (${stored.uid})` : ""}`);
+        console.log(`Default company set to ${company}${stored?.uid ? ` (${stored.uid})` : ""}`);
+        if (priorOptIn && priorOptIn.companyUid !== stored?.uid) {
+            console.log("Usage is no longer counted toward the previous default company.");
+        }
+        const interactive = (promptDeps.isInteractive ??
+            (() => isInteractiveTerminal()))();
+        if (usageChoice === "keep-if-same" &&
+            interactive &&
+            personUid &&
+            !effectiveUsageAttribution(configured, personUid) &&
+            stored?.uid?.startsWith("cmp_")) {
+            console.error(usageOptInExplainer(company));
+            let yes = false;
+            try {
+                yes = await (promptDeps.confirm ?? askYesNo)(usageOptInQuestion(company));
+            }
+            catch {
+                yes = false;
+            }
+            if (yes)
+                configured = setUsageAttribution({ companyUid: stored.uid, personUid }, { root });
+        }
+        console.log(effectiveUsageAttribution(configured, personUid)
+            ? usageCountedLine(company)
+            : usageNotCountedLine(company));
         if (migrationWarning)
             console.error(chalk.yellow(migrationWarning));
     }
     catch (err) {
+        if (err instanceof WorkContextError && err.code === "UsageAttributionUnavailable") {
+            console.error(chalk.red(`${err.code}: ${err.message}`));
+            process.exitCode = 1;
+            return;
+        }
         if (err instanceof DefaultCompanyUnavailableError) {
             console.error(chalk.red(`${err.code}: ${err.message}`));
             process.exitCode = 1;
@@ -1396,12 +1498,16 @@ export async function runContextCorrect(opts, deps = {}) {
 }
 async function runContextDefaultClear(opts) {
     const root = workContextHomeRoot();
+    const hadOptIn = readDeviceConfig({ root }).usageAttribution !== undefined;
     const cfg = clearDefaultCompany({ root });
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, config: cfg }, null, 2));
+        console.log(JSON.stringify({ ok: true, config: cfg, ...usageAttributionJson(cfg, currentPersonUid()) }, null, 2));
         return;
     }
     console.log("Default company cleared.");
+    if (hadOptIn) {
+        console.log("Usage from HQ sessions with no company is no longer counted toward any company.");
+    }
 }
 async function runContextRequeue(opts) {
     const root = workContextHomeRoot();
@@ -1854,7 +1960,7 @@ function addSharedFlags(cmd) {
         .option("--thread-id <id>", "Explicit work thread id")
         .option("--json", "Print machine-readable JSON");
 }
-export function registerMeshCommand(program) {
+export function registerMeshCommand(program, deps = {}) {
     const mesh = program
         .command("mesh")
         .description("Work mesh — register project work, report progress, and warm ~/.hq/work-mesh/cache");
@@ -2030,7 +2136,7 @@ export function registerMeshCommand(program) {
         .description("Manage the device-local default company preference");
     def
         .command("get")
-        .description("Show the device default company (never activeCompany)")
+        .description("Show the device default company (never activeCompany) and whether usage is counted toward it")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runContextDefaultGet(opts))());
     def
@@ -2039,12 +2145,17 @@ export function registerMeshCommand(program) {
         .argument("<slug>", "Company slug")
         .option("--allow-without-migration", "Deprecated compatibility no-op; selected-company membership is always verified")
         .option("--repair-held-with-default", "Persist opt-in for lower-confidence historical held-session repair")
+        .option("--count-usage", "Count usage from HQ sessions with no company toward this company (its owner and admins can see it)")
+        .option("--no-count-usage", "Do not count usage from HQ sessions with no company toward this company")
         .option("--company <slug|uid>", "Deprecated no-op; the selected company is verified directly")
         .option("--json", "Print machine-readable JSON")
-        .action((slug, opts) => wrap(() => runContextDefaultSet(slug, opts))());
+        .addHelpText("after", "\nWith neither --count-usage nor --no-count-usage, an interactive terminal asks (default No);\n" +
+        "otherwise an existing opt-in is kept only when it is for the same company.\n" +
+        "Changing to a different company always stops counting usage toward the old one.")
+        .action((slug, opts) => wrap(() => runContextDefaultSet(slug, opts, deps.defaultCompanyPrompt))());
     def
         .command("clear")
-        .description("Clear the device default company")
+        .description("Clear the device default company and any opt-in to count usage toward it")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runContextDefaultClear(opts))());
     context

package/dist/lib/work-context/config.d.ts

@@ -44,10 +44,41 @@ export interface RepoCompanyMapping {
     updatedAt: string;
 }
 type RepoCompanyMap = Record<string, RepoCompanyMapping>;
+/**
+ * Explicit opt-in to count usage from HQ sessions with no company toward the
+ * device default company. hq-cloud's usage sync reads this field and credits
+ * the default company only when mode is exactly "default-company", companyUid
+ * starts with "cmp_" and equals the default company's uid, and optedInAt
+ * parses as a date. Company owners and admins can see company-attributed
+ * usage, so this is never written without the person's explicit consent.
+ */
+export interface UsageAttributionOptIn {
+    mode: "default-company";
+    companyUid: string;
+    /**
+     * The signed-in person who consented: the `custom:entityUid` claim (prs_...)
+     * of the cached Cognito person session. Consent never carries to another
+     * account on the same OS user.
+     */
+    personUid: string;
+    optedInAt: string;
+}
+/** A person principal uid, as carried in the `custom:entityUid` token claim. */
+export declare function isPersonUid(value: unknown): value is string;
+/** How `setDefaultCompany` treats the usage-attribution opt-in. */
+export type UsageAttributionChoice = 
+/** Write an opt-in for the newly set company (requires its uid). */
+"opt-in"
+/** Remove any opt-in. */
+ | "opt-out"
+/** Keep an existing opt-in only when it is for the same company uid. */
+ | "keep-if-same";
 export interface WorkContextDeviceConfig {
     schemaVersion: typeof DEVICE_CONFIG_SCHEMA_VERSION;
     /** Explicit device default. Never copied from activeCompany. */
     defaultCompany?: DeviceDefaultCompany | null;
+    /** Opt-in to count no-company HQ session usage toward the default company. */
+    usageAttribution?: UsageAttributionOptIn;
     /** Marks a null default written by the automatic-activation implementation. */
     defaultCompanyAutomaticEligible?: true;
     /** Last-known migration capability across memberships (doctor reports this). */
@@ -75,12 +106,31 @@ export interface DeviceConfigDeps {
      */
     validateMembership?: (slug: string) => Promise<MembershipValidationResult> | MembershipValidationResult;
     now?: () => Date;
+    /**
+     * Usage-attribution opt-in handling for setDefaultCompany. Defaults to
+     * "keep-if-same": an existing opt-in survives only when it is for the same
+     * company uid, so changing the default never carries consent across companies.
+     */
+    usageAttribution?: UsageAttributionChoice;
+    /**
+     * The signed-in person (prs_...). Required to write an opt-in; an existing
+     * opt-in is kept only when it was given by this person.
+     */
+    personUid?: string | null;
 }
 /** Acquire an interprocess config lock; exported for direct lock regression tests. */
 export declare function acquireDeviceConfigLock(root: string, options?: {
     timeoutMs?: number;
     staleMs?: number;
 }): () => void;
+/** Parse a raw usageAttribution value; anything malformed is dropped (fail closed). */
+export declare function sanitizeUsageAttribution(raw: unknown): UsageAttributionOptIn | undefined;
+/**
+ * The opt-in that is in effect: present, for the uid of the current enabled
+ * default company, and given by the signed-in person. Mirrors the hq-cloud
+ * reader. No signed-in person means no opt-in.
+ */
+export declare function effectiveUsageAttribution(cfg: Pick<WorkContextDeviceConfig, "defaultCompany" | "usageAttribution">, personUid: string | null | undefined): UsageAttributionOptIn | null;
 /** Injection points for assertSafeConfigPath (tests only). */
 export interface SafeConfigPathIo {
     platform?: NodeJS.Platform;
@@ -104,6 +154,22 @@ export declare function getDefaultCompany(deps: Pick<DeviceConfigDeps, "root">):
 /** A clear is a durable opt-out, not an invitation for automatic reactivation. */
 export declare function isDefaultCompanyDisabled(deps: Pick<DeviceConfigDeps, "root">): boolean;
 export declare function setDefaultCompany(slug: string, deps: DeviceConfigDeps): Promise<WorkContextDeviceConfig>;
+/**
+ * Record or remove the usage-attribution opt-in for the current default
+ * company. Opting in requires an enabled, explicitly chosen default with a
+ * cmp_ uid that equals `companyUid` (the company the person was asked about);
+ * an automatic single-company default is never opted in.
+ */
+export declare function setUsageAttribution(optIn: {
+    companyUid: string;
+    personUid: string;
+} | null, deps: Pick<DeviceConfigDeps, "root" | "now">): WorkContextDeviceConfig;
+/**
+ * Drop the usage-attribution opt-in unless it was given by `personUid`. Called
+ * on login (identity may have changed) and logout (null: always drop). A
+ * config with no opt-in, or one already matching, is left untouched.
+ */
+export declare function retainUsageAttributionForPerson(personUid: string | null | undefined, deps: Pick<DeviceConfigDeps, "root" | "now">): boolean;
 export declare function clearDefaultCompany(deps: DeviceConfigDeps): WorkContextDeviceConfig;
 /**
  * Read the persisted company mapping for a repo identity key (gap 4).

package/dist/lib/work-context/config.js

@@ -9,6 +9,10 @@ import { DefaultCompanyUnavailableError, UnsafeConfigPathError, WorkContextError
 import { workContextConfigPath } from "./paths.js";
 import { assertWindowsOwnerOnlyAcl } from "./windows-acl.js";
 const DEVICE_CONFIG_SCHEMA_VERSION = 1;
+/** A person principal uid, as carried in the `custom:entityUid` token claim. */
+export function isPersonUid(value) {
+    return typeof value === "string" && /^prs_[A-Za-z0-9]+$/.test(value);
+}
 const CONFIG_LOCK_TIMEOUT_MS = 5_000;
 const CONFIG_LOCK_RETRY_MS = 10;
 function waitForConfigLock(ms) {
@@ -146,6 +150,44 @@ function sanitizeRepoCompanyMap(raw) {
     }
     return Object.keys(out).length > 0 ? out : null;
 }
+/** Parse a raw usageAttribution value; anything malformed is dropped (fail closed). */
+export function sanitizeUsageAttribution(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const v = raw;
+    if (v.mode !== "default-company")
+        return undefined;
+    const companyUid = typeof v.companyUid === "string" ? v.companyUid.trim() : "";
+    const personUid = typeof v.personUid === "string" ? v.personUid.trim() : "";
+    const optedInAt = typeof v.optedInAt === "string" ? v.optedInAt.trim() : "";
+    if (!companyUid.startsWith("cmp_") ||
+        !isPersonUid(personUid) ||
+        !optedInAt ||
+        !Number.isFinite(Date.parse(optedInAt))) {
+        return undefined;
+    }
+    return { mode: "default-company", companyUid, personUid, optedInAt };
+}
+/**
+ * The opt-in that is in effect: present, for the uid of the current enabled
+ * default company, and given by the signed-in person. Mirrors the hq-cloud
+ * reader. No signed-in person means no opt-in.
+ */
+export function effectiveUsageAttribution(cfg, personUid) {
+    const opt = cfg.usageAttribution;
+    if (!opt || !isPersonUid(personUid) || opt.personUid !== personUid)
+        return null;
+    const def = cfg.defaultCompany;
+    if (!opt || !def || def.enabled !== true || def.source === "disabled")
+        return null;
+    if (!def.uid || def.uid !== opt.companyUid)
+        return null;
+    return opt;
+}
+/** Keep `usageAttribution` next to `defaultCompany`, omitting it when absent. */
+function usageAttributionField(value) {
+    return value ? { usageAttribution: value } : {};
+}
 /**
  * Refuse a config path that is a symlink (every platform) or writable by
  * anyone other than the owner.
@@ -216,6 +258,7 @@ export function readDeviceConfig(deps) {
             defaultCompany: legacyNullDefault
                 ? { slug: "", enabled: false, source: "disabled" }
                 : raw.defaultCompany ?? null,
+            ...usageAttributionField(sanitizeUsageAttribution(raw.usageAttribution)),
             migrationCapability: raw.migrationCapability ?? null,
             repoCompanyMap: sanitizeRepoCompanyMap(raw.repoCompanyMap),
             defaultCompanyMemberships: sanitizeMembershipSnapshot(raw.defaultCompanyMemberships),
@@ -287,9 +330,36 @@ export async function setDefaultCompany(slug, deps) {
         };
         if (resolvedUid)
             defaultCompany.uid = resolvedUid;
+        const choice = deps.usageAttribution ?? "keep-if-same";
+        let usageAttribution;
+        const personUid = isPersonUid(deps.personUid) ? deps.personUid : undefined;
+        if (choice === "opt-in") {
+            if (!resolvedUid?.startsWith("cmp_")) {
+                throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": its company uid is unknown`);
+            }
+            if (!personUid) {
+                throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": the signed-in person could not be determined`);
+            }
+            usageAttribution = {
+                mode: "default-company",
+                companyUid: resolvedUid,
+                personUid,
+                optedInAt: now().toISOString(),
+            };
+        }
+        else if (choice === "keep-if-same") {
+            usageAttribution =
+                resolvedUid &&
+                    personUid &&
+                    prior.usageAttribution?.companyUid === resolvedUid &&
+                    prior.usageAttribution.personUid === personUid
+                    ? prior.usageAttribution
+                    : undefined;
+        }
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany,
+            ...usageAttributionField(usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -300,6 +370,69 @@ export async function setDefaultCompany(slug, deps) {
         return next;
     });
 }
+/**
+ * Record or remove the usage-attribution opt-in for the current default
+ * company. Opting in requires an enabled, explicitly chosen default with a
+ * cmp_ uid that equals `companyUid` (the company the person was asked about);
+ * an automatic single-company default is never opted in.
+ */
+export function setUsageAttribution(optIn, deps) {
+    const now = deps.now ?? (() => new Date());
+    return withDeviceConfigLock(deps.root, () => {
+        const prior = readDeviceConfig(deps);
+        let usageAttribution;
+        if (optIn) {
+            const def = prior.defaultCompany;
+            if (!def ||
+                def.enabled !== true ||
+                def.source !== "chosen" ||
+                !def.uid?.startsWith("cmp_") ||
+                def.uid !== optIn.companyUid ||
+                !isPersonUid(optIn.personUid)) {
+                throw new WorkContextError("UsageAttributionUnavailable", "Usage can only be counted toward a default company you chose on this device");
+            }
+            usageAttribution = {
+                mode: "default-company",
+                companyUid: def.uid,
+                personUid: optIn.personUid,
+                optedInAt: now().toISOString(),
+            };
+        }
+        const next = {
+            schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
+            defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(usageAttribution),
+            migrationCapability: prior.migrationCapability ?? null,
+            repoCompanyMap: prior.repoCompanyMap ?? null,
+            defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
+            repairHeldWithDefault: prior.repairHeldWithDefault === true,
+            updatedAt: now().toISOString(),
+        };
+        writeDeviceConfig({ root: deps.root }, next);
+        return next;
+    });
+}
+/**
+ * Drop the usage-attribution opt-in unless it was given by `personUid`. Called
+ * on login (identity may have changed) and logout (null: always drop). A
+ * config with no opt-in, or one already matching, is left untouched.
+ */
+export function retainUsageAttributionForPerson(personUid, deps) {
+    if (!fs.existsSync(workContextConfigPath(deps.root)))
+        return false;
+    return withDeviceConfigLock(deps.root, () => {
+        const prior = readDeviceConfig(deps);
+        const opt = prior.usageAttribution;
+        if (!opt)
+            return false;
+        if (isPersonUid(personUid) && opt.personUid === personUid)
+            return false;
+        const now = deps.now ?? (() => new Date());
+        const { usageAttribution: _dropped, ...rest } = prior;
+        writeDeviceConfig({ root: deps.root }, { ...rest, updatedAt: now().toISOString() });
+        return true;
+    });
+}
 export function clearDefaultCompany(deps) {
     const now = deps.now ?? (() => new Date());
     return withDeviceConfigLock(deps.root, () => {
@@ -307,6 +440,8 @@ export function clearDefaultCompany(deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: { slug: "", enabled: false, source: "disabled" },
+            // usageAttribution is intentionally omitted: clearing the default also
+            // withdraws the opt-in to count usage toward it.
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -355,6 +490,7 @@ export function setRepoCompany(key, mapping, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: nextMap,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -373,6 +509,7 @@ export function recordMigrationCapabilitySnapshot(snapshot, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: {
                 unlocked: snapshot.unlocked,
                 offline: snapshot.offline,
@@ -414,6 +551,7 @@ export function recordDefaultCompanyMemberships(snapshot, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: {
@@ -435,6 +573,7 @@ export function invalidateDefaultCompanyMemberships(deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: null,
@@ -468,6 +607,8 @@ export function setAutoDefaultCompany(membership, deps) {
                 enabled: true,
                 source: "auto_single",
             },
+            // usageAttribution is intentionally omitted: an automatic default is
+            // never opted in to usage attribution.
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -485,6 +626,7 @@ export function setRepairHeldWithDefault(enabled, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,

package/dist/lib/work-context/person-identity.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Signed-in person identity for the usage-attribution opt-in.
+ *
+ * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
+ * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
+ * claim of the ID token (falling back to the access token), and only a
+ * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
+ * no opt-in is written or kept for them. Claims are read without
+ * verification; this decides only whether local consent belongs to the
+ * account that is signed in, never authorization.
+ */
+export declare function personUidFromTokens(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string | null;
+//# sourceMappingURL=person-identity.d.ts.map

package/dist/lib/work-context/person-identity.js

@@ -0,0 +1,39 @@
+/**
+ * Signed-in person identity for the usage-attribution opt-in.
+ *
+ * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
+ * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
+ * claim of the ID token (falling back to the access token), and only a
+ * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
+ * no opt-in is written or kept for them. Claims are read without
+ * verification; this decides only whether local consent belongs to the
+ * account that is signed in, never authorization.
+ */
+import { isPersonUid } from "./config.js";
+function claimsOf(token) {
+    if (typeof token !== "string")
+        return null;
+    const part = token.split(".")[1];
+    if (!part)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function personUidFromTokens(tokens) {
+    if (!tokens)
+        return null;
+    for (const token of [tokens.idToken, tokens.accessToken]) {
+        const uid = claimsOf(token)?.["custom:entityUid"];
+        if (isPersonUid(uid))
+            return uid;
+    }
+    return null;
+}
+//# sourceMappingURL=person-identity.js.map

package/dist/utils/client-health.d.ts

@@ -32,7 +32,7 @@
  */
 import { isExpiring, loadCachedTokens } from "./cognito-session.js";
 import { type VersionInfo } from "./feedback-versions.js";
-import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
+import { type ClientHealthArch, type ClientHealthFailureReason, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
 export declare const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -141,6 +141,8 @@ export interface BuildCliHeartbeatInput {
     now: Date;
     platform?: ClientHealthPlatform | null;
     arch?: ClientHealthArch | null;
+    /** Closed, typed reason from the terminal sync runner; never free-form text. */
+    failureReason?: ClientHealthFailureReason;
     /**
      * Bounded local log/journal file facts (US-016). Only ever attached for
      * `sync_success` / `sync_failure` kinds — support asked for this on the
@@ -148,6 +150,8 @@ export interface BuildCliHeartbeatInput {
      */
     localFilesOverview?: ClientHealthLocalFilesOverview | null;
 }
+/** Classify sync failures using typed error identity/code fields only. */
+export declare function classifySyncFailure(err: unknown): ClientHealthFailureReason;
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
  * cannot be represented in the closed contract enums (unknown platform/arch)
@@ -184,7 +188,7 @@ export interface ClientHealthDeps {
  * ignores its abort signal) must never delay a command past the bound. On
  * timeout the pending work is abandoned silently.
  */
-export declare function contributeClientHealth(kind: ClientHealthEventKind, deps?: ClientHealthDeps): Promise<void>;
+export declare function contributeClientHealth(kind: ClientHealthEventKind, deps?: ClientHealthDeps, failureReason?: ClientHealthFailureReason): Promise<void>;
 /**
  * Fire-once-per-process invocation heartbeat (commander preAction seam, next
  * to `emitCliSessionStarted`). Reports the real CLI + Core versions, platform,
@@ -194,7 +198,7 @@ export declare function reportCliClientHealthInvocation(deps?: ClientHealthDeps)
 export interface SyncHealthReport {
     /** Report the terminal outcome. Bounded, swallowed, safe to await. */
     succeeded(): Promise<void>;
-    failed(): Promise<void>;
+    failed(reason?: ClientHealthFailureReason): Promise<void>;
 }
 /**
  * Report a CLI sync command run: an attempt heartbeat now (fire-and-forget)

package/dist/utils/client-health.js

@@ -37,6 +37,7 @@ import { getStateDir, listJournals } from "@indigoai-us/hq-cloud";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
 import { collectVersions } from "./feedback-versions.js";
+import { isAuthError } from "./auth-error.js";
 import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
 import { collectLocalFilesOverview } from "./local-files-overview.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
@@ -314,6 +315,25 @@ function acquireJournalObservationLock(stateDir, nowMs, staleMs) {
         }
     };
 }
+/** Classify sync failures using typed error identity/code fields only. */
+export function classifySyncFailure(err) {
+    if (isAuthError(err))
+        return "AUTH_EXPIRED";
+    let current = err;
+    for (let depth = 0; depth < 3; depth += 1) {
+        if (current === null || typeof current !== "object")
+            break;
+        const value = current;
+        if (value.code === "ENOSPC" || value.code === "EDQUOT") {
+            return "DISK_FULL";
+        }
+        if (value.code === "EACCES" || value.code === "EPERM") {
+            return "PERMISSION_DENIED";
+        }
+        current = value.cause;
+    }
+    return "RUNNER_FAILED";
+}
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
  * cannot be represented in the closed contract enums (unknown platform/arch)
@@ -388,6 +408,9 @@ export function buildCliHeartbeat(input) {
     if (input.state.lastSyncAttemptAt !== undefined) {
         heartbeat.lastSyncAttemptAt = input.state.lastSyncAttemptAt;
     }
+    if (input.kind === "sync_failure" && input.failureReason !== undefined) {
+        heartbeat.failureReason = input.failureReason;
+    }
     if (lastSyncSuccessAt !== null) {
         heartbeat.lastSyncSuccessAt = lastSyncSuccessAt;
     }
@@ -435,10 +458,10 @@ function settleWithin(work, ms) {
  * ignores its abort signal) must never delay a command past the bound. On
  * timeout the pending work is abandoned silently.
  */
-export async function contributeClientHealth(kind, deps = {}) {
-    await settleWithin(contributeClientHealthUnbounded(kind, deps), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
+export async function contributeClientHealth(kind, deps = {}, failureReason) {
+    await settleWithin(contributeClientHealthUnbounded(kind, deps, failureReason), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
 }
-async function contributeClientHealthUnbounded(kind, deps) {
+async function contributeClientHealthUnbounded(kind, deps, failureReason) {
     try {
         const now = (deps.now ?? (() => new Date()))();
         const stateDir = (deps.stateDir ?? getStateDir)();
@@ -546,6 +569,7 @@ async function contributeClientHealthUnbounded(kind, deps) {
             journalLastSyncAt,
             now,
             localFilesOverview,
+            failureReason,
         });
         if (!heartbeat)
             return;
@@ -587,12 +611,12 @@ export function reportCliClientHealthInvocation(deps) {
  */
 export function beginSyncHealthReport(deps = {}) {
     const attempt = contributeClientHealth("sync_attempt", deps);
-    const finish = (kind) => attempt
-        .then(() => contributeClientHealth(kind, deps))
+    const finish = (kind, failureReason) => attempt
+        .then(() => contributeClientHealth(kind, deps, failureReason))
         .catch(() => undefined);
     return {
         succeeded: () => finish("sync_success"),
-        failed: () => finish("sync_failure"),
+        failed: (reason) => finish("sync_failure", reason),
     };
 }
 //# sourceMappingURL=client-health.js.map

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

@@ -1,4 +1,6 @@
 export declare const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
+export declare const PACKAGE_USE_LEASE_PURPOSES: readonly ["command", "resident-preload", "mcp-serve", "hook", "daemon"];
+export type PackageUseLeasePurpose = (typeof PACKAGE_USE_LEASE_PURPOSES)[number];
 export declare class PackageUseUpdatePendingError extends Error {
     constructor(message: string);
 }
@@ -10,7 +12,10 @@ export interface PackageUseLeaseRecord {
     pid: number;
     start_time_ms: number;
     hq_version: string;
+    purpose?: PackageUseLeasePurpose;
 }
+/** Map only fixed command words to a bounded lease purpose; never persist argv values. */
+export declare function packageUseLeasePurposeForArgv(argv: readonly string[]): PackageUseLeasePurpose;
 export interface PackageUseLeaseHandoff {
     readonly envValue: string;
     waitForChild(pid: number, childAlive: () => boolean): Promise<boolean>;
@@ -20,7 +25,7 @@ export declare function npmPrefix(root: string, platform?: NodeJS.Platform): str
 export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
 export declare function packageUseUpdateRequestPath(prefix: string, stateDirectory?: string): string;
 declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
-export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
+export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string, purpose?: PackageUseLeasePurpose): PackageUseLease;
 /**
  * Create a bounded, per-reexec rendezvous in the current lease directory.
  * The child confirms readiness only after publishing its own atomic lease.
@@ -29,7 +34,7 @@ export declare function createPackageUseLeaseHandoff(lease: PackageUseLease, tim
 export declare function createCurrentPackageUseLeaseHandoff(timeoutMs?: number): PackageUseLeaseHandoff | null;
 /** Publish this process's lease identity to a parent waiting in the same prefix. */
 export declare function publishPackageUseLeaseHandoff(lease: PackageUseLease, env?: NodeJS.ProcessEnv): boolean;
-export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
+export declare function acquireCurrentPackageUseLease(argv?: readonly string[]): PackageUseLease | null;
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
 export declare function releaseCurrentPackageUseLease(): void;
 /** The lease remains held through command execution and is released on process exit. */

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

@@ -8,12 +8,47 @@ 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;
+export const PACKAGE_USE_LEASE_PURPOSES = [
+    "command",
+    "resident-preload",
+    "mcp-serve",
+    "hook",
+    "daemon",
+];
 export class PackageUseUpdatePendingError extends Error {
     constructor(message) {
         super(message);
         this.name = "PackageUseUpdatePendingError";
     }
 }
+/** Map only fixed command words to a bounded lease purpose; never persist argv values. */
+export function packageUseLeasePurposeForArgv(argv) {
+    const args = argv.slice(2);
+    if (args[0] === "mcp" && args[1] === "serve")
+        return "mcp-serve";
+    if ((args[0] === "daemon" && args[1] === "run") ||
+        (args[0] === "mesh" && args[1] === "daemon" && args[2] === "run"))
+        return "daemon";
+    if (args[0] === "core" && ["hq-session", "checkpoint-stop-gate"].includes(args[1] ?? "")) {
+        return "hook";
+    }
+    const hasOption = (...options) => options.some((option) => args.includes(option));
+    if (args[0] === "login" ||
+        (args[0] === "auth" && args[1] === "login") ||
+        (args[0] === "agents" && ["kit", "mcp"].includes(args[1] ?? "")) ||
+        (args[0] === "agents" && ["terminal", "message"].includes(args[1] ?? "") &&
+            (args[1] === "terminal" || hasOption("--wait"))) ||
+        (args[0] === "bot" && (args[1] === "run" || (args[1] === "logs" && hasOption("--follow", "-f")))) ||
+        (args[0] === "daemon" && args[1] === "logs" && hasOption("--follow", "-f")) ||
+        (args[0] === "integrations" && args[1] === "connect") ||
+        (args[0] === "lanes" && ["watch", "message", "resume"].includes(args[1] ?? "")) ||
+        (args[0] === "monitor" && ["wait", "_run"].includes(args[1] ?? "")) ||
+        (args[0] === "pack" && args[1] === "install") ||
+        (args[0] === "pkg" && args[1] === "update") ||
+        (args[0] === "secrets" && args[1] === "sandbox"))
+        return "resident-preload";
+    return "command";
+}
 let currentPackageUseLease = null;
 function errorLabel(error) {
     if (error && typeof error === "object") {
@@ -131,7 +166,7 @@ function waitForUpdateRequest(requestPath, timeoutMs) {
         Atomics.wait(sleeper, 0, 0, 100);
     }
 }
-export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
+export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpose = "command") {
     const directory = packageUseLeaseDirectory(prefix, stateDirectory);
     mkdirSync(directory, { recursive: true, mode: 0o700 });
     const requestPath = path.join(directory, UPDATE_REQUEST);
@@ -139,6 +174,7 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
         pid: process.pid,
         start_time_ms: Math.floor(performance.timeOrigin),
         hq_version: hqVersion,
+        purpose,
     };
     const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
     const tempPath = `${leasePath}.${Math.random().toString(36).slice(2)}.tmp`;
@@ -272,7 +308,7 @@ function exists(file) {
         throw error;
     }
 }
-export function acquireCurrentPackageUseLease() {
+export function acquireCurrentPackageUseLease(argv = process.argv) {
     const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
     if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
         return null;
@@ -285,7 +321,7 @@ export function acquireCurrentPackageUseLease() {
         if (nodeModules > 0 && parts[nodeModules - 1] !== "lib")
             return null;
     }
-    const lease = acquirePackageUseLease(prefix, pkg.version);
+    const lease = acquirePackageUseLease(prefix, pkg.version, undefined, packageUseLeasePurposeForArgv(argv));
     currentPackageUseLease = lease;
     publishPackageUseLeaseHandoff(lease);
     return lease;

package/package.json

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