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

package/dist/commands/init-upgrade.js

@@ -0,0 +1,3085 @@
+import { execFile, spawn } from "node:child_process";
+import { lstatSync, watch } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdtemp, mkdir, readFile, readdir, readlink, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAdapter } from "../adapters/index.js";
+import { createNpmUpdateClient } from "../cli/update/npm-client.js";
+import { auditDocs } from "../governance/checks.js";
+import { harnessManifestSchema } from "../governance/manifest-types.js";
+import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
+import { MAX_OVERFLOW_RECOVERIES, MAX_SESSION_RETRIES, OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH, OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH, PI_CONTEXT_OVERFLOW_EXTENSION_PATH, PI_PROJECT_SETTINGS_PATH, inspectProjectPiSettings, } from "./client-recovery.js";
+import { applyInitUpdate, checkInitUpdate, initializeLoopAgentProject, runInitDoctor, } from "./init.js";
+const RUN_ROOT = ".harness/init-upgrades";
+const GLOBAL_LOCK_NAME = ".writer-lock";
+const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
+const RECOVERY_PATHS = [
+    OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
+    OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH,
+    PI_CONTEXT_OVERFLOW_EXTENSION_PATH,
+    PI_PROJECT_SETTINGS_PATH,
+];
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function validRunId(runId) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runId);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isSha256(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function isHomeFingerprint(value) {
+    if (!isRecord(value))
+        return false;
+    const keys = Object.keys(value).sort();
+    if (value.present === false) {
+        return keys.length === 1 && keys[0] === "present";
+    }
+    return (value.present === true &&
+        keys.length === 2 &&
+        keys[0] === "present" &&
+        keys[1] === "sha256" &&
+        isSha256(value.sha256));
+}
+/**
+ * Shape guard for the controller-owned gitignore migration assessment.
+ * `assessGitignoreMigration` is the single schema fact source; status/report
+ * reads fail closed on any shape that the writer could not have produced
+ * (AC-005). `queryError` may be absent and arrays may be empty; extra keys are
+ * tolerated for forward compatibility.
+ */
+function isGitignoreMigrationAssessment(value) {
+    if (!isRecord(value))
+        return false;
+    const assessment = value;
+    if (assessment.schemaVersion !== 1)
+        return false;
+    if (typeof assessment.managedBlockRefreshed !== "boolean")
+        return false;
+    if (typeof assessment.needsAgentsReview !== "boolean")
+        return false;
+    if (!isRecord(assessment.git))
+        return false;
+    const git = assessment.git;
+    if (typeof git.isRepo !== "boolean")
+        return false;
+    if (git.queryError !== undefined && typeof git.queryError !== "string") {
+        return false;
+    }
+    if (!Array.isArray(assessment.harnessTracked) ||
+        !assessment.harnessTracked.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.agentsTracked) ||
+        !assessment.agentsTracked.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.stagedRisk) ||
+        !assessment.stagedRisk.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.followUp) ||
+        !assessment.followUp.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.recommendedCommands))
+        return false;
+    for (const entry of assessment.recommendedCommands) {
+        if (!isRecord(entry))
+            return false;
+        if (typeof entry.command !== "string" || typeof entry.note !== "string") {
+            return false;
+        }
+    }
+    return (assessment.status === "clean" ||
+        assessment.status === "recommended" ||
+        assessment.status === "blocked");
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function serializeJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** Stable hash for controller authority records, independent of JSON key order. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+function canonicalSha256(value) {
+    return sha256(canonicalJson(value));
+}
+function controllerStateProjection(state) {
+    return {
+        phase: state.phase,
+        status: state.status,
+        mergeTasks: cloneJson(state.mergeTasks),
+        ...(state.mergeGuard ? { mergeGuard: cloneJson(state.mergeGuard) } : {}),
+        mergeReceipts: cloneJson(state.mergeReceipts),
+        humanDecisions: cloneJson(state.humanDecisions),
+        actionReceipts: cloneJson(state.actionReceipts),
+    };
+}
+function sameJsonValue(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((entry, index) => sameJsonValue(entry, right[index])));
+    }
+    if (!isRecord(left) || !isRecord(right))
+        return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return (leftKeys.length === rightKeys.length &&
+        leftKeys.every((key, index) => key === rightKeys[index] && sameJsonValue(left[key], right[key])));
+}
+function isControllerIdentity(value) {
+    if (!isRecord(value))
+        return false;
+    const identity = value;
+    return (identity.packageName === "@tea-agent/loop-agent" &&
+        typeof identity.version === "string" &&
+        identity.version.length > 0 &&
+        typeof identity.packageRoot === "string" &&
+        path.isAbsolute(identity.packageRoot) &&
+        typeof identity.cliEntry === "string" &&
+        path.isAbsolute(identity.cliEntry) &&
+        isSha256(identity.cliEntrySha256) &&
+        identity.portableIdentity ===
+            `@tea-agent/loop-agent@${identity.version}:${identity.cliEntrySha256}`);
+}
+function sameControllerIdentity(left, right) {
+    return (left.packageName === right.packageName &&
+        left.version === right.version &&
+        left.packageRoot === right.packageRoot &&
+        left.cliEntry === right.cliEntry &&
+        left.cliEntrySha256 === right.cliEntrySha256 &&
+        left.portableIdentity === right.portableIdentity);
+}
+function assertStateShape(state, repoRoot, runId) {
+    if (!isRecord(state))
+        throw new Error("invalid init upgrade state");
+    const candidate = state;
+    const phases = [
+        "DISCOVER",
+        "VERSION_GATE",
+        "PLAN",
+        "APPLY_SAFE",
+        "MODEL_MERGE",
+        "VERIFY",
+        "COMPLETED",
+    ];
+    const statuses = [
+        "in-progress",
+        "completed",
+        "needs-human-decision",
+        "failed",
+        "cancelled",
+    ];
+    if (candidate.schemaVersion !== 1 ||
+        candidate.runId !== runId ||
+        candidate.repoRoot !== repoRoot ||
+        !phases.includes(candidate.phase) ||
+        !statuses.includes(candidate.status) ||
+        typeof candidate.createdAt !== "string" ||
+        typeof candidate.updatedAt !== "string" ||
+        typeof candidate.nextAction !== "string" ||
+        !isControllerIdentity(candidate.controllerIdentity) ||
+        !isRecord(candidate.versionGate) ||
+        !Array.isArray(candidate.mergeTasks) ||
+        !Array.isArray(candidate.mergeReceipts) ||
+        !Array.isArray(candidate.humanDecisions) ||
+        !Array.isArray(candidate.actionReceipts) ||
+        !isHomeFingerprint(candidate.homeFingerprint)) {
+        throw new Error("invalid init upgrade state or repoRoot authority");
+    }
+}
+function assertTerminalCoherence(state) {
+    if (state.status === "completed" && state.phase !== "COMPLETED") {
+        throw new Error("invalid init upgrade terminal status/phase coherence");
+    }
+    if (state.status === "cancelled" && state.phase !== "VERSION_GATE") {
+        throw new Error("invalid init upgrade terminal status/phase coherence");
+    }
+    if (state.phase === "COMPLETED" && state.status !== "completed") {
+        throw new Error("invalid init upgrade status/phase coherence");
+    }
+    if (state.status === "needs-human-decision" &&
+        state.phase !== "VERSION_GATE" &&
+        state.phase !== "MODEL_MERGE") {
+        throw new Error("invalid init upgrade status/phase coherence");
+    }
+}
+/** Read-only git query; never mutates the user index (no status refresh, no write). */
+function runGitQuery(cwd, args) {
+    return new Promise((resolve) => {
+        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", (error) => {
+            resolve({ ok: false, stdout: "", stderr: error.message });
+        });
+        child.on("close", (code) => {
+            resolve({
+                ok: code === 0,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            });
+        });
+    });
+}
+function splitNulPaths(output) {
+    return output.split("\0").filter((entry) => entry.length > 0);
+}
+/**
+ * Gitignore migration assessment (PRD 2026-08-13): inventories tracked
+ * `.harness/**` / `.agents/**` with read-only git queries after the managed
+ * block has converged, and recommends index-only untrack commands. The
+ * controller never mutates the user Git index and never deletes local files.
+ */
+export async function assessGitignoreMigration(repoRoot, input) {
+    const base = {
+        schemaVersion: 1,
+        managedBlockRefreshed: input.managedBlockRefreshed,
+        harnessTracked: [],
+        agentsTracked: [],
+        stagedRisk: [],
+        needsAgentsReview: false,
+        followUp: [
+            "run `git status --short` and confirm only the intended untrack changes",
+            "confirm the .harness/ and .agents/ directories still exist locally after untracking",
+            "run `loop-agent init doctor` to re-check the gitignore loop-agent block",
+        ],
+    };
+    const inside = await runGitQuery(repoRoot, ["rev-parse", "--is-inside-work-tree"]);
+    if (!inside.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: false,
+                queryError: inside.stderr.trim() || "not inside a Git work tree",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const tracked = await runGitQuery(repoRoot, [
+        "ls-files",
+        "-z",
+        "--cached",
+        "--",
+        ".harness",
+        ".agents",
+    ]);
+    if (!tracked.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: true,
+                queryError: tracked.stderr.trim() || "git ls-files query failed",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const staged = await runGitQuery(repoRoot, [
+        "diff",
+        "--cached",
+        "--name-only",
+        "-z",
+    ]);
+    if (!staged.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: true,
+                queryError: staged.stderr.trim() || "git diff --cached query failed",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const trackedPaths = splitNulPaths(tracked.stdout);
+    const harnessTracked = trackedPaths.filter((entry) => entry.startsWith(".harness/"));
+    const agentsTracked = trackedPaths.filter((entry) => entry.startsWith(".agents/"));
+    const stagedRisk = splitNulPaths(staged.stdout);
+    const needsAgentsReview = agentsTracked.length > 0;
+    if (stagedRisk.length > 0) {
+        // Fail closed: staged entries make any untrack advice ambiguous.
+        return {
+            ...base,
+            git: { isRepo: true },
+            harnessTracked,
+            agentsTracked,
+            stagedRisk,
+            needsAgentsReview,
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const recommendedCommands = [];
+    if (harnessTracked.length > 0) {
+        recommendedCommands.push({
+            command: "git rm -r --cached --ignore-unmatch .harness",
+            note: "untracks tracked .harness runtime facts; index-only, working-tree files are kept",
+        });
+    }
+    if (agentsTracked.length > 0) {
+        recommendedCommands.push({
+            command: "git rm -r --cached --ignore-unmatch .agents",
+            note: "untracks tracked .agents local skills; index-only, working-tree files are kept; review team-shareable customizations first",
+        });
+    }
+    return {
+        ...base,
+        git: { isRepo: true },
+        harnessTracked,
+        agentsTracked,
+        stagedRisk,
+        needsAgentsReview,
+        recommendedCommands,
+        status: harnessTracked.length > 0 || agentsTracked.length > 0
+            ? "recommended"
+            : "clean",
+    };
+}
+function runRoot(repoRoot) {
+    return path.join(repoRoot, RUN_ROOT);
+}
+function runDirectory(repoRoot, runId) {
+    if (!validRunId(runId))
+        throw new Error("invalid init upgrade run id");
+    return path.join(runRoot(repoRoot), runId);
+}
+async function exists(filePath) {
+    return Boolean(await stat(filePath).catch(() => undefined));
+}
+async function writeJsonAtomic(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+        await rename(temp, filePath);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function controllerAnchorPath(input) {
+    const repoRoot = await realpath(input.repoRoot).catch(() => {
+        throw new Error("init upgrade controller authority requires a readable Git repository");
+    });
+    const marker = path.join(repoRoot, ".git");
+    const markerStat = await lstat(marker).catch(() => undefined);
+    let gitDirectory;
+    if (markerStat?.isDirectory()) {
+        gitDirectory = await realpath(marker);
+    }
+    else if (markerStat?.isFile()) {
+        const text = await readFile(marker, "utf-8").catch(() => "");
+        const match = /^gitdir:\s*(.+?)\s*\r?\n?$/.exec(text);
+        if (!match || !match[1]) {
+            throw new Error("init upgrade controller authority rejected an invalid Git worktree file");
+        }
+        gitDirectory = await realpath(path.resolve(path.dirname(marker), match[1]));
+    }
+    else {
+        throw new Error("init upgrade controller authority requires a Git repository");
+    }
+    const gitStat = await stat(gitDirectory).catch(() => undefined);
+    if (!gitStat?.isDirectory() || !(await stat(path.join(gitDirectory, "HEAD")).catch(() => undefined))?.isFile()) {
+        throw new Error("init upgrade controller authority Git directory is unusable");
+    }
+    let anchorRoot = path.join(gitDirectory, "loop-agent-init-upgrades");
+    if (await lstat(anchorRoot).catch(() => undefined)) {
+        anchorRoot = await realpath(anchorRoot);
+        if (!isWithin(gitDirectory, anchorRoot)) {
+            throw new Error("init upgrade controller authority anchor path escapes Git directory");
+        }
+    }
+    const file = path.join(anchorRoot, `${sha256(`${repoRoot}\0${input.runId}`)}.json`);
+    if (!isWithin(anchorRoot, file)) {
+        throw new Error("init upgrade controller authority anchor path escapes Git directory");
+    }
+    return { repoRoot, gitDirectory, anchorRoot, file };
+}
+async function writeControllerAnchor(input) {
+    let location = await controllerAnchorPath(input.state);
+    await mkdir(location.anchorRoot, { recursive: true });
+    location = await controllerAnchorPath(input.state);
+    if (!isWithin(location.gitDirectory, location.anchorRoot)) {
+        throw new Error("init upgrade controller authority anchor path escapes Git directory");
+    }
+    let authoritativeHomeFingerprint;
+    let authoritativeGitignoreMigrationSha256;
+    if (input.initialize) {
+        if (await exists(location.file)) {
+            throw new Error("init upgrade controller authority anchor already exists");
+        }
+        if (!isHomeFingerprint(input.state.homeFingerprint)) {
+            throw new Error("init upgrade controller home fingerprint is invalid");
+        }
+        authoritativeHomeFingerprint = cloneJson(input.state.homeFingerprint);
+    }
+    else {
+        const current = await readControllerAnchor(location.repoRoot, input.state);
+        authoritativeHomeFingerprint = current.homeFingerprint;
+        // Preserve the gitignore migration artifact binding across later
+        // mergeAuthority/completion writes; fail closed on a corrupt or
+        // non-SHA-256 binding instead of silently dropping or propagating it.
+        const digest = input.gitignoreMigrationSha256 ?? current.gitignoreMigrationSha256;
+        if (digest !== undefined && !isSha256(digest)) {
+            throw new Error("init upgrade controller authority gitignore migration digest binding is invalid");
+        }
+        authoritativeGitignoreMigrationSha256 = digest;
+    }
+    await writeJsonAtomic(location.file, {
+        schemaVersion: 1,
+        repoRoot: location.repoRoot,
+        runId: input.state.runId,
+        controllerIdentity: input.state.controllerIdentity,
+        homeFingerprint: authoritativeHomeFingerprint,
+        ...(authoritativeGitignoreMigrationSha256 !== undefined
+            ? { gitignoreMigrationSha256: authoritativeGitignoreMigrationSha256 }
+            : {}),
+        ...(input.mergeAuthority ? { mergeAuthority: input.mergeAuthority } : {}),
+        ...(input.completion ? { completion: input.completion } : {}),
+    });
+}
+async function readControllerAnchor(repoRoot, state) {
+    const location = await controllerAnchorPath({ repoRoot, runId: state.runId });
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(location.file, "utf-8"));
+    }
+    catch {
+        throw new Error("init upgrade controller authority anchor is missing or invalid");
+    }
+    if (!isRecord(parsed) ||
+        parsed.schemaVersion !== 1 ||
+        parsed.repoRoot !== location.repoRoot ||
+        parsed.runId !== state.runId ||
+        !isControllerIdentity(parsed.controllerIdentity) ||
+        !sameControllerIdentity(parsed.controllerIdentity, state.controllerIdentity)) {
+        throw new Error("init upgrade controller authority anchor binding is invalid");
+    }
+    if (!isHomeFingerprint(parsed.homeFingerprint) ||
+        !sameJsonValue(parsed.homeFingerprint, state.homeFingerprint)) {
+        throw new Error("init upgrade controller authority home fingerprint binding is invalid");
+    }
+    return parsed;
+}
+function mergeAuthorityFromAnchor(anchor, state) {
+    const authority = anchor.mergeAuthority;
+    if (!authority ||
+        !isRecord(authority.baselineWorkspace) ||
+        !Number.isInteger(authority.priorMergeReceiptCount) ||
+        authority.priorMergeReceiptCount < 0 ||
+        !isSha256(authority.priorMergeReceiptsSha256) ||
+        !isRecord(authority.stateProjection) ||
+        !isSha256(authority.stateProjectionSha256) ||
+        canonicalSha256(authority.stateProjection) !== authority.stateProjectionSha256 ||
+        !isFrozenVerificationSurface(authority.verificationSurface)) {
+        throw new Error("init upgrade controller merge baseline authority is missing or inconsistent");
+    }
+    validateTaskBoundary(authority.task);
+    if (authority.pending) {
+        assertPendingAcceptance(authority.pending, state, authority.task);
+        if (authority.pending.transition.priorMergeReceiptCount !==
+            authority.priorMergeReceiptCount) {
+            throw new Error("pending merge acceptance receipt count differs from controller authority");
+        }
+    }
+    return authority;
+}
+function expectedPostAcceptanceProjection(authority) {
+    if (!authority.pending) {
+        throw new Error("post-acceptance merge state projection lacks controller merge authority for pending acceptance");
+    }
+    const projection = cloneJson(authority.stateProjection);
+    projection.phase = "PLAN";
+    projection.status = "in-progress";
+    projection.mergeTasks = [];
+    delete projection.mergeGuard;
+    projection.mergeReceipts.push(cloneJson(authority.pending.receipt));
+    return projection;
+}
+function mergeAuthorityProjection(state, authority) {
+    const preAcceptance = state.phase === "MODEL_MERGE";
+    if (preAcceptance) {
+        if (state.mergeTasks.length !== 1) {
+            throw new Error("init upgrade merge state must contain exactly one canonical current merge task");
+        }
+        if (!sameJsonValue(state.mergeTasks[0], authority.task)) {
+            throw new Error("init upgrade merge state is inconsistent with the canonical current merge task");
+        }
+        if (!state.mergeGuard) {
+            throw new Error("init upgrade merge guard is missing; refusing to continue an unbounded model merge");
+        }
+        if (!sameJsonValue(state.mergeGuard.task, authority.task)) {
+            throw new Error("init upgrade merge guard is inconsistent with the canonical current merge task");
+        }
+        if (!sameJsonValue(state.mergeGuard.baselineWorkspace, authority.baselineWorkspace)) {
+            throw new Error("init upgrade merge guard projection differs from controller baseline authority");
+        }
+        if (!sameJsonValue(state.mergeGuard.verificationAuthority, authority.verificationAuthority)) {
+            throw new Error("init upgrade merge guard verification authority differs from controller baseline authority");
+        }
+        if (state.mergeReceipts.length !== authority.priorMergeReceiptCount) {
+            throw new Error("persisted pre-acceptance merge receipt count differs from controller authority");
+        }
+    }
+    const priorReceipts = state.mergeReceipts.slice(0, authority.priorMergeReceiptCount);
+    if (priorReceipts.length !== authority.priorMergeReceiptCount ||
+        sha256(serializeJson(priorReceipts)) !== authority.priorMergeReceiptsSha256) {
+        throw new Error("persisted merge receipt prefix differs from controller authority");
+    }
+    const currentProjection = controllerStateProjection(state);
+    const expectedProjection = preAcceptance
+        ? authority.stateProjection
+        : expectedPostAcceptanceProjection(authority);
+    if (canonicalSha256(currentProjection) !== canonicalSha256(expectedProjection) ||
+        !sameJsonValue(currentProjection, expectedProjection)) {
+        throw new Error("persisted merge state projection differs from controller merge authority");
+    }
+    if (preAcceptance)
+        return "pre-acceptance";
+    const postAcceptance = Boolean(authority.pending) &&
+        state.phase === "PLAN" &&
+        state.mergeTasks.length === 0 &&
+        state.mergeGuard === undefined &&
+        state.mergeReceipts.length === authority.priorMergeReceiptCount + 1 &&
+        sameJsonValue(state.mergeReceipts[authority.priorMergeReceiptCount], authority.pending?.receipt);
+    if (postAcceptance)
+        return "post-acceptance";
+    throw new Error("persisted merge state projection differs from controller merge authority");
+}
+async function packageRoot() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (await exists(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new Error("unable to resolve loop-agent package root");
+        current = parent;
+    }
+}
+async function readIdentity() {
+    const root = await packageRoot();
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf-8"));
+    if (typeof pkg.version !== "string")
+        throw new Error("loop-agent package version is missing");
+    const cliEntry = path.resolve(process.argv[1] ?? path.join(root, "src", "cli.ts"));
+    const cliBytes = await readFile(cliEntry).catch(() => Buffer.from("unreadable-cli-entry"));
+    const cliEntrySha256 = sha256(cliBytes);
+    return {
+        packageName: "@tea-agent/loop-agent",
+        version: pkg.version,
+        packageRoot: root,
+        cliEntry,
+        cliEntrySha256,
+        portableIdentity: `@tea-agent/loop-agent@${pkg.version}:${cliEntrySha256}`,
+    };
+}
+async function homeFingerprint() {
+    const homeSettings = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    try {
+        return { present: true, sha256: sha256(await readFile(homeSettings)) };
+    }
+    catch {
+        return { present: false };
+    }
+}
+function versionsNewer(candidate, current) {
+    const parse = (value) => value.match(/^(\d+)\.(\d+)\.(\d+)$/)?.slice(1).map(Number);
+    const left = parse(candidate);
+    const right = parse(current);
+    if (!left || !right)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] === right[index])
+            continue;
+        return left[index] > right[index];
+    }
+    return false;
+}
+async function readState(repoRoot, runId) {
+    const file = path.join(runDirectory(repoRoot, runId), "state.json");
+    const parsed = JSON.parse(await readFile(file, "utf-8"));
+    assertStateShape(parsed, repoRoot, runId);
+    return parsed;
+}
+async function frozenControllerMatches(directory, state) {
+    const parsed = JSON.parse(await readFile(path.join(directory, "controller-identity.json"), "utf-8"));
+    if (!isRecord(parsed) ||
+        parsed.schemaVersion !== 1 ||
+        parsed.runId !== state.runId ||
+        parsed.repoRoot !== state.repoRoot ||
+        !isControllerIdentity(parsed.controllerIdentity)) {
+        throw new Error("invalid frozen init upgrade controller identity");
+    }
+    const frozen = {
+        schemaVersion: 1,
+        runId: parsed.runId,
+        repoRoot: parsed.repoRoot,
+        controllerIdentity: parsed.controllerIdentity,
+    };
+    if (!sameControllerIdentity(frozen.controllerIdentity, state.controllerIdentity)) {
+        throw new Error("persisted init upgrade controller identity is inconsistent");
+    }
+    return sameControllerIdentity(await readIdentity(), frozen.controllerIdentity);
+}
+async function saveState(directory, state) {
+    state.updatedAt = new Date().toISOString();
+    await writeJsonAtomic(path.join(directory, "state.json"), state);
+}
+function toResult(state, verification, gitignoreMigration) {
+    return {
+        runId: state.runId,
+        status: state.status,
+        phase: state.phase,
+        controllerIdentity: state.controllerIdentity,
+        deterministicActions: state.actionReceipts,
+        modelMergeTasks: state.mergeTasks,
+        humanDecisions: state.humanDecisions,
+        nextAction: state.nextAction,
+        ...(verification ? { verification } : {}),
+        ...(gitignoreMigration ? { gitignoreMigration } : {}),
+    };
+}
+function renderReport(state, verification, gitignoreMigration) {
+    const lines = [
+        "# loop-agent init upgrade report",
+        "",
+        `- runId: \`${state.runId}\``,
+        `- status: \`${state.status}\``,
+        `- phase: \`${state.phase}\``,
+        `- controller: \`${state.controllerIdentity.portableIdentity}\``,
+        `- version gate: \`${state.versionGate.outcome}\``,
+        `- version choice: \`${state.versionGate.choice ?? "pending"}\``,
+        `- deterministic actions applied: ${state.actionReceipts.length}`,
+        `- semantic merges accepted: ${state.mergeReceipts.length}`,
+        `- preserved user modifications: ${state.mergeReceipts.length}`,
+        `- retired path actions: ${state.actionReceipts.filter((action) => action.type === "migrate-owned-file" || action.type === "remove-owned-file" || action.type === "remove-empty-directory").length}`,
+        `- remaining model merge tasks: ${state.mergeTasks.length}`,
+        `- remaining human decisions: ${state.humanDecisions.length}`,
+        `- gitignore migration assessment: \`.harness/init-upgrades/${state.runId}/gitignore-migration.json\` (index-only untrack guidance; the controller never modifies the Git index)`,
+        ...(gitignoreMigration
+            ? [
+                "",
+                "## Gitignore migration assessment",
+                "",
+                `- status: \`${gitignoreMigration.status}\``,
+                `- managed block refreshed: \`${gitignoreMigration.managedBlockRefreshed}\``,
+                `- tracked \`.harness\` inventory: ${gitignoreMigration.harnessTracked.length > 0
+                    ? gitignoreMigration.harnessTracked
+                        .map((entry) => `\`${entry}\``)
+                        .join(", ")
+                    : "(none)"}`,
+                `- tracked \`.agents\` inventory: ${gitignoreMigration.agentsTracked.length > 0
+                    ? gitignoreMigration.agentsTracked
+                        .map((entry) => `\`${entry}\``)
+                        .join(", ")
+                    : "(none)"}`,
+                ...(gitignoreMigration.stagedRisk.length > 0
+                    ? [
+                        `- staged risk: ${gitignoreMigration.stagedRisk
+                            .map((entry) => `\`${entry}\``)
+                            .join(", ")}`,
+                    ]
+                    : []),
+                ...(gitignoreMigration.git.queryError
+                    ? [
+                        `- git query blocker: \`${gitignoreMigration.git.queryError}\``,
+                    ]
+                    : []),
+                `- \`.agents\` review required: \`${gitignoreMigration.needsAgentsReview}\``,
+                "- recommended commands:",
+                ...(gitignoreMigration.recommendedCommands.length > 0
+                    ? gitignoreMigration.recommendedCommands.map((entry) => `  - \`${entry.command}\` — ${entry.note}`)
+                    : ["  - (none)"]),
+                "- follow-up:",
+                ...(gitignoreMigration.followUp.length > 0
+                    ? gitignoreMigration.followUp.map((entry) => `  - ${entry}`)
+                    : ["  - (none)"]),
+            ]
+            : []),
+        "",
+        "## Next action",
+        "",
+        state.nextAction,
+        "",
+        "## Project Pi trust",
+        "",
+        "Pi must trust the target project before loading `.pi/settings.json` and `.pi/extensions/`. This upgrade never writes `~/.pi/agent/settings.json`.",
+        "",
+        ...(verification
+            ? [
+                "## Verification",
+                "",
+                "```json",
+                JSON.stringify(verification, null, 2),
+                "```",
+            ]
+            : []),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+async function writeReport(directory, state, verification, gitignoreMigration) {
+    await writeFile(path.join(directory, "final-report.md"), renderReport(state, verification, gitignoreMigration), "utf-8");
+}
+async function assertInactive(input) {
+    let activity;
+    try {
+        activity = await input.readRuntimeActivity(path.resolve(input.repoRoot));
+    }
+    catch (error) {
+        throw new Error(`init upgrade blocked: runtime activity is unknown (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (isInitRuntimeActive(activity)) {
+        throw new Error("init upgrade blocked: active DAG, Worker, or exclusive writer is present");
+    }
+    return activity;
+}
+function processLiveness(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return "unknown";
+    try {
+        process.kill(pid, 0);
+        return "active";
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return "stale";
+        return "unknown";
+    }
+}
+async function acquireGlobalLock(input) {
+    const root = runRoot(input.repoRoot);
+    await mkdir(root, { recursive: true });
+    const lock = path.join(root, GLOBAL_LOCK_NAME);
+    const token = randomUUID();
+    const owner = {
+        schemaVersion: 1,
+        token,
+        runId: input.runId,
+        pid: process.pid,
+        hostname: os.hostname(),
+        acquiredAt: new Date().toISOString(),
+    };
+    const tryCreate = async () => {
+        try {
+            await mkdir(lock);
+            await writeJsonAtomic(path.join(lock, "owner.json"), owner);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    };
+    if (!(await tryCreate())) {
+        let existing;
+        try {
+            existing = JSON.parse(await readFile(path.join(lock, "owner.json"), "utf-8"));
+        }
+        catch {
+            throw new Error("init upgrade blocked: global upgrade owner is unreadable; lock state is unknown");
+        }
+        if (existing.hostname !== os.hostname() ||
+            typeof existing.pid !== "number") {
+            throw new Error(`init upgrade blocked: global upgrade owner is active or unknown (runId=${String(existing.runId ?? "unknown")})`);
+        }
+        const liveness = processLiveness(existing.pid);
+        if (liveness !== "stale") {
+            throw new Error(`init upgrade blocked: global upgrade owner is ${liveness} (runId=${String(existing.runId ?? "unknown")})`);
+        }
+        await rm(lock, { recursive: true, force: true });
+        if (!(await tryCreate())) {
+            throw new Error("init upgrade blocked: another upgrade writer acquired the global lock");
+        }
+    }
+    return async () => {
+        try {
+            const current = JSON.parse(await readFile(path.join(lock, "owner.json"), "utf-8"));
+            if (current.token === token) {
+                await rm(lock, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // Fail closed: never remove a lock whose ownership can no longer be proven.
+        }
+    };
+}
+async function currentVersionGate(input, identity) {
+    try {
+        const latest = input.latestVersion
+            ? await input.latestVersion()
+            : await createNpmUpdateClient({
+                currentVersion: identity.version,
+                packageRoot: identity.packageRoot,
+            }).latestVersion();
+        if (!latest)
+            return { outcome: "registry-unavailable" };
+        return versionsNewer(latest, identity.version)
+            ? { outcome: "newer-available", latestVersion: latest }
+            : { outcome: "latest", latestVersion: latest };
+    }
+    catch {
+        return { outcome: "registry-unavailable" };
+    }
+}
+function toRepoPath(repoRoot, absolutePath) {
+    return path.relative(repoRoot, absolutePath).split(path.sep).join("/");
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function normalizeAllowedPath(relativePath) {
+    if (!relativePath ||
+        path.isAbsolute(relativePath) ||
+        /[?*[\]{}!]/.test(relativePath)) {
+        throw new Error(`init upgrade merge guard rejected non-concrete allowedPath: ${relativePath}`);
+    }
+    const normalized = path.posix.normalize(relativePath.replace(/\\/g, "/"));
+    if (normalized === "." || normalized.startsWith("../")) {
+        throw new Error(`init upgrade merge guard rejected path outside repo: ${relativePath}`);
+    }
+    return normalized;
+}
+async function assertSafeMergePath(repoRoot, relativePath) {
+    const normalized = normalizeAllowedPath(relativePath);
+    const rootReal = await realpath(repoRoot);
+    const target = path.resolve(repoRoot, normalized);
+    if (!isWithin(path.resolve(repoRoot), target)) {
+        throw new Error(`init upgrade merge path escapes repo: ${normalized}`);
+    }
+    const targetStat = await lstat(target).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (targetStat?.isSymbolicLink()) {
+        throw new Error(`init upgrade merge path is a symlink: ${normalized}`);
+    }
+    if (targetStat && !targetStat.isFile()) {
+        throw new Error(`init upgrade merge path is not a file: ${normalized}`);
+    }
+    const containmentTarget = targetStat ? target : path.dirname(target);
+    const containedReal = await realpath(containmentTarget);
+    if (!isWithin(rootReal, containedReal)) {
+        throw new Error(`init upgrade merge realpath escapes repo: ${normalized}`);
+    }
+}
+async function snapshotWorkspace(repoRoot) {
+    const snapshot = {};
+    async function visit(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            // Git may expose the same temp repository through a short/long Windows
+            // path pair, making path.relative() lose the leading `.git` segment.
+            // Exclude the top-level Git administration directory by entry identity;
+            // init-upgrade protects its own controller anchors separately.
+            if (directory === repoRoot && entry.name === ".git")
+                continue;
+            const absolute = path.join(directory, entry.name);
+            const relative = toRepoPath(repoRoot, absolute);
+            if (relative === ".git" || relative.startsWith(".git/"))
+                continue;
+            if (relative === RUN_ROOT || relative.startsWith(`${RUN_ROOT}/`))
+                continue;
+            if (entry.isSymbolicLink()) {
+                snapshot[relative] = `symlink:${await readlink(absolute)}`;
+                continue;
+            }
+            if (entry.isDirectory()) {
+                snapshot[relative] = "directory";
+                await visit(absolute);
+                continue;
+            }
+            if (entry.isFile()) {
+                snapshot[relative] = `file:${sha256(await readFile(absolute))}`;
+                continue;
+            }
+            snapshot[relative] = "special";
+        }
+    }
+    await visit(repoRoot);
+    return snapshot;
+}
+function changedWorkspacePaths(before, after) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+        .filter((relativePath) => before[relativePath] !== after[relativePath])
+        .sort();
+}
+/**
+ * Generated-output prefixes treated as verification noise when git ignore
+ * rules are unavailable (non-git target). In a git repo the authoritative
+ * filter is `.gitignore` via `git check-ignore`; this list only covers the
+ * common case where a verification command such as `npm run build` writes
+ * untracked artifacts (build/dist/coverage/...) into the workspace.
+ */
+const WORKSPACE_NOISE_PREFIXES = [
+    "node_modules/",
+    "build/",
+    "dist/",
+    "coverage/",
+    ".turbo/",
+    ".next/",
+    ".nuxt/",
+    ".cache/",
+    ".parcel-cache/",
+    ".vite/",
+    "out/",
+    "target/",
+    "__pycache__/",
+];
+function isWorkspaceNoisePath(relative) {
+    if (relative === ".git" || relative.startsWith(".git/"))
+        return true;
+    if (relative === RUN_ROOT || relative.startsWith(`${RUN_ROOT}/`))
+        return true;
+    return WORKSPACE_NOISE_PREFIXES.some((prefix) => relative === prefix.slice(0, -1) || relative.startsWith(prefix));
+}
+/**
+ * Filters changed workspace paths down to meaningful (non-generated) changes
+ * so a verification command that legitimately writes git-ignored artifacts is
+ * not misjudged as an unauthorized workspace mutation. Git ignore rules are
+ * authoritative when the target is a git repo; otherwise the built-in
+ * generated-output prefixes apply.
+ */
+async function filterWorkspaceNoise(repoRoot, relativePaths) {
+    const builtinFiltered = relativePaths.filter((relative) => !isWorkspaceNoisePath(relative));
+    if (builtinFiltered.length === 0)
+        return builtinFiltered;
+    const ignored = await gitIgnoredPaths(repoRoot, builtinFiltered);
+    if (ignored === null)
+        return builtinFiltered;
+    return builtinFiltered.filter((relative) => !ignored.has(relative));
+}
+/**
+ * Returns the subset of paths matched by git ignore rules, or null when the
+ * target is not a git repository (or git is unavailable), in which case the
+ * caller falls back to the built-in noise prefixes.
+ */
+async function gitIgnoredPaths(repoRoot, relativePaths) {
+    return await new Promise((resolve) => {
+        execFile("git", ["-C", repoRoot, "check-ignore", ...relativePaths], {
+            timeout: 15_000,
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (error) {
+                // `git check-ignore` exits 1 when no path is ignored: that is a
+                // successful lookup with an empty result set. Any other failure
+                // (e.g. 128 outside a repo) means the git filter is unavailable.
+                if (error.code === 1 && stdout.length === 0)
+                    resolve(new Set());
+                else
+                    resolve(null);
+                return;
+            }
+            resolve(new Set(stdout
+                .split("\n")
+                .filter(Boolean)
+                .map((entry) => entry.split(path.sep).join("/"))));
+        });
+    });
+}
+function isFrozenVerificationSurface(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === 1 &&
+        Array.isArray(value.files) &&
+        value.files.length > 0 &&
+        value.files.every((entry) => isRecord(entry) &&
+            typeof entry.path === "string" &&
+            entry.path === normalizeAllowedPath(entry.path) &&
+            isSha256(entry.sha256)) &&
+        new Set(value.files.map((entry) => entry.path)).size === value.files.length);
+}
+async function assertSafeRegularRepoFile(repoRoot, relativePath) {
+    const normalized = normalizeAllowedPath(relativePath);
+    await assertSafeMergePath(repoRoot, normalized);
+    const target = path.join(repoRoot, normalized);
+    const targetStat = await lstat(target).catch(() => undefined);
+    if (!targetStat?.isFile() || targetStat.isSymbolicLink()) {
+        throw new Error(`verification authority input is not a regular file: ${normalized}`);
+    }
+    return normalized;
+}
+async function staticScriptDependencies(repoRoot, relativePath, collected) {
+    const normalized = await assertSafeRegularRepoFile(repoRoot, relativePath);
+    if (collected.has(normalized))
+        return;
+    collected.add(normalized);
+    const content = await readFile(path.join(repoRoot, normalized), "utf-8");
+    const dependencies = new Set();
+    for (const match of content.matchAll(/(?:^|[;\s])(?:bash|source|\.)\s+["']?([A-Za-z0-9_./-]+\.sh)["']?/gm)) {
+        if (match[1])
+            dependencies.add(match[1]);
+    }
+    // check-repo-style arrays dispatch quoted script paths indirectly through a variable.
+    for (const match of content.matchAll(/["'](scripts\/[A-Za-z0-9_./-]+\.sh)["']/g)) {
+        if (match[1])
+            dependencies.add(match[1]);
+    }
+    for (const dependency of dependencies) {
+        if (!path.isAbsolute(dependency) && !dependency.startsWith("../")) {
+            await staticScriptDependencies(repoRoot, dependency, collected);
+        }
+    }
+    // Direct interpreter inputs are verification authority too. Only existing,
+    // concrete repo files are accepted; optional absent fallback branches are not.
+    for (const match of content.matchAll(/(?:scripts|src)\/[A-Za-z0-9_./-]+\.(?:mjs|cjs|js|ts)/g)) {
+        const dependency = match[0];
+        if (await exists(path.join(repoRoot, dependency))) {
+            collected.add(await assertSafeRegularRepoFile(repoRoot, dependency));
+        }
+    }
+}
+async function existingRepoFileTokens(repoRoot, tokens) {
+    const files = [];
+    for (const token of tokens) {
+        const candidate = token.includes("=") ? token.slice(token.indexOf("=") + 1) : token;
+        if (!candidate || candidate.startsWith("-") || path.isAbsolute(candidate)) {
+            continue;
+        }
+        let normalized;
+        try {
+            normalized = normalizeAllowedPath(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (await exists(path.join(repoRoot, normalized))) {
+            files.push(await assertSafeRegularRepoFile(repoRoot, normalized));
+        }
+    }
+    return [...new Set(files)];
+}
+async function commandRepositoryInputs(repoRoot, commandText, npmScriptStack = []) {
+    const tokens = tokenizeCommand(commandText);
+    const command = tokens[0];
+    if (!command)
+        throw new Error("empty verification command");
+    if (command === "node" || command === "node.exe") {
+        if (tokens.some((token) => ["-e", "--eval", "-p", "--print"].includes(token))) {
+            throw new Error("verification authority rejects direct node code evaluation");
+        }
+        const files = await existingRepoFileTokens(repoRoot, tokens.slice(1));
+        if (files.length === 0) {
+            throw new Error("verification authority requires node to execute a concrete repo-local entry");
+        }
+        return files;
+    }
+    if (command === "bash") {
+        if (tokens.length < 2 || !tokens[1]?.endsWith(".sh")) {
+            throw new Error("verification authority requires bash to execute one concrete repo-local script");
+        }
+        return [await assertSafeRegularRepoFile(repoRoot, tokens[1])];
+    }
+    if (command === "npm" || command === "npm.cmd") {
+        if (tokens.some((token) => ["-e", "--eval", "-p", "--print"].includes(token))) {
+            throw new Error("verification authority rejects package command code evaluation");
+        }
+        let scriptName;
+        if (tokens[1] === "run" || tokens[1] === "run-script")
+            scriptName = tokens[2];
+        else if (["test", "start", "stop", "restart"].includes(tokens[1] ?? ""))
+            scriptName = tokens[1];
+        if (!scriptName || scriptName.startsWith("-")) {
+            throw new Error("verification authority requires npm to select one concrete package script");
+        }
+        if (npmScriptStack.includes(scriptName)) {
+            throw new Error(`verification authority rejected recursive npm script: ${scriptName}`);
+        }
+        const packagePath = await assertSafeRegularRepoFile(repoRoot, "package.json");
+        const packageJson = JSON.parse(await readFile(path.join(repoRoot, packagePath), "utf-8"));
+        const script = packageJson.scripts?.[scriptName];
+        if (typeof script !== "string" || !script.trim()) {
+            throw new Error(`verification authority package script is missing: ${scriptName}`);
+        }
+        const nested = [];
+        for (const lifecycleName of [`pre${scriptName}`, scriptName, `post${scriptName}`]) {
+            const lifecycleScript = packageJson.scripts?.[lifecycleName];
+            if (typeof lifecycleScript !== "string" || !lifecycleScript.trim())
+                continue;
+            nested.push(...(await commandRepositoryInputs(repoRoot, lifecycleScript, [
+                ...npmScriptStack,
+                scriptName,
+                lifecycleName,
+            ])));
+        }
+        return [...new Set([packagePath, ...nested])];
+    }
+    if (command === "npx" || command === "npx.cmd") {
+        if (tokens.some((token) => ["-e", "--eval", "-p", "--print", "-c", "--call"].includes(token))) {
+            throw new Error("verification authority rejects package command code evaluation");
+        }
+        let runnerIndex = 1;
+        while (["-y", "--yes", "--no-install"].includes(tokens[runnerIndex] ?? "")) {
+            runnerIndex += 1;
+        }
+        const runner = tokens[runnerIndex];
+        if (!runner || runner.startsWith("-")) {
+            throw new Error("verification authority requires npx to select one concrete runner");
+        }
+        const files = await existingRepoFileTokens(repoRoot, tokens.slice(runnerIndex));
+        if (files.length === 0) {
+            throw new Error("verification authority requires npx to bind a concrete repo-local entry");
+        }
+        const inputs = [...files];
+        if (await exists(path.join(repoRoot, "package.json"))) {
+            inputs.unshift(await assertSafeRegularRepoFile(repoRoot, "package.json"));
+        }
+        return [...new Set(inputs)];
+    }
+    if (command.includes("/") || command.startsWith(".")) {
+        return [await assertSafeRegularRepoFile(repoRoot, command)];
+    }
+    const directInputs = await existingRepoFileTokens(repoRoot, tokens.slice(1));
+    if (directInputs.length > 0)
+        return directInputs;
+    throw new Error(`verification authority rejects unbound executable: ${command}`);
+}
+async function freezeVerificationSurface(repoRoot) {
+    const collected = new Set();
+    const add = async (relativePath) => {
+        collected.add(await assertSafeRegularRepoFile(repoRoot, relativePath));
+    };
+    await add("harness.json");
+    const harness = await readVerificationHarness(repoRoot);
+    const matrixPath = verificationMatrixPath(harness);
+    await add(matrixPath);
+    const commands = ["bash scripts/check-repo.sh", await discoverQuickVerification(repoRoot)];
+    for (const command of commands) {
+        for (const input of await commandRepositoryInputs(repoRoot, command)) {
+            const normalized = await assertSafeRegularRepoFile(repoRoot, input);
+            if (normalized.endsWith(".sh"))
+                await staticScriptDependencies(repoRoot, normalized, collected);
+            else
+                collected.add(normalized);
+        }
+    }
+    const files = await Promise.all([...collected].sort().map(async (relativePath) => ({
+        path: relativePath,
+        sha256: sha256(await readFile(path.join(repoRoot, relativePath))),
+    })));
+    return { schemaVersion: 1, files };
+}
+async function assertFrozenVerificationSurface(repoRoot, surface) {
+    if (!isFrozenVerificationSurface(surface)) {
+        throw new Error("verification authority surface manifest is invalid");
+    }
+    for (const entry of surface.files) {
+        const normalized = await assertSafeRegularRepoFile(repoRoot, entry.path);
+        if (normalized !== entry.path || sha256(await readFile(path.join(repoRoot, normalized))) !== entry.sha256) {
+            throw new Error(`verification authority surface changed: ${entry.path}`);
+        }
+    }
+}
+function frozenVerificationMatrixPath(surface) {
+    const paths = surface.files
+        .map((entry) => entry.path)
+        .filter((pathName) => pathName === "verification-matrix.md" ||
+        pathName.endsWith("/verification-matrix.md"));
+    if (paths.length !== 1) {
+        throw new Error("verification authority surface must contain exactly one verification-matrix.md");
+    }
+    return paths[0];
+}
+function isControllerAuthorizedVerificationMergeTask(task, surface) {
+    const taskPath = normalizeAllowedPath(task.path);
+    if (taskPath === "harness.json")
+        return true;
+    return ((taskPath === "verification-matrix.md" ||
+        taskPath.endsWith("/verification-matrix.md")) &&
+        Boolean(surface?.files.some((entry) => entry.path === taskPath)));
+}
+async function assertFrozenVerificationSurfaceExcept(repoRoot, surface, exemptPath) {
+    if (!isFrozenVerificationSurface(surface)) {
+        throw new Error("verification authority surface manifest is invalid");
+    }
+    const canonicalExemptPath = exemptPath
+        ? normalizeAllowedPath(exemptPath)
+        : undefined;
+    for (const entry of surface.files) {
+        if (entry.path === canonicalExemptPath)
+            continue;
+        const normalized = await assertSafeRegularRepoFile(repoRoot, entry.path);
+        if (normalized !== entry.path || sha256(await readFile(path.join(repoRoot, normalized))) !== entry.sha256) {
+            throw new Error(`verification authority surface changed: ${entry.path}`);
+        }
+    }
+}
+async function validateControllerAuthorizedVerificationMerge(input) {
+    const taskPath = normalizeAllowedPath(input.task.path);
+    if (!isControllerAuthorizedVerificationMergeTask(input.task, input.surface))
+        return;
+    const harness = await readVerificationHarness(input.repoRoot);
+    const matrixPath = normalizeAllowedPath(verificationMatrixPath(harness));
+    const frozenMatrixPath = frozenVerificationMatrixPath(input.surface);
+    if (matrixPath !== frozenMatrixPath ||
+        (taskPath !== "harness.json" && taskPath !== frozenMatrixPath)) {
+        throw new Error("verification authority merge must retain the controller-frozen verification matrix path");
+    }
+    if (taskPath === "harness.json") {
+        harnessManifestSchema.parse(harness);
+        const authority = input.guard?.verificationAuthority;
+        if (authority &&
+            (!sameJsonValue(harness.executors ?? null, authority.executors) ||
+                !sameJsonValue(harness.workflowPolicy ?? null, authority.workflowPolicy))) {
+            throw new Error("verification authority harness.json merge cannot change controller executor or workflow authority");
+        }
+    }
+    const command = await discoverQuickVerification(input.repoRoot);
+    tokenizeCommand(command);
+    await commandRepositoryInputs(input.repoRoot, command);
+}
+function assertTaskOutsideVerificationSurface(task, surface) {
+    const taskPath = normalizeAllowedPath(task.path);
+    if (surface.files.some((entry) => entry.path === taskPath) &&
+        !isControllerAuthorizedVerificationMergeTask(task, surface)) {
+        throw new Error(`init upgrade merge task targets authority-sensitive verification input: ${taskPath}`);
+    }
+}
+async function snapshotDirectory(directory) {
+    const snapshot = {};
+    const visit = async (absolute, relative) => {
+        const entries = await readdir(absolute, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            const child = path.join(absolute, entry.name);
+            if (entry.isSymbolicLink())
+                snapshot[childRelative] = `symlink:${await readlink(child)}`;
+            else if (entry.isDirectory()) {
+                snapshot[childRelative] = "directory";
+                await visit(child, childRelative);
+            }
+            else if (entry.isFile())
+                snapshot[childRelative] = `file:${sha256(await readFile(child))}`;
+            else
+                snapshot[childRelative] = "special";
+        }
+    };
+    await visit(directory, "");
+    return snapshot;
+}
+async function controllerAnchorSnapshot(repoRoot, state) {
+    const location = await controllerAnchorPath({ repoRoot, runId: state.runId });
+    return await snapshotDirectory(location.anchorRoot);
+}
+function validateTaskBoundary(task) {
+    const allowed = task.allowedPaths.map(normalizeAllowedPath);
+    if (allowed.length !== 1 || allowed[0] !== normalizeAllowedPath(task.path)) {
+        throw new Error(`init upgrade merge task ${task.taskId} must declare exactly its concrete single-file path`);
+    }
+    return allowed;
+}
+async function harnessVerificationAuthority(repoRoot, task) {
+    if (normalizeAllowedPath(task.path) !== "harness.json")
+        return undefined;
+    const harness = await readVerificationHarness(repoRoot);
+    return {
+        executors: cloneJson(harness.executors ?? null),
+        workflowPolicy: cloneJson(harness.workflowPolicy ?? null),
+    };
+}
+async function createMergeGuard(repoRoot, task) {
+    for (const allowedPath of validateTaskBoundary(task)) {
+        await assertSafeMergePath(repoRoot, allowedPath);
+    }
+    return {
+        task,
+        baselineWorkspace: await snapshotWorkspace(repoRoot),
+        verificationAuthority: await harnessVerificationAuthority(repoRoot, task),
+    };
+}
+function isMergeReceipt(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.taskId === "string" &&
+        typeof value.path === "string" &&
+        isSha256(value.currentSha256) &&
+        isSha256(value.desiredSha256) &&
+        typeof value.acceptedAt === "string" &&
+        !Number.isNaN(Date.parse(value.acceptedAt)));
+}
+function assertPendingAcceptance(value, state, task) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        !isRecord(value.guard) ||
+        !isRecord(value.transition) ||
+        !isRecord(value.surfaceTransition)) {
+        throw new Error("invalid pending merge acceptance record");
+    }
+    const pending = value;
+    const desiredSha256 = task.evidence.desiredSha256;
+    const sourceAnchorSha256 = task.evidence.sourceAnchorSha256;
+    const guard = pending.guard;
+    const receipt = pending.receipt;
+    const transition = pending.transition;
+    const surfaceTransition = pending.surfaceTransition;
+    const canonicalPath = normalizeAllowedPath(task.path);
+    if (pending.runId !== state.runId ||
+        pending.repoRoot !== state.repoRoot ||
+        guard.taskId !== task.taskId ||
+        guard.path !== canonicalPath ||
+        !Array.isArray(guard.allowedPaths) ||
+        guard.allowedPaths.length !== 1 ||
+        guard.allowedPaths[0] !== canonicalPath ||
+        !isSha256(guard.currentSha256) ||
+        !isSha256(guard.desiredSha256) ||
+        !isSha256(desiredSha256) ||
+        guard.desiredSha256 !== desiredSha256 ||
+        (sourceAnchorSha256 === undefined
+            ? guard.sourceAnchorSha256 !== undefined
+            : guard.sourceAnchorSha256 !== sourceAnchorSha256) ||
+        !isMergeReceipt(receipt) ||
+        receipt.taskId !== guard.taskId ||
+        receipt.path !== guard.path ||
+        receipt.currentSha256 !== guard.currentSha256 ||
+        receipt.desiredSha256 !== guard.desiredSha256 ||
+        transition.fromPhase !== "MODEL_MERGE" ||
+        transition.toPhase !== "PLAN" ||
+        !Number.isInteger(transition.priorMergeReceiptCount) ||
+        transition.priorMergeReceiptCount < 0 ||
+        surfaceTransition.path !== canonicalPath ||
+        !isSha256(surfaceTransition.beforeSha256) ||
+        !isSha256(surfaceTransition.acceptedSha256) ||
+        !isRecord(surfaceTransition.beforeEntry)) {
+        throw new Error("pending merge acceptance binding is invalid");
+    }
+}
+function acceptedSurface(input) {
+    if (!isRecord(input.surface) || !isRecord(input.surface.files)) {
+        throw new Error("init upgrade merge surface transition is invalid");
+    }
+    const canonicalPath = normalizeAllowedPath(input.task.path);
+    const entry = input.surface.files[canonicalPath];
+    if (!isRecord(entry)) {
+        throw new Error(`init upgrade cannot accept ${canonicalPath}: recorded surface entry is missing`);
+    }
+    const accepted = cloneJson(input.surface);
+    const acceptedFiles = accepted.files;
+    const acceptedEntry = isRecord(acceptedFiles)
+        ? acceptedFiles[canonicalPath]
+        : undefined;
+    if (!isRecord(acceptedEntry)) {
+        throw new Error("init upgrade merge surface transition is invalid");
+    }
+    acceptedEntry.currentSha256 = input.currentSha256;
+    acceptedEntry.acceptedMerge = {
+        currentSha256: input.currentSha256,
+        desiredSha256: input.desiredSha256,
+        ...(typeof input.task.evidence.sourceAnchorSha256 === "string"
+            ? { sourceAnchorSha256: input.task.evidence.sourceAnchorSha256 }
+            : {}),
+    };
+    return { beforeEntry: cloneJson(entry), accepted };
+}
+async function validatePendingSurfaceTransition(input) {
+    const transition = input.pending.surfaceTransition;
+    const baselineSurface = input.guard.baselineWorkspace[INIT_SURFACE_STATE_PATH];
+    if (baselineSurface !== `file:${transition.beforeSha256}`) {
+        throw new Error("pending merge acceptance surface transition is not bound to the merge baseline");
+    }
+    const surfacePath = path.join(input.repoRoot, INIT_SURFACE_STATE_PATH);
+    let surfaceText;
+    let surface;
+    try {
+        surfaceText = await readFile(surfacePath, "utf-8");
+        surface = JSON.parse(surfaceText);
+    }
+    catch {
+        throw new Error("pending merge acceptance init-surface is invalid");
+    }
+    const actualSha256 = sha256(surfaceText);
+    if (actualSha256 === transition.beforeSha256) {
+        if (!isRecord(surface) ||
+            !isRecord(surface.files) ||
+            !sameJsonValue(surface.files[normalizeAllowedPath(input.task.path)], transition.beforeEntry)) {
+            throw new Error("pending merge acceptance before surface transition is inconsistent");
+        }
+        const expected = acceptedSurface({
+            surface,
+            task: input.task,
+            currentSha256: input.pending.guard.currentSha256,
+            desiredSha256: input.pending.guard.desiredSha256,
+        }).accepted;
+        if (sha256(serializeJson(expected)) !== transition.acceptedSha256) {
+            throw new Error("pending merge acceptance accepted surface transition is inconsistent");
+        }
+        return "before";
+    }
+    if (actualSha256 !== transition.acceptedSha256) {
+        throw new Error("pending merge acceptance init-surface contains an unrelated modification");
+    }
+    if (!isRecord(surface) || !isRecord(surface.files)) {
+        throw new Error("pending merge acceptance init-surface is invalid");
+    }
+    const reconstructedBefore = cloneJson(surface);
+    const reconstructedFiles = reconstructedBefore.files;
+    if (!isRecord(reconstructedFiles)) {
+        throw new Error("pending merge acceptance init-surface is invalid");
+    }
+    reconstructedFiles[normalizeAllowedPath(input.task.path)] = cloneJson(transition.beforeEntry);
+    if (sha256(serializeJson(reconstructedBefore)) !== transition.beforeSha256) {
+        throw new Error("pending merge acceptance surface transition changed unrelated facts");
+    }
+    const expectedAccepted = acceptedSurface({
+        surface: reconstructedBefore,
+        task: input.task,
+        currentSha256: input.pending.guard.currentSha256,
+        desiredSha256: input.pending.guard.desiredSha256,
+    }).accepted;
+    if (serializeJson(expectedAccepted) !== surfaceText) {
+        throw new Error("pending merge acceptance accepted surface transition is not exact");
+    }
+    return "accepted";
+}
+async function readPendingAcceptance(input) {
+    const file = path.join(input.directory, "merge-acceptance-pending.json");
+    if (!(await exists(file)))
+        return input.authoritativePending;
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, "utf-8"));
+    }
+    catch {
+        throw new Error("invalid pending merge acceptance record");
+    }
+    assertPendingAcceptance(parsed, input.state, input.task);
+    if (!input.authoritativePending || !sameJsonValue(parsed, input.authoritativePending)) {
+        throw new Error("pending merge acceptance is not authorized by the controller anchor");
+    }
+    return input.authoritativePending;
+}
+async function verifyMergedFileInvariants(repoRoot, task) {
+    await assertSafeMergePath(repoRoot, task.path);
+    const content = await readFile(path.join(repoRoot, task.path), "utf-8");
+    if (!content.trim())
+        throw new Error(`init upgrade merge invariant failed: ${task.path} is empty`);
+    if (task.path.endsWith(".json")) {
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`init upgrade merge invariant failed: ${task.path} must contain a JSON object`);
+        }
+    }
+    if (task.path === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH) {
+        for (const token of [
+            `MAX_RETRIES = ${MAX_SESSION_RETRIES}`,
+            "plugin-ignore-permanent-error",
+            "recoveryWorkers",
+            "readSessionStatus",
+        ]) {
+            if (!content.includes(token))
+                throw new Error(`init upgrade merge invariant failed: ${task.path} is missing ${token}`);
+        }
+    }
+    if (task.path === OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH) {
+        for (const token of [
+            `MAX_OVERFLOW_RECOVERIES = ${MAX_OVERFLOW_RECOVERIES}`,
+            "pendingOverflow",
+            "deferredResume",
+            "recoveryWorkers",
+            "compactOrSummarize",
+        ]) {
+            if (!content.includes(token))
+                throw new Error(`init upgrade merge invariant failed: ${task.path} is missing ${token}`);
+        }
+    }
+    if (task.path === PI_CONTEXT_OVERFLOW_EXTENSION_PATH) {
+        for (const token of ["message_end", "context_length_exceeded:"]) {
+            if (!content.includes(token))
+                throw new Error(`init upgrade merge invariant failed: ${task.path} is missing ${token}`);
+        }
+    }
+    if (task.path === "AGENTS.md" ||
+        task.path.endsWith("/loop-agent/SKILL.md")) {
+        for (const token of ["init upgrade", "init check-update"]) {
+            if (!content.includes(token))
+                throw new Error(`init upgrade merge invariant failed: ${task.path} is missing ${token}`);
+        }
+    }
+    return sha256(content);
+}
+async function recordAcceptedMerge(input) {
+    const desiredSha256 = input.task.evidence.desiredSha256;
+    if (!desiredSha256) {
+        throw new Error(`init upgrade cannot accept ${input.task.path}: desired hash evidence is missing`);
+    }
+    const sourceAnchorSha256 = input.task.evidence.sourceAnchorSha256;
+    const canonicalPath = normalizeAllowedPath(input.task.path);
+    const surfacePath = path.join(input.state.repoRoot, INIT_SURFACE_STATE_PATH);
+    let pending = input.pending;
+    let receipt;
+    let accepted;
+    if (pending) {
+        receipt = pending.receipt;
+        if (input.pendingSurfaceState !== "before" &&
+            input.pendingSurfaceState !== "accepted") {
+            throw new Error("pending merge acceptance surface transition was not validated");
+        }
+        if (input.pendingSurfaceState === "before") {
+            const surface = JSON.parse(await readFile(surfacePath, "utf-8"));
+            accepted = acceptedSurface({
+                surface,
+                task: input.task,
+                currentSha256: input.currentSha256,
+                desiredSha256,
+            }).accepted;
+        }
+    }
+    else {
+        const surfaceText = await readFile(surfacePath, "utf-8");
+        const surface = JSON.parse(surfaceText);
+        const transition = acceptedSurface({
+            surface,
+            task: input.task,
+            currentSha256: input.currentSha256,
+            desiredSha256,
+        });
+        const beforeSha256 = sha256(surfaceText);
+        if (input.guard.baselineWorkspace[INIT_SURFACE_STATE_PATH] !==
+            `file:${beforeSha256}`) {
+            throw new Error("init upgrade merge surface no longer matches the guarded baseline");
+        }
+        accepted = transition.accepted;
+        receipt = {
+            taskId: input.task.taskId,
+            path: canonicalPath,
+            currentSha256: input.currentSha256,
+            desiredSha256,
+            acceptedAt: new Date().toISOString(),
+        };
+        pending = {
+            schemaVersion: 1,
+            runId: input.state.runId,
+            repoRoot: input.state.repoRoot,
+            guard: {
+                taskId: input.task.taskId,
+                path: canonicalPath,
+                allowedPaths: [canonicalPath],
+                currentSha256: input.currentSha256,
+                desiredSha256,
+                ...(sourceAnchorSha256 !== undefined
+                    ? { sourceAnchorSha256 }
+                    : {}),
+            },
+            receipt,
+            transition: {
+                fromPhase: "MODEL_MERGE",
+                toPhase: "PLAN",
+                priorMergeReceiptCount: input.state.mergeReceipts.length,
+            },
+            surfaceTransition: {
+                path: canonicalPath,
+                beforeSha256,
+                acceptedSha256: sha256(serializeJson(accepted)),
+                beforeEntry: transition.beforeEntry,
+            },
+        };
+        await writeControllerAnchor({
+            state: input.state,
+            mergeAuthority: {
+                task: input.task,
+                baselineWorkspace: input.guard.baselineWorkspace,
+                verificationAuthority: input.guard.verificationAuthority,
+                priorMergeReceiptCount: input.state.mergeReceipts.length,
+                priorMergeReceiptsSha256: sha256(serializeJson(input.state.mergeReceipts)),
+                stateProjection: controllerStateProjection(input.state),
+                stateProjectionSha256: canonicalSha256(controllerStateProjection(input.state)),
+                verificationSurface: input.verificationSurface,
+                pending,
+            },
+        });
+        await writeJsonAtomic(path.join(input.directory, "merge-acceptance-pending.json"), pending);
+    }
+    if (accepted)
+        await writeJsonAtomic(surfacePath, accepted);
+    if (!pending) {
+        throw new Error("pending merge acceptance was not established");
+    }
+    const priorMergeReceiptCount = pending.transition.priorMergeReceiptCount;
+    if (input.state.mergeReceipts.length === priorMergeReceiptCount) {
+        input.state.mergeReceipts.push(receipt);
+    }
+    else if (input.state.mergeReceipts.length !== priorMergeReceiptCount + 1 ||
+        !sameJsonValue(input.state.mergeReceipts[priorMergeReceiptCount], receipt)) {
+        throw new Error("pending merge acceptance receipt projection is inconsistent");
+    }
+    await writeJsonAtomic(path.join(input.directory, "model-merge-receipts.json"), input.state.mergeReceipts);
+}
+async function validateContinueMerge(directory, state, anchor) {
+    if (!anchor.mergeAuthority) {
+        if (state.phase === "MODEL_MERGE" && state.mergeTasks.length > 0) {
+            throw new Error("init upgrade controller merge baseline authority is missing or inconsistent");
+        }
+        return "none";
+    }
+    const authority = mergeAuthorityFromAnchor(anchor, state);
+    const projection = mergeAuthorityProjection(state, authority);
+    const task = authority.task;
+    await assertFrozenVerificationSurfaceExcept(state.repoRoot, authority.verificationSurface, isControllerAuthorizedVerificationMergeTask(task, authority.verificationSurface)
+        ? task.path
+        : undefined);
+    const authoritativeGuard = {
+        task,
+        baselineWorkspace: authority.baselineWorkspace,
+        verificationAuthority: authority.verificationAuthority,
+    };
+    const allowed = new Set(validateTaskBoundary(task));
+    for (const allowedPath of allowed) {
+        await assertSafeMergePath(state.repoRoot, allowedPath);
+    }
+    const current = await snapshotWorkspace(state.repoRoot);
+    const rawChanged = changedWorkspacePaths(authoritativeGuard.baselineWorkspace, current);
+    const pending = await readPendingAcceptance({
+        directory,
+        state,
+        task,
+        authoritativePending: authority.pending,
+    });
+    const pendingSurfaceState = pending
+        ? await validatePendingSurfaceTransition({
+            repoRoot: state.repoRoot,
+            guard: authoritativeGuard,
+            task,
+            pending,
+        })
+        : undefined;
+    // Only the out-of-bound drift check treats git-ignored/generated-output
+    // changes as noise; allowed-path changes are merge content and must stay
+    // intact even when the target is git-ignored (e.g. `.agents/skills/*`).
+    const changed = await filterWorkspaceNoise(state.repoRoot, rawChanged);
+    const unexpected = changed.filter((relativePath) => {
+        if (allowed.has(relativePath))
+            return false;
+        return !(relativePath === INIT_SURFACE_STATE_PATH &&
+            pendingSurfaceState === "accepted");
+    });
+    if (unexpected.length > 0) {
+        throw new Error(`init upgrade merge write-guard blocked out-of-bound workspace changes: ${unexpected.join(", ")}`);
+    }
+    const changedAllowed = rawChanged.filter((relativePath) => allowed.has(relativePath));
+    if (changedAllowed.length === 0) {
+        if (pending) {
+            throw new Error("pending merge acceptance cannot authorize a merge without an allowed workspace change");
+        }
+        state.nextAction = `No change was detected in allowedPaths=[${[...allowed].join(", ")}]. Complete the current merge task before calling --continue.`;
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return "no-change";
+    }
+    const currentSha256 = await verifyMergedFileInvariants(state.repoRoot, task);
+    await validateControllerAuthorizedVerificationMerge({
+        repoRoot: state.repoRoot,
+        task,
+        surface: authority.verificationSurface,
+        guard: authoritativeGuard,
+    });
+    if (pending && pending.guard.currentSha256 !== currentSha256) {
+        throw new Error("pending merge acceptance current hash is inconsistent");
+    }
+    if (projection === "post-acceptance") {
+        if (!pending || pendingSurfaceState !== "accepted") {
+            throw new Error("post-acceptance merge state lacks the exact controller-authorized surface transition");
+        }
+        return "accepted";
+    }
+    await recordAcceptedMerge({
+        directory,
+        state,
+        guard: authoritativeGuard,
+        task,
+        currentSha256,
+        ...(pending && pendingSurfaceState
+            ? { pending, pendingSurfaceState }
+            : {}),
+        verificationSurface: authority.verificationSurface,
+    });
+    state.mergeTasks = [];
+    state.mergeGuard = undefined;
+    state.phase = "PLAN";
+    state.nextAction = "Accepted the bounded semantic merge; replan and verify the current workspace.";
+    await saveState(directory, state);
+    await rm(path.join(directory, "merge-acceptance-pending.json"), {
+        force: true,
+    });
+    return "accepted";
+}
+function boundedOutput(value) {
+    return value.length <= 8000 ? value : value.slice(value.length - 8000);
+}
+const VERIFICATION_COMMAND_DEADLINE_MS = 300_000;
+const VERIFICATION_STDIO_GRACE_MS = 500;
+const VERIFICATION_TREE_SETTLE_MS = 500;
+const VERIFICATION_QUIET_WINDOW_MS = 500;
+const VERIFICATION_OUTPUT_LIMIT = 4 * 1024 * 1024;
+const VERIFICATION_SUPERVISOR_SOURCE = `
+import { spawn } from "node:child_process";
+const specification = JSON.parse(Buffer.from(process.argv[2], "base64url").toString("utf8"));
+let worker;
+let workerClosed = false;
+let exitResult;
+let sent = false;
+const finish = (message) => {
+	if (sent) return;
+	sent = true;
+	const afterSend = () => {
+		if (specification.holdOpen) {
+			setInterval(() => {}, 60000);
+			return;
+		}
+		worker?.stdout?.destroy();
+		worker?.stderr?.destroy();
+		process.disconnect?.();
+		process.exit(0);
+	};
+	if (typeof process.send !== "function") process.exit(97);
+	process.send({ ...message, stdioOpen: !workerClosed }, afterSend);
+};
+try {
+	worker = spawn(specification.command, specification.args, {
+		cwd: process.cwd(),
+		env: process.env,
+		stdio: ["ignore", "pipe", "pipe"],
+		windowsHide: true,
+		shell: false,
+	});
+	worker.stdout?.pipe(process.stdout);
+	worker.stderr?.pipe(process.stderr);
+	worker.once("close", () => {
+		workerClosed = true;
+		if (exitResult) finish(exitResult);
+	});
+	worker.once("error", (error) => finish({
+		type: "result",
+		ok: false,
+		exitCode: null,
+		error: error instanceof Error ? error.message : String(error),
+	}));
+	worker.once("exit", (code, signal) => {
+		exitResult = {
+			type: "result",
+			ok: code === 0 && signal === null,
+			exitCode: typeof code === "number" ? code : 1,
+			...(signal ? { error: "verification command exited by signal " + signal } : {}),
+		};
+		if (workerClosed) finish(exitResult);
+		else setTimeout(() => finish(exitResult), specification.stdioGraceMs);
+	});
+} catch (error) {
+	finish({
+		type: "result",
+		ok: false,
+		exitCode: null,
+		error: error instanceof Error ? error.message : String(error),
+	});
+}
+process.once("disconnect", () => {
+	if (!sent) worker?.kill("SIGTERM");
+	process.exit(98);
+});
+`;
+class VerificationProcessBoundaryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VerificationProcessBoundaryError";
+    }
+}
+function tokenizeCommand(command) {
+    if (!command.trim() || /[;&|><`$\r\n]/.test(command)) {
+        throw new Error(`unsafe verification command: ${command}`);
+    }
+    const tokens = [];
+    let token = "";
+    let quote;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (quote) {
+            if (character === quote)
+                quote = undefined;
+            else
+                token += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (/\s/.test(character)) {
+            if (token) {
+                tokens.push(token);
+                token = "";
+            }
+            continue;
+        }
+        token += character;
+    }
+    if (quote)
+        throw new Error(`unterminated quote in verification command: ${command}`);
+    if (token)
+        tokens.push(token);
+    if (tokens.length === 0)
+        throw new Error("empty verification command");
+    return tokens;
+}
+async function snapshotOptionalDirectory(directory) {
+    const entry = await lstat(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!entry)
+        return {};
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+        throw new Error("real Pi home is not a regular directory");
+    }
+    return await snapshotDirectory(directory);
+}
+function verificationSandboxEnvironment(sandbox) {
+    const home = path.join(sandbox, "home");
+    const temporary = path.join(sandbox, "tmp");
+    const config = path.join(sandbox, "config");
+    const cache = path.join(sandbox, "cache");
+    const pathValue = process.env.PATH;
+    if (!pathValue)
+        throw new Error("verification isolation requires PATH");
+    const env = {
+        PATH: pathValue,
+        HOME: home,
+        USERPROFILE: home,
+        XDG_CONFIG_HOME: config,
+        XDG_CACHE_HOME: cache,
+        XDG_DATA_HOME: path.join(sandbox, "data"),
+        TMPDIR: temporary,
+        TMP: temporary,
+        TEMP: temporary,
+        PI_HOME: path.join(sandbox, "pi-home"),
+        PI_CONFIG_DIR: path.join(config, "pi"),
+        PI_CACHE_DIR: path.join(cache, "pi"),
+        npm_config_cache: path.join(cache, "npm"),
+        HARNESS_ALLOW_ACTIVE_DAG_RUNS: "1",
+    };
+    for (const name of ["SystemRoot", "WINDIR", "ComSpec", "PATHEXT", "LANG", "LC_ALL"]) {
+        if (process.env[name])
+            env[name] = process.env[name];
+    }
+    return env;
+}
+async function createVerificationSandbox() {
+    const sandbox = await mkdtemp(path.join(os.tmpdir(), "loop-agent-init-verification-"));
+    await Promise.all(["home", "tmp", "config", "cache", "data", "pi-home"].map((directory) => mkdir(path.join(sandbox, directory), { recursive: true })));
+    return sandbox;
+}
+async function createVerificationWriteAudit(input) {
+    const events = [];
+    const failures = [];
+    const watchers = [];
+    const watched = new Set();
+    const canonicalRepoRoot = await realpath(input.repoRoot);
+    const piHome = path.join(os.homedir(), ".pi");
+    const anchor = await controllerAnchorPath(input.state);
+    const note = (scope, file) => {
+        events.push(`${scope}=${file.split(path.sep).join("/")}`);
+    };
+    const ignoredWorkspacePath = (candidate) => isWorkspaceNoisePath(toRepoPath(canonicalRepoRoot, candidate));
+    const install = async (scope, directory, ignore, scopeRoot) => {
+        const canonical = await realpath(directory);
+        if (watched.has(canonical))
+            return;
+        watched.add(canonical);
+        let watcher;
+        try {
+            watcher = watch(canonical, { persistent: false }, (_eventType, filename) => {
+                const candidate = filename
+                    ? path.join(canonical, filename.toString())
+                    : canonical;
+                if (ignore?.(candidate))
+                    return;
+                let existingDirectory = false;
+                try {
+                    existingDirectory = lstatSync(candidate).isDirectory();
+                }
+                catch {
+                    // A removed or transient path is still a write-boundary event.
+                }
+                // Windows can report a parent-directory notification when a read-only
+                // traversal opens an existing child directory. Nested watchers own real
+                // mutations below that child; persistent changes are also snapshot-checked.
+                if (!existingDirectory) {
+                    note(scope, path.relative(scopeRoot ?? directory, candidate) || ".");
+                }
+                // A parent rename can introduce a new directory. Installing its watcher
+                // closes the delayed-descendant gap even when the container event is noise.
+                void install(scope, candidate, ignore, scopeRoot).catch((error) => {
+                    const code = error.code;
+                    if (code !== "ENOENT" && code !== "ENOTDIR") {
+                        failures.push(`watcher refresh failed for ${scope}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                });
+            });
+            watcher.on("error", (error) => {
+                failures.push(`watcher failed for ${scope}: ${error.message}`);
+            });
+            watchers.push(watcher);
+        }
+        catch (error) {
+            throw new Error(`verification watcher is unavailable for ${scope}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const entries = await readdir(canonical, { withFileTypes: true });
+        for (const entry of entries) {
+            const child = path.join(canonical, entry.name);
+            if (ignore?.(child) || !entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            await install(scope, child, ignore, scopeRoot);
+        }
+    };
+    await install("workspace", canonicalRepoRoot, ignoredWorkspacePath, canonicalRepoRoot);
+    await install("controller", runRoot(input.repoRoot));
+    await install("controller-anchor", anchor.anchorRoot);
+    const piHomeEntry = await lstat(piHome).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (piHomeEntry) {
+        if (!piHomeEntry.isDirectory() || piHomeEntry.isSymbolicLink()) {
+            throw new Error("real Pi home is not a regular directory");
+        }
+        await install("pi-home", piHome);
+    }
+    else {
+        const home = await realpath(os.homedir());
+        let homeWatcher;
+        try {
+            homeWatcher = watch(home, { persistent: false }, (_eventType, filename) => {
+                if (!filename || filename.toString() === ".pi")
+                    note("pi-home", ".");
+            });
+            homeWatcher.on("error", (error) => {
+                failures.push(`watcher failed for pi-home parent: ${error.message}`);
+            });
+            watchers.push(homeWatcher);
+        }
+        catch (error) {
+            throw new Error(`verification watcher is unavailable for pi-home: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        events,
+        failures,
+        close: () => {
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}
+function appendVerificationOutput(current, chunk) {
+    const combined = `${current}${chunk.toString()}`;
+    return combined.length <= VERIFICATION_OUTPUT_LIMIT
+        ? combined
+        : combined.slice(combined.length - VERIFICATION_OUTPUT_LIMIT);
+}
+async function waitForBounded(promise, timeoutMs) {
+    let timeout;
+    const completed = await Promise.race([
+        promise.then(() => true),
+        new Promise((resolve) => {
+            timeout = setTimeout(() => resolve(false), timeoutMs);
+        }),
+    ]);
+    if (timeout)
+        clearTimeout(timeout);
+    return completed;
+}
+function processBoundaryExists(pid, group) {
+    try {
+        process.kill(group ? -pid : pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+async function runSupervisedVerification(input) {
+    const supervisorPath = path.join(input.sandbox, "verification-supervisor.mjs");
+    await writeFile(supervisorPath, VERIFICATION_SUPERVISOR_SOURCE, "utf-8");
+    // The fixed supervisor, not the repository command, is the direct detached
+    // child. It reports worker exit over IPC and keeps the Windows tree root alive
+    // until the controller performs bounded taskkill /T convergence.
+    const specification = Buffer.from(JSON.stringify({
+        command: input.command,
+        args: input.args,
+        stdioGraceMs: VERIFICATION_STDIO_GRACE_MS,
+        holdOpen: process.platform === "win32",
+    })).toString("base64url");
+    let stdout = "";
+    let stderr = "";
+    const supervisor = spawn(process.execPath, [supervisorPath, specification], {
+        cwd: input.repoRoot,
+        env: verificationSandboxEnvironment(input.sandbox),
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        detached: true,
+        windowsHide: true,
+        shell: false,
+    });
+    supervisor.stdout?.on("data", (chunk) => {
+        stdout = appendVerificationOutput(stdout, chunk);
+    });
+    supervisor.stderr?.on("data", (chunk) => {
+        stderr = appendVerificationOutput(stderr, chunk);
+    });
+    const waitForExit = new Promise((resolve) => {
+        supervisor.once("exit", () => resolve());
+        supervisor.once("error", () => resolve());
+    });
+    const outcome = await new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            resolve(value);
+        };
+        const deadline = setTimeout(() => {
+            finish({
+                reported: false,
+                ok: false,
+                exitCode: null,
+                stdioOpen: true,
+                timedOut: true,
+                error: `verification command exceeded ${VERIFICATION_COMMAND_DEADLINE_MS}ms deadline`,
+            });
+        }, VERIFICATION_COMMAND_DEADLINE_MS);
+        supervisor.once("error", (error) => {
+            finish({
+                reported: false,
+                ok: false,
+                exitCode: null,
+                stdioOpen: false,
+                timedOut: false,
+                error: `verification supervisor failed to start: ${error.message}`,
+            });
+        });
+        supervisor.on("message", (message) => {
+            if (!isRecord(message) ||
+                message.type !== "result" ||
+                typeof message.ok !== "boolean" ||
+                (message.exitCode !== null && typeof message.exitCode !== "number") ||
+                typeof message.stdioOpen !== "boolean" ||
+                (message.error !== undefined && typeof message.error !== "string")) {
+                finish({
+                    reported: false,
+                    ok: false,
+                    exitCode: null,
+                    stdioOpen: false,
+                    timedOut: false,
+                    error: "verification supervisor returned an invalid protocol message",
+                });
+                return;
+            }
+            finish({
+                reported: true,
+                ok: message.ok,
+                exitCode: message.exitCode,
+                stdioOpen: message.stdioOpen,
+                timedOut: false,
+                ...(message.error ? { error: message.error } : {}),
+            });
+        });
+        supervisor.once("exit", (code, signal) => {
+            setTimeout(() => {
+                finish({
+                    reported: false,
+                    ok: false,
+                    exitCode: typeof code === "number" ? code : null,
+                    stdioOpen: false,
+                    timedOut: false,
+                    error: `verification supervisor exited before reporting command completion${signal ? ` (${signal})` : ""}`,
+                });
+            }, 0);
+        });
+    });
+    return {
+        pid: supervisor.pid,
+        outcome,
+        waitForExit,
+        readResult: () => ({
+            ok: outcome.ok && !outcome.timedOut,
+            command: input.commandText,
+            exitCode: outcome.exitCode,
+            stdout: boundedOutput(stdout),
+            stderr: boundedOutput(`${stderr}${outcome.error ? `${stderr ? "\n" : ""}${outcome.error}` : ""}`),
+        }),
+    };
+}
+async function settleVerificationProcessTree(execution) {
+    const pid = execution.pid;
+    if (!pid || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    if (process.platform === "win32") {
+        // holdOpen keeps this exact boundary PID alive, avoiding a post-exit tree
+        // lookup against a vanished direct process.
+        const taskkillOutput = await new Promise((resolve, reject) => {
+            execFile("taskkill", ["/pid", String(pid), "/t", "/f"], { windowsHide: true, timeout: 5_000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+                if (error) {
+                    reject(new Error(`verification Windows process tree did not converge: ${boundedOutput(`${stdout}\n${stderr}\n${error.message}`)}`));
+                    return;
+                }
+                resolve(`${stdout}\n${stderr}`);
+            });
+        });
+        await new Promise((resolve) => setTimeout(resolve, VERIFICATION_TREE_SETTLE_MS));
+        if (processBoundaryExists(pid, false)) {
+            throw new Error("verification Windows process tree did not converge");
+        }
+        const terminatedLines = taskkillOutput
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        return execution.outcome.stdioOpen || terminatedLines.length > 1;
+    }
+    if (execution.outcome.reported) {
+        await waitForBounded(execution.waitForExit, VERIFICATION_TREE_SETTLE_MS);
+    }
+    let descendantsObserved = false;
+    if (processBoundaryExists(pid, true)) {
+        descendantsObserved = execution.outcome.reported;
+        try {
+            process.kill(-pid, "SIGTERM");
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw error;
+        }
+    }
+    await new Promise((resolve) => setTimeout(resolve, VERIFICATION_TREE_SETTLE_MS));
+    if (processBoundaryExists(pid, true)) {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, VERIFICATION_TREE_SETTLE_MS));
+        if (processBoundaryExists(pid, true)) {
+            throw new Error("verification descendant process group did not converge");
+        }
+    }
+    return descendantsObserved || execution.outcome.stdioOpen;
+}
+function scheduleDeferredVerificationCleanup(input) {
+    const retry = async () => {
+        try {
+            await settleVerificationProcessTree(input.execution);
+            await new Promise((resolve) => setTimeout(resolve, VERIFICATION_QUIET_WINDOW_MS));
+            input.audit.close();
+            await rm(input.sandbox, { recursive: true, force: true });
+            if (await exists(input.sandbox)) {
+                throw new Error("verification sandbox cleanup was incomplete");
+            }
+        }
+        catch {
+            // Keep the controller event loop alive while the watcher remains open.
+            // Exiting before boundary proof would abandon an unmonitored descendant.
+            setTimeout(() => void retry(), VERIFICATION_TREE_SETTLE_MS);
+        }
+    };
+    setTimeout(() => void retry(), VERIFICATION_TREE_SETTLE_MS);
+}
+async function runVerificationCommand(input) {
+    const { state, surface, commandText } = input;
+    const repoRoot = state.repoRoot;
+    let sandbox;
+    let audit;
+    let execution;
+    let boundaryConverged = false;
+    let descendantsObserved = false;
+    let failure;
+    let boundaryFailure;
+    let result;
+    try {
+        await assertFrozenVerificationSurface(repoRoot, surface);
+        const workspaceBefore = await snapshotWorkspace(repoRoot);
+        const controllerBefore = await snapshotDirectory(runRoot(repoRoot));
+        const anchorBefore = await controllerAnchorSnapshot(repoRoot, state);
+        const piHomeBefore = await snapshotOptionalDirectory(path.join(os.homedir(), ".pi"));
+        const tokens = tokenizeCommand(commandText);
+        await commandRepositoryInputs(repoRoot, commandText);
+        let command = tokens.shift();
+        if (process.platform === "win32" && command === "npm")
+            command = "npm.cmd";
+        if (process.platform === "win32" && command === "npx")
+            command = "npx.cmd";
+        if (command === "bash" && tokens[0])
+            await assertSafeMergePath(repoRoot, tokens[0]);
+        sandbox = await createVerificationSandbox();
+        audit = await createVerificationWriteAudit({ repoRoot, state });
+        execution = await runSupervisedVerification({
+            repoRoot,
+            sandbox,
+            command,
+            args: tokens,
+            commandText,
+        });
+        descendantsObserved = await settleVerificationProcessTree(execution);
+        boundaryConverged = true;
+        // Keep event coverage through a bounded quiet window after tree convergence.
+        await new Promise((resolve) => setTimeout(resolve, VERIFICATION_QUIET_WINDOW_MS));
+        result = execution.readResult();
+        if (audit.failures.length)
+            throw new Error(audit.failures.join("; "));
+        await assertFrozenVerificationSurface(repoRoot, surface);
+        const changedWorkspace = await filterWorkspaceNoise(repoRoot, changedWorkspacePaths(workspaceBefore, await snapshotWorkspace(repoRoot)));
+        const changedController = changedWorkspacePaths(controllerBefore, await snapshotDirectory(runRoot(repoRoot)));
+        const changedAnchors = changedWorkspacePaths(anchorBefore, await controllerAnchorSnapshot(repoRoot, state));
+        const changedPiHome = changedWorkspacePaths(piHomeBefore, await snapshotOptionalDirectory(path.join(os.homedir(), ".pi")));
+        // Workspace watcher events are repo-root relative (see scopeRoot in
+        // createVerificationWriteAudit); drop git-ignored/generated-output noise
+        // before deciding whether the subprocess wrote the workspace.
+        const workspaceEvents = audit.events.filter((event) => event.startsWith("workspace="));
+        const remainingEvents = [
+            ...audit.events.filter((event) => !event.startsWith("workspace=")),
+            ...(await filterWorkspaceNoise(repoRoot, workspaceEvents.map((event) => event.slice("workspace=".length)))).map((relative) => `workspace=${relative}`),
+        ];
+        if (descendantsObserved || remainingEvents.length || changedWorkspace.length || changedController.length || changedAnchors.length || changedPiHome.length) {
+            return {
+                ...result,
+                ok: false,
+                stderr: boundedOutput(`${result.stderr}\nverification write guard blocked changes: ${[
+                    ...(descendantsObserved ? ["process-tree=descendant"] : []),
+                    ...(remainingEvents.length ? [`events=${remainingEvents.join(",")}`] : []),
+                    ...(changedWorkspace.length ? [`workspace=${changedWorkspace.join(",")}`] : []),
+                    ...(changedController.length ? [`controller=${changedController.join(",")}`] : []),
+                    ...(changedAnchors.length ? [`controller-anchor=${changedAnchors.join(",")}`] : []),
+                    ...(changedPiHome.length ? [`pi-home=${changedPiHome.join(",")}`] : []),
+                ].join("; ")}`),
+            };
+        }
+    }
+    catch (error) {
+        failure = error;
+    }
+    finally {
+        if (execution && !boundaryConverged) {
+            try {
+                descendantsObserved =
+                    (await settleVerificationProcessTree(execution)) || descendantsObserved;
+                boundaryConverged = true;
+                await new Promise((resolve) => setTimeout(resolve, VERIFICATION_QUIET_WINDOW_MS));
+            }
+            catch (cleanupError) {
+                boundaryFailure = new VerificationProcessBoundaryError(`init upgrade ${state.runId} verification process boundary termination is unconfirmed${execution.pid ? ` for pid ${execution.pid}` : ""}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                if (audit && sandbox) {
+                    scheduleDeferredVerificationCleanup({ execution, audit, sandbox });
+                }
+            }
+        }
+        if (!boundaryFailure) {
+            if (audit)
+                audit.close();
+            if (sandbox) {
+                try {
+                    await rm(sandbox, { recursive: true, force: true });
+                    if (await exists(sandbox))
+                        throw new Error("verification sandbox cleanup was incomplete");
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+        }
+        if (boundaryFailure)
+            throw boundaryFailure;
+    }
+    if (failure || !result) {
+        return {
+            ok: false,
+            command: commandText,
+            exitCode: null,
+            stdout: "",
+            stderr: failure instanceof Error ? failure.message : String(failure ?? "verification command did not return a result"),
+        };
+    }
+    return result;
+}
+function verificationMatrixPath(harness) {
+    const governanceRoot = typeof harness.governanceRoot === "string"
+        ? harness.governanceRoot
+        : "ai_workspace/loop-agent";
+    return typeof harness.entrypoints?.verificationMatrix === "string"
+        ? harness.entrypoints.verificationMatrix
+        : `${governanceRoot}/verification-matrix.md`;
+}
+async function readVerificationHarness(repoRoot) {
+    const parsed = JSON.parse(await readFile(path.join(repoRoot, "harness.json"), "utf-8"));
+    if (!isRecord(parsed)) {
+        throw new Error("verification authority harness.json must contain a JSON object");
+    }
+    return parsed;
+}
+async function discoverQuickVerification(repoRoot) {
+    const harness = await readVerificationHarness(repoRoot);
+    const matrixPath = verificationMatrixPath(harness);
+    await assertSafeMergePath(repoRoot, matrixPath);
+    const matrix = await readFile(path.join(repoRoot, matrixPath), "utf-8");
+    const targetTests = matrix.match(/^\|\s*target project tests are valid\s*\|\s*`([^`]+)`/im)?.[1];
+    if (!targetTests) {
+        throw new Error(`target verification matrix does not declare a concrete minimum project test command: ${matrixPath}`);
+    }
+    return targetTests.trim();
+}
+async function verifyRecoveryFiles(repoRoot) {
+    const verification = {};
+    for (const relativePath of RECOVERY_PATHS) {
+        const present = await exists(path.join(repoRoot, relativePath));
+        let invariant = present;
+        if (present && relativePath !== PI_PROJECT_SETTINGS_PATH) {
+            try {
+                const content = await readFile(path.join(repoRoot, relativePath), "utf-8");
+                if (relativePath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH) {
+                    invariant =
+                        content.includes(`MAX_RETRIES = ${MAX_SESSION_RETRIES}`) &&
+                            content.includes("plugin-ignore-permanent-error") &&
+                            content.includes("recoveryWorkers");
+                }
+                else if (relativePath === OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH) {
+                    invariant =
+                        content.includes(`MAX_OVERFLOW_RECOVERIES = ${MAX_OVERFLOW_RECOVERIES}`) &&
+                            content.includes("compactOrSummarize") &&
+                            content.includes("recoveryWorkers");
+                }
+                else {
+                    invariant =
+                        content.includes("message_end") &&
+                            content.includes("context_length_exceeded:");
+                }
+            }
+            catch {
+                invariant = false;
+            }
+        }
+        verification[relativePath] = { exists: present, invariant };
+    }
+    return verification;
+}
+async function runFinalVerification(state, authoritativeHomeFingerprint, surface) {
+    await assertFrozenVerificationSurface(state.repoRoot, surface);
+    const finalCheck = await checkInitUpdate({ repoRoot: state.repoRoot });
+    const doctor = await runInitDoctor({ repoRoot: state.repoRoot });
+    let inspect;
+    try {
+        const adapter = await resolveAdapter(state.repoRoot);
+        const manifest = await adapter.loadHarnessManifest(state.repoRoot);
+        inspect = {
+            ok: true,
+            command: "loop-agent inspect --repo-root .",
+            adapter: adapter.name,
+            project: manifest.project,
+        };
+    }
+    catch (error) {
+        inspect = {
+            ok: false,
+            command: "loop-agent inspect --repo-root .",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    let docsAudit;
+    try {
+        const audit = await auditDocs(state.repoRoot);
+        docsAudit = {
+            ok: audit.summary.errorCount === 0,
+            command: "loop-agent docs audit --repo-root .",
+            errorCount: audit.summary.errorCount,
+            warningCount: audit.summary.warningCount,
+        };
+    }
+    catch (error) {
+        docsAudit = {
+            ok: false,
+            command: "loop-agent docs audit --repo-root .",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const checkRepo = await runVerificationCommand({
+        state,
+        surface,
+        commandText: "bash scripts/check-repo.sh",
+    });
+    let quickVerification;
+    try {
+        const quickCommand = await discoverQuickVerification(state.repoRoot);
+        quickVerification = await runVerificationCommand({
+            state,
+            surface,
+            commandText: quickCommand,
+        });
+    }
+    catch (error) {
+        quickVerification = {
+            ok: false,
+            command: "verification-matrix minimum project test command",
+            exitCode: null,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const recovery = await verifyRecoveryFiles(state.repoRoot);
+    const projectPi = await inspectProjectPiSettings({ repoRoot: state.repoRoot });
+    const homeAfter = await homeFingerprint();
+    return {
+        completion: {
+            schemaVersion: 1,
+            runId: state.runId,
+            repoRoot: state.repoRoot,
+            status: "completed",
+            phase: "COMPLETED",
+            controllerIdentity: state.controllerIdentity,
+            actionReceiptCount: state.actionReceipts.length,
+            mergeReceiptCount: state.mergeReceipts.length,
+        },
+        initSurfaceClean: finalCheck.ok,
+        doctor: { ok: doctor.ok, checks: doctor.checks },
+        inspect,
+        docsAudit,
+        checkRepo,
+        quickVerification,
+        recovery,
+        projectPi: {
+            reason: projectPi.reason,
+            action: projectPi.action,
+            trustRequired: true,
+            valid: projectPi.reason === "matches" ||
+                projectPi.reason === "enabled-false",
+        },
+        userHomeUnchanged: sameJsonValue(homeAfter, authoritativeHomeFingerprint),
+        mergeBoundaryClean: state.mergeTasks.length === 0,
+        humanDecisionClean: state.humanDecisions.length === 0,
+    };
+}
+function authoritativeVerificationFailureReason(verification) {
+    const sources = [
+        verification.quickVerification,
+        verification.checkRepo,
+        verification.inspect,
+        verification.docsAudit,
+    ];
+    for (const source of sources) {
+        if (!isRecord(source))
+            continue;
+        const candidates = [
+            typeof source.error === "string" ? source.error : undefined,
+            source.exitCode === null && typeof source.stderr === "string"
+                ? source.stderr
+                : undefined,
+        ];
+        for (const value of candidates) {
+            if (!value)
+                continue;
+            for (const line of value.split(/\r?\n/)) {
+                const reason = line.trim();
+                if (reason.length <= 500 &&
+                    (reason ===
+                        "verification authority harness.json merge cannot change controller executor or workflow authority" ||
+                        reason ===
+                            "verification authority rejects direct node code evaluation" ||
+                        reason ===
+                            "verification authority rejects package command code evaluation" ||
+                        /^verification authority (?:surface changed|input is not a regular file): [A-Za-z0-9_./-]+$/.test(reason) ||
+                        reason ===
+                            "verification authority merge must retain the controller-frozen verification matrix path")) {
+                    return reason;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function verificationPassed(verification) {
+    const doctor = verification.doctor;
+    const inspect = verification.inspect;
+    const docsAudit = verification.docsAudit;
+    const checkRepo = verification.checkRepo;
+    const quick = verification.quickVerification;
+    const projectPi = verification.projectPi;
+    const recovery = verification.recovery;
+    return (verification.initSurfaceClean === true &&
+        isRecord(doctor) &&
+        doctor.ok === true &&
+        isRecord(inspect) &&
+        inspect.ok === true &&
+        isRecord(docsAudit) &&
+        docsAudit.ok === true &&
+        isRecord(checkRepo) &&
+        checkRepo.ok === true &&
+        isRecord(quick) &&
+        quick.ok === true &&
+        isRecord(projectPi) &&
+        projectPi.valid === true &&
+        isRecord(recovery) &&
+        RECOVERY_PATHS.every((recoveryPath) => {
+            const entry = recovery[recoveryPath];
+            return isRecord(entry) && entry.exists === true && entry.invariant === true;
+        }) &&
+        verification.userHomeUnchanged === true &&
+        verification.mergeBoundaryClean === true &&
+        verification.humanDecisionClean === true);
+}
+function assertCompletedVerification(state, verification) {
+    if (!isRecord(verification) || !isRecord(verification.completion)) {
+        throw new Error("completed init upgrade verification evidence is invalid");
+    }
+    const completion = verification.completion;
+    if (completion.schemaVersion !== 1 ||
+        completion.runId !== state.runId ||
+        completion.repoRoot !== state.repoRoot ||
+        completion.status !== "completed" ||
+        completion.phase !== "COMPLETED" ||
+        !isControllerIdentity(completion.controllerIdentity) ||
+        !sameControllerIdentity(completion.controllerIdentity, state.controllerIdentity) ||
+        completion.actionReceiptCount !== state.actionReceipts.length ||
+        completion.mergeReceiptCount !== state.mergeReceipts.length ||
+        !verificationPassed(verification)) {
+        throw new Error("completed init upgrade verification evidence is inconsistent");
+    }
+}
+function assertAnchorCompletion(anchor, state) {
+    const completion = anchor.completion;
+    if (!completion ||
+        !sameJsonValue(anchor.homeFingerprint, state.homeFingerprint) ||
+        completion.status !== "completed" ||
+        completion.phase !== "COMPLETED" ||
+        completion.actionReceiptCount !== state.actionReceipts.length ||
+        completion.mergeReceiptCount !== state.mergeReceipts.length ||
+        !isSha256(completion.actionReceiptsSha256) ||
+        !isSha256(completion.mergeReceiptsSha256) ||
+        !isSha256(completion.stateProjectionSha256) ||
+        !isSha256(completion.finalReportSha256) ||
+        !isFrozenVerificationSurface(completion.verificationSurface) ||
+        completion.actionReceiptsSha256 !== sha256(serializeJson(state.actionReceipts)) ||
+        completion.mergeReceiptsSha256 !== sha256(serializeJson(state.mergeReceipts)) ||
+        completion.stateProjectionSha256 !== canonicalSha256(controllerStateProjection(state))) {
+        throw new Error("completed init upgrade state is not authorized by the controller anchor");
+    }
+}
+async function readFreshCompletedVerification(repoRoot, state) {
+    const anchor = await readControllerAnchor(repoRoot, state);
+    assertAnchorCompletion(anchor, state);
+    const report = await readFile(path.join(runDirectory(repoRoot, state.runId), "final-report.md")).catch(() => {
+        throw new Error("completed init upgrade report is missing or unreadable");
+    });
+    if (sha256(report) !== anchor.completion?.finalReportSha256) {
+        throw new Error("completed init upgrade report is not authorized by the controller anchor");
+    }
+    if (!anchor.completion?.verificationSurface) {
+        throw new Error("completed verification surface authority is missing");
+    }
+    const verification = await runFinalVerification(state, anchor.homeFingerprint, anchor.completion.verificationSurface);
+    assertCompletedVerification(state, verification);
+    return { verification, reportMarkdown: report.toString("utf-8") };
+}
+async function readValidatedStatusState(repoRoot, runId) {
+    const state = await readState(repoRoot, runId);
+    assertTerminalCoherence(state);
+    const directory = runDirectory(repoRoot, runId);
+    const anchor = await readControllerAnchor(repoRoot, state);
+    if (anchor.mergeAuthority) {
+        mergeAuthorityProjection(state, mergeAuthorityFromAnchor(anchor, state));
+    }
+    if (state.status === "completed" || state.status === "cancelled") {
+        if (!(await frozenControllerMatches(directory, state))) {
+            throw new Error("Controller identity drift detected for persisted init upgrade state");
+        }
+    }
+    return { state, directory, anchor };
+}
+/**
+ * Read-only projection of the controller-owned gitignore migration assessment
+ * for status/report reads. The artifact is written by executeUpgrade after the
+ * managed block has converged; a missing artifact is tolerated only while the
+ * run has not yet reached that write point (DISCOVER/VERSION_GATE). Every
+ * other missing, malformed, or shape-invalid artifact fails closed so
+ * status/report never trust mutable or incomplete content (AC-005).
+ */
+async function readGitignoreMigrationProjection(directory, state, gitignoreMigrationSha256) {
+    const file = path.join(directory, "gitignore-migration.json");
+    let rawBytes;
+    let raw;
+    try {
+        rawBytes = await readFile(file);
+        raw = rawBytes.toString("utf-8");
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code === "ENOENT") {
+            if (state.phase === "DISCOVER" || state.phase === "VERSION_GATE") {
+                return undefined;
+            }
+            throw new Error(`init upgrade integrity error: gitignore migration artifact is missing for run ${state.runId} (phase ${state.phase}); refusing to trust an incomplete run`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact is malformed JSON for run ${state.runId} (${file})`);
+    }
+    if (!isGitignoreMigrationAssessment(parsed)) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact has an invalid shape for run ${state.runId} (${file})`);
+    }
+    // The artifact exists, so this run has generated an assessment; the
+    // controller authority binding must exist, be a legal SHA-256, and match
+    // the raw artifact bytes on disk (fail closed otherwise).
+    if (gitignoreMigrationSha256 === undefined || !isSha256(gitignoreMigrationSha256)) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact digest binding is missing or invalid for run ${state.runId}`);
+    }
+    if (sha256(rawBytes) !== gitignoreMigrationSha256) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact digest does not match the controller authority binding for run ${state.runId}`);
+    }
+    return parsed;
+}
+async function readStatusResult(repoRoot, runId) {
+    const { state, directory, anchor } = await readValidatedStatusState(repoRoot, runId);
+    if (state.status !== "completed") {
+        return toResult(state, undefined, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256));
+    }
+    const authenticated = await readFreshCompletedVerification(repoRoot, state);
+    return toResult(state, authenticated.verification, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256));
+}
+async function executeUpgrade(directory, state, input) {
+    const identity = await readIdentity();
+    if (!sameControllerIdentity(identity, state.controllerIdentity)) {
+        return {
+            ...toResult(state),
+            status: "failed",
+            nextAction: "Controller identity drift detected. Re-run with the frozen controller; no target-project writes were made.",
+        };
+    }
+    const recordedCurrentChoice = input.mode === "continue" &&
+        input.versionChoice === undefined &&
+        state.versionGate.choice === "current"
+        ? "current"
+        : undefined;
+    if (!recordedCurrentChoice)
+        state.phase = "VERSION_GATE";
+    state.versionGate = await currentVersionGate(input, identity);
+    const choice = input.versionChoice ?? recordedCurrentChoice;
+    if (state.versionGate.outcome === "newer-available" && !choice) {
+        state.status = "needs-human-decision";
+        state.nextAction =
+            "Choose --version-choice current, upgrade, or cancel; the controller identity remains frozen until a choice is recorded.";
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    if (state.versionGate.outcome === "registry-unavailable" && !choice) {
+        state.status = "needs-human-decision";
+        state.nextAction =
+            "npm registry is unavailable. Choose --version-choice current, retry, or cancel.";
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    state.versionGate.choice = choice ?? "current";
+    if (choice === "cancel") {
+        state.status = "cancelled";
+        state.nextAction = "Upgrade cancelled before init-surface mutation.";
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    if (choice === "upgrade") {
+        if (state.versionGate.outcome !== "newer-available") {
+            state.status = "needs-human-decision";
+            state.nextAction =
+                "No newer controller was confirmed. Choose current, retry the registry, or cancel.";
+        }
+        else {
+            state.status = "cancelled";
+            state.nextAction = `This frozen run is closed before mutation. Install and verify @tea-agent/loop-agent@${state.versionGate.latestVersion}, then start a new run without --run-id so the new controller freezes a new identity.`;
+        }
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    if (choice === "retry" &&
+        state.versionGate.outcome === "registry-unavailable") {
+        state.status = "needs-human-decision";
+        state.nextAction =
+            "npm registry remains unavailable after retry. Choose --version-choice current, retry, or cancel.";
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    state.status = "in-progress";
+    state.phase = "PLAN";
+    const pre = await checkInitUpdate({ repoRoot: state.repoRoot });
+    await writeJsonAtomic(path.join(directory, "pre-update-report.json"), pre);
+    await writeJsonAtomic(path.join(directory, "upgrade-plan.json"), {
+        deterministicActions: pre.deterministicActions,
+        modelMergeTasks: pre.modelMergeTasks,
+        humanDecisions: pre.humanDecisions,
+        verificationPlan: [
+            "init check-update",
+            "init doctor",
+            "loop-agent inspect",
+            "loop-agent docs audit",
+            "bash scripts/check-repo.sh",
+            "verification-matrix minimum project test command",
+            "project recovery invariants",
+            "Pi home fingerprint",
+        ],
+    });
+    state.phase = "APPLY_SAFE";
+    await assertInactive(input);
+    if (pre.surfaceState === "missing") {
+        const initialized = await initializeLoopAgentProject({
+            repoRoot: state.repoRoot,
+            profile: "full",
+            merge: true,
+            clientRecovery: "project",
+        });
+        state.actionReceipts.push(...initialized.written.map((writtenPath) => ({
+            type: writtenPath === INIT_SURFACE_STATE_PATH
+                ? "bootstrap-surface"
+                : "write-generated-missing",
+            path: writtenPath,
+            reason: writtenPath === INIT_SURFACE_STATE_PATH
+                ? "recorded the complete fresh-project initialization surface"
+                : "full-project initialization wrote the required project surface",
+        })));
+    }
+    await assertInactive(input);
+    const safe = await applyInitUpdate({
+        repoRoot: state.repoRoot,
+        applySafe: true,
+        clientRecovery: "project",
+    });
+    state.actionReceipts.push(...safe.applied);
+    await writeJsonAtomic(path.join(directory, "change-manifest.json"), state.actionReceipts);
+    let post = await checkInitUpdate({ repoRoot: state.repoRoot });
+    // Converge remaining safe deterministic init actions before the final check.
+    // Project/governance-derived drift (e.g. a personalized project rename after
+    // an accepted merge) settles here instead of failing finalCheck. Model merge
+    // tasks and human decisions are never auto-applied.
+    while (post.deterministicActions.length > 0) {
+        const converged = await applyInitUpdate({
+            repoRoot: state.repoRoot,
+            applySafe: true,
+            clientRecovery: "project",
+        });
+        state.actionReceipts.push(...converged.applied);
+        await writeJsonAtomic(path.join(directory, "change-manifest.json"), state.actionReceipts);
+        if (converged.applied.length === 0)
+            break;
+        post = await checkInitUpdate({ repoRoot: state.repoRoot });
+        if (post.humanDecisions.length > 0 ||
+            post.modelMergeTasks.length > 0) {
+            break;
+        }
+    }
+    state.humanDecisions = post.humanDecisions;
+    // Gitignore migration assessment: after the managed block has converged,
+    // inventory tracked .harness/.agents paths with read-only git queries and
+    // recommend index-only untrack commands. The controller never mutates the
+    // user Git index; suggested commands only change the index and keep the
+    // working tree intact.
+    const gitignoreMigration = await assessGitignoreMigration(state.repoRoot, {
+        managedBlockRefreshed: !post.deterministicActions.some((action) => action.type === "refresh-managed-block" &&
+            action.path === ".gitignore"),
+    });
+    await writeJsonAtomic(path.join(directory, "gitignore-migration.json"), gitignoreMigration);
+    // Bind the raw on-disk artifact bytes to the Git-dir controller authority
+    // before any needs-human-decision/model-merge/completed return; later
+    // mergeAuthority/completion anchor writes preserve this binding.
+    await writeControllerAnchor({
+        state,
+        gitignoreMigrationSha256: sha256(await readFile(path.join(directory, "gitignore-migration.json"))),
+    });
+    if (gitignoreMigration.status === "blocked" ||
+        gitignoreMigration.needsAgentsReview) {
+        // Route through the existing needs-human-decision pause: `.agents`
+        // tracked content must be reviewed (PRD §7) and staged blockers must be
+        // resolved before safe untrack guidance can be given (PRD §8).
+        post.humanDecisions.push(gitignoreMigration.status === "blocked"
+            ? {
+                path: ".harness/** (gitignore migration)",
+                reason: "staged changes or a failed git query block safe untrack guidance; resolve the blocker, then rerun the migration assessment",
+            }
+            : {
+                path: ".agents/** (gitignore migration)",
+                reason: "tracked .agents content may include team-shareable customizations; review before running the suggested untrack commands",
+            });
+    }
+    state.humanDecisions = post.humanDecisions;
+    if (post.humanDecisions.length > 0) {
+        state.mergeTasks = [];
+        state.mergeGuard = undefined;
+        state.status = "needs-human-decision";
+        state.phase = "MODEL_MERGE";
+        state.nextAction =
+            "Resolve the recorded destructive, credential, or ambiguous decisions; the controller will not overwrite uncertain user intent. For gitignore migration: review tracked .agents customizations or resolve the staged blocker first, then rerun the assessment so index-only untrack commands can be recommended.";
+        await writeJsonAtomic(path.join(directory, "merge-tasks.json"), state.mergeTasks);
+        await saveState(directory, state);
+        await writeReport(directory, state, undefined, gitignoreMigration);
+        return toResult(state, undefined, gitignoreMigration);
+    }
+    if (post.modelMergeTasks.length > 0) {
+        const activeTask = post.modelMergeTasks[0];
+        const verificationSurface = await freezeVerificationSurface(state.repoRoot);
+        assertTaskOutsideVerificationSurface(activeTask, verificationSurface);
+        if (verificationSurface.files.some((entry) => entry.path === normalizeAllowedPath(activeTask.path))) {
+            await validateControllerAuthorizedVerificationMerge({
+                repoRoot: state.repoRoot,
+                task: activeTask,
+                surface: verificationSurface,
+            });
+        }
+        state.mergeTasks = [activeTask];
+        state.mergeGuard = await createMergeGuard(state.repoRoot, activeTask);
+        // Bind the Git-dir anchor to the state actually handed to the model.
+        state.phase = "MODEL_MERGE";
+        state.status = "in-progress";
+        await writeControllerAnchor({
+            state,
+            mergeAuthority: {
+                ...state.mergeGuard,
+                priorMergeReceiptCount: state.mergeReceipts.length,
+                priorMergeReceiptsSha256: sha256(serializeJson(state.mergeReceipts)),
+                stateProjection: controllerStateProjection(state),
+                stateProjectionSha256: canonicalSha256(controllerStateProjection(state)),
+                verificationSurface,
+            },
+        });
+        state.nextAction = `Complete only task ${activeTask.taskId} within allowedPaths=[${activeTask.allowedPaths.join(", ")}], then call init upgrade --continue. The controller will reject every other workspace change and all symlink/realpath escapes.`;
+        await writeJsonAtomic(path.join(directory, "merge-tasks.json"), state.mergeTasks);
+        await saveState(directory, state);
+        await writeReport(directory, state, undefined, gitignoreMigration);
+        return toResult(state, undefined, gitignoreMigration);
+    }
+    state.mergeTasks = [];
+    state.mergeGuard = undefined;
+    state.humanDecisions = [];
+    state.phase = "VERIFY";
+    const anchor = await readControllerAnchor(state.repoRoot, state);
+    const verificationSurface = await freezeVerificationSurface(state.repoRoot);
+    const verification = await runFinalVerification(state, anchor.homeFingerprint, verificationSurface);
+    await writeJsonAtomic(path.join(directory, "verification.json"), verification);
+    if (verificationPassed(verification)) {
+        state.status = "completed";
+        state.phase = "COMPLETED";
+        state.nextAction =
+            "Init upgrade completed; reload the host session so updated AGENTS, skills, and recovery extensions are discovered.";
+        // The report is controller-produced before its exact bytes are anchored.
+        await writeReport(directory, state, verification, gitignoreMigration);
+        const finalReportSha256 = sha256(await readFile(path.join(directory, "final-report.md")));
+        await writeControllerAnchor({
+            state,
+            completion: {
+                status: "completed",
+                phase: "COMPLETED",
+                actionReceiptCount: state.actionReceipts.length,
+                mergeReceiptCount: state.mergeReceipts.length,
+                actionReceiptsSha256: sha256(serializeJson(state.actionReceipts)),
+                mergeReceiptsSha256: sha256(serializeJson(state.mergeReceipts)),
+                stateProjectionSha256: canonicalSha256(controllerStateProjection(state)),
+                verificationSurface,
+                finalReportSha256,
+            },
+        });
+    }
+    else {
+        state.status = "failed";
+        const authorityReason = authoritativeVerificationFailureReason(verification);
+        state.nextAction = authorityReason
+            ? `Verification failed: ${authorityReason}. Inspect verification.json, repair only the controller-returned concrete merge path, then use --continue.`
+            : "Verification failed. Inspect verification.json; repair only the controller-returned concrete merge path or address the reported external blocker, then use --continue.";
+    }
+    await saveState(directory, state);
+    await writeReport(directory, state, verification, gitignoreMigration);
+    return toResult(state, verification, gitignoreMigration);
+}
+export async function runInitUpgrade(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const mode = input.mode ?? "start";
+    if ((mode === "status" || mode === "report") && !input.runId) {
+        throw new Error("init upgrade --status/--report requires --run-id");
+    }
+    if (mode === "status")
+        return await readStatusResult(repoRoot, input.runId);
+    if (mode === "report") {
+        const { state, directory, anchor } = await readValidatedStatusState(repoRoot, input.runId);
+        if (state.status === "completed") {
+            const authenticated = await readFreshCompletedVerification(repoRoot, state);
+            // Completed report bytes are anchored by finalReportSha256; still
+            // verify the gitignore migration artifact binding so shape-valid
+            // tampering fails closed here as well.
+            await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256);
+            return { markdown: authenticated.reportMarkdown };
+        }
+        // Non-completed reports are projections of the validated state, never an
+        // unauthenticated read of a mutable run-local report file.
+        return {
+            markdown: renderReport(state, undefined, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256)),
+        };
+    }
+    const runId = mode === "continue"
+        ? input.runId
+        : input.runId ??
+            `init-upgrade-${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${randomUUID().slice(0, 8)}`;
+    if (!runId)
+        throw new Error("init upgrade --continue requires --run-id");
+    if (!validRunId(runId))
+        throw new Error("invalid init upgrade run id");
+    if (mode === "continue") {
+        const persisted = await readState(repoRoot, runId);
+        try {
+            assertTerminalCoherence(persisted);
+            const anchor = await readControllerAnchor(repoRoot, persisted);
+            if (anchor.mergeAuthority) {
+                mergeAuthorityProjection(persisted, mergeAuthorityFromAnchor(anchor, persisted));
+            }
+            const directory = runDirectory(repoRoot, runId);
+            if (persisted.status === "completed" || persisted.status === "cancelled") {
+                if (!(await frozenControllerMatches(directory, persisted))) {
+                    throw new Error("Controller identity drift detected for persisted init upgrade state");
+                }
+                if (persisted.status !== "completed")
+                    return toResult(persisted);
+                const authenticated = await readFreshCompletedVerification(repoRoot, persisted);
+                return toResult(persisted, authenticated.verification);
+            }
+        }
+        catch (error) {
+            return {
+                ...toResult(persisted),
+                status: "failed",
+                nextAction: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    await assertInactive({ ...input, repoRoot });
+    if (mode === "start") {
+        await controllerAnchorPath({ repoRoot, runId });
+    }
+    const release = await acquireGlobalLock({ repoRoot, runId });
+    let directory = runDirectory(repoRoot, runId);
+    let state;
+    try {
+        await assertInactive({ ...input, repoRoot });
+        if (mode === "continue") {
+            state = await readState(repoRoot, runId);
+            directory = runDirectory(repoRoot, runId);
+            const recoverableMergeState = state.phase === "MODEL_MERGE" && state.status === "in-progress"
+                ? cloneJson(state)
+                : undefined;
+            let mergeOutcome;
+            try {
+                const anchor = await readControllerAnchor(repoRoot, state);
+                mergeOutcome = await validateContinueMerge(directory, state, anchor);
+            }
+            catch (error) {
+                if (!recoverableMergeState)
+                    throw error;
+                return {
+                    ...toResult(recoverableMergeState),
+                    status: "failed",
+                    nextAction: error instanceof Error ? error.message : String(error),
+                };
+            }
+            if (mergeOutcome === "no-change")
+                return toResult(state);
+            if (state.phase !== "MODEL_MERGE") {
+                await rm(path.join(directory, "merge-acceptance-pending.json"), {
+                    force: true,
+                });
+            }
+        }
+        else {
+            directory = runDirectory(repoRoot, runId);
+            await mkdir(directory, { recursive: false });
+            const identity = await readIdentity();
+            const now = new Date().toISOString();
+            state = {
+                schemaVersion: 1,
+                runId,
+                repoRoot,
+                phase: "DISCOVER",
+                status: "in-progress",
+                createdAt: now,
+                updatedAt: now,
+                controllerIdentity: identity,
+                versionGate: { outcome: "latest" },
+                nextAction: "Evaluate controller version and init surface.",
+                mergeTasks: [],
+                mergeReceipts: [],
+                humanDecisions: [],
+                actionReceipts: [],
+                homeFingerprint: await homeFingerprint(),
+            };
+            await writeControllerAnchor({ state, initialize: true });
+            await writeJsonAtomic(path.join(directory, "controller-identity.json"), {
+                schemaVersion: 1,
+                runId,
+                repoRoot,
+                controllerIdentity: identity,
+            });
+            await saveState(directory, state);
+        }
+        if (!state)
+            throw new Error("init upgrade state was not initialized");
+        return await executeUpgrade(directory, state, { ...input, repoRoot });
+    }
+    catch (error) {
+        if (error instanceof VerificationProcessBoundaryError)
+            throw error;
+        if (!state)
+            throw error;
+        const nextAction = error instanceof Error ? error.message : String(error);
+        state.status = "failed";
+        state.nextAction = nextAction;
+        await saveState(directory, state);
+        await writeReport(directory, state);
+        return toResult(state);
+    }
+    finally {
+        await release();
+    }
+}