@tea-agent/loop-agent 0.28.1 → 0.28.2

package/dist/worker/scheduler/admission.js

@@ -0,0 +1,536 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { nightSchedulerPolicySchema, } from "../../governance/manifest-types.js";
+import { loadHarnessManifest } from "../../governance/harness.js";
+import { materializeTaskSpec, } from "../materialize/harness-task-materializer.js";
+import { readTaskPoolState } from "../pool/run-store.js";
+import { resolveControllerIdentity, controllerIdentityExpectationFailure, } from "../loop-agent/loop-agent-client.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { getTaskPaths } from "../../task/runtime.js";
+import { freezeCleanBase } from "./git-base.js";
+import { cancelSchedule, submitSchedule, transitionSchedule, } from "./lifecycle.js";
+import { assertSafeSchedulerId, getAdmissionPath, relativeSchedulerPath, } from "./paths.js";
+import { reserveTaskPoolForSchedule, releaseTaskPoolReservation, } from "./reservation.js";
+import { readAdmission, readSchedule, writeAdmission } from "./store.js";
+import { validateTaskCard } from "./traceability.js";
+import { SCHEDULER_ERROR_CODES, SchedulerError, } from "./types.js";
+import { parseOnceLocalToUtc } from "./trigger.js";
+import { prepareNightWorkspace } from "./workspace-adapter.js";
+/**
+ * Daytime admission: submitted → validating → worktree + materialize + gate → validated.
+ * Does NOT execute DAG and does NOT consume approve-gate.
+ */
+export async function prepareAdmission(input) {
+    const now = input.now ?? new Date();
+    const controlRepoRoot = path.resolve(input.controlRepoRoot);
+    const featureDir = path.isAbsolute(input.featureDir)
+        ? input.featureDir
+        : path.resolve(controlRepoRoot, input.featureDir);
+    const featureDirRelative = path.relative(controlRepoRoot, featureDir);
+    if (featureDirRelative.length === 0 ||
+        featureDirRelative.startsWith("..") ||
+        path.isAbsolute(featureDirRelative)) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `featureDir must be a child of controlRepoRoot: ${input.featureDir}`);
+    }
+    const relativeFeatureDir = featureDirRelative.split(path.sep).join("/");
+    assertSafeSchedulerId(input.taskId, "taskId");
+    const policy = await resolveNightPolicy(controlRepoRoot, input.policy);
+    if (!policy.enabled) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, "Night Scheduler is disabled by workerPolicy.nightScheduler.enabled");
+    }
+    const card = validateTaskCard(input.taskCard, policy.traceability);
+    if (!card.ok) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, card.reason);
+    }
+    const trigger = parseOnceLocalToUtc({
+        localAt: input.at,
+        timezone: input.timezone ?? policy.timezone,
+        misfirePolicy: policy.misfirePolicy,
+    });
+    // Load TaskSpec from feature dir before creating schedule so we know featureId.
+    const { taskSpec, taskSpecPath, taskSpecSha, taskGraphPath, taskGraphSha, taskGraphDependencies, } = await loadFeatureTask(featureDir, input.taskId);
+    for (const dependencyId of taskGraphDependencies) {
+        const dependencyState = await readTaskPoolState(controlRepoRoot, {
+            featureId: taskSpec.feature_id,
+            taskId: dependencyId,
+        });
+        if (dependencyState?.status !== "Done") {
+            throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `dependency ${dependencyId} is not Done for ${taskSpec.id}`);
+        }
+    }
+    if (taskSpec.feature_id &&
+        path.basename(featureDir) !== taskSpec.feature_id) {
+        // Soft check: feature dir basename should match feature_id when conventional.
+    }
+    const submitted = await submitSchedule({
+        controlRepoRoot,
+        featureId: taskSpec.feature_id,
+        taskId: taskSpec.id,
+        featureDir: relativeFeatureDir,
+        workItemRef: card.workItemRef || undefined,
+        trigger: {
+            type: "once",
+            executeAtUtc: trigger.executeAtUtc,
+            latestStartAtUtc: trigger.latestStartAtUtc ??
+                new Date(Date.parse(trigger.executeAtUtc) + 24 * 60 * 60_000).toISOString(),
+            displayTimezone: trigger.displayTimezone,
+            misfirePolicy: trigger.misfirePolicy,
+        },
+        policySnapshot: {
+            allowedHours: policy.allowedHours,
+            maxConcurrency: policy.maxConcurrency,
+            maxAutoAttempts: policy.maxAutoAttempts,
+            keepFailedWorktree: policy.keepFailedWorktree,
+            mergePolicy: policy.mergePolicy,
+            misfirePolicy: policy.misfirePolicy,
+            timezone: policy.timezone,
+            autoFollowUpEnabled: policy.autoFollowUp?.enabled === true,
+            autoFollowUpMode: policy.autoFollowUp?.mode ?? "draft-only",
+        },
+        traceability: {
+            kind: "task-card",
+            label: policy.traceability.label,
+            workItemRef: card.workItemRef || undefined,
+            pattern: policy.traceability.pattern,
+            commitMessageTemplate: policy.traceability.commitMessageTemplate,
+            requiredOnCreate: policy.traceability.required,
+            requiredOnEveryPushableCommit: policy.traceability.required,
+        },
+        now,
+    });
+    const scheduleId = submitted.schedule.id;
+    try {
+        await transitionSchedule({
+            controlRepoRoot,
+            scheduleId,
+            toStatus: "validating",
+            now,
+        });
+        const baseFactory = input.baseFactory ?? freezeCleanBase;
+        const base = await baseFactory(controlRepoRoot);
+        const workspaceFactory = input.workspaceFactory ?? prepareNightWorkspace;
+        const workspace = await workspaceFactory({
+            controlRepoRoot,
+            scheduleId,
+            baseBranch: base.baseBranch,
+            baseCommit: base.baseCommit,
+            now,
+        });
+        const prepareInWorkspace = input.prepareInWorkspace ?? defaultPrepareInWorkspace;
+        const prepared = await prepareInWorkspace({
+            workspaceRoot: workspace.path,
+            controlRepoRoot,
+            taskSpec,
+            taskSpecPath,
+            client: input.client,
+            now,
+        });
+        const identity = resolveControllerIdentity(input.client, prepared.controllerIdentity) ??
+            prepared.controllerIdentity;
+        const identityFailure = controllerIdentityExpectationFailure(identity, input.controllerExpectation);
+        if (identityFailure) {
+            throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `${identityFailure.code}: ${identityFailure.message}`);
+        }
+        const admission = {
+            schemaVersion: 1,
+            scheduleId,
+            featureId: taskSpec.feature_id,
+            taskId: taskSpec.id,
+            featureDir: relativeFeatureDir,
+            taskSpec: {
+                path: path
+                    .relative(controlRepoRoot, taskSpecPath)
+                    .split(path.sep)
+                    .join("/"),
+                sha256: taskSpecSha,
+            },
+            ...(taskGraphPath
+                ? {
+                    taskGraph: {
+                        path: path
+                            .relative(controlRepoRoot, taskGraphPath)
+                            .split(path.sep)
+                            .join("/"),
+                        sha256: taskGraphSha ?? "sha256:unknown",
+                    },
+                }
+                : {}),
+            harnessTaskId: prepared.materializeManifest.harnessTaskId,
+            workspace: {
+                path: workspace.relativeWorktreePath,
+                branch: workspace.relativeBranch,
+                baseBranch: base.baseBranch,
+                baseCommit: base.baseCommit,
+                ownershipToken: workspace.ownershipToken,
+                taskDir: `.harness/tasks/${prepared.materializeManifest.harnessTaskId}`,
+            },
+            ...(identity
+                ? { controllerIdentity: identity }
+                : {}),
+            dag: {
+                path: path
+                    .relative(workspace.path, prepared.dagPath)
+                    .split(path.sep)
+                    .join("/"),
+                sha256: prepared.dagSha256,
+                ...(prepared.nodeCount !== undefined
+                    ? { nodeCount: prepared.nodeCount }
+                    : {}),
+                strictValidated: true,
+                ...(prepared.writeSet ? { writeSet: prepared.writeSet } : {}),
+            },
+            gateApproval: {
+                id: prepared.gate.id,
+                token: prepared.gate.token,
+                digest: prepared.gate.digest,
+                ...(prepared.gate.bound ? { bound: prepared.gate.bound } : {}),
+            },
+            createdAt: now.toISOString(),
+        };
+        const admissionRel = await writeAdmission(controlRepoRoot, admission);
+        const admissionPath = admissionRel.startsWith(".harness/")
+            ? admissionRel
+            : relativeSchedulerPath(controlRepoRoot, getAdmissionPath(controlRepoRoot, scheduleId)).startsWith("..")
+                ? `.harness/task-pool/scheduler/admissions/${scheduleId}.json`
+                : `.harness/task-pool/scheduler/admissions/${scheduleId}.json`;
+        const validated = await transitionSchedule({
+            controlRepoRoot,
+            scheduleId,
+            toStatus: "validated",
+            patch: {
+                admissionRef: admissionPath.startsWith(".")
+                    ? admissionPath
+                    : `.harness/task-pool/scheduler/admissions/${scheduleId}.json`,
+                isolation: {
+                    mode: "git-worktree",
+                    required: true,
+                    baseBranch: base.baseBranch,
+                    baseCommit: base.baseCommit,
+                    worktreePath: workspace.relativeWorktreePath,
+                    branch: workspace.relativeBranch,
+                    mergePolicy: policy.mergePolicy,
+                    mergeState: "pending-execution",
+                },
+            },
+            evidencePaths: [
+                `.harness/task-pool/scheduler/admissions/${scheduleId}.json`,
+            ],
+            now,
+        });
+        return {
+            schedule: validated.schedule,
+            admission,
+            reviewPacket: {
+                scheduleId,
+                featureId: taskSpec.feature_id,
+                taskId: taskSpec.id,
+                harnessTaskId: prepared.materializeManifest.harnessTaskId,
+                worktreePath: workspace.relativeWorktreePath,
+                branch: workspace.relativeBranch,
+                baseBranch: base.baseBranch,
+                baseCommit: base.baseCommit,
+                ...(prepared.writeSet ? { writeSet: prepared.writeSet } : {}),
+                gateToken: prepared.gate.token,
+                gateDigest: prepared.gate.digest,
+                ...(card.workItemRef ? { taskCard: card.workItemRef } : {}),
+                executeAtUtc: trigger.executeAtUtc,
+                admissionPath: `.harness/task-pool/scheduler/admissions/${scheduleId}.json`,
+            },
+        };
+    }
+    catch (error) {
+        // Best-effort reject so intent is not left as validating forever.
+        try {
+            const current = await readSchedule(controlRepoRoot, scheduleId);
+            if (current && current.status === "validating") {
+                await transitionSchedule({
+                    controlRepoRoot,
+                    scheduleId,
+                    toStatus: "rejected",
+                    reason: error instanceof Error ? error.message : String(error),
+                    reasonCode: "admission-failed",
+                    now: new Date(),
+                });
+            }
+        }
+        catch {
+            // ignore secondary failures
+        }
+        throw error;
+    }
+}
+/**
+ * Human-approved schedule commit: validated → scheduled + Task Pool Queued.
+ * Freezes gate approval receipt; does NOT call task advance --approve-gate.
+ */
+export async function addSchedule(input) {
+    const now = input.now ?? new Date();
+    const controlRepoRoot = path.resolve(input.controlRepoRoot);
+    const schedule = await readSchedule(controlRepoRoot, input.scheduleId);
+    if (!schedule) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.NOT_FOUND, `schedule not found: ${input.scheduleId}`);
+    }
+    if (schedule.status !== "validated") {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_TRANSITION, `scheduler add requires validated status, found ${schedule.status}`);
+    }
+    const admission = await readAdmission(controlRepoRoot, input.scheduleId);
+    if (!admission) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `admission missing for ${input.scheduleId}`);
+    }
+    if (!admission.gateApproval?.token || !admission.workspace) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `admission incomplete for ${input.scheduleId} (gate/workspace required)`);
+    }
+    const expectedToken = admission.gateApproval.token;
+    const provided = input.approveGate.trim();
+    if (provided !== expectedToken) {
+        // Also accept bare digest if operator pasted digest only.
+        const expectedDigest = admission.gateApproval.digest;
+        const alt = `${admission.gateApproval.id}:${expectedDigest}`;
+        if (provided !== expectedDigest && provided !== alt) {
+            throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `approve-gate token mismatch for ${input.scheduleId}`);
+        }
+    }
+    if (!admission.workspace.baseBranch ||
+        !admission.workspace.baseCommit ||
+        !admission.workspace.path ||
+        !admission.workspace.branch ||
+        !admission.workspace.ownershipToken ||
+        !admission.harnessTaskId ||
+        !admission.dag?.sha256 ||
+        admission.dag.strictValidated !== true ||
+        !admission.gateApproval.id ||
+        !admission.gateApproval.digest) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `admission missing required frozen fields for ${input.scheduleId}`);
+    }
+    const admissionPath = schedule.admissionRef ??
+        `.harness/task-pool/scheduler/admissions/${input.scheduleId}.json`;
+    await reserveTaskPoolForSchedule({
+        controlRepoRoot,
+        featureId: schedule.featureId,
+        taskId: schedule.taskId,
+        nightScheduleId: schedule.id,
+        admissionPath,
+        nightWorktreePath: admission.workspace.path,
+        nightBranch: admission.workspace.branch,
+        now,
+    });
+    const approvedAdmission = {
+        ...admission,
+        gateApproval: {
+            ...admission.gateApproval,
+            approvedAt: now.toISOString(),
+            approvedBy: "operator",
+            token: expectedToken,
+        },
+    };
+    await writeAdmission(controlRepoRoot, approvedAdmission);
+    const scheduled = await transitionSchedule({
+        controlRepoRoot,
+        scheduleId: input.scheduleId,
+        toStatus: "scheduled",
+        event: "schedule_created",
+        patch: {
+            reservation: {
+                taskPoolStatus: "Queued",
+                reservedAt: now.toISOString(),
+            },
+            admissionRef: admissionPath,
+            isolation: {
+                mode: "git-worktree",
+                required: true,
+                baseBranch: admission.workspace.baseBranch,
+                baseCommit: admission.workspace.baseCommit,
+                worktreePath: admission.workspace.path,
+                branch: admission.workspace.branch,
+                mergePolicy: schedule.isolation?.mergePolicy ??
+                    schedule.policySnapshot?.mergePolicy ??
+                    "manual-on-success",
+                mergeState: "pending-execution",
+            },
+        },
+        evidencePaths: [admissionPath],
+        now,
+    });
+    return {
+        schedule: scheduled.schedule,
+        admission: approvedAdmission,
+        taskPoolStatus: "Queued",
+    };
+}
+/**
+ * Cancel before dispatch and release Queued → Ready when bound.
+ */
+export async function cancelScheduledReservation(input) {
+    const schedule = await readSchedule(input.controlRepoRoot, input.scheduleId);
+    if (!schedule) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.NOT_FOUND, `schedule not found: ${input.scheduleId}`);
+    }
+    const result = await cancelSchedule({
+        controlRepoRoot: input.controlRepoRoot,
+        scheduleId: input.scheduleId,
+        reason: input.reason,
+        now: input.now,
+    });
+    if (schedule.status === "scheduled" ||
+        schedule.status === "waiting" ||
+        schedule.status === "validated") {
+        await releaseTaskPoolReservation({
+            controlRepoRoot: input.controlRepoRoot,
+            featureId: schedule.featureId,
+            taskId: schedule.taskId,
+            nightScheduleId: schedule.id,
+            now: input.now,
+        });
+    }
+    return result.schedule;
+}
+async function resolveNightPolicy(controlRepoRoot, override) {
+    if (override) {
+        return nightSchedulerPolicySchema.parse(override);
+    }
+    try {
+        const manifest = await loadHarnessManifest(controlRepoRoot);
+        return nightSchedulerPolicySchema.parse(manifest.workerPolicy?.nightScheduler ?? {});
+    }
+    catch {
+        return nightSchedulerPolicySchema.parse({});
+    }
+}
+async function loadFeatureTask(featureDir, taskId) {
+    const tasksDir = path.join(featureDir, "tasks");
+    const taskGraphPath = path.join(tasksDir, "task-graph.yaml");
+    let graphRaw;
+    try {
+        graphRaw = await readFile(taskGraphPath, "utf-8");
+    }
+    catch (error) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.NOT_FOUND, `task graph is required for night admission: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const graph = YAML.parse(graphRaw);
+    const matchingNodes = (graph.nodes ?? []).filter((entry) => entry.id === taskId);
+    if (matchingNodes.length !== 1) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `task graph must contain exactly one node for ${taskId}`);
+    }
+    const node = matchingNodes[0];
+    if (!node?.task) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `task graph node ${taskId} must declare a task file`);
+    }
+    const taskRef = node.task;
+    const taskSpecPath = path.resolve(tasksDir, taskRef);
+    const taskSpecRelative = path.relative(path.resolve(tasksDir), taskSpecPath);
+    if (taskSpecRelative.length === 0 ||
+        taskSpecRelative.startsWith("..") ||
+        path.isAbsolute(taskSpecRelative)) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `task graph node ${taskId} has unsafe task path: ${taskRef}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(taskSpecPath, "utf-8");
+    }
+    catch (error) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.NOT_FOUND, `TaskSpec not found for ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsed = taskSpecSchema.parse(YAML.parse(raw));
+    if (parsed.id !== taskId) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `TaskSpec id ${parsed.id} does not match requested taskId ${taskId}`);
+    }
+    if (graph.feature_id !== parsed.feature_id) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `task graph feature_id ${graph.feature_id ?? "missing"} does not match TaskSpec ${parsed.feature_id}`);
+    }
+    const graphDependencies = node.depends_on ?? [];
+    if (JSON.stringify(graphDependencies) !== JSON.stringify(parsed.depends_on)) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `task graph dependencies do not match TaskSpec for ${taskId}`);
+    }
+    return {
+        taskSpec: parsed,
+        taskSpecPath,
+        taskSpecSha: `sha256:${createHash("sha256").update(raw, "utf-8").digest("hex")}`,
+        taskGraphPath,
+        taskGraphSha: `sha256:${createHash("sha256").update(graphRaw, "utf-8").digest("hex")}`,
+        taskGraphDependencies: graphDependencies,
+    };
+}
+async function defaultPrepareInWorkspace(input) {
+    // Materialize + open writeSet gate inside the schedule worktree.
+    const materializeManifest = await materializeTaskSpec({
+        repoRoot: input.workspaceRoot,
+        taskSpec: input.taskSpec,
+        taskSpecPath: input.taskSpecPath,
+        client: input.client,
+        now: input.now,
+    });
+    const dagPath = path.join(input.workspaceRoot, ".harness", "tasks", materializeManifest.harnessTaskId, "artifacts", `admission-dag.json`);
+    const advanceResult = await input.client.run([
+        "task",
+        "advance",
+        materializeManifest.harnessTaskId,
+        "--profile",
+        materializeManifest.loopAgentProfile,
+        "--dag-output",
+        dagPath,
+        "--json",
+    ], {
+        cwd: input.workspaceRoot,
+        artifactName: `admission-task-advance-${materializeManifest.harnessTaskId}`,
+    });
+    const gate = extractGate(advanceResult, materializeManifest.harnessTaskId);
+    const dagBytes = await readFile(getTaskPaths(input.workspaceRoot, materializeManifest.harnessTaskId)
+        .dagDraftPath, "utf-8").catch(async () => readFile(dagPath, "utf-8"));
+    const dagSha256 = `sha256:${createHash("sha256").update(dagBytes, "utf-8").digest("hex")}`;
+    let nodeCount;
+    let writeSet;
+    try {
+        const dagJson = JSON.parse(dagBytes);
+        if (Array.isArray(dagJson.nodes))
+            nodeCount = dagJson.nodes.length;
+        if (Array.isArray(dagJson.writeSet))
+            writeSet = dagJson.writeSet;
+    }
+    catch {
+        // ignore
+    }
+    const identity = typeof input.client.getIdentity === "function"
+        ? input.client.getIdentity()
+        : undefined;
+    return {
+        materializeManifest,
+        dagPath,
+        dagSha256,
+        ...(nodeCount !== undefined ? { nodeCount } : {}),
+        ...(writeSet ? { writeSet } : {}),
+        gate,
+        ...(identity ? { controllerIdentity: identity } : {}),
+    };
+}
+function extractGate(result, taskId) {
+    const root = result.json;
+    if (!root || typeof root !== "object") {
+        throw new Error(`admission prepare did not return JSON for ${taskId}; cannot open writeSet gate`);
+    }
+    const envelope = root;
+    const payload = envelope.result && typeof envelope.result === "object"
+        ? envelope.result
+        : envelope;
+    const gate = payload.gate && typeof payload.gate === "object"
+        ? payload.gate
+        : undefined;
+    const id = typeof gate?.id === "string" ? gate.id : undefined;
+    const digest = typeof gate?.digest === "string" ? gate.digest : undefined;
+    if (!id || !digest) {
+        const lifecycleState = typeof payload.lifecycleState === "string"
+            ? payload.lifecycleState
+            : "unknown";
+        throw new Error(`admission prepare for ${taskId} did not open a writeSet gate (lifecycleState=${lifecycleState})`);
+    }
+    const bound = gate?.bound && typeof gate.bound === "object"
+        ? gate.bound
+        : undefined;
+    return {
+        id,
+        digest,
+        token: `${id}:${digest}`,
+        ...(bound ? { bound } : {}),
+    };
+}

package/dist/worker/scheduler/auto-followup.js

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { draftFollowUpDecision, } from "../follow-up/factory.js";
+/**
+ * ADR 0010: optional post-failure Follow-up draft enqueue.
+ * Default off via policySnapshot.autoFollowUpEnabled.
+ * Never approves; never mutates Ready / writeSet / admission.
+ */
+export async function maybeEnqueueNightFollowUp(input) {
+    const enabled = input.schedule.policySnapshot?.autoFollowUpEnabled === true;
+    if (!enabled) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "disabled",
+            detail: "policySnapshot.autoFollowUpEnabled is false (ADR 0010 default)",
+        };
+    }
+    const mode = input.schedule.policySnapshot?.autoFollowUpMode ?? "draft-only";
+    if (mode !== "draft-only") {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "unsupported-mode",
+            detail: `autoFollowUpMode=${mode} is not supported; only draft-only`,
+        };
+    }
+    if (input.schedule.status !== "failed") {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "not-failed",
+            detail: `schedule status is ${input.schedule.status}`,
+        };
+    }
+    const featureDirRel = input.schedule.featureDir?.trim();
+    if (!featureDirRel) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "missing-feature-dir",
+            detail: "schedule.featureDir required to draft follow-up against Feature Packet",
+        };
+    }
+    const workerRunId = input.workerRunId?.trim();
+    if (!workerRunId) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "missing-worker-run",
+            detail: "workerRunId required to bind failed run evidence",
+        };
+    }
+    if (path.isAbsolute(featureDirRel)) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "unsafe-feature-dir",
+            detail: "schedule.featureDir must be repo-relative",
+        };
+    }
+    const featureDir = path.resolve(input.controlRepoRoot, featureDirRel);
+    const relativeFeatureDir = path.relative(path.resolve(input.controlRepoRoot), featureDir);
+    if (relativeFeatureDir.length === 0 ||
+        relativeFeatureDir.startsWith("..") ||
+        path.isAbsolute(relativeFeatureDir)) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "unsafe-feature-dir",
+            detail: "schedule.featureDir escapes controlRepoRoot",
+        };
+    }
+    const draftFn = input.draft ?? draftFollowUpDecision;
+    try {
+        const result = await draftFn({
+            repoRoot: input.controlRepoRoot,
+            featureDir,
+            taskId: input.schedule.taskId,
+            workerRunId,
+        });
+        return {
+            ok: true,
+            action: result.created ? "drafted" : "reused",
+            kind: result.kind,
+            followUpId: result.followUpId,
+            draftPath: result.draftPath,
+            workerRunId,
+            featureDir,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            action: "skipped",
+            reason: "draft-error",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}