@indigoai-us/hq-cli 5.225.0 → 5.227.0

package/dist/lib/checkpoint-ontology/plan.js

@@ -15,7 +15,6 @@ import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
-export const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
 export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
  * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
@@ -163,14 +162,13 @@ function missingRefs(companyDir, rel) {
 }
 /**
  * Update the ledger with the current tree and return it. New or changed files
- * become pending when this machine should process them (design 14.1) and
- * seen otherwise. The first run seeds from the entity boundary (design 14.3).
+ * the session touched become pending; others are recorded as seen. The first
+ * run records the entity boundary (design 14.3).
  */
-export function refreshLedger(company, existing, touched, sharedInputs) {
+export function refreshLedger(company, existing, touched) {
     const firstRun = existing === null;
     const index = firstRun ? buildEntityIndex(company.dir) : null;
     const boundary = existing ? existing.boundary : entityBoundary(index);
-    const boundaryMs = boundary ? Date.parse(boundary) : Number.NaN;
     const entries = {};
     const files = [...listKnowledgeFiles(company.dir), ...listSignalFiles(company.dir)];
     for (const rel of files) {
@@ -188,24 +186,10 @@ export function refreshLedger(company, existing, touched, sharedInputs) {
                 : { ...previous, ...base };
             continue;
         }
-        let reason = null;
-        if (touched.has(rel))
-            reason = "session-touched";
-        else if (sharedInputs && firstRun) {
-            if (Number.isFinite(boundaryMs) && stat.mtimeMs > boundaryMs)
-                reason = "first-run-gap";
-            else if (rel.startsWith("signals/") && missingRefs(company.dir, rel).length > 0)
-                reason = "missing-refs";
-        }
-        else if (sharedInputs)
-            reason = "shared";
-        entries[rel] = reason ? { ...base, state: "pending", reason } : { ...base, state: "seen" };
+        entries[rel] = touched.has(rel) ? { ...base, state: "pending", reason: "session-touched" } : { ...base, state: "seen" };
     }
     return { ledger: { schema: LEDGER_SCHEMA, company: company.slug, boundary, entries }, firstRun };
 }
-function reasonRank(reason) {
-    return reason === "session-touched" ? 0 : 1;
-}
 /** Plan this run. Never throws for a skip; returns the reason instead. */
 export async function planOntologyRun(options) {
     const { hqRoot, runDir, payload } = options;
@@ -218,7 +202,6 @@ export async function planOntologyRun(options) {
         fs.rmSync(backendPreferencePath(hqRoot, company), { force: true });
         return { status: "skipped", reason: "flag off" };
     }
-    const sharedInputs = await options.readFlag(SHARED_INPUTS_FLAG, company);
     const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
     recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
@@ -226,15 +209,15 @@ export async function planOntologyRun(options) {
     const touched = sessionTouched(hqRoot, company, payload.files);
     // A first run takes its boundary from the entity tree, so the ledger is
     // refreshed before merge-back moves any `last_updated` forward.
-    const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched, sharedInputs);
+    const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched);
     // Merge-back and the brief come before the nothing-changed return, so such
     // a plan still merges set-aside versions and records the brief; the brief
     // follows merge-back so its counts include merged entities.
     const multiWriter = multiWriterOn ? startMultiWriterRun(hqRoot, company, options.now ?? new Date()) : undefined;
     const companyBrief = briefOn ? writeCompanyBrief(hqRoot, company, options.now ?? new Date()) : undefined;
     const pending = Object.entries(ledger.entries)
-        .filter(([, entry]) => entry.state === "pending" && (sharedInputs || entry.reason === "session-touched"))
-        .sort(([aRel, a], [bRel, b]) => reasonRank(a.reason) - reasonRank(b.reason) || a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
+        .filter(([, entry]) => entry.state === "pending" && entry.reason === "session-touched")
+        .sort(([aRel, a], [bRel, b]) => a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
     const inputs = [];
     let tokens = 0;
     let remaining = 0;
@@ -264,7 +247,7 @@ export async function planOntologyRun(options) {
                 kind,
                 path: rel,
                 audience: "company",
-                reason: entry.reason ?? "shared",
+                reason: "session-touched",
                 sha256: entry.sha256,
                 est_tokens: cost,
                 lines: chunks.length > 1 ? [start, end] : null,
@@ -313,7 +296,6 @@ export async function planOntologyRun(options) {
         created_at: (options.now ?? new Date()).toISOString(),
         first_run: firstRun,
         boundary: ledger.boundary,
-        shared_inputs: sharedInputs,
         ...(companyBrief
             ? {
                 company_brief: companyBrief.reason

package/dist/lib/doctor/client-health-flag-token.d.ts

@@ -0,0 +1,15 @@
+export declare const CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS = 1000;
+export declare class MissingFlagTokenError extends Error {
+    constructor();
+}
+export declare class ClientHealthFlagTokenTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+export type ClientHealthFlagTokenProvider = (signal: AbortSignal) => string | Promise<string>;
+/**
+ * Obtain a non-interactive ID token, separately bounded from the flag read.
+ * ensureCognitoIdToken refreshes expired person sessions and selects machine
+ * identity credentials when the current installation is a machine.
+ */
+export declare function getClientHealthFlagToken(provider?: ClientHealthFlagTokenProvider, timeoutMs?: number, callerSignal?: AbortSignal): Promise<string>;
+//# sourceMappingURL=client-health-flag-token.d.ts.map

package/dist/lib/doctor/client-health-flag-token.js

@@ -0,0 +1,66 @@
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+export const CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS = 1_000;
+export class MissingFlagTokenError extends Error {
+    constructor() {
+        super("No cached HQ identity token is available");
+        this.name = "MissingFlagTokenError";
+    }
+}
+export class ClientHealthFlagTokenTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Client-health flag token acquisition exceeded its ${timeoutMs} ms bound`);
+        this.name = "ClientHealthFlagTokenTimeoutError";
+    }
+}
+/**
+ * Obtain a non-interactive ID token, separately bounded from the flag read.
+ * ensureCognitoIdToken refreshes expired person sessions and selects machine
+ * identity credentials when the current installation is a machine.
+ */
+export async function getClientHealthFlagToken(provider, timeoutMs = CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS, callerSignal) {
+    if (callerSignal?.aborted) {
+        throw callerSignal.reason ?? new Error("Token acquisition was aborted");
+    }
+    const controller = new AbortController();
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const timeout = new ClientHealthFlagTokenTimeoutError(timeoutMs);
+    const timer = setTimeout(() => controller.abort(timeout), timeoutMs);
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error("Token acquisition was aborted"));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        const acquire = provider ?? ((requestSignal) => ensureCognitoIdToken({ interactive: false, signal: requestSignal }));
+        const acquisition = Promise.resolve().then(() => {
+            if (signal.aborted) {
+                throw signal.reason ?? new Error("Token acquisition was aborted");
+            }
+            return acquire(signal);
+        });
+        const token = await Promise.race([acquisition, aborted]);
+        if (signal.aborted) {
+            throw signal.reason ?? new Error("Token acquisition was aborted");
+        }
+        if (typeof token !== "string" || token.trim().length === 0) {
+            throw new MissingFlagTokenError();
+        }
+        return token;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith("No valid HQ session and interactive login is disabled")) {
+            throw new MissingFlagTokenError();
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=client-health-flag-token.js.map

package/dist/lib/doctor/client-health-reason-codes-flag.d.ts

@@ -7,6 +7,7 @@ export interface ClientHealthReasonCodesFlagDependencies {
     env?: NodeJS.ProcessEnv;
     createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
     getToken?: FlagClientOptions["getToken"];
+    tokenTimeoutMs?: number;
     fetch?: typeof fetch;
     reportFailure?: (error: unknown) => void;
 }

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -1,6 +1,6 @@
-import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient, } from "@indigoai-us/hq-flags-client";
 import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { getClientHealthFlagToken } from "./client-health-flag-token.js";
 export const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
 export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
 export const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
@@ -39,9 +39,8 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
         return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
     }
     const companySlug = company.companySlug?.trim() || "";
-    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS);
-    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
-    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    if (callerSignal?.aborted)
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
     let client;
     let failed = false;
     let failureReported = false;
@@ -53,6 +52,18 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
         failureReported = true;
         (dependencies.reportFailure ?? reportFlagFailure)(error);
     };
+    let token;
+    try {
+        token = await getClientHealthFlagToken(dependencies.getToken, dependencies.tokenTimeoutMs, callerSignal);
+    }
+    catch (error) {
+        if (!callerSignal?.aborted)
+            reportFailureOnce(error);
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
     try {
         client = (dependencies.createClient ?? createFlagClient)({
             endpoint,
@@ -61,7 +72,7 @@ export async function clientHealthReasonCodesEnabledForCompany(company, dependen
                 ? { companyIdentifiers: [companySlug] }
                 : {}),
             env: {},
-            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            getToken: () => token,
             fetch: (input, init) => doFetch(input, {
                 ...init,
                 signal: combineSignals(init?.signal ?? undefined, signal),

package/dist/lib/doctor/client-health-sentry-flag.d.ts

@@ -7,6 +7,7 @@ export interface ClientHealthSentryFlagDependencies {
     env?: NodeJS.ProcessEnv;
     createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
     getToken?: FlagClientOptions["getToken"];
+    tokenTimeoutMs?: number;
     fetch?: typeof fetch;
     reportFailure?: (error: unknown) => void;
 }

package/dist/lib/doctor/client-health-sentry-flag.js

@@ -1,6 +1,6 @@
-import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient, } from "@indigoai-us/hq-flags-client";
 import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { getClientHealthFlagToken } from "./client-health-flag-token.js";
 export const CLIENT_HEALTH_SENTRY_DIRECT_FLAG = "client-health.sentry-direct";
 export const CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK = false;
 export const CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS = 150;
@@ -31,10 +31,8 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
     if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
         return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
     }
-    const companySlug = company.companySlug?.trim() || "";
-    const deadline = AbortSignal.timeout(CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS);
-    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
-    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    if (callerSignal?.aborted)
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
     let client;
     let failed = false;
     let failureReported = false;
@@ -46,6 +44,19 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
         failureReported = true;
         (dependencies.reportFailure ?? reportFlagFailure)(error);
     };
+    let token;
+    try {
+        token = await getClientHealthFlagToken(dependencies.getToken, dependencies.tokenTimeoutMs, callerSignal);
+    }
+    catch (error) {
+        if (!callerSignal?.aborted)
+            reportFailureOnce(error);
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
     try {
         client = (dependencies.createClient ?? createFlagClient)({
             endpoint: resolveFlagRegistryEndpoint(undefined, env),
@@ -54,7 +65,7 @@ export async function clientHealthSentryDirectEnabledForCompany(company, depende
                 ? { companyIdentifiers: [companySlug] }
                 : {}),
             env: {},
-            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            getToken: () => token,
             fetch: (input, init) => doFetch(input, {
                 ...init,
                 signal: combineSignals(init?.signal ?? undefined, signal),

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

@@ -50,6 +50,8 @@ export interface DrainDeps {
     afterRead?: () => void;
     /** Prefix marks archives that belong to one provider turn. */
     archivePrefix?: string;
+    /** Terminal messages with no permitted delivery path are kept separately. */
+    archiveDirectory?: "delivered" | "undeliverable";
 }
 export interface LaneDrainHookInput {
     transcript_path?: string | null;
@@ -68,6 +70,13 @@ export declare function mintClaimId(): string;
 export declare function assertSafeLaneId(laneId: string): void;
 export declare function dropboxDir(hqRoot: string, laneId: string): string;
 export declare function dropboxInboxPath(hqRoot: string, laneId: string): string;
+/** A recovery drain can claim the inbox, draining files, or dead inflight files. */
+export declare function dropboxInboxHasMessages(hqRoot: string, laneId: string): boolean;
+/**
+ * Return a failed recovery claim to the append-only inbox without replacing
+ * messages appended while resume validation or spawn was in progress.
+ */
+export declare function requeueDropboxMessages(hqRoot: string, laneId: string, messages: readonly DropboxMessage[]): void;
 /**
  * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
  * `--output-format json` writes nothing to worker.out until it exits, so the

package/dist/lib/lanes/dropbox.js

@@ -65,6 +65,75 @@ export function dropboxDir(hqRoot, laneId) {
 export function dropboxInboxPath(hqRoot, laneId) {
     return path.join(dropboxDir(hqRoot, laneId), INBOX_NAME);
 }
+function directoryHasRecoverableFiles(dir, nestedInboxOnly = false) {
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    for (const name of names) {
+        const candidate = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(candidate);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        if (nestedInboxOnly) {
+            if (!stat.isDirectory())
+                continue;
+            try {
+                const inbox = fs.statSync(path.join(candidate, INBOX_NAME));
+                if (inbox.isFile() && inbox.size > 0)
+                    return true;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        }
+        else if (stat.isFile() && stat.size > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function fileHasBytes(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.isFile() && stat.size > 0;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/** A recovery drain can claim the inbox, draining files, or dead inflight files. */
+export function dropboxInboxHasMessages(hqRoot, laneId) {
+    const box = dropboxDir(hqRoot, laneId);
+    return fileHasBytes(path.join(box, INBOX_NAME)) ||
+        directoryHasRecoverableFiles(path.join(box, DRAINING_DIR)) ||
+        directoryHasRecoverableFiles(path.join(box, INFLIGHT_DIR), true);
+}
+/**
+ * Return a failed recovery claim to the append-only inbox without replacing
+ * messages appended while resume validation or spawn was in progress.
+ */
+export function requeueDropboxMessages(hqRoot, laneId, messages) {
+    if (messages.length === 0)
+        return;
+    const inbox = dropboxInboxPath(hqRoot, laneId);
+    fs.mkdirSync(path.dirname(inbox), { recursive: true });
+    fs.appendFileSync(inbox, messages.map((message) => `${JSON.stringify(message)}\n`).join(""), "utf8");
+}
 /**
  * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
  * `--output-format json` writes nothing to worker.out until it exits, so the
@@ -220,7 +289,7 @@ export function drainDropboxAtPath(box, depsInput = {}) {
         return [];
     const inbox = path.join(box, INBOX_NAME);
     const draining = path.join(box, DRAINING_DIR);
-    const delivered = path.join(box, DELIVERED_DIR);
+    const delivered = path.join(box, deps.archiveDirectory ?? DELIVERED_DIR);
     const inflightRoot = path.join(box, INFLIGHT_DIR);
     try {
         deps.mkdirSync(box, { recursive: true });

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

@@ -81,6 +81,10 @@ export interface ReconcileDeps {
     readRegistryFlag?: typeof readLanesRegistryFlag;
     /** Active-company fallback for questions raised from an unscoped lane. */
     resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
+    /** Index local questions and poll remote answers before the normal answer-wake pass. */
+    syncTrackerQuestions?: (hqRoot: string) => Promise<void>;
+    /** Resume queued messages after this pass wins a local dead-worker CAS. */
+    recoverQueuedMessages?: (lane: LaneRecord) => Promise<void>;
     /** Detached mesh seam for dead-watcher recovery. */
     mesh?: LaneMesh | null;
     /** Bound on one terminal mesh emit during dead-host recovery. Default 10 s. */

package/dist/lib/lanes/reconcile.js

@@ -632,6 +632,14 @@ export async function runPassBody(hqRoot, deps) {
     const livenessDeps = deps.livenessDeps ?? defaultLivenessDeps();
     let lanes;
     let questions;
+    if (!deps.dryRun) {
+        try {
+            await deps.syncTrackerQuestions?.(hqRoot);
+        }
+        catch (err) {
+            markError(summary, err);
+        }
+    }
     try {
         lanes = loadLaneRecords(hqRoot, summary);
         questions = loadQuestionRecords(hqRoot, summary);
@@ -845,6 +853,14 @@ export async function runPassBody(hqRoot, deps) {
         await admitQueued(hqRoot, drainLanes, summary, deps, now);
         await resumeAwaiting(hqRoot, drainLanes, freshQuestions, summary, deps);
     });
+    if (!deps.dryRun && deps.syncTrackerQuestions) {
+        try {
+            await deps.syncTrackerQuestions(hqRoot);
+        }
+        catch (err) {
+            markError(summary, err);
+        }
+    }
     if (!deps.dryRun && summary.errors.length === 0) {
         try {
             writeHeartbeatFile(hqRoot, summary, nowIso);
@@ -1172,6 +1188,18 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                             }
                         }
                     }
+                    if (!deps.dryRun && deps.recoverQueuedMessages) {
+                        try {
+                            await deps.recoverQueuedMessages(result.record);
+                        }
+                        catch (err) {
+                            markDirty(summary, {
+                                kind: "lane",
+                                id: lane.lane_id,
+                                why: `queued message recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+                            });
+                        }
+                    }
                 }
             }
             catch (err) {

package/dist/lib/lanes/store.js

@@ -708,7 +708,15 @@ export function parseQuestionRecord(raw, filePath) {
             value: delivered_at,
         });
     }
