@indigoai-us/hq-cli 5.263.0 → 5.265.0

package/dist/lib/lanes/kr-freshness.js

@@ -0,0 +1,412 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_KR_FRESHNESS_HOURS, loadLanesConfig } from "./config.js";
+import { LanesError } from "./errors.js";
+import { resolveManagerStatusTarget } from "./manager-status-gate.js";
+import { readLanesRegistryFlag } from "./registry-flag.js";
+import { assertNoSecretText } from "./text-scan.js";
+export const KR_FRESHNESS_FLAG = "lanes.kr-freshness";
+export const KR_FRESHNESS_DEFAULT_HOURS = DEFAULT_KR_FRESHNESS_HOURS;
+export const KR_FRESHNESS_LEDGER_REL = path.join("workspace", "lanes", "kpi-ledger");
+export const KR_FRESHNESS_LEDGER_SCHEMA = "kr-freshness-ledger.v1";
+export const KR_FRESHNESS_HISTORY_LIMIT = 50;
+const MAX_STATUS_BYTES = 1024 * 1024;
+const MAX_LEDGER_BYTES = 1024 * 1024;
+const MAX_KPIS = 1000;
+const REMOVED_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fail(code, message, details = {}) {
+    throw new LanesError(code, message, details);
+}
+function errorCode(error) {
+    return error instanceof LanesError ? error.error : "kr_freshness_unavailable";
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function displayName(name) {
+    const chars = Array.from(name);
+    return chars.length <= 120 ? name : `${chars.slice(0, 119).join("")}…`;
+}
+function safeLaneId(laneId) {
+    return /^[A-Za-z0-9._-]{1,200}$/.test(laneId) && laneId !== "." && laneId !== "..";
+}
+function ensureLedgerDirectory(root, create) {
+    let current = path.resolve(root);
+    const parts = [current];
+    for (const segment of ["workspace", "lanes", "kpi-ledger"]) {
+        current = path.join(current, segment);
+        parts.push(current);
+    }
+    for (const [index, directory] of parts.entries()) {
+        if (create && index > 0) {
+            try {
+                fs.mkdirSync(directory, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST") {
+                    fail("kr_freshness_ledger_write_failed", `Cannot create KR freshness ledger directory: ${directory}`, { path: directory });
+                }
+            }
+        }
+        let stat;
+        try {
+            stat = fs.lstatSync(directory);
+        }
+        catch (error) {
+            if (!create && error.code === "ENOENT")
+                return false;
+            fail("kr_freshness_ledger_unavailable", `Cannot inspect KR freshness ledger directory: ${directory}`, { path: directory });
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            fail("kr_freshness_ledger_invalid", `KR freshness ledger path must not be a symlink: ${directory}`, { path: directory });
+        }
+    }
+    return true;
+}
+function ledgerFilePath(root, laneId) {
+    if (!safeLaneId(laneId))
+        fail("kr_freshness_lane_id_invalid", "Lane id cannot be used as a KR freshness ledger filename");
+    return path.join(root, KR_FRESHNESS_LEDGER_REL, `${laneId}.json`);
+}
+function validDate(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function validateLedger(value, laneId, filePath) {
+    if (!isObject(value) || value.schema_version !== KR_FRESHNESS_LEDGER_SCHEMA || value.lane_id !== laneId ||
+        !validDate(value.updated_at) || !isObject(value.kpis)) {
+        fail("kr_freshness_ledger_invalid", `KR freshness ledger has an invalid shape: ${filePath}`, { path: filePath });
+    }
+    const keys = Object.keys(value.kpis);
+    if (keys.length > MAX_KPIS)
+        fail("kr_freshness_ledger_invalid", `KR freshness ledger exceeds ${MAX_KPIS} entries`, { path: filePath });
+    const kpis = {};
+    for (const key of keys) {
+        const row = value.kpis[key];
+        if (!/^[a-f0-9]{64}$/.test(key) || !isObject(row) || typeof row.name !== "string" || row.name.trim() === "" ||
+            !(typeof row.value === "string" || (typeof row.value === "number" && Number.isFinite(row.value))) ||
+            !(row.entry_measured_at === null || typeof row.entry_measured_at === "string") ||
+            !validDate(row.first_seen_at) || !validDate(row.measured_at) || !validDate(row.value_changed_at) ||
+            (row.removed_at !== undefined && !validDate(row.removed_at))) {
+            fail("kr_freshness_ledger_invalid", `KR freshness ledger contains an invalid KPI record: ${filePath}`, { path: filePath });
+        }
+        assertNoSecretText("KR name", row.name);
+        if (typeof row.value === "string")
+            assertNoSecretText("KR value", row.value);
+        if (typeof row.entry_measured_at === "string")
+            assertNoSecretText("KR measured_at", row.entry_measured_at);
+        kpis[key] = {
+            name: row.name,
+            value: row.value,
+            entry_measured_at: row.entry_measured_at,
+            first_seen_at: row.first_seen_at,
+            measured_at: row.measured_at,
+            value_changed_at: row.value_changed_at,
+            ...(typeof row.removed_at === "string" ? { removed_at: row.removed_at } : {}),
+        };
+    }
+    return {
+        schema_version: KR_FRESHNESS_LEDGER_SCHEMA,
+        lane_id: laneId,
+        updated_at: value.updated_at,
+        kpis,
+    };
+}
+export function readKrFreshnessStatus(statusPath) {
+    let stat;
+    try {
+        stat = fs.lstatSync(statusPath);
+    }
+    catch (error) {
+        fail("kr_freshness_status_unreadable", `Cannot inspect manager status for KR freshness: ${statusPath}`, {
+            path: statusPath,
+            cause: error.code ?? "unknown",
+        });
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_STATUS_BYTES) {
+        fail("kr_freshness_status_invalid", `Manager status is not a bounded regular file: ${statusPath}`, { path: statusPath });
+    }
+    let text;
+    try {
+        text = fs.readFileSync(statusPath, "utf8");
+    }
+    catch (error) {
+        fail("kr_freshness_status_unreadable", `Cannot read manager status for KR freshness: ${statusPath}`, {
+            path: statusPath,
+            cause: error.code ?? "unknown",
+        });
+    }
+    if (Buffer.byteLength(text, "utf8") > MAX_STATUS_BYTES) {
+        fail("kr_freshness_status_invalid", `Manager status exceeds the KR freshness size limit: ${statusPath}`, { path: statusPath });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        fail("kr_freshness_status_invalid", `Manager status contains invalid JSON: ${statusPath}`, { path: statusPath });
+    }
+    if (!isObject(parsed) || !Array.isArray(parsed.kpis)) {
+        fail("kr_freshness_status_invalid", `Manager status must contain a top-level kpis array: ${statusPath}`, { path: statusPath });
+    }
+    if (parsed.kpis.length > MAX_KPIS) {
+        fail("kr_freshness_status_invalid", `Manager status exceeds ${MAX_KPIS} KPIs: ${statusPath}`, { path: statusPath });
+    }
+    const found = new Map();
+    for (const [index, candidate] of parsed.kpis.entries()) {
+        if (!isObject(candidate) || typeof candidate.name !== "string" || candidate.name.trim() === "")
+            continue;
+        const fullName = candidate.name.trim();
+        if (Array.from(fullName).some((char) => {
+            const codePoint = char.codePointAt(0) ?? 0;
+            return codePoint <= 0x1f || codePoint === 0x7f;
+        })) {
+            fail("kr_freshness_status_invalid", `Manager KPI ${index + 1} name contains control characters: ${statusPath}`, { path: statusPath, index });
+        }
+        if (!(typeof candidate.value === "string" || (typeof candidate.value === "number" && Number.isFinite(candidate.value)))) {
+            fail("kr_freshness_status_invalid", `Manager KPI ${index + 1} needs a string or finite number value: ${statusPath}`, { path: statusPath, index });
+        }
+        if (candidate.measured_at !== undefined && typeof candidate.measured_at !== "string") {
+            fail("kr_freshness_status_invalid", `Manager KPI ${index + 1} measured_at must be a string when present: ${statusPath}`, { path: statusPath, index });
+        }
+        assertNoSecretText("KR name", fullName);
+        if (typeof candidate.value === "string")
+            assertNoSecretText("KR value", candidate.value);
+        if (typeof candidate.measured_at === "string")
+            assertNoSecretText("KR measured_at", candidate.measured_at);
+        const key = sha256(fullName);
+        if (found.has(key))
+            fail("kr_freshness_status_invalid", `Manager status contains duplicate KPI names: ${statusPath}`, { path: statusPath, index });
+        found.set(key, {
+            key,
+            fullName,
+            name: displayName(fullName),
+            value: candidate.value,
+            entryMeasuredAt: typeof candidate.measured_at === "string" ? candidate.measured_at : null,
+        });
+    }
+    return [...found.values()];
+}
+export function krFreshnessLedgerPath(root, laneId) {
+    return ledgerFilePath(root, laneId);
+}
+export function readKrFreshnessLedger(root, laneId) {
+    const filePath = ledgerFilePath(root, laneId);
+    if (!ensureLedgerDirectory(root, false))
+        return null;
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        fail("kr_freshness_ledger_unreadable", `Cannot inspect KR freshness ledger: ${filePath}`, { path: filePath });
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_LEDGER_BYTES) {
+        fail("kr_freshness_ledger_invalid", `KR freshness ledger is not a bounded regular file: ${filePath}`, { path: filePath });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        fail("kr_freshness_ledger_invalid", `KR freshness ledger contains invalid JSON: ${filePath}`, { path: filePath });
+    }
+    return validateLedger(parsed, laneId, filePath);
+}
+export function writeKrFreshnessLedger(root, ledger) {
+    const filePath = ledgerFilePath(root, ledger.lane_id);
+    const directory = path.dirname(filePath);
+    let tempPath;
+    try {
+        ensureLedgerDirectory(root, true);
+        const data = `${JSON.stringify(ledger, null, 2)}\n`;
+        if (Buffer.byteLength(data, "utf8") > MAX_LEDGER_BYTES) {
+            fail("kr_freshness_ledger_invalid", `KR freshness ledger exceeds ${MAX_LEDGER_BYTES} bytes`, { path: filePath });
+        }
+        tempPath = path.join(directory, `.${ledger.lane_id}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+        fs.writeFileSync(tempPath, data, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        if (tempPath !== undefined) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* preserve the original write failure */ }
+        }
+        if (error instanceof LanesError)
+            throw error;
+        fail("kr_freshness_ledger_write_failed", `Cannot write KR freshness ledger: ${filePath}`, { path: filePath });
+    }
+}
+export function updateKrFreshnessLedger(laneId, prior, statusKpis, now) {
+    const at = new Date(now).toISOString();
+    const next = {};
+    const seen = new Set();
+    for (const item of statusKpis) {
+        const { key, fullName } = item;
+        seen.add(key);
+        const old = prior?.kpis[key];
+        const changed = old === undefined || JSON.stringify(old.value) !== JSON.stringify(item.value);
+        const remeasured = old === undefined || old.removed_at !== undefined || old.entry_measured_at !== item.entryMeasuredAt;
+        next[key] = {
+            name: item.name,
+            value: item.value,
+            entry_measured_at: item.entryMeasuredAt,
+            first_seen_at: old?.first_seen_at ?? at,
+            measured_at: changed || remeasured ? at : old.measured_at,
+            value_changed_at: changed ? at : old.value_changed_at,
+        };
+        assertNoSecretText("KR name", fullName);
+    }
+    for (const [key, old] of Object.entries(prior?.kpis ?? {})) {
+        if (seen.has(key))
+            continue;
+        const removedAt = old.removed_at ?? at;
+        if (now - Date.parse(removedAt) >= REMOVED_RETENTION_MS)
+            continue;
+        next[key] = { ...old, removed_at: removedAt };
+    }
+    if (Object.keys(next).length > MAX_KPIS) {
+        fail("kr_freshness_ledger_invalid", `KR freshness ledger exceeds ${MAX_KPIS} retained entries`);
+    }
+    return {
+        schema_version: KR_FRESHNESS_LEDGER_SCHEMA,
+        lane_id: laneId,
+        updated_at: at,
+        kpis: next,
+    };
+}
+export function krFreshnessVerdict(kpi, now, windowHours) {
+    const cutoff = now - windowHours * 60 * 60 * 1000;
+    if (Date.parse(kpi.value_changed_at) >= cutoff)
+        return "moving";
+    if (Date.parse(kpi.measured_at) >= cutoff)
+        return "flat";
+    return "stalled";
+}
+export function krFreshnessFingerprint(keys) {
+    return sha256(JSON.stringify([...keys].sort()));
+}
+function viewsFromLedger(ledger, now, windowHours) {
+    if (!ledger)
+        return [];
+    return Object.entries(ledger.kpis)
+        .filter(([, kpi]) => kpi.removed_at === undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, kpi]) => ({
+        name: kpi.name,
+        value: kpi.value,
+        verdict: krFreshnessVerdict(kpi, now, windowHours),
+        measured_at: kpi.measured_at,
+        value_changed_at: kpi.value_changed_at,
+    }));
+}
+function reportFailure(lane, error) {
+    process.stderr.write(`hq lanes: KR freshness disabled for ${lane.lane_id}: ${errorCode(error)}\n`);
+}
+function failedResolution(error, onError) {
+    onError(error);
+    return {
+        flagEnabled: false,
+        enabled: false,
+        windowHours: KR_FRESHNESS_DEFAULT_HOURS,
+        kpis: [],
+        stalledKeys: [],
+        error: errorCode(error),
+    };
+}
+/** Read the flag before manager mapping, status, configuration or ledger files. */
+export async function resolveKrFreshnessForLane(root, lane, options = {}) {
+    const onError = options.onError ?? ((error) => reportFailure(lane, error));
+    let flagEnabled;
+    try {
+        flagEnabled = await (options.readFlag ?? readLanesRegistryFlag)(KR_FRESHNESS_FLAG, {
+            company: lane.company ?? lane.mesh_company ?? undefined,
+            env: options.env,
+        });
+    }
+    catch (error) {
+        return failedResolution(error, onError);
+    }
+    if (!flagEnabled) {
+        return { flagEnabled: false, enabled: false, windowHours: KR_FRESHNESS_DEFAULT_HOURS, kpis: [], stalledKeys: [] };
+    }
+    try {
+        const target = resolveManagerStatusTarget(root, lane);
+        if (!target.manager || target.statusPath === undefined) {
+            return {
+                flagEnabled: true,
+                enabled: true,
+                target,
+                windowHours: KR_FRESHNESS_DEFAULT_HOURS,
+                kpis: [],
+                stalledKeys: [],
+            };
+        }
+        const windowHours = loadLanesConfig(root).kr_freshness_hours;
+        const statusKpis = readKrFreshnessStatus(target.statusPath);
+        const prior = readKrFreshnessLedger(root, lane.lane_id);
+        const ledger = updateKrFreshnessLedger(lane.lane_id, prior, statusKpis, options.now ?? Date.now());
+        writeKrFreshnessLedger(root, ledger);
+        const effectiveNow = options.now ?? Date.now();
+        return {
+            flagEnabled: true,
+            enabled: true,
+            target,
+            statusPath: target.statusPath,
+            windowHours,
+            kpis: viewsFromLedger(ledger, effectiveNow, windowHours),
+            stalledKeys: Object.entries(ledger.kpis)
+                .filter(([, kpi]) => kpi.removed_at === undefined && krFreshnessVerdict(kpi, effectiveNow, windowHours) === "stalled")
+                .map(([key]) => key)
+                .sort(),
+        };
+    }
+    catch (error) {
+        return failedResolution(error, onError);
+    }
+}
+/** Read a previously written ledger for `lanes show`; this never reads status. */
+export async function resolveKrFreshnessForShow(root, lane, options = {}) {
+    const onError = options.onError ?? ((error) => reportFailure(lane, error));
+    let enabled;
+    try {
+        enabled = await (options.readFlag ?? readLanesRegistryFlag)(KR_FRESHNESS_FLAG, {
+            company: lane.company ?? lane.mesh_company ?? undefined,
+            env: options.env,
+        });
+    }
+    catch (error) {
+        onError(error);
+        return null;
+    }
+    if (!enabled)
+        return null;
+    try {
+        const windowHours = loadLanesConfig(root).kr_freshness_hours;
+        const ledger = readKrFreshnessLedger(root, lane.lane_id);
+        return { enabled: true, kpis: viewsFromLedger(ledger, options.now ?? Date.now(), windowHours) };
+    }
+    catch (error) {
+        onError(error);
+        return null;
+    }
+}
+/** Operator report path: the ledger remains readable while runtime enforcement is off. */
+export function readKrFreshnessReport(root, laneId, now) {
+    const ledger = readKrFreshnessLedger(root, laneId);
+    const windowHours = loadLanesConfig(root).kr_freshness_hours;
+    return {
+        ledger_path: krFreshnessLedgerPath(root, laneId),
+        available: ledger !== null,
+        kr_freshness_hours: windowHours,
+        kpis: viewsFromLedger(ledger, now, windowHours),
+    };
+}
+//# sourceMappingURL=kr-freshness.js.map

package/dist/lib/lanes/lane-company.d.ts

@@ -0,0 +1,9 @@
+import type { LaneCompanyRef, LaneRecord } from "./types.js";
+export type LaneCompanySource = "lane" | "project" | "unresolved";
+export interface LaneCompanyResolution {
+    company: LaneCompanyRef | null;
+    source: LaneCompanySource;
+}
+/** Resolve a lane's company without inferring ownership from its worker or caller. */
+export declare function resolveLaneCompany(hqRoot: string, lane: Pick<LaneRecord, "lane_id" | "company" | "project_id">): LaneCompanyResolution;
+//# sourceMappingURL=lane-company.d.ts.map

package/dist/lib/lanes/lane-company.js

@@ -0,0 +1,24 @@
+import { resolveProjectQuestionCompany } from "./questions.js";
+import { LanesError } from "./errors.js";
+/** Resolve a lane's company without inferring ownership from its worker or caller. */
+export function resolveLaneCompany(hqRoot, lane) {
+    const slug = typeof lane.company?.slug === "string" ? lane.company.slug.trim() : "";
+    const uid = typeof lane.company?.uid === "string" ? lane.company.uid.trim() : "";
+    if (slug && uid) {
+        return { company: { slug, uid }, source: "lane" };
+    }
+    let projectCompany;
+    try {
+        projectCompany = resolveProjectQuestionCompany(hqRoot, lane);
+    }
+    catch (err) {
+        if (err instanceof LanesError && err.error === "question_company_unavailable") {
+            return { company: null, source: "unresolved" };
+        }
+        throw err;
+    }
+    return projectCompany
+        ? { company: projectCompany, source: "project" }
+        : { company: null, source: "unresolved" };
+}
+//# sourceMappingURL=lane-company.js.map

package/dist/lib/lanes/reconcile.js

@@ -22,6 +22,7 @@ import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecor
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
+import { resolveLaneCompany } from "./lane-company.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, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
@@ -851,8 +852,11 @@ export async function runPassBody(hqRoot, deps) {
             if (doneKeepAliveVerdict(lane, envelope, hasQueuedWork) !== "eligible")
                 continue;
         }
-        const key = keepAliveCompanyKey(lane.company);
-        keepAliveFlagCompanies.set(key, lane.company);
+        const company = resolveLaneCompany(hqRoot, lane).company;
+        if (company === null)
+            continue;
+        const key = keepAliveCompanyKey(company);
+        keepAliveFlagCompanies.set(key, company);
     }
     const keepAliveFlagByCompany = new Map();
     const supersessionLineageAwareByCompany = new Map();
@@ -1598,6 +1602,15 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
     const nowMs = now.getTime();
     const nowIso = now.toISOString();
     const config = loadLanesConfig(hqRoot);
+    const resolvedCompanyByLaneVersion = new Map();
+    const companyForLane = (candidate) => {
+        const key = `${candidate.lane_id}\u0000${candidate.version}`;
+        if (resolvedCompanyByLaneVersion.has(key))
+            return resolvedCompanyByLaneVersion.get(key) ?? null;
+        const company = resolveLaneCompany(hqRoot, candidate).company;
+        resolvedCompanyByLaneVersion.set(key, company);
+        return company;
+    };
     const keepAliveEnabled = [...flagByCompany.values()].some((enabled) => enabled);
     let retiredLaneIds = null;
     if (keepAliveEnabled) {
@@ -1615,7 +1628,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             originalLane.state === "cancelled" ||
             originalLane.state === "failed") {
             if (originalLane.keep_alive === true &&
-                flagByCompany.get(keepAliveCompanyKey(originalLane.company)) === true)
+                flagByCompany.get(keepAliveCompanyKey(companyForLane(originalLane))) === true)
                 recordKeepAliveSkip(hqRoot, originalLane, "terminal_state", summary, deps);
             continue;
         }
@@ -1641,8 +1654,28 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
                 continue;
             }
         }
-        if (flagByCompany.get(keepAliveCompanyKey(lane.company)) !== true)
+        const company = companyForLane(lane);
+        if (company === null) {
+            if (lane.keep_alive === true) {
+                summary.skipped.push({
+                    kind: "lane",
+                    id: lane.lane_id,
+                    why: "keep_alive_company_unresolved",
+                });
+            }
             continue;
+        }
+        const companyKey = keepAliveCompanyKey(company);
+        if (flagByCompany.get(companyKey) !== true) {
+            if (lane.keep_alive === true) {
+                summary.skipped.push({
+                    kind: "lane",
+                    id: lane.lane_id,
+                    why: "keep_alive_flag_off",
+                });
+            }
+            continue;
+        }
         // Persist a stable timestamp for legacy interrupted rows before a later
         // keep-alive status write can advance their general updated_at clock. The
         // watcher classification is the interruption time; updated_at is only an
@@ -1760,7 +1793,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             recordKeepAliveSkip(hqRoot, lane, "retired_list_invalid", summary, deps);
             continue;
         }
-        const exclusion = keepAliveExclusion(lane, lanes, retiredLaneIds, supersessionLineageAwareByCompany.get(keepAliveCompanyKey(lane.company)) === true);
+        const exclusion = keepAliveExclusion(lane, lanes, retiredLaneIds, supersessionLineageAwareByCompany.get(companyKey) === true, companyForLane);
         if (exclusion !== undefined) {
             recordKeepAliveSkip(hqRoot, lane, exclusion, summary, deps);
             continue;
@@ -1851,7 +1884,25 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             continue;
         }
         const currentLanes = loadLaneRecords(hqRoot, summary);
-        const currentExclusion = keepAliveExclusion(current, currentLanes, retiredLaneIds, supersessionLineageAwareByCompany.get(keepAliveCompanyKey(current.company)) === true);
+        const currentCompany = companyForLane(current);
+        if (currentCompany === null) {
+            summary.skipped.push({
+                kind: "lane",
+                id: current.lane_id,
+                why: "keep_alive_company_unresolved",
+            });
+            continue;
+        }
+        const currentCompanyKey = keepAliveCompanyKey(currentCompany);
+        if (flagByCompany.get(currentCompanyKey) !== true) {
+            summary.skipped.push({
+                kind: "lane",
+                id: current.lane_id,
+                why: "keep_alive_flag_off",
+            });
+            continue;
+        }
+        const currentExclusion = keepAliveExclusion(current, currentLanes, retiredLaneIds, supersessionLineageAwareByCompany.get(currentCompanyKey) === true, companyForLane);
         if (currentExclusion !== undefined) {
             recordKeepAliveSkip(hqRoot, current, currentExclusion, summary, deps);
             continue;

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

@@ -370,7 +370,22 @@ export interface BlockerFreshnessHistoryEntry {
     resume_skipped_reason?: "open_question" | "blocked" | "miss_limit" | "no_provider_session";
     delivery_failed?: true;
 }
-export type LaneGateHistoryEntry = ManagerStatusGateHistoryEntry | BlockerFreshnessHistoryEntry;
+export interface KrFreshnessState {
+    /** Stable fingerprint of the last stalled KPI set, which is resumed once. */
+    stalled_fingerprint?: string;
+}
+export interface KrFreshnessHistoryEntry {
+    event: "kr_stalled";
+    turn_id: string;
+    path: string;
+    at: string;
+    names: string[];
+    count: number;
+    fingerprint: string;
+    resume_queued?: boolean;
+    resume_skipped_reason?: "open_question" | "blocked" | "miss_limit" | "no_provider_session";
+}
+export type LaneGateHistoryEntry = ManagerStatusGateHistoryEntry | BlockerFreshnessHistoryEntry | KrFreshnessHistoryEntry;
 export interface LaneStory {
     project_id: string;
     story_id: string;
@@ -516,6 +531,8 @@ export interface LaneRecord {
     status_gate_history?: LaneGateHistoryEntry[];
     /** Last blocker-freshness state used to detect consecutive stale turns. */
     blocker_freshness_state?: BlockerFreshnessState;
+    /** Last stalled KR set already offered one automatic resume. */
+    kr_freshness_state?: KrFreshnessState;
     /** Last automatic compaction of a resumed session (compaction.ts). */
     last_compaction?: LaneCompactionRecord;
     /**
@@ -857,6 +874,8 @@ export interface LanesConfig {
     session_question_timeout_secs: number;
     /** Age in hours after which an open manager blocker must be re-verified. */
     blocker_freshness_hours: number;
+    /** Age in hours after which a manager KPI is considered stalled. */
+    kr_freshness_hours: number;
 }
 export declare function parseMajorSchema(schemaVersion: string, expectedPrefix: string, expectedMajor: number): void;
 export declare function parseLaneEnvelope(raw: unknown): LaneEnvelope;

package/dist/lib/lanes/types.js

@@ -228,7 +228,7 @@ export const LANE_FIELD_WRITERS = {
     provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
-    last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
+    last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
     admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], interrupted_at: ["watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],

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

@@ -233,6 +233,8 @@ export interface WatcherLoopDeps {
     readManagerStatusGateFlag?: typeof readLanesRegistryFlag;
     /** Test seam; production reads the company-scoped hq-flags row. */
     readBlockerFreshnessFlag?: typeof readLanesRegistryFlag;
+    /** Test seam; production reads the company-scoped hq-flags row. */
+    readKrFreshnessFlag?: typeof readLanesRegistryFlag;
 }
 /**
  * Wrap one mesh call. A failed emit is logged as `mesh_event_failed` with