@tea-agent/loop-agent 0.44.0-next.13 → 0.44.0-next.14

package/dist/commands/init-upgrade.js

@@ -5,15 +5,21 @@ import { lstat, mkdtemp, mkdir, readFile, readdir, readlink, realpath, rename, r
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import semver from "semver";
 import { resolveAdapter } from "../adapters/index.js";
 import { createNpmUpdateClient, } from "../shared/update/npm-client.js";
 import { auditDocs } from "../governance/checks.js";
 import { harnessManifestSchema } from "../governance/manifest-types.js";
+import { ProjectCapabilityScanner } from "../governance/project-capability-scanner.js";
+import { loadNormalizedProjectConfig } from "../governance/project-config.js";
+import { CONTROLLER_RESOURCE_IDS, createControllerContextProvider, } from "../governance/resource-catalog.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";
+import { applyInitUpdate, applyInitDecisionBoundActions, checkInitUpdate, initializeLoopAgentProject, runInitDoctor, } from "./init.js";
 const RUN_ROOT = ".harness/init-upgrades";
 const GLOBAL_LOCK_NAME = ".writer-lock";
+const PENDING_DECISION_FILE = "decision-application-pending.json";
+const DECISION_REPLACE_REASON = "replace an explicitly approved legacy loop-agent Skill with the minimal external Agent bridge";
 const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const RECOVERY_PATHS = [
     OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
@@ -27,6 +33,80 @@ function sha256(value) {
 function validRunId(runId) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runId);
 }
+async function readRepoLocalDecisionFile(repoRoot, decisionFile) {
+    const absolutePath = path.resolve(repoRoot, decisionFile);
+    const relativePath = path.relative(repoRoot, absolutePath);
+    if (relativePath.length === 0 ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        throw new Error("init upgrade --decision-file must resolve inside repoRoot");
+    }
+    const info = await lstat(absolutePath).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw new Error("init upgrade --decision-file must be a regular non-symlink file");
+    }
+    return await readFile(absolutePath);
+}
+async function readInitUpgradeDecisionFile(input) {
+    const raw = await readRepoLocalDecisionFile(input.repoRoot, input.decisionFile);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf-8"));
+    }
+    catch {
+        throw new Error("init upgrade --decision-file is not valid JSON");
+    }
+    if (!isRecord(parsed) ||
+        parsed.schemaVersion !== 1 ||
+        parsed.runId !== input.runId ||
+        !Array.isArray(parsed.decisions)) {
+        throw new Error("init upgrade --decision-file has an invalid schema or runId binding");
+    }
+    const decisions = [];
+    const decisionPaths = new Set();
+    const pendingByPath = new Map(input.pending.map((decision) => [decision.path, decision]));
+    for (const value of parsed.decisions) {
+        const pending = isRecord(value) && typeof value.path === "string"
+            ? pendingByPath.get(value.path)
+            : undefined;
+        const legacyDisposition = isRecord(value) &&
+            (value.disposition === "retain-project-content" ||
+                value.disposition === "preserve-unproven" ||
+                value.disposition === "delete-listed-file");
+        if (!isRecord(value) ||
+            typeof value.path !== "string" ||
+            (value.disposition !== "detach-as-project-content" &&
+                value.disposition !== "replace-with-bridge" &&
+                !legacyDisposition) ||
+            !isSha256(value.expectedSha256) ||
+            decisionPaths.has(value.path) ||
+            !pending ||
+            (Boolean(pending.candidateId) !== legacyDisposition) ||
+            (Boolean(pending.candidateId) &&
+                (value.candidateId !== pending.candidateId ||
+                    value.expectedSha256 !== pending.expectedSha256))) {
+            throw new Error("init upgrade --decision-file contains an invalid or duplicate decision");
+        }
+        decisionPaths.add(value.path);
+        decisions.push({
+            path: value.path,
+            disposition: value.disposition,
+            expectedSha256: value.expectedSha256,
+            ...(typeof value.candidateId === "string"
+                ? { candidateId: value.candidateId }
+                : {}),
+        });
+    }
+    const pendingPaths = new Set(input.pending.map((decision) => decision.path));
+    if (decisionPaths.size !== pendingPaths.size ||
+        [...pendingPaths].some((pendingPath) => !decisionPaths.has(pendingPath))) {
+        throw new Error("init upgrade --decision-file must resolve every current human decision exactly once");
+    }
+    return {
+        document: { schemaVersion: 1, runId: input.runId, decisions },
+        sha256: sha256(raw),
+    };
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -129,8 +209,12 @@ function controllerStateProjection(state) {
         queuedMergeTasks: cloneJson(state.queuedMergeTasks),
         ...(state.mergeGuard ? { mergeGuard: cloneJson(state.mergeGuard) } : {}),
         mergeReceipts: cloneJson(state.mergeReceipts),
+        decisionReceipts: cloneJson(state.decisionReceipts ?? []),
         humanDecisions: cloneJson(state.humanDecisions),
         actionReceipts: cloneJson(state.actionReceipts),
+        coreState: state.coreState,
+        migrationState: state.migrationState,
+        ...(state.legacyAudit ? { legacyAudit: cloneJson(state.legacyAudit) } : {}),
     };
 }
 function sameJsonValue(left, right) {
@@ -149,6 +233,88 @@ function sameJsonValue(left, right) {
     return (leftKeys.length === rightKeys.length &&
         leftKeys.every((key, index) => key === rightKeys[index] && sameJsonValue(left[key], right[key])));
 }
+function isDecisionAction(value) {
+    return (isRecord(value) &&
+        typeof value.path === "string" &&
+        (value.disposition === "detach-as-project-content" ||
+            value.disposition === "replace-with-bridge" ||
+            value.disposition === "retain-project-content" ||
+            value.disposition === "preserve-unproven" ||
+            value.disposition === "delete-listed-file") &&
+        isSha256(value.expectedSha256) &&
+        (value.candidateId === undefined || typeof value.candidateId === "string"));
+}
+function assertPendingDecisionAuthority(authority, state) {
+    if (!authority)
+        return undefined;
+    const pending = authority.pending;
+    if (!isRecord(pending) ||
+        pending.schemaVersion !== 1 ||
+        pending.runId !== state.runId ||
+        pending.repoRoot !== state.repoRoot ||
+        !isSha256(pending.decisionFileSha256) ||
+        !isRecord(pending.document) ||
+        pending.document.schemaVersion !== 1 ||
+        pending.document.runId !== state.runId ||
+        !Array.isArray(pending.document.decisions) ||
+        pending.document.decisions.length === 0 ||
+        !pending.document.decisions.every(isDecisionAction) ||
+        !isRecord(pending.stateProjection) ||
+        !isSha256(pending.stateProjectionSha256) ||
+        canonicalSha256(pending.stateProjection) !== pending.stateProjectionSha256 ||
+        typeof pending.preparedAt !== "string" ||
+        !isSha256(authority.pendingSha256) ||
+        canonicalSha256(pending) !== authority.pendingSha256) {
+        throw new Error("pending init decision authority is invalid");
+    }
+    const pre = pending.stateProjection;
+    const current = controllerStateProjection(state);
+    if (sameJsonValue(current, pre))
+        return pending;
+    const priorDecisionReceipts = pre.decisionReceipts ?? [];
+    const currentDecisionReceipts = current.decisionReceipts ?? [];
+    const appended = currentDecisionReceipts.slice(priorDecisionReceipts.length);
+    if (currentDecisionReceipts.length !==
+        priorDecisionReceipts.length + pending.document.decisions.length ||
+        !sameJsonValue(currentDecisionReceipts.slice(0, priorDecisionReceipts.length), priorDecisionReceipts) ||
+        appended.some((receipt, index) => {
+            const decision = pending.document.decisions[index];
+            return (!decision ||
+                receipt.path !== decision.path ||
+                receipt.disposition !== decision.disposition ||
+                receipt.expectedSha256 !== decision.expectedSha256 ||
+                receipt.candidateId !== decision.candidateId ||
+                receipt.decisionFileSha256 !== pending.decisionFileSha256 ||
+                !isSha256(receipt.resultSha256) ||
+                typeof receipt.decidedAt !== "string");
+        })) {
+        throw new Error("pending init decision receipt projection is inconsistent");
+    }
+    const expectedPost = cloneJson(pre);
+    expectedPost.status = "in-progress";
+    expectedPost.humanDecisions = [];
+    expectedPost.decisionReceipts = cloneJson(currentDecisionReceipts);
+    expectedPost.actionReceipts = [
+        ...cloneJson(pre.actionReceipts),
+        ...pending.document.decisions
+            .filter((decision) => decision.disposition === "replace-with-bridge" ||
+            decision.disposition === "delete-listed-file")
+            .map((decision) => ({
+            type: decision.disposition === "replace-with-bridge"
+                ? "replace-owned-file"
+                : "remove-owned-file",
+            path: decision.path,
+            expectedSha256: decision.expectedSha256,
+            reason: decision.disposition === "replace-with-bridge"
+                ? DECISION_REPLACE_REASON
+                : "remove an explicitly approved hash-bound legacy init file",
+        })),
+    ];
+    if (!sameJsonValue(current, expectedPost)) {
+        throw new Error("pending init decision state differs from controller authority");
+    }
+    return pending;
+}
 function isControllerIdentity(value) {
     if (!isRecord(value))
         return false;
@@ -205,8 +371,14 @@ function assertStateShape(state, repoRoot, runId) {
         !Array.isArray(candidate.mergeTasks) ||
         !Array.isArray(candidate.queuedMergeTasks) ||
         !Array.isArray(candidate.mergeReceipts) ||
+        (candidate.decisionReceipts !== undefined &&
+            !Array.isArray(candidate.decisionReceipts)) ||
         !Array.isArray(candidate.humanDecisions) ||
         !Array.isArray(candidate.actionReceipts) ||
+        (candidate.coreState !== "ready" &&
+            candidate.coreState !== "blocked" &&
+            candidate.coreState !== "error") ||
+        !["clean", "retained", "review-required", "in-progress", "failed"].includes(candidate.migrationState) ||
         !isHomeFingerprint(candidate.homeFingerprint) ||
         (candidate.modelCatalog !== undefined &&
             (!isRecord(candidate.modelCatalog) ||
@@ -257,6 +429,9 @@ function runGitQuery(cwd, args) {
 function splitNulPaths(output) {
     return output.split("\0").filter((entry) => entry.length > 0);
 }
+function quoteGitPath(pathName) {
+    return `'${pathName.replaceAll("'", `'"'"'`)}'`;
+}
 /**
  * Gitignore migration assessment (PRD 2026-08-13): inventories tracked
  * `.harness/**` / `.agents/**` with read-only git queries after the managed
@@ -273,7 +448,8 @@ export async function assessGitignoreMigration(repoRoot, input) {
         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",
+            "confirm the listed .harness files still exist locally after index-only untracking",
+            "keep every tracked .agents path at its existing tracking intent; the bridge remains shared",
             "run `loop-agent init doctor` to re-check the gitignore loop-agent block",
         ],
     };
@@ -329,7 +505,7 @@ export async function assessGitignoreMigration(repoRoot, input) {
     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;
+    const needsAgentsReview = false;
     if (stagedRisk.length > 0) {
         // Fail closed: staged entries make any untrack advice ambiguous.
         return {
@@ -344,16 +520,10 @@ export async function assessGitignoreMigration(repoRoot, input) {
         };
     }
     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) {
+    for (const trackedPath of harnessTracked) {
         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",
+            command: `git rm --cached --ignore-unmatch -- ${quoteGitPath(trackedPath)}`,
+            note: `untracks only ${trackedPath}; the working-tree file is kept`,
         });
     }
     return {
@@ -364,9 +534,7 @@ export async function assessGitignoreMigration(repoRoot, input) {
         stagedRisk,
         needsAgentsReview,
         recommendedCommands,
-        status: harnessTracked.length > 0 || agentsTracked.length > 0
-            ? "recommended"
-            : "clean",
+        status: harnessTracked.length > 0 ? "recommended" : "clean",
     };
 }
 function runRoot(repoRoot) {
@@ -440,6 +608,7 @@ async function writeControllerAnchor(input) {
     let authoritativeHomeFingerprint;
     let authoritativeGitignoreMigrationSha256;
     let authoritativeModelCatalogSha256;
+    let authoritativeDecisionAuthority;
     if (input.initialize) {
         if (await exists(location.file)) {
             throw new Error("init upgrade controller authority anchor already exists");
@@ -449,8 +618,9 @@ async function writeControllerAnchor(input) {
         }
         authoritativeHomeFingerprint = cloneJson(input.state.homeFingerprint);
         authoritativeModelCatalogSha256 = input.state.modelCatalog
-            ? canonicalSha256(input.state.modelCatalog)
+            ? canonicalSha256(cloneJson(input.state.modelCatalog))
             : undefined;
+        authoritativeDecisionAuthority = undefined;
     }
     else {
         const current = await readControllerAnchor(location.repoRoot, input.state);
@@ -464,6 +634,10 @@ async function writeControllerAnchor(input) {
         }
         authoritativeGitignoreMigrationSha256 = digest;
         authoritativeModelCatalogSha256 = current.modelCatalogSha256;
+        authoritativeDecisionAuthority =
+            input.decisionAuthority === null
+                ? undefined
+                : input.decisionAuthority ?? current.decisionAuthority;
     }
     await writeJsonAtomic(location.file, {
         schemaVersion: 1,
@@ -478,6 +652,9 @@ async function writeControllerAnchor(input) {
             ? { gitignoreMigrationSha256: authoritativeGitignoreMigrationSha256 }
             : {}),
         ...(input.mergeAuthority ? { mergeAuthority: input.mergeAuthority } : {}),
+        ...(authoritativeDecisionAuthority
+            ? { decisionAuthority: authoritativeDecisionAuthority }
+            : {}),
         ...(input.completion ? { completion: input.completion } : {}),
     });
 }
@@ -499,7 +676,7 @@ async function readControllerAnchor(repoRoot, state) {
         throw new Error("init upgrade controller authority anchor binding is invalid");
     }
     const expectedModelCatalogSha256 = state.modelCatalog
-        ? canonicalSha256(state.modelCatalog)
+        ? canonicalSha256(cloneJson(state.modelCatalog))
         : undefined;
     if (parsed.modelCatalogSha256 !== expectedModelCatalogSha256) {
         throw new Error("init upgrade model catalog differs from controller authority");
@@ -510,6 +687,59 @@ async function readControllerAnchor(repoRoot, state) {
     }
     return parsed;
 }
+async function readPendingDecisionApplication(input) {
+    const pending = assertPendingDecisionAuthority(input.anchor.decisionAuthority, input.state);
+    const pendingPath = path.join(input.directory, PENDING_DECISION_FILE);
+    if (!pending) {
+        await rm(pendingPath, { force: true });
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(pendingPath, "utf-8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error("pending init decision record is missing or invalid");
+        }
+        await writeJsonAtomic(pendingPath, pending);
+        parsed = pending;
+    }
+    if (!sameJsonValue(parsed, pending) ||
+        canonicalSha256(parsed) !== input.anchor.decisionAuthority?.pendingSha256) {
+        throw new Error("pending init decision record differs from controller authority");
+    }
+    return pending;
+}
+async function readPendingDecisionProjection(input) {
+    const pending = assertPendingDecisionAuthority(input.anchor.decisionAuthority, input.state);
+    const pendingPath = path.join(input.directory, PENDING_DECISION_FILE);
+    let raw;
+    try {
+        raw = await readFile(pendingPath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT" && !pending) {
+            return undefined;
+        }
+        throw new Error("pending init decision record is missing or unreadable");
+    }
+    if (!pending) {
+        throw new Error("pending init decision record lacks controller authority");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("pending init decision record is invalid");
+    }
+    if (!sameJsonValue(parsed, pending) ||
+        canonicalSha256(parsed) !== input.anchor.decisionAuthority?.pendingSha256) {
+        throw new Error("pending init decision record differs from controller authority");
+    }
+    return pending;
+}
 function mergeAuthorityFromAnchor(anchor, state) {
     const authority = anchor.mergeAuthority;
     if (!authority ||
@@ -633,17 +863,9 @@ async function homeFingerprint() {
     }
 }
 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;
+    return semver.valid(candidate) !== null && semver.valid(current) !== null
+        ? semver.gt(candidate, current)
+        : false;
 }
 async function readState(repoRoot, runId) {
     const file = path.join(runDirectory(repoRoot, runId), "state.json");
@@ -684,12 +906,22 @@ function toResult(state, verification, gitignoreMigration) {
         versionGate: state.versionGate,
         deterministicActions: state.actionReceipts,
         modelMergeTasks: state.mergeTasks,
+        decisionReceipts: state.decisionReceipts ?? [],
         humanDecisions: state.humanDecisions,
+        coreState: state.coreState,
+        migrationState: state.migrationState,
+        ...(state.legacyAudit ? { legacyAudit: state.legacyAudit } : {}),
         nextAction: state.nextAction,
         ...(verification ? { verification } : {}),
         ...(gitignoreMigration ? { gitignoreMigration } : {}),
     };
 }
+function projectInitStates(state, report) {
+    state.coreState = report.coreState;
+    state.migrationState = report.migrationState;
+    if (report.legacyAudit)
+        state.legacyAudit = cloneJson(report.legacyAudit);
+}
 function renderReport(state, verification, gitignoreMigration) {
     const lines = [
         "# loop-agent init upgrade report",
@@ -708,10 +940,13 @@ function renderReport(state, verification, gitignoreMigration) {
         `- version choice: \`${state.versionGate.choice ?? "pending"}\``,
         `- deterministic actions applied: ${state.actionReceipts.length}`,
         `- semantic merges accepted: ${state.mergeReceipts.length}`,
-        `- preserved user modifications: ${state.mergeReceipts.length}`,
+        `- decision-bound dispositions accepted: ${(state.decisionReceipts ?? []).length}`,
+        `- preserved user modifications: ${state.mergeReceipts.length + (state.decisionReceipts ?? []).filter((receipt) => receipt.disposition === "detach-as-project-content").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 + state.queuedMergeTasks.length}`,
         `- remaining human decisions: ${state.humanDecisions.length}`,
+        `- core state: \`${state.coreState}\``,
+        `- migration state: \`${state.migrationState}\``,
         `- gitignore migration assessment: \`.harness/init-upgrades/${state.runId}/gitignore-migration.json\` (index-only untrack guidance; the controller never modifies the Git index)`,
         ...(gitignoreMigration
             ? [
@@ -1225,12 +1460,12 @@ async function freezeVerificationSurface(repoRoot) {
         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)) {
+    if (await exists(path.join(repoRoot, ".loop-agent", "project.json"))) {
+        await add(".loop-agent/project.json");
+    }
+    const verification = await resolveProjectVerification(repoRoot);
+    for (const command of verification.commands) {
+        for (const input of command.inputs) {
             const normalized = await assertSafeRegularRepoFile(repoRoot, input);
             if (normalized.endsWith(".sh"))
                 await staticScriptDependencies(repoRoot, normalized, collected);
@@ -1244,6 +1479,50 @@ async function freezeVerificationSurface(repoRoot) {
     })));
     return { schemaVersion: 1, files };
 }
+async function resolveProjectVerification(repoRoot) {
+    const config = await loadNormalizedProjectConfig(repoRoot);
+    const configured = config.verification.quick.length > 0
+        ? config.verification.quick
+        : config.verification.standard.length > 0
+            ? config.verification.standard
+            : config.verification.full;
+    if (configured.length > 0) {
+        const commands = [];
+        for (const command of configured) {
+            commands.push({
+                command,
+                inputs: await commandRepositoryInputs(repoRoot, command),
+            });
+        }
+        return {
+            source: config.verification.reproducibility === "tracked"
+                ? "tracked"
+                : "local-only",
+            commands,
+        };
+    }
+    const scan = await new ProjectCapabilityScanner().scan(repoRoot);
+    if (scan.verification.status !== "ready") {
+        throw new Error(`project verification is ${scan.verification.status}; configure .loop-agent/project.json verification before init upgrade`);
+    }
+    const candidates = scan.verification.commands;
+    const selected = candidates.find((candidate) => candidate.id.endsWith(":test")) ??
+        candidates.find((candidate) => candidate.id.endsWith(":typecheck")) ??
+        candidates.find((candidate) => candidate.id.endsWith(":lint")) ??
+        candidates[0];
+    if (!selected) {
+        throw new Error("project verification is unavailable; configure .loop-agent/project.json verification before init upgrade");
+    }
+    return {
+        source: "scanner",
+        commands: [
+            {
+                command: selected.command,
+                inputs: scan.evidence.map((entry) => entry.path),
+            },
+        ],
+    };
+}
 async function assertFrozenVerificationSurface(repoRoot, surface) {
     if (!isFrozenVerificationSurface(surface)) {
         throw new Error("verification authority surface manifest is invalid");
@@ -1273,6 +1552,32 @@ function isControllerAuthorizedVerificationMergeTask(task, surface) {
         taskPath.endsWith("/verification-matrix.md")) &&
         Boolean(surface?.files.some((entry) => entry.path === taskPath)));
 }
+function isControllerModelMatrixSelectionTask(task) {
+    if (normalizeAllowedPath(task.path) !== "harness.json")
+        return false;
+    if (task.purpose === "pi-model-matrix-selection")
+        return true;
+    return (task.allowedPaths.length === 1 &&
+        normalizeAllowedPath(task.allowedPaths[0] ?? "") === "harness.json" &&
+        (task.reason ===
+            "harness.json has no complete Pi model matrix that resolves against the current Pi model catalog" ||
+            task.reason.startsWith("only unavailable Pi tiers need reselection: ")) &&
+        (task.mergeRules.includes("Write the complete matrix directly to harness.json; do not run init update because this task authorizes only harness.json. The controller will revalidate all three tiers on continue.") ||
+            task.mergeRules.includes("Apply the complete matrix through init update --apply-safe with all three tier flags so code can revalidate it; valid existing tiers must keep their current effective reference.")));
+}
+function executorAuthorityWithoutPiModelTiers(value) {
+    if (!isRecord(value))
+        return value;
+    const executors = { ...value };
+    if (!isRecord(value.pi))
+        return executors;
+    const pi = { ...value.pi };
+    delete pi.LOW;
+    delete pi.MED;
+    delete pi.HIGH;
+    executors.pi = pi;
+    return executors;
+}
 async function assertFrozenVerificationSurfaceExcept(repoRoot, surface, exemptPath) {
     if (!isFrozenVerificationSurface(surface)) {
         throw new Error("verification authority surface manifest is invalid");
@@ -1294,20 +1599,34 @@ async function validateControllerAuthorizedVerificationMerge(input) {
     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;
+        const executorAuthorityChanged = authority && isControllerModelMatrixSelectionTask(input.task)
+            ? !sameJsonValue(executorAuthorityWithoutPiModelTiers(harness.executors ?? null), executorAuthorityWithoutPiModelTiers(authority.executors))
+            : authority
+                ? !sameJsonValue(harness.executors ?? null, authority.executors)
+                : false;
         if (authority &&
-            (!sameJsonValue(harness.executors ?? null, authority.executors) ||
+            (executorAuthorityChanged ||
                 !sameJsonValue(harness.workflowPolicy ?? null, authority.workflowPolicy))) {
             throw new Error("verification authority harness.json merge cannot change controller executor or workflow authority");
         }
+        const verification = await resolveProjectVerification(input.repoRoot);
+        const frozenPaths = new Set(input.surface.files.map((entry) => entry.path));
+        for (const command of verification.commands) {
+            for (const relativePath of command.inputs) {
+                if (!frozenPaths.has(normalizeAllowedPath(relativePath))) {
+                    throw new Error(`verification authority harness.json merge introduced an unfrozen input: ${relativePath}`);
+                }
+            }
+        }
+        return;
+    }
+    const matrixPath = normalizeAllowedPath(verificationMatrixPath(harness));
+    const frozenMatrixPath = frozenVerificationMatrixPath(input.surface);
+    if (matrixPath !== frozenMatrixPath || taskPath !== frozenMatrixPath) {
+        throw new Error("verification authority merge must retain the controller-frozen verification matrix path");
     }
     const command = await discoverQuickVerification(input.repoRoot);
     tokenizeCommand(command);
@@ -1799,6 +2118,14 @@ 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"));
+const windowsCommandScript = process.platform === "win32" && /\\.(?:cmd|bat)$/i.test(specification.command);
+const quoteWindowsCommandArgument = (value) => /^[A-Za-z0-9_@./:\\\\=,+-]+$/.test(value)
+	? value
+	: '"' + value.replaceAll('"', '""') + '"';
+const workerCommand = windowsCommandScript ? process.env.ComSpec || "cmd.exe" : specification.command;
+const workerArgs = windowsCommandScript
+	? ["/d /s /c " + [specification.command, ...specification.args].map(quoteWindowsCommandArgument).join(" ")]
+	: specification.args;
 let worker;
 let workerClosed = false;
 let exitResult;
@@ -1820,12 +2147,13 @@ const finish = (message) => {
 	process.send({ ...message, stdioOpen: !workerClosed }, afterSend);
 };
 try {
-	worker = spawn(specification.command, specification.args, {
+	worker = spawn(workerCommand, workerArgs, {
 		cwd: process.cwd(),
 		env: process.env,
 		stdio: ["ignore", "pipe", "pipe"],
 		windowsHide: true,
 		shell: false,
+		windowsVerbatimArguments: windowsCommandScript,
 	});
 	worker.stdout?.pipe(process.stdout);
 	worker.stderr?.pipe(process.stderr);
@@ -2291,7 +2619,18 @@ async function runVerificationCommand(input) {
         const anchorBefore = await controllerAnchorSnapshot(repoRoot, state);
         const piHomeBefore = await snapshotOptionalDirectory(path.join(os.homedir(), ".pi"));
         const tokens = tokenizeCommand(commandText);
-        await commandRepositoryInputs(repoRoot, commandText);
+        if (process.platform === "win32" &&
+            tokens.some((token) => /[%!^]/.test(token))) {
+            throw new Error(`unsafe Windows verification command: ${commandText}`);
+        }
+        if (input.authorityInputs) {
+            for (const relativePath of input.authorityInputs) {
+                await assertSafeRegularRepoFile(repoRoot, relativePath);
+            }
+        }
+        else {
+            await commandRepositoryInputs(repoRoot, commandText);
+        }
         let command = tokens.shift();
         if (process.platform === "win32" && command === "npm")
             command = "npm.cmd";
@@ -2454,6 +2793,7 @@ async function runFinalVerification(state, authoritativeHomeFingerprint, surface
     const finalCheck = await checkInitUpdate({
         repoRoot: state.repoRoot,
         modelCatalog,
+        legacyAudit: true,
     });
     const doctor = await runInitDoctor({ repoRoot: state.repoRoot, modelCatalog });
     let inspect;
@@ -2474,47 +2814,72 @@ async function runFinalVerification(state, authoritativeHomeFingerprint, surface
             error: error instanceof Error ? error.message : String(error),
         };
     }
-    let docsAudit;
+    const normalized = await loadNormalizedProjectConfig(state.repoRoot);
+    const documentedGovernance = Object.values(normalized.manifest.entrypoints ?? {}).some((value) => typeof value === "string" && value.length > 0);
+    let docsAudit = {
+        ok: true,
+        status: "not-configured",
+    };
+    if (documentedGovernance) {
+        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),
+            };
+        }
+    }
+    let packageSelfCheck;
     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,
+        const provider = await createControllerContextProvider();
+        await provider.read(CONTROLLER_RESOURCE_IDS.loopAgentBridgeSkill);
+        packageSelfCheck = {
+            ok: true,
+            catalogSha256: provider.identity.catalogDigest,
+            resourceCount: provider.list().length,
         };
     }
     catch (error) {
-        docsAudit = {
+        packageSelfCheck = {
             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;
+    let projectVerification;
     try {
-        const quickCommand = await discoverQuickVerification(state.repoRoot);
-        quickVerification = await runVerificationCommand({
-            state,
-            surface,
-            commandText: quickCommand,
-        });
+        const plan = await resolveProjectVerification(state.repoRoot);
+        const results = [];
+        for (const item of plan.commands) {
+            results.push(await runVerificationCommand({
+                state,
+                surface,
+                commandText: item.command,
+                authorityInputs: item.inputs,
+            }));
+        }
+        projectVerification = {
+            ok: results.length > 0 && results.every((result) => result.ok),
+            source: plan.source,
+            results,
+        };
     }
     catch (error) {
-        quickVerification = {
+        projectVerification = {
             ok: false,
-            command: "verification-matrix minimum project test command",
-            exitCode: null,
-            stdout: "",
-            stderr: error instanceof Error ? error.message : String(error),
+            source: "unavailable",
+            error: error instanceof Error ? error.message : String(error),
         };
     }
-    const recovery = await verifyRecoveryFiles(state.repoRoot);
+    const recovery = { ok: true, status: "not-installed" };
     const projectPi = await inspectProjectPiSettings({ repoRoot: state.repoRoot });
     const homeAfter = await homeFingerprint();
     return {
@@ -2529,6 +2894,8 @@ async function runFinalVerification(state, authoritativeHomeFingerprint, surface
             mergeReceiptCount: state.mergeReceipts.length,
         },
         initSurfaceClean: finalCheck.ok,
+        coreState: finalCheck.coreState,
+        migrationState: finalCheck.migrationState,
         initSurface: {
             deterministicActions: finalCheck.deterministicActions,
             modelMergeTasks: finalCheck.modelMergeTasks,
@@ -2537,15 +2904,14 @@ async function runFinalVerification(state, authoritativeHomeFingerprint, surface
         doctor: { ok: doctor.ok, checks: doctor.checks },
         inspect,
         docsAudit,
-        checkRepo,
-        quickVerification,
+        packageSelfCheck,
+        projectVerification,
         recovery,
         projectPi: {
             reason: projectPi.reason,
             action: projectPi.action,
-            trustRequired: true,
-            valid: projectPi.reason === "matches" ||
-                projectPi.reason === "enabled-false",
+            trustRequired: projectPi.reason !== "missing-file",
+            valid: projectPi.reason !== "invalid-json",
         },
         userHomeUnchanged: sameJsonValue(homeAfter, authoritativeHomeFingerprint),
         mergeBoundaryClean: state.mergeTasks.length === 0 && state.queuedMergeTasks.length === 0,
@@ -2554,8 +2920,8 @@ async function runFinalVerification(state, authoritativeHomeFingerprint, surface
 }
 function authoritativeVerificationFailureReason(verification) {
     const sources = [
-        verification.quickVerification,
-        verification.checkRepo,
+        verification.projectVerification,
+        verification.packageSelfCheck,
         verification.inspect,
         verification.docsAudit,
     ];
@@ -2594,28 +2960,25 @@ function verificationPassed(verification) {
     const doctor = verification.doctor;
     const inspect = verification.inspect;
     const docsAudit = verification.docsAudit;
-    const checkRepo = verification.checkRepo;
-    const quick = verification.quickVerification;
+    const packageSelfCheck = verification.packageSelfCheck;
+    const projectVerification = verification.projectVerification;
     const projectPi = verification.projectPi;
-    const recovery = verification.recovery;
     return (verification.initSurfaceClean === true &&
+        verification.coreState === "ready" &&
+        (verification.migrationState === "clean" ||
+            verification.migrationState === "retained") &&
         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(packageSelfCheck) &&
+        packageSelfCheck.ok === true &&
+        isRecord(projectVerification) &&
+        projectVerification.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);
@@ -2687,13 +3050,24 @@ async function readFreshCompletedVerification(repoRoot, state) {
     return { verification, reportMarkdown: report.toString("utf-8") };
 }
 async function readValidatedStatusState(repoRoot, runId) {
-    const state = await readState(repoRoot, runId);
+    let 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));
     }
+    const pendingDecision = await readPendingDecisionProjection({
+        directory,
+        state,
+        anchor,
+    });
+    if (pendingDecision) {
+        state = cloneJson(state);
+        state.status = "in-progress";
+        state.humanDecisions = [];
+        state.nextAction = `Resume the authenticated pending decision application with: loop-agent init upgrade --continue --run-id ${state.runId}`;
+    }
     if (state.status === "completed" || state.status === "cancelled") {
         if (!(await frozenControllerMatches(directory, state))) {
             throw new Error("Controller identity drift detected for persisted init upgrade state");
@@ -2788,6 +3162,138 @@ async function activateModelMergeTask(input) {
     await writeReport(directory, state, undefined, gitignoreMigration);
     return toResult(state, undefined, gitignoreMigration);
 }
+class DecisionApplicationPendingError extends Error {
+    constructor(error) {
+        super(`init decision application is pending recovery: ${error instanceof Error ? error.message : String(error)}`);
+        this.name = "DecisionApplicationPendingError";
+    }
+}
+async function applyDecisionBoundFile(input) {
+    let anchor = await readControllerAnchor(input.state.repoRoot, input.state);
+    let pending = await readPendingDecisionApplication({
+        directory: input.directory,
+        state: input.state,
+        anchor,
+    });
+    if (!pending) {
+        if (!input.decisionFile) {
+            throw new Error("init upgrade requires --decision-file for unresolved human decisions");
+        }
+        const parsed = await readInitUpgradeDecisionFile({
+            repoRoot: input.state.repoRoot,
+            runId: input.state.runId,
+            decisionFile: input.decisionFile,
+            pending: input.state.humanDecisions,
+        });
+        const stateProjection = controllerStateProjection(input.state);
+        pending = {
+            schemaVersion: 1,
+            runId: input.state.runId,
+            repoRoot: input.state.repoRoot,
+            decisionFileSha256: parsed.sha256,
+            document: cloneJson(parsed.document),
+            stateProjection,
+            stateProjectionSha256: canonicalSha256(stateProjection),
+            preparedAt: new Date().toISOString(),
+        };
+        await writeJsonAtomic(path.join(input.directory, PENDING_DECISION_FILE), pending);
+        await writeControllerAnchor({
+            state: input.state,
+            decisionAuthority: {
+                pending,
+                pendingSha256: canonicalSha256(pending),
+            },
+        });
+        anchor = await readControllerAnchor(input.state.repoRoot, input.state);
+        pending = await readPendingDecisionApplication({
+            directory: input.directory,
+            state: input.state,
+            anchor,
+        });
+        if (!pending)
+            throw new Error("pending init decision authority was not established");
+    }
+    else if (input.decisionFile) {
+        try {
+            const suppliedSha256 = sha256(await readRepoLocalDecisionFile(input.state.repoRoot, input.decisionFile));
+            if (suppliedSha256 !== pending.decisionFileSha256) {
+                throw new Error("init upgrade --decision-file differs from the authenticated pending decision");
+            }
+        }
+        catch (error) {
+            throw new DecisionApplicationPendingError(error);
+        }
+    }
+    try {
+        const applied = await applyInitDecisionBoundActions({
+            repoRoot: input.state.repoRoot,
+            actions: pending.document.decisions,
+            resumeAuthority: {
+                runId: pending.runId,
+                pendingSha256: anchor.decisionAuthority.pendingSha256,
+            },
+        });
+        await input.afterActionsApplied?.();
+        const decidedAt = new Date().toISOString();
+        const receipts = applied.map((result) => ({
+            ...result,
+            decisionFileSha256: pending.decisionFileSha256,
+            decidedAt,
+        }));
+        const existingReceiptKeys = new Set((input.state.decisionReceipts ?? []).map((receipt) => canonicalSha256({
+            path: receipt.path,
+            candidateId: receipt.candidateId,
+            disposition: receipt.disposition,
+            expectedSha256: receipt.expectedSha256,
+            resultSha256: receipt.resultSha256,
+            decisionFileSha256: receipt.decisionFileSha256,
+        })));
+        input.state.decisionReceipts = [
+            ...(input.state.decisionReceipts ?? []),
+            ...receipts.filter((receipt) => !existingReceiptKeys.has(canonicalSha256({
+                path: receipt.path,
+                candidateId: receipt.candidateId,
+                disposition: receipt.disposition,
+                expectedSha256: receipt.expectedSha256,
+                resultSha256: receipt.resultSha256,
+                decisionFileSha256: receipt.decisionFileSha256,
+            }))),
+        ];
+        for (const receipt of receipts) {
+            if ((receipt.disposition === "replace-with-bridge" ||
+                receipt.disposition === "delete-listed-file") &&
+                !input.state.actionReceipts.some((action) => action.type ===
+                    (receipt.disposition === "replace-with-bridge"
+                        ? "replace-owned-file"
+                        : "remove-owned-file") &&
+                    action.path === receipt.path &&
+                    action.expectedSha256 === receipt.expectedSha256)) {
+                input.state.actionReceipts.push({
+                    type: receipt.disposition === "replace-with-bridge"
+                        ? "replace-owned-file"
+                        : "remove-owned-file",
+                    path: receipt.path,
+                    expectedSha256: receipt.expectedSha256,
+                    reason: receipt.disposition === "replace-with-bridge"
+                        ? DECISION_REPLACE_REASON
+                        : "remove an explicitly approved hash-bound legacy init file",
+                });
+            }
+        }
+        input.state.humanDecisions = [];
+        input.state.status = "in-progress";
+        input.state.nextAction =
+            "Decision-bound dispositions were recorded; re-plan the minimal surface and continue verification.";
+        await writeJsonAtomic(path.join(input.directory, "decision-receipts.json"), input.state.decisionReceipts);
+        await writeJsonAtomic(path.join(input.directory, "change-manifest.json"), input.state.actionReceipts);
+        await saveState(input.directory, input.state);
+        await writeControllerAnchor({ state: input.state, decisionAuthority: null });
+        await rm(path.join(input.directory, PENDING_DECISION_FILE), { force: true });
+    }
+    catch (error) {
+        throw new DecisionApplicationPendingError(error);
+    }
+}
 async function verifyAndCompleteUpgrade(input) {
     const { directory, state, gitignoreMigration, modelCatalog } = input;
     state.mergeTasks = [];
@@ -2798,6 +3304,7 @@ async function verifyAndCompleteUpgrade(input) {
         let postMerge = await checkInitUpdate({
             repoRoot: state.repoRoot,
             modelCatalog,
+            legacyAudit: true,
         });
         const seen = new Set();
         for (let pass = 0; postMerge.deterministicActions.length > 0 && pass < 2; pass += 1) {
@@ -2809,8 +3316,8 @@ async function verifyAndCompleteUpgrade(input) {
             const converged = await applyInitUpdate({
                 repoRoot: state.repoRoot,
                 applySafe: true,
-                clientRecovery: "project",
                 modelCatalog,
+                legacyAudit: true,
             });
             state.actionReceipts.push(...converged.applied);
             await writeJsonAtomic(path.join(directory, "change-manifest.json"), state.actionReceipts);
@@ -2819,6 +3326,7 @@ async function verifyAndCompleteUpgrade(input) {
             postMerge = await checkInitUpdate({
                 repoRoot: state.repoRoot,
                 modelCatalog,
+                legacyAudit: true,
             });
         }
         if (postMerge.deterministicActions.length > 0) {
@@ -2828,6 +3336,7 @@ async function verifyAndCompleteUpgrade(input) {
             postMerge.humanDecisions.length > 0) {
             throw new Error("accepted semantic merges introduced new non-deterministic init decisions; start a new bounded upgrade run");
         }
+        projectInitStates(state, postMerge);
     }
     state.phase = "VERIFY";
     const anchor = await readControllerAnchor(state.repoRoot, state);
@@ -2839,7 +3348,7 @@ async function verifyAndCompleteUpgrade(input) {
         state.status = "completed";
         state.phase = "COMPLETED";
         state.nextAction =
-            "Init upgrade completed; reload the host session so updated AGENTS, skills, and recovery extensions are discovered.";
+            "Init upgrade completed; reload the host session so the minimal bridge and current package resources are discovered.";
         await writeReport(directory, state, verification, gitignoreMigration);
         const finalReportSha256 = sha256(await readFile(path.join(directory, "final-report.md")));
         await writeControllerAnchor({
@@ -2937,7 +3446,9 @@ async function executeUpgrade(directory, state, input) {
     const pre = await checkInitUpdate({
         repoRoot: state.repoRoot,
         modelCatalog: state.modelCatalog,
+        legacyAudit: true,
     });
+    projectInitStates(state, pre);
     await writeJsonAtomic(path.join(directory, "pre-update-report.json"), pre);
     await writeJsonAtomic(path.join(directory, "upgrade-plan.json"), {
         deterministicActions: pre.deterministicActions,
@@ -2947,10 +3458,10 @@ async function executeUpgrade(directory, state, input) {
             "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",
+            "package resource catalog self-check",
+            "normalized project verification or bounded capability scan",
+            "project docs audit when configured",
+            "explicit adapter invariants when installed",
             "Pi home fingerprint",
         ],
     });
@@ -2959,9 +3470,7 @@ async function executeUpgrade(directory, state, 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
@@ -2969,23 +3478,25 @@ async function executeUpgrade(directory, state, input) {
                 : "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",
+                ? "recorded the minimal fresh-project initialization surface"
+                : "minimal initialization wrote the required project surface",
         })));
     }
     await assertInactive(input);
     const safe = await applyInitUpdate({
         repoRoot: state.repoRoot,
         applySafe: true,
-        clientRecovery: "project",
         modelCatalog: state.modelCatalog,
+        legacyAudit: true,
     });
     state.actionReceipts.push(...safe.applied);
     await writeJsonAtomic(path.join(directory, "change-manifest.json"), state.actionReceipts);
     let post = await checkInitUpdate({
         repoRoot: state.repoRoot,
         modelCatalog: state.modelCatalog,
+        legacyAudit: true,
     });
+    projectInitStates(state, post);
     // 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
@@ -3000,8 +3511,8 @@ async function executeUpgrade(directory, state, input) {
         const converged = await applyInitUpdate({
             repoRoot: state.repoRoot,
             applySafe: true,
-            clientRecovery: "project",
             modelCatalog: state.modelCatalog,
+            legacyAudit: true,
         });
         state.actionReceipts.push(...converged.applied);
         await writeJsonAtomic(path.join(directory, "change-manifest.json"), state.actionReceipts);
@@ -3010,7 +3521,9 @@ async function executeUpgrade(directory, state, input) {
         post = await checkInitUpdate({
             repoRoot: state.repoRoot,
             modelCatalog: state.modelCatalog,
+            legacyAudit: true,
         });
+        projectInitStates(state, post);
     }
     if (post.deterministicActions.length > 0) {
         throw new Error(`deterministic init update exceeded the 2-pass convergence limit: ${post.deterministicActions.map((action) => `${action.type}:${action.path}`).join(", ")}`);
@@ -3056,7 +3569,7 @@ async function executeUpgrade(directory, state, input) {
         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.";
+            "Resolve every file decision in a repo-local schemaVersion 1 decision file bound to this runId and each current SHA-256, then call init upgrade --continue --decision-file <path>. The controller preserves detached project content and only replaces the bridge after explicit approval. Resolve staged Git blockers before continuing.";
         await writeJsonAtomic(path.join(directory, "merge-tasks.json"), state.mergeTasks);
         await saveState(directory, state);
         await writeReport(directory, state, undefined, gitignoreMigration);
@@ -3083,6 +3596,9 @@ async function executeUpgrade(directory, state, input) {
 export async function runInitUpgrade(input) {
     const repoRoot = path.resolve(input.repoRoot);
     const mode = input.mode ?? "start";
+    if (input.decisionFile && mode !== "continue") {
+        throw new Error("init upgrade --decision-file requires --continue and --run-id");
+    }
     if ((mode === "status" || mode === "report") && !input.runId) {
         throw new Error("init upgrade --status/--report requires --run-id");
     }
@@ -3151,6 +3667,25 @@ export async function runInitUpgrade(input) {
         if (mode === "continue") {
             state = await readState(repoRoot, runId);
             directory = runDirectory(repoRoot, runId);
+            const decisionAnchor = await readControllerAnchor(repoRoot, state);
+            const pendingDecision = await readPendingDecisionApplication({
+                directory,
+                state,
+                anchor: decisionAnchor,
+            });
+            if (pendingDecision || input.decisionFile) {
+                if ((!pendingDecision && state.phase !== "MODEL_MERGE") ||
+                    (!pendingDecision && state.status !== "needs-human-decision") ||
+                    (!pendingDecision && state.humanDecisions.length === 0)) {
+                    throw new Error("init upgrade --decision-file requires a paused needs-human-decision run");
+                }
+                await applyDecisionBoundFile({
+                    directory,
+                    state,
+                    decisionFile: input.decisionFile,
+                    afterActionsApplied: input.afterDecisionActionsApplied,
+                });
+            }
             const recoverableMergeState = state.phase === "MODEL_MERGE" && state.status === "in-progress"
                 ? cloneJson(state)
                 : undefined;
@@ -3217,10 +3752,13 @@ export async function runInitUpgrade(input) {
                 mergeTasks: [],
                 queuedMergeTasks: [],
                 mergeReceipts: [],
+                decisionReceipts: [],
                 humanDecisions: [],
                 actionReceipts: [],
                 homeFingerprint: await homeFingerprint(),
                 modelCatalog: input.modelCatalog,
+                coreState: "blocked",
+                migrationState: "clean",
             };
             await writeControllerAnchor({ state, initialize: true });
             await writeJsonAtomic(path.join(directory, "controller-identity.json"), {
@@ -3238,6 +3776,8 @@ export async function runInitUpgrade(input) {
     catch (error) {
         if (error instanceof VerificationProcessBoundaryError)
             throw error;
+        if (error instanceof DecisionApplicationPendingError)
+            throw error;
         if (!state)
             throw error;
         const nextAction = error instanceof Error ? error.message : String(error);