@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/lanes/throttle.js

@@ -0,0 +1,437 @@
+/**
+ * CPU busy-fraction and memory admission gate (spec §5).
+ *
+ * Algorithm is the workflow-runner sampler (two os.cpus() readings
+ * CPU_SAMPLE_MS apart, 1 - idleDelta/totalDelta, clamped 0..1). The sampler
+ * is reimplemented here because hq-cli cannot import core/scripts and the
+ * shared @indigoai-us/hq-cloud export listed in spec §13 does not exist yet.
+ *
+ * Overrides HQ_LANES_CPU_BUSY_OVERRIDE and HQ_LANES_CPU_CHECK are deliberately
+ * distinct from the runner's HQ_WORKFLOW_* pair — this module never reads those.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_MIN_AVAILABLE_MEM_MB, } from "./config.js";
+// Reconcile normally measures the interval between cumulative CPU snapshots.
+// A five-second window establishes a baseline or recovers from stale counters.
+export const CPU_SAMPLE_MS = 5_000;
+export const CPU_CUMULATIVE_MAX_AGE_MS = 5 * 60 * 1000;
+export const STARVATION_MAX_DEFERRALS = 10;
+export const STARVATION_MAX_MS = 30 * 60 * 1000;
+export const PROC_MEMINFO = "/proc/meminfo";
+export const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
+export const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function defaultThrottleDeps(env = process.env) {
+    return {
+        env,
+        now: () => Date.now(),
+        cpus: () => os.cpus() ?? [],
+        sleep: defaultSleep,
+        readFileSync: (file, encoding) => fs.readFileSync(file, encoding),
+        // os.freemem() reports MemFree on Linux (excludes page cache). Used only
+        // where MemAvailable is absent — see readAvailableMemMb.
+        freemem: () => os.freemem(),
+        existsSync: (file) => fs.existsSync(file),
+        mkdirSync: fs.mkdirSync.bind(fs),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+    };
+}
+export function cpuTimesSnapshot(cpus) {
+    let idle = 0;
+    let total = 0;
+    for (const cpu of cpus) {
+        const t = cpu.times;
+        idle += t.idle;
+        total += t.user + t.nice + t.sys + t.idle + t.irq;
+    }
+    return { idle, total };
+}
+export function busyFractionFromDeltas(before, after) {
+    const idleDelta = after.idle - before.idle;
+    const totalDelta = after.total - before.total;
+    if (!(totalDelta > 0))
+        return null;
+    return Math.max(0, Math.min(1, 1 - idleDelta / totalDelta));
+}
+export async function sampleCpuBusyFraction(deps = defaultThrottleDeps(), sampleMs = CPU_SAMPLE_MS) {
+    try {
+        const a = cpuTimesSnapshot(deps.cpus());
+        await deps.sleep(sampleMs);
+        const b = cpuTimesSnapshot(deps.cpus());
+        return busyFractionFromDeltas(a, b);
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: CPU sample failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export function isCpuCheckEnabled(env = process.env) {
+    return !/^(0|false|off|no)$/i.test(env[LANES_CPU_CHECK] || "");
+}
+export async function resolveCpuBusyFraction(deps = defaultThrottleDeps()) {
+    const raw = deps.env[LANES_CPU_BUSY_OVERRIDE];
+    if (raw !== undefined && raw !== "") {
+        const v = Number(raw);
+        if (Number.isFinite(v))
+            return Math.max(0, Math.min(1, v));
+        process.stderr.write(`lanes throttle: ${LANES_CPU_BUSY_OVERRIDE} is not a finite number (${JSON.stringify(raw)}); sampling instead\n`);
+    }
+    return sampleCpuBusyFraction(deps);
+}
+function snapshotFromDeps(deps) {
+    return {
+        ...cpuTimesSnapshot(deps.cpus()),
+        sampled_at: new Date(deps.now()).toISOString(),
+    };
+}
+/**
+ * Measure CPU busy against the previous reconcile snapshot when it is fresh.
+ * A short stable window is used only to establish a baseline or recover from
+ * stale/backwards counters (for example, after a reboot).
+ */
+export async function sampleCpuBusyObservation(deps, previous, options = {}) {
+    let start;
+    try {
+        start = snapshotFromDeps(deps);
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: CPU counters failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { busy: null, source: undefined, snapshot: previous };
+    }
+    if (options.measureBusy === false || !isCpuCheckEnabled(deps.env)) {
+        return { busy: null, source: undefined, snapshot: start };
+    }
+    const rawOverride = deps.env[LANES_CPU_BUSY_OVERRIDE];
+    if (rawOverride !== undefined && rawOverride !== "") {
+        const override = Number(rawOverride);
+        if (Number.isFinite(override)) {
+            return {
+                busy: Math.max(0, Math.min(1, override)),
+                source: "override",
+                snapshot: start,
+            };
+        }
+        process.stderr.write(`lanes throttle: ${LANES_CPU_BUSY_OVERRIDE} is not a finite number (${JSON.stringify(rawOverride)}); sampling instead\n`);
+    }
+    const nowMs = Date.parse(start.sampled_at);
+    const previousAtMs = previous ? Date.parse(previous.sampled_at) : Number.NaN;
+    if (previous !== undefined &&
+        Number.isFinite(previousAtMs) &&
+        nowMs >= previousAtMs &&
+        nowMs - previousAtMs <= CPU_CUMULATIVE_MAX_AGE_MS &&
+        start.idle >= previous.idle &&
+        start.total >= previous.total) {
+        return {
+            busy: busyFractionFromDeltas(previous, start),
+            source: "interval",
+            snapshot: start,
+        };
+    }
+    try {
+        await deps.sleep(CPU_SAMPLE_MS);
+        const end = snapshotFromDeps(deps);
+        return {
+            busy: busyFractionFromDeltas(start, end),
+            source: "window",
+            snapshot: end,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: CPU window sample failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { busy: null, source: "window", snapshot: start };
+    }
+}
+export function recordCpuBusyObservation(state, observation, options = {}) {
+    const observationAt = observation.snapshot === undefined
+        ? Number.NaN
+        : Date.parse(observation.snapshot.sampled_at);
+    const currentSnapshotAt = state.cpu_snapshot === undefined
+        ? Number.NaN
+        : Date.parse(state.cpu_snapshot.sampled_at);
+    const snapshotIsCurrent = options.advanceSnapshot !== false && observation.snapshot !== undefined && (!Number.isFinite(currentSnapshotAt) ||
+        observationAt > currentSnapshotAt ||
+        (observationAt === currentSnapshotAt && observation.snapshot.total >= (state.cpu_snapshot?.total ?? 0)));
+    const currentMetricAt = state.sampled_at === undefined ? Number.NaN : Date.parse(state.sampled_at);
+    const metricIsCurrent = observation.source !== undefined && Number.isFinite(observationAt) && (!Number.isFinite(currentMetricAt) || observationAt >= currentMetricAt);
+    return {
+        ...state,
+        ...(snapshotIsCurrent ? { cpu_snapshot: observation.snapshot } : {}),
+        ...(metricIsCurrent
+            ? {
+                last_busy: observation.busy,
+                busy_source: observation.source,
+                sampled_at: observation.snapshot.sampled_at,
+            }
+            : {}),
+    };
+}
+/** Parse MemAvailable kB from /proc/meminfo. */
+export function parseMemAvailableKb(contents) {
+    for (const line of contents.split("\n")) {
+        const match = /^MemAvailable:\s+(\d+)\s+kB\s*$/.exec(line.trimEnd());
+        if (match) {
+            const kb = Number(match[1]);
+            return Number.isFinite(kb) && kb >= 0 ? kb : null;
+        }
+    }
+    return null;
+}
+/**
+ * Available memory in MiB. Prefers kernel MemAvailable; falls back to
+ * os.freemem() only where MemAvailable is absent.
+ */
+export function readAvailableMemMb(deps = defaultThrottleDeps()) {
+    try {
+        const contents = deps.readFileSync(PROC_MEMINFO, "utf8");
+        const kb = parseMemAvailableKb(contents);
+        if (kb !== null)
+            return kb / 1024;
+        // /proc/meminfo exists but has no MemAvailable (unusual). Fall back.
+        process.stderr.write("lanes throttle: MemAvailable missing from /proc/meminfo; falling back to os.freemem()\n");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            process.stderr.write(`lanes throttle: failed to read ${PROC_MEMINFO}: ${err instanceof Error ? err.message : String(err)}\n`);
+            return null;
+        }
+        // Platform without /proc/meminfo — fall back to free memory.
+    }
+    try {
+        const bytes = deps.freemem();
+        if (!Number.isFinite(bytes) || bytes < 0)
+            return null;
+        return bytes / (1024 * 1024);
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: freemem fallback failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export function emptyThrottleState() {
+    return {
+        consecutiveDeferrals: 0,
+        lastAdmissionAt: null,
+        cpuPaused: false,
+    };
+}
+export function starvationBoundReached(state, nowMs) {
+    if (state.consecutiveDeferrals >= STARVATION_MAX_DEFERRALS)
+        return true;
+    if (state.lastAdmissionAt === null)
+        return false;
+    const last = Date.parse(state.lastAdmissionAt);
+    if (!Number.isFinite(last))
+        return false;
+    return nowMs - last >= STARVATION_MAX_MS;
+}
+export function evaluateThrottle(input) {
+    if (input.state === "unreadable") {
+        return { admit: true, reason: "unreadable" };
+    }
+    const pause = input.throttle.cpu_busy_pause;
+    const resume = input.throttle.cpu_busy_resume;
+    const minMem = input.throttle.min_available_mem_mb;
+    let cpuBlocks = false;
+    if (input.cpuCheckEnabled && input.busy !== null) {
+        if (input.state.cpuPaused) {
+            cpuBlocks = input.busy > resume;
+        }
+        else {
+            cpuBlocks = input.busy >= pause;
+        }
+    }
+    let memBlocks = false;
+    if (input.availableMemMb !== null) {
+        memBlocks = input.availableMemMb < minMem;
+    }
+    if (!cpuBlocks && !memBlocks) {
+        return {
+            admit: true,
+            reason: input.cpuCheckEnabled ? "ok" : "cpu_check_disabled",
+        };
+    }
+    if (starvationBoundReached(input.state, input.nowMs)) {
+        return { admit: true, reason: "starvation_bound" };
+    }
+    if (cpuBlocks) {
+        return { admit: false, reason: "cpu", busy: input.busy ?? undefined };
+    }
+    return {
+        admit: false,
+        reason: "memory",
+        availableMemMb: input.availableMemMb ?? undefined,
+    };
+}
+export function applyThrottleDecision(state, decision, nowMs) {
+    if (decision.admit) {
+        return {
+            ...state,
+            consecutiveDeferrals: 0,
+            lastAdmissionAt: new Date(nowMs).toISOString(),
+            cpuPaused: false,
+        };
+    }
+    return {
+        ...state,
+        consecutiveDeferrals: state.consecutiveDeferrals + 1,
+        lastAdmissionAt: state.lastAdmissionAt,
+        cpuPaused: decision.reason === "cpu" ? true : state.cpuPaused,
+    };
+}
+export function throttleStatePath(hqRoot) {
+    return path.join(hqRoot, "workspace", "lanes-runs", "throttle-state.json");
+}
+export function readThrottleState(filePath, deps = defaultThrottleDeps()) {
+    if (!deps.existsSync(filePath))
+        return "missing";
+    let raw;
+    try {
+        raw = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: failed to read state ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return "unreadable";
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            process.stderr.write(`lanes throttle: state ${filePath} is not an object\n`);
+            return "unreadable";
+        }
+        const obj = parsed;
+        if (typeof obj.consecutiveDeferrals !== "number" ||
+            !Number.isInteger(obj.consecutiveDeferrals) ||
+            obj.consecutiveDeferrals < 0) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid consecutiveDeferrals\n`);
+            return "unreadable";
+        }
+        if (obj.lastAdmissionAt !== null &&
+            typeof obj.lastAdmissionAt !== "string") {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid lastAdmissionAt\n`);
+            return "unreadable";
+        }
+        if (typeof obj.cpuPaused !== "boolean") {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid cpuPaused\n`);
+            return "unreadable";
+        }
+        const optionalTimestamp = (value) => typeof value === "string" && value.trim() !== "" && Number.isFinite(Date.parse(value));
+        let cpuSnapshot;
+        if (obj.cpu_snapshot !== undefined) {
+            const rawSnapshot = obj.cpu_snapshot;
+            if (rawSnapshot === null || typeof rawSnapshot !== "object" || Array.isArray(rawSnapshot)) {
+                process.stderr.write(`lanes throttle: state ${filePath} has invalid cpu_snapshot\n`);
+                return "unreadable";
+            }
+            const snapshot = rawSnapshot;
+            if (typeof snapshot.idle !== "number" || !Number.isFinite(snapshot.idle) || snapshot.idle < 0 ||
+                typeof snapshot.total !== "number" || !Number.isFinite(snapshot.total) || snapshot.total < 0 ||
+                !optionalTimestamp(snapshot.sampled_at)) {
+                process.stderr.write(`lanes throttle: state ${filePath} has invalid cpu_snapshot fields\n`);
+                return "unreadable";
+            }
+            cpuSnapshot = {
+                idle: snapshot.idle,
+                total: snapshot.total,
+                sampled_at: snapshot.sampled_at,
+            };
+        }
+        if (obj.last_busy !== undefined && obj.last_busy !== null && (typeof obj.last_busy !== "number" || !Number.isFinite(obj.last_busy) || obj.last_busy < 0 || obj.last_busy > 1)) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid last_busy\n`);
+            return "unreadable";
+        }
+        if (obj.busy_source !== undefined && !["interval", "window", "override"].includes(String(obj.busy_source))) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid busy_source\n`);
+            return "unreadable";
+        }
+        if (obj.sampled_at !== undefined && !optionalTimestamp(obj.sampled_at)) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid sampled_at\n`);
+            return "unreadable";
+        }
+        return {
+            consecutiveDeferrals: obj.consecutiveDeferrals,
+            lastAdmissionAt: obj.lastAdmissionAt,
+            cpuPaused: obj.cpuPaused,
+            ...(cpuSnapshot !== undefined ? { cpu_snapshot: cpuSnapshot } : {}),
+            ...(obj.last_busy !== undefined ? { last_busy: obj.last_busy } : {}),
+            ...(obj.busy_source !== undefined ? { busy_source: obj.busy_source } : {}),
+            ...(obj.sampled_at !== undefined ? { sampled_at: obj.sampled_at } : {}),
+        };
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: state ${filePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}\n`);
+        return "unreadable";
+    }
+}
+export function writeThrottleState(filePath, state, deps = defaultThrottleDeps()) {
+    const dir = path.dirname(filePath);
+    deps.mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        deps.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, {
+            encoding: "utf8",
+        });
+        deps.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes throttle: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+export async function decideAdmission(hqRoot, throttle = {
+    cpu_busy_pause: DEFAULT_CPU_BUSY_PAUSE,
+    cpu_busy_resume: DEFAULT_CPU_BUSY_RESUME,
+    min_available_mem_mb: DEFAULT_MIN_AVAILABLE_MEM_MB,
+}, deps = defaultThrottleDeps(), cpuBusyFraction, cpuObservation) {
+    const filePath = throttleStatePath(hqRoot);
+    const loaded = readThrottleState(filePath, deps);
+    if (loaded === "unreadable") {
+        return {
+            decision: { admit: true, reason: "unreadable" },
+            state: emptyThrottleState(),
+        };
+    }
+    const state = loaded === "missing" ? emptyThrottleState() : loaded;
+    const cpuCheckEnabled = isCpuCheckEnabled(deps.env);
+    const observation = cpuObservation ?? (cpuBusyFraction === undefined && cpuCheckEnabled
+        ? await sampleCpuBusyObservation(deps, state.cpu_snapshot)
+        : undefined);
+    const busy = cpuBusyFraction === undefined
+        ? observation?.busy ?? null
+        : cpuBusyFraction;
+    const availableMemMb = readAvailableMemMb(deps);
+    const nowMs = deps.now();
+    const decision = evaluateThrottle({
+        busy,
+        availableMemMb,
+        cpuCheckEnabled,
+        state,
+        throttle,
+        nowMs,
+    });
+    const observedState = observation
+        ? recordCpuBusyObservation(state, observation, {
+            advanceSnapshot: cpuObservation !== undefined,
+        })
+        : state;
+    const next = applyThrottleDecision(observedState, decision, nowMs);
+    writeThrottleState(filePath, next, deps);
+    return { decision, state: next };
+}
+//# sourceMappingURL=throttle.js.map

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

@@ -0,0 +1,3 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export declare function normalizeIsoTimestamp(value: unknown): string | null;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/lib/lanes/timestamp.js

@@ -0,0 +1,26 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export function normalizeIsoTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.(\d+))?(Z|([+-])(\d\d):(\d\d))$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const offsetHour = match[9] === undefined ? 0 : Number(match[10]);
+    const offsetMinute = match[9] === undefined ? 0 : Number(match[11]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    if (month < 1 || month > 12 || day < 1 || daysInMonth === undefined || day > daysInMonth ||
+        hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    return new Date(parsed).toISOString();
+}
+//# sourceMappingURL=timestamp.js.map

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" | "orphaned_lane";
+    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/tracker-report-state.d.ts

@@ -0,0 +1,10 @@
+export declare const FIRST_TRACKER_REPORT_SINCE = "1970-01-01T00:00:00.000Z";
+export interface TrackerReportState {
+    schema_version: "hq-lanes-report-state.v1";
+    company: string;
+    last_report_at: string;
+}
+export declare function trackerReportStatePath(root: string, company: string): string;
+export declare function readTrackerReportState(root: string, company: string): TrackerReportState | null;
+export declare function writeTrackerReportState(root: string, company: string, at: string): TrackerReportState;
+//# sourceMappingURL=tracker-report-state.d.ts.map