@indigoai-us/hq-cli 5.125.0 → 5.126.0

package/dist/lib/lanes/index.js

@@ -0,0 +1,12 @@
+/**
+ * Library layer for `hq lanes`. The command module should import from here.
+ */
+export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
+export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";
+export { DEFAULT_ACCOUNT_HOMES, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, writeLanesConfig, } from "./config.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, updateLane, updateQuestion, } from "./store.js";
+export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
+export { AUTH_JSON_NAME, PROVIDER_HOME_ENV, accountEnv, accountStatus, authJsonPath, listAccountStatuses, resolveAccount, } from "./accounts.js";
+export { LIVE_WITHIN_MS, LIVENESS_EVENT_KINDS, SILENT_LOST_MS, TURN_START_LOST_MS, buildLivenessIndexFromSpool, classifySessionLiveness, defaultLivenessDeps, defaultSpoolPath, ingestSpoolLine, listSessionLiveness, livenessIndexPath, loadLivenessIndex, readLivenessIndex, rebuildLivenessIndex, sessionLiveness, } from "./liveness.js";
+export { WORKER_REGISTRY_REL, personalWorkerDir, personalWorkerExists, readWorkerRegistryFile, registryPath, resolveContextBasePaths, resolveLaneWorker, resolveSkillFiles, tenancyFromRegistryPath, } from "./registry.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,89 @@
+/**
+ * Session liveness from the work-mesh spool (spec §9).
+ *
+ * Source: ~/.hq/work-mesh/spool.jsonl, events session_start / turn_start /
+ * turn_end / session_end keyed by session id. Nothing latches, including
+ * `ended` — a later event for a reused id supersedes session_end.
+ *
+ * An index is a single compact file (workspace/lanes/sessions/index.json).
+ * This module never stats workspace/sessions/.
+ */
+import * as fs from "node:fs";
+import type { LivenessState, LivenessWindows } from "./types.js";
+export declare const LIVE_WITHIN_MS: number;
+export declare const TURN_START_LOST_MS: number;
+export declare const SILENT_LOST_MS: number;
+export declare const LIVENESS_EVENT_KINDS: readonly ["session_start", "turn_start", "turn_end", "session_end"];
+export type LivenessEventKind = (typeof LIVENESS_EVENT_KINDS)[number];
+export interface SessionIndexEntry {
+    sessionId: string;
+    lastKind: string;
+    lastAt: string;
+    lastSeq?: number;
+}
+export interface LivenessIndex {
+    schema_version: "hq-lane-liveness-index.v1";
+    built_at: string;
+    spool_path: string;
+    spool_bytes: number;
+    spool_mtime_ms: number;
+    sessions: Record<string, SessionIndexEntry>;
+}
+export interface LivenessDeps {
+    now: () => number;
+    homedir: () => string;
+    env: NodeJS.ProcessEnv;
+    readFileSync: (file: string, encoding: "utf8") => string;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    unlinkSync: typeof fs.unlinkSync;
+    existsSync: (file: string) => boolean;
+    mkdirSync: typeof fs.mkdirSync;
+    statSync: (file: string) => fs.Stats;
+}
+export declare function defaultLivenessDeps(): LivenessDeps;
+export declare function defaultSpoolPath(deps?: LivenessDeps): string;
+export declare function livenessIndexPath(hqRoot: string): string;
+/**
+ * Classify one session from its last spool event. `ended` is not latched:
+ * a later event for the same id is classified from that later event.
+ *
+ * Mid-turn (`turn_start` younger than 2h) stays `live` even after the 10
+ * minute recency window — spec §9's prose treats that as working, not idle.
+ * `session_end` as the last event is `ended` even when recent (fast path).
+ */
+export declare function classifySessionLiveness(entry: SessionIndexEntry, nowMs: number, presenceConnected?: boolean, windows?: LivenessWindows): LivenessState;
+export declare function ingestSpoolLine(line: string, sessions: Record<string, SessionIndexEntry>, lineNo: number): void;
+export declare function buildLivenessIndexFromSpool(spoolContents: string, meta: {
+    spool_path: string;
+    spool_bytes: number;
+    spool_mtime_ms: number;
+    built_at: string;
+}): LivenessIndex;
+export declare function rebuildLivenessIndex(hqRoot: string, spoolPath: string, deps?: LivenessDeps): LivenessIndex;
+export declare function readLivenessIndex(hqRoot: string, deps?: LivenessDeps): LivenessIndex | null;
+/**
+ * Return the compact index, rebuilding from the spool when missing or stale.
+ * Never walks workspace/sessions/.
+ */
+export declare function loadLivenessIndex(hqRoot: string, spoolPath?: string, deps?: LivenessDeps): LivenessIndex;
+export declare function sessionLiveness(hqRoot: string, sessionId: string, opts?: {
+    spoolPath?: string;
+    nowMs?: number;
+    presenceConnected?: boolean;
+    deps?: LivenessDeps;
+    windows?: LivenessWindows;
+}): LivenessState | null;
+export declare function listSessionLiveness(hqRoot: string, opts?: {
+    spoolPath?: string;
+    nowMs?: number;
+    presenceConnected?: boolean;
+    deps?: LivenessDeps;
+    windows?: LivenessWindows;
+}): Array<{
+    sessionId: string;
+    state: LivenessState;
+    lastKind: string;
+    lastAt: string;
+}>;
+//# sourceMappingURL=liveness.d.ts.map

