@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/mesh/live/daemon/work-subscribe.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Contract-2 subscriber for the personal work topic.
+ * Owns live-cache.json writes. Presence publish stays on PresenceClient.
+ */
+import type { IClientOptions } from "mqtt";
+import type { MeshMqttEventClient } from "./mqtt-events.js";
+import { type PersonalCredentialsFetcher } from "./credentials.js";
+export interface WorkCacheMqtt extends MeshMqttEventClient {
+    subscribe(topic: string, opts: {
+        qos: 0 | 1;
+    }, cb?: (err?: Error | null) => void): unknown;
+    end(force?: boolean, cb?: () => void): unknown;
+}
+export interface WorkCacheSubscriber {
+    stop: () => Promise<void>;
+}
+export declare const AGENT_INBOX_PUSH_STATE_BASENAME = "agent-inbox-push.json";
+export declare function startWorkCacheSubscriber(opts: {
+    meshRoot: string;
+    fetchCredentials?: PersonalCredentialsFetcher;
+    token?: () => Promise<string>;
+    baseUrl?: string;
+    mqttConnect: (url: string, options: IClientOptions) => WorkCacheMqtt;
+    now?: () => Date;
+    timers?: {
+        setTimeout: (fn: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+    };
+    onInfo?: (message: string) => void;
+    random?: () => number;
+}): Promise<WorkCacheSubscriber>;
+//# sourceMappingURL=work-subscribe.d.ts.map

package/dist/lib/mesh/live/daemon/work-subscribe.js

@@ -0,0 +1,262 @@
+/**
+ * Contract-2 subscriber for the personal work topic.
+ * Owns live-cache.json writes. Presence publish stays on PresenceClient.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createPersonalRealtimeFetcher, } from "./credentials.js";
+import { presignIotWssUrl } from "./presign.js";
+import { applyProjectViewPush, parseProjectViewPush } from "./live-cache.js";
+import { backoffDelayMs, RECONNECT_MIN_DELAY_MS } from "./presence.js";
+export const AGENT_INBOX_PUSH_STATE_BASENAME = "agent-inbox-push.json";
+const INBOX_PUSH_HEARTBEAT_MS = 5_000;
+function readInboxWakeSequence(meshRoot, onInfo) {
+    const target = path.join(meshRoot, AGENT_INBOX_PUSH_STATE_BASENAME);
+    try {
+        const info = fs.lstatSync(target);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            onInfo?.("agent inbox push state read ignored (not a regular file)");
+            return 0;
+        }
+        const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (Number.isSafeInteger(parsed.wakeSequence) && Number(parsed.wakeSequence) >= 0) {
+            return Number(parsed.wakeSequence);
+        }
+        onInfo?.("agent inbox push state read ignored (invalid wake sequence)");
+        return 0;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            const name = error instanceof Error ? error.name : "UnknownError";
+            onInfo?.(`agent inbox push state read failed (${name})`);
+        }
+        return 0;
+    }
+}
+function writeInboxPushState(meshRoot, state) {
+    fs.mkdirSync(meshRoot, { recursive: true, mode: 0o700 });
+    const target = path.join(meshRoot, AGENT_INBOX_PUSH_STATE_BASENAME);
+    const temporary = `${target}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT")
+                throw cleanupError;
+        }
+        throw error;
+    }
+}
+export async function startWorkCacheSubscriber(opts) {
+    const fetchCredentials = opts.fetchCredentials ??
+        (opts.token
+            ? createPersonalRealtimeFetcher({
+                token: await opts.token(),
+                baseUrl: opts.baseUrl,
+            })
+            : null);
+    if (!fetchCredentials) {
+        throw new Error("work cache subscriber needs credentials");
+    }
+    const now = opts.now ?? (() => new Date());
+    const timers = opts.timers ?? {
+        setTimeout: (fn, ms) => setTimeout(fn, ms),
+        clearTimeout: (handle) => clearTimeout(handle),
+    };
+    const random = opts.random ?? Math.random;
+    let stopped = false;
+    let client = null;
+    let reconnectLogged = false;
+    let attempt = 0;
+    let timer = null;
+    let heartbeatTimer = null;
+    let generation = 0;
+    let inboxSubscribed = false;
+    // Carry the sequence forward from the last state marker so a daemon restart
+    // cannot reuse a value the watcher has already consumed.
+    let wakeSequence = readInboxWakeSequence(opts.meshRoot, opts.onInfo);
+    const clearInboxHeartbeat = () => {
+        if (heartbeatTimer !== null)
+            timers.clearTimeout(heartbeatTimer);
+        heartbeatTimer = null;
+    };
+    const persistInboxState = (connected) => {
+        try {
+            writeInboxPushState(opts.meshRoot, {
+                connected,
+                heartbeatAtMs: now().getTime(),
+                wakeSequence,
+            });
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : "UnknownError";
+            opts.onInfo?.(`agent inbox push state write failed (${name})`);
+        }
+    };
+    const scheduleInboxHeartbeat = () => {
+        if (stopped || !inboxSubscribed)
+            return;
+        clearInboxHeartbeat();
+        heartbeatTimer = timers.setTimeout(() => {
+            heartbeatTimer = null;
+            if (!stopped && inboxSubscribed) {
+                persistInboxState(true);
+                scheduleInboxHeartbeat();
+            }
+        }, INBOX_PUSH_HEARTBEAT_MS);
+    };
+    const connect = async () => {
+        if (stopped)
+            return;
+        inboxSubscribed = false;
+        clearInboxHeartbeat();
+        persistInboxState(false);
+        const gen = ++generation;
+        let bundle;
+        try {
+            bundle = await fetchCredentials();
+        }
+        catch (err) {
+            schedule(err);
+            return;
+        }
+        if (stopped || gen !== generation)
+            return;
+        const topic = bundle.topics.work;
+        const inboxTopic = bundle.actorUid.startsWith("agt_") &&
+            bundle.topics.inbox === `hq/${bundle.actorUid}/inbox`
+            ? bundle.topics.inbox
+            : undefined;
+        if (!topic && !inboxTopic) {
+            opts.onInfo?.("work cache subscribe skipped: credentials have no supported topic");
+            return;
+        }
+        const url = presignIotWssUrl(bundle.credentials, bundle.iotEndpoint, bundle.region, now());
+        const next = opts.mqttConnect(url, {
+            clientId: `${bundle.clientId}-work`,
+            clean: true,
+            reconnectPeriod: 0,
+            protocolVersion: 4,
+        });
+        client = next;
+        next.on("connect", () => {
+            if (stopped || gen !== generation)
+                return;
+            reconnectLogged = false;
+            let pendingSubscriptions = Number(Boolean(topic)) + Number(Boolean(inboxTopic));
+            let subscriptionFailed = false;
+            const finishSubscription = (err) => {
+                if (err) {
+                    if (subscriptionFailed)
+                        return;
+                    subscriptionFailed = true;
+                    schedule(err);
+                    next.end(true);
+                    return;
+                }
+                if (subscriptionFailed)
+                    return;
+                pendingSubscriptions -= 1;
+                if (pendingSubscriptions === 0)
+                    attempt = 0;
+            };
+            if (topic) {
+                next.subscribe(topic, { qos: 1 }, (err) => finishSubscription(err));
+            }
+            if (inboxTopic) {
+                next.subscribe(inboxTopic, { qos: 1 }, (err) => {
+                    if (stopped || gen !== generation)
+                        return;
+                    if (err) {
+                        inboxSubscribed = false;
+                        clearInboxHeartbeat();
+                        persistInboxState(false);
+                        opts.onInfo?.("agent inbox push subscribe failed");
+                        finishSubscription(err);
+                        return;
+                    }
+                    inboxSubscribed = true;
+                    persistInboxState(true);
+                    scheduleInboxHeartbeat();
+                    finishSubscription();
+                });
+            }
+        });
+        next.on("message", (_topic, payload) => {
+            if (stopped || gen !== generation)
+                return;
+            if (inboxTopic && _topic === inboxTopic && inboxSubscribed) {
+                // A topic message is a doorbell only. Never parse, persist, or log its
+                // content; the authenticated inbox GET remains the source of truth.
+                wakeSequence += 1;
+                persistInboxState(true);
+                return;
+            }
+            if (_topic !== topic)
+                return;
+            const push = parseProjectViewPush(payload);
+            if (!push)
+                return;
+            const result = applyProjectViewPush(opts.meshRoot, push, now().toISOString());
+            if (result.applied) {
+                opts.onInfo?.(`project-view cache cursor=${result.cursor} ${push.companyUid}/${push.projectId}`);
+            }
+        });
+        next.on("close", () => {
+            if (stopped || gen !== generation)
+                return;
+            inboxSubscribed = false;
+            clearInboxHeartbeat();
+            persistInboxState(false);
+            schedule();
+        });
+    };
+    const schedule = (err) => {
+        if (stopped || timer !== null)
+            return;
+        if (!reconnectLogged) {
+            reconnectLogged = true;
+            const detail = err instanceof Error ? `: ${err.message}` : "";
+            opts.onInfo?.(`work cache mqtt reconnecting${detail}`.slice(0, 200));
+        }
+        if (timer !== null)
+            timers.clearTimeout(timer);
+        const delay = backoffDelayMs(attempt, 1000, 60_000, random, 0, RECONNECT_MIN_DELAY_MS);
+        attempt += 1;
+        timer = timers.setTimeout(() => {
+            timer = null;
+            void connect();
+        }, delay);
+    };
+    await connect();
+    return {
+        stop: async () => {
+            stopped = true;
+            generation += 1;
+            if (timer !== null)
+                timers.clearTimeout(timer);
+            clearInboxHeartbeat();
+            inboxSubscribed = false;
+            persistInboxState(false);
+            const current = client;
+            client = null;
+            if (!current)
+                return;
+            await new Promise((resolve) => {
+                try {
+                    current.end(true, () => resolve());
+                }
+                catch {
+                    resolve();
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=work-subscribe.js.map

package/dist/lib/mesh/live/emit-client.d.ts

@@ -23,6 +23,8 @@ export interface EmitEventResult {
     status: EmitEventStatus;
     /** Present when status != accepted (no_company_evidence | not_a_member | …). */
     reason?: string;
+    /** Server rejection code when status is rejected (`code`, else `reason`). */
+    code?: string;
     /** Resolved company (accepted, or unassigned-into-single-company). */
     companyUid?: string;
 }
