@indigoai-us/hq-cli 5.217.0 → 5.219.0

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;
 }

package/dist/lib/lanes/watcher-main.js

@@ -6,6 +6,20 @@
  * Requires HQ_ROOT in the environment.
  */
 import { runWatcherLoop } from "./watcher.js";
+import { LanesError } from "./errors.js";
+import { openMeshTransport } from "../mesh/client.js";
+import { CompanySelectionError } from "../../utils/company-selection-error.js";
+async function resolveQuestionActiveCompany() {
+    try {
+        const { company } = await openMeshTransport({});
+        return { slug: company.companySlug, uid: company.companyUid };
+    }
+    catch (err) {
+        if (!(err instanceof CompanySelectionError))
+            throw err;
+        throw new LanesError("question_company_unavailable", "Cannot raise a lane question because the active HQ company could not be resolved", {});
+    }
+}
 function main() {
     const laneId = process.argv[2]?.trim();
     const hqRoot = process.env.HQ_ROOT?.trim();
@@ -13,7 +27,9 @@ function main() {
         process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
         process.exit(1);
     }
-    void runWatcherLoop(hqRoot, laneId).catch((err) => {
+    void runWatcherLoop(hqRoot, laneId, {
+        resolveQuestionActiveCompany,
+    }).catch((err) => {
         process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
         process.exit(1);
     });

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

@@ -31,7 +31,7 @@
  * Queue admission of the next lane when a slot frees is owned by the
  * periodic reconcile pass and is out of scope here.
  */
-import { ENVELOPE_INVALID_REASON, type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
+import { ENVELOPE_INVALID_REASON, type LaneEnvelope, type LaneCompanyRef, type LaneRecord, type LaneState } from "./types.js";
 import { type QuotaSignal } from "./quota.js";
 import { type ProviderRejection } from "./provider-rejection.js";
 import type { AdmissionHost } from "./admission.js";
@@ -145,6 +145,7 @@ export interface ApplyTerminalOpts {
     envelopeRef?: string;
     envelopeValidationErrors?: string[];
     questionIndexes?: readonly number[];
+    activeCompany?: LaneCompanyRef | null;
     at?: string;
     quota?: QuotaSignal | null;
     /** Written to `terminal_details` with the model and account the run used. */
@@ -219,6 +220,8 @@ export interface WatcherLoopDeps {
     resolveAdmissionHost?: () => AdmissionHost;
     /** Spawn seams for account retry; host scope is supplied by the resolver above. */
     retrySpawnDeps?: Omit<SpawnLaneDeps, "admissionHost">;
+    /** Active-company fallback when an unscoped lane asks from its envelope. */
+    resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
 }
 /**
  * Wrap one mesh call. A failed emit is logged as `mesh_event_failed` with

package/dist/lib/lanes/watcher.js

@@ -34,7 +34,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
-import { raiseEnvelopeQuestions } from "./questions.js";
+import { questionRecordRefusalCode, raiseEnvelopeQuestions } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, } from "./types.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { readLane, retryUpdateLane } from "./store.js";
@@ -309,12 +309,27 @@ export function applyTerminalToLane(hqRoot, laneId, classification, opts = {}) {
 export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, opts = {}) {
     const at = opts.at ?? new Date().toISOString();
     const existing = readLane(hqRoot, laneId);
+    let questionRefusalCode = null;
     if (!isTerminalLaneState(existing.state) &&
         classification.state === "awaiting_input" &&
         opts.envelope &&
         (opts.envelope.questions?.length ?? 0) > 0) {
-        raiseEnvelopeQuestions(hqRoot, existing, opts.envelope, opts.envelopeRef ?? "envelopes/unknown.json", at, opts.questionIndexes);
+        try {
+            raiseEnvelopeQuestions(hqRoot, existing, opts.envelope, opts.envelopeRef ?? "envelopes/unknown.json", at, opts.questionIndexes, opts.activeCompany);
+        }
+        catch (err) {
+            questionRefusalCode = questionRecordRefusalCode(err);
+            if (questionRefusalCode === null)
+                throw err;
+            process.stderr.write(`hq lanes watcher: terminal ask refused for ${laneId}: ${questionRefusalCode}\n`);
+        }
     }
+    const terminalClassification = questionRefusalCode === null
+        ? classification
+        : {
+            state: "failed",
+            reason: `question_record_refused:${questionRefusalCode}`,
+        };
     let changed = false;
     const updated = retryUpdateLane(hqRoot, laneId, "watcher", (current) => {
         const terminal = current.state === "done" ||
@@ -331,7 +346,7 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
         const next = {
             ...current,
             ...runResultFields(hqRoot, current),
-            state: classification.state,
+            state: terminalClassification.state,
             queued_reason: undefined,
             stalled: undefined,
             stalled_at: undefined,
@@ -340,9 +355,9 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
             envelope_validation_errors: opts.envelopeValidationErrors,
         };
         changed = true;
-        if (classification.reason) {
+        if (terminalClassification.reason) {
             next.terminal_reason =
-                classification.reason;
+                terminalClassification.reason;
         }
         if (opts.quota?.quota_reset_at) {
             next.quota_reset_at = opts.quota.quota_reset_at;
@@ -1054,11 +1069,19 @@ export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
                             return;
                     }
                 }
+                const terminalLane = readLane(hqRoot, laneId);
+                const activeQuestionCompany = envelope?.decision === "ask" &&
+                    (envelope.questions?.length ?? 0) > 0 &&
+                    terminalLane.company === null &&
+                    terminalLane.mesh_company === undefined
+                    ? await deps.resolveQuestionActiveCompany?.()
+                    : undefined;
                 const terminalWrite = applyTerminalToLaneWithResult(hqRoot, laneId, classification, {
                     envelope,
                     envelopeRef: latest?.ref,
                     envelopeValidationErrors,
                     questionIndexes,
+                    activeCompany: activeQuestionCompany,
                     at: tick.emit.at,
                     quota,
                     providerRejection,
@@ -1074,7 +1097,7 @@ export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
                 // lane_blocked; ask → lane_ask with the queue ids. After the state
                 // write, so a mesh failure can never leave the lane unclassified.
                 if (mesh && terminalWrite.changed) {
-                    if (envelope && latest) {
+                    if (envelope && latest && updated.state === classification.state) {
                         const questionIds = envelope.decision === "ask"
                             ? envelopeQuestionIds(laneId, latest.ref, envelope, questionIndexes)
                             : undefined;
@@ -1086,7 +1109,7 @@ export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
                     }
                     else if (updated.state === "failed" || updated.state === "interrupted" ||
                         updated.state === "cancelled" || updated.state === "killed") {
-                        await emitMeshSoft(`lane_${updated.state}`, logDecision, tick.emit.at, (signal) => emitLaneTerminalStateEvent(mesh, updated, updated.state, classification.reason, signal), meshRequestTimeoutMs);
+                        await emitMeshSoft(`lane_${updated.state}`, logDecision, tick.emit.at, (signal) => emitLaneTerminalStateEvent(mesh, updated, updated.state, updated.terminal_reason ?? classification.reason, signal), meshRequestTimeoutMs);
                     }
                 }
             }

package/package.json

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