@tea-agent/loop-agent 0.28.2-beta.1 → 0.28.2

package/dist/worker/scheduler/morning-window.js

@@ -0,0 +1,161 @@
+import { listSchedules } from "./store.js";
+/**
+ * Project Night Scheduler facts for morning report --window night.
+ * Date is local calendar day in display timezone (default Asia/Shanghai).
+ */
+export async function buildNightMorningWindow(input) {
+    const timezone = input.timezone ?? "Asia/Shanghai";
+    const now = input.now ?? new Date();
+    const date = input.date ?? formatLocalDate(now, timezone);
+    const schedules = await listSchedules(input.controlRepoRoot);
+    const inWindow = schedules.filter((schedule) => scheduleTouchesLocalDate(schedule, date, timezone));
+    const rows = inWindow
+        .map((schedule) => toRow(schedule))
+        .sort((a, b) => (a.executeAtUtc ?? "").localeCompare(b.executeAtUtc ?? ""));
+    const summary = {
+        total: rows.length,
+        succeeded: rows.filter((row) => row.status === "succeeded").length,
+        failed: rows.filter((row) => row.status === "failed").length,
+        humanRequired: rows.filter((row) => row.status === "human_required").length,
+        pendingHarvest: rows.filter((row) => row.mergeState === "pending-harvest")
+            .length,
+        scheduledOrWaiting: rows.filter((row) => row.status === "scheduled" ||
+            row.status === "waiting" ||
+            row.status === "validated").length,
+    };
+    return {
+        schemaVersion: 1,
+        window: "night",
+        date,
+        timezone,
+        generatedAt: now.toISOString(),
+        schedules: rows,
+        summary,
+    };
+}
+export function renderNightMorningMarkdown(window) {
+    const lines = [
+        `# Night Scheduler Morning Report (${window.date})`,
+        "",
+        `Timezone: ${window.timezone}`,
+        `Generated: ${window.generatedAt}`,
+        "",
+        "## Summary",
+        "",
+        `- Total schedules: ${window.summary.total}`,
+        `- Succeeded: ${window.summary.succeeded}`,
+        `- Failed: ${window.summary.failed}`,
+        `- Human required: ${window.summary.humanRequired}`,
+        `- Pending harvest: ${window.summary.pendingHarvest}`,
+        `- Still scheduled/waiting: ${window.summary.scheduledOrWaiting}`,
+        "",
+        "## Schedules",
+        "",
+        "| Schedule | Task | Plan | Status | Merge | Card | Next |",
+        "|---|---|---|---|---|---|---|",
+    ];
+    for (const row of window.schedules) {
+        lines.push(`| ${row.scheduleId} | ${row.featureId}/${row.taskId} | ${row.executeAtUtc ?? "-"} | ${row.status} | ${row.mergeState ?? "-"} | ${row.taskCard ?? "-"} | ${row.nextAction} |`);
+    }
+    if (window.schedules.length === 0) {
+        lines.push("| (none) | - | - | - | - | - | - |");
+    }
+    lines.push("", "## Details", "");
+    for (const row of window.schedules) {
+        lines.push(`### ${row.scheduleId}`);
+        lines.push("");
+        lines.push(`- Task: ${row.featureId}/${row.taskId}`);
+        lines.push(`- Status: ${row.status}`);
+        lines.push(`- Plan: ${row.executeAtUtc ?? "-"}`);
+        lines.push(`- Merge: ${row.mergeState ?? "-"}`);
+        lines.push(`- Worktree: ${row.worktreePath ?? "-"}`);
+        lines.push(`- Branch: ${row.branch ?? "-"}`);
+        lines.push(`- Card: ${row.taskCard ?? "-"}`);
+        lines.push(`- Execution: ${row.currentExecutionId ?? "-"}`);
+        lines.push(`- Evidence: ${row.evidencePath ?? "-"}`);
+        lines.push(`- Next: ${row.nextAction}`);
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}
+function toRow(schedule) {
+    const mergeState = schedule.isolation?.mergeState;
+    const nextAction = resolveNextAction(schedule);
+    return {
+        scheduleId: schedule.id,
+        featureId: schedule.featureId,
+        taskId: schedule.taskId,
+        status: schedule.status,
+        ...(schedule.trigger?.executeAtUtc
+            ? { executeAtUtc: schedule.trigger.executeAtUtc }
+            : {}),
+        ...(mergeState ? { mergeState } : {}),
+        ...(schedule.isolation?.worktreePath
+            ? { worktreePath: schedule.isolation.worktreePath }
+            : {}),
+        ...(schedule.isolation?.branch
+            ? { branch: schedule.isolation.branch }
+            : {}),
+        ...(schedule.traceability?.workItemRef
+            ? { taskCard: schedule.traceability.workItemRef }
+            : {}),
+        currentExecutionId: schedule.currentExecutionId ?? null,
+        ...(schedule.currentExecutionId
+            ? {
+                evidencePath: `.harness/task-pool/scheduler/evidence/${schedule.currentExecutionId}`,
+            }
+            : {}),
+        nextAction,
+    };
+}
+export function resolveNextAction(schedule) {
+    if (schedule.status === "succeeded" &&
+        schedule.isolation?.mergeState === "pending-harvest") {
+        return `agent-worker scheduler harvest ${schedule.id} --repo .`;
+    }
+    if (schedule.status === "succeeded" &&
+        schedule.isolation?.mergeState === "merged") {
+        return "done (merged)";
+    }
+    if (schedule.status === "failed" ||
+        schedule.status === "human_required" ||
+        schedule.status === "cancelled") {
+        return `agent-worker scheduler discard ${schedule.id} --repo . --reason "..."${schedule.status === "failed" || schedule.status === "human_required" ? " --force" : ""}`;
+    }
+    if (schedule.status === "scheduled" || schedule.status === "waiting") {
+        return "wait for scheduler tick / inspect schedule status";
+    }
+    if (schedule.status === "validated") {
+        return `agent-worker scheduler add ${schedule.id} --approve-gate <token> --repo .`;
+    }
+    if (schedule.status === "running" || schedule.status === "dispatching") {
+        return "monitor running execution; do not start a second writer";
+    }
+    return `agent-worker scheduler status ${schedule.id} --repo .`;
+}
+function scheduleTouchesLocalDate(schedule, date, timezone) {
+    const instants = [];
+    if (schedule.trigger?.executeAtUtc)
+        instants.push(schedule.trigger.executeAtUtc);
+    if (schedule.timestamps.submittedAt)
+        instants.push(schedule.timestamps.submittedAt);
+    if (schedule.timestamps.finishedAt)
+        instants.push(schedule.timestamps.finishedAt);
+    if (schedule.timestamps.startedAt)
+        instants.push(schedule.timestamps.startedAt);
+    if (instants.length === 0)
+        return true;
+    return instants.some((iso) => formatLocalDate(new Date(iso), timezone) === date);
+}
+function formatLocalDate(date, timezone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone: timezone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(date);
+    const year = parts.find((part) => part.type === "year")?.value ?? "1970";
+    const month = parts.find((part) => part.type === "month")?.value ?? "01";
+    const day = parts.find((part) => part.type === "day")?.value ?? "01";
+    return `${year}-${month}-${day}`;
+}

package/dist/worker/scheduler/night-git-finalizer.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { parseGitStatusPorcelain, pathMatchesPattern, } from "../../shared/git-progress.js";
+import { formatCommitMessage, validateTaskCard } from "./traceability.js";
+/**
+ * Create a single closing commit on the night branch after successful execution.
+ * Does not merge to base. Fail-closed on writeSet violations or missing task card.
+ */
+export async function createNightClosingCommit(input) {
+    const card = validateTaskCard(input.schedule.traceability?.workItemRef, {
+        required: input.schedule.traceability?.requiredOnEveryPushableCommit ??
+            input.schedule.traceability?.requiredOnCreate ??
+            true,
+        label: input.schedule.traceability?.label ?? "Task Card",
+        pattern: input.schedule.traceability?.pattern ??
+            "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$",
+        commitMessageTemplate: input.schedule.traceability?.commitMessageTemplate ??
+            "{summary}\n\n{workItemRef}",
+    });
+    if (!card.ok || !card.workItemRef) {
+        return {
+            ok: false,
+            reason: card.ok ? "task card required for closing commit" : card.reason,
+        };
+    }
+    const status = (await runGit(input.workspaceRoot, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+    ])).trim();
+    if (!status) {
+        return { ok: false, reason: "no changes to commit after execution" };
+    }
+    const changedPaths = parseGitStatusPorcelain(status).map((entry) => entry.path);
+    const writeSet = input.writeSet ?? input.admission.dag?.writeSet ?? undefined;
+    if (writeSet && writeSet.length > 0) {
+        const offenders = changedPaths.filter((p) => !pathAllowedByWriteSet(p, writeSet));
+        if (offenders.length > 0) {
+            return {
+                ok: false,
+                reason: `changed paths outside frozen writeSet: ${offenders.join(", ")}`,
+                changedPaths,
+            };
+        }
+    }
+    await runGit(input.workspaceRoot, ["add", "-A"]);
+    const summary = `feat(${input.schedule.taskId.toLowerCase()}): night schedule ${input.schedule.id}`;
+    const message = formatCommitMessage({
+        summary,
+        workItemRef: card.workItemRef,
+        template: input.schedule.traceability?.commitMessageTemplate,
+        trailers: {
+            "Worker-Run": input.workerRunId,
+            Schedule: input.schedule.id,
+            Execution: input.executionId,
+        },
+    });
+    await runGit(input.workspaceRoot, ["commit", "-m", message]);
+    const commitSha = (await runGit(input.workspaceRoot, ["rev-parse", "HEAD"])).trim();
+    return {
+        ok: true,
+        commitSha,
+        message,
+        changedPaths,
+    };
+}
+function pathAllowedByWriteSet(filePath, writeSet) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return writeSet.some((pattern) => pathMatchesPattern(normalized, pattern));
+}
+async function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout?.on("data", (c) => stdout.push(c));
+        child.stderr?.on("data", (c) => stderr.push(c));
+        child.on("error", (err) => reject(err));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`git ${args.join(" ")} failed: ${Buffer.concat(stderr).toString("utf-8")}`));
+                return;
+            }
+            resolve(Buffer.concat(stdout).toString("utf-8"));
+        });
+    });
+}

