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

package/dist/cli/update/init-surface-notifier.js

@@ -0,0 +1,167 @@
+import { applyInitUpdate, checkInitUpdate, readRecordedSurfaceControllerVersion, } from "../../commands/init.js";
+import path from "node:path";
+import { isInitRuntimeActive, } from "../../shared/runtime-activity.js";
+import { shouldRunInitSurfaceCheck } from "./policy.js";
+import { readInitRuntimeActivity } from "./runtime-activity.js";
+/**
+ * Post-upgrade init surface notifier.
+ *
+ * Runs only after a normal successful CLI invocation when:
+ *  - the invocation is not a controller-sensitive / machine-output / `init`
+ *    command (see {@link shouldRunInitSurfaceCheck}), and
+ *  - the target repo records a valid `.harness/init-surface.json` whose
+ *    `controllerVersion` differs from the currently running controller.
+ *
+ * It never writes to stdout and never changes the host command's exit code.
+ * In non-TTY contexts it only emits a stderr pointer to
+ * `loop-agent init reconcile --repo-root ...` and writes nothing to the target.
+ * In TTY contexts with deterministic actions, no pending human decisions, and
+ * no active DAG/Worker runtime, it may ask for an explicit `y/yes` before
+ * applying safe actions. Human decisions and active runtimes block all writes.
+ */
+export async function runInitSurfaceNotifier(options) {
+    if (!shouldRunInitSurfaceCheck(options))
+        return;
+    // Purity contract: the notifier must never pollute machine stdout.
+    void options.writeStdout;
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    try {
+        const recorded = await readRecordedSurfaceControllerVersion(options.repoRoot);
+        if (!recorded)
+            return; // missing / corrupt / uninitialized -> skip silently
+        if (recorded.controllerVersion === options.currentVersion)
+            return; // already aligned
+        const report = await checkInitUpdate({
+            repoRoot: options.repoRoot,
+            projectName: options.projectName,
+            governanceRoot: options.governanceRoot,
+        });
+        const readRuntime = options.readRuntimeActivity ?? readInitRuntimeActivity;
+        // Already aligned to a clean surface; silently refresh recorded state only
+        // when no DAG or Worker runtime can observe the state write.
+        if (report.ok) {
+            const activity = await readRuntime(options.repoRoot);
+            if (isInitRuntimeActive(activity)) {
+                writeStderr(buildActiveRuntimeNotice(options.repoRoot, activity));
+                return;
+            }
+            await applyInitUpdate({
+                repoRoot: options.repoRoot,
+                projectName: options.projectName,
+                governanceRoot: options.governanceRoot,
+                applySafe: true,
+            }).catch(() => undefined);
+            return;
+        }
+        const hasHumanDecisions = report.humanDecisions.length > 0;
+        if (hasHumanDecisions) {
+            writeStderr(buildHumanDecisionNotice(options.repoRoot, report.humanDecisions.length));
+            return;
+        }
+        if (report.deterministicActions.length === 0) {
+            writeStderr(buildRemainingNotice(report, options.repoRoot));
+            return;
+        }
+        if (!options.stdoutIsTTY || !options.stdinIsTTY || !options.stderrIsTTY) {
+            writeStderr(buildReconcileNotice(options.repoRoot));
+            return;
+        }
+        const activity = await readRuntime(options.repoRoot);
+        if (isInitRuntimeActive(activity)) {
+            writeStderr(buildActiveRuntimeNotice(options.repoRoot, activity));
+            return;
+        }
+        const prompt = `loop-agent 控制器版本已变化（${recorded.controllerVersion} → ${options.currentVersion}），` +
+            `目标项目 init surface 有 ${report.deterministicActions.length} 个待处理安全动作。\n` +
+            `现在应用 deterministic safe actions？[y/N] `;
+        const answer = await ask(options, prompt);
+        if (!isYes(answer)) {
+            writeStderr(buildReconcileNotice(options.repoRoot));
+            return;
+        }
+        const update = await applyInitUpdate({
+            repoRoot: options.repoRoot,
+            projectName: options.projectName,
+            governanceRoot: options.governanceRoot,
+            applySafe: true,
+        });
+        writeStderr(`loop-agent init surface safe actions applied to ${options.repoRoot}.\n` +
+            buildRemainingNotice(update.report, options.repoRoot));
+    }
+    catch (error) {
+        writeStderr(`loop-agent init surface check skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function buildReconcileNotice(repoRoot) {
+    return (`loop-agent init surface needs reconciliation at ${repoRoot}.\n` +
+        `Run: loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+function buildHumanDecisionNotice(repoRoot, count) {
+    return (`loop-agent init surface has ${count} pending human decision(s) at ${repoRoot}.\n` +
+        `Run: loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+function buildRemainingNotice(report, repoRoot) {
+    const lines = [];
+    if (report.modelMergeTasks.length > 0) {
+        lines.push(`Remaining model merge tasks: ${report.modelMergeTasks.length}. Run: loop-agent init check-update --repo-root ${repoRoot} --markdown`);
+    }
+    if (report.deterministicActions.length > 0) {
+        lines.push(`Remaining deterministic actions: ${report.deterministicActions.length}. Run: loop-agent init reconcile --repo-root ${repoRoot}`);
+    }
+    if (lines.length === 0)
+        lines.push("init surface is now clean.");
+    return lines.join("\n") + "\n";
+}
+function buildActiveRuntimeNotice(repoRoot, activity) {
+    const details = [
+        activity.activeDagRunIds.length > 0
+            ? `active DAG runs: ${activity.activeDagRunIds.join(", ")}`
+            : undefined,
+        activity.activeWorkerTasks > 0
+            ? `active Worker tasks: ${activity.activeWorkerTasks}`
+            : undefined,
+        activity.activeWorkerBatches > 0
+            ? `active Worker batches: ${activity.activeWorkerBatches}`
+            : undefined,
+        activity.workerProjectionError
+            ? `Worker activity unavailable: ${activity.workerProjectionError}`
+            : undefined,
+    ].filter((value) => Boolean(value));
+    return (`loop-agent init reconcile blocked-active-runtime at ${repoRoot}.\n` +
+        `${details.join("; ")}\n` +
+        "Wait for the active runtime to finish, then run: " +
+        `loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+export function resolveInitSurfaceRepoRoot(argv, defaultRepoRoot) {
+    let selected = defaultRepoRoot;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo-root") {
+            const value = argv[index + 1];
+            if (value && !value.startsWith("-"))
+                selected = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--repo-root=")) {
+            selected = arg.slice("--repo-root=".length) || selected;
+        }
+    }
+    return path.resolve(defaultRepoRoot, selected);
+}
+async function ask(options, prompt) {
+    if (options.readLine) {
+        options.writeStderr?.(prompt);
+        return options.readLine(prompt);
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(prompt);
+    }
+    finally {
+        rl.close();
+    }
+}
+function isYes(answer) {
+    return /^(y|yes)$/i.test(answer.trim());
+}

package/dist/cli/update/notifier.js

@@ -0,0 +1,117 @@
+import { createInterface } from "node:readline/promises";
+import { evaluateLatestVersion, shouldCheckForUpdates } from "./policy.js";
+import { acquireUpdateLock, readUpdateState, updateLockPath, updateStatePath, writeUpdateState, } from "./state.js";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_COOLDOWN_MS = 10 * 60 * 1000;
+export async function runSelfUpdateNotifier(options) {
+    if (!shouldCheckForUpdates(options))
+        return;
+    const now = options.now ?? (() => new Date());
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    void options.writeStdout;
+    try {
+        const statePath = updateStatePath(options.homeDir);
+        let state = await readUpdateState(statePath);
+        if (state.retryAfter && Date.parse(state.retryAfter) > now().getTime())
+            return;
+        let latestVersion = cachedLatest(state, now());
+        if (!latestVersion) {
+            latestVersion = await options.client.latestVersion();
+            state = {
+                ...state,
+                lastCheckedAt: now().toISOString(),
+                latestVersion,
+            };
+            await safeWriteState(statePath, state);
+        }
+        const decision = evaluateLatestVersion({
+            currentVersion: options.currentVersion,
+            latestVersion,
+            dismissedVersion: state.dismissedVersion,
+            now: now(),
+            retryAfter: state.retryAfter,
+        });
+        if (!decision.shouldPrompt)
+            return;
+        const release = await acquireUpdateLock(updateLockPath(options.homeDir), { now });
+        if (!release)
+            return;
+        try {
+            state = await readUpdateState(statePath);
+            if (state.dismissedVersion === decision.targetVersion)
+                return;
+            const answer = await ask(options, `loop-agent 有新版本：${options.currentVersion} → ${decision.targetVersion}\n现在更新到 ${decision.targetVersion}？[y/N] `);
+            if (!isYes(answer)) {
+                await safeWriteState(statePath, {
+                    ...state,
+                    latestVersion: decision.targetVersion,
+                    dismissedVersion: decision.targetVersion,
+                });
+                return;
+            }
+            const proof = await options.client.canAutoInstall();
+            if (!proof.ok) {
+                writeStderr(`当前 loop-agent 不是由此 npm 的正式全局安装管理，无法自动升级。\n请运行：npm install -g @tea-agent/loop-agent@${decision.targetVersion}\n`);
+                await safeWriteState(statePath, cooldownState(state, now()));
+                return;
+            }
+            const install = await options.client.installExact(decision.targetVersion);
+            if (!install.ok) {
+                writeStderr(`loop-agent 更新失败：${install.reason}\n`);
+                await safeWriteState(statePath, cooldownState(state, now()));
+                return;
+            }
+            const verified = await options.client.verifyInstalled(decision.targetVersion);
+            if (!verified.ok) {
+                writeStderr(`loop-agent 已尝试安装，但验证失败：${verified.reason}\n`);
+                await safeWriteState(statePath, cooldownState(state, now()));
+                return;
+            }
+            writeStderr(`loop-agent 已更新到 ${decision.targetVersion}；新版本将在下一次调用时生效。\n`);
+            await safeWriteState(statePath, {
+                schemaVersion: 1,
+                lastCheckedAt: now().toISOString(),
+                latestVersion: decision.targetVersion,
+            });
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        writeStderr(`loop-agent 更新检查已跳过：${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function cachedLatest(state, now) {
+    if (!state.lastCheckedAt || !state.latestVersion)
+        return undefined;
+    const checkedAt = Date.parse(state.lastCheckedAt);
+    if (!Number.isFinite(checkedAt))
+        return undefined;
+    return now.getTime() - checkedAt <= CHECK_INTERVAL_MS ? state.latestVersion : undefined;
+}
+async function ask(options, prompt) {
+    if (options.readLine) {
+        options.writeStderr?.(prompt);
+        return options.readLine(prompt);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(prompt);
+    }
+    finally {
+        rl.close();
+    }
+}
+function isYes(answer) {
+    return /^(y|yes)$/i.test(answer.trim());
+}
+function cooldownState(state, now) {
+    return {
+        ...state,
+        retryAfter: new Date(now.getTime() + FAILURE_COOLDOWN_MS).toISOString(),
+    };
+}
+async function safeWriteState(path, state) {
+    await writeUpdateState(path, state).catch(() => undefined);
+}

package/dist/cli/update/npm-client.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import semver from "semver";
+const PACKAGE_NAME = "@tea-agent/loop-agent";
+export function createNpmUpdateClient(options) {
+    const npmCommand = options.npmCommand ?? "npm";
+    const loopAgentCommand = options.loopAgentCommand ?? "loop-agent";
+    const runner = options.runner ?? runCommand;
+    const timeoutMs = options.timeoutMs ?? 1500;
+    const env = options.env;
+    return {
+        async latestVersion() {
+            const result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, env });
+            if (result.exitCode !== 0 || result.timedOut)
+                return undefined;
+            return parseNpmViewLatest(result.stdout);
+        },
+        async canAutoInstall() {
+            return proveGlobalNpmInstall({
+                currentVersion: options.currentVersion,
+                packageRoot: options.packageRoot,
+                npmCommand,
+                runner,
+                env,
+                timeoutMs,
+            });
+        },
+        async installExact(version) {
+            if (!isStrictRelease(version))
+                return { ok: false, reason: "invalid-version" };
+            const result = await runner(npmCommand, buildExactInstallArgs(version), { timeoutMs: Math.max(timeoutMs, 120000), env });
+            if (result.exitCode !== 0 || result.timedOut)
+                return { ok: false, reason: "install-failed" };
+            return { ok: true };
+        },
+        async verifyInstalled(version) {
+            const list = await runner(npmCommand, ["list", "-g", PACKAGE_NAME, "--depth=0", "--json"], { timeoutMs, env });
+            if (list.exitCode !== 0 || !verifyNpmListVersion(list.stdout, version)) {
+                return { ok: false, reason: "npm-list-version-mismatch" };
+            }
+            const pathVersion = await runner(loopAgentCommand, ["--version"], { timeoutMs, env });
+            if (pathVersion.exitCode !== 0 || !verifyPathVersion(pathVersion.stdout, version)) {
+                return { ok: false, reason: "path-version-mismatch" };
+            }
+            return { ok: true };
+        },
+    };
+}
+export function parseNpmViewLatest(stdout) {
+    const trimmed = stdout.trim();
+    let value = trimmed;
+    try {
+        value = JSON.parse(trimmed);
+    }
+    catch {
+        // npm may emit a bare value under older versions or mocked tests.
+    }
+    if (typeof value !== "string")
+        return undefined;
+    return isStrictRelease(value) ? value : undefined;
+}
+export function buildExactInstallArgs(version) {
+    if (!isStrictRelease(version))
+        throw new Error(`invalid release version: ${version}`);
+    return ["install", "-g", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit"];
+}
+export function verifyNpmListVersion(stdout, expectedVersion) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed.dependencies?.[PACKAGE_NAME]?.version === expectedVersion;
+    }
+    catch {
+        return false;
+    }
+}
+export function verifyPathVersion(stdout, expectedVersion) {
+    return stdout.trim() === expectedVersion;
+}
+async function proveGlobalNpmInstall(options) {
+    const root = await options.runner(options.npmCommand, ["root", "-g"], {
+        timeoutMs: options.timeoutMs,
+        env: options.env,
+    });
+    if (root.exitCode !== 0 || root.timedOut)
+        return { ok: false, reason: "npm-root-failed" };
+    const globalPackageRoot = path.join(root.stdout.trim(), "@tea-agent", "loop-agent");
+    try {
+        const [expectedReal, currentReal, expectedStat] = await Promise.all([
+            realpath(globalPackageRoot),
+            realpath(options.packageRoot),
+            lstat(globalPackageRoot),
+        ]);
+        if (expectedStat.isSymbolicLink())
+            return { ok: false, reason: "linked-global-package" };
+        if (expectedReal !== currentReal)
+            return { ok: false, reason: "not-global" };
+        const pkg = JSON.parse(await readFile(path.join(options.packageRoot, "package.json"), "utf-8"));
+        if (pkg.name !== PACKAGE_NAME)
+            return { ok: false, reason: "wrong-package" };
+        if (pkg.version !== options.currentVersion)
+            return { ok: false, reason: "version-mismatch" };
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, reason: "source-proof-failed" };
+    }
+}
+function isStrictRelease(version) {
+    const parsed = semver.parse(version);
+    return Boolean(parsed && parsed.prerelease.length === 0);
+}
+async function runCommand(command, args, options) {
+    return new Promise((resolve) => {
+        const child = spawn(command, [...args], {
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            settled = true;
+            child.kill("SIGTERM");
+            resolve({ exitCode: null, stdout, stderr, timedOut: true });
+        }, options.timeoutMs);
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode: null, stdout, stderr: `${stderr}${error.message}`, timedOut: false });
+        });
+        child.on("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode, stdout, stderr, timedOut: false });
+        });
+    });
+}

package/dist/cli/update/policy.js

@@ -0,0 +1,92 @@
+import semver from "semver";
+const CONTROLLER_SENSITIVE_COMMANDS = new Set([
+    "dag",
+    "loop",
+    "delegate",
+    "pi-prompt",
+    "cursor-prompt",
+]);
+const MACHINE_OUTPUT_FLAGS = new Set(["--json", "--markdown"]);
+const GLOBAL_VALUE_FLAGS = new Set(["--repo-root", "--adapter", "--worktree"]);
+export function isStrictReleaseVersion(version) {
+    if (!version)
+        return false;
+    const parsed = semver.parse(version);
+    return Boolean(parsed && parsed.prerelease.length === 0);
+}
+export function shouldCheckForUpdates(input) {
+    if (!input.stdinIsTTY || !input.stdoutIsTTY || !input.stderrIsTTY)
+        return false;
+    if (input.env.CI || input.env.LOOP_AGENT_DISABLE_UPDATE_CHECK === "1")
+        return false;
+    const args = input.argv;
+    if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V")) {
+        return false;
+    }
+    if (args.some((arg) => MACHINE_OUTPUT_FLAGS.has(arg)))
+        return false;
+    const command = firstCommand(args);
+    if (command && CONTROLLER_SENSITIVE_COMMANDS.has(command))
+        return false;
+    return true;
+}
+/**
+ * Eligibility predicate for the post-upgrade init surface notifier.
+ *
+ * Mirrors {@link shouldCheckForUpdates}'s skip conditions (CI, disable env,
+ * help/version, machine-output flags, controller-sensitive commands) and
+ * additionally skips the `init` command family itself so the notifier never
+ * re-enters the explicit init surface write path.
+ *
+ * Unlike {@link shouldCheckForUpdates}, this predicate does NOT require a TTY:
+ * non-interactive invocations are still eligible because the notifier emits a
+ * read-only stderr pointer (zero target writes) in non-TTY contexts. The TTY
+ * distinction is handled inside the notifier.
+ */
+export function shouldRunInitSurfaceCheck(input) {
+    if (input.env.CI || input.env.LOOP_AGENT_DISABLE_UPDATE_CHECK === "1")
+        return false;
+    const args = input.argv;
+    if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V")) {
+        return false;
+    }
+    if (args.some((arg) => MACHINE_OUTPUT_FLAGS.has(arg)))
+        return false;
+    const command = firstCommand(args);
+    if (command === "init")
+        return false;
+    if (command && CONTROLLER_SENSITIVE_COMMANDS.has(command))
+        return false;
+    return true;
+}
+export function evaluateLatestVersion(input) {
+    const now = input.now ?? new Date();
+    if (input.retryAfter && Date.parse(input.retryAfter) > now.getTime()) {
+        return { shouldPrompt: false, reason: "retry-after" };
+    }
+    if (!isStrictReleaseVersion(input.currentVersion)) {
+        return { shouldPrompt: false, reason: "invalid-current-version" };
+    }
+    if (!isStrictReleaseVersion(input.latestVersion)) {
+        return { shouldPrompt: false, reason: "invalid-latest-version" };
+    }
+    if (!semver.gt(input.latestVersion, input.currentVersion)) {
+        return { shouldPrompt: false, reason: "not-newer" };
+    }
+    if (input.dismissedVersion === input.latestVersion) {
+        return { shouldPrompt: false, reason: "dismissed-version" };
+    }
+    return { shouldPrompt: true, targetVersion: input.latestVersion };
+}
+function firstCommand(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (GLOBAL_VALUE_FLAGS.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            return arg;
+    }
+    return undefined;
+}

package/dist/cli/update/runtime-activity.js

@@ -0,0 +1,29 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { buildGlobalSnapshot } from "../../worker/observability/read-model.js";
+/**
+ * Read-only runtime guard for init-surface writes.
+ *
+ * DAG activeness is anchored to real directories in the canonical active
+ * lifecycle root. Worker activeness reuses the Observe read model so Task Pool
+ * status precedence and composite identity stay owned by the Worker adapter.
+ * Projection failures block writes because liveness cannot be proven safely.
+ */
+export async function readInitRuntimeActivity(repoRoot) {
+    const resolvedRoot = path.resolve(repoRoot);
+    const activeDagRoot = path.join(resolvedRoot, ".harness", "dag-runs", "active");
+    const entries = await readdir(activeDagRoot, { withFileTypes: true }).catch(() => []);
+    const activeDagRunIds = entries
+        .filter((entry) => entry.isDirectory() && entry.name !== ".gitkeep")
+        .map((entry) => entry.name)
+        .sort();
+    const snapshot = await buildGlobalSnapshot({ repoRoot: resolvedRoot });
+    return {
+        activeDagRunIds,
+        activeWorkerBatches: snapshot.health.worker.activeBatches,
+        activeWorkerTasks: snapshot.health.worker.activeTasks,
+        ...(snapshot.projectionError
+            ? { workerProjectionError: snapshot.projectionError.message }
+            : {}),
+    };
+}

package/dist/cli/update/state.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function updateStatePath(homeDir) {
+    return path.join(homeDir, ".loop-agent", "update-state.json");
+}
+export function updateLockPath(homeDir) {
+    return path.join(homeDir, ".loop-agent", "update.lock");
+}
+export async function readUpdateState(statePath) {
+    try {
+        const raw = await readFile(statePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1)
+            return emptyState();
+        return {
+            schemaVersion: 1,
+            lastCheckedAt: stringOrUndefined(parsed.lastCheckedAt),
+            latestVersion: stringOrUndefined(parsed.latestVersion),
+            dismissedVersion: stringOrUndefined(parsed.dismissedVersion),
+            retryAfter: stringOrUndefined(parsed.retryAfter),
+        };
+    }
+    catch {
+        return emptyState();
+    }
+}
+export async function writeUpdateState(statePath, state) {
+    await mkdir(path.dirname(statePath), { recursive: true });
+    const tempPath = path.join(path.dirname(statePath), `.${path.basename(statePath)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(tempPath, `${JSON.stringify({ ...state, schemaVersion: 1 }, null, 2)}\n`, "utf-8");
+    await rename(tempPath, statePath);
+}
+export async function acquireUpdateLock(lockPath, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const staleMs = options.staleMs ?? 10 * 60 * 1000;
+    await mkdir(path.dirname(lockPath), { recursive: true });
+    try {
+        await mkdir(lockPath);
+        await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
+        return async () => {
+            await rm(lockPath, { recursive: true, force: true });
+        };
+    }
+    catch {
+        try {
+            const ownerRaw = await readFile(path.join(lockPath, "owner.json"), "utf-8");
+            const owner = JSON.parse(ownerRaw);
+            if (owner.at && now().getTime() - Date.parse(owner.at) > staleMs) {
+                await rm(lockPath, { recursive: true, force: true });
+                await mkdir(lockPath);
+                await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
+                return async () => {
+                    await rm(lockPath, { recursive: true, force: true });
+                };
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return undefined;
+    }
+}
+function emptyState() {
+    return { schemaVersion: 1 };
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/dist/cli-governance/active-residue-check.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { evaluateActiveResidue, formatActiveResidueFinding, shouldFailActiveResidue, } from "../infrastructure/harness/active-residue-policy.js";
+function readEntriesFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    return raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function getRequiredFlag(args, flag) {
+    const index = args.indexOf(flag);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    if (!value) {
+        throw new Error(`missing required flag: ${flag}`);
+    }
+    return value;
+}
+function main(rawArgs, env) {
+    const dagEntriesFile = getRequiredFlag(rawArgs, "--dag-entries-file");
+    const toolEntriesFile = getRequiredFlag(rawArgs, "--tool-entries-file");
+    const findings = evaluateActiveResidue({
+        dagActiveEntries: readEntriesFile(dagEntriesFile),
+        toolActiveEntries: readEntriesFile(toolEntriesFile),
+    });
+    for (const finding of findings) {
+        if (env[finding.allowEnv] === "1")
+            continue;
+        process.stderr.write(formatActiveResidueFinding(finding));
+    }
+    return shouldFailActiveResidue(findings, env).fail ? 1 : 0;
+}
+try {
+    process.exitCode = main(process.argv.slice(2), process.env);
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}