@indigoai-us/hq-cli 5.124.0 → 5.126.0

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

package/dist/lib/lanes/registry.js

@@ -0,0 +1,247 @@
+/**
+ * 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";
+import * as path from "node:path";
+import { parseUserYaml } from "../../utils/user-yaml-error.js";
+import { WorkerResolutionError } from "./errors.js";
+export const WORKER_REGISTRY_REL = path.join("core", "workers", "registry.yaml");
+function defaultRegistryDeps() {
+    return {
+        existsSync: (p) => fs.existsSync(p),
+        readFileSync: (p, encoding) => fs.readFileSync(p, encoding),
+        statSync: (p) => fs.statSync(p),
+    };
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function registryPath(hqRoot) {
+    return path.join(hqRoot, WORKER_REGISTRY_REL);
+}
+export function personalWorkerDir(hqRoot, workerId) {
+    return path.join(hqRoot, "personal", "workers", workerId);
+}
+function isExistingPath(p, deps) {
+    try {
+        const st = deps.statSync(p);
+        return st.isFile() || st.isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function personalWorkerExists(hqRoot, workerId, deps = defaultRegistryDeps()) {
+    const yamlPath = path.join(personalWorkerDir(hqRoot, workerId), "worker.yaml");
+    try {
+        return deps.statSync(yamlPath).isFile();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function readWorkerRegistryFile(hqRoot, deps = defaultRegistryDeps()) {
+    const filePath = registryPath(hqRoot);
+    if (!deps.existsSync(filePath)) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Worker registry missing at ${filePath}`, { path: filePath });
+    }
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    const doc = parseUserYaml(text, filePath);
+    const workers = doc?.workers;
+    if (!Array.isArray(workers)) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Worker registry workers key is missing or not an array at ${filePath}`, { path: filePath });
+    }
+    const entries = [];
+    for (let i = 0; i < workers.length; i += 1) {
+        const item = workers[i];
+        if (!isPlainObject(item)) {
+            process.stderr.write(`lanes registry: skipping malformed worker entry in ${filePath} at index ${i}: not an object (type=${typeof item})\n`);
+            continue;
+        }
+        if (typeof item.id !== "string" ||
+            item.id.length === 0 ||
+            typeof item.path !== "string" ||
+            item.path.length === 0) {
+            process.stderr.write(`lanes registry: skipping malformed worker entry in ${filePath} at index ${i}: missing id or path (id=${JSON.stringify(item.id)} path=${JSON.stringify(item.path)})\n`);
+            continue;
+        }
+        entries.push({
+            id: item.id,
+            path: item.path,
+            type: typeof item.type === "string" ? item.type : "",
+            visibility: typeof item.visibility === "string" ? item.visibility : undefined,
+            company: typeof item.company === "string" ? item.company : undefined,
+            team: typeof item.team === "string" ? item.team : undefined,
+            status: typeof item.status === "string" ? item.status : undefined,
+            description: typeof item.description === "string" ? item.description : undefined,
+        });
+    }
+    return entries;
+}
+const COMPANY_PATH = /^companies\/([^/]+)\//;
+const PERSONAL_PATH = /^(?:personal\/workers\/)/;
+const CORE_PATH = /^(?:core\/workers\/)/;
+/**
+ * Tenancy from path, not from `company:`. A company path whose field is
+ * missing or disagrees is unresolved — never global.
+ */
+export function tenancyFromRegistryPath(entry) {
+    const normalized = entry.path.replaceAll("\\", "/");
+    if (PERSONAL_PATH.test(normalized)) {
+        return { kind: "personal" };
+    }
+    const companyMatch = COMPANY_PATH.exec(normalized);
+    if (companyMatch) {
+        const pathSlug = companyMatch[1] ?? "";
+        if (!pathSlug) {
+            return { kind: "unresolved", pathSlug, field: entry.company };
+        }
+        const field = entry.company?.trim() ?? "";
+        if (!field || field !== pathSlug) {
+            return { kind: "unresolved", pathSlug, field: field || undefined };
+        }
+        return { kind: "company", slug: pathSlug };
+    }
+    if (CORE_PATH.test(normalized) || normalized.startsWith("core/")) {
+        return { kind: "global" };
+    }
+    // Unknown tree: do not treat as global.
+    return { kind: "unresolved", pathSlug: "", field: entry.company };
+}
+function loadWorkerYaml(hqRoot, relativeDir, deps) {
+    const dir = path.join(hqRoot, relativeDir);
+    const filePath = path.join(dir, "worker.yaml");
+    if (!deps.existsSync(filePath)) {
+        throw new WorkerResolutionError("worker_not_found", `worker.yaml missing at ${filePath}`, { path: filePath });
+    }
+    const text = deps.readFileSync(filePath, "utf8");
+    const doc = parseUserYaml(text, filePath);
+    if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+        return {};
+    }
+    return doc;
+}
+/**
+ * Resolve context.base against HQ root, then core/, then the worker directory.
+ * Entries that resolve nowhere are dropped, not passed on.
+ */
+export function resolveContextBasePaths(hqRoot, workerDir, bases, deps = defaultRegistryDeps()) {
+    if (!bases || bases.length === 0)
+        return [];
+    const resolved = [];
+    for (const entry of bases) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        const candidates = [
+            path.isAbsolute(entry) ? entry : path.join(hqRoot, entry),
+            path.join(hqRoot, "core", entry),
+            path.join(workerDir, entry),
+        ];
+        const hit = candidates.find((candidate) => isExistingPath(candidate, deps));
+        if (hit)
+            resolved.push(hit);
+    }
+    return resolved;
+}
+export function resolveSkillFiles(workerDir, skills, deps = defaultRegistryDeps()) {
+    if (!skills)
+        return [];
+    const files = [];
+    for (const skill of skills) {
+        if (!skill || typeof skill.file !== "string" || skill.file.length === 0) {
+            continue;
+        }
+        const candidate = path.isAbsolute(skill.file)
+            ? skill.file
+            : path.join(workerDir, skill.file);
+        if (isExistingPath(candidate, deps))
+            files.push(candidate);
+    }
+    return files;
+}
+function humanCheckpointsOf(yaml) {
+    const raw = yaml.verification?.human_checkpoints;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((item) => typeof item === "string");
+}
+export function resolveLaneWorker(hqRoot, workerId, laneCompany, deps = defaultRegistryDeps()) {
+    if (personalWorkerExists(hqRoot, workerId, deps)) {
+        throw new WorkerResolutionError("personal_worker_unindexed", `Worker ${JSON.stringify(workerId)} lives under personal/workers/ which the registry does not index; --worker cannot resolve personal workers`, {
+            worker: workerId,
+            path: path.join("personal", "workers", workerId).replaceAll("\\", "/"),
+        });
+    }
+    const entries = readWorkerRegistryFile(hqRoot, deps);
+    const entry = entries.find((item) => item.id === workerId);
+    if (!entry) {
+        throw new WorkerResolutionError("worker_not_found", `Worker ${JSON.stringify(workerId)} is not in core/workers/registry.yaml`, { worker: workerId });
+    }
+    const tenancy = tenancyFromRegistryPath(entry);
+    if (tenancy.kind === "personal") {
+        throw new WorkerResolutionError("personal_worker_unindexed", `Worker ${JSON.stringify(workerId)} is registered under personal/workers/ which lanes do not admit`, { worker: workerId, path: entry.path });
+    }
+    if (tenancy.kind === "unresolved") {
+        throw new WorkerResolutionError("worker_tenancy_unresolved", `Worker ${JSON.stringify(workerId)} has a company path whose company field is missing or contradicts the path`, {
+            worker: workerId,
+            path: entry.path,
+            path_slug: tenancy.pathSlug,
+            company_field: tenancy.field ?? null,
+        });
+    }
+    if (tenancy.kind === "company") {
+        if (!laneCompany || laneCompany !== tenancy.slug) {
+            throw new WorkerResolutionError("worker_not_available", `Worker ${JSON.stringify(workerId)} belongs to company ${tenancy.slug} and is not available to ${laneCompany ?? "(none)"}`, {
+                worker: workerId,
+                worker_company: tenancy.slug,
+                lane_company: laneCompany ?? null,
+            });
+        }
+    }
+    const status = entry.status && entry.status.length > 0 ? entry.status : "active";
+    if (status !== "active") {
+        throw new WorkerResolutionError("worker_not_active", `Worker ${JSON.stringify(workerId)} has status ${JSON.stringify(status)} (need active)`, { worker: workerId, status });
+    }
+    const relativeDir = entry.path.replace(/\/+$/, "");
+    const workerDir = path.join(hqRoot, relativeDir);
+    const workerYaml = loadWorkerYaml(hqRoot, relativeDir, deps);
+    const resolvedContextBase = resolveContextBasePaths(hqRoot, workerDir, workerYaml.context?.base, deps);
+    const skillFiles = resolveSkillFiles(workerDir, workerYaml.skills, deps);
+    return {
+        id: entry.id,
+        path: entry.path,
+        type: entry.type,
+        status,
+        visibility: entry.visibility,
+        description: entry.description,
+        tenancy,
+        workerYaml,
+        workerDir,
+        resolvedContextBase,
+        skillFiles,
+        defaultTimeout: workerYaml.execution?.max_runtime,
+        approvalRequired: workerYaml.verification?.approval_required === true,
+        humanCheckpoints: humanCheckpointsOf(workerYaml),
+    };
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,64 @@
+/**
+ * File-backed lane / question record store (spec §10, §10.1).
+ *
+ * Root: workspace/lanes/ under the HQ root. One stable path per record;
+ * `status` is the pending/answered discriminator — files are never moved
+ * between directories. Every mutation is temp-file-plus-rename and a
+ * compare-and-set on `version`. Histories are capped at 50 at the append site.
+ */
+import * as fs from "node:fs";
+import { type AttributionHistoryEntry, type LaneRecord, type QuestionRecord, type RoutingHistoryEntry, type SeniorHistoryEntry } from "./types.js";
+export declare const LANES_STORE_REL: string;
+export declare const LANE_RECORDS_DIR = "lanes";
+export declare const QUESTION_RECORDS_DIR = "questions";
+export declare const PENDING_INDEX_DIR: string;
+export interface StoreDeps {
+    now: () => Date;
+    hostname: () => string;
+    mkdirSync: typeof fs.mkdirSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    unlinkSync: typeof fs.unlinkSync;
+    existsSync: typeof fs.existsSync;
+    readdirSync: typeof fs.readdirSync;
+    openSync: typeof fs.openSync;
+    closeSync: typeof fs.closeSync;
+    fsyncSync: typeof fs.fsyncSync;
+    chmodSync: typeof fs.chmodSync;
+}
+export declare function resolveStoreHqRoot(hqRoot?: string): string;
+export declare function lanesStoreRoot(hqRoot?: string): string;
+export declare function laneRecordPath(hqRoot: string, laneId: string): string;
+export declare function questionRecordPath(hqRoot: string, questionId: string): string;
+export declare function pendingMarkerPath(hqRoot: string, questionId: string): string;
+export declare function sanitizeHostComponent(hostname: string): string;
+/** Collision-safe across machines: ULID plus a host component. */
+export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
+export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
+/**
+ * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:
+ * `<file>.json.conflict-<ISO-with-dashes>-<machine>.json`
+ * (legacy twins; current engines park losers under `.hq/conflict-backups/`,
+ * but merge-on-read still has to recover the ones already on disk).
+ */
+export declare function isConflictSidecarName(recordBasename: string, name: string): boolean;
+export declare function mergeLaneRecords(live: LaneRecord, sidecars: readonly LaneRecord[]): LaneRecord;
+export declare function mergeQuestionRecords(live: QuestionRecord, sidecars: readonly QuestionRecord[]): QuestionRecord;
+export declare function tryReadLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord | null;
+export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
+export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
+export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
+export declare function createLane(hqRoot: string, init: Omit<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at"> & Partial<Pick<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at">>, deps?: StoreDeps): LaneRecord;
+export declare function updateLane(hqRoot: string, laneId: string, expectedVersion: number, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps): LaneRecord;
+export declare function appendLaneSeniorHistory(hqRoot: string, laneId: string, expectedVersion: number, entry: SeniorHistoryEntry, deps?: StoreDeps): LaneRecord;
+export declare function appendLaneAttribution(hqRoot: string, laneId: string, expectedVersion: number, entry: AttributionHistoryEntry, deps?: StoreDeps): LaneRecord;
+export declare function createQuestion(hqRoot: string, init: Omit<QuestionRecord, "schema_version" | "question_id" | "version"> & Partial<Pick<QuestionRecord, "schema_version" | "question_id" | "version">>, deps?: StoreDeps): QuestionRecord;
+export declare function updateQuestion(hqRoot: string, questionId: string, expectedVersion: number, updater: (current: QuestionRecord) => QuestionRecord, deps?: StoreDeps): QuestionRecord;
+export declare function appendQuestionRouting(hqRoot: string, questionId: string, expectedVersion: number, entry: RoutingHistoryEntry, deps?: StoreDeps): QuestionRecord;
+export declare function listLaneIds(hqRoot: string, deps?: StoreDeps): string[];
+export declare function listQuestionIds(hqRoot: string, deps?: StoreDeps): string[];
+//# sourceMappingURL=store.d.ts.map