@tea-agent/loop-agent 0.28.12-beta.1 → 0.28.13

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## [Unreleased]
 
+## [0.28.13] - 2026-08-06
+
+### 重点更新
+
+- 显著缩短 CI 与发布流程的测试耗时，优化 2 vCPU runner 上的并发策略
+- 修复集成测试在多核环境下因工作区指纹竞态导致的不稳定问题
+
+### 改进
+
+- 优化 CI/发布环境的测试执行效率：固定 fast 测试池为 2 个 worker，移除重复的 pre-prepare 类型检查，并将 npm dist-tag 收敛轮询改为前快后慢的退避策略
+- 默认 fast 测试池现按可用 CPU 核数（上限 4）分配，避免在 2 核环境下意外退化为串行执行
+
+### 修复
+
+- 修复集成测试在多 worker 下因读取工作区指纹竞态导致的包校验不稳定问题，现固定集成测试为串行执行
+- 修复 pre-push 验证收据漂移测试受 CI 环境固定 worker 数量影响的问题，确保使用不同值以正确验证指纹失效场景
+
+## [0.28.12] - 2026-08-06
+
+### 重点更新
+
+- Night Scheduler 交付 Clock Guarantee，支持通过 macOS、Linux 和 Windows 原生系统定时器自动周期触发调度
+- 加固前端 DAG 验证的回退机制与 JSON 解析，提升复杂环境下的容错能力
+- 修复 pre-push 验证在本地缺失远程提交记录时异常中断的问题，保障推送流程顺畅
+
+### 新增
+
+- 新增 `scheduler clock install|status|uninstall` 命令，支持安装用户级别的 launchd、systemd 和 schtasks 定时器
+- 统一 Clock receipt 记录机制，使手动触发与系统定时触发共享运行状态
+- 新增 Clock 健康状态分类器，并接入 doctor、morning 和 scheduler add 的状态反馈
+
+### 改进
+
+- 改进 `--verify` 相关文档示例，不再硬编码特定命令，改用占位符并指向项目配置文件以避免误导
+- 规范化初始化升级测试套件的代码格式，使其符合项目的统一排版规范
+
+### 修复
+
+- 修复 pre-push 验证在本地无法解析远程最新提交 SHA 时直接报错中断的问题，现会安全回退到完整验证流程
+- 修复 CI 环境下因系统定时器精度不足导致的重试退避时间断言不稳定问题
+- 修复前端 DAG 验证 JSON 解析及覆盖率证据推导的问题，增强验证回退机制的健壮性
+- 修复任务草稿复用时因缺少 `--dag-output` 参数导致无法正确导出 DAG 的问题
+- 修复空事实情况下误触发契约准备的问题，现会安全软停止并提示需要输入
+- 修复 macOS 下因路径别名导致初始化升级测试中写入保护用例失败的问题
+
 ## [0.28.11] - 2026-08-06
 
 ### 重点更新
@@ -98,7 +143,7 @@
 
 ### 修复
 
