@indigoai-us/hq-cli 5.239.0 → 5.240.0

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

@@ -24,6 +24,7 @@
  */
 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;
@@ -115,5 +116,7 @@ export declare function tenancyFromRegistryPath(entry: RegistryWorkerEntry): Wor
  */
 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;
+export declare function resolveLaneWorker(hqRoot: string, workerId: string, laneCompany: string | undefined, deps?: RegistryDeps, options?: {
+    registryWorkerRecord?: RegistryWorkerRecord;
+}): ResolvedLaneWorker;
 //# sourceMappingURL=registry.d.ts.map

package/dist/lib/lanes/registry.js

@@ -28,7 +28,7 @@ import { parseUserYaml } from "../../utils/user-yaml-error.js";
 import { readContributes } from "../scan-packages/index.js";
 import { contributionLinks, linkStatus, } from "../../utils/pack-contributions.js";
 import { WorkerResolutionError } from "./errors.js";
-import { loadWorkerProfile, workerProfileMarker, } from "./profile.js";
+import { loadWorkerProfileWithRegistry, workerProfileMarker, } from "./profile.js";
 export const WORKER_REGISTRY_REL = path.join("core", "workers", "registry.yaml");
 function defaultRegistryDeps() {
     return {
@@ -371,10 +371,15 @@ function readRegistryOrEmpty(hqRoot, deps) {
         return [];
     return readWorkerRegistryFile(hqRoot, deps);
 }
-export function resolveLaneWorker(hqRoot, workerId, laneCompany, deps = defaultRegistryDeps()) {
+export function resolveLaneWorker(hqRoot, workerId, laneCompany, deps = defaultRegistryDeps(), options = {}) {
     const personalRel = path.posix.join("personal", "workers", workerId);
     const profile = workerProfileMarker(hqRoot, workerId) === "present"
-        ? loadWorkerProfile(hqRoot, workerId)
+        ? loadWorkerProfileWithRegistry(hqRoot, workerId, {
+            laneCompany,
+            ...(options.registryWorkerRecord !== undefined
+                ? { registryWorkerRecord: options.registryWorkerRecord }
+                : {}),
+        })
         : undefined;
     const personalClaim = profile ? "profile" : personalDirClaim(hqRoot, workerId, deps);
     if (personalClaim === "missing_yaml") {

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

@@ -239,7 +239,7 @@ export declare function buildProviderCommand(provider: LaneProvider, input: {
 export declare function workerEnv(base: NodeJS.ProcessEnv, resolved: {
     envVar: string;
     home: string;
-}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string): NodeJS.ProcessEnv;
+}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string, registryWorker?: LaneRecord["registry_worker"]): NodeJS.ProcessEnv;
 export declare const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
 /** Grok does not run HQ hooks; Claude and Codex use the installed capability marker. */
 export declare function workerPolicyDeliveryMode(hqRoot: string, provider: LaneProvider): "hook" | "prompt";

package/dist/lib/lanes/spawn.js

@@ -23,7 +23,8 @@ import { appendEffortFlag, resolveLaneEffort, } from "./effort.js";
 import { defaultProbe, validateLaneModel, validateProfileLaneModel, } from "./models.js";
 import { claimableStatesFor, planLaneLaunch, providerSupportsSessionResume, } from "./delivery.js";
 import { AccountResolutionError, LanesError } from "./errors.js";
-import { ignoredWorkerProfileFields, loadWorkerProfile, materializeWorkerProfile, workerProfilePrompt, } from "./profile.js";
+import { ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, materializeWorkerProfile, workerProfilePrompt, } from "./profile.js";
+import { registryWorkerRecord } from "./registry-persona.js";
 import { resolveMachineIdentity, } from "./machine-identity.js";
 import { appendCappedHistory, listLaneIds, readLane, retryUpdateLane } from "./store.js";
 import { copySessionFiles, planSessionCopy } from "./move-account.js";
@@ -1236,7 +1237,7 @@ export function buildProviderCommand(provider, input) {
         args: appendFastModeFlags(parsed, appendEffortFlag(parsed, appendModelFlag(parsed, appendCodexWorkerPolicyDirFlag(parsed, appendProviderProfileFlags(parsed, args, input.profile), input.workerPolicyDir), input.model), input.effort), input.fastMode),
     };
 }
-export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir) {
+export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir, registryWorker) {
     const accepted = Object.values(PROVIDER_HOME_ENV);
     if (!accepted.includes(resolved.envVar)) {
         throw new LanesError("unknown_provider_home_env", `Unknown provider home variable ${JSON.stringify(resolved.envVar)}. Accepted: ${accepted.join(", ")}`, { accepted, value: resolved.envVar });
@@ -1245,6 +1246,8 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     delete env.HQ_PROJECT_ID;
     delete env.HQ_STORY_ID;
     delete env.HQ_POLICY_WORKER_DIR;
+    delete env.HQ_LANE_APPROVAL_REQUIRED;
+    delete env.HQ_LANE_HUMAN_CHECKPOINTS;
     env[resolved.envVar] = resolved.home;
     delete env[CLAUDE_AUTO_COMPACT_ENV];
     if (resolved.envVar === PROVIDER_HOME_ENV.claude && autoCompactTokens !== undefined) {
@@ -1252,6 +1255,12 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     }
     env.HQ_LANE_ID = laneId;
     env.HQ_ROOT = hqRoot;
+    if (registryWorker && (registryWorker.approval_required || registryWorker.human_checkpoints.length > 0)) {
+        env.HQ_LANE_APPROVAL_REQUIRED = "1";
+        env.HQ_LANE_HUMAN_CHECKPOINTS = registryWorker.human_checkpoints.length > 0
+            ? registryWorker.human_checkpoints.join(",")
+            : "external_publish";
+    }
     if (workerPolicyDir !== undefined &&
         (resolved.envVar === PROVIDER_HOME_ENV.claude || resolved.envVar === PROVIDER_HOME_ENV.codex)) {
         env.HQ_POLICY_WORKER_DIR = workerPolicyDir;
@@ -1659,7 +1668,12 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     ensureDir(logsDir);
     ensureDir(path.join(runDir, "envelopes"));
     const profile = existing.worker_profile
-        ? loadWorkerProfile(hqRoot, existing.worker_profile)
+        ? loadWorkerProfileWithRegistry(hqRoot, existing.worker_profile, {
+            laneCompany: existing.company?.slug ?? existing.mesh_company?.slug,
+            ...(existing.registry_worker !== undefined
+                ? { registryWorkerRecord: existing.registry_worker }
+                : {}),
+        })
         : undefined;
     if (existing.host.kind === "outpost" &&
         profile !== undefined &&
@@ -1827,7 +1841,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
     const laneTurnId = randomUUID();
     childEnv.HQ_LANE_TURN_ID = laneTurnId;
     const model = resolveLaneModel({
@@ -2023,10 +2037,13 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             ...(profile
                 ? {
                     worker_profile_hash: profile.contentHash,
+                    registry_worker: profile.registryWorker !== undefined
+                        ? registryWorkerRecord(profile.registryWorker)
+                        : undefined,
                     worker_profile_ignored: [...ignoredProfileFields],
                     worker_policy_delivery: policyDelivery,
                 }
-                : { worker_policy_delivery: undefined }),
+                : { registry_worker: undefined, worker_policy_delivery: undefined }),
         };
         if (resume !== undefined) {
             next.provider_session_id = resume.session_id;
@@ -2240,7 +2257,11 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     ensureDir(logsDir);
     const config = loadLanesConfig(hqRoot);
     const profile = lane.worker_profile
-        ? loadWorkerProfile(hqRoot, lane.worker_profile, {
+        ? loadWorkerProfileWithRegistry(hqRoot, lane.worker_profile, {
+            laneCompany: lane.company?.slug ?? lane.mesh_company?.slug,
+            ...(lane.registry_worker !== undefined
+                ? { registryWorkerRecord: lane.registry_worker }
+                : {}),
             onUnknownMetaFields: (fields) => {
                 process.stderr.write(`hq lanes watcher: envelope repair ignored unknown worker profile meta field(s) for ${lane.worker_profile}: ${fields.join(", ")}\n`);
                 input.onProfileWarning?.(fields);
@@ -2289,7 +2310,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
     const accountCfg = config.providers[lane.provider].accounts[resolved.id];
     const model = resolveLaneModel({
         cliModel: pinnedModel,

package/dist/lib/lanes/store.js

@@ -543,6 +543,91 @@ export function parseLaneRecord(raw, filePath) {
         raw.worker_policy_delivery !== "prompt") {
         throw new LaneSchemaError(`Unknown worker policy delivery mode ${JSON.stringify(raw.worker_policy_delivery)}`, { path: filePath, field: "worker_policy_delivery", value: raw.worker_policy_delivery });
     }
+    if (raw.registry_worker !== undefined) {
+        const worker = raw.registry_worker;
+        if (!isPlainObject(worker) || Object.keys(worker).some((key) => !["id", "path", "worker_yaml_sha256", "approval_required", "human_checkpoints"].includes(key))) {
+            throw new LaneSchemaError("registry_worker must be a pinned registry worker record", {
+                path: filePath,
+                field: "registry_worker",
+            });
+        }
+        for (const key of ["id", "path"]) {
+            if (typeof worker[key] !== "string" || worker[key].trim().length === 0) {
+                throw new LaneSchemaError(`registry_worker.${key} must be a non-empty string`, {
+                    path: filePath,
+                    field: `registry_worker.${key}`,
+                });
+            }
+        }
+        const registryPath = worker.path.replaceAll("\\", "/");
+        if (path.posix.isAbsolute(registryPath) || registryPath.split("/").some((part) => part === ".." || part === ".")) {
+            throw new LaneSchemaError("registry_worker.path must stay within HQ_ROOT", {
+                path: filePath,
+                field: "registry_worker.path",
+            });
+        }
+        if (typeof worker.worker_yaml_sha256 !== "string" || !/^sha256:[a-f0-9]{64}$/.test(worker.worker_yaml_sha256)) {
+            throw new LaneSchemaError("registry_worker.worker_yaml_sha256 must be a SHA-256 hash", {
+                path: filePath,
+                field: "registry_worker.worker_yaml_sha256",
+            });
+        }
+        if (typeof worker.approval_required !== "boolean") {
+            throw new LaneSchemaError("registry_worker.approval_required must be a boolean", {
+                path: filePath,
+                field: "registry_worker.approval_required",
+            });
+        }
+        if (!Array.isArray(worker.human_checkpoints) || worker.human_checkpoints.some((checkpoint) => typeof checkpoint !== "string" || checkpoint.trim().length === 0) ||
+            new Set(worker.human_checkpoints).size !== worker.human_checkpoints.length) {
+            throw new LaneSchemaError("registry_worker.human_checkpoints must be unique non-empty strings", {
+                path: filePath,
+                field: "registry_worker.human_checkpoints",
+            });
+        }
+    }
+    if (raw.registry_worker_approval_history !== undefined) {
+        if (!Array.isArray(raw.registry_worker_approval_history)) {
+            throw new LaneSchemaError("registry_worker_approval_history must be an array when present", {
+                path: filePath,
+                field: "registry_worker_approval_history",
+            });
+        }
+        for (const [index, entry] of raw.registry_worker_approval_history.entries()) {
+            const field = `registry_worker_approval_history[${index}]`;
+            if (!isPlainObject(entry)) {
+                throw new LaneSchemaError(`${field} must be an approval audit event`, { path: filePath, field });
+            }
+            const expected = entry.event === "approved"
+                ? ["event", "approval_id", "checkpoint", "registry_worker_id", "worker_yaml_sha256", "reason", "actor", "at"]
+                : entry.event === "consumed"
+                    ? ["event", "approval_id", "envelope_ref", "at"]
+                    : [];
+            if (expected.length === 0 || Object.keys(entry).some((key) => !expected.includes(key))) {
+                throw new LaneSchemaError(`${field} has an unknown event or field`, { path: filePath, field });
+            }
+            for (const key of ["approval_id", ...(entry.event === "approved" ? ["checkpoint", "reason", "actor"] : ["envelope_ref"])]) {
+                if (typeof entry[key] !== "string" || entry[key].trim().length === 0) {
+                    throw new LaneSchemaError(`${field}.${key} must be a non-empty string`, { path: filePath, field });
+                }
+            }
+            if (entry.event === "approved" && entry.worker_yaml_sha256 !== undefined &&
+                (typeof entry.worker_yaml_sha256 !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.worker_yaml_sha256))) {
+                throw new LaneSchemaError(`${field}.worker_yaml_sha256 must be a SHA-256 hash`, {
+                    path: filePath,
+                    field: `${field}.worker_yaml_sha256`,
+                });
+            }
+            if (entry.event === "approved" && entry.registry_worker_id !== undefined &&
+                (typeof entry.registry_worker_id !== "string" || entry.registry_worker_id.trim().length === 0)) {
+                throw new LaneSchemaError(`${field}.registry_worker_id must be a non-empty string`, {
+                    path: filePath,
+                    field: `${field}.registry_worker_id`,
+                });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+        }
+    }
     parseLaneStories(raw, filePath);
     if (raw.last_envelope !== undefined) {
         if (!isPlainObject(raw.last_envelope) || typeof raw.last_envelope.ref !== "string" ||
@@ -920,6 +1005,11 @@ export function mergeLaneRecords(live, sidecars) {
                 worker_profile_repin_history: unionHistory(all.map((record) => record.worker_profile_repin_history ?? []), entryIdentity, base.worker_profile_repin_history ?? []),
             }
             : {}),
+        ...(all.some((record) => record.registry_worker_approval_history !== undefined)
+            ? {
+                registry_worker_approval_history: unionHistory(all.map((record) => record.registry_worker_approval_history ?? []), entryIdentity, base.registry_worker_approval_history ?? []),
+            }
+            : {}),
         ...(all.some((record) => record.failed_resume_history !== undefined)
             ? {
                 failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),

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

@@ -295,6 +295,31 @@ export interface WorkerProfileRepinHistoryEntry {
     at: string;
     reason: string;
 }
+/** The registry worker identity and approval contract pinned at lane creation. */
+export interface RegistryWorkerRecord {
+    id: string;
+    path: string;
+    worker_yaml_sha256: string;
+    approval_required: boolean;
+    human_checkpoints: string[];
+}
+/** Append-only approval and consumption events for registry worker checkpoints. */
+export type RegistryWorkerApprovalHistoryEntry = {
+    event: "approved";
+    approval_id: string;
+    checkpoint: string;
+    /** Pins this approval to the registry worker version that received it. */
+    registry_worker_id?: string;
+    worker_yaml_sha256?: string;
+    reason: string;
+    actor: string;
+    at: string;
+} | {
+    event: "consumed";
+    approval_id: string;
+    envelope_ref: string;
+    at: string;
+};
 export interface AttributionHistoryEntry {
     project_id: string;
     story_id: string;
@@ -390,6 +415,10 @@ export interface LaneRecord {
     hire_grant?: number;
     /** Content hash of the profile last applied to this lane. */
     worker_profile_hash?: string;
+    /** Registry persona selected by the profile, pinned at lane creation. */
+    registry_worker?: RegistryWorkerRecord;
+    /** Append-only approvals and one-envelope consumption records. */
+    registry_worker_approval_history?: RegistryWorkerApprovalHistoryEntry[];
     /** Bounded audit history of authorized Outpost profile hash re-pins. */
     worker_profile_repin_history?: WorkerProfileRepinHistoryEntry[];
     /** Profile fields intentionally unsupported by the selected provider. */

package/dist/lib/lanes/types.js

@@ -223,7 +223,7 @@ export const LANE_FIELD_WRITERS = {
     state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
-    priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
+    priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
     provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],

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

@@ -164,6 +164,8 @@ export declare function applyTerminalToLane(hqRoot: string, laneId: string, clas
 export declare function applyTerminalToLaneWithResult(hqRoot: string, laneId: string, classification: TerminalClassification, opts?: ApplyTerminalOpts): {
     record: LaneRecord;
     changed: boolean;
+    envelope?: LaneEnvelope;
+    classification: TerminalClassification;
 };
 export declare function isPidAlive(pid: number): boolean;
 export interface LatestEnvelope {