-    return { ...raw, delivered_at };
+    const mesh_question_id = raw.mesh_question_id;
+    if (mesh_question_id !== undefined && (typeof mesh_question_id !== "string" || !mesh_question_id.trim())) {
+        throw new LaneSchemaError("mesh_question_id must be a non-empty string when present", { path: filePath, value: mesh_question_id });
+    }
+    const mesh_delivered_at = raw.mesh_delivered_at === undefined ? null : raw.mesh_delivered_at;
+    if (mesh_delivered_at !== null && (typeof mesh_delivered_at !== "string" || !Number.isFinite(Date.parse(mesh_delivered_at)))) {
+        throw new LaneSchemaError("mesh_delivered_at must be a valid timestamp or null", { path: filePath, value: mesh_delivered_at });
+    }
+    return { ...raw, delivered_at, mesh_delivered_at };
 }
 /**
  * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:

package/dist/lib/lanes/tracker-mesh-questions.d.ts

@@ -0,0 +1,54 @@
+import type { LaneCompanyRef, QuestionRecord } from "./types.js";
+import { type TrackerMeshRequest } from "./tracker-mesh.js";
+export type TrackerMeshQuestionAudience = "owner" | "operator" | "lane";
+export type TrackerMeshQuestionStatus = "pending" | "answered" | "cancelled";
+export interface TrackerMeshQuestionRow {
+    questionId: string;
+    threadId: string;
+    companyUid: string;
+    projectId: string;
+    laneId: string;
+    host: {
+        kind: string;
+        id: string;
+    };
+    audience: TrackerMeshQuestionAudience;
+    audienceChain: string[];
+    routingHistory: Array<Record<string, string>>;
+    question: string;
+    context?: string;
+    options: string[];
+    recommended?: string;
+    askedAt: string;
+    status: TrackerMeshQuestionStatus;
+    choice?: string;
+    notes?: string;
+    answeredBy?: string;
+    answeredAt?: string;
+    deliveredAt?: string;
+}
+export interface TrackerMeshQuestionInput {
+    laneId: string;
+    threadId?: string;
+    projectId: string;
+    audience: TrackerMeshQuestionAudience;
+    audienceChain: string[];
+    routingHistory: Array<Record<string, string>>;
+    question: string;
+    context: string;
+    options: string[];
+    recommended?: string;
+}
+export interface TrackerMeshQuestionClient {
+    create(input: TrackerMeshQuestionInput): Promise<TrackerMeshQuestionRow>;
+    list(statuses?: readonly TrackerMeshQuestionStatus[]): Promise<TrackerMeshQuestionRow[]>;
+    answer(questionId: string, choice: string, notes?: string): Promise<TrackerMeshQuestionRow>;
+    delivered(questionId: string): Promise<TrackerMeshQuestionRow>;
+}
+/** Persist a local delivery checkpoint only after the Work Mesh stamp succeeds. */
+export declare function deliverTrackerMeshQuestionOnce(question: QuestionRecord, company: LaneCompanyRef, client: Pick<TrackerMeshQuestionClient, "delivered">, persist: (deliveredAt: string) => QuestionRecord): Promise<QuestionRecord>;
+export declare function createTrackerMeshQuestionClient(options: {
+    company: LaneCompanyRef;
+    request?: TrackerMeshRequest;
+}): TrackerMeshQuestionClient;
+//# sourceMappingURL=tracker-mesh-questions.d.ts.map