package/dist/lib/lanes/liveness.js

@@ -0,0 +1,273 @@
+/**
+ * Session liveness from the work-mesh spool (spec §9).
+ *
+ * Source: ~/.hq/work-mesh/spool.jsonl, events session_start / turn_start /
+ * turn_end / session_end keyed by session id. Nothing latches, including
+ * `ended` — a later event for a reused id supersedes session_end.
+ *
+ * An index is a single compact file (workspace/lanes/sessions/index.json).
+ * This module never stats workspace/sessions/.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { workMeshSpoolPath, workMeshRoot } from "../mesh/live/paths.js";
+import { DEFAULT_LIVE_WITHIN_MS, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, loadLanesConfig, } from "./config.js";
+import { lanesStoreRoot } from "./store.js";
+export const LIVE_WITHIN_MS = DEFAULT_LIVE_WITHIN_MS;
+export const TURN_START_LOST_MS = DEFAULT_TURN_START_LOST_MS;
+export const SILENT_LOST_MS = DEFAULT_SILENT_LOST_MS;
+export const LIVENESS_EVENT_KINDS = [
+    "session_start",
+    "turn_start",
+    "turn_end",
+    "session_end",
+];
+export function defaultLivenessDeps() {
+    return {
+        now: () => Date.now(),
+        homedir: () => os.homedir(),
+        env: process.env,
+        readFileSync: (file, encoding) => fs.readFileSync(file, encoding),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+        existsSync: (file) => fs.existsSync(file),
+        mkdirSync: fs.mkdirSync.bind(fs),
+        statSync: (file) => fs.statSync(file),
+    };
+}
+export function defaultSpoolPath(deps = defaultLivenessDeps()) {
+    return workMeshSpoolPath(workMeshRoot(deps.homedir(), deps.env));
+}
+export function livenessIndexPath(hqRoot) {
+    return path.join(lanesStoreRoot(hqRoot), "sessions", "index.json");
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Classify one session from its last spool event. `ended` is not latched:
+ * a later event for the same id is classified from that later event.
+ *
+ * Mid-turn (`turn_start` younger than 2h) stays `live` even after the 10
+ * minute recency window — spec §9's prose treats that as working, not idle.
+ * `session_end` as the last event is `ended` even when recent (fast path).
+ */
+export function classifySessionLiveness(entry, nowMs, presenceConnected = false, windows = {
+    live_within_ms: LIVE_WITHIN_MS,
+    turn_start_lost_ms: TURN_START_LOST_MS,
+    silent_lost_ms: SILENT_LOST_MS,
+}) {
+    const at = Date.parse(entry.lastAt);
+    const age = Number.isFinite(at) ? nowMs - at : Number.POSITIVE_INFINITY;
+    const kind = entry.lastKind;
+    if (kind === "session_end")
+        return "ended";
+    if (presenceConnected)
+        return "live";
+    if (kind === "turn_start" && age < windows.turn_start_lost_ms)
+        return "live";
+    if (age <= windows.live_within_ms)
+        return "live";
+    if (kind === "turn_start" && age >= windows.turn_start_lost_ms)
+        return "lost";
+    if (age >= windows.silent_lost_ms)
+        return "lost";
+    if (kind === "turn_end")
+        return "idle";
+    return "idle";
+}
+export function ingestSpoolLine(line, sessions, lineNo) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: skipping malformed spool line ${lineNo}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return;
+    }
+    if (!isPlainObject(parsed))
+        return;
+    const sessionId = typeof parsed.sessionId === "string" ? parsed.sessionId : "";
+    const kind = typeof parsed.kind === "string" ? parsed.kind : "";
+    const at = typeof parsed.at === "string" ? parsed.at : "";
+    if (!sessionId || !kind || !at)
+        return;
+    if (!Number.isFinite(Date.parse(at))) {
+        process.stderr.write(`lanes liveness: skipping spool line ${lineNo} with unparseable at\n`);
+        return;
+    }
+    const existing = sessions[sessionId];
+    const seq = typeof parsed.seq === "number" ? parsed.seq : undefined;
+    if (existing) {
+        const existingAt = Date.parse(existing.lastAt);
+        const nextAt = Date.parse(at);
+        if (nextAt < existingAt)
+            return;
+        if (nextAt === existingAt &&
+            seq !== undefined &&
+            existing.lastSeq !== undefined &&
+            seq < existing.lastSeq) {
+            return;
+        }
+    }
+    const entry = { sessionId, lastKind: kind, lastAt: at };
+    if (seq !== undefined)
+        entry.lastSeq = seq;
+    sessions[sessionId] = entry;
+}
+export function buildLivenessIndexFromSpool(spoolContents, meta) {
+    const sessions = {};
+    const lines = spoolContents.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        ingestSpoolLine(lines[i] ?? "", sessions, i + 1);
+    }
+    return {
+        schema_version: "hq-lane-liveness-index.v1",
+        built_at: meta.built_at,
+        spool_path: meta.spool_path,
+        spool_bytes: meta.spool_bytes,
+        spool_mtime_ms: meta.spool_mtime_ms,
+        sessions,
+    };
+}
+function atomicWriteJson(target, value, deps) {
+    const dir = path.dirname(target);
+    deps.mkdirSync(dir, { recursive: true });
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        deps.writeFileSync(tmp, `${JSON.stringify(value)}\n`, { encoding: "utf8" });
+        deps.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes liveness: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+export function rebuildLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps()) {
+    let contents;
+    let st;
+    try {
+        st = deps.statSync(spoolPath);
+        contents = deps.readFileSync(spoolPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            const empty = {
+                schema_version: "hq-lane-liveness-index.v1",
+                built_at: new Date(deps.now()).toISOString(),
+                spool_path: spoolPath,
+                spool_bytes: 0,
+                spool_mtime_ms: 0,
+                sessions: {},
+            };
+            atomicWriteJson(livenessIndexPath(hqRoot), empty, deps);
+            return empty;
+        }
+        throw err;
+    }
+    const index = buildLivenessIndexFromSpool(contents, {
+        spool_path: spoolPath,
+        spool_bytes: st.size,
+        spool_mtime_ms: Math.floor(st.mtimeMs),
+        built_at: new Date(deps.now()).toISOString(),
+    });
+    atomicWriteJson(livenessIndexPath(hqRoot), index, deps);
+    return index;
+}
+export function readLivenessIndex(hqRoot, deps = defaultLivenessDeps()) {
+    const filePath = livenessIndexPath(hqRoot);
+    if (!deps.existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: failed to read index ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isPlainObject(parsed) || parsed.schema_version !== "hq-lane-liveness-index.v1") {
+            throw new Error(`unexpected liveness index schema in ${filePath}`);
+        }
+        if (!isPlainObject(parsed.sessions)) {
+            throw new Error(`liveness index sessions map missing in ${filePath}`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: invalid index ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+}
+/**
+ * Return the compact index, rebuilding from the spool when missing or stale.
+ * Never walks workspace/sessions/.
+ */
+export function loadLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps()) {
+    const spool = spoolPath ?? defaultSpoolPath(deps);
+    const existing = (() => {
+        try {
+            return readLivenessIndex(hqRoot, deps);
+        }
+        catch (err) {
+            process.stderr.write(`lanes liveness: rebuilding after invalid index: ${err instanceof Error ? err.message : String(err)}\n`);
+            return null;
+        }
+    })();
+    if (existing) {
+        try {
+            const st = deps.statSync(spool);
+            if (existing.spool_path === spool &&
+                existing.spool_bytes === st.size &&
+                existing.spool_mtime_ms === Math.floor(st.mtimeMs)) {
+                return existing;
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+            if (existing.spool_bytes === 0)
+                return existing;
+        }
+    }
+    return rebuildLivenessIndex(hqRoot, spool, deps);
+}
+export function sessionLiveness(hqRoot, sessionId, opts = {}) {
+    const deps = opts.deps ?? defaultLivenessDeps();
+    const index = loadLivenessIndex(hqRoot, opts.spoolPath, deps);
+    const entry = index.sessions[sessionId];
+    if (!entry)
+        return null;
+    const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
+    return classifySessionLiveness(entry, opts.nowMs ?? deps.now(), opts.presenceConnected ?? false, windows);
+}
+export function listSessionLiveness(hqRoot, opts = {}) {
+    const deps = opts.deps ?? defaultLivenessDeps();
+    const index = loadLivenessIndex(hqRoot, opts.spoolPath, deps);
+    const nowMs = opts.nowMs ?? deps.now();
+    const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
+    return Object.values(index.sessions).map((entry) => ({
+        sessionId: entry.sessionId,
+        state: classifySessionLiveness(entry, nowMs, opts.presenceConnected ?? false, windows),
+        lastKind: entry.lastKind,
+        lastAt: entry.lastAt,
+    }));
+}
+//# sourceMappingURL=liveness.js.map

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

@@ -0,0 +1,103 @@
+/**
+ * HQ worker resolution for lanes (spec §5.3).
+ *
+ * Tenancy derives from the registry entry's `path:` prefix, never from the
+ * optional `company:` field. A company path with a missing or contradictory
+ * `company:` is `worker_tenancy_unresolved`, never a global worker.
+ *
+ * The registry does not index personal/workers/ for this command. Naming a
+ * personal worker fails with a clear error and does not fall through to a
+ * same-named entry in another tree.
+ */
+import * as fs from "node:fs";
+export declare const WORKER_REGISTRY_REL: string;
+export interface RegistryWorkerEntry {
+    id: string;
+    path: string;
+    type: string;
+    visibility?: string;
+    company?: string;
+    team?: string;
+    status?: string;
+    description?: string;
+}
+export type WorkerTenancy = {
+    kind: "global";
+} | {
+    kind: "company";
+    slug: string;
+};
+export interface WorkerYamlSkill {
+    id?: string;
+    file: string;
+}
+export interface WorkerYaml {
+    worker?: {
+        id?: string;
+        name?: string;
+        description?: string;
+        type?: string;
+        company?: string;
+        status?: string;
+    };
+    instructions?: unknown;
+    skills?: WorkerYamlSkill[];
+    context?: {
+        base?: string[];
+    };
+    knowledge?: unknown;
+    verification?: {
+        approval_required?: boolean;
+        human_checkpoints?: unknown;
+    };
+    execution?: {
+        max_runtime?: unknown;
+        model?: unknown;
+        codex_model?: unknown;
+        codex_flags?: unknown;
+    };
+}
+export interface ResolvedLaneWorker {
+    id: string;
+    path: string;
+    type: string;
+    status: string;
+    visibility?: string;
+    description?: string;
+    tenancy: WorkerTenancy;
+    workerYaml: WorkerYaml;
+    workerDir: string;
+    resolvedContextBase: string[];
+    skillFiles: string[];
+    defaultTimeout: unknown;
+    approvalRequired: boolean;
+    humanCheckpoints: string[];
+}
+export interface RegistryDeps {
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string, encoding: "utf8") => string;
+    statSync: (p: string) => fs.Stats;
+}
+export declare function registryPath(hqRoot: string): string;
+export declare function personalWorkerDir(hqRoot: string, workerId: string): string;
+export declare function personalWorkerExists(hqRoot: string, workerId: string, deps?: RegistryDeps): boolean;
+export declare function readWorkerRegistryFile(hqRoot: string, deps?: RegistryDeps): RegistryWorkerEntry[];
+/**
+ * Tenancy from path, not from `company:`. A company path whose field is
+ * missing or disagrees is unresolved — never global.
+ */
+export declare function tenancyFromRegistryPath(entry: RegistryWorkerEntry): WorkerTenancy | {
+    kind: "unresolved";
+    pathSlug: string;
+    field?: string;
+} | {
+    kind: "personal";
+};
+/**
+ * Resolve context.base against HQ root, then core/, then the worker directory.
+ * Entries that resolve nowhere are dropped, not passed on.
+ */
+export declare function resolveContextBasePaths(hqRoot: string, workerDir: string, bases: string[] | undefined, deps?: RegistryDeps): string[];
+export declare function resolveSkillFiles(workerDir: string, skills: WorkerYamlSkill[] | undefined, deps?: RegistryDeps): string[];
+export declare function resolveLaneWorker(hqRoot: string, workerId: string, laneCompany: string | undefined, deps?: RegistryDeps): ResolvedLaneWorker;
+//# sourceMappingURL=registry.d.ts.map