@kylecheng3146/agent-ops 0.5.3 → 0.6.0

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

@@ -0,0 +1,176 @@
+import { readdir, readFile, lstat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalJson, calculateConfigHash } from "../config/hash.js";
+import { mergeConfigLayers } from "../config/merge.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { evaluateGuardrail } from "../guardrails/evaluate.js";
+import { validateConfig } from "../schema/validate.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { redactSecrets } from "../security/redact.js";
+import { activeWallTimeMs } from "./scheduler.js";
+function fail(code, message) { throw new AgentOpsError(code, message); }
+const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function validApprovals(value) {
+    return Array.isArray(value) && value.length <= 100 && value.every(a => plain(a) &&
+        Object.keys(a).every(key => ["capabilityId", "classification", "reason"].includes(key)) &&
+        typeof a.capabilityId === "string" && /^(?:command|runner|setup):[^\s\0]{1,128}$/u.test(a.capabilityId) &&
+        a.classification === "non-dangerous" && typeof a.reason === "string" && a.reason.trim().length > 0 &&
+        a.reason.length <= 4096 && !a.reason.includes("\0"));
+}
+function validBaseBinding(value, root) {
+    return plain(value) && Object.keys(value).every(key => ["canonicalPath", "remoteIdentity", "configHash", "runtimeHash"].includes(key)) &&
+        value.canonicalPath === root && isAbsolute(root) && typeof value.remoteIdentity === "string" && value.remoteIdentity.length > 0 &&
+        typeof value.configHash === "string" && /^[a-f0-9]{64}$/u.test(value.configHash) && typeof value.runtimeHash === "string" && /^[a-f0-9]{64}$/u.test(value.runtimeHash);
+}
+/** Hash executable toolkit modules, rather than only its package version. */
+export async function runRuntimeHash() {
+    const root = fileURLToPath(new URL("../../../", import.meta.url));
+    const entries = [];
+    async function walk(relative) {
+        for (const name of (await readdir(join(root, relative))).sort()) {
+            const path = join(relative, name), absolute = join(root, path), stat = await lstat(absolute);
+            if (stat.isSymbolicLink())
+                fail("RUN_RUNTIME_CHANGED", "Run runtime cannot contain symlinks.");
+            if (stat.isDirectory())
+                await walk(path);
+            else if (stat.isFile() && name.endsWith(".js"))
+                entries.push({ path, digest: sha256(await readFile(absolute)) });
+        }
+    }
+    await walk("runtime");
+    await walk("packages/cli");
+    return sha256(canonicalJson(entries));
+}
+function capabilities(config) {
+    return new Map([
+        ...config.verification.commands.map(command => ["command:" + command.id, command]),
+        ...(config.verification.acceptanceRunners ?? []).map(runner => ["runner:" + runner.id, runner]),
+        ...(config.worktree?.setup ?? []).map((command, index) => ["setup:" + index, command])
+    ]);
+}
+/** A renewal preserves earlier assessments; it does not turn them into user trust. */
+export async function runPolicyAssessment(state, policy, capabilityId) {
+    const definition = capabilities(policy.config).get(capabilityId);
+    if (definition === undefined)
+        fail("RUN_POLICY_APPROVAL_REQUIRED", "Execution capability is absent from the current policy.");
+    if (canonicalJson(capabilities(policy.baseConfig).get(capabilityId) ?? null) === canonicalJson(definition))
+        return null;
+    let current = policy;
+    for (let depth = 0; depth < 128; depth++) {
+        const assessment = current.approvals.find(a => a.capabilityId === capabilityId);
+        if (assessment !== undefined && canonicalJson(capabilities(current.config).get(capabilityId) ?? null) === canonicalJson(definition))
+            return assessment;
+        if (current.previousDigest === null)
+            break;
+        const source = await readPrivateFile(join(state.commonDir, "agent-ops/runs", state.runId, "policies", current.previousDigest + ".json"), state.commonDir);
+        if (source === null || sha256(source) !== current.previousDigest)
+            fail("RUN_POLICY_CHANGED", "Historical capability assessment is missing or changed.");
+        const previous = JSON.parse(source);
+        current = (await readRunPolicy({ ...state, policyBinding: { artifactDigest: current.previousDigest, configHash: calculateConfigHash(previous.config),
+                runtimeHash: previous.runtimeHash, expiresAt: previous.expiresAt } }, previous.runtimeHash, Date.now(), true));
+    }
+    return fail("RUN_POLICY_APPROVAL_REQUIRED", "The current capability lacks a matching historical run assessment.");
+}
+/** Existing monotonic policy merging remains authoritative during a run. */
+export function validateRunPolicyChange(previous, candidate, approvals) {
+    if (!validateConfig(previous).ok || !validateConfig(candidate).ok)
+        fail("RUN_POLICY_INVALID", "Proposed run policy is invalid.");
+    if (!validApprovals(approvals))
+        fail("RUN_POLICY_APPROVAL_REQUIRED", "Policy assessments require strict bounded capability identities and reasons.");
+    for (const field of ["features", "reviewRoles", "securityExceptions"])
+        if (canonicalJson(previous[field] ?? null) !== canonicalJson(candidate[field] ?? null))
+            fail("RUN_POLICY_GUARDRAIL_CHANGED", "A run cannot change completion, review or security policy.");
+    if (previous.worktree?.mode !== candidate.worktree?.mode)
+        fail("RUN_POLICY_GUARDRAIL_CHANGED", "A run cannot change worktree isolation.");
+    const config = mergeConfigLayers([{ source: "user", sourcePath: "run baseline", config: previous },
+        { source: "project", sourcePath: "coordinator proposal", config: candidate }]).config;
+    const before = capabilities(previous), after = capabilities(config);
+    const changed = [...after].filter(([id, value]) => canonicalJson(value) !== canonicalJson(before.get(id) ?? null));
+    if (new Set(approvals.map(a => a.capabilityId)).size !== approvals.length || approvals.length !== changed.length)
+        fail("RUN_POLICY_APPROVAL_REQUIRED", "Every changed execution capability needs its own run-scoped review.");
+    for (const [id, value] of changed) {
+        const approval = approvals.find(a => a.capabilityId === id);
+        if (approval?.classification !== "non-dangerous" || typeof approval.reason !== "string" ||
+            approval.reason.trim().length === 0 || approval.reason.length > 4096 || approval.reason.includes("\0"))
+            fail("RUN_POLICY_APPROVAL_REQUIRED", "Changed runner, command and setup definitions require a non-dangerous assessment and reason.");
+        const definition = value;
+        for (const command of [definition, ...(definition.setup ?? []), ...(definition.build ?? []), ...(definition.testBuild ?? [])]) {
+            const decision = evaluateGuardrail({ kind: "command", command: command.command, args: command.args, scope: "." });
+            if (decision.action !== "allow")
+                fail("RUN_POLICY_COMMAND_DENIED", "A guarded capability needs explicit user approval; a run cannot grant it automatically.");
+        }
+    }
+    if (evaluateGuardrail({ kind: "content", content: canonicalJson(config), scope: "." }).action === "block")
+        fail("RUN_POLICY_SECRET", "Policy must use secret references, not literal credentials.");
+    return config;
+}
+export async function readRunPolicy(state, runtimeHash, now = Date.now(), allowExpired = false) {
+    const binding = state.policyBinding;
+    if (binding === undefined)
+        return null;
+    const path = join(state.commonDir, "agent-ops", "runs", state.runId, "policies", binding.artifactDigest + ".json");
+    const source = await readPrivateFile(path, state.commonDir);
+    if (source === null || Buffer.byteLength(source) > 512 * 1024 || sha256(source) !== binding.artifactDigest)
+        fail("RUN_POLICY_CHANGED", "Run policy artifact is missing or changed.");
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return fail("RUN_POLICY_INVALID", "Run policy JSON is invalid.");
+    }
+    if (!plain(parsed) || Object.keys(parsed).some(key => !["schemaVersion", "runId", "config", "baseConfig", "baseTrustBinding", "runtimeHash", "expiresAt", "approvals", "previousDigest"].includes(key)) ||
+        !validBaseBinding(parsed.baseTrustBinding, state.root) || !validApprovals(parsed.approvals) ||
+        !(parsed.previousDigest === null || (typeof parsed.previousDigest === "string" && /^[a-f0-9]{64}$/u.test(parsed.previousDigest))))
+        fail("RUN_POLICY_INVALID", "Run policy artifact has an invalid structure or trust origin.");
+    const artifact = parsed;
+    if (artifact.schemaVersion !== 1 || artifact.runId !== state.runId || !validateConfig(artifact.config).ok ||
+        !validateConfig(artifact.baseConfig).ok || calculateConfigHash(artifact.config) !== binding.configHash ||
+        artifact.runtimeHash !== binding.runtimeHash || artifact.expiresAt !== binding.expiresAt ||
+        artifact.baseTrustBinding?.configHash !== calculateConfigHash(artifact.baseConfig))
+        fail("RUN_POLICY_INVALID", "Run policy does not match its ledger binding.");
+    if (runtimeHash !== binding.runtimeHash)
+        fail("RUN_RUNTIME_CHANGED", "The executable run runtime changed; preserve the checkout and revalidate before resume.");
+    if (!allowExpired && Date.parse(binding.expiresAt) <= now)
+        fail("RUN_POLICY_EXPIRED", "Run-scoped execution authorization expired.");
+    return artifact;
+}
+/** No user/repository trust record is created or changed. */
+export async function bindRunPolicy(repository, runId, input) {
+    const state = await repository.read(runId);
+    if (state === null)
+        return fail("RUN_NOT_FOUND", "Run does not exist.");
+    const now = input.now ?? Date.now();
+    if (!Number.isFinite(now) || !validBaseBinding(input.baseTrustBinding, state.root))
+        fail("RUN_POLICY_INVALID", "Policy requires the original canonical repository trust binding and a valid clock.");
+    const previous = await readRunPolicy(state, input.resumeRuntime === true ? state.policyBinding?.runtimeHash ?? input.runtimeHash : input.runtimeHash, now, true);
+    if ((state.policyBinding?.artifactDigest ?? undefined) !== input.expectedDigest)
+        fail("RUN_POLICY_STALE", "The run policy changed before this assessment.");
+    if (state.status !== "active" || state.disableRestart || state.awaitingResume)
+        fail("RUN_POLICY_DISABLED", "Only an active run can acquire execution authorization.");
+    if (state.proofProcess != null)
+        fail("RUN_POLICY_WRITER_ACTIVE", "Confirm the registered proof process is dead before rebinding execution policy.");
+    if (previous !== null && state.workers.some(w => w.proofProcess != null || !["stopped", "fenced", "delivered", "blocked"].includes(w.status) ||
+        (w.processId !== null && w.stopIntent?.confirmedDeadAt == null)))
+        fail("RUN_POLICY_WRITER_ACTIVE", "Stop and confirm every writer before changing its execution policy.");
+    const config = previous === null ? input.config : validateRunPolicyChange(previous.config, input.config, input.approvals ?? []);
+    if (!validateConfig(config).ok || !/^[a-f0-9]{64}$/u.test(input.runtimeHash) ||
+        (previous === null && input.baseTrustBinding.configHash !== calculateConfigHash(config)))
+        fail("RUN_POLICY_INVALID", "Run policy or runtime identity is invalid.");
+    const remaining = state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, now);
+    if (remaining <= 0)
+        fail("RUN_BUDGET_EXHAUSTED", "No active execution budget remains.");
+    const artifact = { schemaVersion: 1, runId, config, baseConfig: previous?.baseConfig ?? config,
+        baseTrustBinding: previous?.baseTrustBinding ?? input.baseTrustBinding, runtimeHash: input.runtimeHash,
+        expiresAt: new Date(now + remaining).toISOString(), approvals: (input.approvals ?? []).map(a => ({ ...a, reason: redactSecrets(a.reason) })), previousDigest: previous === null ? null : state.policyBinding.artifactDigest };
+    const content = canonicalJson(artifact), digest = sha256(content);
+    await writePrivateFile(join(state.commonDir, "agent-ops", "runs", runId, "policies", digest + ".json"), content, state.commonDir);
+    return await repository.mutate(runId, current => {
+        if (current.revision !== state.revision || (current.policyBinding?.artifactDigest ?? undefined) !== input.expectedDigest || current.status !== "active" || current.disableRestart)
+            return fail("RUN_POLICY_STALE", "The run stopped or its policy changed during assessment.");
+        return { ...current, policyBinding: { configHash: calculateConfigHash(config), runtimeHash: input.runtimeHash,
+                artifactDigest: digest, expiresAt: artifact.expiresAt } };
+    });
+}

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