@@ -72,6 +74,9 @@ export interface MeshEmitEvent {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
     evidence?: EmitEvidence;
 }
 export interface BuildMeshEmitEventInput {
@@ -88,6 +93,9 @@ export interface BuildMeshEmitEventInput {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
     evidence?: EmitEvidence;
 }
 /**

package/dist/lib/mesh/live/emit-client.js

@@ -58,10 +58,7 @@ export function parseEmitResults(body) {
             if (!status)
                 continue;
             const res = { eventId, status };
-            if (typeof r.reason === "string" && r.reason.trim())
-                res.reason = r.reason.trim();
-            else if (typeof r.code === "string" && r.code.trim())
-                res.reason = r.code.trim();
+            applyEmitReasonAndCode(res, r);
             if (typeof r.companyUid === "string" && r.companyUid.trim()) {
                 res.companyUid = r.companyUid.trim();
             }
@@ -86,16 +83,26 @@ export function parseEmitResults(body) {
                 if (!eventId)
                     continue;
                 const res = { eventId, status: "rejected" };
-                if (typeof r.reason === "string" && r.reason.trim())
-                    res.reason = r.reason.trim();
-                else if (typeof r.code === "string" && r.code.trim())
-                    res.reason = r.code.trim();
+                applyEmitReasonAndCode(res, r);
                 out.push(res);
             }
         }
     }
     return out.length > 0 ? out : null;
 }
+function applyEmitReasonAndCode(res, raw) {
+    const reason = typeof raw.reason === "string" ? raw.reason.trim() : "";
+    const code = typeof raw.code === "string" ? raw.code.trim() : "";
+    if (reason)
+        res.reason = reason;
+    else if (code)
+        res.reason = code;
+    if (res.status !== "rejected")
+        return;
+    const rejectionCode = code || reason;
+    if (rejectionCode)
+        res.code = rejectionCode;
+}
 function normalizeStatus(v) {
     if (typeof v !== "string")
         return null;
@@ -185,6 +192,14 @@ export function buildMeshEmitEvent(input) {
     const summary = keep(input.summary);
     if (summary)
         event.summary = summary;
+    const repo = keep(input.repo);
+    if (repo)
+        event.repo = repo;
+    const gitBranch = keep(input.gitBranch);
+    if (gitBranch)
+        event.gitBranch = gitBranch;
+    if (input.prUrls && input.prUrls.length > 0)
+        event.prUrls = input.prUrls;
     if (input.evidence && Object.keys(input.evidence).length > 0) {
         event.evidence = input.evidence;
     }

package/dist/lib/mesh/live/emit-evidence.d.ts

@@ -37,6 +37,17 @@ export interface BuildEmitEvidenceInput {
     readMeta?: (sessionId: string, hqRoot: string | undefined) => string | undefined;
     /** Injectable work-tree finder (tests). */
     findRepo?: (startDir: string) => string | null;
+    /**
+     * Env for HQ_SPAWN_COMPANY and the identity file. Defaults to empty so a
+     * unit test does not inherit the developer shell. Callers that emit pass
+     * `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable machine-company reader (tests). */
+    readMachineCompany?: (env: NodeJS.ProcessEnv) => {
+        slug?: string;
+        uid?: string;
+    } | undefined;
 }
 /** Dedupe absolute-ish paths, preserving first-seen order. */
 export declare function normalizeTouchedPaths(paths: Array<string | undefined | null>): string[];
