@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/lib/lanes/keep-alive.js

@@ -1,343 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { LanesError } from "./errors.js";
-import { dropboxInboxHasMessages } from "./dropbox.js";
-import { appendCappedHistory, listQuestionIds, readQuestion, retryUpdateLane } from "./store.js";
-import { isTerminalLaneState, isIsoDateTime, } from "./types.js";
-export const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
-export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
-export const LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS = 24 * 60 * 60 * 1000;
-export const LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG = "lanes.keep-alive-resume-blocked";
-export const LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_DEFAULT_ENABLED = false;
-export const LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG = "lanes.keep-alive-immediate-first-resume";
-export const LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_DEFAULT_ENABLED = false;
-export const LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS = 30_000;
-export const LEAD_LANE_KEEP_ALIVE_TERMINAL_TRIGGER_FLAG = "lanes.keep-alive-terminal-trigger";
-export const LEAD_LANE_KEEP_ALIVE_TERMINAL_TRIGGER_DEFAULT_ENABLED = false;
-export const LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS = 15 * 60 * 1000;
-/** Missing or unreadable registry values retain the legacy supersession behavior. */
-export const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
-export const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
-/** Missing or unreadable registry values keep rejecting superseded messages. */
-export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
-export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
-export const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
-export const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS = 5 * 60 * 1000;
-export const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS = 60 * 60 * 1000;
-/** Shared resume transition for terminal gate follow-ups. */
-export function queueLaneTerminalResume(current, at, resumeText, options = {}) {
-    if (options.mergeExisting && current.pending_resume !== undefined) {
-        return {
-            lane: {
-                ...current,
-                pending_resume: {
-                    ...current.pending_resume,
-                    text: `${current.pending_resume.text}\n\n${resumeText}`,
-                },
-            },
-            resumeQueued: true,
-        };
-    }
-    if (current.state === "blocked" && options.allowBlockedResume !== true)
-        return { lane: current, resumeQueued: false, resumeSkippedReason: "blocked" };
-    if (current.state === "awaiting_input")
-        return { lane: current, resumeQueued: false, resumeSkippedReason: "open_question" };
-    if (options.allowResume === false)
-        return { lane: current, resumeQueued: false, resumeSkippedReason: "miss_limit" };
-    if (current.state !== "done" && current.state !== "interrupted" && current.state !== "failed" && !(current.state === "blocked" && options.allowBlockedResume === true)) {
-        return { lane: current, resumeQueued: false };
-    }
-    const sessionId = current.provider_session_id ?? current.last_resume?.session_id;
-    if (!sessionId) {
-        return { lane: current, resumeQueued: false, resumeSkippedReason: "no_provider_session" };
-    }
-    return {
-        lane: {
-            ...current,
-            state: "queued",
-            queued_reason: undefined,
-            queued_details: undefined,
-            queued_at: at,
-            admission_reserved_at: undefined,
-            terminal_reason: undefined,
-            terminal_details: undefined,
-            pending_resume: {
-                session_id: sessionId,
-                trigger: options.trigger ?? "watcher",
-                resumed_from: current.state,
-                text: resumeText,
-                compact: true,
-                at,
-            },
-        },
-        resumeQueued: true,
-    };
-}
-/** Persist a manager status miss and queue its one bounded follow-up turn. */
-export function queueManagerStatusGateResume(hqRoot, laneId, entry, resumeText) {
-    return retryUpdateLane(hqRoot, laneId, "watcher", (current) => {
-        const gate = current.status_gate;
-        if (gate === undefined || gate.turn_id !== entry.turn_id)
-            return current;
-        const history = current.status_gate_history ?? [];
-        if (history.some((prior) => prior.event === "status_missed" && prior.turn_id === entry.turn_id)) {
-            return current;
-        }
-        const consecutiveMisses = gate.consecutive_misses + 1;
-        const transitioned = queueLaneTerminalResume({
-            ...current,
-            status_gate: { ...gate, consecutive_misses: consecutiveMisses },
-        }, entry.at, resumeText, { allowResume: consecutiveMisses <= 1 });
-        const missed = {
-            event: "status_missed",
-            ...entry,
-            ...(transitioned.resumeQueued ? { resume_queued: true } : {}),
-            ...(transitioned.resumeSkippedReason !== undefined
-                ? { resume_skipped_reason: transitioned.resumeSkippedReason }
-                : {}),
-        };
-        return {
-            ...transitioned.lane,
-            status_gate_history: appendCappedHistory(history, missed),
-        };
-    });
-}
-export const LEAD_LANE_KEEP_ALIVE_RESUME_TEXT = "Automatic keep-alive resume: your last turn ended with decision done and story_complete false. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
-export const LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT = "You ended blocked with no pending question. Record the event you wait on in waiting_on, re-check each blocker, and continue the next unblocked story.";
-export const LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT = "Automatic keep-alive resume: your previous turn was interrupted by a provider process exit. Check your last state before continuing. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
-export function keepAliveNextCheckAtMs(value, nowMs, anchorMs = nowMs) {
-    if (typeof value !== "string" || !isIsoDateTime(value))
-        return undefined;
-    const parsed = Date.parse(value);
-    if (parsed <= nowMs)
-        return undefined;
-    const stableAnchorMs = Number.isFinite(anchorMs) ? anchorMs : nowMs;
-    const capped = Math.min(parsed, stableAnchorMs + LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS);
-    return capped > nowMs ? capped : undefined;
-}
-/** Shared done-state policy used by watch, reconcile, and the show command. */
-export function doneKeepAliveVerdict(lane, envelope, hasQueuedWork, options = {}) {
-    if (envelope.decision !== "done")
-        return null;
-    let verdict;
-    if (envelope.story_complete !== true)
-        verdict = "eligible";
-    else if (lane.keep_alive_standing !== true)
-        verdict = "story_complete";
-    else
-        verdict = hasQueuedWork ? "eligible" : "standing_idle";
-    if (verdict === "eligible" && options.hasPendingWork !== true) {
-        const nowMs = options.nowMs ?? Date.now();
-        const anchorMs = options.nextCheckAnchorMs ?? nowMs;
-        const nextCheckAtMs = keepAliveNextCheckAtMs(envelope.next_check_at, nowMs, anchorMs);
-        if (nextCheckAtMs !== undefined)
-            return "next_check_at";
-    }
-    return verdict;
-}
-export function canResumeDoneKeepAliveLane(lane, envelope, hasQueuedWork) {
-    return doneKeepAliveVerdict(lane, envelope, hasQueuedWork) === "eligible";
-}
-/** Work signals already persisted for a lane that ended its turn. */
-export function hasPendingKeepAliveWork(hqRoot, lane, questionRecords) {
-    if (lane.pending_resume !== undefined)
-        return true;
-    if (dropboxInboxHasMessages(hqRoot, lane.lane_id))
-        return true;
-    const questions = questionRecords ?? readKeepAliveQuestionRecords(hqRoot);
-    return undeliveredAnsweredQuestions(lane, questions).length > 0;
-}
-/** Undelivered answers that belong to this lane and company. */
-export function undeliveredAnsweredQuestions(lane, questions) {
-    return questions.filter((question) => {
-        const sameCompany = question.company === null
-            ? lane.company === null
-            : lane.company !== null &&
-                question.company.uid === lane.company.uid &&
-                question.company.slug === lane.company.slug;
-        return (question.lane_id === lane.lane_id &&
-            question.origin.id === lane.lane_id &&
-            sameCompany &&
-            question.status === "answered" &&
-            question.answer !== undefined &&
-            (question.delivered_at === null || question.delivered_at === undefined));
-    });
-}
-function readKeepAliveQuestionRecords(hqRoot) {
-    const questions = [];
-    for (const questionId of listQuestionIds(hqRoot)) {
-        try {
-            questions.push(readQuestion(hqRoot, questionId));
-        }
-        catch (err) {
-            process.stderr.write(`hq lanes keep-alive: skipped unreadable question ${questionId}: ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-    }
-    return questions;
-}
-export function retiredLaneRegistryPath(hqRoot) {
-    return path.join(hqRoot, "workspace", "lane-briefs", "juniors.json");
-}
-/** Missing registry means no retired lanes; every present invalid file fails closed. */
-export function loadRetiredLaneIds(hqRoot) {
-    const filePath = retiredLaneRegistryPath(hqRoot);
-    let text;
-    try {
-        const stat = fs.lstatSync(filePath);
-        if (!stat.isFile() || stat.isSymbolicLink()) {
-            throw new Error("expected a regular file");
-        }
-        text = fs.readFileSync(filePath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return new Set();
-        throw new LanesError("keep_alive_retired_list_invalid", `Cannot read retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch (err) {
-        throw new LanesError("keep_alive_retired_list_invalid", `Cannot parse retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
-    }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw invalidRetiredList(filePath, "root must be an object");
-    }
-    const retired = parsed.retired;
-    if (retired === undefined)
-        return new Set();
-    if (!Array.isArray(retired))
-        throw invalidRetiredList(filePath, "retired must be an array");
-    const laneIds = new Set();
-    for (const [index, entry] of retired.entries()) {
-        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
-            throw invalidRetiredList(filePath, `retired[${index}] must be an object with a lane id`);
-        }
-        const laneId = entry.lane;
-        if (typeof laneId !== "string" || laneId.trim() === "") {
-            throw invalidRetiredList(filePath, `retired[${index}].lane must be a non-empty string`);
-        }
-        laneIds.add(laneId.trim());
-    }
-    return laneIds;
-}
-function invalidRetiredList(filePath, message) {
-    return new LanesError("keep_alive_retired_list_invalid", `Invalid retired lane list ${filePath}: ${message}`, { path: filePath });
-}
-/** IDs may be stored bare or with an owner-host suffix after an underscore. */
-export function isRetiredLaneId(laneId, retiredLaneIds) {
-    for (const retiredId of retiredLaneIds) {
-        if (retiredId === laneId ||
-            retiredId.startsWith(`${laneId}_`) ||
-            laneId.startsWith(`${retiredId}_`))
-            return true;
-    }
-    return false;
-}
-export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED, companyForLane) {
-    const createdAt = Date.parse(lane.created_at);
-    if (!Number.isFinite(createdAt))
-        return undefined;
-    const companyOf = companyForLane ?? ((candidate) => candidate.company);
-    const laneCompany = companyOf(lane) ?? null;
-    const lanesById = new Map(lanes.map((candidate) => [candidate.lane_id, candidate]));
-    lanesById.set(lane.lane_id, lane);
-    const sessionOwners = new Map();
-    for (const owner of lanesById.values()) {
-        for (const sessionId of recordedLaneSessionIds(owner)) {
-            const owners = sessionOwners.get(sessionId) ?? new Set();
-            owners.add(owner.lane_id);
-            sessionOwners.set(sessionId, owners);
-        }
-    }
-    const targetAncestorIds = lineageAware
-        ? laneAncestorsFrom(lane.senior, lanesById, sessionOwners)
-        : new Set();
-    return lanes.find((candidate) => {
-        if (candidate.lane_id === lane.lane_id || Date.parse(candidate.created_at) <= createdAt)
-            return false;
-        if (candidate.state === "cancelled" ||
-            candidate.state === "killed" ||
-            candidate.state === "failed" ||
-            (lane.state === "running" && isTerminalLaneState(candidate.state)))
-            return false;
-        const candidateCompany = companyOf(candidate) ?? null;
-        const sameCompany = laneCompany === null
-            ? candidateCompany === null
-            : candidateCompany?.uid === laneCompany.uid;
-        if (!sameCompany)
-            return false;
-        if (lineageAware && targetAncestorIds.has(candidate.lane_id))
-            return false;
-        // Any descendant is part of this lead's work tree, not a replacement lead.
-        if (laneAncestorsFrom(candidate.senior, lanesById, sessionOwners).has(lane.lane_id))
-            return false;
-        const sameLaneSenior = (lane.senior.kind === "lane" || lane.senior.kind === "session") &&
-            candidate.senior.kind === lane.senior.kind &&
-            candidate.senior.id === lane.senior.id;
-        const differentKnownSenior = lane.senior.kind === "lane" &&
-            candidate.senior.kind === "lane" &&
-            typeof lane.senior.id === "string" &&
-            lane.senior.id.trim().length > 0 &&
-            typeof candidate.senior.id === "string" &&
-            candidate.senior.id.trim().length > 0 &&
-            candidate.senior.id !== lane.senior.id;
-        const sameProfile = lane.worker_profile !== undefined &&
-            candidate.worker_profile === lane.worker_profile &&
-            !(lane.state === "running" && differentKnownSenior) &&
-            !(lineageAware && sameLaneSenior);
-        const projectLead = lane.project_id !== undefined &&
-            candidate.project_id === lane.project_id &&
-            (candidate.hire_grant ?? 0) > 0;
-        return sameProfile || projectLead;
-    });
-}
-/** Session ids durable lane records still identify as spawn/resume sessions. */
-function recordedLaneSessionIds(lane) {
-    return [lane.provider_session_id, lane.last_resume?.session_id].filter((sessionId) => typeof sessionId === "string" && sessionId.trim().length > 0);
-}
-/** Follow both lane seniors and session seniors back to the lane that owns each session. */
-function laneAncestorsFrom(senior, lanesById, sessionOwners) {
-    const laneIds = new Set();
-    const sessionIds = new Set();
-    const pending = [senior];
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        if (current.kind === "lane") {
-            const laneId = current.id;
-            if (typeof laneId !== "string" || laneId.trim().length === 0 || laneIds.has(laneId))
-                continue;
-            laneIds.add(laneId);
-            const parent = lanesById.get(laneId);
-            if (parent !== undefined)
-                pending.push(parent.senior);
-            continue;
-        }
-        if (current.kind !== "session")
-            continue;
-        const sessionId = current.id;
-        if (typeof sessionId !== "string" || sessionId.trim().length === 0 || sessionIds.has(sessionId))
-            continue;
-        sessionIds.add(sessionId);
-        for (const ownerLaneId of sessionOwners.get(sessionId) ?? []) {
-            pending.push({ kind: "lane", id: ownerLaneId });
-        }
-    }
-    return laneIds;
-}
-export function keepAliveExclusion(lane, lanes, retiredLaneIds, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED, companyForLane) {
-    if (isRetiredLaneId(lane.lane_id, retiredLaneIds))
-        return "retired";
-    return keepAliveSupersededBy(lane, lanes, lineageAware, companyForLane) === undefined ? undefined : "superseded";
-}
-export function leadLaneKeepAliveBackoffMs(attempt) {
-    if (!Number.isSafeInteger(attempt) || attempt < 1) {
-        throw new RangeError("keep-alive attempt must be a positive safe integer");
-    }
-    const exponential = LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS * 2 ** (attempt - 1);
-    return Math.min(exponential, LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS);
-}
-//# sourceMappingURL=keep-alive.js.map

package/dist/lib/lanes/kr-freshness.d.ts

@@ -1,76 +0,0 @@
-import { type ManagerStatusTarget } from "./manager-status-gate.js";
-import { readLanesRegistryFlag } from "./registry-flag.js";
-import type { LaneRecord } from "./types.js";
-export declare const KR_FRESHNESS_FLAG = "lanes.kr-freshness";
-export declare const KR_FRESHNESS_DEFAULT_HOURS = 6;
-export declare const KR_FRESHNESS_LEDGER_REL: string;
-export declare const KR_FRESHNESS_LEDGER_SCHEMA = "kr-freshness-ledger.v1";
-export declare const KR_FRESHNESS_HISTORY_LIMIT = 50;
-export type KrFreshnessVerdict = "moving" | "flat" | "stalled";
-export interface KrFreshnessKpi {
-    name: string;
-    value: number | string;
-    entry_measured_at: string | null;
-    first_seen_at: string;
-    measured_at: string;
-    value_changed_at: string;
-    removed_at?: string;
-}
-export interface KrFreshnessLedger {
-    schema_version: typeof KR_FRESHNESS_LEDGER_SCHEMA;
-    lane_id: string;
-    updated_at: string;
-    kpis: Record<string, KrFreshnessKpi>;
-}
-export interface KrFreshnessView {
-    name: string;
-    value: number | string;
-    verdict: KrFreshnessVerdict;
-    measured_at: string;
-    value_changed_at: string;
-}
-export interface KrFreshnessResolution {
-    flagEnabled: boolean;
-    enabled: boolean;
-    target?: ManagerStatusTarget;
-    statusPath?: string;
-    windowHours: number;
-    kpis: KrFreshnessView[];
-    stalledKeys: string[];
-    error?: string;
-}
-export interface KrFreshnessResolutionOptions {
-    env?: NodeJS.ProcessEnv;
-    now?: number;
-    readFlag?: typeof readLanesRegistryFlag;
-    onError?: (error: unknown) => void;
-}
-export interface KrFreshnessStatusKpi {
-    key: string;
-    fullName: string;
-    name: string;
-    value: number | string;
-    entryMeasuredAt: string | null;
-}
-export declare function readKrFreshnessStatus(statusPath: string): KrFreshnessStatusKpi[];
-export declare function krFreshnessLedgerPath(root: string, laneId: string): string;
-export declare function readKrFreshnessLedger(root: string, laneId: string): KrFreshnessLedger | null;
-export declare function writeKrFreshnessLedger(root: string, ledger: KrFreshnessLedger): void;
-export declare function updateKrFreshnessLedger(laneId: string, prior: KrFreshnessLedger | null, statusKpis: readonly KrFreshnessStatusKpi[], now: number): KrFreshnessLedger;
-export declare function krFreshnessVerdict(kpi: Pick<KrFreshnessKpi, "measured_at" | "value_changed_at">, now: number, windowHours: number): KrFreshnessVerdict;
-export declare function krFreshnessFingerprint(keys: readonly string[]): string;
-/** Read the flag before manager mapping, status, configuration or ledger files. */
-export declare function resolveKrFreshnessForLane(root: string, lane: LaneRecord, options?: KrFreshnessResolutionOptions): Promise<KrFreshnessResolution>;
-/** Read a previously written ledger for `lanes show`; this never reads status. */
-export declare function resolveKrFreshnessForShow(root: string, lane: LaneRecord, options?: KrFreshnessResolutionOptions): Promise<{
-    enabled: true;
-    kpis: KrFreshnessView[];
-} | null>;
-/** Operator report path: the ledger remains readable while runtime enforcement is off. */
-export declare function readKrFreshnessReport(root: string, laneId: string, now: number): {
-    ledger_path: string;
-    available: boolean;
-    kr_freshness_hours: number;
-    kpis: KrFreshnessView[];
-};
-//# sourceMappingURL=kr-freshness.d.ts.map