@tea-agent/loop-agent 0.38.2 → 0.38.4

package/dist/commands/init.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 import { OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH, OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH, PI_CONTEXT_OVERFLOW_EXTENSION_PATH, PI_PROJECT_SETTINGS_PATH, applyPiRetryMerge, applyProjectPiSettingsMerge, buildOpenCodeContextOverflowCompactPluginSource, buildProjectPiSettingsSource, buildOpenCodeTransientRetryPluginSource, buildPiContextOverflowExtensionSource, inspectProjectPiSettings, parseClientRecoveryMode, runClientRecovery, } from "./client-recovery.js";
+import { assessInitPiModelReadiness, discoverInitModelCatalog, validateInitModelMatrixAgainstCatalog, } from "./init-model-catalog.js";
 const MANAGED_BLOCK_START = "<!-- LOOP_AGENT_INIT_START -->";
 const MANAGED_BLOCK_END = "<!-- LOOP_AGENT_INIT_END -->";
 const GITIGNORE_BLOCK_START = "# LOOP_AGENT_INIT_START";
@@ -889,13 +890,13 @@ function buildHarness(input) {
     }
     // Init always writes a Pi tier matrix. `defaultModel` remains runtime
     // compatibility for old projects only and is never fresh-init output.
-    if (input.model) {
+    if (input.model || input.modelMatrix) {
         const piExisting = isRecord(mergedExecutors.pi) ? mergedExecutors.pi : {};
         mergedExecutors.pi = {
             ...piExisting,
-            LOW: input.model,
-            MED: input.model,
-            HIGH: input.model,
+            LOW: input.modelMatrix?.LOW ?? input.model,
+            MED: input.modelMatrix?.MED ?? input.model,
+            HIGH: input.modelMatrix?.HIGH ?? input.model,
         };
     }
     if (isRecord(mergedExecutors.pi)) {
@@ -1128,6 +1129,28 @@ export function normalizeInitModelReference(input) {
     }
     return model;
 }
+export function normalizeInitModelMatrix(input) {
+    const tierInputs = [input.lowModel, input.medModel, input.highModel];
+    if (tierInputs.every((value) => value === undefined))
+        return undefined;
+    if (input.provider !== undefined || input.model !== undefined) {
+        throw new Error("init --low-model/--med-model/--high-model cannot be combined with --provider or --model");
+    }
+    if (tierInputs.some((value) => value === undefined)) {
+        throw new Error("init model matrix requires --low-model, --med-model, and --high-model together");
+    }
+    const lowModel = normalizeInitModelReference({ model: input.lowModel });
+    const medModel = normalizeInitModelReference({ model: input.medModel });
+    const highModel = normalizeInitModelReference({ model: input.highModel });
+    if (!lowModel || !medModel || !highModel) {
+        throw new Error("init model matrix contains an empty model reference");
+    }
+    return {
+        LOW: lowModel,
+        MED: medModel,
+        HIGH: highModel,
+    };
+}
 function normalizeRelativePath(relativePath) {
     return relativePath.split(path.sep).join("/");
 }
@@ -1363,6 +1386,7 @@ async function readExistingSurfaceState(repoRoot) {
 /** The IDE schema reference remains a structural update signal. */
 const HARNESS_STRUCTURAL_VALUE_KEYS = new Set(["$schema"]);
 const PI_MODEL_ROUTING_KEYS = new Set(["LOW", "MED", "HIGH", "defaultModel"]);
+const HARNESS_OPEN_MAP_PATHS = new Set(["entrypoints", "artifacts", "scripts"]);
 function isPiModelRoutingPath(path) {
     return path.length === 2 && path[0] === "executors" && path[1] === "pi";
 }
@@ -1400,6 +1424,48 @@ function harnessJsonShapeMatches(current, desired, path = []) {
     }
     return true;
 }
+/**
+ * Align harness.json object properties with the current generated contract while
+ * preserving project-owned scalar/array values. Pi tier routing is deliberately
+ * opaque: existing LOW/MED/HIGH values survive byte-for-value, and missing tiers
+ * stay missing until model readiness selects them from the Pi catalog.
+ */
+function reconcileHarnessStructure(current, desired, path = []) {
+    if (!isRecord(desired)) {
+        if (HARNESS_STRUCTURAL_VALUE_KEYS.has(path.at(-1) ?? ""))
+            return desired;
+        if (Array.isArray(desired) &&
+            Array.isArray(current)) {
+            return current;
+        }
+        return current !== undefined && typeof current === typeof desired
+            ? current
+            : desired;
+    }
+    const currentRecord = isRecord(current) ? current : {};
+    const next = {};
+    for (const [key, desiredValue] of Object.entries(desired)) {
+        if (isPiModelRoutingPath(path) && PI_MODEL_ROUTING_KEYS.has(key)) {
+            if (key in currentRecord)
+                next[key] = currentRecord[key];
+            continue;
+        }
+        next[key] = reconcileHarnessStructure(currentRecord[key], desiredValue, [...path, key]);
+    }
+    if (isPiModelRoutingPath(path)) {
+        for (const key of PI_MODEL_ROUTING_KEYS) {
+            if (key in currentRecord && !(key in next))
+                next[key] = currentRecord[key];
+        }
+    }
+    if (path.length === 1 && HARNESS_OPEN_MAP_PATHS.has(path[0])) {
+        for (const [key, value] of Object.entries(currentRecord)) {
+            if (!(key in next))
+                next[key] = value;
+        }
+    }
+    return next;
+}
 /**
  * Stable package/source anchor for generated desired content: sha256 of the
  * desired content re-rendered through buildDesiredSurfaceContent with fixed
@@ -1574,6 +1640,13 @@ async function writeInitSurfaceState(input) {
                 file.acceptedMerge = { ...priorFile.acceptedMerge };
             }
         }
+        for (const [pathName, priorFile] of Object.entries(input.preserveOwnershipFrom.files)) {
+            if (state.files[pathName] || priorFile.mode === "state")
+                continue;
+            if (await exists(path.join(input.repoRoot, pathName))) {
+                state.files[pathName] = { ...priorFile };
+            }
+        }
     }
     if (input.acceptCurrentHarnessAsMerge) {
         const harness = state.files["harness.json"];
@@ -1725,7 +1798,8 @@ function assessHarnessModelMigration(harness) {
     }
     const pi = isRecord(executorRecord.pi) ? executorRecord.pi : {};
     const hasDefaultModel = "defaultModel" in pi;
-    const hasTier = PI_MODEL_TIERS.some((tier) => tier in pi);
+    const tierCount = PI_MODEL_TIERS.filter((tier) => tier in pi).length;
+    const hasTier = tierCount > 0;
     if (["requiresApiKey", "provider", "model"].some((field) => field in pi) ||
         Object.keys(pi).some((field) => !["description", "enabled", "defaultModel", ...PI_MODEL_TIERS].includes(field))) {
         return {
@@ -1739,8 +1813,16 @@ function assessHarnessModelMigration(harness) {
             reason: "legacy top-level model or workflow fields cannot be proven equivalent",
         };
     }
+    if (tierCount > 0 && tierCount < PI_MODEL_TIERS.length) {
+        return {
+            kind: "ambiguous",
+            reason: "executors.pi contains an incomplete LOW/MED/HIGH model matrix",
+        };
+    }
     if (!hasDefaultModel)
         return { kind: "none" };
+    if (tierCount === PI_MODEL_TIERS.length)
+        return { kind: "none" };
     if (hasTier) {
         return {
             kind: "ambiguous",
@@ -2428,7 +2510,9 @@ export function buildInitInstructions(input) {
         "",
         `- Project name: default \`${projectName}\`.`,
         `- Governance root: default \`${governanceRoot}\`.`,
-        "- Confirm the Pi LOW/MED/HIGH matrix. Explicit input must be `--model provider/model` or a paired `--provider provider --model model`; do not guess a provider for a bare model.",
+        "- Discover a credential-safe Pi/OpenCode model catalog with `loop-agent init model-catalog --repo-root <target> --json`. The command exposes only allowlisted model metadata, Pi setup status, and credential-readiness booleans, never raw config or credentials.",
+        "- Preserve every existing LOW/MED/HIGH reference that still resolves in Pi. Select only missing or removed tiers from `eligibleForHarness=true`, then apply the complete matrix with `--low-model`, `--med-model`, and `--high-model`; update code keeps valid tiers unchanged.",
+        "- If `piSetup.status` is `model-definition-required`, ask only for the missing provider/model id, API/base URL, context window, maximum output, inputs/reasoning, cost constraints, and credential method. Help merge Pi models.json without exposing credential values, rerun the catalog, and only then initialize. If definitions exist but credentials are missing, configure auth instead of rewriting harness tiers.",
         "- Default: merge existing AGENTS.md, harness.json, and loop-agent governance docs instead of overwriting user content.",
         "",
         "## Initialization Upgrade Routing",
@@ -2463,12 +2547,14 @@ export function buildInitInstructions(input) {
         "",
         "When a model/agent is asked to initialize a target project, treat initialization as one automated workflow. Do not run deterministic init and then wait for another user turn to fill project-specific content.",
         "",
-        "1. Resolve only the inputs that are genuinely unsafe to assume: provider/model, non-default governance root, overwrite policy, credentials, cost, or deployment side effects.",
-        "2. Run deterministic init with merge defaults.",
-        "3. Continue immediately into project inspection and adaptation.",
-        "4. Finish by running the init health checks and quick verification.",
+        "1. Run `init model-catalog` and inspect `piSetup`. When Pi has no usable model setup, collect only the missing provider/model metadata or credential method, help configure Pi, and rerun the catalog before writing harness.json.",
+        "2. Inspect the target repository. Preserve existing tiers that still resolve in Pi and select only missing/removed tiers from credential-ready Pi-compatible entries. OpenCode-only entries are context, not proof that the Pi executor can use them.",
+        "3. Resolve with the user only inputs that remain genuinely unsafe to assume: material credential/cost/compliance choices, non-default governance root, overwrite policy, or deployment side effects.",
+        "4. Run deterministic init with all three tier flags and merge defaults.",
+        "5. Continue immediately into project inspection and adaptation.",
+        "6. Finish by running the init health checks and quick verification; `init doctor` must confirm the Pi model matrix before any DAG is started.",
         "",
-        "If provider/model is not specified and the existing tier matrix is usable, proceed with it and record the assumption in the handoff. Ask the user only when the choice affects credentials, cost, availability, or an explicitly requested model backend. An ambiguous old model configuration must stay in a bounded harness.json model merge/human decision; never silently reinterpret it.",
+        "A model reference that remains in Pi is project-owned and must not be reset merely because init templates changed. If its credentials are missing, preserve the tier and repair authentication. If a reference has left Pi, replace only that tier. Ask the user only when required model metadata, credentials, cost, compliance, or availability cannot be inferred. An ambiguous old model configuration stays in a bounded harness.json model merge/human decision; never silently reinterpret it.",
         "",
         "## Required Model Adaptation",
         "",
@@ -2502,6 +2588,7 @@ export async function initializeLoopAgentProject(options) {
     const profile = options.profile ?? "full";
     const merge = options.merge ?? true;
     const model = normalizeInitModelReference(options);
+    const modelMatrix = options.modelMatrix;
     const written = [];
     const skipped = [];
     const assetRoot = await findPackageRoot();
@@ -2538,6 +2625,7 @@ export async function initializeLoopAgentProject(options) {
         projectName,
         governanceRoot,
         model,
+        modelMatrix,
     });
     await writeText({
         repoRoot,
@@ -2680,7 +2768,7 @@ export async function initializeLoopAgentProject(options) {
         projectName,
         governanceRoot,
         stateKind: "recorded",
-        acceptCurrentHarnessAsMerge: model !== undefined,
+        acceptCurrentHarnessAsMerge: model !== undefined || modelMatrix !== undefined,
     });
     written.push(INIT_SURFACE_STATE_PATH);
     return {
@@ -2743,11 +2831,7 @@ function modelMergeTaskFor(pathName, state, allPaths, recordedState) {
             "Keep writes inside allowedPaths only.",
         ],
         verification: [
-            "loop-agent init check-update --repo-root . --json",
-            "loop-agent init doctor --repo-root .",
-            "loop-agent inspect --repo-root .",
-            "loop-agent docs audit --repo-root .",
-            "bash scripts/check-repo.sh",
+            `git diff --check -- ${pathName}`,
         ],
         evidence: {
             baseSha256: recordedState?.files[pathName]?.currentSha256,
@@ -2900,15 +2984,52 @@ export async function checkInitUpdate(input) {
                 (state.mode === "copied" || state.mode === "generated") &&
                 state.currentSha256 !== undefined &&
                 recordedState.files[pathName]?.currentSha256 === state.currentSha256) {
+                if (pathName === "harness.json") {
+                    // harness.json always contains project-owned routing and configuration.
+                    // Even when its bytes still match the recorded baseline, package evolution
+                    // must use a semantic merge instead of replacing the whole file.
+                    modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths, recordedState));
+                }
+                else {
+                    deterministicActions.push({
+                        type: "refresh-owned-file",
+                        path: pathName,
+                        mode: state.mode,
+                        reason: "refresh an unchanged recorded init file to the current generated or bundled content",
+                    });
+                }
+            }
+            else {
+                modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths, recordedState));
+            }
+        }
+    }
+    const retiredActionPaths = new Set(retiredLayoutActions.map((action) => action.path));
+    if (recordedState) {
+        for (const [pathName, recordedFile] of Object.entries(recordedState.files)) {
+            if (currentState.files[pathName] ||
+                retiredActionPaths.has(pathName) ||
+                recordedFile.mode === "state" ||
+                recordedFile.mode === "directory") {
+                continue;
+            }
+            const currentSha256 = await fileSha256IfExists(path.join(repoRoot, pathName));
+            if (!currentSha256)
+                continue;
+            if (recordedFile.currentSha256 &&
+                currentSha256 === recordedFile.currentSha256) {
                 deterministicActions.push({
-                    type: "refresh-owned-file",
+                    type: "remove-owned-file",
                     path: pathName,
-                    mode: state.mode,
-                    reason: "refresh an unchanged recorded init file to the current generated or bundled content",
+                    expectedSha256: currentSha256,
+                    reason: "remove an unchanged recorded init file that is no longer part of the current initialization surface",
                 });
             }
-            else {
-                modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths, recordedState));
+            else if (!humanDecisions.some((decision) => decision.path === pathName)) {
+                humanDecisions.push({
+                    path: pathName,
+                    reason: "this recorded init file was removed from the current surface but has local changes; review whether to preserve or delete it",
+                });
             }
         }
     }
@@ -2916,9 +3037,12 @@ export async function checkInitUpdate(input) {
     // Safe harness hygiene: strip obsolete pi.requiresApiKey without full harness rewrite.
     // Cursor requiresApiKey is intentionally kept when present.
     const harnessPath = path.join(repoRoot, "harness.json");
+    let currentHarness;
     if (await exists(harnessPath)) {
         try {
             const harness = JSON.parse(await readFile(harnessPath, "utf-8"));
+            if (isRecord(harness))
+                currentHarness = harness;
             if (recordedState &&
                 isRecord(harness) &&
                 harness.$schema !== expectedHarnessSchemaRef(governanceRoot)) {
@@ -2942,10 +3066,11 @@ export async function checkInitUpdate(input) {
             // A harness that already matches the current generated surface except for
             // opaque Pi routing fields is modern, not a legacy-routing candidate.
             // Keep the explicit migration assessment for every other harness shape.
+            let modelMigration = { kind: "none" };
             if (isRecord(harness) &&
                 currentState.files["harness.json"]?.relationship !==
                     "matches-current-generated") {
-                const modelMigration = assessHarnessModelMigration(harness);
+                modelMigration = assessHarnessModelMigration(harness);
                 if (modelMigration.kind === "safe") {
                     deterministicActions.push({
                         type: "migrate-harness-model-fields",
@@ -2975,11 +3100,83 @@ export async function checkInitUpdate(input) {
                         modelMergeTasks.push(mergeTask);
                 }
             }
+            if (recordedState &&
+                isRecord(harness) &&
+                modelMigration.kind !== "ambiguous") {
+                const desired = await buildDesiredSurfaceContent({
+                    assetRoot,
+                    repoRoot,
+                    projectName,
+                    governanceRoot,
+                    entry: { path: "harness.json", mode: "generated" },
+                });
+                if (desired.content !== undefined) {
+                    const desiredHarness = JSON.parse(desired.content);
+                    const reconciled = reconcileHarnessStructure(harness, desiredHarness);
+                    if (!isDeepStrictEqual(reconciled, harness)) {
+                        deterministicActions.push({
+                            type: "reconcile-harness-structure",
+                            path: "harness.json",
+                            reason: "add current harness properties, remove retired properties, and preserve project-owned values",
+                        });
+                        const existingTask = modelMergeTasks.findIndex((task) => task.path === "harness.json");
+                        if (existingTask >= 0)
+                            modelMergeTasks.splice(existingTask, 1);
+                    }
+                }
+            }
         }
         catch {
             // leave malformed harness for model merge / doctor
         }
     }
+    const modelReadiness = input.modelCatalog
+        ? assessInitPiModelReadiness(isRecord(currentHarness?.executors) &&
+            isRecord(currentHarness.executors.pi)
+            ? currentHarness.executors.pi
+            : undefined, input.modelCatalog)
+        : undefined;
+    if (modelReadiness?.status === "selection-required" ||
+        modelReadiness?.status === "reselection-required") {
+        const state = currentState.files["harness.json"];
+        const task = modelMergeTaskFor("harness.json", state, allPaths, recordedState);
+        task.reason =
+            modelReadiness.status === "selection-required"
+                ? "harness.json has no complete Pi model matrix that resolves against the current Pi model catalog"
+                : `only unavailable Pi tiers need reselection: ${modelReadiness.reselectTiers.join(", ")}`;
+        task.mergeRules = [
+            `Preserve these currently resolvable tiers byte-for-byte: ${modelReadiness.preserveTiers.join(", ") || "none"}.`,
+            `Select replacements only for: ${modelReadiness.reselectTiers.join(", ")}.`,
+            "Choose replacements from eligibleReferences using target-project needs, capability, context window, latency, and cost; tiers may intentionally share a model.",
+            "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.",
+            "Do not add credentials or raw Pi configuration to harness.json.",
+        ];
+        task.verification = [
+            "loop-agent init model-catalog --repo-root . --json",
+            "loop-agent init check-update --repo-root . --json",
+            "loop-agent init doctor --repo-root .",
+            "bash scripts/check-repo.sh",
+        ];
+        const existingTask = modelMergeTasks.findIndex((candidate) => candidate.path === "harness.json");
+        if (existingTask >= 0)
+            modelMergeTasks[existingTask] = task;
+        else
+            modelMergeTasks.push(task);
+    }
+    else if (modelReadiness &&
+        modelReadiness.status !== "ready") {
+        const setup = input.modelCatalog?.piSetup;
+        const reason = setup?.status === "model-definition-required"
+            ? `${setup.reason} Ask for: ${setup.requiredUserInput.join("; ")}.`
+            : setup?.status === "credentials-required" ||
+                setup?.status === "discovery-failed"
+                ? setup.reason
+                : "One or more configured Pi tiers are known but not credential-ready; enable their provider without changing the tier selection.";
+        humanDecisions.push({
+            path: "~/.pi/agent/models.json",
+            reason,
+        });
+    }
     const partial = {
         repoRoot,
         controllerVersion: currentState.controllerVersion,
@@ -2987,6 +3184,7 @@ export async function checkInitUpdate(input) {
         deterministicActions,
         modelMergeTasks,
         humanDecisions,
+        ...(modelReadiness ? { modelReadiness } : {}),
         summary: {
             missing: deterministicActions.filter((action) => action.type !== "bootstrap-surface").length,
             modelMerge: modelMergeTasks.length,
@@ -2994,6 +3192,9 @@ export async function checkInitUpdate(input) {
         },
     };
     const recommendedNext = recommendedNextFor(partial);
+    if (modelReadiness && modelReadiness.status !== "ready") {
+        recommendedNext.unshift("loop-agent init model-catalog --repo-root <target> --json");
+    }
     // Project settings are part of the surface. Do not inspect user home by default.
     const piInspection = await inspectProjectPiSettings({ repoRoot });
     return {
@@ -3105,9 +3306,36 @@ async function applySafeAction(input) {
         const target = path.join(input.repoRoot, input.action.path);
         if (!(await exists(target)))
             return false;
+        if (input.action.expectedSha256 &&
+            (await fileSha256IfExists(target)) !== input.action.expectedSha256) {
+            return false;
+        }
         await rm(target, { force: true });
         return true;
     }
+    if (input.action.type === "reconcile-harness-structure") {
+        const target = path.join(input.repoRoot, "harness.json");
+        if (!(await exists(target)))
+            return false;
+        const current = JSON.parse(await readFile(target, "utf-8"));
+        if (!isRecord(current))
+            return false;
+        const assetRoot = await findPackageRoot();
+        const desired = await buildDesiredSurfaceContent({
+            assetRoot,
+            repoRoot: input.repoRoot,
+            projectName: input.projectName,
+            governanceRoot: input.governanceRoot,
+            entry: { path: "harness.json", mode: "generated" },
+        });
+        if (desired.content === undefined)
+            return false;
+        const next = reconcileHarnessStructure(current, JSON.parse(desired.content));
+        if (isDeepStrictEqual(next, current))
+            return false;
+        await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+        return true;
+    }
     if (input.action.type === "remove-empty-directory") {
         const target = path.join(input.repoRoot, input.action.path);
         if (!(await isDirectoryEmpty(target)))
@@ -3162,6 +3390,8 @@ async function applySafeAction(input) {
         return true;
     }
     if (input.action.type === "refresh-owned-file") {
+        if (input.action.path === "harness.json")
+            return false;
         await writeFile(target, desired.content, "utf-8");
         return true;
     }
@@ -3180,6 +3410,52 @@ export async function applyInitUpdate(input) {
     const applied = [];
     const skipped = [];
     const clientRecoveryMode = input.clientRecovery ?? "auto";
+    const requestedModelMatrix = input.modelMatrix ??
+        (input.model
+            ? { LOW: input.model, MED: input.model, HIGH: input.model }
+            : undefined);
+    if (requestedModelMatrix) {
+        if (!input.modelCatalog) {
+            throw new Error("init update model selection requires a fresh Pi model catalog");
+        }
+        validateInitModelMatrixAgainstCatalog(requestedModelMatrix, input.modelCatalog);
+        const harnessPath = path.join(repoRoot, "harness.json");
+        const harness = JSON.parse(await readFile(harnessPath, "utf-8"));
+        if (!isRecord(harness) ||
+            !isRecord(harness.executors) ||
+            !isRecord(harness.executors.pi)) {
+            throw new Error("init update cannot select models until harness.json executors.pi exists");
+        }
+        const readiness = assessInitPiModelReadiness(harness.executors.pi, input.modelCatalog);
+        if (readiness.status === "credentials-required" ||
+            readiness.status === "model-definition-required" ||
+            readiness.status === "discovery-failed") {
+            throw new Error(`init update cannot change harness model routing while Pi model readiness is ${readiness.status}`);
+        }
+        for (const tier of readiness.preserveTiers) {
+            const currentReference = readiness.tiers[tier].resolvedReference;
+            if (currentReference &&
+                requestedModelMatrix[tier] !== currentReference) {
+                throw new Error(`init update preserves the current Pi ${tier} model because it is still in the Pi catalog: ${currentReference}`);
+            }
+        }
+        if (readiness.reselectTiers.length > 0) {
+            const nextPi = { ...harness.executors.pi };
+            for (const tier of readiness.reselectTiers) {
+                nextPi[tier] = requestedModelMatrix[tier];
+            }
+            const next = {
+                ...harness,
+                executors: { ...harness.executors, pi: nextPi },
+            };
+            await writeFile(harnessPath, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+            applied.push({
+                type: "write-harness-model-matrix",
+                path: "harness.json",
+                reason: `replace only unavailable Pi tiers: ${readiness.reselectTiers.join(", ")}`,
+            });
+        }
+    }
     if (input.bootstrapSurface) {
         await writeInitSurfaceState({
             repoRoot,
@@ -3206,6 +3482,7 @@ export async function applyInitUpdate(input) {
             governanceRoot,
             clientRecovery: clientRecoveryMode,
             homeDir: input.homeDir,
+            modelCatalog: input.modelCatalog,
         });
         for (const action of report.deterministicActions) {
             if (action.type === "bootstrap-surface") {
@@ -3245,6 +3522,7 @@ export async function applyInitUpdate(input) {
             governanceRoot,
             clientRecovery: clientRecoveryMode,
             homeDir: input.homeDir,
+            modelCatalog: input.modelCatalog,
         }),
     };
 }
@@ -3258,6 +3536,16 @@ function formatClientRecoverySummary(report) {
         `clientRecovery.pi.path: ${pi.path}`,
     ];
 }
+function formatModelReadinessSummary(report) {
+    const readiness = report.modelReadiness;
+    if (!readiness)
+        return [];
+    return [
+        `modelReadiness.status: ${readiness.status}`,
+        `modelReadiness.preserveTiers: ${readiness.preserveTiers.join(",") || "none"}`,
+        `modelReadiness.reselectTiers: ${readiness.reselectTiers.join(",") || "none"}`,
+    ];
+}
 function formatCheckUpdateText(report) {
     return [
         `loop-agent init update check for ${report.repoRoot}`,
@@ -3266,6 +3554,7 @@ function formatCheckUpdateText(report) {
         `deterministicActions: ${report.deterministicActions.length}`,
         `modelMergeTasks: ${report.modelMergeTasks.length}`,
         `humanDecisions: ${report.humanDecisions.length}`,
+        ...formatModelReadinessSummary(report),
         ...formatClientRecoverySummary(report),
         "recommendedNext:",
         ...report.recommendedNext.map((item) => `- ${item}`),
@@ -3279,6 +3568,14 @@ function formatCheckUpdateMarkdown(report) {
         `- repoRoot: \`${report.repoRoot}\``,
         `- controllerVersion: \`${report.controllerVersion}\``,
         `- surfaceState: \`${report.surfaceState}\``,
+        ...(report.modelReadiness
+            ? [
+                "",
+                "## Pi Model Readiness",
+                "",
+                ...formatModelReadinessSummary(report).map((line) => `- ${line}`),
+            ]
+            : []),
         ...(piLines.length > 0
             ? ["", "## Client Recovery (Pi user config, read-only)", "", ...piLines]
             : []),
@@ -3313,6 +3610,14 @@ export async function runInitDoctor(input) {
         const manifest = await loadHarnessManifest(repoRoot);
         add("harness.json", manifest.adapter === "loop-agent" || manifest.project === "loop-agent", `project=${manifest.project}`);
         add("governance root", await exists(path.join(repoRoot, manifest.governanceRoot, "README.md")), manifest.governanceRoot);
+        if (input.modelCatalog) {
+            const readiness = assessInitPiModelReadiness(isRecord(manifest.executors?.pi)
+                ? manifest.executors.pi
+                : undefined, input.modelCatalog);
+            add("Pi model matrix", readiness.status === "ready", readiness.status === "ready"
+                ? "LOW/MED/HIGH resolve against the current Pi model catalog"
+                : `${readiness.status}; preserve=${readiness.preserveTiers.join(",") || "none"}; reselect=${readiness.reselectTiers.join(",") || "none"}`);
+        }
     }
     catch (error) {
         add("harness.json", false, error instanceof Error ? error.message : String(error));
@@ -3354,6 +3659,7 @@ export async function runInitReconcile(input) {
         repoRoot,
         projectName: input.projectName,
         governanceRoot: input.governanceRoot,
+        modelCatalog: input.modelCatalog,
     });
     if (preReport.surfaceState === "missing") {
         return { status: "needs-baseline", report: preReport };
@@ -3374,6 +3680,7 @@ export async function runInitReconcile(input) {
         projectName: input.projectName,
         governanceRoot: input.governanceRoot,
         applySafe: true,
+        modelCatalog: input.modelCatalog,
     });
     const status = update.report.ok
         ? "clean"
@@ -3395,6 +3702,9 @@ function parseInitArgs(repoRoot, args) {
     let merge = true;
     let provider;
     let model;
+    let lowModel;
+    let medModel;
+    let highModel;
     let clientRecovery = "auto";
     let json = false;
     let markdown = false;
@@ -3409,6 +3719,7 @@ function parseInitArgs(repoRoot, args) {
         const arg = args[i];
         if ((arg === "instructions" ||
             arg === "doctor" ||
+            arg === "model-catalog" ||
             arg === "check-update" ||
             arg === "update" ||
             arg === "reconcile" ||
@@ -3441,6 +3752,18 @@ function parseInitArgs(repoRoot, args) {
             model = args[++i];
         else if (arg.startsWith("--model="))
             model = arg.slice("--model=".length);
+        else if (arg === "--low-model")
+            lowModel = args[++i];
+        else if (arg.startsWith("--low-model="))
+            lowModel = arg.slice("--low-model=".length);
+        else if (arg === "--med-model")
+            medModel = args[++i];
+        else if (arg.startsWith("--med-model="))
+            medModel = arg.slice("--med-model=".length);
+        else if (arg === "--high-model")
+            highModel = args[++i];
+        else if (arg.startsWith("--high-model="))
+            highModel = arg.slice("--high-model=".length);
         else if (arg === "--client-recovery")
             clientRecovery = parseClientRecoveryMode(args[++i]);
         else if (arg.startsWith("--client-recovery="))
@@ -3478,6 +3801,13 @@ function parseInitArgs(repoRoot, args) {
         throw new Error("init upgrade --version-choice must be current|upgrade|cancel|retry");
     }
     const normalizedModel = normalizeInitModelReference({ provider, model });
+    const modelMatrix = normalizeInitModelMatrix({
+        provider,
+        model,
+        lowModel,
+        medModel,
+        highModel,
+    });
     return {
         repoRoot,
         projectName,
@@ -3486,6 +3816,7 @@ function parseInitArgs(repoRoot, args) {
         merge,
         provider,
         model: normalizedModel,
+        modelMatrix,
         clientRecovery,
         subcommand,
         json,
@@ -3499,21 +3830,49 @@ function parseInitArgs(repoRoot, args) {
         versionChoice,
     };
 }
+async function discoverInitCatalogForRepo(repoRoot) {
+    const harness = await readJsonIfExists(path.join(repoRoot, "harness.json"));
+    const pi = isRecord(harness.executors) && isRecord(harness.executors.pi)
+        ? harness.executors.pi
+        : undefined;
+    const includePiReferences = pi
+        ? PI_MODEL_TIERS.flatMap((tier) => {
+            const value = pi[tier];
+            const model = typeof value === "string"
+                ? value
+                : isRecord(value) && typeof value.model === "string"
+                    ? value.model
+                    : undefined;
+            return model && isQualifiedModelReference(model) ? [model] : [];
+        })
+        : [];
+    return discoverInitModelCatalog({ repoRoot, includePiReferences });
+}
 export async function runInit(repoRoot, rawArgs, dependencies) {
     const parsed = parseInitArgs(repoRoot, rawArgs);
     if (parsed.subcommand === "instructions") {
         console.log(buildInitInstructions(parsed));
         return;
     }
+    if (parsed.subcommand === "model-catalog") {
+        const catalog = await discoverInitCatalogForRepo(parsed.repoRoot);
+        console.log(JSON.stringify(catalog, null, 2));
+        return;
+    }
     if (parsed.subcommand === "doctor") {
-        const report = await runInitDoctor({ repoRoot: parsed.repoRoot });
+        const modelCatalog = await discoverInitCatalogForRepo(parsed.repoRoot);
+        const report = await runInitDoctor({
+            repoRoot: parsed.repoRoot,
+            modelCatalog,
+        });
         console.log(JSON.stringify(report, null, 2));
         if (!report.ok)
             process.exitCode = 1;
         return;
     }
     if (parsed.subcommand === "check-update") {
-        const report = await checkInitUpdate(parsed);
+        const modelCatalog = await discoverInitCatalogForRepo(parsed.repoRoot);
+        const report = await checkInitUpdate({ ...parsed, modelCatalog });
         if (parsed.json)
             console.log(JSON.stringify(report, null, 2));
         else if (parsed.markdown)
@@ -3526,7 +3885,11 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
         if (!parsed.bootstrapSurface && !parsed.applySafe) {
             throw new Error("usage: init update [--bootstrap-surface] [--apply-safe]");
         }
-        const result = await applyInitUpdate(parsed);
+        if ((parsed.model || parsed.modelMatrix) && !parsed.applySafe) {
+            throw new Error("init update model selection requires --apply-safe");
+        }
+        const modelCatalog = await discoverInitCatalogForRepo(parsed.repoRoot);
+        const result = await applyInitUpdate({ ...parsed, modelCatalog });
         console.log(parsed.json
             ? JSON.stringify(result, null, 2)
             : formatInitUpdateResult(result));
@@ -3537,12 +3900,23 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
         const selected = [parsed.upgradeStatus, parsed.upgradeContinue, parsed.upgradeReport].filter(Boolean).length;
         if (selected > 1)
             throw new Error("init upgrade accepts only one of --status, --continue, or --report");
+        const mode = parsed.upgradeStatus
+            ? "status"
+            : parsed.upgradeContinue
+                ? "continue"
+                : parsed.upgradeReport
+                    ? "report"
+                    : "start";
+        const modelCatalog = mode === "start"
+            ? await discoverInitCatalogForRepo(parsed.repoRoot)
+            : undefined;
         const result = await runInitUpgrade({
             repoRoot: parsed.repoRoot,
             runId: parsed.runId,
-            mode: parsed.upgradeStatus ? "status" : parsed.upgradeContinue ? "continue" : parsed.upgradeReport ? "report" : "start",
+            mode,
             versionChoice: parsed.versionChoice,
             readRuntimeActivity: dependencies.readRuntimeActivity,
+            modelCatalog,
         });
         if ("markdown" in result)
             console.log(result.markdown);
@@ -3551,8 +3925,10 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
         return;
     }
     if (parsed.subcommand === "reconcile") {
+        const modelCatalog = await discoverInitCatalogForRepo(parsed.repoRoot);
         const result = await runInitReconcile({
             ...parsed,
+            modelCatalog,
             readRuntimeActivity: dependencies.readRuntimeActivity,
         });
         console.log(parsed.json
@@ -3560,6 +3936,31 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
             : formatReconcileResult(result));
         return;
     }
+    const catalog = await discoverInitCatalogForRepo(parsed.repoRoot);
+    const requestedMatrix = parsed.modelMatrix ??
+        (parsed.model
+            ? { LOW: parsed.model, MED: parsed.model, HIGH: parsed.model }
+            : undefined);
+    if (requestedMatrix) {
+        validateInitModelMatrixAgainstCatalog(requestedMatrix, catalog);
+    }
+    else {
+        const harness = await readJsonIfExists(path.join(parsed.repoRoot, "harness.json"));
+        const readiness = assessInitPiModelReadiness(isRecord(harness.executors) && isRecord(harness.executors.pi)
+            ? harness.executors.pi
+            : undefined, catalog);
+        if (readiness.status !== "ready") {
+            const setup = catalog.piSetup;
+            if (setup.status === "model-definition-required") {
+                throw new Error(`Pi model setup is required before init. Ask the user for: ${setup.requiredUserInput.join("; ")}. Help merge the definition into ${setup.configPath} without storing credential values, rerun init model-catalog, then initialize with all three tier flags.`);
+            }
+            if (setup.status === "credentials-required" ||
+                setup.status === "discovery-failed") {
+                throw new Error(`${setup.reason} ${setup.nextSteps.join(" ")}`);
+            }
+            throw new Error(`Pi model selection is required before init (${readiness.status}). Run init model-catalog, preserve tiers still present in Pi, select only missing tiers, and pass --low-model/--med-model/--high-model.`);
+        }
+    }
     const result = await initializeLoopAgentProject(parsed);
     console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitResult(result));
 }