@@ -46,4 +57,12 @@ export declare function normalizeTouchedPaths(paths: Array<string | undefined |
  * first touched file). All fields are omitted when empty.
  */
 export declare function buildEmitEvidence(input: BuildEmitEvidenceInput): EmitEvidence;
+/**
+ * A machine credential with no company must not be posted. The server would
+ * file it as company NONE. Hold it instead.
+ */
+export declare function machineEmitDisposition(input: {
+    machine: boolean;
+    companySlug?: string;
+}): "post" | "hold";
 //# sourceMappingURL=emit-evidence.d.ts.map

package/dist/lib/mesh/live/emit-evidence.js

@@ -9,7 +9,7 @@
  * work-tree off disk. Never reads prompts/tokens; never hits the network.
  */
 import * as path from "node:path";
-import { readMetaCompanySlug } from "../../work-context/company.js";
+import { readMachineCompanyBinding, readMetaCompanySlug } from "../../work-context/company.js";
 import { findWorkTreeRoot } from "../../work-context/repo-remote.js";
 function clean(v) {
     return typeof v === "string" && v.trim() ? v.trim() : undefined;
@@ -41,7 +41,16 @@ export function buildEmitEvidence(input) {
     const cwd = clean(input.cwd);
     const hqRoot = clean(input.hqRoot);
     const touchedPaths = normalizeTouchedPaths(input.touchedPaths ?? []);
-    const companySlug = clean(input.companySlug) ?? clean(readMeta(input.sessionId, hqRoot));
+    const env = input.env ?? {};
+    const machine = (input.readMachineCompany ?? readMachineCompanyBinding)(env);
+    const spawned = clean(env.HQ_SPAWN_COMPANY);
+    // Explicit, spawn, session meta, then the box binding (slug, else uid).
+    // A uid with no slug still rides companySlug so the event is not company NONE.
+    const companySlug = clean(input.companySlug) ??
+        spawned ??
+        clean(readMeta(input.sessionId, hqRoot)) ??
+        (machine && machine.slug !== spawned ? clean(machine.slug) : undefined) ??
+        clean(machine?.uid);
     let repoPath = clean(input.repoPath);
     if (!repoPath) {
         // Search from the cwd (a directory) or the directory of the first touched
@@ -69,6 +78,15 @@ export function buildEmitEvidence(input) {
         evidence.task = task;
     return evidence;
 }
+/**
+ * A machine credential with no company must not be posted. The server would
+ * file it as company NONE. Hold it instead.
+ */
+export function machineEmitDisposition(input) {
+    if (input.machine && !clean(input.companySlug))
+        return "hold";
+    return "post";
+}
 /** Directory of the first absolute touched file, for work-tree discovery. */
 function firstFileDir(touchedPaths) {
     const abs = touchedPaths.find((p) => path.isAbsolute(p));

package/dist/lib/mesh/live/emit.d.ts

@@ -47,8 +47,17 @@ export interface EmitEventsSummary {
     retryDepth: number;
     batches: number;
     statuses: Record<EmitEventStatus, number>;
+    /** Server code for each terminally rejected event. */
+    rejections: Array<{
+        eventId: string;
+        code: string;
+    }>;
     lastPostAt?: string;
 }
+export declare function formatEmitRejectionLines(rejections: ReadonlyArray<{
+    eventId: string;
+    code: string;
+}>): string[];
 /** Drain the retry file, post pending + new events, persist failures. */
 export declare function emitEvents(deps: EmitEventsDeps): Promise<EmitEventsSummary>;
 //# sourceMappingURL=emit.d.ts.map

package/dist/lib/mesh/live/emit.js

@@ -41,9 +41,23 @@ function writeEmitState(workMeshRoot, state) {
         /* best-effort */
     }
 }
+function rejectionCodeFromBody(body, status) {
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const rec = body;
+        if (typeof rec.code === "string" && rec.code.trim())
+            return rec.code.trim();
+        if (typeof rec.error === "string" && /^[A-Z0-9_]+$/.test(rec.error.trim())) {
+            return rec.error.trim();
+        }
+    }
+    return `HTTP_${status}`;
+}
 function eventIdOf(e) {
     return typeof e.eventId === "string" && e.eventId.trim() ? e.eventId.trim() : null;
 }
+export function formatEmitRejectionLines(rejections) {
+    return rejections.map((row) => `work-mesh: rejected eventId=${row.eventId} code=${row.code}`);
+}
 /** Drain the retry file, post pending + new events, persist failures. */
 export async function emitEvents(deps) {
     const now = deps.now ?? (() => new Date());
@@ -74,6 +88,7 @@ export async function emitEvents(deps) {
         retryDepth: 0,
         batches: 0,
         statuses: { accepted: 0, unassigned: 0, rejected: 0 },
+        rejections: [],
     };
     const keep = [];
     let anyPosted = false;
@@ -95,7 +110,13 @@ export async function emitEvents(deps) {
                 // Non-retryable 4xx (e.g. 401/400) → drop with a log (never user data).
                 summary.rejected += chunk.length;
                 summary.statuses.rejected += chunk.length;
-                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status}`);
+                const batchCode = rejectionCodeFromBody(result.body, result.status);
+                for (const event of chunk) {
+                    const id = eventIdOf(event);
+                    if (id)
+                        summary.rejections.push({ eventId: id, code: batchCode });
+                }
+                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status} code=${batchCode}`);
             }
             continue;
         }