@@ -0,0 +1,71 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { readPrivateFile } from "../security/permissions.js";
+import { REVIEW_ATTESTATION_DIRECTORY, reviewReportDigest } from "../review/attestation.js";
+import { validateReviewReport } from "../review/report.js";
+import { goalHash } from "../task/contract.js";
+import { loadFindingPin } from "../task/pin-finding.js";
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Failed blocking findings need an explicit pin or a recorded recurrence before the next final gate. */
+export async function pendingFindingPins(root, tasks, rootTaskId) {
+    const owner = tasks.find(record => record.task.id === rootTaskId);
+    if (owner === undefined)
+        return [];
+    const pending = new Set();
+    const currentTasks = tasks.filter(record => record.status !== "archived" && record.supersededBy === undefined);
+    const directory = join(root, REVIEW_ATTESTATION_DIRECTORY);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return [];
+    }
+    for (const name of names.filter(n => /^[a-f0-9]{64}(?:\.[a-z][a-z0-9-]{0,127})?\.reports\.json$/u.test(n))) {
+        const source = await readPrivateFile(join(directory, name), root);
+        if (source === null || Buffer.byteLength(source) > 512 * 1024)
+            continue;
+        let artifact;
+        try {
+            artifact = JSON.parse(source);
+        }
+        catch {
+            continue;
+        }
+        if (!plain(artifact) || artifact.schemaVersion !== 2 || artifact.status !== "FAIL" || artifact.goalHash !== goalHash(owner.task) ||
+            !plain(artifact.taskContracts) || !Object.keys(artifact.taskContracts).some(id => tasks.some(record => record.task.id === id)))
+            continue;
+        for (const report of [artifact.report, plain(artifact.adversarial) ? artifact.adversarial.report : undefined]) {
+            if (!plain(report) || !Array.isArray(report.results) || report.results.some(r => !plain(r) || typeof r.criterionId !== "string"))
+                continue;
+            const checked = validateReviewReport(report, report.results.map(r => r.criterionId));
+            if (!checked.ok)
+                continue;
+            const digest = reviewReportDigest(checked.value);
+            for (const [index, finding] of checked.value.findings.entries()) {
+                if (!finding.blocking)
+                    continue;
+                const reference = digest + ":" + index;
+                const pin = sha256(reference);
+                let pinned = currentTasks.some(record => record.task.criteria.some(c => c.finding?.pinId === pin));
+                if (!pinned)
+                    for (const record of currentTasks) {
+                        for (const criterion of record.task.criteria.filter(c => c.finding !== undefined)) {
+                            if (!record.revisions?.some(revision => revision.diagnostics.includes("finding:" + reference) &&
+                                revision.diagnostics.includes("pin:" + criterion.finding.pinId)))
+                                continue;
+                            try {
+                                await loadFindingPin(root, record, reference, criterion, tasks);
+                                pinned = true;
+                            }
+                            catch { /* A claimed recurrence without saved source authority cannot discharge a finding. */ }
+                        }
+                    }
+                if (!pinned)
+                    pending.add(reference);
+            }
+        }
+    }
+    return [...pending].sort();
+}

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

