@kylecheng3146/agent-ops 0.5.2 → 0.6.0

package/dist/runtime/src/run/integration.js

@@ -0,0 +1,204 @@
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { FileRunRepository } from "./service.js";
+function ledger(commonDir) { return new FileRunRepository(join(commonDir, "agent-ops", "runs"), commonDir); }
+function proofPath(commonDir, runId) { return join(commonDir, "agent-ops", "runs", runId, "integration-proof.json"); }
+function integrationIdentity(integration) {
+    return {
+        transactionId: integration.transactionId,
+        expectedTarget: integration.expectedTarget,
+        candidate: integration.candidate
+    };
+}
+/** The binding intentionally excludes receiptDigest to avoid a receipt/state cycle. */
+export function integrationReceiptBindingDigest(integration) {
+    return sha256(canonicalJson(integrationIdentity(integration)));
+}
+export function integrationReceiptBinding(integration) {
+    return { ...integrationIdentity(integration), digest: integrationReceiptBindingDigest(integration) };
+}
+const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Validate the immutable run transaction fields embedded in a final receipt. */
+export function validateRunIntegrationReceipt(integration, receipt) {
+    const binding = receipt.integrationJournal;
+    if (receipt.candidateHead !== integration.candidate || receipt.targetCommit !== integration.expectedTarget ||
+        !plain(binding) || binding.transactionId !== integration.transactionId ||
+        binding.expectedTarget !== integration.expectedTarget || binding.candidate !== integration.candidate ||
+        binding.digest !== integrationReceiptBindingDigest(integration)) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The final receipt is not bound to the sealed integration transaction.");
+    }
+}
+async function readSealedProof(commonDir, runId, integration) {
+    const source = await readPrivateFile(proofPath(commonDir, runId), commonDir);
+    if (source === null || integration.proofDigest === undefined || sha256(source) !== integration.proofDigest) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The sealed integration proof is missing or changed.");
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (cause) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The sealed integration proof is not valid JSON.", { cause });
+    }
+    if (!plain(value) || value.target !== integration.expectedTarget || value.head !== integration.candidate) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "Integration proof no longer matches the frozen target and candidate.");
+    }
+    return value;
+}
+/** Seal the exact final gate before any target mutation. Recovery cannot invent a new proof. */
+export async function prepareRunIntegration(commonDir, record, proof) {
+    if (record.runId === undefined)
+        return;
+    const repository = ledger(commonDir);
+    const state = await repository.read(record.runId);
+    if (state === null || state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId ||
+        state.status !== "active" || state.disableRestart || state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Final integration requires the stopped registered coordinator and current active run.");
+    if (state.integration !== null) {
+        if (state.integration.status !== "prepared")
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Reconcile the existing integration before preparing another candidate.");
+        const sealed = await readSealedProof(commonDir, record.runId, state.integration);
+        if (canonicalJson(sealed) !== canonicalJson(proof))
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The existing sealed integration cannot be replaced by a new proof.");
+        return;
+    }
+    const source = JSON.stringify(proof);
+    await repository.mutate(record.runId, async (current) => {
+        if (current.status !== "active" || current.disableRestart || current.revision !== state.revision)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "Run changed while sealing final proof.");
+        await writePrivateFile(proofPath(commonDir, record.runId), source, commonDir);
+        return { ...current, integration: { transactionId: randomUUID(), status: "prepared", expectedTarget: proof.target,
+                candidate: proof.head, proofDigest: sha256(source), completedSteps: [], receiptPath: null, receiptDigest: null,
+                updatedAt: new Date().toISOString(), childDeliveries: proof.children.map(child => child.commit) } };
+    });
+}
+export async function readRunIntegrationProof(commonDir, record) {
+    if (record.runId === undefined)
+        return null;
+    const state = await ledger(commonDir).read(record.runId);
+    if (state?.integration == null)
+        return null;
+    if (state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId)
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Recovery coordinator does not match the sealed transaction.");
+    return await readSealedProof(commonDir, record.runId, state.integration);
+}
+/** A failed pre-merge CAS may be retried only after archiving the unused sealed transaction. */
+export async function abandonPreparedRunIntegration(commonDir, record, git) {
+    if (record.runId === undefined)
+        return;
+    const repository = ledger(commonDir);
+    const state = await repository.read(record.runId);
+    const transaction = state?.integration;
+    if (state === null || transaction == null)
+        return;
+    if (transaction.status !== "prepared" || state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId ||
+        state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Only a stopped, unused prepared transaction may be superseded.");
+    const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+    const commit = target.stdout.trim();
+    const ancestry = await git(state.root, ["merge-base", "--is-ancestor", transaction.candidate, commit]);
+    if (target.exitCode !== 0 || commit === transaction.expectedTarget || commit === transaction.candidate || ancestry.exitCode !== 1)
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The old candidate may have reached the target; preserve and recover its sealed transaction.");
+    const proof = await readSealedProof(commonDir, record.runId, transaction);
+    await repository.mutate(record.runId, async (current) => {
+        const actual = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+        if (current.revision !== state.revision || actual.exitCode !== 0 || actual.stdout.trim() !== commit)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "Run or target changed while superseding an unused transaction.");
+        const path = join(commonDir, "agent-ops", "runs", record.runId, "integration-history", transaction.transactionId + ".json");
+        await writePrivateFile(path, JSON.stringify({ transaction, proof, observedTarget: commit }), commonDir);
+        return { ...current, integration: null };
+    });
+}
+/** Read the binding used by a finish receipt without trusting caller-supplied transaction fields. */
+export async function readRunIntegrationReceiptBinding(commonDir, record, expected) {
+    if (record.runId === undefined)
+        return null;
+    const state = await ledger(commonDir).read(record.runId);
+    if (state === null || state.integration === null)
+        throw new AgentOpsError("RUN_INTEGRATION_REQUIRED", "A run-owned final receipt requires a sealed integration transaction.");
+    if (state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId)
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "The integration transaction belongs to another coordinator.");
+    await readSealedProof(commonDir, record.runId, state.integration);
+    if (state.integration.expectedTarget !== expected.target || state.integration.candidate !== expected.candidate)
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The receipt candidate does not match the sealed integration transaction.");
+    return integrationReceiptBinding(state.integration);
+}
+export async function markRunIntegration(commonDir, record, status, step, receipt) {
+    if (record.runId === undefined)
+        return;
+    await ledger(commonDir).mutate(record.runId, current => {
+        if (current.integration === null || current.ownerSessionId !== record.sessionId || current.coordinatorId !== record.workerId)
+            throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "The integration transaction is missing or belongs to another coordinator.");
+        return { ...current, integration: { ...current.integration, status, updatedAt: new Date().toISOString(),
+                completedSteps: [...new Set([...current.integration.completedSteps, step])],
+                ...(receipt === undefined ? {} : { receiptPath: receipt.path, receiptDigest: receipt.digest }) } };
+    });
+}
+/**
+ * Finish bookkeeping after a coordinator checkout vanished. This only verifies
+ * sealed artifacts and advances the ledger; it never recreates a checkout or
+ * starts a native writer.
+ */
+export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
+    const repository = ledger(commonDir);
+    const state = await repository.read(runId);
+    if (state === null || state.integration === null)
+        throw new AgentOpsError("RUN_INTEGRATION_REQUIRED", "There is no sealed integration to recover.");
+    const integration = state.integration;
+    if (state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Integration cleanup cannot be recovered while a writer is active.");
+    await readSealedProof(commonDir, runId, integration);
+    if (integration.status !== "cleaned" &&
+        (integration.status !== "receipt-written" || !integration.completedSteps.includes("receipt") ||
+            !integration.completedSteps.includes("note"))) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recovery requires a recorded receipt and Git note before cleanup can be completed.");
+    }
+    if (integration.receiptPath === null || integration.receiptDigest === null)
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The integration has no sealed receipt.");
+    const source = await readPrivateFile(integration.receiptPath, commonDir);
+    if (source === null || sha256(source) !== integration.receiptDigest)
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The recorded integration receipt is missing or changed.");
+    let receipt;
+    try {
+        const value = JSON.parse(source);
+        if (!plain(value))
+            throw new Error("receipt is not an object");
+        receipt = value;
+    }
+    catch (cause) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The recorded integration receipt is not valid JSON.", { cause });
+    }
+    if (receipt.sessionId !== state.ownerSessionId)
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The receipt belongs to another run owner.");
+    validateRunIntegrationReceipt(integration, receipt);
+    const note = await git(state.root, ["notes", "--ref=agent-ops", "show", integration.candidate]);
+    const noteText = note.stdout;
+    if (note.exitCode !== 0 || !noteText.includes(`session: ${state.ownerSessionId}`) ||
+        !noteText.includes(`receipt: ${integration.receiptPath}`) ||
+        !noteText.includes(`receipt-sha256: ${integration.receiptDigest}`)) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The sealed receipt is not bound by the Git note for the candidate.");
+    }
+    const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+    const exact = target.exitCode === 0 && target.stdout.trim() === integration.candidate;
+    const historic = !exact && target.exitCode === 0 && integration.completedSteps.includes("target") &&
+        integration.completedSteps.includes("receipt") && integration.completedSteps.includes("note") &&
+        (await git(state.root, ["merge-base", "--is-ancestor", integration.candidate, target.stdout.trim()])).exitCode === 0;
+    if (!exact && !historic)
+        throw new AgentOpsError("RUN_INTEGRATION_TARGET_CHANGED", "The target is inconsistent with the sealed, receipt-bound integration history.");
+    await repository.mutate(runId, current => {
+        if (current.integration === null || current.integration.transactionId !== integration.transactionId ||
+            current.integration.candidate !== integration.candidate || current.integration.expectedTarget !== integration.expectedTarget)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "The integration changed during recovery.");
+        if (current.integration.status === "cleaned")
+            return current;
+        if (current.integration.status !== "receipt-written")
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The integration is not at the cleanup recovery boundary.");
+        return { ...current, integration: { ...current.integration, status: "cleaned",
+                completedSteps: [...new Set([...current.integration.completedSteps, "coordinator"])], updatedAt: new Date().toISOString() } };
+    });
+    return { transactionId: integration.transactionId, receiptPath: integration.receiptPath, receiptDigest: integration.receiptDigest };
+}