-- Night Scheduler 准入控制：freezeCleanBase 忽略 .harness/** 与 .worktrees/** 运行态事实，避免 lifecycle 运行事实自污染导致 clean-tree 误拒，同时保留失败 admission 的 submitted → rejected 审计链
+- Night Scheduler 准入控制：freezeCleanBase 忽略 .harness/**与 .worktrees/** 运行态事实，避免 lifecycle 运行事实自污染导致 clean-tree 误拒，同时保留失败 admission 的 submitted → rejected 审计链
 - 调整 freezeCleanBase 的执行顺序，将其提前至 submitSchedule 之前，确保 baseCommit 能在调度器写入控制文件前正确捕获 HEAD
 - freezeCleanBase 将 .harness 与 .worktrees 视为非源码脏污（与 harvest 逻辑共享），避免准入流程自写入的调度事实干扰基线冻结
 

package/README.md

@@ -70,7 +70,7 @@ loop-agent task advance example-task "实现一个有明确验收标准的小功
   --prd path/to/prd.md \
   --allowed-path "src/**" \
   --forbidden-path ".harness/**" \
-  --verify "typecheck:npm run typecheck" \
+  --verify "<label>:<command>" \
   --json
 
 # 审查返回的 writeSet / gate.digest 后，同一命令批准并长跑到稳定终态
@@ -82,6 +82,8 @@ loop-agent task advance example-task \
 loop-agent task status example-task --json
 ```
 
+`--verify` 命令应取项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的验证命令（不要假定 `npm run typecheck` 存在）；`--verify` 可选，省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
+
 首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG，然后停在 writeSet gate；未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
 
 ## 查看执行状态

package/dist/application/task-lifecycle/advance.js

@@ -50,6 +50,24 @@ function uniqueTransitions(existing, extra) {
         set.add(item);
     return [...set];
 }
+/**
+ * Materialize `--dag-output` from the task DAG draft (or an explicit source).
+ * Must run even when generate-dag is skipped because a draft already exists —
+ * Console prepareConfirmDag relies on this side effect.
+ */
+async function exportDagDraftIfRequested(repoRoot, taskId, dagOutputPath, sourcePath) {
+    if (!dagOutputPath?.trim())
+        return;
+    const from = sourcePath ?? getTaskPaths(repoRoot, taskId).dagDraftPath;
+    try {
+        await access(from);
+    }
+    catch {
+        return;
+    }
+    await mkdir(path.dirname(dagOutputPath), { recursive: true });
+    await copyFile(from, dagOutputPath);
+}
 function extractMeaningfulProgressAt(state) {
     const activeNode = Object.values(state.nodes ?? {}).find((node) => node.status === "RUNNING");
     if (activeNode) {
@@ -549,10 +567,7 @@ export async function advanceTaskLifecycle(input) {
                     });
                     break;
                 }