@@ -0,0 +1,260 @@
+import { AgentOpsError } from "../fs/paths.js";
+import { MAX_ACTIVE_WORKERS } from "./service.js";
+const ID = /^[A-Za-z0-9._:/-]{1,256}$/u;
+function error(code, message) {
+    return new AgentOpsError(code, message);
+}
+function replaceTask(state, taskId, update) {
+    const index = state.tasks.findIndex((task) => task.taskId === taskId);
+    if (index < 0)
+        throw error("RUN_TASK_NOT_FOUND", `Run task not found: ${taskId}`);
+    const tasks = [...state.tasks];
+    tasks[index] = { ...tasks[index], ...update };
+    return { ...state, tasks };
+}
+function dependencyState(tasks, task) {
+    const byId = new Map(tasks.map((candidate) => [candidate.taskId, candidate]));
+    let waiting = false;
+    for (const dependency of task.dependencies) {
+        const parent = byId.get(dependency);
+        if (parent === undefined || parent.status === "blocked")
+            return "blocked";
+        if (!["delivered", "complete"].includes(parent.status))
+            waiting = true;
+    }
+    return waiting ? "waiting" : "ready";
+}
+/** Validate the explicit dependency DAG; parentTaskId alone is not enough. */
+export function validateRunDag(tasks) {
+    const ids = new Set();
+    for (const task of tasks) {
+        if (!ID.test(task.taskId) || ids.has(task.taskId))
+            throw error("RUN_DAG_INVALID", `Task identity is duplicated or invalid: ${task.taskId}`);
+        ids.add(task.taskId);
+        if (task.dependencies.some((dependency) => dependency === task.taskId || !ID.test(dependency))) {
+            throw error("RUN_DAG_INVALID", `Task ${task.taskId} has an invalid self or malformed dependency.`);
+        }
+    }
+    for (const task of tasks) {
+        for (const dependency of task.dependencies) {
+            if (!ids.has(dependency))
+                throw error("RUN_DAG_MISSING_DEPENDENCY", `Task ${task.taskId} depends on missing ${dependency}.`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const byId = new Map(tasks.map((task) => [task.taskId, task]));
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw error("RUN_DAG_CYCLE", `Run task dependency cycle includes ${id}.`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of byId.get(id).dependencies)
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const task of tasks)
+        visit(task.taskId);
+}
+export function planSchedule(state) {
+    validateRunDag(state.tasks);
+    const running = state.tasks.filter((task) => task.status === "running" || task.status === "awaiting-delivery");
+    const blocked = state.tasks.filter((task) => task.status === "blocked");
+    const ready = state.tasks.filter((task) => ["planned", "ready"].includes(task.status) && dependencyState(state.tasks, task) === "ready");
+    return {
+        ready,
+        running,
+        blocked,
+        availableSlots: Math.max(0, Math.min(state.jobs, MAX_ACTIVE_WORKERS) - running.length)
+    };
+}
+/**
+ * Compute whole-run active wall time as the union of intervals. This prevents
+ * two parallel writers from doubling the 60-minute run budget.
+ */
+export function activeWallTimeMs(intervals, nowMs) {
+    if (!Number.isFinite(nowMs) || nowMs < 0)
+        throw error("RUN_CLOCK_INVALID", "Budget clock is invalid.");
+    const sorted = intervals
+        .map(({ startMs, endMs }) => ({ startMs, endMs: endMs ?? nowMs }))
+        .filter(({ startMs, endMs }) => Number.isFinite(startMs) && Number.isFinite(endMs) && startMs >= 0 && endMs >= startMs)
+        .sort((left, right) => left.startMs - right.startMs);
+    let total = 0;
+    let start = null;
+    let end = 0;
+    for (const interval of sorted) {
+        if (start === null) {
+            start = interval.startMs;
+            end = interval.endMs;
+            continue;
+        }
+        if (interval.startMs <= end) {
+            end = Math.max(end, interval.endMs);
+            continue;
+        }
+        total += end - start;
+        start = interval.startMs;
+        end = interval.endMs;
+    }
+    return start === null ? 0 : total + end - start;
+}
+export function budgetExpired(state, now = Date.now()) {
+    return activeWallTimeMs(state.budget.activeIntervals, now) >= state.budget.limitMs;
+}
+/** Two consecutive identical failure rounds without a useful change stop one child. */
+export function noProgressForTwoRounds(rounds) {
+    if (rounds.length < 2)
+        return false;
+    const current = rounds[rounds.length - 1];
+    const previous = rounds[rounds.length - 2];
+    return !current.usefulProgress && !previous.usefulProgress &&
+        current.taskId === previous.taskId &&
+        current.failureClass === previous.failureClass &&
+        current.failureId === previous.failureId &&
+        current.diagnosticDigest === previous.diagnosticDigest;
+}
+/** Persistent scheduler operations. Native writers are started by supervisor. */
+export class RunScheduler {
+    #repository;
+    #now;
+    constructor(options) {
+        this.#repository = options.repository;
+        this.#now = options.now ?? (() => new Date().toISOString());
+    }
+    async addTasks(runId, tasks) {
+        return await this.#repository.mutate(runId, (current) => {
+            if (current.status !== "active" || current.disableRestart)
+                throw error("RUN_NOT_ACTIVE", "Only an active run can plan workers.");
+            const combined = [...current.tasks, ...tasks.map((task) => ({ ...task, status: "planned", workerId: null, deliveryDigest: null, sourceCommit: null, blockedReason: null }))];
+            validateRunDag(combined);
+            if (combined.length > 512)
+                throw error("RUN_DAG_INVALID", "Run task limit exceeded.");
+            return { ...current, tasks: combined };
+        });
+    }
+    async plan(runId) {
+        const state = await this.#repository.read(runId);
+        if (state === null)
+            throw error("RUN_NOT_FOUND", `Run not found: ${runId}`);
+        return planSchedule(state);
+    }
+    async markReady(runId) {
+        return await this.#repository.mutate(runId, (current) => {
+            validateRunDag(current.tasks);
+            let next = current;
+            for (const task of [...next.tasks]) {
+                if (!["planned", "ready"].includes(task.status))
+                    continue;
+                const state = dependencyState(next.tasks, task);
+                if (state === "blocked")
+                    next = replaceTask(next, task.taskId, { status: "blocked", blockedReason: "dependency-blocked" });
+                else if (state === "ready")
+                    next = replaceTask(next, task.taskId, { status: "ready" });
+            }
+            return next;
+        });
+    }
+    async markDelivered(runId, taskId, deliveryDigest, sourceCommit) {
+        return await this.#repository.mutate(runId, (current) => {
+            const task = current.tasks.find((candidate) => candidate.taskId === taskId);
+            if (task === undefined)
+                throw error("RUN_TASK_NOT_FOUND", `Run task not found: ${taskId}`);
+            if (task.status === "delivered" && task.deliveryDigest === deliveryDigest && task.sourceCommit === sourceCommit)
+                return current;
+            if (!["running", "awaiting-delivery", "ready"].includes(task.status))
+                throw error("RUN_TASK_STATE_INVALID", `Task ${taskId} cannot be delivered from ${task.status}.`);
+            return replaceTask(current, taskId, { status: "delivered", deliveryDigest, sourceCommit });
+        });
+    }
+    async completeTask(runId, taskId) {
+        return await this.#repository.mutate(runId, (current) => {
+            const task = current.tasks.find((candidate) => candidate.taskId === taskId);
+            if (task === undefined || task.status !== "delivered")
+                throw error("RUN_TASK_NOT_DELIVERED", `Task ${taskId} is not delivered.`);
+            return replaceTask(current, taskId, { status: "complete" });
+        });
+    }
+    async blockTaskAndDependents(runId, taskId, reason, onlyWhileActive = false) {
+        const boundedReason = reason.slice(0, 4096);
+        return await this.#repository.mutate(runId, (current) => {
+            if (onlyWhileActive && (current.status !== "active" || current.disableRestart))
+                return current;
+            const ids = new Set([taskId]);
+            let changed = true;
+            while (changed) {
+                changed = false;
+                for (const task of current.tasks) {
+                    if (task.dependencies.some((dependency) => ids.has(dependency)) && !ids.has(task.taskId)) {
+                        ids.add(task.taskId);
+                        changed = true;
+                    }
+                }
+            }
+            let next = current;
+            for (const id of ids) {
+                const task = next.tasks.find((candidate) => candidate.taskId === id);
+                if (task !== undefined && task.status !== "complete")
+                    next = replaceTask(next, id, { status: "blocked", blockedReason: boundedReason });
+            }
+            return next;
+        });
+    }
+    /** Return only tasks which are safe to assign in this scheduling turn. */
+    async next(runId) {
+        const plan = await this.plan(runId);
+        return plan.ready.slice(0, plan.availableSlots);
+    }
+    /** Useful for status output and for native adapters that report worker state. */
+    async workerCount(runId) {
+        const state = await this.#repository.read(runId);
+        if (state === null)
+            throw error("RUN_NOT_FOUND", `Run not found: ${runId}`);
+        return state.workers.filter((worker) => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)).length;
+    }
+    async openBudgetInterval(runId, startMs) {
+        if (!Number.isSafeInteger(startMs) || startMs < 0)
+            throw error("RUN_CLOCK_INVALID", "Budget interval start is invalid.");
+        return await this.#repository.mutate(runId, (current) => {
+            if (current.budget.activeIntervals.some((interval) => interval.startMs === startMs && interval.endMs === null))
+                return current;
+            return {
+                ...current,
+                budget: {
+                    ...current.budget,
+                    activeIntervals: [...current.budget.activeIntervals, { startMs, endMs: null }]
+                }
+            };
+        });
+    }
+    async closeBudgetInterval(runId, startMs, endMs) {
+        if (!Number.isSafeInteger(startMs) || !Number.isSafeInteger(endMs) || startMs < 0 || endMs < startMs)
+            throw error("RUN_CLOCK_INVALID", "Budget interval is invalid.");
+        return await this.#repository.mutate(runId, (current) => {
+            let closed = false;
+            const intervals = current.budget.activeIntervals.map((interval) => {
+                if (!closed && interval.startMs === startMs && interval.endMs === null) {
+                    closed = true;
+                    return { ...interval, endMs };
+                }
+                return interval;
+            });
+            const accumulatedMs = activeWallTimeMs(intervals, endMs);
+            return { ...current, budget: { ...current.budget, activeIntervals: intervals, accumulatedMs, lastObservedAt: new Date(endMs).toISOString() } };
+        });
+    }
+    async refreshBudget(runId, nowMs = Date.now()) {
+        if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+            throw error("RUN_CLOCK_INVALID", "Budget clock is invalid.");
+        return await this.#repository.mutate(runId, (current) => {
+            const accumulatedMs = activeWallTimeMs(current.budget.activeIntervals, nowMs);
+            const expired = accumulatedMs >= current.budget.limitMs;
+            return {
+                ...current,
+                status: expired && ["active", "awaiting-input"].includes(current.status) ? "budget-limited" : current.status,
+                budget: { ...current.budget, accumulatedMs, lastObservedAt: new Date(nowMs).toISOString() }
+            };
+        });
+    }
+}