@tea-agent/loop-agent 0.43.0-next.9 → 0.43.0

package/dist/worker/scheduler/scheduled-goal-store.js

@@ -0,0 +1,699 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { evaluateScheduledGoalWake } from "./scheduled-goal-time.js";
+import { captureScheduledGoalTree } from "./scheduled-goal-evidence.js";
+import { scheduledGoalDraftSchema, scheduledGoalRecordSchema, scheduledGoalOperationObservationSchema, scheduledGoalAssessmentSchema, scheduledGoalProposalSchema, } from "./scheduled-goal-types.js";
+const stateSchema = z.object({ schemaVersion: z.literal(1), goals: z.array(scheduledGoalRecordSchema) }).strict();
+const execFileAsync = promisify(execFile);
+const holdsWriterSlot = (intent) => ["dispatching", "associated", "unknown"].includes(intent.state);
+const holdsResource = (goal) => Boolean(goal.assessmentAttempt) || goal.intents.some(holdsWriterSlot) || goal.supervisions.some((entry) => ["requested", "proposed", "preparing", "unknown"].includes(entry.state));
+async function syncDirectory(directoryPath) {
+    const directory = await open(directoryPath, "r");
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function assertInitialFrozenTree(frozen) {
+    const tree = await captureScheduledGoalTree(frozen.worktreeRef, frozen.frozenBase, frozen.allowedPaths, frozen.forbiddenPaths);
+    if (tree.changedPaths.length)
+        throw new Error(`initial worktree differs from frozen base: ${tree.changedPaths.join(", ")}`);
+}
+async function assertExecutionWorkspace(repoRef, worktreeRef, base) {
+    const git = async (cwd, args) => (await execFileAsync("git", ["-C", cwd, ...args], { timeout: 30_000, encoding: "utf8" })).stdout.trim();
+    try {
+        const [top, common, controlCommon, gitDir, head] = await Promise.all([
+            git(worktreeRef, ["rev-parse", "--show-toplevel"]),
+            git(worktreeRef, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+            git(repoRef, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+            git(worktreeRef, ["rev-parse", "--absolute-git-dir"]),
+            git(worktreeRef, ["rev-parse", "HEAD"]),
+        ]);
+        if (await realpath(top) !== worktreeRef || await realpath(common) !== await realpath(controlCommon)
+            || (worktreeRef !== repoRef && await realpath(gitDir) === await realpath(common)) || head !== base)
+            throw new Error("worktree identity/base mismatch");
+    }
+    catch (error) {
+        throw new Error(`scheduled goal requires the current repository or its linked git worktree at frozen base: ${String(error)}`);
+    }
+}
+export function scheduledGoalHash(value) {
+    const canonical = (item) => Array.isArray(item) ? item.map(canonical)
+        : item !== null && typeof item === "object"
+            ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, canonical(entry)])) : item;
+    return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+/** Canonical IDs are required by workflow lineage stores, not just the CLI.
+ * Use the frozen UTC date so a later wake never changes an intent's identity. */
+function scheduledGoalRunId(goal, key) {
+    const day = goal.frozen.time.executeAtUtc.slice(0, 10).replaceAll("-", "");
+    return `${day}-sg-${key.slice(0, 32)}`;
+}
+/** Stable delivery identity excludes delivery bookkeeping and wake-only state versions. */
+export function scheduledGoalDeliveryKey(goal) {
+    return scheduledGoalHash([goal.goalId, goal.goalRevision, goal.state, goal.acceptanceState,
+        goal.reasonCode ?? null, goal.evidence.at(-1)?.evidenceId ?? null, goal.intents.at(-1)?.state ?? null]);
+}
+/**
+ * One repository admission ledger: root envelope, budget, intent and journal are
+ * one atomic commit. The cross-process mutex is never automatically stolen.
+ * A crash leaving it behind requires explicit reconciliation, not a second writer.
+ */
+export class ScheduledGoalStore {
+    repoRoot;
+    root;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+        this.root = path.resolve(repoRoot, ".harness/scheduled-goals");
+    }
+    async get(goalId) {
+        return this.requireGoal(await this.read(), goalId);
+    }
+    async recordDelivery(goalId, key, delivery) {
+        await this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (scheduledGoalDeliveryKey(goal) !== key)
+                throw new Error("delivery result changed");
+            if (goal.deliveryKey === key && goal.deliveryState === delivery)
+                return;
+            goal.deliveryKey = key;
+            goal.deliveryState = delivery;
+            this.event(goal, `result_delivery:${delivery}`, new Date());
+        });
+    }
+    async list() { return (await this.read()).goals; }
+    async createDraft(input, now) {
+        const frozen = scheduledGoalDraftSchema.parse(input);
+        const repoRef = await realpath(this.repoRoot);
+        frozen.worktreeRef = await realpath(frozen.worktreeRef);
+        await assertExecutionWorkspace(repoRef, frozen.worktreeRef, frozen.frozenBase);
+        await assertInitialFrozenTree(frozen);
+        const resourceKey = scheduledGoalHash([repoRef, frozen.managedTaskId]);
+        return this.transaction((state) => {
+            now ??= new Date();
+            if (state.goals.some((goal) => goal.resourceKey === resourceKey && !["cancelled", "accepted"].includes(goal.state)))
+                throw new Error("managed task already reserved by a scheduled goal");
+            const goal = {
+                schemaVersion: 1, goalId: `sg-${randomUUID()}`, goalRevision: 1, stateVersion: 1,
+                repoRef, resourceKey, envelopeHash: scheduledGoalHash({ repoRef, frozen, goalRevision: 1 }), frozen,
+                state: "planned", used: { turns: 0, dagRuns: 0, supervisorCalls: 0 }, intents: [],
+                acceptanceState: "not_started", evidence: [], supervisions: [], deliveryState: "not_requested",
+                journal: [{ version: 1, at: now.toISOString(), event: "draft_created" }],
+            };
+            state.goals.push(goal);
+            return goal;
+        });
+    }
+    /** Human-facing adapter supplies the exact reviewed hash and immutable approval reference. */
+    async approve(goalId, expectedVersion, envelopeHash, approvalRef, now) {
+        const before = await this.get(goalId);
+        await assertExecutionWorkspace(before.repoRef, before.frozen.worktreeRef, before.frozen.frozenBase);
+        await assertInitialFrozenTree(before.frozen);
+        return this.transaction((state) => {
+            now ??= new Date();
+            const goal = this.requireGoal(state, goalId);
+            if (goal.stateVersion !== expectedVersion || goal.state !== "planned" || goal.envelopeHash !== envelopeHash || !approvalRef.trim())
+                throw new Error("approval binding mismatch");
+            if (now.toISOString() >= goal.frozen.time.expiresAt)
+                throw new Error("authorization expired");
+            goal.approval = { approvalRef, approvedAt: now.toISOString(), envelopeHash, approvedVersion: expectedVersion };
+            goal.state = "authorized";
+            this.event(goal, "human_approved", now);
+            return goal;
+        });
+    }
+    /** Durable cancellation blocks admission; it does not assert that a child has stopped. */
+    async cancel(goalId, expectedVersion, requestId, reason, now) {
+        if (!requestId.trim() || !reason.trim())
+            throw new Error("cancellation reference and reason required");
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (goal.cancellation?.requestId === requestId) {
+                if (goal.cancellation.reason !== reason)
+                    throw new Error("cancellation request payload mismatch");
+                return goal;
+            }
+            if (goal.stateVersion !== expectedVersion)
+                throw new Error("cancellation version mismatch");
+            if (goal.state === "accepted")
+                throw new Error("accepted goal cannot be cancelled");
+            if (goal.cancellation)
+                throw new Error("goal already cancelled");
+            now ??= new Date();
+            goal.cancellation = { requestId, reason, requestedAt: now.toISOString() };
+            goal.state = "cancelled";
+            goal.reasonCode = "user_cancelled";
+            // Prepared has never granted dispatch. In-flight/unknown intents retain
+            // their writer slot until an exact operation/run terminal observation.
+            for (const intent of goal.intents)
+                if (intent.state === "prepared")
+                    intent.state = "terminal";
+            for (const entry of goal.supervisions)
+                if (entry.state === "proposed")
+                    entry.state = "stopped";
+            this.event(goal, "cancel_requested", now);
+            return goal;
+        });
+    }
+    async claim(goalId, now) {
+        return this.transaction((state) => {
+            now ??= new Date();
+            const goal = this.requireGoal(state, goalId);
+            if (!goal.approval || goal.approval.envelopeHash !== goal.envelopeHash)
+                throw new Error("scheduled goal not authorized");
+            if (["cancelled", "blocked", "budget_exhausted", "accepted", "unknown"].includes(goal.state))
+                return { kind: "blocked", reason: goal.reasonCode ?? goal.state };
+            const existing = goal.intents.find((intent) => intent.state !== "terminal");
+            if (existing)
+                return { kind: "existing", intent: existing };
+            const wake = evaluateScheduledGoalWake(goal.frozen.time, now);
+            if (wake.kind !== "due") {
+                goal.state = wake.kind === "waiting" ? "waiting" : "blocked";
+                if (wake.kind === "blocked")
+                    goal.reasonCode = wake.reason;
+                this.event(goal, wake.kind === "waiting" ? "waiting_for_window" : wake.reason, now);
+                return wake;
+            }
+            // Unknown and cancelled-but-in-flight intents continue holding the writer slot.
+            if (state.goals.some(holdsResource))
+                return { kind: "waiting" };
+            if (goal.used.turns >= goal.frozen.budget.maxTurns || goal.used.dagRuns >= goal.frozen.budget.maxDagRuns) {
+                goal.state = "budget_exhausted";
+                goal.reasonCode = "budget_exhausted";
+                this.event(goal, "budget_exhausted", now);
+                return { kind: "blocked", reason: "budget_exhausted" };
+            }
+            if (goal.frozen.budget.maxTokens !== undefined) {
+                goal.state = "blocked";
+                goal.reasonCode = "token_usage_unknown";
+                this.event(goal, "token_usage_unknown", now);
+                return { kind: "blocked", reason: "token_usage_unknown" };
+            }
+            // Initial admission only; Derived admission requires
+            // the separate parent-evidence transaction; never silently start a second task.
+            if (goal.intents.length)
+                throw new Error("derived task requires validated parent evidence");
+            const key = scheduledGoalHash([goal.goalId, goal.goalRevision, 1, 1, "execute", goal.envelopeHash]);
+            const intent = {
+                intentId: `intent-${key}`, taskRevision: 1, turnSeq: 1, epoch: 1, ownerToken: randomUUID(),
+                idempotencyKey: key, state: "prepared", operationId: `op_${key.slice(0, 32)}`,
+                runId: scheduledGoalRunId(goal, key), createdAt: now.toISOString(), observations: [],
+            };
+            goal.used.turns++;
+            goal.used.dagRuns++;
+            goal.intents.push(intent);
+            goal.state = "admitted";
+            this.event(goal, "intent_prepared", now);
+            return { kind: "claimed", intent };
+        });
+    }
+    /** Returns true exactly once; callers must never spawn on false or uncertainty. */
+    async beginDispatch(goalId, intentId, ownerToken, now) {
+        const before = await this.get(goalId);
+        await assertExecutionWorkspace(before.repoRef, before.frozen.worktreeRef, before.frozen.frozenBase);
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            const intent = goal.intents.find((item) => item.intentId === intentId);
+            if (!intent || intent.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            if (!["admitted", "waiting"].includes(goal.state) || intent.state !== "prepared")
+                return false;
+            if (intent.derived) {
+                const tree = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+                if (goal.evidence.at(-1)?.evidenceId !== intent.derived.parentEvidenceId || tree.treeHash !== intent.derived.treeHash || tree.scopeViolations.length)
+                    throw new Error("derived dispatch evidence drift");
+            }
+            if (!intent.derived) {
+                try {
+                    await assertInitialFrozenTree(goal.frozen);
+                }
+                catch {
+                    goal.state = "blocked";
+                    goal.reasonCode = "initial_tree_drift";
+                    intent.state = "terminal";
+                    this.event(goal, "not_dispatched:initial_tree_drift", now ?? new Date());
+                    return false;
+                }
+            }
+            now ??= new Date();
+            const wake = evaluateScheduledGoalWake(goal.frozen.time, now);
+            if (wake.kind !== "due") {
+                if (wake.kind === "waiting") {
+                    goal.state = "waiting";
+                    this.event(goal, "waiting_for_window", now);
+                }
+                else {
+                    goal.state = "blocked";
+                    goal.reasonCode = wake.reason;
+                    // This intent never obtained dispatch permission; no child can exist.
+                    intent.state = "terminal";
+                    this.event(goal, `not_dispatched:${wake.reason}`, now);
+                }
+                return false;
+            }
+            if (state.goals.some(holdsResource))
+                return false;
+            goal.state = "admitted";
+            intent.state = "dispatching";
+            intent.dispatchedAt = now.toISOString();
+            intent.dispatchOwnerPid = process.pid;
+            this.event(goal, "dispatch_intent_committed", now);
+            return true;
+        });
+    }
+    /** Only the trusted operation adapter calls this; a run success is not AC acceptance. */
+    async observeOperation(goalId, intentId, ownerToken, input) {
+        const observation = scheduledGoalOperationObservationSchema.parse(input);
+        await this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const intent = goal.intents.find((item) => item.intentId === intentId);
+            if (!intent || intent.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            if (intent.state === "prepared")
+                throw new Error("operation observation before dispatch");
+            if (intent.observations.some((entry) => scheduledGoalHash(entry) === scheduledGoalHash(observation)))
+                return;
+            intent.observations.push(observation);
+            const bound = observation.operationId === intent.operationId && observation.runId === intent.runId;
+            if (intent.state === "terminal") {
+                this.event(goal, "late_operation_observation", new Date(observation.observedAt));
+                return;
+            }
+            if (!bound || observation.state === "unknown") {
+                intent.state = "unknown";
+                if (goal.state !== "cancelled") {
+                    goal.state = "unknown";
+                    goal.reasonCode = "operation_unknown";
+                }
+            }
+            else {
+                intent.state = observation.state === "running" ? "associated" : "terminal";
+                if (goal.state === "unknown") {
+                    goal.state = "admitted";
+                    delete goal.reasonCode;
+                }
+            }
+            this.event(goal, `operation_observed:${intent.state}`, new Date(observation.observedAt));
+        });
+    }
+    async beginAssessment(goalId, expectedVersion, now = new Date()) {
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const intent = goal.intents.at(-1);
+            if (goal.stateVersion !== expectedVersion || goal.state !== "admitted" || !goal.approval)
+                throw new Error("assessment authorization/version mismatch");
+            if (!intent || intent.state !== "terminal" || !intent.observations.some((observation) => observation.operationId === intent.operationId && observation.runId === intent.runId && ["succeeded", "failed"].includes(observation.state)))
+                throw new Error("assessment requires an associated terminal operation");
+            if (now.getTime() >= Math.min(Date.parse(goal.frozen.time.stopAtUtc), Date.parse(goal.frozen.time.expiresAt)))
+                throw new Error("assessment authorization expired");
+            if (state.goals.some(holdsResource))
+                throw new Error("assessment resource busy");
+            goal.assessmentAttempt = { intentId: intent.intentId, ownerToken: randomUUID(), ownerPid: process.pid, startedAt: now.toISOString() };
+            goal.acceptanceState = "assessing";
+            this.event(goal, "assessment_started", now);
+            return goal.assessmentAttempt;
+        });
+    }
+    async refreshAcceptance(goalId) {
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (!["accepted", "admitted"].includes(goal.state) || !["accepted", "failed"].includes(goal.acceptanceState))
+                return goal;
+            const evidence = goal.evidence.at(-1);
+            const tree = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+            if (!evidence || evidence.intentId !== goal.intents.at(-1)?.intentId || tree.treeHash !== evidence.assessment.after.treeHash || tree.scopeViolations.length) {
+                goal.state = "admitted";
+                goal.acceptanceState = "stale";
+                goal.reasonCode = "evidence_drift";
+                this.event(goal, "acceptance_invalidated:tree_changed", new Date());
+            }
+            return goal;
+        });
+    }
+    async failAssessment(goalId, ownerToken, now = new Date()) {
+        await this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (goal.assessmentAttempt?.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            goal.acceptanceState = "pending";
+            if (goal.state !== "cancelled") {
+                goal.state = "unknown";
+                goal.reasonCode = "assessment_execution_unknown";
+            }
+            this.event(goal, "assessment_execution_unknown", now);
+        });
+    }
+    async finishAssessment(goalId, ownerToken, input, now) {
+        const assessment = scheduledGoalAssessmentSchema.parse(input);
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            const attempt = goal.assessmentAttempt;
+            if (!attempt || attempt.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            if (goal.evidence.some((entry) => entry.intentId === attempt.intentId && entry.assessment.executionUnknown))
+                throw new Error("assessment requires explicit reconciliation");
+            const intent = goal.intents.find((entry) => entry.intentId === attempt.intentId);
+            const expected = goal.frozen.acceptance.criteria;
+            if (assessment.criteria.length !== expected.length || assessment.criteria.some((entry, index) => entry.acId !== expected[index].acId || entry.command !== expected[index].command ||
+                (entry.status === "succeeded" && entry.exitCode !== 0) ||
+                entry.outputHash !== createHash("sha256").update(JSON.stringify({ stdout: entry.stdout, stderr: entry.stderr, exitCode: entry.exitCode })).digest("hex")))
+                throw new Error("assessment frozen AC/output binding mismatch");
+            if (assessment.before.base !== goal.frozen.frozenBase || assessment.after.base !== goal.frozen.frozenBase ||
+                Date.parse(assessment.startedAt) < Date.parse(attempt.startedAt) || Date.parse(assessment.finishedAt) < Date.parse(assessment.startedAt))
+                throw new Error("assessment base/time binding mismatch");
+            const current = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+            now ??= new Date();
+            if (Date.parse(assessment.finishedAt) > now.getTime())
+                throw new Error("assessment finish time is in the future");
+            const uncertain = assessment.executionUnknown || assessment.criteria.some((entry) => entry.reason === "command_execution_unknown");
+            assessment.executionUnknown = uncertain;
+            const stale = assessment.status === "stale" || assessment.before.treeHash !== assessment.after.treeHash || current.treeHash !== assessment.after.treeHash;
+            const expired = now.getTime() >= Math.min(Date.parse(goal.frozen.time.stopAtUtc), Date.parse(goal.frozen.time.expiresAt));
+            const scopeFailure = current.scopeViolations.length > 0 || assessment.before.scopeViolations.length > 0;
+            assessment.status = uncertain ? "pending" : stale ? "stale" : scopeFailure ? "failed" : expired ? "pending"
+                : assessment.criteria.every((entry) => entry.status === "succeeded" && entry.exitCode === 0) ? "succeeded"
+                    : assessment.criteria.some((entry) => entry.status === "pending") ? "pending" : "failed";
+            const payload = { goalId: goal.goalId, goalRevision: goal.goalRevision, envelopeHash: goal.envelopeHash, intentId: intent.intentId,
+                taskRevision: intent.taskRevision, turnSeq: intent.turnSeq, operationId: intent.operationId, runId: intent.runId,
+                assessment, committedTree: current, recordedAt: now.toISOString() };
+            goal.evidence.push({ evidenceId: scheduledGoalHash(payload), ...payload });
+            goal.acceptanceState = goal.state === "cancelled" ? "pending" : assessment.status === "succeeded" ? "accepted" : assessment.status;
+            if (!uncertain)
+                delete goal.assessmentAttempt;
+            if (goal.state !== "cancelled") {
+                if (uncertain) {
+                    goal.state = "unknown";
+                    goal.reasonCode = "assessment_execution_unknown";
+                }
+                else if (scopeFailure) {
+                    goal.state = "blocked";
+                    goal.reasonCode = "scope_violation";
+                }
+                else if (assessment.status === "succeeded") {
+                    goal.state = "accepted";
+                    goal.deliveryState = "pending";
+                }
+            }
+            this.event(goal, `assessment_recorded:${assessment.status}`, now);
+            return goal;
+        });
+    }
+    /** Settle only idle work. In-flight/unknown ownership is never released by a clock tick. */
+    async settleIdleGoal(goalId, now) {
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (!goal.approval || ["cancelled", "blocked", "budget_exhausted", "accepted", "unknown"].includes(goal.state))
+                return goal;
+            if (goal.assessmentAttempt || goal.intents.some(holdsWriterSlot) ||
+                goal.supervisions.some((entry) => ["requested", "preparing", "unknown"].includes(entry.state)))
+                return goal;
+            const latest = goal.evidence.at(-1);
+            let noProgress = false;
+            if (latest && goal.acceptanceState === "failed" && latest.intentId === goal.intents.at(-1)?.intentId) {
+                const tree = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+                if (tree.treeHash !== latest.committedTree.treeHash || tree.scopeViolations.length) {
+                    goal.acceptanceState = "stale";
+                    goal.reasonCode = "evidence_drift";
+                    this.event(goal, "acceptance_invalidated:tree_changed", now ?? new Date());
+                    return goal;
+                }
+                const previous = [...goal.evidence].reverse().find((item) => item.intentId !== latest.intentId);
+                const outcomes = (item) => item.assessment.criteria.map((ac) => [ac.acId, ac.status, ac.exitCode]);
+                noProgress = Boolean(previous && previous.assessment.status === "failed" && latest.assessment.status === "failed" &&
+                    previous.committedTree.treeHash === latest.committedTree.treeHash && scheduledGoalHash(outcomes(previous)) === scheduledGoalHash(outcomes(latest)));
+            }
+            now ??= new Date();
+            const wake = evaluateScheduledGoalWake(goal.frozen.time, now);
+            const prepared = goal.intents.some((intent) => intent.state === "prepared");
+            const needsAdmission = prepared || !goal.intents.length || goal.acceptanceState === "failed";
+            // latestStart/windows constrain a new run, not acceptance of a run already finished.
+            let reason = now.getTime() >= Date.parse(goal.frozen.time.expiresAt) ? "authorization_expired"
+                : now.getTime() >= Date.parse(goal.frozen.time.stopAtUtc) ? "deadline_reached"
+                    : needsAdmission && wake.kind === "blocked" ? wake.reason : undefined;
+            if (!reason && noProgress)
+                reason = "no_progress";
+            const needsSupervision = goal.acceptanceState === "failed" && !goal.supervisions.some((entry) => entry.state === "proposed");
+            if (!reason && needsAdmission && !prepared && (goal.used.turns >= goal.frozen.budget.maxTurns || goal.used.dagRuns >= goal.frozen.budget.maxDagRuns ||
+                (needsSupervision && goal.used.supervisorCalls >= goal.frozen.budget.maxSupervisorCalls)))
+                reason = "budget_exhausted";
+            if (!reason)
+                return goal;
+            goal.state = reason === "budget_exhausted" ? "budget_exhausted" : "blocked";
+            goal.reasonCode = reason;
+            for (const intent of goal.intents)
+                if (intent.state === "prepared")
+                    intent.state = "terminal";
+            for (const entry of goal.supervisions)
+                if (entry.state === "proposed")
+                    entry.state = "stopped";
+            this.event(goal, reason, now);
+            return goal;
+        });
+    }
+    /** Reserve before calling a tool-less model; a crash never repeats the call. */
+    async beginSupervision(goalId, expectedVersion, now) {
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            if (goal.stateVersion !== expectedVersion || goal.state !== "admitted" || goal.acceptanceState !== "failed")
+                throw new Error("supervision requires current failed acceptance");
+            if (state.goals.some(holdsResource))
+                throw new Error("supervision resource busy");
+            const evidence = goal.evidence.at(-1);
+            const parent = goal.intents.at(-1);
+            if (!goal.approval || !evidence || !parent || parent.state !== "terminal" || evidence.intentId !== parent.intentId ||
+                evidence.assessment.status !== "failed" || evidence.assessment.executionUnknown)
+                throw new Error("supervision parent binding mismatch");
+            if (goal.used.supervisorCalls >= goal.frozen.budget.maxSupervisorCalls || goal.used.turns >= goal.frozen.budget.maxTurns ||
+                goal.used.dagRuns >= goal.frozen.budget.maxDagRuns)
+                throw new Error("supervision budget exhausted");
+            // No reliable aggregate DAG token bound exists yet. Never treat its unknown usage as zero.
+            if (goal.frozen.budget.maxTokens !== undefined)
+                throw new Error("token_usage_unknown");
+            const tree = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+            now ??= new Date();
+            if (evaluateScheduledGoalWake(goal.frozen.time, now).kind !== "due")
+                throw new Error("supervision outside authorization window");
+            if (tree.treeHash !== evidence.committedTree.treeHash || tree.scopeViolations.length)
+                throw new Error("supervision evidence drift");
+            const taskRevision = parent.taskRevision + 1;
+            const turnSeq = parent.turnSeq + 1;
+            const supervisionId = scheduledGoalHash([goalId, goal.goalRevision, evidence.evidenceId, taskRevision, turnSeq]);
+            const entry = { supervisionId, ownerToken: randomUUID(), ownerPid: process.pid, parentEvidenceId: evidence.evidenceId, treeHash: tree.treeHash,
+                managedTaskId: `${goalId}-r${taskRevision}`, taskRevision, turnSeq, state: "requested", startedAt: now.toISOString() };
+            goal.used.supervisorCalls++;
+            goal.supervisions.push(entry);
+            this.event(goal, "supervision_reserved", now);
+            return entry;
+        });
+    }
+    async recordSupervisionResponse(goalId, ownerToken, text, modelRef, usageTokens) {
+        if (text.length > 64000 || !modelRef.trim() || (usageTokens !== null && (!Number.isSafeInteger(usageTokens) || usageTokens < 0)))
+            throw new Error("invalid supervision response");
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const entry = goal.supervisions.at(-1);
+            if (!entry || entry.ownerToken !== ownerToken || entry.state !== "requested")
+                throw new Error("stale_owner");
+            const response = { text, hash: scheduledGoalHash(text), modelRef };
+            if (entry.response && scheduledGoalHash(entry.response) !== scheduledGoalHash(response))
+                throw new Error("supervision response mismatch");
+            entry.response = response;
+            entry.usageTokens = usageTokens;
+            this.event(goal, "supervision_response_recorded", new Date());
+        });
+    }
+    async finishSupervision(goalId, ownerToken, input, usageTokens, now = new Date()) {
+        const proposal = scheduledGoalProposalSchema.parse(input);
+        if (usageTokens !== null && (!Number.isSafeInteger(usageTokens) || usageTokens < 0))
+            throw new Error("invalid model usage");
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const entry = goal.supervisions.at(-1);
+            if (!entry || entry.ownerToken !== ownerToken || entry.state !== "requested")
+                throw new Error("stale_owner");
+            const evidence = goal.evidence.find((item) => item.evidenceId === entry.parentEvidenceId);
+            const failedIds = evidence.assessment.criteria.filter((item) => item.status === "failed").map((item) => item.acId);
+            if (proposal.action === "continue" && (!proposal.instructions.trim() || !proposal.gapAcIds.length ||
+                (!proposal.gapAcIds.some((id) => failedIds.includes(id)) || proposal.gapAcIds.some((id) => !goal.frozen.acceptance.criteria.some((ac) => ac.acId === id)))))
+                throw new Error("proposal must address frozen failed AC");
+            entry.proposal = proposal;
+            entry.usageTokens = usageTokens;
+            entry.finishedAt = now.toISOString();
+            entry.state = goal.state === "cancelled" || proposal.action === "stop" ? "stopped" : "proposed";
+            if (proposal.action === "stop" && goal.state !== "cancelled") {
+                goal.state = "blocked";
+                goal.reasonCode = "supervisor_stopped";
+            }
+            this.event(goal, `supervision_${entry.state}`, now);
+            return entry;
+        });
+    }
+    async beginDerivedPreparation(goalId, ownerToken, now = new Date()) {
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const entry = goal.supervisions.at(-1);
+            if (!entry || entry.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            if (goal.state !== "admitted" || entry.state !== "proposed")
+                return false;
+            if (evaluateScheduledGoalWake(goal.frozen.time, now).kind !== "due")
+                return false;
+            entry.state = "preparing";
+            entry.ownerPid = process.pid;
+            this.event(goal, "derived_preparation_started", now);
+            return true;
+        });
+    }
+    async failSupervision(goalId, ownerToken, now = new Date()) {
+        return this.transaction((state) => {
+            const goal = this.requireGoal(state, goalId);
+            const entry = goal.supervisions.at(-1);
+            if (!entry || entry.ownerToken !== ownerToken || !["requested", "proposed", "preparing"].includes(entry.state))
+                throw new Error("stale_owner");
+            entry.state = "unknown";
+            if (goal.state !== "cancelled") {
+                goal.state = "unknown";
+                goal.reasonCode = "supervision_unknown";
+            }
+            this.event(goal, "supervision_unknown", now);
+        });
+    }
+    /** The caller validates the new managed gate through the pinned CLI before admission. */
+    async admitDerivedTask(goalId, ownerToken, input, now) {
+        const draft = scheduledGoalDraftSchema.parse(input);
+        return this.transaction(async (state) => {
+            const goal = this.requireGoal(state, goalId);
+            const entry = goal.supervisions.at(-1);
+            if (!entry || entry.ownerToken !== ownerToken)
+                throw new Error("stale_owner");
+            const existing = goal.intents.find((intent) => intent.derived?.supervisionId === entry.supervisionId);
+            if (existing) {
+                if (scheduledGoalHash(existing.derived?.prepared) !== scheduledGoalHash(draft.prepared) || existing.derived?.managedTaskId !== draft.managedTaskId)
+                    throw new Error("derived request mismatch");
+                return existing;
+            }
+            if (goal.state !== "admitted" || !goal.approval || entry.state !== "preparing" || entry.proposal?.action !== "continue")
+                throw new Error("derived admission not authorized");
+            const envelope = ({ managedTaskId: _task, prepared: _prepared, ...rest }) => rest;
+            if (draft.managedTaskId !== entry.managedTaskId || scheduledGoalHash(envelope(draft)) !== scheduledGoalHash(envelope(goal.frozen)) ||
+                draft.prepared.gateToken === goal.frozen.prepared.gateToken)
+                throw new Error("derived envelope/gate mismatch");
+            if (state.goals.some((item) => item.goalId !== goalId && holdsResource(item)) || goal.assessmentAttempt || goal.intents.some((item) => item.state !== "terminal"))
+                throw new Error("derived resource busy");
+            if (goal.used.turns >= goal.frozen.budget.maxTurns || goal.used.dagRuns >= goal.frozen.budget.maxDagRuns)
+                throw new Error("derived budget exhausted");
+            if (goal.evidence.at(-1)?.evidenceId !== entry.parentEvidenceId)
+                throw new Error("derived parent evidence drift");
+            const tree = await captureScheduledGoalTree(goal.frozen.worktreeRef, goal.frozen.frozenBase, goal.frozen.allowedPaths, goal.frozen.forbiddenPaths);
+            now ??= new Date();
+            if (evaluateScheduledGoalWake(goal.frozen.time, now).kind !== "due")
+                throw new Error("derived outside authorization window");
+            if (tree.treeHash !== entry.treeHash || tree.scopeViolations.length)
+                throw new Error("derived tree drift");
+            const key = scheduledGoalHash([goalId, goal.goalRevision, entry.taskRevision, entry.turnSeq, "execute", goal.envelopeHash, entry.parentEvidenceId]);
+            const intent = {
+                intentId: `intent-${key}`, taskRevision: entry.taskRevision, turnSeq: entry.turnSeq, epoch: 1, ownerToken: randomUUID(),
+                idempotencyKey: key, state: "prepared", operationId: `op_${key.slice(0, 32)}`, runId: scheduledGoalRunId(goal, key),
+                createdAt: now.toISOString(), observations: [], derived: { supervisionId: entry.supervisionId,
+                    parentEvidenceId: entry.parentEvidenceId, treeHash: tree.treeHash, managedTaskId: draft.managedTaskId, prepared: draft.prepared },
+            };
+            goal.intents.push(intent);
+            goal.used.turns++;
+            goal.used.dagRuns++;
+            entry.state = "admitted";
+            goal.acceptanceState = "not_started";
+            this.event(goal, "derived_intent_prepared", now);
+            return intent;
+        });
+    }
+    requireGoal(state, goalId) {
+        const goal = state.goals.find((item) => item.goalId === goalId);
+        if (!goal)
+            throw new Error("scheduled goal not found");
+        const hash = scheduledGoalHash({ repoRef: goal.repoRef, frozen: goal.frozen, goalRevision: goal.goalRevision });
+        if (hash !== goal.envelopeHash)
+            throw new Error("scheduled goal envelope drift");
+        for (const entry of goal.supervisions)
+            if (entry.response && scheduledGoalHash(entry.response.text) !== entry.response.hash)
+                throw new Error("supervision response drift");
+        for (const { evidenceId, ...payload } of goal.evidence)
+            if (scheduledGoalHash(payload) !== evidenceId)
+                throw new Error("scheduled goal evidence drift");
+        return goal;
+    }
+    event(goal, event, now) {
+        goal.stateVersion++;
+        goal.journal.push({ version: goal.stateVersion, at: now.toISOString(), event });
+    }
+    async read() {
+        let bytes;
+        try {
+            bytes = await readFile(path.join(this.root, "state.json"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { schemaVersion: 1, goals: [] };
+            throw error;
+        }
+        const state = stateSchema.parse(JSON.parse(bytes));
+        const repoRef = await realpath(this.repoRoot);
+        for (const goal of state.goals) {
+            if (goal.repoRef !== repoRef || goal.resourceKey !== scheduledGoalHash([repoRef, goal.frozen.managedTaskId]))
+                throw new Error("scheduled goal repository binding mismatch");
+            this.requireGoal(state, goal.goalId);
+        }
+        return state;
+    }
+    async transaction(mutate) {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        // The first ledger commit must also persist newly created .harness and
+        // scheduled-goals directory entries, not only state.json's rename.
+        await syncDirectory(path.dirname(this.root));
+        await syncDirectory(path.dirname(path.dirname(this.root)));
+        const lockPath = path.join(this.root, "mutation.lock");
+        const lock = await open(lockPath, "wx", 0o600).catch((error) => {
+            if (error.code === "EEXIST")
+                throw new Error("scheduled goal store locked: retry or reconcile owner; never steal");
+            throw error;
+        });
+        let committed = false;
+        let mutationStarted = false;
+        try {
+            await lock.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }));
+            await lock.sync();
+            const state = await this.read();
+            const result = await mutate(state);
+            const bytes = JSON.stringify(stateSchema.parse(state));
+            mutationStarted = true;
+            await this.persist(bytes);
+            committed = true;
+            return result;
+        }
+        finally {
+            await lock.close();
+            // Ambiguous filesystem failure retains the lock and durable facts for reconcile.
+            if (committed || !mutationStarted)
+                await unlink(lockPath);
+        }
+    }
+    async persist(bytes) {
+        const temp = path.join(this.root, `state-${randomUUID()}.tmp`);
+        const file = await open(temp, "wx", 0o600);
+        try {
+            await file.writeFile(bytes);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temp, path.join(this.root, "state.json"));
+        // fsync directory makes the rename durable on supported local POSIX filesystems.
+        await syncDirectory(this.root);
+    }
+}