@tea-agent/loop-agent 0.25.2 → 0.25.4

package/dist/commands/init.js

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
-import { access, copyFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile, } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { copyDir } from "../shared/copy-dir.js";
 import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
 import { loadHarnessManifest } from "../governance/harness.js";
+import { OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH, applyPiRetryMerge, buildOpenCodeTransientRetryPluginSource, inspectPiRetryConfig, parseClientRecoveryMode, runClientRecovery, } from "./client-recovery.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";
@@ -14,18 +16,36 @@ const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const DEFAULT_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
 const CORE_DOC_FILES = [
     { source: "README.md", target: "README.md" },
-    { source: "architecture/runtime-boundaries.md", target: "architecture/runtime-boundaries.md" },
-    { source: "governance/development-principles.md", target: "development-principles.md" },
+    {
+        source: "architecture/runtime-boundaries.md",
+        target: "architecture/runtime-boundaries.md",
+    },
+    {
+        source: "governance/development-principles.md",
+        target: "development-principles.md",
+    },
     { source: "governance/feature-workflow.md", target: "feature-workflow.md" },
-    { source: "governance/verification-matrix.md", target: "verification-matrix.md" },
+    {
+        source: "governance/verification-matrix.md",
+        target: "verification-matrix.md",
+    },
     { source: "runtime/loop-agent-harness.md", target: "loop-agent-harness.md" },
-    { source: "governance/harness-methodology-tdd.md", target: "harness-methodology-tdd.md" },
-    { source: "governance/harness-methodology-verification.md", target: "harness-methodology-verification.md" },
-    { source: "governance/harness-methodology-debugging.md", target: "harness-methodology-debugging.md" },
+    {
+        source: "governance/harness-methodology-tdd.md",
+        target: "harness-methodology-tdd.md",
+    },
+    {
+        source: "governance/harness-methodology-verification.md",
+        target: "harness-methodology-verification.md",
+    },
+    {
+        source: "governance/harness-methodology-debugging.md",
+        target: "harness-methodology-debugging.md",
+    },
     { source: "templates/README.md", target: "templates/README.md" },
 ];
 function coreDocSourceForTarget(target) {
-    return CORE_DOC_FILES.find((entry) => entry.target === target)?.source ?? target;
+    return (CORE_DOC_FILES.find((entry) => entry.target === target)?.source ?? target);
 }
 const GOVERNANCE_README_DIRS = [
     "decisions",
@@ -854,7 +874,7 @@ function buildManagedAgentsBlock(input) {
         "### Agent DAG 路径",
         "",
         "```bash",
-        "loop-agent new-task <task-id> \"任务标题\"",
+        'loop-agent new-task <task-id> "任务标题"',
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
         "loop-agent dag run-task <task-id> --profile auto --strict-models",
@@ -868,9 +888,12 @@ function buildManagedAgentsBlock(input) {
         "",
         "### 任务类型路由（taskKind）",
         "",
-        "- 用户明确提出后端测试、接口/API 测试、pytest，或语境明确为后端的自动化测试时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `\"backend-test\"`，不得保留默认 `standard`。",
+        '- 用户明确提出后端测试、接口/API 测试、pytest，或语境明确为后端的自动化测试时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"backend-test"`，不得保留默认 `standard`。',
         "- `backend-test` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`。",
         "- 仅出现“自动化测试”且无法判断前后端时，先阅读任务源与目标项目技术栈再决定，禁止无条件路由到 `backend-test`。",
+        '- 用户提示词明确是前端实现需求（例如前端页面、UI、组件或交互开发）时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"frontend-implementation"`，不得保留默认 `standard`。',
+        "- `frontend-implementation` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`，也可按需显式选择 `minimal` / `standard` / `reviewed` / `supervised`，不要把业务模板名当作 profile。",
+        '- 前端自动化测试（浏览器/UI 自动化、Playwright、E2E）继续使用 `taskKind: "frontend-test"`，不得设置为 `frontend-implementation`。',
         "",
         "### 运行看板（只读）",
         "",
@@ -904,7 +927,8 @@ function mergeManagedBlock(existing, block) {
     const start = existing.indexOf(MANAGED_BLOCK_START);
     const end = existing.indexOf(MANAGED_BLOCK_END);
     if (start >= 0 && end > start) {
-        return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + MANAGED_BLOCK_END.length).trimStart()}`.trimEnd() + "\n";
+        return (`${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + MANAGED_BLOCK_END.length).trimStart()}`.trimEnd() +
+            "\n");
     }
     return `${existing.trimEnd()}\n\n${block}\n`;
 }
@@ -912,7 +936,8 @@ function mergeGitignoreManagedBlock(existing, block) {
     const start = existing.indexOf(GITIGNORE_BLOCK_START);
     const end = existing.indexOf(GITIGNORE_BLOCK_END);
     if (start >= 0 && end > start) {
-        return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + GITIGNORE_BLOCK_END.length).trimStart()}`.trimEnd() + "\n";
+        return (`${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + GITIGNORE_BLOCK_END.length).trimStart()}`.trimEnd() +
+            "\n");
     }
     if (!existing.trim())
         return `${block}\n`;
@@ -1051,19 +1076,22 @@ function buildHarness(input) {
     // Do not project legacy step-routing models / modelProfiles / modelRouting into
     // new or refreshed harness.json. Keep them only when the target already has them
     // so old files remain loadable until the user migrates.
-    if (isRecord(input.existing.models) && Object.keys(input.existing.models).length > 0) {
+    if (isRecord(input.existing.models) &&
+        Object.keys(input.existing.models).length > 0) {
         harness.models = input.existing.models;
     }
     else {
         delete harness.models;
     }
-    if (isRecord(input.existing.modelProfiles) && Object.keys(input.existing.modelProfiles).length > 0) {
+    if (isRecord(input.existing.modelProfiles) &&
+        Object.keys(input.existing.modelProfiles).length > 0) {
         harness.modelProfiles = input.existing.modelProfiles;
     }
     else {
         delete harness.modelProfiles;
     }
-    if (isRecord(input.existing.modelRouting) && Object.keys(input.existing.modelRouting).length > 0) {
+    if (isRecord(input.existing.modelRouting) &&
+        Object.keys(input.existing.modelRouting).length > 0) {
         harness.modelRouting = input.existing.modelRouting;
     }
     else {
@@ -1110,7 +1138,9 @@ async function copyDirMerge(input) {
     const source = path.join(input.assetRoot, input.sourceRelativePath);
     const target = path.join(input.repoRoot, input.targetRelativePath);
     await copyDir(source, target);
-    input.written.push(input.targetRelativePath.endsWith("/") ? input.targetRelativePath : `${input.targetRelativePath}/`);
+    input.written.push(input.targetRelativePath.endsWith("/")
+        ? input.targetRelativePath
+        : `${input.targetRelativePath}/`);
 }
 async function ensureHarnessDirs(repoRoot, written) {
     const dirs = [
@@ -1187,7 +1217,8 @@ function manifestPathToTargetPath(relativePath, governanceRoot) {
     return relativePath;
 }
 function targetPathToManifestPath(relativePath, governanceRoot) {
-    if (governanceRoot !== "docs" && relativePath.startsWith(`${governanceRoot}/`)) {
+    if (governanceRoot !== "docs" &&
+        relativePath.startsWith(`${governanceRoot}/`)) {
         return `docs/${relativePath.slice(`${governanceRoot}/`.length)}`;
     }
     if (relativePath.startsWith(".agents/skills/")) {
@@ -1197,7 +1228,9 @@ function targetPathToManifestPath(relativePath, governanceRoot) {
 }
 async function readPackageVersion(assetRoot) {
     const packageJson = JSON.parse(await readFile(path.join(assetRoot, "package.json"), "utf-8"));
-    return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+    return typeof packageJson.version === "string"
+        ? packageJson.version
+        : "0.0.0";
 }
 async function readInitSurfaceManifest(assetRoot) {
     const manifestPath = path.join(assetRoot, "docs", "init-surface.manifest.json");
@@ -1275,6 +1308,7 @@ function inferInitSurfaceMode(relativePath) {
         return "managed-block";
     }
     if (relativePath === "harness.json" ||
+        relativePath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH ||
         relativePath.startsWith("scripts/") ||
         relativePath.startsWith(".harness/prompts/") ||
         relativePath.startsWith("docs/README.md") ||
@@ -1321,6 +1355,9 @@ async function buildDesiredSurfaceContent(input) {
             }), null, 2)}\n`,
         };
     }
+    if (manifestPath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH) {
+        return { content: buildOpenCodeTransientRetryPluginSource() };
+    }
     if (manifestPath.startsWith("scripts/")) {
         const scripts = buildInitScriptFiles(input.governanceRoot);
         return { content: scripts[manifestPath] };
@@ -1335,7 +1372,10 @@ async function buildDesiredSurfaceContent(input) {
         const sourceManifestPath = manifestPath.slice(".agents/".length);
         const mirrorSourcePath = path.join(input.assetRoot, sourceManifestPath);
         if (await exists(mirrorSourcePath)) {
-            return { content: await readFile(mirrorSourcePath, "utf-8"), sourcePath: mirrorSourcePath };
+            return {
+                content: await readFile(mirrorSourcePath, "utf-8"),
+                sourcePath: mirrorSourcePath,
+            };
         }
         return {};
     }
@@ -1350,7 +1390,10 @@ async function buildDesiredSurfaceContent(input) {
             return { content: generated };
         const mappedSourcePath = path.join(input.assetRoot, "docs", coreDocSourceForTarget(doc));
         if (await exists(mappedSourcePath)) {
-            return { content: await readFile(mappedSourcePath, "utf-8"), sourcePath: mappedSourcePath };
+            return {
+                content: await readFile(mappedSourcePath, "utf-8"),
+                sourcePath: mappedSourcePath,
+            };
         }
     }
     const sourcePath = path.join(input.assetRoot, manifestPath);
@@ -1392,7 +1435,10 @@ export async function readRecordedSurfaceControllerVersion(repoRoot) {
     }
     if (!state || typeof state.controllerVersion !== "string")
         return undefined;
-    return { controllerVersion: state.controllerVersion, stateKind: state.stateKind };
+    return {
+        controllerVersion: state.controllerVersion,
+        stateKind: state.stateKind,
+    };
 }
 async function buildCurrentSurfaceState(input) {
     const assetRoot = await findPackageRoot();
@@ -1401,7 +1447,10 @@ async function buildCurrentSurfaceState(input) {
     const files = {};
     for (const manifestEntry of manifest.entries) {
         const targetRelativePath = normalizeRelativePath(manifestPathToTargetPath(manifestEntry.path, input.governanceRoot));
-        const entry = { ...manifestEntry, path: targetRelativePath };
+        const entry = {
+            ...manifestEntry,
+            path: targetRelativePath,
+        };
         const targetPath = path.join(input.repoRoot, targetRelativePath);
         const targetStat = await stat(targetPath).catch(() => null);
         const desired = await buildDesiredSurfaceContent({
@@ -1416,7 +1465,9 @@ async function buildCurrentSurfaceState(input) {
             status: targetStat ? "present" : "missing",
             relationship: "missing-from-target",
             sourceSha256,
-            sourcePath: desired.sourcePath ? repoRelative(assetRoot, desired.sourcePath) : undefined,
+            sourcePath: desired.sourcePath
+                ? repoRelative(assetRoot, desired.sourcePath)
+                : undefined,
             mode: entry.mode,
         };
         if (entry.mode === "state") {
@@ -1434,7 +1485,9 @@ async function buildCurrentSurfaceState(input) {
         if (entry.mode === "directory") {
             files[targetRelativePath] = {
                 ...base,
-                relationship: targetStat.isDirectory() ? "directory-present" : "local-existing-unknown",
+                relationship: targetStat.isDirectory()
+                    ? "directory-present"
+                    : "local-existing-unknown",
             };
             continue;
         }
@@ -1448,14 +1501,17 @@ async function buildCurrentSurfaceState(input) {
             files[targetRelativePath] = {
                 ...base,
                 currentSha256,
-                relationship: currentBlock && sourceSha256 && sha256Text(currentBlock) === sourceSha256
+                relationship: currentBlock &&
+                    sourceSha256 &&
+                    sha256Text(currentBlock) === sourceSha256
                     ? "managed-block-current"
                     : "managed-block-present",
             };
             continue;
         }
         let semanticallyMatchesGeneratedJson = false;
-        if (targetRelativePath === "harness.json" && desired.content !== undefined) {
+        if (targetRelativePath === "harness.json" &&
+            desired.content !== undefined) {
             try {
                 semanticallyMatchesGeneratedJson = isDeepStrictEqual(JSON.parse(current.toString("utf-8")), JSON.parse(desired.content));
             }
@@ -1529,7 +1585,9 @@ async function listRelativeFiles(rootPath) {
     const files = [];
     async function walk(currentPath, relativeDir) {
         for (const entry of await readdir(currentPath, { withFileTypes: true })) {
-            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const relativePath = relativeDir
+                ? `${relativeDir}/${entry.name}`
+                : entry.name;
             const absolutePath = path.join(currentPath, entry.name);
             if (entry.isDirectory())
                 await walk(absolutePath, relativePath);
@@ -1558,7 +1616,8 @@ async function expectedLegacyInitFileSha(input) {
             }));
         }
     }
-    if (!input.legacyPath.startsWith("docs/") && !input.legacyPath.startsWith("skills/")) {
+    if (!input.legacyPath.startsWith("docs/") &&
+        !input.legacyPath.startsWith("skills/")) {
         return undefined;
     }
     if (input.legacyPath.startsWith("docs/")) {
@@ -1572,7 +1631,10 @@ function collectSafeRetiredDirectories(paths) {
     for (const retiredPath of paths) {
         let dir = path.posix.dirname(retiredPath);
         while (dir !== "." && dir !== "/") {
-            if (dir === "skills" || dir.startsWith("skills/") || dir === "docs" || dir.startsWith("docs/")) {
+            if (dir === "skills" ||
+                dir.startsWith("skills/") ||
+                dir === "docs" ||
+                dir.startsWith("docs/")) {
                 dirs.add(dir);
             }
             dir = path.posix.dirname(dir);
@@ -1583,28 +1645,24 @@ function collectSafeRetiredDirectories(paths) {
     return [...dirs].sort((left, right) => right.split("/").length - left.split("/").length);
 }
 function needsHarnessModelMigration(harness) {
-    if ("model" in harness || "models" in harness || "modelProfiles" in harness || "modelRouting" in harness) {
+    if ("model" in harness ||
+        "models" in harness ||
+        "modelProfiles" in harness ||
+        "modelRouting" in harness) {
         return true;
     }
     if (isRecord(harness.executors)) {
         if ("cursor" in harness.executors)
             return true;
         if (isRecord(harness.executors.pi)) {
-            return ("requiresApiKey" in harness.executors.pi ||
-                "defaultModel" in harness.executors.pi);
+            return "requiresApiKey" in harness.executors.pi;
         }
     }
     return false;
 }
 function migrateHarnessModelFields(harness) {
     const next = { ...harness };
-    const legacyModel = typeof next.model === "string"
-        ? next.model
-        : isRecord(next.executors) &&
-            isRecord(next.executors.pi) &&
-            typeof next.executors.pi.defaultModel === "string"
-            ? next.executors.pi.defaultModel
-            : undefined;
+    const legacyModel = typeof next.model === "string" ? next.model : undefined;
     delete next.model;
     delete next.models;
     delete next.modelProfiles;
@@ -1613,7 +1671,6 @@ function migrateHarnessModelFields(harness) {
     delete executors.cursor;
     const pi = isRecord(executors.pi) ? { ...executors.pi } : {};
     delete pi.requiresApiKey;
-    delete pi.defaultModel;
     if (legacyModel) {
         for (const level of ["LOW", "MED", "HIGH"]) {
             if (typeof pi[level] !== "string")
@@ -1769,7 +1826,9 @@ async function collectRetiredLayoutActions(input) {
 }
 async function resolveInitProjectContext(input) {
     const harness = await readJsonIfExists(path.join(input.repoRoot, "harness.json"));
-    const recordedGovernanceRoot = typeof harness.governanceRoot === "string" ? harness.governanceRoot : undefined;
+    const recordedGovernanceRoot = typeof harness.governanceRoot === "string"
+        ? harness.governanceRoot
+        : undefined;
     return {
         projectName: input.projectName ??
             (typeof harness.project === "string" ? harness.project : undefined) ??
@@ -1816,7 +1875,7 @@ function buildManagedReadmeBlock(input) {
         "默认使用 Agent DAG 作为实现工作流：",
         "",
         "```bash",
-        "loop-agent new-task <task-id> \"任务标题\"",
+        'loop-agent new-task <task-id> "任务标题"',
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
         "loop-agent dag run-task <task-id> --profile auto --strict-models",
@@ -2005,7 +2064,7 @@ function buildTargetDevelopmentPrinciples(input) {
         "Principle 1 covers **granularity** (one bounded block). This section covers **shape**: each slice should cross the real integration layers the work needs and leave an independently verifiable narrow loop.",
         "",
         "- Every slice needs its own acceptance criteria, verification commands, and failure conditions.",
-        "- Prefer vertical tracer bullets over horizontal layering. Paths like \"schema → API → UI → tests\" are *possible* examples only; do not assume every project has those layers.",
+        '- Prefer vertical tracer bullets over horizontal layering. Paths like "schema → API → UI → tests" are *possible* examples only; do not assume every project has those layers.',
         "- Horizontal anti-patterns: finish all of one layer before the next; or write every test first, then implement everything.",
         "- For behavior changes, use one failing test → minimal implementation → green → next behavior. Do not batch all RED then all GREEN.",
         "- Split large features into multiple independently runnable tasks/DAGs instead of one oversized writer across every layer.",
@@ -2048,7 +2107,7 @@ function buildTargetFeatureWorkflow(input) {
         "## Agent DAG Path",
         "",
         "```bash",
-        "loop-agent new-task <task-id> \"Task title\"",
+        'loop-agent new-task <task-id> "Task title"',
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
         "loop-agent dag run-task <task-id> --profile auto --strict-models",
@@ -2074,11 +2133,11 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "Set an explicit specialized `taskKind` in `.harness/tasks/<task-id>/task.json` only when the dedicated workflow itself is part of the task contract:",
         "",
-        "- `taskKind: \"frontend-implementation\"` explicitly selects the frontend DAG for compatibility or intentional override. Optional `frontendMock` config sets `policy: auto|required|disabled`, an existing `serviceRoot`, and generation-time-frozen `verifyCommands`; an unsafe or incomplete explicit required contract produces an assessment-only DAG with no writer, while a complete required contract adds Mock-specific verification only when trusted commands exist. Auto API tasks without a native service may use an existing browser interception harness or reversible request adapter, then continue through static and behavior verification.",
-        "- `taskKind: \"backend-test\"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project's pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.",
-        "- `taskKind: \"knowledge-sync\"` selects the Feature-scoped test-knowledge write-back DAG (collect → draft → validate → apply → pointer). Bind `featureId` in `task.json` (or hardConstraints / requirement text). It writes only under `features/<featureId>/…` after final verification evidence exists.",
-        "- `taskKind: \"knowledge-graph-bootstrap\"` selects the business knowledge-graph bootstrap DAG (preflight → inventory → propose → validate → review → gate → promote → materialize). AI writes only `knowledge/bootstrap/staging/**`; promote is merge-new-only.",
-        "- `taskKind: \"frontend-test\"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 20 (maximum 50); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case's token usage is recorded, marking them `blocked: token-budget-exhausted`. Generated browser startup uses `playwright-cli open --browser=chrome --headed <base-url>`; the generic playwright-cli skill is unchanged.",
+        '- `taskKind: "frontend-implementation"` explicitly selects the frontend DAG for compatibility or intentional override. Optional `frontendMock` config sets `policy: auto|required|disabled`, an existing `serviceRoot`, and generation-time-frozen `verifyCommands`; an unsafe or incomplete explicit required contract produces an assessment-only DAG with no writer, while a complete required contract adds Mock-specific verification only when trusted commands exist. Auto API tasks without a native service may use an existing browser interception harness or reversible request adapter, then continue through static and behavior verification.',
+        '- `taskKind: "backend-test"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project\'s pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.',
+        '- `taskKind: "knowledge-sync"` selects the Feature-scoped test-knowledge write-back DAG (collect → draft → validate → apply → pointer). Bind `featureId` in `task.json` (or hardConstraints / requirement text). It writes only under `features/<featureId>/…` after final verification evidence exists.',
+        '- `taskKind: "knowledge-graph-bootstrap"` selects the business knowledge-graph bootstrap DAG (preflight → inventory → propose → validate → review → gate → promote → materialize). AI writes only `knowledge/bootstrap/staging/**`; promote is merge-new-only.',
+        '- `taskKind: "frontend-test"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 20 (maximum 50); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case\'s token usage is recorded, marking them `blocked: token-budget-exhausted`. Generated browser startup uses `playwright-cli open --browser=chrome --headed <base-url>`; the generic playwright-cli skill is unchanged.',
         "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
         "",
         "Use the package-backed public knowledge CLI for graph operations. Do not require target projects to run package-only kb runtime scripts:",
@@ -2089,14 +2148,14 @@ function buildTargetFeatureWorkflow(input) {
         "loop-agent dag run-task <task-id>   # taskKind: knowledge-graph-bootstrap",
         "loop-agent knowledge query --mode by_feature --feature F-2026-004 --json",
         "loop-agent knowledge query --mode by_id --id SVC-order --json",
-        "loop-agent knowledge query --mode search --text \"keyword\" --json",
+        'loop-agent knowledge query --mode search --text "keyword" --json',
         "loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service <service>",
         "# review the prepared scope/staging; for a manual reviewed promotion:",
         "loop-agent knowledge graph-promote",
         "loop-agent knowledge graph-materialize",
         "```",
         "",
-        "Daily Feature test-knowledge write-back still uses `taskKind: \"knowledge-sync\"` with a bound `featureId`, separate from graph bootstrap/incremental entry points.",
+        'Daily Feature test-knowledge write-back still uses `taskKind: "knowledge-sync"` with a bound `featureId`, separate from graph bootstrap/incremental entry points.',
         "",
         "## Verification",
         "",
@@ -2196,11 +2255,16 @@ function buildGeneratedCoreDoc(input) {
                 governanceRoot: input.governanceRoot,
             });
         case "feature-workflow.md":
-            return buildTargetFeatureWorkflow({ governanceRoot: input.governanceRoot });
+            return buildTargetFeatureWorkflow({
+                governanceRoot: input.governanceRoot,
+            });
         case "verification-matrix.md":
             return buildTargetVerificationMatrix();
         case "loop-agent-harness.md":
-            return buildTargetLoopAgentHarness({ projectName: input.projectName, governanceRoot: input.governanceRoot });
+            return buildTargetLoopAgentHarness({
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            });
         default:
             return undefined;
     }
@@ -2258,7 +2322,7 @@ export function buildInitInstructions(input) {
         "",
         "## Apply Defaults",
         "",
-        "- Use the current loop-agent harness.json as the default template, but write target project name plus `adapter: \"loop-agent\"`.",
+        '- Use the current loop-agent harness.json as the default template, but write target project name plus `adapter: "loop-agent"`.',
         `- ${DAG_HARD_GATE_TRIGGER}`,
         "- Generate the target project's loop-agent script matrix from templates: structure check, docs index/link checks, active plan status, exec-plan index sync, harness runtime cleanliness, architecture boundaries, skill entry integrity, governance CI, project-test CI, and full CI.",
         "- Copy or project only stack-agnostic governance scripts. For project-specific verification, packaging, release, or maintenance commands, generate the target-project version from templates plus the target repository's actual files instead of copying loop-agent's own TypeScript-specific scripts.",
@@ -2326,7 +2390,9 @@ export async function initializeLoopAgentProject(options) {
     const existingHarness = await readJsonIfExists(path.join(repoRoot, "harness.json"));
     await mkdir(repoRoot, { recursive: true });
     const readmePath = path.join(repoRoot, "README.md");
-    const existingReadme = (await exists(readmePath)) ? await readFile(readmePath, "utf-8") : undefined;
+    const existingReadme = (await exists(readmePath))
+        ? await readFile(readmePath, "utf-8")
+        : undefined;
     const readmeContent = existingReadme
         ? mergeManagedBlock(existingReadme, buildManagedReadmeBlock({ projectName, governanceRoot }))
         : buildTargetReadme({ projectName, governanceRoot });
@@ -2355,7 +2421,9 @@ export async function initializeLoopAgentProject(options) {
         skipped,
     });
     const agentsPath = path.join(repoRoot, "AGENTS.md");
-    const existingAgents = (await exists(agentsPath)) ? await readFile(agentsPath, "utf-8") : `# AGENTS.md\n`;
+    const existingAgents = (await exists(agentsPath))
+        ? await readFile(agentsPath, "utf-8")
+        : `# AGENTS.md\n`;
     await writeText({
         repoRoot,
         relativePath: "AGENTS.md",
@@ -2377,7 +2445,11 @@ export async function initializeLoopAgentProject(options) {
         skipped,
     });
     for (const doc of CORE_DOC_FILES) {
-        const generated = buildGeneratedCoreDoc({ doc: doc.target, projectName, governanceRoot });
+        const generated = buildGeneratedCoreDoc({
+            doc: doc.target,
+            projectName,
+            governanceRoot,
+        });
         if (generated) {
             await writeTextIfMissing({
                 repoRoot,
@@ -2443,23 +2515,65 @@ export async function initializeLoopAgentProject(options) {
     }
     await ensureHarnessDirs(repoRoot, written);
     await writeCompatPrompts({ repoRoot, merge, written, skipped });
-    await writeInitSurfaceState({ repoRoot, projectName, governanceRoot, stateKind: "recorded" });
+    const clientRecoveryMode = options.clientRecovery ?? "auto";
+    const clientRecovery = clientRecoveryMode === "off"
+        ? undefined
+        : await runClientRecovery({
+            repoRoot,
+            mode: clientRecoveryMode,
+        });
+    if (clientRecovery?.plugin.written) {
+        written.push(OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH);
+    }
+    else if (clientRecoveryMode === "off") {
+        skipped.push(OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH);
+    }
+    await writeInitSurfaceState({
+        repoRoot,
+        projectName,
+        governanceRoot,
+        stateKind: "recorded",
+    });
     written.push(INIT_SURFACE_STATE_PATH);
-    return { repoRoot, projectName, governanceRoot, profile, written, skipped };
+    return {
+        repoRoot,
+        projectName,
+        governanceRoot,
+        profile,
+        written,
+        skipped,
+        clientRecovery,
+    };
 }
 function actionForMissing(pathName, state) {
     if (state.mode === "state")
         return undefined;
     if (state.mode === "directory") {
-        return { type: "create-directory", path: pathName, reason: "required init directory is missing" };
+        return {
+            type: "create-directory",
+            path: pathName,
+            reason: "required init directory is missing",
+        };
     }
     if (state.mode === "copied") {
-        return { type: "copy-missing", path: pathName, reason: "required bundled init file is missing" };
+        return {
+            type: "copy-missing",
+            path: pathName,
+            reason: "required bundled init file is missing",
+        };
     }
     if (state.mode === "generated") {
-        return { type: "write-generated-missing", path: pathName, reason: "required generated init file is missing" };
+        return {
+            type: "write-generated-missing",
+            path: pathName,
+            reason: "required generated init file is missing",
+        };
     }
-    return { type: "refresh-managed-block", path: pathName, reason: "managed block file is missing or stale" };
+    return {
+        type: "refresh-managed-block",
+        path: pathName,
+        reason: "managed block file is missing or stale",
+    };
 }
 function modelMergeTaskFor(pathName, state, allPaths) {
     return {
@@ -2609,7 +2723,8 @@ export async function checkInitUpdate(input) {
             if (recordedState &&
                 isRecord(harness) &&
                 governanceRoot !== "docs" &&
-                (harness.governanceRoot === "docs" || hasLegacyHarnessGovernancePaths(harness))) {
+                (harness.governanceRoot === "docs" ||
+                    hasLegacyHarnessGovernancePaths(harness))) {
                 deterministicActions.push({
                     type: "migrate-harness-governance-root",
                     path: "harness.json",
@@ -2642,12 +2757,19 @@ export async function checkInitUpdate(input) {
         },
     };
     const recommendedNext = recommendedNextFor(partial);
+    // Pi user config is never part of project surface hash; only report semantics.
+    const piInspection = await inspectPiRetryConfig({
+        homeDir: input.homeDir,
+    });
     return {
         ...partial,
         ok: deterministicActions.length === 0 &&
             modelMergeTasks.length === 0 &&
             humanDecisions.length === 0,
         recommendedNext,
+        clientRecovery: {
+            pi: piInspection,
+        },
     };
 }
 async function applySafeAction(input) {
@@ -2672,7 +2794,9 @@ async function applySafeAction(input) {
         if (!(await exists(target)))
             return false;
         const harness = JSON.parse(await readFile(target, "utf-8"));
-        if (!isRecord(harness) || !isRecord(harness.executors) || !isRecord(harness.executors.pi)) {
+        if (!isRecord(harness) ||
+            !isRecord(harness.executors) ||
+            !isRecord(harness.executors.pi)) {
             return false;
         }
         if (!Object.hasOwn(harness.executors.pi, "requiresApiKey")) {
@@ -2706,7 +2830,8 @@ async function applySafeAction(input) {
             return false;
         const harness = JSON.parse(await readFile(target, "utf-8"));
         if (!isRecord(harness) ||
-            (harness.governanceRoot !== "docs" && !hasLegacyHarnessGovernancePaths(harness))) {
+            (harness.governanceRoot !== "docs" &&
+                !hasLegacyHarnessGovernancePaths(harness))) {
             return false;
         }
         const next = {
@@ -2782,11 +2907,16 @@ async function applySafeAction(input) {
         return false;
     await mkdir(path.dirname(target), { recursive: true });
     if (input.action.type === "refresh-managed-block") {
-        const existing = (await exists(target)) ? await readFile(target, "utf-8") : "";
+        const existing = (await exists(target))
+            ? await readFile(target, "utf-8")
+            : "";
         const next = input.action.path === ".gitignore"
             ? mergeGitignoreManagedBlock(existing, desired.content)
             : input.action.path === "README.md" && existing.trim().length === 0
-                ? buildTargetReadme({ projectName: input.projectName, governanceRoot: input.governanceRoot })
+                ? buildTargetReadme({
+                    projectName: input.projectName,
+                    governanceRoot: input.governanceRoot,
+                })
                 : input.action.path === "AGENTS.md" && existing.trim().length === 0
                     ? `# AGENTS.md\n\n${desired.content}\n`
                     : mergeManagedBlock(existing, desired.content);
@@ -2811,8 +2941,14 @@ export async function applyInitUpdate(input) {
     });
     const applied = [];
     const skipped = [];
+    const clientRecoveryMode = input.clientRecovery ?? "auto";
     if (input.bootstrapSurface) {
-        await writeInitSurfaceState({ repoRoot, projectName, governanceRoot, stateKind: "inferred-baseline" });
+        await writeInitSurfaceState({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            stateKind: "inferred-baseline",
+        });
         applied.push({
             type: "bootstrap-surface",
             path: INIT_SURFACE_STATE_PATH,
@@ -2823,8 +2959,16 @@ export async function applyInitUpdate(input) {
         const existingSurface = await readExistingSurfaceState(repoRoot);
         // Preserve source strength: recorded stays recorded so unchanged owned files
         // remain deterministic refresh candidates; bootstrap/inferred stays inferred.
-        const preservedStateKind = existingSurface?.stateKind === "recorded" ? "recorded" : "inferred-baseline";
-        const report = await checkInitUpdate({ repoRoot, projectName, governanceRoot });
+        const preservedStateKind = existingSurface?.stateKind === "recorded"
+            ? "recorded"
+            : "inferred-baseline";
+        const report = await checkInitUpdate({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            clientRecovery: clientRecoveryMode,
+            homeDir: input.homeDir,
+        });
         for (const action of report.deterministicActions) {
             if (action.type === "bootstrap-surface") {
                 skipped.push(action);
@@ -2846,12 +2990,36 @@ export async function applyInitUpdate(input) {
             preserveOwnershipFrom: existingSurface,
         });
     }
+    // Pi user config is only mutated with explicit --client-recovery=user.
+    // Do not reinstall the project plugin here — that would bypass ownership and
+    // clobber user-modified plugins; plugin updates stay on deterministic actions.
+    if (clientRecoveryMode === "user") {
+        await applyPiRetryMerge({
+            homeDir: input.homeDir ?? os.homedir(),
+        });
+    }
     return {
         applied,
         skipped,
-        report: await checkInitUpdate({ repoRoot, projectName, governanceRoot }),
+        report: await checkInitUpdate({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            clientRecovery: clientRecoveryMode,
+            homeDir: input.homeDir,
+        }),
     };
 }
+function formatClientRecoverySummary(report) {
+    if (!report.clientRecovery?.pi)
+        return [];
+    const pi = report.clientRecovery.pi;
+    return [
+        `clientRecovery.pi.reason: ${pi.reason}`,
+        `clientRecovery.pi.action: ${pi.action}`,
+        `clientRecovery.pi.path: ${pi.path}`,
+    ];
+}
 function formatCheckUpdateText(report) {
     return [
         `loop-agent init update check for ${report.repoRoot}`,
@@ -2860,17 +3028,22 @@ function formatCheckUpdateText(report) {
         `deterministicActions: ${report.deterministicActions.length}`,
         `modelMergeTasks: ${report.modelMergeTasks.length}`,
         `humanDecisions: ${report.humanDecisions.length}`,
+        ...formatClientRecoverySummary(report),
         "recommendedNext:",
         ...report.recommendedNext.map((item) => `- ${item}`),
     ].join("\n");
 }
 function formatCheckUpdateMarkdown(report) {
+    const piLines = formatClientRecoverySummary(report).map((line) => `- ${line}`);
     const lines = [
         "# loop-agent init check-update",
         "",
         `- repoRoot: \`${report.repoRoot}\``,
         `- controllerVersion: \`${report.controllerVersion}\``,
         `- surfaceState: \`${report.surfaceState}\``,
+        ...(piLines.length > 0
+            ? ["", "## Client Recovery (Pi user config, read-only)", "", ...piLines]
+            : []),
         "",
         "## Deterministic Actions",
         "",
@@ -2907,21 +3080,29 @@ export async function runInitDoctor(input) {
         add("harness.json", false, error instanceof Error ? error.message : String(error));
     }
     const agents = path.join(repoRoot, "AGENTS.md");
-    add("AGENTS.md loop-agent block", (await exists(agents)) && (await readFile(agents, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
+    add("AGENTS.md loop-agent block", (await exists(agents)) &&
+        (await readFile(agents, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
     const readme = path.join(repoRoot, "README.md");
-    add("README loop-agent block", (await exists(readme)) && (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
+    add("README loop-agent block", (await exists(readme)) &&
+        (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
     add("repo-local skills", await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md")), ".agents/skills/loop-agent/SKILL.md");
     const gitignorePath = path.join(repoRoot, ".gitignore");
-    const gitignoreContent = (await exists(gitignorePath)) ? await readFile(gitignorePath, "utf-8") : "";
-    add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) && gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
+    const gitignoreContent = (await exists(gitignorePath))
+        ? await readFile(gitignorePath, "utf-8")
+        : "";
+    add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) &&
+        gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
     const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
     const missingScripts = [];
     for (const script of requiredScripts) {
         if (!(await exists(path.join(repoRoot, script))))
             missingScripts.push(script);
     }
-    add("script matrix", missingScripts.length === 0, missingScripts.length === 0 ? `${requiredScripts.length} scripts` : `missing: ${missingScripts.join(", ")}`);
-    add("compat prompts", await exists(path.join(repoRoot, ".harness", "prompts", "analyze.md")) && await exists(path.join(repoRoot, ".harness", "prompts", "plan.md")), ".harness/prompts/analyze.md");
+    add("script matrix", missingScripts.length === 0, missingScripts.length === 0
+        ? `${requiredScripts.length} scripts`
+        : `missing: ${missingScripts.join(", ")}`);
+    add("compat prompts", (await exists(path.join(repoRoot, ".harness", "prompts", "analyze.md"))) &&
+        (await exists(path.join(repoRoot, ".harness", "prompts", "plan.md"))), ".harness/prompts/analyze.md");
     add("harness runtime dirs", await exists(path.join(repoRoot, ".harness", "dag-runs", "active")), ".harness/dag-runs/active");
     return {
         ok: checks.every((check) => check.ok),
@@ -2961,7 +3142,12 @@ export async function runInitReconcile(input) {
         : update.report.modelMergeTasks.length > 0
             ? "needs-model-merge"
             : "needs-safe-update";
-    return { status, report: update.report, applied: update.applied, skipped: update.skipped };
+    return {
+        status,
+        report: update.report,
+        applied: update.applied,
+        skipped: update.skipped,
+    };
 }
 function parseInitArgs(repoRoot, args) {
     let subcommand;
@@ -2971,13 +3157,19 @@ function parseInitArgs(repoRoot, args) {
     let merge = true;
     let provider;
     let model;
+    let clientRecovery = "auto";
     let json = false;
     let markdown = false;
     let bootstrapSurface = false;
     let applySafe = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
-        if ((arg === "instructions" || arg === "doctor" || arg === "check-update" || arg === "update" || arg === "reconcile") && !subcommand) {
+        if ((arg === "instructions" ||
+            arg === "doctor" ||
+            arg === "check-update" ||
+            arg === "update" ||
+            arg === "reconcile") &&
+            !subcommand) {
             subcommand = arg;
             continue;
         }
@@ -3005,6 +3197,10 @@ function parseInitArgs(repoRoot, args) {
             model = args[++i];
         else if (arg.startsWith("--model="))
             model = arg.slice("--model=".length);
+        else if (arg === "--client-recovery")
+            clientRecovery = parseClientRecoveryMode(args[++i]);
+        else if (arg.startsWith("--client-recovery="))
+            clientRecovery = parseClientRecoveryMode(arg.slice("--client-recovery=".length));
         else if (arg === "--json")
             json = true;
         else if (arg === "--markdown")
@@ -3028,6 +3224,7 @@ function parseInitArgs(repoRoot, args) {
         merge,
         provider,
         model,
+        clientRecovery,
         subcommand,
         json,
         markdown,
@@ -3063,7 +3260,9 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
             throw new Error("usage: init update [--bootstrap-surface] [--apply-safe]");
         }
         const result = await applyInitUpdate(parsed);
-        console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitUpdateResult(result));
+        console.log(parsed.json
+            ? JSON.stringify(result, null, 2)
+            : formatInitUpdateResult(result));
         return;
     }
     if (parsed.subcommand === "reconcile") {
@@ -3071,7 +3270,9 @@ export async function runInit(repoRoot, rawArgs, dependencies) {
             ...parsed,
             readRuntimeActivity: dependencies.readRuntimeActivity,
         });
-        console.log(parsed.json ? JSON.stringify(result, null, 2) : formatReconcileResult(result));
+        console.log(parsed.json
+            ? JSON.stringify(result, null, 2)
+            : formatReconcileResult(result));
         return;
     }
     const result = await initializeLoopAgentProject(parsed);