@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/scheduler/doctor.js

@@ -0,0 +1,431 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { listTaskPoolStates } from "../pool/run-store.js";
+import { clockDoctorSeverity, readClockInstallReceipt, readClockReceipt, classifyClockHealth, countActiveExecutionLeases, } from "./clock.js";
+import { selectClockAdapter } from "./clock-install.js";
+import { getLeasesDir, getMutationLockPath, getSchedulerRoot, } from "./paths.js";
+import { classifyLeaseLiveness, classifyLeaseRecovery } from "./recovery.js";
+import { verifyEvidenceArchive } from "./evidence.js";
+import { readExecutionLease } from "./lease.js";
+import { listPendingJournals, listSchedules, readAdmission, readExecution, readLedgerEvents, } from "./store.js";
+import { evaluateOnceDue } from "./trigger.js";
+import { ACTIVE_SCHEDULE_STATUSES, isTerminalScheduleStatus, } from "./types.js";
+/**
+ * Read-only consistency check for Night Scheduler facts.
+ * Does not mutate; use lifecycle recover / explicit apply commands for repair.
+ */
+export async function diagnoseScheduler(controlRepoRoot, options) {
+    const now = options?.now ?? new Date();
+    const findings = [];
+    let schedules = [];
+    try {
+        schedules = await listSchedules(controlRepoRoot);
+    }
+    catch (error) {
+        findings.push({
+            code: "schedules-unreadable",
+            severity: "error",
+            message: `cannot list schedules: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const pending = await listPendingJournals(controlRepoRoot);
+    for (const journal of pending) {
+        findings.push({
+            code: "pending-transition-journal",
+            severity: "error",
+            scheduleId: journal.scheduleId,
+            message: `pending transition journal ${journal.transitionId} (${journal.fromStatus} → ${journal.toStatus}); run any mutation or doctor recover path`,
+        });
+    }
+    // Duplicate active schedule per task
+    const activeByTask = new Map();
+    for (const schedule of schedules) {
+        if (!ACTIVE_SCHEDULE_STATUSES.has(schedule.status))
+            continue;
+        const key = `${schedule.featureId}/${schedule.taskId}`;
+        const list = activeByTask.get(key) ?? [];
+        list.push(schedule);
+        activeByTask.set(key, list);
+    }
+    for (const [key, list] of activeByTask) {
+        if (list.length > 1) {
+            findings.push({
+                code: "duplicate-active-schedule",
+                severity: "error",
+                featureId: list[0]?.featureId,
+                taskId: list[0]?.taskId,
+                message: `multiple active schedules for ${key}: ${list.map((item) => item.id).join(", ")}`,
+            });
+        }
+    }
+    // Per-schedule structural checks
+    for (const schedule of schedules) {
+        if ((schedule.status === "scheduled" ||
+            schedule.status === "waiting" ||
+            schedule.status === "dispatching" ||
+            schedule.status === "running") &&
+            !schedule.trigger) {
+            findings.push({
+                code: "missing-trigger",
+                severity: "error",
+                scheduleId: schedule.id,
+                featureId: schedule.featureId,
+                taskId: schedule.taskId,
+                message: `status ${schedule.status} requires frozen once trigger`,
+            });
+        }
+        if (schedule.status === "scheduled" ||
+            schedule.status === "waiting" ||
+            schedule.status === "dispatching" ||
+            schedule.status === "running" ||
+            schedule.status === "succeeded") {
+            if (!schedule.admissionRef) {
+                findings.push({
+                    code: "missing-admission-ref",
+                    severity: "error",
+                    scheduleId: schedule.id,
+                    message: `status ${schedule.status} requires admissionRef (Phase 2 fills this; Phase 1 flags premature scheduled)`,
+                });
+            }
+            else {
+                const admission = await readAdmission(controlRepoRoot, schedule.id);
+                if (!admission) {
+                    findings.push({
+                        code: "admission-missing",
+                        severity: "error",
+                        scheduleId: schedule.id,
+                        message: `admissionRef present but admission file missing for ${schedule.id}`,
+                    });
+                }
+            }
+        }
+        if (isTerminalScheduleStatus(schedule.status) &&
+            schedule.currentExecutionId) {
+            const evidence = await verifyEvidenceArchive({
+                controlRepoRoot,
+                executionId: schedule.currentExecutionId,
+            });
+            if (!evidence.ok) {
+                findings.push({
+                    code: "evidence-integrity-failed",
+                    severity: "error",
+                    scheduleId: schedule.id,
+                    featureId: schedule.featureId,
+                    taskId: schedule.taskId,
+                    message: `evidence archive ${schedule.currentExecutionId} is invalid: ${evidence.reason}`,
+                });
+            }
+        }
+        if (schedule.traceability?.requiredOnCreate &&
+            !schedule.traceability.workItemRef &&
+            !isTerminalScheduleStatus(schedule.status)) {
+            findings.push({
+                code: "missing-task-card",
+                severity: "warning",
+                scheduleId: schedule.id,
+                message: "traceability.requiredOnCreate but workItemRef is empty",
+            });
+        }
+        if (schedule.status === "scheduled" &&
+            schedule.reservation?.taskPoolStatus !== "Queued") {
+            findings.push({
+                code: "missing-reservation",
+                severity: "warning",
+                scheduleId: schedule.id,
+                message: "scheduled record lacks Task Pool Queued reservation projection",
+            });
+        }
+    }
+    // Schedule ↔ Task Pool reservation consistency
+    let poolStates = [];
+    try {
+        poolStates = await listTaskPoolStates(controlRepoRoot);
+    }
+    catch (error) {
+        findings.push({
+            code: "task-pool-unreadable",
+            severity: "warning",
+            message: `cannot list Task Pool states: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const scheduleById = new Map(schedules.map((item) => [item.id, item]));
+    for (const state of poolStates) {
+        if (!state.nightScheduleId)
+            continue;
+        const schedule = scheduleById.get(state.nightScheduleId);
+        if (!schedule) {
+            findings.push({
+                code: "orphan-task-pool-reservation",
+                severity: "error",
+                featureId: state.featureId,
+                taskId: state.taskId,
+                scheduleId: state.nightScheduleId,
+                message: `Task Pool state references missing schedule ${state.nightScheduleId}`,
+            });
+            continue;
+        }
+        if (schedule.featureId !== state.featureId ||
+            schedule.taskId !== state.taskId) {
+            findings.push({
+                code: "reservation-identity-mismatch",
+                severity: "error",
+                scheduleId: schedule.id,
+                featureId: state.featureId,
+                taskId: state.taskId,
+                message: `Task Pool reservation identity ${state.featureId}/${state.taskId} does not match schedule ${schedule.featureId}/${schedule.taskId}`,
+            });
+        }
+        if (ACTIVE_SCHEDULE_STATUSES.has(schedule.status) &&
+            state.status !== "Queued" &&
+            state.status !== "Running" &&
+            state.status !== "Done" &&
+            state.status !== "Failed") {
+            findings.push({
+                code: "reservation-status-mismatch",
+                severity: "warning",
+                scheduleId: schedule.id,
+                featureId: state.featureId,
+                taskId: state.taskId,
+                message: `active schedule ${schedule.id} but Task Pool status is ${state.status}`,
+            });
+        }
+    }
+    for (const schedule of schedules) {
+        if (schedule.status !== "scheduled" &&
+            schedule.status !== "waiting" &&
+            schedule.status !== "dispatching") {
+            continue;
+        }
+        const bound = poolStates.find((state) => state.featureId === schedule.featureId &&
+            state.taskId === schedule.taskId &&
+            state.nightScheduleId === schedule.id);
+        if (!bound) {
+            findings.push({
+                code: "schedule-missing-pool-projection",
+                severity: "warning",
+                scheduleId: schedule.id,
+                featureId: schedule.featureId,
+                taskId: schedule.taskId,
+                message: `schedule ${schedule.id} has no Task Pool state bound via nightScheduleId`,
+            });
+        }
+    }
+    // Stale mutation lock
+    try {
+        const lockOwnerPath = path.join(getMutationLockPath(controlRepoRoot), "owner.json");
+        const raw = await readFile(lockOwnerPath, "utf-8");
+        const owner = JSON.parse(raw);
+        findings.push({
+            code: "mutation-lock-present",
+            severity: "warning",
+            message: `mutation lock present (pid=${owner.pid ?? "?"}, acquiredAt=${owner.acquiredAt ?? "?"})`,
+        });
+    }
+    catch {
+        // no lock — ok
+    }
+    // Lease recovery classification (Phase 4)
+    try {
+        const leaseDir = getLeasesDir(controlRepoRoot);
+        const leases = await readdir(leaseDir);
+        for (const name of leases) {
+            if (!name.endsWith(".json"))
+                continue;
+            const scheduleId = name.slice(0, -5);
+            const schedule = scheduleById.get(scheduleId);
+            const lease = await readExecutionLease(controlRepoRoot, scheduleId);
+            if (!schedule) {
+                findings.push({
+                    code: "orphan-lease",
+                    severity: "warning",
+                    scheduleId,
+                    message: `lease file exists without schedule snapshot ${scheduleId}`,
+                });
+                continue;
+            }
+            let execution = schedule.currentExecutionId
+                ? await readExecution(controlRepoRoot, schedule.currentExecutionId)
+                : undefined;
+            if (!execution && lease?.executionId) {
+                execution = await readExecution(controlRepoRoot, lease.executionId);
+            }
+            const classification = classifyLeaseRecovery({
+                schedule,
+                ...(lease ? { lease } : {}),
+                ...(execution ? { execution } : {}),
+                now,
+            });
+            const liveness = classifyLeaseLiveness(lease, now);
+            if (classification.kind === "termination-unconfirmed") {
+                findings.push({
+                    code: "termination-unconfirmed",
+                    severity: "error",
+                    scheduleId,
+                    featureId: schedule.featureId,
+                    taskId: schedule.taskId,
+                    message: `${classification.reason} (liveness=${liveness}); do not start a second writer`,
+                });
+            }
+            else if (classification.kind === "safe-reclaim") {
+                findings.push({
+                    code: "orphan-claim-reclaimable",
+                    severity: "warning",
+                    scheduleId,
+                    message: `${classification.reason}; next tick will reclaim`,
+                });
+            }
+            else if (isTerminalScheduleStatus(schedule.status) ||
+                classification.kind === "already-terminal") {
+                findings.push({
+                    code: "orphan-lease",
+                    severity: "warning",
+                    scheduleId,
+                    message: `lease remains on terminal/recoverable schedule ${scheduleId}`,
+                });
+            }
+        }
+    }
+    catch {
+        // leases dir may not exist yet
+    }
+    // Ledger readability sample
+    try {
+        await readLedgerEvents(controlRepoRoot);
+    }
+    catch (error) {
+        findings.push({
+            code: "ledger-unreadable",
+            severity: "error",
+            message: `ledger unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    // Root existence info
+    try {
+        await readdir(getSchedulerRoot(controlRepoRoot));
+    }
+    catch {
+        findings.push({
+            code: "scheduler-root-missing",
+            severity: "info",
+            message: "scheduler root does not exist yet (no schedules submitted)",
+        });
+    }
+    // Clock health (OS timer + tick receipt)
+    try {
+        const [clockReceipt, clockInstall, activeLeaseCount] = await Promise.all([
+            readClockReceipt(controlRepoRoot),
+            readClockInstallReceipt(controlRepoRoot),
+            countActiveExecutionLeases(controlRepoRoot, now),
+        ]);
+        const adapter = selectClockAdapter();
+        let unitPresent = null;
+        let unitLoaded = null;
+        let configMatches = null;
+        let providerSupported = adapter != null;
+        if (adapter) {
+            providerSupported = await adapter.isAvailable();
+            if (clockInstall) {
+                const probe = await adapter.probe({
+                    receipt: clockInstall,
+                    unitName: clockInstall.unitName,
+                });
+                unitPresent = probe.present;
+                unitLoaded = probe.loaded;
+                configMatches = probe.configMatches;
+            }
+        }
+        const health = classifyClockHealth({
+            now,
+            receipt: clockReceipt,
+            install: clockInstall,
+            unitPresent,
+            unitLoaded,
+            configMatches,
+            providerSupported,
+            activeLeaseCount,
+            defaultMaxConcurrency: 1,
+        });
+        const futureScheduled = schedules.some((schedule) => (schedule.status === "scheduled" || schedule.status === "waiting") &&
+            schedule.trigger?.type === "once" &&
+            Date.parse(schedule.trigger.executeAtUtc) > now.getTime());
+        const dueUnclaimed = schedules.some((schedule) => {
+            if (schedule.status !== "scheduled" && schedule.status !== "waiting") {
+                return false;
+            }
+            const trigger = schedule.trigger;
+            if (!trigger || trigger.type !== "once")
+                return false;
+            const decision = evaluateOnceDue({
+                nowUtc: now,
+                executeAtUtc: trigger.executeAtUtc,
+                ...(trigger.latestStartAtUtc
+                    ? { latestStartAtUtc: trigger.latestStartAtUtc }
+                    : {}),
+                timezone: trigger.displayTimezone ??
+                    schedule.policySnapshot?.timezone ??
+                    "Asia/Shanghai",
+                allowedHours: schedule.policySnapshot?.allowedHours ?? ["00:00-08:00"],
+                misfirePolicy: trigger.misfirePolicy ??
+                    schedule.policySnapshot?.misfirePolicy ??
+                    "wait-next-window",
+            });
+            return decision.kind === "eligible";
+        });
+        const severity = clockDoctorSeverity({
+            health,
+            hasFutureScheduled: futureScheduled,
+            hasDueUnclaimed: dueUnclaimed,
+        });
+        if (severity) {
+            findings.push({
+                code: `clock-${health.status}`,
+                severity,
+                message: `${health.message}${health.nextAction ? ` Next: ${health.nextAction}` : ""}`,
+            });
+        }
+    }
+    catch (error) {
+        findings.push({
+            code: "clock-unreadable",
+            severity: "warning",
+            message: `cannot classify clock health: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const activeCount = schedules.filter((item) => ACTIVE_SCHEDULE_STATUSES.has(item.status)).length;
+    const errors = findings.filter((item) => item.severity === "error");
+    return {
+        schemaVersion: 1,
+        generatedAt: now.toISOString(),
+        controlRepoRoot,
+        scheduleCount: schedules.length,
+        activeCount,
+        pendingJournalCount: pending.length,
+        findings,
+        ok: errors.length === 0,
+    };
+}
+export function formatSchedulerDoctorHuman(report) {
+    const lines = [
+        `Night Scheduler doctor`,
+        `root: ${report.controlRepoRoot}`,
+        `schedules: ${report.scheduleCount} (active ${report.activeCount})`,
+        `pending journals: ${report.pendingJournalCount}`,
+        `status: ${report.ok ? "ok" : "issues found"}`,
+        "",
+    ];
+    if (report.findings.length === 0) {
+        lines.push("No findings.");
+    }
+    else {
+        for (const finding of report.findings) {
+            const where = finding.scheduleId
+                ? ` [${finding.scheduleId}]`
+                : finding.featureId
+                    ? ` [${finding.featureId}/${finding.taskId ?? "?"}]`
+                    : "";
+            lines.push(`- (${finding.severity}) ${finding.code}${where}: ${finding.message}`);
+        }
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}

package/dist/worker/scheduler/evidence.js

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, readdir, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getEvidenceDir } from "./paths.js";
+/**
+ * Copy terminal evidence into control-root archive so worktree can be deleted later.
+ * Missing optional sources are skipped; manifest always written.
+ */
+export async function archiveExecutionEvidence(input) {
+    const now = input.now ?? new Date();
+    const archiveRoot = path.join(getEvidenceDir(input.controlRepoRoot), input.executionId);
+    await mkdir(archiveRoot, { recursive: true });
+    const files = [];
+    const writeJson = async (relativePath, value) => {
+        const target = resolveArchiveTarget(archiveRoot, relativePath);
+        await mkdir(path.dirname(target), { recursive: true });
+        const text = `${JSON.stringify(value, null, 2)}\n`;
+        await writeFile(target, text, "utf-8");
+        files.push({
+            relativePath,
+            sha256: `sha256:${createHash("sha256").update(text, "utf-8").digest("hex")}`,
+            bytes: Buffer.byteLength(text, "utf-8"),
+        });
+    };
+    await writeJson("schedule.json", input.schedule);
+    await writeJson("execution.json", input.execution);
+    if (input.admission) {
+        await writeJson("admission.json", input.admission);
+    }
+    const candidates = [
+        ...(input.extraFiles ?? []),
+    ];
+    if (input.workspaceRoot && input.admission?.harnessTaskId) {
+        const taskDir = path.join(input.workspaceRoot, ".harness", "tasks", input.admission.harnessTaskId);
+        candidates.push({
+            absolutePath: path.join(taskDir, "artifacts", "worker-run-record.json"),
+            relativePath: "workspace/worker-run-record.json",
+        }, {
+            absolutePath: path.join(taskDir, "dag.json"),
+            relativePath: "workspace/dag.json",
+        }, {
+            absolutePath: path.join(taskDir, "artifacts", "admission-dag.json"),
+            relativePath: "workspace/admission-dag.json",
+        });
+        if (input.admission.dag?.path) {
+            const dagAbs = path.isAbsolute(input.admission.dag.path)
+                ? input.admission.dag.path
+                : path.join(input.workspaceRoot, input.admission.dag.path);
+            candidates.push({
+                absolutePath: dagAbs,
+                relativePath: "workspace/frozen-dag.json",
+            });
+        }
+    }
+    for (const candidate of candidates) {
+        const target = resolveArchiveTarget(archiveRoot, candidate.relativePath);
+        try {
+            const st = await stat(candidate.absolutePath);
+            if (!st.isFile())
+                continue;
+            await mkdir(path.dirname(target), { recursive: true });
+            await copyFile(candidate.absolutePath, target);
+            const raw = await readFile(target);
+            files.push({
+                relativePath: candidate.relativePath,
+                sha256: `sha256:${createHash("sha256").update(raw).digest("hex")}`,
+                bytes: raw.byteLength,
+            });
+        }
+        catch {
+            // optional
+        }
+    }
+    // Best-effort: copy only the latest completed DAG run bound to this task.
+    if (input.workspaceRoot && input.admission?.harnessTaskId) {
+        try {
+            const dagRuns = path.join(input.workspaceRoot, ".harness", "dag-runs", "completed");
+            const entries = (await readdir(dagRuns)).sort().reverse();
+            for (const name of entries) {
+                const runPath = path.join(dagRuns, name, "run.json");
+                try {
+                    const runRaw = await readFile(runPath, "utf-8");
+                    const run = JSON.parse(runRaw);
+                    const boundTaskId = run.taskContractBinding?.taskId ?? run.sourceBinding?.taskId;
+                    if (boundTaskId !== input.admission.harnessTaskId)
+                        continue;
+                    for (const fileName of ["run.json", "state.json"]) {
+                        const source = path.join(dagRuns, name, fileName);
+                        const relativePath = `workspace/dag-runs/${name}/${fileName}`;
+                        const target = resolveArchiveTarget(archiveRoot, relativePath);
+                        await mkdir(path.dirname(target), { recursive: true });
+                        await copyFile(source, target);
+                        const raw = await readFile(target);
+                        files.push({
+                            relativePath,
+                            sha256: `sha256:${createHash("sha256").update(raw).digest("hex")}`,
+                            bytes: raw.byteLength,
+                        });
+                    }
+                    break;
+                }
+                catch {
+                    // Not a readable/matching completed run.
+                }
+            }
+        }
+        catch {
+            // no completed runs
+        }
+    }
+    const manifest = {
+        schemaVersion: 1,
+        executionId: input.executionId,
+        scheduleId: input.schedule.id,
+        createdAt: now.toISOString(),
+        files,
+        archiveRoot: path
+            .relative(input.controlRepoRoot, archiveRoot)
+            .split(path.sep)
+            .join("/"),
+    };
+    await writeJsonAtomic(path.join(archiveRoot, "manifest.json"), manifest, {
+        repoRoot: input.controlRepoRoot,
+    });
+    return manifest;
+}
+export async function verifyEvidenceArchive(input) {
+    const archiveRoot = path.join(getEvidenceDir(input.controlRepoRoot), input.executionId);
+    try {
+        const raw = await readFile(path.join(archiveRoot, "manifest.json"), "utf-8");
+        const manifest = JSON.parse(raw);
+        if (manifest?.schemaVersion !== 1 ||
+            manifest.executionId !== input.executionId ||
+            !Array.isArray(manifest.files)) {
+            return { ok: false, reason: "manifest-shape-invalid" };
+        }
+        for (const file of manifest.files) {
+            const target = resolveArchiveTarget(archiveRoot, file.relativePath);
+            const bytes = await readFile(target);
+            const actual = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+            if (bytes.byteLength !== file.bytes || actual !== file.sha256) {
+                return {
+                    ok: false,
+                    reason: `file-integrity-mismatch:${file.relativePath}`,
+                };
+            }
+        }
+        return { ok: true, manifest };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function resolveArchiveTarget(archiveRoot, relativePath) {
+    if (!relativePath || path.isAbsolute(relativePath)) {
+        throw new Error(`unsafe evidence relativePath: ${relativePath}`);
+    }
+    const target = path.resolve(archiveRoot, relativePath);
+    const relative = path.relative(path.resolve(archiveRoot), target);
+    if (relative.length === 0 ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new Error(`evidence path escapes archive root: ${relativePath}`);
+    }
+    return target;
+}

package/dist/worker/scheduler/git-base.js

@@ -0,0 +1,90 @@
+import { spawn } from "node:child_process";
+/**
+ * Scheduler/Task Pool runtime under `.harness` and night worktrees are expected
+ * control facts. They must not block admission/harvest of source commits.
+ */
+export function isSchedulerRuntimeGitPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return (normalized === ".harness" ||
+        normalized === ".worktrees" ||
+        normalized.startsWith(".harness/") ||
+        normalized.startsWith(".worktrees/"));
+}
+/**
+ * Parse `git status --porcelain=v1` and return source-path dirty lines only.
+ * XY markers occupy the first two columns; path starts at index 3.
+ */
+export function filterSourceDirtyPorcelain(statusPorcelain) {
+    return statusPorcelain
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter(Boolean)
+        .filter((line) => {
+        // Rename lines: `R  old -> new` — treat either side as dirty source.
+        const body = line.slice(3).trim();
+        if (body.includes(" -> ")) {
+            const [from, to] = body.split(" -> ").map((part) => part.trim());
+            return ((from ? !isSchedulerRuntimeGitPath(from) : false) ||
+                (to ? !isSchedulerRuntimeGitPath(to) : false));
+        }
+        return !isSchedulerRuntimeGitPath(body);
+    });
+}
+/**
+ * Freeze the control repo HEAD as admission base.
+ * MVP requires a named branch and a clean *source* working tree.
+ * Runtime facts under `.harness/**` / `.worktrees/**` are ignored (ADR 0009).
+ */
+export async function freezeCleanBase(controlRepoRoot) {
+    const branch = (await runGit(controlRepoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    const isDetached = branch === "HEAD";
+    const baseCommit = (await runGit(controlRepoRoot, ["rev-parse", "HEAD"])).trim();
+    const statusPorcelain = (await runGit(controlRepoRoot, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+    ])).trimEnd();
+    const dirtySourceLines = filterSourceDirtyPorcelain(statusPorcelain);
+    const isClean = dirtySourceLines.length === 0;
+    if (isDetached) {
+        throw new Error("admission requires a named base branch (detached HEAD is not allowed)");
+    }
+    if (!isClean) {
+        const sample = dirtySourceLines
+            .slice(0, 5)
+            .map((line) => line.slice(3).trim())
+            .join(", ");
+        throw new Error(`admission requires a clean Git working tree on the base branch${sample ? ` (dirty source: ${sample})` : ""}`);
+    }
+    return {
+        baseBranch: branch,
+        baseCommit,
+        isClean,
+        isDetached,
+        statusPorcelain,
+        dirtySourceLines,
+    };
+}
+export async function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", (err) => {
+            reject(new Error(`git ${args.join(" ")} spawn error: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+            const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+            if (code !== 0) {
+                reject(new Error(`git ${args.join(" ")} failed (exit ${code}): ${stderr.trim()}`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}