@@ -121,8 +142,13 @@ export async function emitEvents(deps) {
                 summary.accepted += 1;
             else if (r.status === "unassigned")
                 summary.unassigned += 1;
-            else
+            else if (id) {
                 summary.rejected += 1;
+                summary.rejections.push({
+                    eventId: id,
+                    code: r.code || r.reason || "rejected",
+                });
+            }
         }
     }
     const written = writeEmitRetry(deps.workMeshRoot, keep, retryMax);

package/dist/lib/mesh/live/enqueue.d.ts

@@ -23,6 +23,11 @@ export interface EnqueueOptions {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
+    /** Local only: used to build a session_end summary; never written to the spool. */
+    transcriptPath?: string;
     cwd?: string;
     hqRoot?: string;
     companySlug?: string;

package/dist/lib/mesh/live/enqueue.js

@@ -2,6 +2,7 @@
  * Local session-event enqueue (US-008): validate + append one spool line.
  * No network. Shared line format with work-mesh-enqueue.sh.
  */
+import { enrichSessionEndEvent } from "./report-summary.js";
 import { validateSessionEvent } from "./validate-session-event.js";
 import { formatSpoolLine, } from "./format-spool-line.js";
 import { generateUlid } from "./ulid.js";
@@ -65,6 +66,12 @@ export function enqueueSessionEvent(opts) {
         event.reason = opts.reason;
     if (opts.summary)
         event.summary = opts.summary;
+    if (opts.repo)
+        event.repo = opts.repo;
+    if (opts.gitBranch)
+        event.gitBranch = opts.gitBranch;
+    if (opts.prUrls && opts.prUrls.length > 0)
+        event.prUrls = opts.prUrls;
     if (opts.cwd)
         event.cwd = opts.cwd;
     if (opts.hqRoot)
@@ -77,6 +84,18 @@ export function enqueueSessionEvent(opts) {
         event.task = opts.task;
     if (opts.toolWrites !== undefined)
         event.toolWrites = opts.toolWrites;
+    if (event.kind === "session_end") {
+        const enriched = enrichSessionEndEvent(event, { transcriptPath: opts.transcriptPath });
+        if (typeof enriched.summary === "string")
+            event.summary = enriched.summary;
+        if (typeof enriched.repo === "string")
+            event.repo = enriched.repo;
+        if (typeof enriched.gitBranch === "string")
+            event.gitBranch = enriched.gitBranch;
+        if (Array.isArray(enriched.prUrls) && enriched.prUrls.length > 0) {
+            event.prUrls = enriched.prUrls;
+        }
+    }
     const candidate = {
         ...event,
         v: 1,

package/dist/lib/mesh/live/flush.d.ts

@@ -2,20 +2,26 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
  */
+import { type SessionStateFile } from "../../work-context/state.js";
 import { type RandomFn, type SleepFn } from "./backoff.js";
 import { type SessionEventsPoster } from "./session-events-client.js";
 export declare const HELD_TTL_MS: number;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export declare const HELD_RETRY_INTERVAL_MS: number;
-/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+/** Cap distinct held events; oldest overflow is dead-lettered with HELD_OVERFLOW. */
 export declare const HELD_MAX_LINES = 20000;
-export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
+/**
+ * Re-check an unbound session against the project catalog at most this often.
+ * The catalog itself is also cached inside bind-best.
+ */
+export declare const PROJECT_REBIND_INTERVAL_MS = 60000;
+export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "NEEDS_PROJECT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
 export interface HeldLineRecord {
     /** Original spool event fields. */
     event: Record<string, unknown>;
@@ -26,6 +32,7 @@ export interface FlushDeps {
     workMeshRoot: string;
     workContextRoot: string;
     poster: SessionEventsPoster;
+    signal?: AbortSignal;
     now?: () => Date;
     sleep?: SleepFn;
     random?: RandomFn;
@@ -39,10 +46,15 @@ export interface FlushDeps {
     lastHeldRetryAtMs?: number;
     /** Invoked when this flush claims held, so the daemon can advance its timestamp. */
     onHeldClaimed?: (atMs: number) => void;
-    /** Max lines retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
+    /** Max distinct eventIds retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
     heldMaxLines?: number;
     /** Optional logger (daemon wires this); used once per overflow trim. */
     log?: (message: string) => void;
+    /** Authoritative gate for state derived from a device default. */
+    authorizeDeviceDefaultTenant?: (state: SessionStateFile) => Promise<boolean>;
+    /** Passed through to bind-best (catalog cache root and HQ_WORK_MESH_CACHE). */
+    env?: NodeJS.ProcessEnv;
+    home?: string;
 }
 export interface FlushSummary {
     claimed: number;