package/dist/runtime/src/run/macOS.js

@@ -0,0 +1,189 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+const execFile = promisify(execFileCallback);
+function xml(value) {
+    return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;")
+        .replace(/"/gu, "&quot;").replace(/'/gu, "&apos;");
+}
+function shellSafe(value) {
+    return value.replace(/[^A-Za-z0-9._-]/gu, "-").slice(0, 60) || "worker";
+}
+function assertPathInside(root, candidate) {
+    const canonicalRoot = resolve(root);
+    const canonicalCandidate = resolve(candidate);
+    const fromRoot = relative(canonicalRoot, canonicalCandidate);
+    if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+        throw new AgentOpsError("LAUNCHD_PATH_INVALID", "launchd transient state escaped its private directory.");
+    }
+}
+function defaultUid() {
+    if (typeof process.getuid !== "function") {
+        throw new AgentOpsError("LAUNCHD_UID_UNAVAILABLE", "launchd requires a macOS user id.");
+    }
+    return process.getuid();
+}
+function defaultExecFile(file, args, options) {
+    return execFile(file, [...args], options).then((result) => ({
+        stdout: result.stdout,
+        stderr: result.stderr
+    }));
+}
+export function createLaunchdDescriptor(input) {
+    if (input.runId.length === 0 || input.workerId.length === 0 || input.command.length === 0 || input.cwd.length === 0) {
+        throw new AgentOpsError("LAUNCHD_DESCRIPTOR_INVALID", "launchd descriptor fields cannot be empty.");
+    }
+    const privateDirectory = resolve(input.privateDirectory);
+    const label = `com.agent-ops.run.${shellSafe(input.runId)}.${shellSafe(input.workerId)}.${createHash("sha256").update(input.runId).digest("hex").slice(0, 8)}`;
+    const path = join(privateDirectory, `${label}.plist`);
+    const disabledPath = join(privateDirectory, `${label}.disabled.json`);
+    assertPathInside(privateDirectory, path);
+    assertPathInside(privateDirectory, disabledPath);
+    const uid = input.uid ?? (process.platform === "darwin" ? defaultUid() : 0);
+    if (!Number.isSafeInteger(uid) || uid < 0) {
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "launchd user id is invalid.");
+    }
+    const stdoutPath = input.stdoutPath ?? join(privateDirectory, `${label}.stdout.log`);
+    const stderrPath = input.stderrPath ?? join(privateDirectory, `${label}.stderr.log`);
+    assertPathInside(privateDirectory, stdoutPath);
+    assertPathInside(privateDirectory, stderrPath);
+    const argumentsXml = [input.command, ...input.args]
+        .map((arg) => `    <string>${xml(arg)}</string>`)
+        .join("\n");
+    const xmlDocument = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argumentsXml}
+  </array>
+  <key>WorkingDirectory</key><string>${xml(input.cwd)}</string>
+${input.pathEnvironment === undefined ? "" : "  <key>EnvironmentVariables</key><dict><key>PATH</key><string>" + xml(input.pathEnvironment) + "</string></dict>"}
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict><key>SuccessfulExit</key><false/></dict>
+  <key>StandardOutPath</key><string>${xml(stdoutPath)}</string>
+  <key>StandardErrorPath</key><string>${xml(stderrPath)}</string>
+</dict>
+</plist>
+`;
+    return {
+        label,
+        domain: `gui/${uid}`,
+        path,
+        privateDirectory,
+        disabledPath,
+        xml: xmlDocument
+    };
+}
+export function compareBootLogin(saved, current) {
+    if (saved.boot !== current.boot) {
+        return { resume: false, reason: "boot-change" };
+    }
+    if (saved.login !== current.login) {
+        return { resume: false, reason: "login-change" };
+    }
+    return { resume: true, reason: "same-login" };
+}
+export async function readBootIdentity(platform = process.platform, run = defaultExecFile) {
+    if (platform !== "darwin") {
+        return `platform:${platform}`;
+    }
+    const result = await run("sysctl", ["-n", "kern.boottime"], {});
+    const value = result.stdout?.trim();
+    if (value === undefined || value.length === 0) {
+        throw new AgentOpsError("LAUNCHD_BOOT_IDENTITY_UNAVAILABLE", "macOS boot identity was empty.");
+    }
+    return value;
+}
+export function readLoginIdentity(uid = defaultUid()) {
+    if (!Number.isSafeInteger(uid) || uid < 0) {
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "macOS login user id is invalid.");
+    }
+    return `uid:${uid}:${process.env.LOGNAME ?? process.env.USER ?? "unknown"}`;
+}
+/** A uid alone survives logout/login; the GUI audit session identifies this login. */
+export async function readGuiLoginIdentity(uid = defaultUid(), run = defaultExecFile) {
+    if (!Number.isSafeInteger(uid) || uid < 0)
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "Invalid macOS login user id.");
+    const result = await run("launchctl", ["print", `gui/${uid}`], {});
+    const security = result.stdout?.match(/^\tsecurity context = \{[\s\S]*?^\t\}/mu)?.[0];
+    const auditSession = security?.match(/^\s*asid = ([0-9]+)$/mu)?.[1];
+    if (auditSession === undefined)
+        throw new AgentOpsError("LAUNCHD_LOGIN_IDENTITY_UNAVAILABLE", "Cannot identify the current GUI audit session.");
+    return `gui:${uid}:asid:${auditSession}`;
+}
+export class LaunchdController {
+    platform;
+    uid;
+    run;
+    constructor(options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.uid = options.uid ?? (this.platform === "darwin" ? defaultUid() : 0);
+        this.run = options.execFile ?? defaultExecFile;
+    }
+    get supported() {
+        return this.platform === "darwin";
+    }
+    async writeDescriptor(descriptor) {
+        this.assertSupported();
+        await writePrivateFile(descriptor.path, descriptor.xml, descriptor.privateDirectory);
+    }
+    async bootstrap(descriptor) {
+        this.assertSupported();
+        await this.run("launchctl", ["bootstrap", descriptor.domain, descriptor.path], {
+            cwd: descriptor.privateDirectory
+        });
+    }
+    async wake(descriptor) {
+        this.assertSupported();
+        try {
+            await this.bootstrap(descriptor);
+        }
+        catch {
+            await this.run("launchctl", ["kickstart", `${descriptor.domain}/${descriptor.label}`], { cwd: descriptor.privateDirectory });
+        }
+    }
+    async bootout(descriptor) {
+        this.assertSupported();
+        try {
+            await this.run("launchctl", ["bootout", `${descriptor.domain}/${descriptor.label}`], { cwd: descriptor.privateDirectory });
+        }
+        catch (cause) {
+            const failure = cause;
+            if (failure.code !== 3 || typeof failure.stderr !== "string" || !failure.stderr.includes("No such process"))
+                throw cause;
+        }
+    }
+    async disableRestart(descriptor, reason) {
+        this.assertSupported();
+        if (reason.length === 0 || reason.length > 512 || reason.includes("\0")) {
+            throw new AgentOpsError("LAUNCHD_DISABLE_REASON_INVALID", "launchd disable reason is invalid.");
+        }
+        await writePrivateFile(descriptor.disabledPath, `${JSON.stringify({ disabled: true, reason, at: new Date().toISOString() })}\n`, descriptor.privateDirectory);
+        await this.run("launchctl", ["disable", `${descriptor.domain}/${descriptor.label}`], {
+            cwd: descriptor.privateDirectory
+        });
+    }
+    async isRestartDisabled(descriptor) {
+        return (await readPrivateFile(descriptor.disabledPath, descriptor.privateDirectory)) !== null;
+    }
+    async enableRestart(descriptor) {
+        this.assertSupported();
+        await this.run("launchctl", ["enable", `${descriptor.domain}/${descriptor.label}`], {
+            cwd: descriptor.privateDirectory
+        });
+        await rm(descriptor.disabledPath, { force: true });
+    }
+    assertSupported() {
+        if (!this.supported) {
+            throw new AgentOpsError("LAUNCHD_UNSUPPORTED", "Transient launchd primitives require macOS.");
+        }
+    }
+}

package/dist/runtime/src/run/ownership.js

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import { FileRunRepository } from "./service.js";
+/** The common run ledger, rather than worker-local metadata, grants writer ownership. */
+export async function registeredRunWriter(record, sessionId, agentId) {
+    if (record.runId === undefined || record.workerId === undefined || record.workerGeneration === undefined)
+        return false;
+    try {
+        const common = join(record.mainRoot, ".git");
+        const state = await new FileRunRepository(join(common, "agent-ops", "runs"), common).read(record.runId);
+        const worker = state?.workers.find(w => w.workerId === record.workerId);
+        return state !== null && state !== undefined && state.status === "active" && !state.disableRestart &&
+            worker !== undefined && worker.worktree === record.path && worker.generation === record.workerGeneration &&
+            worker.ownerSessionId === record.ownerSessionId && state.coordinatorId === record.coordinatorId &&
+            ["running", "idle"].includes(worker.status) && worker.stopIntent === null &&
+            (worker.nativeSessionId === sessionId || worker.ownerSessionId === sessionId) &&
+            worker.leaseExpiresAt !== null && Date.parse(worker.leaseExpiresAt) > Date.now() &&
+            (agentId === undefined || agentId === record.agentId);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime/src/run/planning.js

@@ -0,0 +1,25 @@
+import { AgentOpsError } from "../fs/paths.js";
+import { validateCriterion } from "../schema/validate.js";
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 4096 && !v.includes("\0");
+/** Validate a deferred worker plan without freezing criteria before dependencies are delivered. */
+export function workerPlan(value, taskId, state) {
+    if (!plain(value) || Object.keys(value).some(k => !["title", "intent", "criteria", "dependencies"].includes(k)) ||
+        !text(value.title) || !text(value.intent) || !Array.isArray(value.criteria) || value.criteria.length < 2 || value.criteria.length > 5 ||
+        !Array.isArray(value.dependencies) || value.dependencies.length > 512 || new Set(value.dependencies).size !== value.dependencies.length ||
+        value.dependencies.some(id => typeof id !== "string" || id === state.rootTaskId || !state.tasks.some(task => task.taskId === id)))
+        throw new AgentOpsError("RUN_WORKER_PLAN_INVALID", "Worker plans require 2–5 criteria and known non-coordinator dependencies.");
+    const ids = new Set();
+    const criteria = value.criteria.map((criterion, index) => {
+        if (!plain(criterion) || criterion.finding !== undefined || (plain(criterion.acceptance) && criterion.acceptance.baselineCommit !== undefined))
+            throw new AgentOpsError("RUN_WORKER_BASELINE_DEFERRED", "New worker baselines are captured only after dependencies enter its checkout; finding pins belong to an existing task.");
+        const normalized = { ...criterion, ...(plain(criterion.acceptance) ? { acceptance: { ...criterion.acceptance, baselineCommit: "0".repeat(40) } } : {}) };
+        const checked = validateCriterion(normalized, `$.criteria[${index}]`);
+        if (!checked.ok || ids.has(checked.value.id))
+            throw new AgentOpsError("RUN_WORKER_PLAN_INVALID", "Worker criteria must be unique valid contracts.");
+        ids.add(checked.value.id);
+        // TaskService.create resolves the real checkout SHA when this worker starts.
+        return structuredClone(criterion);
+    });
+    return { taskId, title: value.title, intent: value.intent, criteria, dependencies: [...value.dependencies] };
+}