@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,35 @@
+import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
+import type { LaneCompanyRef } from "./types.js";
+export declare const LANES_FLAG_API_DEFAULT_ENDPOINT = "https://hqapi.hq.computer";
+export declare const LANES_FLAG_READ_TIMEOUT_MS = 5000;
+export interface LanesFlagClient {
+    ready(): Promise<void>;
+    explain(flagKey: string, options?: {
+        fallback?: boolean;
+    }): FlagResolution;
+    close(): void;
+}
+export type LanesFlagClientFactory = (options: FlagClientOptions) => LanesFlagClient;
+export interface ReadLanesFlagOptions {
+    company?: LaneCompanyRef | null;
+    companyUidSource?: string;
+    env?: NodeJS.ProcessEnv;
+    createClient?: LanesFlagClientFactory;
+    getToken?: () => string | Promise<string>;
+    reportFailure?: (error: unknown) => void;
+}
+export declare function readLanesFlagLocalOverride(flagKey: string, env?: NodeJS.ProcessEnv): boolean | null;
+/**
+ * Read a lanes flag once for each company identity in this CLI process. The
+ * cache contains only an in-flight or settled boolean promise; it is never
+ * written to disk. A local override is checked on every call and wins first.
+ */
+export declare function readLanesRegistryFlag(flagKey: string, options?: ReadLanesFlagOptions): Promise<boolean>;
+/**
+ * Flag readers normally report their own failures and return the safe default.
+ * Keep enforcement callers safe if an injected or unexpected reader rejects.
+ */
+export declare function readLanesRegistryFlagFailOff(flagKey: string, options?: ReadLanesFlagOptions, reader?: typeof readLanesRegistryFlag): Promise<boolean>;
+export declare function _resetThrownFlagReadWarningsForTests(): void;
+export declare function _resetLanesRegistryFlagCacheForTests(): void;
+//# sourceMappingURL=registry-flag.d.ts.map

package/dist/lib/lanes/registry-flag.js