package/dist/worker/scheduler/night-harvest.js

@@ -0,0 +1,421 @@
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { getLeasePath } from "./paths.js";
+import { verifyEvidenceArchive } from "./evidence.js";
+import { patchScheduleIsolation, transitionSchedule, } from "./lifecycle.js";
+import { readAdmission, readExecution, readSchedule } from "./store.js";
+import { releaseExecutionLease } from "./lease.js";
+import { validateTaskCard } from "./traceability.js";
+import { SCHEDULER_ERROR_CODES, SchedulerError, } from "./types.js";
+/**
+ * MVP harvest: exact-base fast-forward only.
+ * Refuses when base HEAD moved, dirty, missing evidence, or bad mergeState.
+ */
+export async function harvestNightSchedule(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 !== "succeeded") {
+        return blocked("schedule-not-succeeded", `schedule status is ${schedule.status}, expected succeeded`, "Inspect schedule status / evidence; only succeeded pending-harvest can harvest");
+    }
+    if (schedule.isolation?.mergeState !== "pending-harvest") {
+        return blocked("merge-state-invalid", `mergeState is ${schedule.isolation?.mergeState ?? "missing"}, expected pending-harvest`, schedule.isolation?.mergeState === "merged"
+            ? "Already harvested"
+            : "Use scheduler status / doctor before harvest");
+    }
+    const baseBranch = schedule.isolation.baseBranch;
+    const baseCommit = schedule.isolation.baseCommit;
+    const nightBranch = schedule.isolation.branch;
+    const worktreeRel = schedule.isolation.worktreePath;
+    if (!baseBranch || !baseCommit || !nightBranch) {
+        return blocked("isolation-incomplete", "schedule isolation missing baseBranch/baseCommit/branch", "Doctor admission/isolation facts");
+    }
+    if (nightBranch !== `night/${schedule.id}`) {
+        return blocked("night-branch-unsafe", `night branch must be night/${schedule.id}, got ${nightBranch}`, "Run scheduler doctor and repair the tampered isolation facts");
+    }
+    let safeWorktreePath;
+    if (worktreeRel) {
+        try {
+            safeWorktreePath = resolveSafeNightWorktreePath(controlRepoRoot, worktreeRel);
+        }
+        catch (error) {
+            return blocked("worktree-path-unsafe", error instanceof Error ? error.message : String(error), "Run scheduler doctor and repair the tampered isolation facts");
+        }
+    }
+    const baseStatus = (await runGit(controlRepoRoot, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+    ])).trim();
+    // Scheduler/Task Pool runtime under .harness and night worktrees are expected
+    // control facts; they must not block harvest of source commits.
+    const dirtySource = baseStatus
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => {
+        const filePath = line.slice(3).trim().replace(/\\/g, "/");
+        return (!filePath.startsWith(".harness/") &&
+            !filePath.startsWith(".worktrees/") &&
+            filePath !== ".harness" &&
+            filePath !== ".worktrees");
+    });
+    if (dirtySource.length > 0) {
+        return blocked("base-dirty", `control repo has uncommitted source changes: ${dirtySource
+            .slice(0, 5)
+            .map((line) => line.slice(3).trim())
+            .join(", ")}`, "Commit or stash base source changes, then retry harvest");
+    }
+    const currentBranch = (await runGit(controlRepoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    if (currentBranch !== baseBranch) {
+        return blocked("base-branch-mismatch", `checked out ${currentBranch}, expected base branch ${baseBranch}`, `git checkout ${baseBranch} then retry harvest`);
+    }
+    const head = (await runGit(controlRepoRoot, ["rev-parse", "HEAD"])).trim();
+    if (head !== baseCommit) {
+        return blocked("base-moved", `base HEAD ${head.slice(0, 12)} != frozen baseCommit ${baseCommit.slice(0, 12)}`, "MVP refuses harvest when base moved; integrate manually or open Phase 3.5+ integration worktree");
+    }
+    const isAncestor = await runGitAllowFail(controlRepoRoot, [
+        "merge-base",
+        "--is-ancestor",
+        baseCommit,
+        nightBranch,
+    ]);
+    if (isAncestor.exitCode !== 0) {
+        return blocked("night-branch-not-descendant", `night branch ${nightBranch} is not a descendant of frozen baseCommit`, "Inspect night branch history; do not force FF");
+    }
+    // Traceability: every commit on night branch after base must mention work item when required.
+    const cardCheck = await auditBranchTraceability(controlRepoRoot, baseCommit, nightBranch, schedule);
+    if (!cardCheck.ok) {
+        return blocked("traceability-failed", cardCheck.reason, "Fix commit messages on night branch or discard");
+    }
+    // Evidence archive integrity when execution id present
+    if (schedule.currentExecutionId) {
+        const evidenceOk = await evidenceArchivePresent(controlRepoRoot, schedule.currentExecutionId);
+        if (!evidenceOk) {
+            return blocked("evidence-missing", `evidence archive missing for ${schedule.currentExecutionId}`, "Restore evidence or re-archive before harvest");
+        }
+    }
+    // Fast-forward only
+    try {
+        await runGit(controlRepoRoot, ["merge", "--ff-only", nightBranch]);
+    }
+    catch (error) {
+        return blocked("ff-failed", error instanceof Error ? error.message : String(error), "Resolve history manually; MVP does not rebase/merge");
+    }
+    const mergedCommit = (await runGit(controlRepoRoot, ["rev-parse", "HEAD"])).trim();
+    let worktreeRemoved = false;
+    let branchDeleted = false;
+    if (!input.keepWorktree && safeWorktreePath) {
+        try {
+            await runGit(controlRepoRoot, [
+                "worktree",
+                "remove",
+                "--force",
+                safeWorktreePath,
+            ]);
+            worktreeRemoved = true;
+        }
+        catch {
+            try {
+                await rm(safeWorktreePath, { recursive: true, force: true });
+                await runGit(controlRepoRoot, ["worktree", "prune"]).catch(() => { });
+                worktreeRemoved = true;
+            }
+            catch {
+                worktreeRemoved = false;
+            }
+        }
+        try {
+            await runGit(controlRepoRoot, ["branch", "-d", nightBranch]);
+            branchDeleted = true;
+        }
+        catch {
+            branchDeleted = false;
+        }
+    }
+    // succeeded is already terminal — only patch mergeState + ledger (no status change).
+    await patchScheduleIsolation({
+        controlRepoRoot,
+        scheduleId: schedule.id,
+        isolation: {
+            mode: "git-worktree",
+            required: true,
+            baseBranch: schedule.isolation.baseBranch,
+            baseCommit: schedule.isolation.baseCommit,
+            worktreePath: schedule.isolation.worktreePath,
+            branch: schedule.isolation.branch,
+            mergePolicy: schedule.isolation.mergePolicy,
+            mergeState: "merged",
+        },
+        event: "merge_completed",
+        reason: `fast-forward ${nightBranch} -> ${baseBranch}`,
+        reasonCode: "merged",
+        ...(schedule.currentExecutionId
+            ? {
+                evidencePaths: [
+                    `.harness/task-pool/scheduler/evidence/${schedule.currentExecutionId}`,
+                ],
+            }
+            : {}),
+        now,
+    });
+    return {
+        ok: true,
+        scheduleId: schedule.id,
+        baseBranch,
+        baseCommit,
+        nightBranch,
+        mergedCommit,
+        fastForward: true,
+        worktreeRemoved,
+        branchDeleted,
+        mergeState: "merged",
+    };
+}
+/**
+ * Discard night worktree/branch after evidence is retained.
+ * Failed/human_required require --force.
+ */
+export async function discardNightSchedule(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}`);
+    }
+    const activeRuntime = new Set(["dispatching", "running", "cancel_requested"]);
+    if (activeRuntime.has(schedule.status)) {
+        return blocked("still-running", `cannot discard schedule in status ${schedule.status}`, "Wait for terminal status or cancel first");
+    }
+    if ((schedule.status === "failed" || schedule.status === "human_required") &&
+        !input.force) {
+        return blocked("force-required", `discard of ${schedule.status} schedule requires --force`, `agent-worker scheduler discard ${schedule.id} --repo . --reason "..." --force`);
+    }
+    if (schedule.currentExecutionId) {
+        const evidenceOk = await evidenceArchivePresent(controlRepoRoot, schedule.currentExecutionId);
+        if (!evidenceOk) {
+            // Still allow discard if never executed (no execution file)
+            const execution = await readExecution(controlRepoRoot, schedule.currentExecutionId);
+            if (execution) {
+                return blocked("evidence-missing", `evidence archive missing for ${schedule.currentExecutionId}`, "Archive evidence before discard so control root retains forensics");
+            }
+        }
+    }
+    // Drop lease if any
+    await releaseExecutionLease({
+        controlRepoRoot,
+        scheduleId: schedule.id,
+    }).catch(() => { });
+    try {
+        await rm(getLeasePath(controlRepoRoot, schedule.id), { force: true });
+    }
+    catch {
+        // ignore
+    }
+    const nightBranch = schedule.isolation?.branch;
+    const worktreeRel = schedule.isolation?.worktreePath;
+    if (nightBranch && nightBranch !== `night/${schedule.id}`) {
+        return blocked("night-branch-unsafe", `night branch must be night/${schedule.id}, got ${nightBranch}`, "Run scheduler doctor and repair the tampered isolation facts");
+    }
+    let safeWorktreePath;
+    if (worktreeRel) {
+        try {
+            safeWorktreePath = resolveSafeNightWorktreePath(controlRepoRoot, worktreeRel);
+        }
+        catch (error) {
+            return blocked("worktree-path-unsafe", error instanceof Error ? error.message : String(error), "Run scheduler doctor and repair the tampered isolation facts");
+        }
+    }
+    let worktreeRemoved = false;
+    let branchDeleted = false;
+    if (safeWorktreePath) {
+        try {
+            await runGit(controlRepoRoot, [
+                "worktree",
+                "remove",
+                "--force",
+                safeWorktreePath,
+            ]);
+            worktreeRemoved = true;
+        }
+        catch {
+            try {
+                await rm(safeWorktreePath, { recursive: true, force: true });
+                await runGit(controlRepoRoot, ["worktree", "prune"]).catch(() => { });
+                worktreeRemoved = true;
+            }
+            catch {
+                worktreeRemoved = false;
+            }
+        }
+    }
+    if (nightBranch) {
+        try {
+            await runGit(controlRepoRoot, ["branch", "-D", nightBranch]);
+            branchDeleted = true;
+        }
+        catch {
+            branchDeleted = false;
+        }
+    }
+    // Keep schedule terminal status; only mergeState → discarded + ledger.
+    if (schedule.status === "scheduled" ||
+        schedule.status === "waiting" ||
+        schedule.status === "validated" ||
+        schedule.status === "submitted" ||
+        schedule.status === "validating") {
+        await transitionSchedule({
+            controlRepoRoot,
+            scheduleId: schedule.id,
+            toStatus: "cancelled",
+            event: "worktree_discarded",
+            reason: input.reason,
+            reasonCode: "discard",
+            patch: {
+                isolation: {
+                    mode: "git-worktree",
+                    required: true,
+                    baseBranch: schedule.isolation?.baseBranch,
+                    baseCommit: schedule.isolation?.baseCommit,
+                    worktreePath: schedule.isolation?.worktreePath,
+                    branch: schedule.isolation?.branch,
+                    mergePolicy: schedule.isolation?.mergePolicy ?? "manual-on-success",
+                    mergeState: "discarded",
+                },
+                cancelReason: input.reason,
+            },
+            now,
+        });
+    }
+    else {
+        await patchScheduleIsolation({
+            controlRepoRoot,
+            scheduleId: schedule.id,
+            isolation: {
+                mode: "git-worktree",
+                required: true,
+                baseBranch: schedule.isolation?.baseBranch,
+                baseCommit: schedule.isolation?.baseCommit,
+                worktreePath: schedule.isolation?.worktreePath,
+                branch: schedule.isolation?.branch,
+                mergePolicy: schedule.isolation?.mergePolicy ?? "manual-on-success",
+                mergeState: "discarded",
+            },
+            event: "worktree_discarded",
+            reason: input.reason,
+            reasonCode: "discarded",
+            ...(schedule.currentExecutionId
+                ? {
+                    evidencePaths: [
+                        `.harness/task-pool/scheduler/evidence/${schedule.currentExecutionId}`,
+                    ],
+                }
+                : {}),
+            now,
+        });
+    }
+    return {
+        ok: true,
+        scheduleId: schedule.id,
+        worktreeRemoved,
+        branchDeleted,
+        mergeState: "discarded",
+        reason: input.reason,
+    };
+}
+function resolveSafeNightWorktreePath(controlRepoRoot, worktreeRef) {
+    if (path.isAbsolute(worktreeRef)) {
+        throw new Error(`night worktree path must be repo-relative: ${worktreeRef}`);
+    }
+    const worktreeRoot = path.resolve(controlRepoRoot, ".worktrees");
+    const candidate = path.resolve(controlRepoRoot, worktreeRef);
+    const relative = path.relative(worktreeRoot, candidate);
+    if (relative.length === 0 ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new Error(`night worktree path escapes .worktrees: ${worktreeRef}`);
+    }
+    return candidate;
+}
+function blocked(code, message, nextAction) {
+    return { ok: false, code, message, nextAction };
+}
+async function evidenceArchivePresent(controlRepoRoot, executionId) {
+    return (await verifyEvidenceArchive({ controlRepoRoot, executionId })).ok;
+}
+async function auditBranchTraceability(controlRepoRoot, baseCommit, nightBranch, schedule) {
+    const required = schedule.traceability?.requiredOnEveryPushableCommit ??
+        schedule.traceability?.requiredOnCreate ??
+        false;
+    if (!required)
+        return { ok: true };
+    const workItemRef = schedule.traceability?.workItemRef;
+    const card = validateTaskCard(workItemRef, {
+        required: true,
+        label: schedule.traceability?.label ?? "Task Card",
+        pattern: schedule.traceability?.pattern ?? "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$",
+        commitMessageTemplate: schedule.traceability?.commitMessageTemplate ??
+            "{summary}\n\n{workItemRef}",
+    });
+    if (!card.ok || !card.workItemRef) {
+        return {
+            ok: false,
+            reason: card.ok ? "missing workItemRef" : card.reason,
+        };
+    }
+    const log = (await runGit(controlRepoRoot, [
+        "log",
+        `${baseCommit}..${nightBranch}`,
+        "--format=%H%n%B%n==END==",
+    ])).trim();
+    if (!log) {
+        return { ok: false, reason: "no commits on night branch after base" };
+    }
+    const messages = log
+        .split("==END==")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    for (const block of messages) {
+        const body = block.split("\n").slice(1).join("\n");
+        if (!body.includes(card.workItemRef)) {
+            const sha = block.split("\n")[0] ?? "?";
+            return {
+                ok: false,
+                reason: `commit ${sha.slice(0, 12)} missing task card ${card.workItemRef}`,
+            };
+        }
+    }
+    return { ok: true };
+}
+async function runGit(cwd, args) {
+    const result = await runGitAllowFail(cwd, args);
+    if (result.exitCode !== 0) {
+        throw new Error(`git ${args.join(" ")} failed (exit ${result.exitCode}): ${result.stderr}`);
+    }
+    return result.stdout;
+}
+async function runGitAllowFail(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout?.on("data", (c) => stdout.push(c));
+        child.stderr?.on("data", (c) => stderr.push(c));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdout).toString("utf-8"),
+                stderr: Buffer.concat(stderr).toString("utf-8"),
+            });
+        });
+    });
+}
+// keep admission import used for future branch ownership checks
+void readAdmission;