@indigoai-us/hq-cli 5.218.0 → 5.219.0

package/dist/lib/lanes/questions.js

@@ -7,8 +7,28 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
+import { assertNoSecretText } from "./text-scan.js";
 import { appendCappedHistory, createQuestion, retryUpdateQuestion, } from "./store.js";
 import { QUESTION_BODY_STORES, } from "./types.js";
+export function assertQuestionBodySecretSafe(body) {
+    assertNoSecretText("question", body.question);
+    assertNoSecretText("context", body.context);
+    body.options.forEach((option, index) => assertNoSecretText(`option[${index}]`, option));
+    if (body.recommended !== undefined) {
+        assertNoSecretText("recommended", body.recommended);
+    }
+    if (body.notes !== undefined)
+        assertNoSecretText("answer notes", body.notes);
+}
+/** Errors that make an envelope ask unsafe or impossible to persist. */
+export function questionRecordRefusalCode(err) {
+    if (!(err instanceof LanesError))
+        return null;
+    if (err.error === "secret_text_refused" || err.error === "question_company_unavailable") {
+        return err.error;
+    }
+    return null;
+}
 export function parseQuestionBodyStore(value) {
     if (typeof value === "string" &&
         QUESTION_BODY_STORES.includes(value)) {
@@ -16,8 +36,15 @@ export function parseQuestionBodyStore(value) {
     }
     throw new LanesError("unknown_body_store", `Unknown question body store ${JSON.stringify(value)}. Accepted: ${QUESTION_BODY_STORES.join(", ")}`, { accepted: [...QUESTION_BODY_STORES], value });
 }
-export function bodyStoreForLane(lane) {
-    return lane.company ? "company" : "personal";
+export function bodyStoreForLane(lane, resolvedCompany) {
+    return lane.company || lane.mesh_company || resolvedCompany ? "company" : "personal";
+}
+export function resolveQuestionCompany(lane, activeCompany) {
+    const company = lane.company ?? lane.mesh_company ?? activeCompany;
+    if (!company || !company.slug.trim() || !company.uid.trim()) {
+        throw new LanesError("question_company_unavailable", `Cannot raise a question for lane ${lane.lane_id}: no lane, project, or active company could be resolved`, { lane_id: lane.lane_id });
+    }
+    return company;
 }
 export function questionBodyRef(questionId) {
     return path.posix.join("lanes", "questions", `${questionId}.json`);
@@ -37,6 +64,7 @@ export function questionBodyAbsPath(hqRoot, question) {
     return path.join(hqRoot, "personal", "lanes", "questions", `${question.question_id}.json`);
 }
 export function writeQuestionBody(hqRoot, question, body) {
+    assertQuestionBodySecretSafe(body);
     const store = parseQuestionBodyStore(question.body.store);
     const filePath = questionBodyAbsPath(hqRoot, question);
     const serialized = `${JSON.stringify(body, null, 2)}\n`;
@@ -53,12 +81,14 @@ export function writeQuestionBody(hqRoot, question, body) {
  * tenant body, then CAS routing_history with reason `asked`.
  */
 export function raiseLaneQuestion(input) {
-    const store = bodyStoreForLane(input.lane);
+    assertQuestionBodySecretSafe(input.body);
+    const company = resolveQuestionCompany(input.lane, input.activeCompany);
+    const store = bodyStoreForLane(input.lane, company);
     let questionId = input.questionId;
     if (!questionId) {
         const created = createQuestion(input.hqRoot, {
             lane_id: input.lane.lane_id,
-            company: input.lane.company,
+            company,
             project_id: input.lane.project_id,
             story_id: input.lane.story_id,
             thread_id: input.lane.thread_id,
@@ -77,7 +107,7 @@ export function raiseLaneQuestion(input) {
             createQuestion(input.hqRoot, {
                 question_id: questionId,
                 lane_id: input.lane.lane_id,
-                company: input.lane.company,
+                company,
                 project_id: input.lane.project_id,
                 story_id: input.lane.story_id,
                 thread_id: input.lane.thread_id,
@@ -97,7 +127,7 @@ export function raiseLaneQuestion(input) {
         }
     }
     const stored = writeQuestionBody(input.hqRoot, {
-        company: input.lane.company,
+        company,
         question_id: questionId,
         body: { store, ref: "", digest: "" },
     }, input.body);
@@ -149,34 +179,40 @@ export function questionBodyPathForLane(hqRoot, lane, questionId) {
  * Free-text notes the operator attached with `questions answer --notes`.
  * Read from the lane's own store (spec §6.5): the company store for a company
  * lane, the personal store otherwise. Returns undefined when the answer has
- * no notes_ref or the body carries no notes; a body the host cannot read is
- * reported and skipped rather than failing the resume.
+ * no notes_ref or the body carries no notes. An unavailable or malformed body
+ * fails the resume so the lane cannot continue without its answer notes.
  */
 export function readAnswerNotes(hqRoot, lane, question) {
     if (!question.answer?.notes_ref)
         return undefined;
-    const filePath = questionBodyPathForLane(hqRoot, lane, question.question_id);
+    const bodyStore = parseQuestionBodyStore(question.body.store);
+    const company = question.company ?? (bodyStore === "company" ? lane.company ?? lane.mesh_company ?? null : null);
+    if (bodyStore === "personal" && company !== question.company) {
+        throw new LanesError("question_answer_notes_store_mismatch", `Answer notes for question ${question.question_id} cannot use lane company attribution for a personal-store body`, { question_id: question.question_id });
+    }
+    const filePath = questionBodyAbsPath(hqRoot, { ...question, company });
     let text;
     try {
         text = fs.readFileSync(filePath, "utf8");
     }
     catch (err) {
-        const code = err.code;
-        process.stderr.write(`hq lanes: answer notes for ${question.question_id} unreadable at ${filePath} (${code ?? (err instanceof Error ? err.message : String(err))})\n`);
-        return undefined;
+        throw new LanesError("question_answer_notes_unavailable", `Answer notes for question ${question.question_id} are unavailable on the owning host`, { question_id: question.question_id, code: err.code });
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch (err) {
-        process.stderr.write(`hq lanes: answer notes for ${question.question_id} at ${filePath} is not JSON: ${err instanceof Error ? err.message : String(err)}\n`);
-        return undefined;
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} are not valid JSON`, { question_id: question.question_id });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} have an invalid body`, { question_id: question.question_id });
     }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        return undefined;
     const notes = parsed.notes;
-    return typeof notes === "string" && notes.length > 0 ? notes : undefined;
+    if (typeof notes !== "string") {
+        throw new LanesError("question_answer_notes_invalid", `Answer notes for question ${question.question_id} are missing from the body`, { question_id: question.question_id });
+    }
+    return notes.length > 0 ? notes : undefined;
 }
 /**
  * The `answered-questions.json` a resumed worker is handed (spec §6.5). Ids,
@@ -200,6 +236,22 @@ export function answeredQuestionEntries(hqRoot, lane, questions) {
         return entry;
     });
 }
+export function markAnsweredQuestionsDelivered(hqRoot, laneId, questionIds, deliveredAt) {
+    if (!Number.isFinite(Date.parse(deliveredAt))) {
+        throw new LanesError("question_delivery_timestamp_invalid", "Cannot mark an answer delivered with an invalid timestamp", { lane_id: laneId });
+    }
+    return [...new Set(questionIds)].map((questionId) => retryUpdateQuestion(hqRoot, questionId, (current) => {
+        if (current.lane_id !== laneId || current.origin.id !== laneId) {
+            throw new LanesError("question_lane_mismatch", `Question ${questionId} does not belong to the resumed lane ${laneId}`, { lane_id: laneId, question_id: questionId });
+        }
+        if (current.status !== "answered" || !current.answer) {
+            throw new LanesError("question_not_answered", `Question ${questionId} is not answered and cannot be marked delivered`, { lane_id: laneId, question_id: questionId });
+        }
+        if (current.delivered_at)
+            return current;
+        return { ...current, delivered_at: deliveredAt };
+    }));
+}
 export function envelopeQuestionId(laneId, envelopeRef, index) {
     const stem = path.basename(envelopeRef, ".json").replace(/[^A-Za-z0-9_-]/g, "");
     const digest = createHash("sha256")
@@ -222,8 +274,15 @@ function envelopeQuestionBody(item) {
  * Spec §6.1: each envelope questions[] entry becomes one queue record, via
  * raiseLaneQuestion (the same function the CLI ask path uses).
  */
-export function raiseEnvelopeQuestions(hqRoot, lane, envelope, envelopeRef, at, questionIndexes) {
+export function raiseEnvelopeQuestions(hqRoot, lane, envelope, envelopeRef, at, questionIndexes, activeCompany) {
     const items = envelope.questions ?? [];
+    const presentItems = items.filter((item) => item !== undefined);
+    if (presentItems.length === 0)
+        return [];
+    for (const item of presentItems) {
+        assertQuestionBodySecretSafe(envelopeQuestionBody(item));
+    }
+    resolveQuestionCompany(lane, activeCompany);
     const raised = [];
     for (let i = 0; i < items.length; i += 1) {
         const item = items[i];
@@ -236,6 +295,7 @@ export function raiseEnvelopeQuestions(hqRoot, lane, envelope, envelopeRef, at,
             raisedVia: "envelope",
             at,
             questionId: envelopeQuestionId(lane.lane_id, envelopeRef, questionIndexes?.[i] ?? i),
+            activeCompany,
         }));
     }
     return raised;

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

@@ -10,7 +10,7 @@ import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
 import { type ThrottleDeps } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
 import { type KeepAliveBlockedReason } from "./keep-alive.js";
-import type { LaneRecord, LivenessState, QueuedReason, QuestionRecord, SeniorRef } from "./types.js";
+import type { LaneCompanyRef, LaneRecord, LivenessState, QueuedReason, QuestionRecord, SeniorRef } from "./types.js";
 import { type LaneMesh } from "./mesh-events.js";
 /** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
 export declare const QUESTION_AGE_MS: number;
@@ -79,6 +79,8 @@ export interface ReconcileDeps {
     env?: NodeJS.ProcessEnv;
     /** Flag reader seam used to assert rollout reads happen before admission locks. */
     readRegistryFlag?: typeof readLanesRegistryFlag;
+    /** Active-company fallback for questions raised from an unscoped lane. */
+    resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
     /** 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

@@ -24,7 +24,7 @@ import { readLanesRegistryFlag } from "./registry-flag.js";
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
-import { answeredQuestionEntries, raiseEnvelopeQuestions } from "./questions.js";
+import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, } from "./questions.js";
 import { SILENCE_MS, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
@@ -1010,9 +1010,10 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     if (!repairCandidate.missing)
                         invalidEnvelope = { errors: repair.errors };
                 }
-                const repairedClassification = invalidEnvelope
+                let repairedClassification = invalidEnvelope
                     ? classifyLaneExit({ envelope: null, hasPartialOutput: false, invalidEnvelope })
                     : classification;
+                let questionRefusalCode = null;
                 const accountRetryReason = quota
                     ? "usage_limit"
                     : providerRejection && classification.reason === "account_not_logged_in"
@@ -1052,7 +1053,23 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     classification.state === "awaiting_input" &&
                     latest &&
                     (latest.envelope.questions?.length ?? 0) > 0) {
-                    raiseEnvelopeQuestions(hqRoot, readLane(hqRoot, lane.lane_id), latest.envelope, latest.ref, nowIso);
+                    const questionLane = readLane(hqRoot, lane.lane_id);
+                    const activeCompany = questionLane.company || questionLane.mesh_company
+                        ? undefined
+                        : await deps.resolveQuestionActiveCompany?.();
+                    try {
+                        raiseEnvelopeQuestions(hqRoot, questionLane, latest.envelope, latest.ref, nowIso, undefined, activeCompany);
+                    }
+                    catch (err) {
+                        questionRefusalCode = questionRecordRefusalCode(err);
+                        if (questionRefusalCode === null)
+                            throw err;
+                        repairedClassification = {
+                            state: "failed",
+                            reason: `question_record_refused:${questionRefusalCode}`,
+                        };
+                        process.stderr.write(`hq lanes reconcile: terminal ask refused for ${lane.lane_id}: ${questionRefusalCode}\n`);
+                    }
                 }
                 const result = casLaneIf(hqRoot, lane.lane_id, (current) => current.state === "running", (current) => {
                     const next = {
@@ -1100,7 +1117,7 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                         to: repairedClassification.state,
                         reason: repairedClassification.reason ?? "host_lost",
                     });
-                    if (latest?.envelope) {
+                    if (latest?.envelope && questionRefusalCode === null) {
                         const mesh = deps.mesh === undefined ? createLaneMesh({ interactive: false }) : deps.mesh;
                         if (mesh) {
                             const meshEmitTimeoutMs = deps.meshEmitTimeoutMs ?? 10_000;
@@ -2030,10 +2047,12 @@ async function resumeAwaiting(hqRoot, lanes, questions, summary, deps, onlyLaneI
         }
         catch (err) {
             terminalizeModelUnsupported(hqRoot, lane, err);
+            const errorName = err instanceof LanesError ? `${err.error}: ` : "";
+            const errorMessage = err instanceof Error ? err.message : String(err);
             markDirty(summary, {
                 kind: "lane",
                 id: lane.lane_id,
-                why: `resume failed: ${err instanceof Error ? err.message : String(err)}`,
+                why: `resume failed: ${errorName}${errorMessage}`,
             });
         }
     }

package/dist/lib/lanes/spawn.js

@@ -27,6 +27,7 @@ import { appendCappedHistory, listLaneIds, readLane, retryUpdateLane } from "./s
 import { copySessionFiles, planSessionCopy } from "./move-account.js";
 import { ensureSessionHome } from "./session-relink.js";
 import { MESSAGE_REPLAY_STATE_NAME } from "./message-replay.js";
+import { markAnsweredQuestionsDelivered } from "./questions.js";
 import { hasEarlierEligibleQueuedLane, laneAdmissionCapReason, withLaneAdmissionLock, } from "./admission.js";
 import { resolveAdmissionHost } from "./admission-host.js";
 import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, parseLaneProvider, } from "./types.js";
@@ -979,22 +980,30 @@ export function readAnsweredQuestionLines(answersPath) {
         parsed = JSON.parse(text);
     }
     catch (err) {
-        process.stderr.write(`hq lanes: ${answersPath} is not JSON: ${err instanceof Error ? err.message : String(err)}\n`);
-        return [];
+        throw new LanesError("answered_questions_invalid", `Answered questions at ${answersPath} are not valid JSON`, { path: answersPath });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new LanesError("answered_questions_invalid", `Answered questions at ${answersPath} must be a JSON array`, { path: answersPath });
     }
-    if (!Array.isArray(parsed))
-        return [];
     const out = [];
-    for (const item of parsed) {
-        if (!item || typeof item !== "object")
-            continue;
+    for (const [index, item] of parsed.entries()) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new LanesError("answered_questions_invalid", `Answered question ${index} at ${answersPath} must be an object`, { path: answersPath, index });
+        }
         const rec = item;
-        if (typeof rec.question_id !== "string")
-            continue;
+        if (typeof rec.question_id !== "string" || !rec.question_id.trim()) {
+            throw new LanesError("answered_questions_invalid", `Answered question ${index} at ${answersPath} must have a question_id`, { path: answersPath, index });
+        }
+        if (typeof rec.choice !== "string") {
+            throw new LanesError("answered_questions_invalid", `Answered question ${rec.question_id} at ${answersPath} must have a choice`, { path: answersPath, question_id: rec.question_id });
+        }
         const line = {
             question_id: rec.question_id,
-            choice: typeof rec.choice === "string" ? rec.choice : JSON.stringify(rec.choice ?? null),
+            choice: rec.choice,
         };
+        if (rec.notes !== undefined && typeof rec.notes !== "string") {
+            throw new LanesError("answered_questions_invalid", `Answered question ${rec.question_id} at ${answersPath} has invalid notes`, { path: answersPath, question_id: rec.question_id });
+        }
         if (typeof rec.notes === "string" && rec.notes.length > 0)
             line.notes = rec.notes;
         out.push(line);
@@ -1744,6 +1753,10 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const envelopePath = nextEnvelopePath(runDir);
     const lastMessagePath = path.join(logsDir, "last-message.txt");
     const answersPath = path.join(runDir, ANSWERED_QUESTIONS_FILE);
+    const carriesAnsweredQuestions = trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions";
+    const answeredLines = carriesAnsweredQuestions && existsSync(answersPath)
+        ? readAnsweredQuestionLines(answersPath)
+        : undefined;
     const extraPrompt = existsSync(answersPath)
         ? `Previously answered questions are at ${answersPath}; treat those choices as operator decisions that outrank the brief.`
         : undefined;
@@ -1795,12 +1808,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                         ? pendingResume.text
                         : undefined,
                 resumedFrom: trigger.kind === "resume" ? trigger.from : pendingResume?.resumed_from,
-                answersPath: (trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions") && existsSync(answersPath)
-                    ? answersPath
-                    : undefined,
-                answers: (trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions") && existsSync(answersPath)
-                    ? readAnsweredQuestionLines(answersPath)
-                    : undefined,
+                answersPath: answeredLines !== undefined ? answersPath : undefined,
+                answers: answeredLines,
                 envelopeRepairErrors: lane.terminal_reason === ENVELOPE_INVALID_REASON &&
                     lane.envelope_repair?.attempted === true &&
                     lane.envelope_repair.succeeded === false
@@ -2053,6 +2062,9 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             starttime: readProcStarttime(workerPid) ?? undefined,
         });
         requireDetached(proveDetached, workerPid, "worker");
+        if (answeredLines && answeredLines.length > 0) {
+            markAnsweredQuestionsDelivered(hqRoot, lane.lane_id, answeredLines.map(({ question_id }) => question_id), (deps.now ?? (() => new Date()))().toISOString());
+        }
         watcherPid = armLaneWatcher(hqRoot, lane.lane_id, deps);
         writeSpawnManifest(runDir, {
             command: command.command,

package/dist/lib/lanes/store.js

@@ -700,7 +700,15 @@ export function parseQuestionRecord(raw, filePath) {
             path: filePath,
         });
     }
-    return raw;
+    const delivered_at = raw.delivered_at === undefined ? null : raw.delivered_at;
+    if (delivered_at !== null &&
+        (typeof delivered_at !== "string" || !Number.isFinite(Date.parse(delivered_at)))) {
+        throw new LaneSchemaError("delivered_at must be a valid timestamp or null", {
+            path: filePath,
+            value: delivered_at,
+        });
+    }
+    return { ...raw, delivered_at };
 }
 /**
  * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:
@@ -845,8 +853,13 @@ export function mergeQuestionRecords(live, sidecars) {
         return live;
     const all = [live, ...sidecars];
     const base = higherVersionRecord(live, sidecars);
+    const deliveredAt = all
+        .map((record) => record.delivered_at)
+        .filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)))
+        .sort((a, b) => Date.parse(a) - Date.parse(b))[0] ?? null;
     return {
         ...base,
+        delivered_at: deliveredAt,
         answer_history: unionHistory(all.map(questionAnswerHistory), entryIdentity, questionAnswerHistory(base)),
         routing_history: unionHistory(all.map((record) => record.routing_history), entryIdentity, base.routing_history),
     };
@@ -1205,6 +1218,7 @@ export function createQuestion(hqRoot, init, deps = defaultStoreDeps()) {
         ...init,
         schema_version: init.schema_version ?? QUESTION_SCHEMA_VERSION,
         question_id,
+        delivered_at: init.delivered_at ?? null,
         version: 1,
         routing_history: init.routing_history ?? [],
     };

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

@@ -0,0 +1,77 @@
+import type { TrackerChecksConfig } from "./types.js";
+export interface TrackerCheckQuestion {
+    id: string;
+    status: string;
+    asked_at: string;
+    routing_history: Array<{
+        at: string;
+        audience_kind: string;
+    }>;
+    surfaced_at: string | null;
+}
+export interface TrackerCheckTeam {
+    team: string;
+    project_id: string;
+    lead_lane?: {
+        id: string;
+        state: string;
+    };
+    open_story_ids: string[];
+    open_pr_refs: string[];
+    running_worker_ids: string[];
+    status_path: string;
+    status_updated_at: string | null;
+    task_list_path: string;
+    task_list_updated_at: string | null;
+}
+export interface TrackerCheckBlocker {
+    id: string;
+    opened_at: string;
+    resolved_at: string | null;
+    next_step: string | null;
+}
+export interface TrackerCheckKpi {
+    id: string;
+    created_at: string;
+    defined_at?: string;
+    values: Array<{
+        at: string;
+    }>;
+}
+export interface TrackerCheckDirective {
+    id: string;
+    created_at: string;
+    teams: string[];
+    acknowledgements: Array<{
+        team: string;
+        lane_id: string;
+        at: string;
+    }>;
+}
+export interface TrackerCheckDirectiveTeam {
+    team: string;
+    lead_lane_id?: string;
+}
+export interface TrackerChecksInput {
+    now: Date;
+    thresholds: TrackerChecksConfig;
+    questions: TrackerCheckQuestion[];
+    teams: TrackerCheckTeam[];
+    blockers: TrackerCheckBlocker[];
+    kpis: TrackerCheckKpi[];
+    directives: TrackerCheckDirective[];
+    /** Company-wide mapping retained when the caller filters checks to one project. */
+    directive_teams?: TrackerCheckDirectiveTeam[];
+}
+export interface TrackerCheckFinding {
+    id: string;
+    reason: string;
+    [key: string]: unknown;
+}
+export interface TrackerCheckResult {
+    id: "questions" | "lead_lanes" | "freshness" | "blockers" | "kpis" | "directives";
+    result: "ok" | "failing";
+    items: TrackerCheckFinding[];
+}
+export declare function evaluateTrackerChecks(input: TrackerChecksInput): TrackerCheckResult[];
+//# sourceMappingURL=tracker-checks.d.ts.map

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

@@ -0,0 +1,134 @@
+function timestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new TypeError(`Invalid tracker check timestamp for ${field}`);
+    return parsed;
+}
+function check(id, items) {
+    return { id, result: items.length === 0 ? "ok" : "failing", items };
+}
+export function evaluateTrackerChecks(input) {
+    const now = input.now.getTime();
+    const questions = new Map();
+    for (const question of input.questions) {
+        if (question.status !== "pending")
+            continue;
+        const askedAt = timestamp(question.asked_at, `question ${question.id}.asked_at`);
+        if (now - askedAt > input.thresholds.open_question_age_ms) {
+            questions.set(question.id, {
+                id: question.id,
+                reason: "open_question_overdue",
+                age_ms: now - askedAt,
+            });
+        }
+        const latestRoute = question.routing_history
+            .map((route) => ({ ...route, at_ms: timestamp(route.at, `question ${question.id}.routing_history.at`) }))
+            .sort((a, b) => a.at_ms - b.at_ms)
+            .at(-1);
+        if (!latestRoute || latestRoute.audience_kind !== "user")
+            continue;
+        const surfacedAt = question.surfaced_at === null
+            ? null
+            : timestamp(question.surfaced_at, `question ${question.id}.surfaced_at`);
+        if (now - latestRoute.at_ms >= input.thresholds.owner_question_surface_ms &&
+            (surfacedAt === null || surfacedAt < latestRoute.at_ms)) {
+            const finding = questions.get(question.id);
+            questions.set(question.id, {
+                ...(finding ?? { id: question.id }),
+                reason: finding ? `${finding.reason},owner_not_surfaced` : "owner_not_surfaced",
+                routed_to_owner_at: new Date(latestRoute.at_ms).toISOString(),
+            });
+        }
+    }
+    const leadLanes = input.teams.flatMap((team) => {
+        const lead = team.lead_lane;
+        if (!lead || (lead.state !== "done" && lead.state !== "failed"))
+            return [];
+        const hasOpenWork = team.open_story_ids.length > 0 ||
+            team.open_pr_refs.length > 0 || team.running_worker_ids.length > 0;
+        if (!hasOpenWork)
+            return [];
+        return [{
+                id: team.team,
+                reason: "terminal_lead_with_open_work",
+                lead_lane_id: lead.id,
+                lead_state: lead.state,
+                open_story_ids: team.open_story_ids,
+                open_pr_refs: team.open_pr_refs,
+                running_worker_ids: team.running_worker_ids,
+            }];
+    });
+    const freshness = [];
+    for (const team of input.teams) {
+        if (team.status_updated_at === null) {
+            freshness.push({ id: team.team, reason: "status_missing", path: team.status_path });
+        }
+        else {
+            const age = now - timestamp(team.status_updated_at, `${team.team}.status.updated_at`);
+            if (age >= input.thresholds.status_stale_ms) {
+                freshness.push({ id: team.team, reason: "status_stale", path: team.status_path, age_ms: age });
+            }
+        }
+        if (team.task_list_updated_at === null) {
+            freshness.push({ id: team.team, reason: "task_list_missing", path: team.task_list_path });
+        }
+        else {
+            const age = now - timestamp(team.task_list_updated_at, `${team.team}.task_list.mtime`);
+            if (age >= input.thresholds.task_list_stale_ms) {
+                freshness.push({ id: team.team, reason: "task_list_stale", path: team.task_list_path, age_ms: age });
+            }
+        }
+    }
+    const blockers = input.blockers.flatMap((blocker) => {
+        if (blocker.resolved_at !== null)
+            return [];
+        const reasons = [];
+        const age = now - timestamp(blocker.opened_at, `blocker ${blocker.id}.opened_at`);
+        if (typeof blocker.next_step !== "string" || blocker.next_step.trim() === "")
+            reasons.push("missing_next_step");
+        if (age > input.thresholds.blocker_max_age_ms)
+            reasons.push("open_overdue");
+        return reasons.length === 0 ? [] : [{ id: blocker.id, reason: reasons.join(","), age_ms: age }];
+    });
+    const kpis = input.kpis.flatMap((kpi) => {
+        const latestValue = kpi.values
+            .map((value) => timestamp(value.at, `KPI ${kpi.id}.values.at`))
+            .reduce((latest, at) => latest === null || at > latest ? at : latest, null);
+        const baseline = latestValue ?? timestamp(kpi.created_at, `KPI ${kpi.id}.created_at`);
+        const age = now - baseline;
+        return age >= input.thresholds.kpi_value_max_age_ms
+            ? [{ id: kpi.id, reason: latestValue === null ? "no_value_overdue" : "value_stale", age_ms: age }]
+            : [];
+    });
+    const directiveTeams = input.directive_teams ?? input.teams.map((team) => ({
+        team: team.team,
+        ...(team.lead_lane ? { lead_lane_id: team.lead_lane.id } : {}),
+    }));
+    const teamByName = new Map(directiveTeams.map((team) => [team.team, team.lead_lane_id]));
+    const directives = input.directives.flatMap((directive) => {
+        const age = now - timestamp(directive.created_at, `directive ${directive.id}.created_at`);
+        if (age < input.thresholds.directive_ack_timeout_ms)
+            return [];
+        return directive.teams.flatMap((teamName) => {
+            const leadId = teamByName.get(teamName);
+            const acknowledged = leadId !== undefined && directive.acknowledgements.some((ack) => ack.team === teamName && ack.lane_id === leadId);
+            return acknowledged ? [] : [{
+                    id: `${directive.id}:${teamName}`,
+                    reason: leadId === undefined ? "target_team_lead_unavailable" : "lead_ack_missing",
+                    directive_id: directive.id,
+                    team: teamName,
+                    lead_lane_id: leadId ?? null,
+                    age_ms: age,
+                }];
+        });
+    });
+    return [
+        check("questions", [...questions.values()]),
+        check("lead_lanes", leadLanes),
+        check("freshness", freshness),
+        check("blockers", blockers),
+        check("kpis", kpis),
+        check("directives", directives),
+    ];
+}
+//# sourceMappingURL=tracker-checks.js.map

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

@@ -636,6 +636,8 @@ export interface QuestionRecord {
     hop: number;
     status: QuestionStatus;
     version: number;
+    /** Null until the owner starts a resume carrying this answer; absent on old records. */
+    delivered_at?: string | null;
     body: QuestionBodyRef;
     routing_history: RoutingHistoryEntry[];
     answer?: QuestionAnswer;
@@ -727,11 +729,24 @@ export interface LivenessWindows {
     /** No event at all for this window (and no `session_end`) → lost. Default 12 hours. */
     silent_lost_ms: number;
 }
+/** Age limits used by `hq lanes checks`; each value is a positive millisecond count. */
+export interface TrackerChecksConfig {
+    owner_question_surface_ms: number;
+    open_question_age_ms: number;
+    status_stale_ms: number;
+    task_list_stale_ms: number;
+    blocker_max_age_ms: number;
+    kpi_value_max_age_ms: number;
+    directive_ack_timeout_ms: number;
+}
 export interface LanesConfig {
     schema_version: typeof CONFIG_SCHEMA_VERSION | string;
     providers: Record<LaneProvider, ProviderConfig>;
     throttle: ThrottleConfig;
     liveness: LivenessWindows;
+    tracker: {
+        checks: TrackerChecksConfig;
+    };
     /** Seconds an unanswered question waits at a session audience before advancing. */
     session_question_timeout_secs: number;
 }