-                if (input.dagOutputPath) {
-                    await mkdir(path.dirname(input.dagOutputPath), { recursive: true });
-                    await copyFile(generated.outputPath, input.dagOutputPath);
-                }
+                await exportDagDraftIfRequested(input.repoRoot, input.taskId, input.dagOutputPath, generated.outputPath);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -633,6 +648,7 @@ export async function advanceTaskLifecycle(input) {
             completed.push("write-set-gate-opened");
             await saveLifecycleRecord(input.repoRoot, record);
             snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            await exportDagDraftIfRequested(input.repoRoot, input.taskId, input.dagOutputPath);
             // Stop before writers.
             return {
                 taskId: input.taskId,
@@ -852,6 +868,7 @@ export async function advanceTaskLifecycle(input) {
         ? (snapshot.gate ??
             (await buildCurrentGate(input.repoRoot, input.taskId)))
         : snapshot.gate;
+    await exportDagDraftIfRequested(input.repoRoot, input.taskId, input.dagOutputPath);
     return {
         taskId: input.taskId,
         lifecycleState: snapshot.lifecycleState,

package/dist/application/task-lifecycle/plan-transitions.js

@@ -87,8 +87,7 @@ export function planTransitions(input) {
         }
         if (shouldImportPrd ||
             input.hasEngineeringBoundary ||
-            alreadyImportedPrd ||
-            snapshot.exists) {
+            alreadyImportedPrd) {
             if (shouldImportPrd) {
                 actions.push({ type: "import-prd" });
                 expectedTransitions.push("prd-imported");
@@ -97,11 +96,24 @@ export function planTransitions(input) {
             expectedTransitions.push("contract-managed");
         }
         else {
+            // Task exists (e.g. just created in this advance loop) but intake is
+            // still incomplete. Soft-stop with INTAKE_REQUIRED so create-only /
+            // Console bootstrap does not attempt prepare-contract on empty facts.
+            actions.push({ type: "stop", reason: "blocker" });
             blockers.push({
-                code: "CONTRACT_INCOMPLETE",
-                message: "source/contract not ready; re-run advance with PRD and boundaries",
+                code: "INTAKE_REQUIRED",
+                message: "task created or creatable; provide --prd and engineering boundary flags (or --from-text) to continue",
             });
-            return stopWith(actions, expectedTransitions, blockers, snapshot, "blocker");
+            return {
+                actions,
+                gate: null,
+                blockers,
+                next: {
+                    kind: "advance",
+                    command: `loop-agent task advance ${snapshot.taskId} --prd <path> --allowed-path <glob> --json`,
+                },
+                expectedTransitions,
+            };
         }
     }
     const dagExists = snapshot.dagDraft?.exists === true;

package/dist/commands/import-prd.js

@@ -63,7 +63,7 @@ export async function runImportPrd(repoRoot, args) {
             referenceDocs: result.referenceDocs,
             message: "Imported PRD as an immutable source reference. Next: task source prepare --use-imported-prd (plus engineering --allowed-path/--verify) then --apply. Do not rewrite source/references/*.",
             next: [
-                `loop-agent task source prepare ${result.taskId} --use-imported-prd --allowed-path <glob> --verify "typecheck:npm run typecheck" --json`,
+                `loop-agent task source prepare ${result.taskId} --use-imported-prd --allowed-path <glob> --verify "<label>:<command>" --json`,
                 `loop-agent task source prepare ${result.taskId} --use-imported-prd --allowed-path <glob> --apply --json`,
             ],
         }, null, 2));

package/dist/commands/init.js

@@ -1954,7 +1954,7 @@ function buildManagedReadmeBlock(input) {
         'loop-agent task advance <task-id> "任务标题" \\',
         "  --prd <prd.md> \\",
         '  --allowed-path "<glob>" \\',
-        '  --verify "typecheck:npm run typecheck" \\',
+        '  --verify "<label>:<command>" \\',
         "  --json",
         "# 审查 writeSet gate digest 后：",
         'loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json',
@@ -2188,7 +2188,7 @@ function buildTargetFeatureWorkflow(input) {
         'loop-agent task advance <task-id> "Task title" \\',
         "  --prd <prd.md> \\",
         '  --allowed-path "<glob>" \\',
-        '  --verify "typecheck:npm run typecheck" \\',
+        '  --verify "<label>:<command>" \\',
         "  --json",
         "# Review writeSet gate digest, then:",
         'loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json',

package/dist/shared/operator/capabilities.js

@@ -2175,6 +2175,27 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
         source: "agent-worker",
         exclusionReason: "Daemon/clock path; not exposed to Operator Chat (use CLI/cron).",
     },
+    {
+        command: "agent-worker scheduler clock install",
+        coverage: "excluded",
+        action: null,
+        source: "agent-worker",
+        exclusionReason: "OS timer install is CLI-only; Operator Console does not manage launchd/systemd/schtasks.",
+    },
+    {
+        command: "agent-worker scheduler clock status",
+        coverage: "excluded",
+        action: null,
+        source: "agent-worker",
+        exclusionReason: "Clock status is CLI-only in MVP; use scheduler doctor for Console-facing health.",
+    },
+    {
+        command: "agent-worker scheduler clock uninstall",
+        coverage: "excluded",
+        action: null,
+        source: "agent-worker",
+        exclusionReason: "OS timer uninstall is CLI-only; not exposed to Operator Chat.",
+    },
     {
         command: "agent-worker scheduler submit",
         coverage: "excluded",

package/dist/worker/console/operator-actions.js

@@ -689,6 +689,17 @@ export async function dispatchOperatorAction(ctx, req) {
                     };
                 }
                 dagText = await readFile(staged.path, "utf8");
+                if (!dagText.trim()) {
+                    // Fallback: advance may skip generate-dag when a draft already
+                    // exists; still prefer the task DAG over an empty staged file.
+                    const taskDagPath = getTaskPaths(ctx.repoRoot, taskId).dagDraftPath;
+                    try {
+                        dagText = await readFile(taskDagPath, "utf8");
+                    }
+                    catch {
+                        dagText = "";
+                    }
+                }
                 if (!dagText.trim()) {
                     return {
                         kind: "error",

package/dist/worker/scheduler/cli.js

@@ -6,6 +6,8 @@ import { diagnoseScheduler, formatSchedulerDoctorHuman } from "./doctor.js";
 import { readAdmission, readLedgerEvents, recoverAllPendingJournals, } from "./store.js";
 import { discardNightSchedule, harvestNightSchedule } from "./night-harvest.js";
 import { schedulerTick } from "./scheduler-loop.js";
+import { formatClockHealthHuman, runRecordedSchedulerTick, } from "./clock.js";
+import { detectClockSourceFromEnv, installClockTimer, statusClockTimer, uninstallClockTimer, } from "./clock-install.js";
 import { scheduleStatusSchema, SchedulerError, } from "./types.js";
 import { parseOnceLocalToUtc } from "./trigger.js";
 /**
@@ -80,12 +82,43 @@ export function registerSchedulerCommands(program) {
         .option("--json", "Emit JSON")
         .action(async (scheduleId, options) => {
         try {
+            const controlRepoRoot = path.resolve(options.repo);
             const result = await addSchedule({
-                controlRepoRoot: path.resolve(options.repo),
+                controlRepoRoot,
                 scheduleId,
                 approveGate: options.approveGate,
             });
-            emit(options.json, result, () => formatScheduleHuman(result.schedule));
+            // Soft clock hint only — never hard-gate schedule creation.
+            let clockHint = null;
+            try {
+                const clock = await statusClockTimer({ controlRepoRoot });
+                clockHint = {
+                    status: clock.health.status,
+                    nextAction: clock.health.nextAction,
+                };
+            }
+            catch {
+                clockHint = null;
+            }
+            const payload = { ...result, clock: clockHint };
+            emit(options.json, payload, () => {
+                const base = formatScheduleHuman(result.schedule);
+                if (!clockHint || clockHint.status === "healthy")
+                    return base;
+                const lines = [
+                    base.trimEnd(),
+                    `Clock: ${clockHint.status}`,
+                    "Automatic invocation is not currently guaranteed.",
+                ];
+                if (clockHint.nextAction) {
+                    lines.push(`Next: ${clockHint.nextAction}`);
+                }
+                else {
+                    lines.push("Next: agent-worker scheduler clock install --repo .");
+                }
+                lines.push("");
+                return `${lines.join("\n")}\n`;
+            });
         }
         catch (error) {
             handleSchedulerCliError(error, options.json === true);
@@ -251,6 +284,7 @@ export function registerSchedulerCommands(program) {
         .requiredOption("--repo <repo-root>", "Control repo root")
         .option("--loop-agent-bin <path>", "Published loop-agent binary")
         .option("--max-claims <n>", "Max schedules to claim this tick", "1")
+        .option("--clock-source <source>", "Clock receipt source (manual|launchd|systemd-user|schtasks|clock-run)")
         .option("--json", "Emit JSON")
         .action(async (options) => {
         try {
@@ -261,10 +295,15 @@ export function registerSchedulerCommands(program) {
                 resolveIdentity: true,
             });
             const maxClaims = Number(options.maxClaims ?? "1");
-            const result = await schedulerTick({
+            const source = detectClockSourceFromEnv(options.clockSource);
+            const result = await runRecordedSchedulerTick({
                 controlRepoRoot,
-                client,
-                maxClaims: Number.isFinite(maxClaims) ? maxClaims : 1,
+                source,
+                tick: () => schedulerTick({
+                    controlRepoRoot,
+                    client,
+                    maxClaims: Number.isFinite(maxClaims) ? maxClaims : 1,
+                }),
             });
             if (options.json) {
                 process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -276,6 +315,72 @@ export function registerSchedulerCommands(program) {
             handleSchedulerCliError(error, options.json === true);
         }
     });
+    const clock = scheduler
+        .command("clock")
+        .description("OS timer install / status / uninstall for automatic scheduler tick");
+    clock
+        .command("install")
+        .description("Install or idempotently update user-level OS timer that runs scheduler tick")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--interval-sec <n>", "Tick interval in seconds (default 60)", "60")
+        .option("--loop-agent-bin <path>", "Published loop-agent binary")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const intervalSec = Number(options.intervalSec ?? "60");
+            const result = await installClockTimer({
+                controlRepoRoot: path.resolve(options.repo),
+                intervalSec: Number.isFinite(intervalSec) ? intervalSec : 60,
+                ...(options.loopAgentBin
+                    ? { loopAgentBin: options.loopAgentBin }
+                    : {}),
+            });
+            emit(options.json, result, () => [
+                result.message,
+                `Provider: ${result.provider}`,
+                `Interval: ${result.receipt.intervalSec}s`,
+                `Repo: ${result.receipt.controlRepoRoot}`,
+                `Unit: ${result.receipt.unitName}`,
+                "Next: agent-worker scheduler clock status --repo .",
+                "",
+            ].join("\n"));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    clock
+        .command("status")
+        .description("Show OS timer + install receipt + tick health (read-only)")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const result = await statusClockTimer({
+                controlRepoRoot: path.resolve(options.repo),
+            });
+            emit(options.json, result, () => formatClockHealthHuman(result.health));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    clock
+        .command("uninstall")
+        .description("Remove ownership-matched managed OS timer (keeps schedule/receipt history)")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const result = await uninstallClockTimer({
+                controlRepoRoot: path.resolve(options.repo),
+            });
+            emit(options.json, result, () => `${result.message}\n`);
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
     scheduler
         .command("harvest")
         .description("Exact-base fast-forward night branch into base (succeeded + pending-harvest only)")

package/dist/worker/scheduler/clock-install/darwin-launchd.js

@@ -0,0 +1,238 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { deriveClockUnitName, hashManagedConfig, } from "../clock.js";
+import { MANAGED_MARKER } from "./types.js";
+function launchAgentsDir() {
+    return path.join(os.homedir(), "Library", "LaunchAgents");
+}
+function plistPath(unitName) {
+    return path.join(launchAgentsDir(), `${unitName}.plist`);
+}
+export function renderLaunchdPlist(input) {
+    const args = [
+        input.nodeBin,
+        input.agentWorkerEntry,
+        "scheduler",
+        "tick",
+        "--repo",
+        input.controlRepoRoot,
+        "--loop-agent-bin",
+        input.loopAgentBin,
+        "--clock-source",
+        "launchd",
+        "--json",
+    ];
+    const programArgs = args
+        .map((arg) => `\t\t<string>${escapeXml(arg)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${escapeXml(input.unitName)}</string>
+\t<key>Comment</key>
+\t<string>${MANAGED_MARKER} ${escapeXml(input.managedConfigHash)}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${programArgs}
+\t</array>
+\t<key>StartInterval</key>
+\t<integer>${input.intervalSec}</integer>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>WorkingDirectory</key>
+\t<string>${escapeXml(input.controlRepoRoot)}</string>
+\t<key>StandardOutPath</key>
+\t<string>${escapeXml(path.join(input.controlRepoRoot, ".harness/task-pool/scheduler/clock-launchd.out.log"))}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${escapeXml(path.join(input.controlRepoRoot, ".harness/task-pool/scheduler/clock-launchd.err.log"))}</string>
+\t<key>ProcessType</key>
+\t<string>Background</string>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+async function runLaunchctl(args) {
+    return new Promise((resolve) => {
+        const child = spawn("launchctl", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("close", (code) => {
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+        child.on("error", (error) => {
+            resolve({
+                code: 1,
+                stdout,
+                stderr: error instanceof Error ? error.message : String(error),
+            });
+        });
+    });
+}
+export const darwinLaunchdAdapter = {
+    provider: "launchd",
+    async isAvailable() {
+        if (process.platform !== "darwin")
+            return false;
+        try {
+            await access("/bin/launchctl");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    unitName(controlRepoRoot) {
+        return deriveClockUnitName(controlRepoRoot);
+    },
+    renderConfig(input) {
+        return renderLaunchdPlist({
+            unitName: input.receipt.unitName,
+            intervalSec: input.receipt.intervalSec,
+            nodeBin: input.entrypoints.nodeBin,
+            agentWorkerEntry: input.entrypoints.agentWorkerEntry,
+            controlRepoRoot: input.entrypoints.controlRepoRoot,
+            loopAgentBin: input.entrypoints.loopAgentBin,
+            managedConfigHash: input.receipt.managedConfigHash,
+        });
+    },
+    async install(input) {
+        const file = plistPath(input.receipt.unitName);
+        await mkdir(launchAgentsDir(), { recursive: true });
+        // Fail-closed if an unmanaged unit with same label exists.
+        try {
+            const existing = await readFile(file, "utf-8");
+            if (!existing.includes(MANAGED_MARKER) &&
+                !existing.includes("tea-agent.loop-agent.night")) {
+                throw new Error(`Refusing to overwrite unmanaged LaunchAgent at ${file}`);
+            }
+            // bootout before rewrite when loaded
+            await runLaunchctl([
+                "bootout",
+                `gui/${process.getuid?.() ?? 501}/${input.receipt.unitName}`,
+            ]);
+        }
+        catch (error) {
+            if (!(error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT")) {
+                // ignore bootout failures for unloaded units; rethrow ownership errors
+                if (error instanceof Error &&
+                    error.message.includes("Refusing to overwrite")) {
+                    throw error;
+                }
+            }
+        }
+        const body = renderLaunchdPlist({
+            unitName: input.receipt.unitName,
+            intervalSec: input.receipt.intervalSec,
+            nodeBin: input.entrypoints.nodeBin,
+            agentWorkerEntry: input.entrypoints.agentWorkerEntry,
+            controlRepoRoot: input.entrypoints.controlRepoRoot,
+            loopAgentBin: input.entrypoints.loopAgentBin,
+            managedConfigHash: input.receipt.managedConfigHash,
+        });
+        await writeFile(file, body, "utf-8");
+        const uid = process.getuid?.() ?? 501;
+        const bootstrap = await runLaunchctl(["bootstrap", `gui/${uid}`, file]);
+        if (bootstrap.code !== 0) {
+            // try enable + kickstart as softer recovery
+            const enable = await runLaunchctl([
+                "enable",
+                `gui/${uid}/${input.receipt.unitName}`,
+            ]);
+            const kick = await runLaunchctl([
+                "kickstart",
+                "-k",
+                `gui/${uid}/${input.receipt.unitName}`,
+            ]);
+            if (enable.code !== 0 && kick.code !== 0 && bootstrap.code !== 0) {
+                throw new Error(`launchctl bootstrap failed: ${bootstrap.stderr || bootstrap.stdout || `exit ${bootstrap.code}`}`);
+            }
+        }
+    },
+    async uninstall(input) {
+        const file = plistPath(input.receipt.unitName);
+        try {
+            const existing = await readFile(file, "utf-8");
+            if (!existing.includes(MANAGED_MARKER) &&
+                !existing.includes(input.receipt.managedConfigHash)) {
+                throw new Error(`Refusing to uninstall non-managed LaunchAgent at ${file}`);
+            }
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+        const uid = process.getuid?.() ?? 501;
+        await runLaunchctl(["bootout", `gui/${uid}/${input.receipt.unitName}`]);
+        await unlink(file).catch(() => { });
+    },
+    async probe(input) {
+        const unitName = input.receipt?.unitName ?? input.unitName ?? deriveClockUnitName(".");
+        const file = plistPath(unitName);
+        let present = false;
+        let body = "";
+        try {
+            body = await readFile(file, "utf-8");
+            present = true;
+        }
+        catch {
+            present = false;
+        }
+        const uid = process.getuid?.() ?? 501;
+        const print = await runLaunchctl(["print", `gui/${uid}/${unitName}`]);
+        const loaded = print.code === 0;
+        let configMatches = null;
+        if (present && input.receipt) {
+            configMatches =
+                body.includes(MANAGED_MARKER) &&
+                    (body.includes(input.receipt.managedConfigHash) ||
+                        body.includes(input.receipt.controlRepoRoot));
+        }
+        return {
+            present,
+            loaded,
+            configMatches,
+            detail: loaded
+                ? "launchctl print ok"
+                : print.stderr.trim() || print.stdout.trim() || "not loaded",
+        };
+    },
+};
+export function expectedLaunchdHash(receipt) {
+    return hashManagedConfig({
+        provider: "launchd",
+        unitName: receipt.unitName,
+        controlRepoRoot: receipt.controlRepoRoot,
+        intervalSec: receipt.intervalSec,
+        nodeBin: receipt.nodeBin,
+        agentWorkerEntry: receipt.agentWorkerEntry,
+        loopAgentBin: receipt.loopAgentBin,
+    });
+}