@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/execution-bundles.js

@@ -0,0 +1,275 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { hybridDigest, validateHybridContract, validateHybridShape } from "./hybrid-contracts.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { projectPacketLocators } from "./stage-context.js";
+const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const limit = 1024 * 1024;
+function refuse(reason, issues) {
+    throw new AppError("execution_bundle_invalid", "Execution bundle cannot be admitted", 1, { reason, phase: "prepare", effect: "no_effect", ...(issues ? { issues } : {}) });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_utf8_json");
+    }
+}
+function frozen(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+}
+function directory(file) {
+    if (!fs.lstatSync(file).isDirectory())
+        refuse("non_regular_bundle_directory");
+}
+function fileIn(root, logical, create = false) {
+    const parts = logical.split("/");
+    let current = root;
+    for (const part of parts.slice(0, -1)) {
+        current = path.join(current, part);
+        if (create && !fs.existsSync(current))
+            fs.mkdirSync(current, { mode: 0o700 });
+        directory(current);
+    }
+    return path.join(current, parts.at(-1));
+}
+/** Retained contract data only. RUN generation, physical ownership and writer admission remain separate. */
+export class RetainedExecutionBundle {
+    sha256;
+    manifest;
+    descriptor;
+    execution;
+    #bytes;
+    #blobs;
+    #admission;
+    #engine;
+    #engineRelocation;
+    constructor(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation) {
+        frozen(manifest);
+        this.manifest = manifest;
+        this.sha256 = hash(bytes);
+        this.#bytes = bytes;
+        this.#blobs = blobs;
+        this.#admission = admission;
+        this.descriptor = descriptor;
+        this.execution = execution;
+        this.#engineRelocation = engineRelocation && structuredClone(engineRelocation);
+        Object.freeze(this);
+    }
+    static admit(input, expectedSha256, sourceBlobs, selected, engineRelocation) {
+        if (input.byteLength > limit || !/^[a-f0-9]{64}$/.test(expectedSha256))
+            refuse("invalid_bundle_identity");
+        const bytes = Buffer.from(input);
+        if (hash(bytes) !== expectedSha256)
+            refuse("manifest_bytes_changed");
+        const value = json(bytes), shape = validateHybridShape("execution-bundle", value);
+        if (shape.length)
+            refuse("invalid_bundle_shape", shape);
+        const manifest = value;
+        if (manifest.run_id !== selected.runId || selected.executionScope.projectRoot !== selected.bundleProjectRoot)
+            refuse("foreign_run_identity");
+        const admission = structuredClone(selected);
+        const names = manifest.inventory.map(ref => ref.path), folded = new Set();
+        for (const name of names) {
+            const normalized = name.toLowerCase();
+            if (folded.has(normalized) || ["manifest.json", "publication.json"].includes(normalized)
+                || names.some(other => other !== name && other.toLowerCase().startsWith(`${normalized}/`)))
+                refuse("conflicting_bundle_path");
+            folded.add(normalized);
+        }
+        const blobs = new Map();
+        let total = 0;
+        for (const reference of manifest.inventory) {
+            const source = sourceBlobs.get(reference.path);
+            if (!source || source.byteLength === 0 || source.byteLength > limit || (total += source.byteLength) > 32 * limit)
+                refuse("missing_or_unbounded_blob");
+            blobs.set(reference.path, Buffer.from(source));
+        }
+        const context = { ...admission, blobs };
+        const issues = validateHybridContract("execution-bundle", manifest, context);
+        if (issues.length)
+            refuse("invalid_bundle_context", issues);
+        if (!admission.descriptorContext)
+            refuse("missing_handler_context");
+        const descriptor = ResolvedFlowDescriptor.admit(blobs.get(manifest.descriptor.path), manifest.descriptor.sha256, { ...admission.descriptorContext, blobs });
+        for (const stage of descriptor.descriptor.stages) {
+            try {
+                new TextDecoder("utf-8", { fatal: true }).decode(descriptor.stageBlob(stage.id, "instruction"));
+            }
+            catch {
+                refuse("invalid_instruction_encoding");
+            }
+        }
+        const profiles = json(blobs.get(manifest.profile_settings.path));
+        const snapshot = { schema_id: "dd-flow/frozen-execution@1", scope: admission.executionScope,
+            settings: json(blobs.get(manifest.execution_settings.path)), profiles: profiles.profiles };
+        const execution = FrozenGenericExecution.restore(snapshot, hybridDigest(snapshot), descriptor, admission.executionScope, admission.receipts);
+        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation);
+        admitted.engine();
+        return admitted;
+    }
+    /** Read only the retained inventory. Mutable canon/profile sources are never consulted. */
+    static read(root, expectedSha256, admission, engineRelocation) {
+        try {
+            directory(root);
+            const bytes = readBoundedReleaseFile(path.join(root, "manifest.json"), limit);
+            if (hash(bytes) !== expectedSha256)
+                refuse("manifest_bytes_changed");
+            const value = json(bytes), issues = validateHybridShape("execution-bundle", value);
+            if (issues.length)
+                refuse("invalid_bundle_shape", issues);
+            const manifest = value, blobs = new Map();
+            for (const ref of manifest.inventory)
+                blobs.set(ref.path, readBoundedReleaseFile(fileIn(root, ref.path), limit));
+            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission, engineRelocation);
+        }
+        catch (error) {
+            if (error instanceof AppError && ["execution_bundle_invalid", "frozen_engine_invalid"].includes(error.code))
+                throw error;
+            return refuse("retained_bundle_unavailable");
+        }
+    }
+    manifestBytes() { return Buffer.from(this.#bytes); }
+    blob(logical) {
+        const bytes = this.#blobs.get(logical);
+        if (!bytes)
+            refuse("unlisted_bundle_blob");
+        return Buffer.from(bytes);
+    }
+    admission() { return structuredClone(this.#admission); }
+    engine() {
+        // An issued bundle already admitted this exact immutable engine. Fresh
+        // read/admit creates a new owner; publication explicitly rechecks below.
+        return this.#engine ??= this.#admitEngine();
+    }
+    #admitEngine() {
+        const binding = json(this.blob(this.manifest.engine_binding.path));
+        const retainedManifest = this.blob(this.manifest.engine_manifest.path), relocation = this.#engineRelocation;
+        if (relocation) {
+            const root = JSON.parse(projectPacketLocators(JSON.stringify({ root: binding.engine.snapshot_root }), relocation.relocations)).root;
+            if (!relocation.relocations.length || root === binding.engine.snapshot_root || root !== relocation.binding.engine.snapshot_root
+                || relocation.binding.run_id !== this.manifest.run_id)
+                refuse("foreign_engine_relocation");
+        }
+        const engine = relocation
+            ? AdmittedFrozenEngine.admitRelocation(binding, retainedManifest, this.manifest.engine_manifest.sha256, relocation.binding)
+            : AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
+        if (!relocation && !engine.manifestBytes().equals(retainedManifest))
+            refuse("engine_manifest_bytes_changed");
+        const manifest = engine.manifest(), contracts = new Set(Object.values(manifest.supports_contracts).flat());
+        for (const id of ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1"]) {
+            if (!contracts.has(id))
+                refuse("engine_contract_not_supported");
+        }
+        for (const reference of this.manifest.bootstrap_receipts) {
+            const receipt = json(this.blob(reference.path));
+            if (receipt.schema_id !== "dd-flow/memory-bootstrap-receipt@2")
+                continue;
+            if (!contracts.has(receipt.schema_id))
+                refuse("engine_contract_not_supported");
+            const entries = manifest.schema_registry.entries.filter(entry => entry.id === receipt.schema_id);
+            const entry = entries[0];
+            if (entries.length !== 1 || !entry)
+                refuse("unregistered_bootstrap_schema");
+            try {
+                const validate = new Ajv2020({ strict: true, validateFormats: false }).compile(json(engine.schema(entry.name)));
+                if (!validate(receipt))
+                    refuse("invalid_frozen_bootstrap_shape", validate.errors);
+            }
+            catch (error) {
+                if (error instanceof AppError)
+                    throw error;
+                refuse("invalid_frozen_bootstrap_schema");
+            }
+        }
+        for (const stage of this.descriptor.descriptor.stages) {
+            const bytes = this.descriptor.stageBlob(stage.id, "result_schema"), schema = json(bytes);
+            if (!manifest.schema_registry.entries.some(entry => entry.id === schema.$id && entry.checksum === hash(bytes)))
+                refuse("unregistered_stage_schema");
+        }
+        return engine;
+    }
+    /** Deterministic publication under the RUN's existing root and immutable engine binding. */
+    materialize(runRoot) {
+        this.#admitEngine();
+        directory(runRoot);
+        if (hash(readBoundedReleaseFile(path.join(runRoot, "engine-binding.json"), limit)) !== this.manifest.engine_binding.sha256)
+            refuse("run_engine_binding_changed");
+        const target = path.join(runRoot, "execution-bundle"), pending = path.join(runRoot, `.execution-bundle.pending-${this.sha256}`);
+        const lock = acquireInstallationLock(path.join(runRoot, "execution-bundle.lock"), this.sha256);
+        let publicationStarted = false;
+        try {
+            if (fs.existsSync(target)) {
+                RetainedExecutionBundle.read(target, this.sha256, this.#admission);
+                return { path: target, sha256: this.sha256, changed: false };
+            }
+            const owner = Buffer.from(JSON.stringify({ schema_id: "dd-flow/bundle-publication@1", sha256: this.sha256, run_id: this.manifest.run_id }));
+            publicationStarted = true;
+            if (!fs.existsSync(pending)) {
+                fs.mkdirSync(pending, { mode: 0o700 });
+                fs.writeFileSync(path.join(pending, "publication.json"), owner, { flag: "wx", mode: 0o600 });
+            }
+            directory(pending);
+            if (!readBoundedReleaseFile(path.join(pending, "publication.json"), limit).equals(owner))
+                refuse("foreign_pending_publication");
+            const write = (logical, bytes) => {
+                const file = fileIn(pending, logical, true);
+                if (fs.existsSync(file)) {
+                    if (!readBoundedReleaseFile(file, limit).equals(bytes))
+                        refuse("retained_blob_changed");
+                    return;
+                }
+                const temporary = path.join(pending, `.write-${hash(Buffer.from(logical))}.tmp`);
+                if (fs.existsSync(temporary)) {
+                    const stat = fs.lstatSync(temporary);
+                    if (!stat.isFile() || stat.nlink !== 1)
+                        refuse("foreign_pending_write");
+                    fs.unlinkSync(temporary);
+                }
+                // This temporary is owned by the exact publication receipt and lock.
+                // A crashed partial write is deterministic; no productive operation is retried.
+                const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+                try {
+                    fs.writeFileSync(fd, bytes);
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                fs.renameSync(temporary, file);
+            };
+            for (const [logical, bytes] of this.#blobs)
+                write(logical, bytes);
+            write("manifest.json", this.#bytes);
+            RetainedExecutionBundle.read(pending, this.sha256, this.#admission);
+            if (fs.existsSync(target))
+                refuse("concurrent_bundle_publication");
+            fs.renameSync(pending, target);
+            return { path: target, sha256: this.sha256, changed: true };
+        }
+        catch (error) {
+            if (!publicationStarted)
+                throw error;
+            throw new AppError("execution_bundle_publication_failed", "Execution bundle publication requires recovery", 1, {
+                phase: "publication", effect: "partial", run_id: this.manifest.run_id,
+                sha256: this.sha256, pending_path: pending,
+                reason: error instanceof AppError ? error.code : "publication_io_failure",
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }
+}

package/dist/services/execution-policy.js

@@ -0,0 +1,185 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { harnessKey } from "./harness-config.js";
+import { vnextStages } from "../domain/stage-catalog.js";
+import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
+import { operatorSettingsPath, readOperatorProfiles, readOperatorProfileInput, resolveOperatorProfile } from "./operator-profiles.js";
+import { selectOnboardingExecutor } from "./executor-onboarding.js";
+/** Read once so the frozen policy and its provenance describe the same bytes. */
+export function loadExecutionRoutingInput(file) {
+    const { file: source_path, bytes } = prepareFileBytes(file, "execution routing");
+    const value = prepareJsonText(bytes.toString("utf8"), { file: source_path, label: "execution routing" }).value;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("execution_profile_invalid", "Execution routing input must be an object", 2, { source_path, phase: "prepare", effect: "no_effect", recoverable: true });
+    }
+    const input = value;
+    if (input.schema_id !== "dd-flow/execution-routing@1"
+        || Object.keys(input).some(key => key !== "schema_id" && key !== "execution")
+        || !isExecutionRouting(input.execution)) {
+        throw new AppError("execution_profile_invalid", "Execution routing input does not match dd-flow/execution-routing@1", 2, { source_path, phase: "prepare", effect: "no_effect", recoverable: true });
+    }
+    return { execution: input.execution, bytes, source_path, source_checksum: crypto.createHash("sha256").update(bytes).digest("hex") };
+}
+/** One routing validator for project defaults and explicit RUN inputs. */
+export function isExecutionRouting(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const { stage_overrides: stages, ...root } = value;
+    if (typeof root.agent_profile_id !== "string")
+        return false;
+    try {
+        validateExecutionOverride(root);
+        if (stages !== undefined) {
+            if (!stages || typeof stages !== "object" || Array.isArray(stages))
+                return false;
+            for (const [stage, override] of Object.entries(stages)) {
+                if (!vnextStages.some(item => item.id === stage))
+                    return false;
+                validateExecutionOverride(override);
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reads one complete profile.  A policy selects profiles; it never field-merges them. */
+export function loadAgentProfile(ddFlowHome, id) {
+    if (typeof id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id))
+        throw new AppError("agent_profile_invalid", "Agent profile id is invalid", 2, { id });
+    if (fs.existsSync(operatorSettingsPath(ddFlowHome)))
+        return resolveOperatorProfile(readOperatorProfiles(ddFlowHome), id);
+    const file = path.join(ddFlowHome, "agent-profiles", `${id}.json`);
+    if (!fs.existsSync(file))
+        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id });
+    let profile;
+    try {
+        profile = readOperatorProfileInput(file);
+    }
+    catch {
+        throw new AppError("agent_profile_invalid", "Agent profile must be a bounded valid regular JSON file", 2, { id });
+    }
+    if (profile.id !== id) {
+        throw new AppError("agent_profile_invalid", "Agent profile does not match its selected ID", 2, { id });
+    }
+    // Only execution settings enter RUN evidence; never copy arbitrary profile fields.
+    return { schema_id: profile.schema_id, id, harness: profile.harness, provider: profile.provider, model: profile.model, reasoning: profile.reasoning, mode: profile.mode, permission: profile.permission };
+}
+export function snapshotAgentProfiles(ddFlowHome, policy) {
+    if (!isExecutionRouting(policy))
+        throw new AppError("execution_profile_invalid", "Execution routing contains an invalid stage, profile or delegation policy", 2);
+    const profiles = Object.create(null);
+    const settings = fs.existsSync(operatorSettingsPath(ddFlowHome)) ? readOperatorProfiles(ddFlowHome) : undefined;
+    for (const override of [policy, ...Object.values(policy.stage_overrides ?? {})]) {
+        for (const id of [override.agent_profile_id, override.delegation?.agent_profile_id]) {
+            if (id !== undefined && !Object.hasOwn(profiles, id)) {
+                const profile = settings ? selectOnboardingExecutor({}, () => settings, { allowSkip: false, projectProfileId: id }).profile : loadAgentProfile(ddFlowHome, id);
+                profiles[id] = profile;
+                // Routing labels may be aliases. Default worker resolution uses the
+                // complete coordinator's canonical ID, which must also be frozen.
+                profiles[profile.id] = profile;
+            }
+        }
+    }
+    // Validate every declared route now, including stages not reached by this run.
+    for (const stage of [undefined, ...Object.keys(policy.stage_overrides ?? {})]) {
+        resolveExecutionPolicy({ ddFlowHome, policy, profiles, ...(stage ? { stage } : {}) });
+    }
+    return profiles;
+}
+/** Resolves a frozen policy with explicit topology.  Same profiles do not turn external work into native work. */
+export function resolveExecutionPolicy(input) {
+    if (input.work !== undefined)
+        validateExecutionOverride(input.work);
+    const profile = (id) => {
+        if (!input.profiles)
+            return loadAgentProfile(input.ddFlowHome, id);
+        if (!Object.hasOwn(input.profiles, id))
+            throw new AppError("execution_profile_not_frozen", "Profile is not in this RUN's frozen execution snapshot", 1, { id });
+        return input.profiles[id];
+    };
+    const stage = input.stage ? input.policy.stage_overrides?.[input.stage] : undefined;
+    const coordinatorId = stage?.agent_profile_id ?? input.policy.agent_profile_id;
+    if (!coordinatorId)
+        throw new AppError("execution_profile_missing", "Execution policy needs agent_profile_id before external dispatch", 1, { stage: input.stage ?? null });
+    const coordinator = profile(coordinatorId);
+    const delegation = input.work?.delegation ?? stage?.delegation ?? input.policy.delegation ?? { mode: "native" };
+    validateDelegation(delegation);
+    if (input.work?.agent_profile_id && input.work.delegation?.agent_profile_id && input.work.agent_profile_id !== input.work.delegation.agent_profile_id)
+        throw new AppError("execution_profile_invalid", "Work selects conflicting worker profiles", 2);
+    const worker = profile(input.work?.agent_profile_id ?? delegation.agent_profile_id ?? coordinator.id);
+    if (delegation.mode === "native" && harnessKey(worker.harness) !== harnessKey(coordinator.harness)) {
+        throw new AppError("native_harness_mismatch", "Native delegation cannot change harness", 2, { coordinator_harness: coordinator.harness, worker_harness: worker.harness });
+    }
+    if (delegation.mode === "native" && !sameSessionProfile(coordinator, worker))
+        throw new AppError("native_profile_override_unqualified", "Native worker profile overrides require qualified adapter support; select external delegation", 2, { coordinator_profile_id: coordinator.id, worker_profile_id: worker.id });
+    const resolved = {
+        coordinator,
+        worker,
+        delegation: { mode: delegation.mode, max_parallel: delegation.mode === "external" ? delegation.max_parallel ?? 1 : null }
+    };
+    return { ...resolved, profile_hash: digest(resolved) };
+}
+export function runtimeHarness(profile) { return harnessKey(profile.harness); }
+/** Profile labels are not execution identity; every session-affecting value is. */
+export function sameSessionProfile(left, right) {
+    const settings = (profile) => ({ harness: runtimeHarness(profile), provider: profile.provider, model: profile.model, reasoning: profile.reasoning, mode: profile.mode, permission: profile.permission });
+    return digest(settings(left)) === digest(settings(right));
+}
+export function assertSameSessionMerge(input) {
+    const merge = resolveExecutionPolicy({ ...input, stage: "merge" }).coordinator;
+    for (const stage of input.previousStages) {
+        const previous = resolveExecutionPolicy({ ...input, stage }).coordinator;
+        if (!sameSessionProfile(previous, merge))
+            throw new AppError("merge_profile_session_conflict", "Same-session MERGE cannot switch execution profiles; select a compatible profile or server MERGE", 2, { previous_stage: stage, previous_profile_id: previous.id, merge_profile_id: merge.id });
+    }
+}
+/** The RUN identity root and a native Session's fixed launch directory are distinct. */
+export function stageExecutionCwd(input) {
+    return path.resolve(input.stage === "specify" || input.stage === "protocolize" ? input.projectRoot
+        : input.stage === "merge" ? input.mergeTargetWorkspace ?? input.projectRoot
+            : input.workspaceRoot);
+}
+export function resolveStageTransition(input) {
+    const target = resolveExecutionPolicy(input);
+    const previous = input.fromStage ? resolveExecutionPolicy({ ...input, stage: input.fromStage }).coordinator : null;
+    const compatible = !previous || sameSessionProfile(previous, target.coordinator);
+    const previousCwd = input.fromStage ? stageExecutionCwd({ ...input, stage: input.fromStage }) : null;
+    const targetCwd = stageExecutionCwd(input);
+    const sameWorkspace = previousCwd === null || previousCwd === targetCwd;
+    if (input.stage === "merge" && input.mergeMode === "same_session") {
+        if (!compatible)
+            throw new AppError("merge_profile_session_conflict", "Same-session MERGE cannot replace its current coordinator", 2);
+        if (!sameWorkspace)
+            throw new AppError("merge_session_workspace_conflict", "Same-session MERGE cannot change the native coordinator workspace", 2, { source_workspace: previousCwd, target_workspace: targetCwd });
+        return { ...target, session_mode: "same_session" };
+    }
+    return { ...target, session_mode: !compatible || !sameWorkspace || (input.stage === "merge" && input.mergeMode === "server") ? "new_session" : input.stageSessionMode };
+}
+function validateDelegation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["mode", "agent_profile_id", "max_parallel"].includes(key)))
+        throw new AppError("execution_profile_invalid", "Delegation has unsupported fields", 2);
+    if (value.mode !== "native" && value.mode !== "external")
+        throw new AppError("execution_profile_invalid", "Delegation mode must be native or external", 2);
+    if (value.agent_profile_id !== undefined && (typeof value.agent_profile_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value.agent_profile_id)))
+        throw new AppError("execution_profile_invalid", "Delegation profile id is invalid", 2);
+    if (value.max_parallel !== undefined && (!Number.isInteger(value.max_parallel) || value.max_parallel < 1))
+        throw new AppError("execution_profile_invalid", "External max_parallel must be a positive integer", 2);
+    if (value.mode === "native" && value.max_parallel !== undefined)
+        throw new AppError("execution_profile_invalid", "Native delegation does not accept max_parallel", 2);
+}
+export function validateExecutionOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["agent_profile_id", "delegation"].includes(key)))
+        throw new AppError("execution_profile_invalid", "Work execution override has unsupported fields", 2);
+    const override = value;
+    if (override.agent_profile_id === undefined && override.delegation === undefined)
+        throw new AppError("execution_profile_invalid", "Work execution override is empty", 2);
+    if (override.agent_profile_id !== undefined && (typeof override.agent_profile_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(override.agent_profile_id)))
+        throw new AppError("execution_profile_invalid", "Work profile id is invalid", 2);
+    if (override.delegation !== undefined)
+        validateDelegation(override.delegation);
+}
+function digest(value) { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/dist/services/executor-onboarding.js

@@ -0,0 +1,56 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareOperatorProfile, readOperatorProfileInput, resolveOperatorProfile, validateProfileCreationIntent } from "./operator-profiles.js";
+function refuse(code, message, exitCode = 2) {
+    throw new AppError(code, message, exitCode, { phase: "executor_onboarding", effect: "no_effect", help: "profiles" });
+}
+/** Shared setup/first-flow admission; settings are read lazily, never written. */
+export function selectOnboardingExecutor(choice, readSettings, policy) {
+    if (!choice || typeof choice !== "object" || Array.isArray(choice)
+        || Object.keys(choice).some(key => !["profileId", "profile", "profileFile", "skip", "profileCreation"].includes(key))
+        || choice.profileFile !== undefined && (typeof choice.profileFile !== "string" || !choice.profileFile.trim())
+        || choice.skip !== undefined && typeof choice.skip !== "boolean"
+        || choice.profileId !== undefined && (typeof choice.profileId !== "string" || !choice.profileId.trim())) {
+        refuse("usage", "Invalid executor selection");
+    }
+    if ([choice.profileId !== undefined, choice.profile !== undefined, choice.profileFile !== undefined, choice.skip === true].filter(Boolean).length > 1) {
+        refuse("usage", "Executor profile, profile ID and skip are mutually exclusive");
+    }
+    if (choice.profileCreation !== undefined) {
+        validateProfileCreationIntent(choice.profileCreation);
+        if (choice.profile === undefined || hybridDigest(choice.profile) !== hybridDigest(choice.profileCreation.profile))
+            refuse("usage", "Profile save intent requires its exact explicit profile");
+    }
+    if (choice.skip) {
+        if (!policy.allowSkip)
+            refuse("agent_profile_missing", "This operation requires an executor profile", 1);
+        return { profile: null, revision: null, source: "skip" };
+    }
+    const explicit = choice.profile !== undefined || choice.profileFile !== undefined || choice.profileId !== undefined;
+    if (!explicit && policy.projectProfileId !== undefined && (typeof policy.projectProfileId !== "string" || !policy.projectProfileId.trim())) {
+        refuse("usage", "Invalid project executor profile selection");
+    }
+    const profile = prepareOperatorProfile(choice.profile !== undefined ? choice.profile : choice.profileFile !== undefined
+        ? readOperatorProfileInput(choice.profileFile) : resolveOperatorProfile(readSettings(), choice.profileId ?? policy.projectProfileId));
+    return { profile: structuredClone(profile), revision: hybridDigest(profile),
+        ...(choice.profileCreation ? { profileCreation: structuredClone(choice.profileCreation) } : {}),
+        source: choice.profile !== undefined ? "explicit-profile" : choice.profileFile !== undefined ? "explicit-file" : choice.profileId !== undefined ? "explicit-id" : policy.projectProfileId !== undefined ? "project-default" : "default" };
+}
+/** Interactive decisions use exactly the same admission as headless choices. */
+export async function onboardExecutor(choice, readSettings, policy, ask) {
+    try {
+        return selectOnboardingExecutor(choice, readSettings, policy);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "agent_profile_missing"
+            || choice.profileId !== undefined || choice.profile !== undefined || choice.profileFile !== undefined || choice.skip === true
+            || policy.projectProfileId !== undefined || policy.nonInteractive || !ask)
+            throw error;
+        // No speculative defaults or writes: the human supplies a concrete choice.
+        const decision = await ask(structuredClone(readSettings()));
+        if (decision.profileId === undefined && decision.profile === undefined && decision.profileFile === undefined && decision.skip !== true) {
+            refuse("agent_profile_missing", "Onboarding requires an explicit choice", 1);
+        }
+        return selectOnboardingExecutor(decision, readSettings, policy);
+    }
+}