@@ -0,0 +1,164 @@
+import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import { FLAG_REGISTRY_DEFAULT_ENDPOINT, resolveFlagRegistryEndpoint, } from "../flag-registry-endpoint.js";
+export const LANES_FLAG_API_DEFAULT_ENDPOINT = FLAG_REGISTRY_DEFAULT_ENDPOINT;
+export const LANES_FLAG_READ_TIMEOUT_MS = 5_000;
+export function readLanesFlagLocalOverride(flagKey, env = process.env) {
+    return readLocalOverride(flagKey, env);
+}
+const registryReads = new Map();
+const reportedThrownFlagReads = new Set();
+class MissingFlagTokenError extends Error {
+    constructor() {
+        super("No cached HQ identity token is available");
+        this.name = "MissingFlagTokenError";
+    }
+}
+function errorClass(error) {
+    return error instanceof Error ? error.name : "UnknownError";
+}
+function reportReadFailure(flagKey, error) {
+    const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
+    process.stderr.write(`${JSON.stringify({
+        event: `lanes.${suffix}.flag_read_failed`,
+        flag: flagKey,
+        error: errorClass(error),
+        fallback: false,
+    })}\n`);
+}
+function reportInvalidCompanyUid(flagKey, source) {
+    const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
+    process.stderr.write(`${JSON.stringify({
+        event: `lanes.${suffix}.invalid_company_uid`,
+        flag: flagKey,
+        source,
+        expected_prefix: "cmp_",
+        fallback: false,
+    })}\n`);
+}
+function cacheKey(flagKey, company, endpoint) {
+    return JSON.stringify([
+        flagKey,
+        endpoint,
+        company?.uid ?? null,
+        company?.slug ?? null,
+    ]);
+}
+/**
+ * Read a lanes flag once for each company identity in this CLI process. The
+ * cache contains only an in-flight or settled boolean promise; it is never
+ * written to disk. A local override is checked on every call and wins first.
+ */
+export async function readLanesRegistryFlag(flagKey, options = {}) {
+    const env = options.env ?? process.env;
+    const localOverride = readLanesFlagLocalOverride(flagKey, env);
+    if (localOverride !== null)
+        return localOverride;
+    const companyUid = options.company?.uid?.trim();
+    if (companyUid && !companyUid.startsWith("cmp_")) {
+        reportInvalidCompanyUid(flagKey, options.companyUidSource ?? "company.uid");
+        return false;
+    }
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const key = cacheKey(flagKey, options.company, endpoint);
+    const cached = registryReads.get(key);
+    if (cached)
+        return cached;
+    const pending = readRegistryValue(flagKey, endpoint, options);
+    registryReads.set(key, pending);
+    return pending;
+}
+/**
+ * Flag readers normally report their own failures and return the safe default.
+ * Keep enforcement callers safe if an injected or unexpected reader rejects.
+ */
+export async function readLanesRegistryFlagFailOff(flagKey, options = {}, reader = readLanesRegistryFlag) {
+    try {
+        return await reader(flagKey, options);
+    }
+    catch (error) {
+        if (!reportedThrownFlagReads.has(flagKey)) {
+            reportedThrownFlagReads.add(flagKey);
+            process.stderr.write(`${JSON.stringify({
+                event: "lanes.flag_read_threw",
+                flag: flagKey,
+                error: error instanceof Error ? "Error" : "NonError",
+                fallback: false,
+            })}\n`);
+        }
+        return false;
+    }
+}
+export function _resetThrownFlagReadWarningsForTests() {
+    reportedThrownFlagReads.clear();
+}
+async function readRegistryValue(flagKey, endpoint, options) {
+    const company = options.company;
+    const companyUid = company?.uid?.trim();
+    const companySlug = company?.slug?.trim();
+    let client;
+    let enabled = false;
+    let failed = false;
+    let reported = false;
+    const reportFailure = (error) => {
+        failed = true;
+        if (reported)
+            return;
+        reported = true;
+        (options.reportFailure ?? ((cause) => reportReadFailure(flagKey, cause)))(error);
+    };
+    try {
+        const acquireToken = options.getToken ?? (async () => {
+            try {
+                return await ensureCognitoIdToken({ interactive: false });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.startsWith("No valid HQ session")) {
+                    throw new MissingFlagTokenError();
+                }
+                throw error;
+            }
+        });
+        const getToken = async () => {
+            const token = await acquireToken();
+            if (typeof token !== "string" || token.trim().length === 0) {
+                throw new MissingFlagTokenError();
+            }
+            return token;
+        };
+        client = (options.createClient ?? createFlagClient)({
+            endpoint,
+            getToken,
+            env: {},
+            refreshIntervalMs: 0,
+            requestTimeoutMs: LANES_FLAG_READ_TIMEOUT_MS,
+            ...(companyUid ? { companyUid } : {}),
+            ...(companySlug ? { companyIdentifiers: [companySlug] } : {}),
+            onError: reportFailure,
+        });
+        await client.ready();
+        const resolution = client.explain(flagKey, { fallback: false });
+        if (failed)
+            return false;
+        if (resolution.source === "snapshot" || resolution.source === "local-override") {
+            enabled = resolution.value;
+        }
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailure(error);
+        }
+    }
+    return failed ? false : enabled;
+}
+export function _resetLanesRegistryFlagCacheForTests() {
+    registryReads.clear();
+}
+//# sourceMappingURL=registry-flag.js.map

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

@@ -0,0 +1,20 @@
+import type { RegistryWorkerRecord } from "./types.js";
+export interface RegistryPersona {
+    id: string;
+    /** Registry-relative worker directory. Kept for stable resume resolution. */
+    path: string;
+    workerYamlSha256: string;
+    description: string;
+    instructions: string;
+    /** Skill files are path references only. Their contents are never inlined. */
+    skillFiles: string[];
+    postExecute: string[];
+    approvalRequired: boolean;
+    humanCheckpoints: string[];
+}
+/** Resolve an active registry worker for a lane without company fallback. */
+export declare function resolveRegistryPersona(hqRoot: string, id: string, laneCompany: string | undefined): RegistryPersona;
+/** Re-read the recorded path on resume; registry changes cannot redirect a lane. */
+export declare function loadRegistryPersonaFromRecord(hqRoot: string, record: RegistryWorkerRecord): RegistryPersona;
+export declare function registryWorkerRecord(persona: RegistryPersona): RegistryWorkerRecord;
+//# sourceMappingURL=registry-persona.d.ts.map

package/dist/lib/lanes/registry-persona.js

