@indigoai-us/hq-cli 5.343.0 → 5.344.0

package/dist/lib/bot/progress.d.ts

@@ -28,13 +28,10 @@ export declare const PROGRESS_MIN_GAP_MS = 4000;
 export declare const WORKING_NOTICE_MS = 60000;
 export declare const WORKING_NOTICE_TEXT = "Working on it \u2014 I'll reply here when it's done.";
 export interface ProgressPosterOptions {
-    /** Post one message; resolve true when it was delivered. */
-    send: (body: string) => Promise<boolean>;
-    /**
-     * If provided, the final reply is sent through this instead of `send`.
-     * Use to tag the final reply differently from in-between progress messages.
-     */
-    sendFinal?: (body: string) => Promise<boolean>;
+    /** Post a live progress beat while the turn is still running. */
+    sendProgress: (body: string) => Promise<boolean>;
+    /** Post terminal content that the person needs to read. */
+    sendToPerson: (body: string) => Promise<boolean>;
     now?: () => number;
     setTimer?: (fn: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
@@ -63,8 +60,8 @@ export declare function normalizeForCompare(text: string): string;
 /** Matches {"action":"no_reply"} anywhere in a model reply, with or without preamble text. */
 export declare function containsNoReplySentinel(text: string): boolean;
 export declare class ProgressPoster {
-    private readonly send;
-    private readonly sendFinalFn?;
+    private readonly sendProgress;
+    private readonly sendToPerson;
     private readonly now;
     private readonly setTimer;
     private readonly clearTimer;
@@ -95,6 +92,8 @@ export declare class ProgressPoster {
      * deliveries posted the placeholder right after a real message.
      */
     private queued;
+    /** Posts queued for the person, excluding agent-lane status beats. */
+    private personQueued;
     constructor(opts: ProgressPosterOptions);
     /** Arm the one-time "working on it" note. Call when the turn starts. */
     start(): void;
@@ -109,11 +108,9 @@ export declare class ProgressPoster {
     /** True once any message from the model was said this turn (not counting the notice). */
     get saidAnything(): boolean;
     /**
-     * The turn succeeded: post whatever is pending, then the final answer unless
-     * it repeats what was already said. Resolves once everything is sent.
-     *
-     * When `sendFinal` was provided, progress items flush through `send` and the
-     * final reply goes through `sendFinal` — keeping their audience tags distinct.
+     * The turn succeeded: post pending human-facing text, then a human-lane
+     * terminal message when the final adds something. Agent-lane status beats
+     * alone still receive a human-lane fallback before the turn closes.
      */
     finish(finalText: string): Promise<void>;
     /**
@@ -125,6 +122,7 @@ export declare class ProgressPoster {
     private scheduleFlush;
     private flushNow;
     private enqueue;
+    private enqueueToPerson;
     private enqueueWith;
     private cancelFlush;
     private cancelNotice;

package/dist/lib/bot/progress.js

@@ -36,8 +36,8 @@ export function containsNoReplySentinel(text) {
     return /\{\s*"action"\s*:\s*"no_reply"\s*\}/.test(text);
 }
 export class ProgressPoster {
-    send;
-    sendFinalFn;
+    sendProgress;
+    sendToPerson;
     now;
     setTimer;
     clearTimer;
@@ -68,9 +68,11 @@ export class ProgressPoster {
      * deliveries posted the placeholder right after a real message.
      */
     queued = 0;
+    /** Posts queued for the person, excluding agent-lane status beats. */
+    personQueued = 0;
     constructor(opts) {
-        this.send = opts.send;
-        this.sendFinalFn = opts.sendFinal;
+        this.sendProgress = opts.sendProgress;
+        this.sendToPerson = opts.sendToPerson;
         this.now = opts.now ?? Date.now;
         this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
         this.clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
@@ -92,7 +94,7 @@ export class ProgressPoster {
             if (this.finished || this.said.length > 0 || this.noticeSent)
                 return;
             this.noticeSent = true;
-            this.enqueue(this.workingNoticeText);
+            this.enqueueWith(this.workingNoticeText, this.sendProgress);
         }, this.workingNoticeMs);
     }
     /** One finished assistant message from the model. */
@@ -147,11 +149,9 @@ export class ProgressPoster {
         return this.said.length > 0;
     }
     /**
-     * The turn succeeded: post whatever is pending, then the final answer unless
-     * it repeats what was already said. Resolves once everything is sent.
-     *
-     * When `sendFinal` was provided, progress items flush through `send` and the
-     * final reply goes through `sendFinal` — keeping their audience tags distinct.
+     * The turn succeeded: post pending human-facing text, then a human-lane
+     * terminal message when the final adds something. Agent-lane status beats
+     * alone still receive a human-lane fallback before the turn closes.
      */
     async finish(finalText) {
         if (this.finished)
@@ -171,42 +171,25 @@ export class ProgressPoster {
         // Grok's final is every message concatenated, so it repeats and is skipped.
         // A silent turn (run.ts decides via sentinel/empty) never reaches here.
         if (this.buffer) {
+            const terminalParts = this.said.filter((s) => !containsNoReplySentinel(s));
             this.pending = [];
             this.heldQuestions = [];
-            for (const s of this.said) {
-                if (!containsNoReplySentinel(s))
-                    this.pending.push(s);
-            }
             if (final && !containsNoReplySentinel(final) && !this.repeatsSaid(final)) {
-                if (this.sendFinalFn) {
-                    // Keep the audience split: collected messages go through send, the
-                    // final reply through sendFinal.
-                    this.flushNow();
-                    this.enqueueWith(final, this.sendFinalFn);
-                    return this.chain;
-                }
-                this.pending.push(final);
+                terminalParts.push(final);
             }
-            this.flushNow();
+            this.enqueueToPerson(terminalParts.join("\n\n") || "(no reply)");
             return this.chain;
         }
         const held = this.heldQuestions;
         this.heldQuestions = [];
-        const shouldAddFinal = Boolean(final && !this.repeatsSaid(final));
-        if (!shouldAddFinal && held.length > 0)
-            this.pending.push(...held);
-        if (this.pending.length === 0 && this.queued === 0 && !shouldAddFinal)
-            this.pending.push("(no reply)");
-        if (this.sendFinalFn && shouldAddFinal) {
-            // Flush any remaining progress messages first, then the final reply separately.
-            this.flushNow();
-            this.enqueueWith(final, this.sendFinalFn);
-        }
-        else {
-            if (shouldAddFinal)
-                this.pending.push(final);
-            this.flushNow();
-        }
+        this.flushNow();
+        const shouldAddFinal = Boolean(final && !containsNoReplySentinel(final) && !this.repeatsSaid(final));
+        if (shouldAddFinal)
+            this.enqueueToPerson(final);
+        else if (held.length > 0)
+            this.enqueueToPerson(held.join("\n\n"));
+        else if (this.personQueued === 0)
+            this.enqueueToPerson("(no reply)");
         return this.chain;
     }
     /**
@@ -226,9 +209,11 @@ export class ProgressPoster {
             this.heldQuestions = [];
             return this.chain;
         }
-        this.pending.push(...this.heldQuestions);
+        const held = this.heldQuestions;
         this.heldQuestions = [];
         this.flushNow();
+        if (held.length > 0)
+            this.enqueueToPerson(held.join("\n\n"));
         return this.chain;
     }
     repeatsSaid(final) {
@@ -256,7 +241,11 @@ export class ProgressPoster {
         this.enqueue(body);
     }
     enqueue(body) {
-        this.enqueueWith(body, this.send);
+        this.enqueueToPerson(body);
+    }
+    enqueueToPerson(body) {
+        this.personQueued += 1;
+        this.enqueueWith(body, this.sendToPerson);
     }
     enqueueWith(body, sendFn) {
         // Defence in depth: never let the silence sentinel reach the chat, whatever

package/dist/lib/bot/run.js

@@ -766,8 +766,8 @@ export async function runBot(deps) {
             ...deps.progress,
             ...(args.workingNotice === false || silenceable || isSetupBot ? { workingNoticeMs: 0 } : {}),
             ...(silenceable || args.suppressOutput ? { buffer: true } : {}),
-            send: makeSendFn(args.send),
-            ...(args.sendFinal ? { sendFinal: makeSendFn(args.sendFinal) } : {}),
+            sendProgress: makeSendFn(args.sendProgress),
+            sendToPerson: makeSendFn(args.sendToPerson),
         });
         const controller = new AbortController();
         currentTurns.add(controller);
@@ -827,7 +827,7 @@ export async function runBot(deps) {
         const root = rootEventId ? { rootEventId } : {};
         return target.kind === "dm"
             ? api.sendDm({ toPersonUid: target.peerUid, body, ...root, ...(audience ? { audience } : {}) })
-            : api.sendChannelMessage({ channelId: target.channelId, body, ...root });
+            : api.sendChannelMessage({ channelId: target.channelId, body, ...root, ...(audience ? { audience } : {}) });
     };
     /**
      * Post `parts` in order, starting at `from`. A failure throws a
@@ -863,15 +863,15 @@ export async function runBot(deps) {
                 throw err;
             }
         };
-        const send = makeSend(target.kind === "dm" ? "agent" : undefined);
-        const sendFinal = makeSend(target.kind === "dm" ? "human" : undefined);
+        const sendProgress = makeSend("agent");
+        const sendToPerson = makeSend("human");
         const saved = (reply) => {
             const parts = splitBody(reply);
             const partial = last.value;
             const sameBody = partial !== null && partial.parts.length === parts.length && partial.parts.every((p, i) => p === parts[i]);
             return { reply, replyParts: parts, replyPartsDelivered: sameBody ? partial.delivered : 0 };
         };
-        return { send, sendFinal, saved };
+        return { sendProgress, sendToPerson, saved };
     };
     // ── Scheduled jobs ────────────────────────────────────────────────────────
     /** Newest pending run key already picked up, per jobId (one catch-up per wake). */
@@ -1113,14 +1113,14 @@ export async function runBot(deps) {
             }
         };
         const target = { kind: "dm", peerUid };
-        const { send, sendFinal, saved } = trackingSend(target);
+        const { sendProgress, sendToPerson, saved } = trackingSend(target);
         const { outcome, poster } = await runTurnWithProgress({
             marker: { messageId: KICKOFF_MESSAGE_ID, target, ...(thinking && introEventId ? { reactionEventId: introEventId } : {}) },
             prompt,
             sessionScope: "dm",
             tReceived,
-            send,
-            sendFinal,
+            sendProgress,
+            sendToPerson,
             // The intro already said the bot is starting, and the app shows it thinking.
             workingNotice: false,
         });
@@ -1146,7 +1146,7 @@ export async function runBot(deps) {
             clearInflight(dir, KICKOFF_MESSAGE_ID);
             patchBotConfig(dir, { kickoffPendingSignIn: true });
             markSignInBroken(outcome.excerpt);
-            await tellSignInNeeded("dm", send, true);
+            await tellSignInNeeded("dm", sendToPerson, true);
             return;
         }
         if (readBotConfig(dir)?.kickoffPendingSignIn)
@@ -1158,7 +1158,7 @@ export async function runBot(deps) {
             ? `${didNotFinishText(failureReason(outcome), poster.postedCount > 0)} Send me any message and I'll pick up from there.`
             : `Sorry — I couldn't get started on my own (${runtime.id} failed: ${outcome.excerpt.slice(0, 160)}). Send me any message and I'll pick up from there, or check that ${runtime.id} is signed in on this computer.`;
         try {
-            await send(body);
+            await sendToPerson(body);
             clearInflight(dir, KICKOFF_MESSAGE_ID);
         }
         catch {
@@ -1235,8 +1235,8 @@ export async function runBot(deps) {
                 throw err;
             }
         };
-        const send = makeSend(tracking.send);
-        const sendFinal = makeSend(tracking.sendFinal);
+        const sendProgress = makeSend(tracking.sendProgress);
+        const sendToPerson = makeSend(tracking.sendToPerson);
         const normalize = (text) => text.replace(/\s+/g, " ").trim();
         /**
          * True only when the final report itself reached the chat in full. With no
@@ -1272,8 +1272,8 @@ export async function runBot(deps) {
             prompt: buildJobTurnPrompt(job, { now: now(), timeZone }),
             sessionScope: target.sessionScope,
             tReceived,
-            send,
-            sendFinal,
+            sendProgress,
+            sendToPerson,
             // A scheduled run has nobody waiting in a chat: no "working on it" filler.
             workingNotice: false,
             ...(quietJob ? { suppressOutput: true } : {}),
@@ -1307,7 +1307,7 @@ export async function runBot(deps) {
             clearInflight(dir, id);
             attempts.delete(id);
             markSignInBroken(outcome.excerpt);
-            await tellSignInNeeded(`job:${jobId}`, (body) => sendToTarget(markerTarget, body));
+            await tellSignInNeeded(`job:${jobId}`, (body) => sendToTarget(markerTarget, body, undefined, "human"));
             log("warn", `kept scheduled run ${id} of job ${jobId} until ${runtime.id} can sign in again`);
             return; // un-acked, un-reported: run once the sign-in works
         }
@@ -1320,7 +1320,7 @@ export async function runBot(deps) {
                 return;
             }
             if (attempt >= MAX_ATTEMPTS_PER_MESSAGE) {
-                await send(`I couldn't run this one — ${runtime.id} kept failing: ${excerpt.slice(0, 160)}.`).catch(() => undefined);
+                await sendToPerson(`I couldn't run this one — ${runtime.id} kept failing: ${excerpt.slice(0, 160)}.`).catch(() => undefined);
                 await completeJobRun(jobId, id, { status: "failed", output: jobRunOutput(excerpt), disposition: `${runtime.id} could not be started` });
                 markReported("failed");
                 markProcessed(dir, id, now().toISOString());
@@ -1339,7 +1339,7 @@ export async function runBot(deps) {
         // reports and says this real reason, not "the bot was restarted".
         patchInflight(dir, id, { jobFailure: { reason, ...(outcome.excerpt ? { excerpt: outcome.excerpt } : {}) } });
         try {
-            await send(didNotFinishText(reason, poster.postedCount > 0));
+            await sendToPerson(didNotFinishText(reason, poster.postedCount > 0));
         }
         catch (err) {
             // Leave it un-acked with the marker: the next poll reports it.
@@ -1534,7 +1534,7 @@ export async function runBot(deps) {
         const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? ownerText :
             `[HQ DM sender: ${target.peerUid}; owner: ${config.ownerUid}; sender is not the owner.]\n\n${text}`;
         const markerTarget = target.kind === "dm" ? { kind: "dm", peerUid: target.peerUid } : { kind: "room", channelId: target.channelId };
-        const { send, sendFinal, saved } = trackingSend(markerTarget, item.rootEventId);
+        const { sendProgress, sendToPerson, saved } = trackingSend(markerTarget, item.rootEventId);
         const { outcome, poster } = await runTurnWithProgress({
             marker: {
                 messageId: id,
@@ -1545,8 +1545,8 @@ export async function runBot(deps) {
             prompt,
             sessionScope,
             tReceived,
-            send,
-            sendFinal,
+            sendProgress,
+            sendToPerson,
             silenceable: target.kind === "room" && !target.mentioned,
             ...(readDirs.length ? { readDirs } : {}),
             ...(target.kind === "room"
@@ -1605,7 +1605,7 @@ export async function runBot(deps) {
             attempts.delete(id);
             markSignInBroken(outcome.excerpt);
             const conversation = markerTarget.kind === "dm" ? sessionScope : `room:${markerTarget.channelId}:${item.rootEventId ?? ""}`;
-            await tellSignInNeeded(conversation, send);
+            await tellSignInNeeded(conversation, sendToPerson);
             log("warn", `kept ${id} until ${runtime.id} can sign in again`);
             return; // un-acked: answered once the sign-in works
         }
@@ -1620,7 +1620,7 @@ export async function runBot(deps) {
             }
             if (attempt >= MAX_ATTEMPTS_PER_MESSAGE) {
                 try {
-                    await send(`Sorry — I couldn't answer that one (${runtime.id} kept failing: ${excerpt.slice(0, 160)}). Try again in a bit, or check that ${runtime.id} is signed in on this computer.`);
+                    await sendToPerson(`Sorry — I couldn't answer that one (${runtime.id} kept failing: ${excerpt.slice(0, 160)}). Try again in a bit, or check that ${runtime.id} is signed in on this computer.`);
                 }
                 catch {
                     /* best-effort */
@@ -1660,7 +1660,7 @@ export async function runBot(deps) {
             // still say we did not finish — but with a plain reason, never the raw
             // internal error string.
             const reason = reasoningOnly ? "the model returned no answer" : failureReason(outcome);
-            await send(didNotFinishText(reason, poster.postedCount > 0));
+            await sendToPerson(didNotFinishText(reason, poster.postedCount > 0));
         }
         catch (err) {
             // Leave it un-acked with the marker: the next poll says it did not finish.

package/dist/lib/core-utils/sentry-report.d.ts

@@ -26,7 +26,7 @@ export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
  * is owner-approved telemetry for the exact hook script and may include a
  * company directory; it is never a substitute for hook input or a transcript.
  */
-export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "hook_script", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average", "spawn_ms", "slow_child", "slow_child_ms", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence", "hook_timeout_debug_context"];
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "hook_script", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average", "spawn_ms", "slow_child", "slow_child_ms", "slow_phase", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence", "hook_timeout_debug_context"];
 export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
 export type HookSequenceEntry = {
     script: string;

package/dist/lib/core-utils/sentry-report.js

@@ -130,18 +130,25 @@ const DEBUG_CONTEXT_HOOK_EVENTS = new Set([
     "TaskCompleted",
     "TeammateIdle",
 ]);
-const DEBUG_CONTEXT_PHASES = new Set([
+const SAFE_SLOW_PHASES = new Set([
     "startup",
     "source",
     "config_load",
     "policy_load",
     "external_command",
     "output_write",
+    "output_scan",
+    "output_merge",
+    "output_stdout",
+    "output_abandoned_scan",
+    "output_abandoned_merge",
+    "output_abandoned_stdout",
     "wait",
     "child_wait",
     "probe",
     "parse",
 ]);
+const DEBUG_CONTEXT_PHASES = new Set(SAFE_SLOW_PHASES);
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -166,6 +173,7 @@ export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
     "spawn_ms",
     "slow_child",
     "slow_child_ms",
+    "slow_phase",
     "exit_code",
     "final_elapsed_ms",
     "bash_env_set",
@@ -255,6 +263,11 @@ function boundedDebugName(value, known) {
 function boundedDebugPhase(value) {
     return typeof value === "string" && DEBUG_CONTEXT_PHASES.has(value) ? value : "other";
 }
+function safeSlowPhase(value) {
+    if (typeof value !== "string")
+        return "unknown";
+    return SAFE_SLOW_PHASES.has(value) ? value : "other";
+}
 function boundedDebugHookEvent(value) {
     return typeof value === "string" && DEBUG_CONTEXT_HOOK_EVENTS.has(value) ? value : "other";
 }
@@ -425,6 +438,9 @@ function parseSentryReportEvent(stdin) {
     if (typeof metadata.slow_child === "string") {
         metadata.slow_child = safeSlowChild(metadata);
     }
+    if ("slow_phase" in metadata) {
+        metadata.slow_phase = safeSlowPhase(metadata.slow_phase);
+    }
     return {
         code: 0,
         event: {
@@ -678,6 +694,7 @@ function hookTimeoutTags(event) {
         load_bucket: loadAverage === "unavailable" ? "unavailable" : loadBucket(loadAverage),
         spawn_ms_bucket: spawnMsBucket(metadata),
         slow_child: safeSlowChild(metadata),
+        slow_phase: safeSlowPhase(metadata.slow_phase),
         slow_child_ms_bucket: typeof slowChildMs === "number" && Number.isFinite(slowChildMs)
             ? elapsedBucket(slowChildMs)
             : "unknown",

package/dist/lib/daemon/command-call.d.ts

@@ -0,0 +1,9 @@
+interface DaemonCallDependencies {
+    home: string;
+    env: NodeJS.ProcessEnv;
+    out: (line: string) => void;
+}
+/** Send one CLI request after its protocol module has been preloaded. */
+export declare function runDaemonCall(op: string, args: Record<string, unknown>, timeoutMs: number, deps: DaemonCallDependencies): Promise<void>;
+export {};
+//# sourceMappingURL=command-call.d.ts.map

package/dist/lib/daemon/command-call.js

@@ -0,0 +1,18 @@
+/** Send one CLI request after its protocol module has been preloaded. */
+export async function runDaemonCall(op, args, timeoutMs, deps) {
+    const { hqdRequest, hqdSocketPath, HqdClientError } = await import("./protocol.js");
+    try {
+        const result = await hqdRequest(op, args, {
+            socketPath: hqdSocketPath(deps.home, deps.env),
+            timeoutMs,
+        });
+        deps.out(JSON.stringify(result, null, 2));
+    }
+    catch (error) {
+        if (!(error instanceof HqdClientError))
+            throw error;
+        deps.out(JSON.stringify({ error: { code: error.code, message: error.message } }, null, 2));
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=command-call.js.map

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -146,6 +146,7 @@ export declare function dispatchOutpostPickup(port: OutpostExecPort, input: {
     command: string;
     timeoutSeconds?: number;
     waitMs?: number;
+    beforeWait?: () => Promise<void>;
 }): Promise<OutpostDispatchResult>;
 export declare function dispatchErrorMessage(err: unknown): string;
 /** Factory matching `hq outposts exec`'s client wiring. */

package/dist/lib/lanes/outpost-dispatch.js

@@ -252,6 +252,7 @@ export async function stageOutpostPayload(port, outpostId, bytes, put = fetch) {
 }
 export async function dispatchOutpostPickup(port, input) {
     const submitted = await port.submitExec(input.command, input.outpostId, input.timeoutSeconds ?? PICKUP_EXEC_TIMEOUT_SECONDS);
+    await input.beforeWait?.();
     const ac = new AbortController();
     const waitMs = input.waitMs ?? PICKUP_WAIT_MS;
     const timer = setTimeout(() => ac.abort(), waitMs);

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).