@@ -0,0 +1,329 @@
+import { createHash } from "node:crypto";
+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";
+const REGISTRY_RELATIVE_PATH = path.join("core", "workers", "registry.yaml");
+function fail(code, message, details = {}) {
+    throw new WorkerResolutionError(code, message, details);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function withinRoot(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+function resolveWorkerDirectory(hqRoot, workerPath, id) {
+    const relative = workerPath.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (relative.length === 0 ||
+        path.posix.isAbsolute(relative) ||
+        relative.split("/").some((part) => part === ".." || part === ".")) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} has an unsafe path`, {
+            worker: id,
+            path: workerPath,
+        });
+    }
+    const root = path.resolve(hqRoot);
+    const abs = path.resolve(root, ...relative.split("/"));
+    if (!withinRoot(root, abs)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} escapes HQ_ROOT`, {
+            worker: id,
+            path: workerPath,
+        });
+    }
+    let realRoot;
+    let realWorkerDir;
+    try {
+        realRoot = fs.realpathSync(root);
+        realWorkerDir = fs.realpathSync(abs);
+    }
+    catch (err) {
+        fail("registry_worker_unreadable", `Cannot resolve registry worker ${JSON.stringify(id)} at ${abs}: ${err instanceof Error ? err.message : String(err)}`, {
+            worker: id,
+            path: abs,
+        });
+    }
+    if (!withinRoot(realRoot, realWorkerDir)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} resolves outside HQ_ROOT`, {
+            worker: id,
+            path: workerPath,
+        });
+    }
+    return { abs: realWorkerDir, relative };
+}
+function readWorkerYaml(hqRoot, workerPath, id) {
+    const directory = resolveWorkerDirectory(hqRoot, workerPath, id);
+    const filePath = path.join(directory.abs, "worker.yaml");
+    let stat;
+    let text;
+    try {
+        stat = fs.lstatSync(filePath);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} worker.yaml must be a regular file`, {
+                worker: id,
+                path: filePath,
+            });
+        }
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        if (err instanceof WorkerResolutionError)
+            throw err;
+        fail("registry_worker_unreadable", `Cannot read registry worker ${JSON.stringify(id)} at ${filePath}: ${err instanceof Error ? err.message : String(err)}`, {
+            worker: id,
+            path: filePath,
+        });
+    }
+    let parsed;
+    try {
+        parsed = parseUserYaml(text, filePath);
+    }
+    catch (err) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} has invalid worker.yaml at ${filePath}: ${err instanceof Error ? err.message : String(err)}`, {
+            worker: id,
+            path: filePath,
+        });
+    }
+    if (!isPlainObject(parsed)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} worker.yaml must contain an object`, {
+            worker: id,
+            path: filePath,
+        });
+    }
+    const realFile = fs.realpathSync(filePath);
+    const realRoot = fs.realpathSync(path.resolve(hqRoot));
+    if (!withinRoot(realRoot, realFile)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} worker.yaml resolves outside HQ_ROOT`, {
+            worker: id,
+            path: filePath,
+        });
+    }
+    return {
+        filePath,
+        text,
+        yaml: parsed,
+        sha256: `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`,
+    };
+}
+function textValue(value, field, id) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value.trim();
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return value.map((item) => item.trim()).filter(Boolean).join("\n");
+    }
+    fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} ${field} must be a string or string array`, {
+        worker: id,
+        field,
+    });
+}
+function stringList(value, field, id) {
+    if (value === undefined || value === null)
+        return [];
+    const values = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || item.trim().length === 0)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} ${field} must be an array of non-empty strings`, {
+            worker: id,
+            field,
+        });
+    }
+    const cleaned = values.map((item) => item.trim());
+    if (new Set(cleaned).size !== cleaned.length) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} ${field} must not contain duplicates`, {
+            worker: id,
+            field,
+        });
+    }
+    return cleaned;
+}
+function verificationCommands(value, id) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} verification.post_execute must be an array`, {
+            worker: id,
+            field: "verification.post_execute",
+        });
+    }
+    const commands = value.map((entry, index) => {
+        if (typeof entry === "string" && entry.trim() !== "")
+            return entry.trim();
+        if (isPlainObject(entry) && typeof entry.command === "string" && entry.command.trim() !== "") {
+            return entry.command.trim();
+        }
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} verification.post_execute[${index}] must contain a non-empty command`, {
+            worker: id,
+            field: `verification.post_execute[${index}]`,
+        });
+    });
+    if (new Set(commands).size !== commands.length) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} verification.post_execute must not contain duplicate commands`, {
+            worker: id,
+            field: "verification.post_execute",
+        });
+    }
+    return commands;
+}
+function personaFromYaml(hqRoot, id, workerPath, yaml, sha256, registryDescription, pinnedApproval) {
+    if (yaml.worker?.id !== undefined && yaml.worker.id !== id) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} worker.yaml declares a different id`, {
+            worker: id,
+            declared_id: yaml.worker.id,
+        });
+    }
+    const workerDir = resolveWorkerDirectory(hqRoot, workerPath, id).abs;
+    const description = textValue(yaml.worker?.description ?? yaml.description ?? registryDescription, "description", id) || id;
+    const instructions = textValue(yaml.instructions, "instructions", id);
+    const skillFiles = [];
+    if (yaml.skills !== undefined) {
+        if (!Array.isArray(yaml.skills)) {
+            fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} skills must be an array`, {
+                worker: id,
+                field: "skills",
+            });
+        }
+        for (const [index, skill] of yaml.skills.entries()) {
+            if (!isPlainObject(skill) || typeof skill.file !== "string" || skill.file.trim().length === 0) {
+                fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} skills[${index}].file must be a non-empty string`, {
+                    worker: id,
+                    field: `skills[${index}].file`,
+                });
+            }
+            skillFiles.push(path.resolve(workerDir, skill.file.trim()));
+        }
+    }
+    let verification = {};
+    if (yaml.verification !== undefined) {
+        if (!isPlainObject(yaml.verification)) {
+            fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} verification must be an object`, {
+                worker: id,
+                field: "verification",
+            });
+        }
+        verification = yaml.verification;
+    }
+    if (verification.approval_required !== undefined && typeof verification.approval_required !== "boolean") {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(id)} verification.approval_required must be a boolean`, {
+            worker: id,
+            field: "verification.approval_required",
+        });
+    }
+    const humanCheckpoints = pinnedApproval?.human_checkpoints ??
+        stringList(verification.human_checkpoints, "verification.human_checkpoints", id);
+    return {
+        id,
+        path: workerPath,
+        workerYamlSha256: sha256,
+        description,
+        instructions,
+        skillFiles,
+        postExecute: verificationCommands(verification.post_execute, id),
+        approvalRequired: pinnedApproval?.approval_required ?? verification.approval_required === true,
+        humanCheckpoints: [...humanCheckpoints],
+    };
+}
+function registryEntries(hqRoot) {
+    const registryPath = path.join(hqRoot, REGISTRY_RELATIVE_PATH);
+    let text;
+    try {
+        text = fs.readFileSync(registryPath, "utf8");
+    }
+    catch (err) {
+        fail("registry_worker_unreadable", `Cannot read worker registry at ${registryPath}: ${err instanceof Error ? err.message : String(err)}`, {
+            path: registryPath,
+        });
+    }
+    let parsed;
+    try {
+        parsed = parseUserYaml(text, registryPath);
+    }
+    catch (err) {
+        fail("registry_worker_unreadable", `Cannot parse worker registry at ${registryPath}: ${err instanceof Error ? err.message : String(err)}`, {
+            path: registryPath,
+        });
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.workers)) {
+        fail("registry_worker_unreadable", `Worker registry at ${registryPath} must contain a workers array`, {
+            path: registryPath,
+        });
+    }
+    return parsed.workers.filter(isPlainObject);
+}
+/** Resolve an active registry worker for a lane without company fallback. */
+export function resolveRegistryPersona(hqRoot, id, laneCompany) {
+    const workerId = id.trim();
+    if (!workerId) {
+        fail("registry_worker_invalid", "registry_worker must be a non-empty worker id", { worker: id });
+    }
+    const candidates = registryEntries(hqRoot).filter((entry) => entry.id === workerId);
+    if (candidates.length === 0) {
+        fail("registry_worker_not_found", `Registry worker ${JSON.stringify(workerId)} was not found`, {
+            worker: workerId,
+            path: path.join(hqRoot, REGISTRY_RELATIVE_PATH),
+        });
+    }
+    if (candidates.length > 1) {
+        fail("registry_worker_ambiguous", `Registry worker ${JSON.stringify(workerId)} appears more than once`, {
+            worker: workerId,
+            paths: candidates.map((entry) => entry.path),
+        });
+    }
+    const entry = candidates[0];
+    if (typeof entry.path !== "string" || entry.path.trim().length === 0) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(workerId)} has no path`, {
+            worker: workerId,
+        });
+    }
+    if (entry.company !== undefined && typeof entry.company !== "string") {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(workerId)} company must be a string`, {
+            worker: workerId,
+        });
+    }
+    if (typeof entry.company === "string" && entry.company.trim().length === 0) {
+        fail("registry_worker_invalid", `Registry worker ${JSON.stringify(workerId)} company must be non-empty when supplied`, {
+            worker: workerId,
+        });
+    }
+    const workerCompany = typeof entry.company === "string" && entry.company.trim().length > 0
+        ? entry.company.trim()
+        : undefined;
+    if (workerCompany !== undefined && workerCompany !== laneCompany) {
+        fail("registry_worker_company_mismatch", `Registry worker ${JSON.stringify(workerId)} belongs to company ${workerCompany} and is not available to ${laneCompany ?? "(none)"}`, {
+            worker: workerId,
+            worker_company: workerCompany,
+            lane_company: laneCompany ?? null,
+        });
+    }
+    const status = typeof entry.status === "string" && entry.status.trim() !== ""
+        ? entry.status.trim()
+        : "active";
+    if (status !== "active") {
+        fail("registry_worker_inactive", `Registry worker ${JSON.stringify(workerId)} has status ${JSON.stringify(status)} (need active)`, {
+            worker: workerId,
+            status,
+        });
+    }
+    const worker = readWorkerYaml(hqRoot, entry.path.trim(), workerId);
+    const persona = personaFromYaml(hqRoot, workerId, entry.path.trim(), worker.yaml, worker.sha256, entry.description);
+    return persona;
+}
+/** Re-read the recorded path on resume; registry changes cannot redirect a lane. */
+export function loadRegistryPersonaFromRecord(hqRoot, record) {
+    const worker = readWorkerYaml(hqRoot, record.path, record.id);
+    return personaFromYaml(hqRoot, record.id, record.path, worker.yaml, worker.sha256, undefined, {
+        approval_required: record.approval_required,
+        human_checkpoints: record.human_checkpoints,
+    });
+}
+export function registryWorkerRecord(persona) {
+    return {
+        id: persona.id,
+        path: persona.path,
+        worker_yaml_sha256: persona.workerYamlSha256,
+        approval_required: persona.approvalRequired,
+        human_checkpoints: [...persona.humanCheckpoints],
+    };
+}
+//# sourceMappingURL=registry-persona.js.map

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

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ *
+ * Personal workers are indexed by the registry generator when they have a
+ * worker.yaml. A personal directory that exists without one fails by name
+ * and does not fall through to a same-named entry in another tree.
+ *
+ * Package workers are not a fourth generator scan root. `hq core
+ * scan-packages` mounts a declared `contributes.workers` entry into
+ * `core/workers/public/<item>` (a symlink; origin/main writes that link
+ * relative to the host directory, this branch still writes it absolute).
+ * The generator then indexes the mount, and `packAttribution` keeps
+ * recognising it by realpath. Scanning `core/packages` as well would
+ * double-register that mount. A pack that declares a worker whose symlink
+ * is missing fails with `package_workers_unmounted` instead of resolving
+ * some other tree's copy. Tenancy for a mount follows the package: global
+ * when package.yaml has no company and access is public (or omitted),
+ * company-owned when package.yaml names `company`, and
+ * `worker_tenancy_unresolved` when that cannot be determined.
+ */
+import * as fs from "node:fs";
+import { type WorkerProfile } from "./profile.js";
+import type { RegistryWorkerRecord } from "./types.js";
+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[];
+    /** Set when the worker's realpath lives in a package. */
+    pack?: string;
+    /** Set when this worker was resolved from personal/workers/<id>/meta.yaml. */
+    profile?: WorkerProfile;
+}
+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;
+};
+/**
+ * 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, options?: {
+    registryWorkerRecord?: RegistryWorkerRecord;
+}): ResolvedLaneWorker;
+//# sourceMappingURL=registry.d.ts.map