@tea-agent/loop-agent 0.25.2 → 0.25.3

package/AGENTS.md

@@ -60,6 +60,7 @@
 - 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
 - init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
 - CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
+- 明确的前端页面/UI/组件/交互实现需求必须设置 `taskKind: "frontend-implementation"`（不是 `--profile`），不得保留默认 `standard`；浏览器/UI 自动化测试继续使用 `taskKind: "frontend-test"`。
 - 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
 
 ## 验证

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.25.3] - 2026-07-30
+
+### 重点更新
+
+- 新增 OpenCode 客户端瞬态会话恢复机制，在内置重试遗漏时自动补偿 UnknownError
+- 优化前端实现需求路由，将前端开发与测试任务准确分发至对应 DAG 流程
+
+### 新增
+
+- loop-agent init 支持 --client-recovery 参数，可在目标项目生成 OpenCode 插件以补偿瞬态 UnknownError
+- 支持在用户级别原子写入 Pi retry 推荐配置，并严格遵守插件 ownership 不覆盖用户改动
+
+### 改进
+
+- 初始化或刷新 AGENTS.md 时，要求将明确的前端实现需求路由至 frontend-implementation，与浏览器和 UI 自动化测试区分开
+
+### 修复
+
+- 修复生成的 OpenCode 恢复插件无法按真实 API 工作的问题，现直接返回 Hooks.event 并按事件正确分发与续接
+- 修复 Type validation failed 等真实错误被业务校验规则误杀的问题
+- 修复 Pi retry 配置读取将权限或 I/O 错误误判为缺文件的问题，现仅 ENOENT 视为缺文件
+
 ## [0.25.2] - 2026-07-30
 
 ### 重点更新

package/dist/cli/command-definitions.js

@@ -216,7 +216,7 @@ export const COMMAND_DEFINITIONS = [
         adapter: "none",
         tier: "primary",
         intent: "Initialize a target repository with loop-agent harness capabilities.",
-        usage: "init [instructions|doctor|check-update|update|reconcile] [--profile full|minimal] [--merge] [--json|--markdown] [--bootstrap-surface|--apply-safe]",
+        usage: "init [instructions|doctor|check-update|update|reconcile] [--profile full|minimal] [--merge] [--json|--markdown] [--bootstrap-surface|--apply-safe] [--client-recovery=auto|project|user|off]",
         subcommands: [...INIT_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
             await runInit(repoRoot, [subcommand, ...rest].filter(Boolean), { readRuntimeActivity: readInitRuntimeActivity });

package/dist/cli/program.js

@@ -617,7 +617,8 @@ export function buildLoopAgentProgram(options) {
                 .option("--json", "print JSON")
                 .option("--markdown", "print Markdown")
                 .option("--bootstrap-surface", "write an inferred .harness/init-surface.json baseline")
-                .option("--apply-safe", "apply deterministic safe init updates");
+                .option("--apply-safe", "apply deterministic safe init updates")
+                .option("--client-recovery <mode>", "auto|project|user|off — OpenCode project plugin and optional Pi user retry config", "auto");
             command.action(async (args, _options, actionCommand) => runInitCommand(args, actionCommand, options.defaultRepoRoot));
             addStandaloneSubcommands(command, entry.subcommands ?? [], (args, actionCommand) => runInitCommand(args, actionCommand, options.defaultRepoRoot));
             program.addCommand(command);

package/dist/commands/client-recovery.js

@@ -0,0 +1,657 @@
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const CLIENT_RECOVERY_MODES = ["auto", "project", "user", "off"];
+export const OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH = ".opencode/plugins/loop-agent-transient-retry.js";
+export const PERMANENT_ERROR_INTERACTION = "plugin-ignore-permanent-error";
+export const BACKOFF_MS = [2000, 4000, 8000, 16000, 30000];
+export const MAX_SESSION_RETRIES = 5;
+export const PI_RECOMMENDED_RETRY = {
+    enabled: true,
+    maxRetries: 5,
+    baseDelayMs: 3000,
+    provider: {
+        maxRetries: 0,
+        maxRetryDelayMs: 60000,
+    },
+};
+const PERMANENT_MESSAGE_PATTERNS = [
+    { reason: "auth", pattern: /\b(401|unauthorized|invalid api key|authentication)\b/i },
+    { reason: "permission", pattern: /\b(403|forbidden|permission denied|not allowed)\b/i },
+    { reason: "quota", pattern: /\b(quota|rate.?limit|billing|insufficient.?credit)\b/i },
+    {
+        reason: "context-overflow",
+        pattern: /\b(context (length )?overflow|too many tokens|maximum context|context window)\b/i,
+    },
+    { reason: "cancelled", pattern: /\b(cancelled|canceled|aborted by user|user cancel)\b/i },
+    {
+        reason: "business-validation",
+        pattern: /\b(business validation|invalid task|schema validation)\b/i,
+    },
+];
+const TRANSIENT_MESSAGE_PATTERNS = [
+    /\bcode[:\s]*502\b/i,
+    /\b502\b/,
+    /\bLLMRequestError\b/i,
+    /\bTypeValidationError\b/i,
+    /\bnetwork fluctuation\b/i,
+    /\btimeout\b/i,
+    /\btransient provider failure\b/i,
+    /\bnon-standard (payload|response)\b/i,
+    /\bupstream returned\b/i,
+    /\bmodel processing timeout\b/i,
+];
+export function isClientRecoveryMode(value) {
+    return (typeof value === "string" &&
+        CLIENT_RECOVERY_MODES.includes(value));
+}
+export function parseClientRecoveryMode(value) {
+    if (value === undefined || value === null || value === "")
+        return "auto";
+    if (isClientRecoveryMode(value))
+        return value;
+    throw new Error(`init --client-recovery must be one of ${CLIENT_RECOVERY_MODES.join("|")}`);
+}
+function asText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function collectErrorText(error) {
+    if (typeof error === "string")
+        return error;
+    if (!error || typeof error !== "object")
+        return asText(error);
+    const record = error;
+    const parts = [
+        asText(record.name),
+        asText(record.message),
+        asText(record.status),
+        asText(record.code),
+        asText(record.data),
+    ];
+    return parts.filter(Boolean).join(" ");
+}
+function hasUnknownErrorShape(error) {
+    const text = collectErrorText(error);
+    if (/\bUnknownError\b/i.test(text))
+        return true;
+    if (error && typeof error === "object") {
+        const record = error;
+        if (typeof record.name === "string" && /UnknownError/i.test(record.name))
+            return true;
+    }
+    return false;
+}
+function isStandardApiError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const record = error;
+    if (typeof record.name === "string" && /^APIError$/i.test(record.name))
+        return true;
+    if (typeof record.name === "string" && /^(AuthError|PermissionError)$/i.test(record.name)) {
+        return true;
+    }
+    return false;
+}
+function permanentReason(error) {
+    if (isStandardApiError(error)) {
+        const record = error;
+        if (typeof record.name === "string" && /AuthError/i.test(record.name))
+            return "auth";
+        if (typeof record.name === "string" && /PermissionError/i.test(record.name)) {
+            return "permission";
+        }
+        return "api-error";
+    }
+    const text = collectErrorText(error);
+    for (const entry of PERMANENT_MESSAGE_PATTERNS) {
+        if (entry.pattern.test(text))
+            return entry.reason;
+    }
+    return undefined;
+}
+function looksTransient(error) {
+    const text = collectErrorText(error);
+    if (TRANSIENT_MESSAGE_PATTERNS.some((pattern) => pattern.test(text)))
+        return true;
+    if (error && typeof error === "object") {
+        const record = error;
+        if (record.code === 502 || record.status === 502)
+            return true;
+        if (record.data && typeof record.data === "object") {
+            const data = record.data;
+            if (data.code === 502 || data.status === 502)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide whether an OpenCode error should be resumed by the project plugin.
+ * Only compensates transient UnknownError paths that built-in APIError retry misses.
+ */
+export function classifyTransientUnknownError(error) {
+    const permanent = permanentReason(error);
+    if (permanent) {
+        return {
+            resumable: false,
+            reason: permanent,
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    if (!hasUnknownErrorShape(error)) {
+        return {
+            resumable: false,
+            reason: "not-unknown-error",
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    if (!looksTransient(error)) {
+        return {
+            resumable: false,
+            reason: "unknown-non-transient",
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    return { resumable: true, reason: "transient-unknown-error" };
+}
+export function nextBackoffMs(attempt) {
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt >= BACKOFF_MS.length) {
+        return undefined;
+    }
+    return BACKOFF_MS[attempt];
+}
+export function canResumeSession(input) {
+    if (input.sessionStatus === "retry") {
+        return { allowed: false, reason: "builtin-retry-active" };
+    }
+    if (input.locked) {
+        return { allowed: false, reason: "session-locked" };
+    }
+    if (!input.idle || input.sessionStatus === "busy" || input.sessionStatus === "running") {
+        return { allowed: false, reason: "session-busy" };
+    }
+    if (input.attempt >= MAX_SESSION_RETRIES) {
+        return { allowed: false, reason: "max-retries" };
+    }
+    return { allowed: true, reason: "ready" };
+}
+export function buildResumePrompt(input) {
+    return [
+        `[loop-agent transient recovery] session=${input.sessionId} attempt=${input.attempt}`,
+        `Previous model turn failed with a transient UnknownError: ${input.errorSummary}`,
+        "Before continuing any work, first inspect already completed tool calls and existing file modifications in this session.",
+        "Do not re-run side-effecting tools or rewrite files that already reflect successful prior work.",
+        "Resume only the remaining unfinished work after that check.",
+        "续接前请先检查本 session 已有工具调用与文件改动，避免重复执行有副作用的操作。",
+    ].join("\n");
+}
+export function createSessionRecoveryTracker() {
+    const states = new Map();
+    function getOrCreate(sessionId) {
+        let state = states.get(sessionId);
+        if (!state) {
+            state = { attempt: 0, locked: false };
+            states.set(sessionId, state);
+        }
+        return state;
+    }
+    return {
+        getOrCreate,
+        isLocked(sessionId) {
+            return getOrCreate(sessionId).locked;
+        },
+        tryAcquire(sessionId) {
+            const state = getOrCreate(sessionId);
+            if (state.locked)
+                return false;
+            state.locked = true;
+            return true;
+        },
+        release(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.locked = false;
+        },
+        markSuccess(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.attempt = 0;
+            state.locked = false;
+        },
+        incrementAttempt(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.attempt += 1;
+            return state.attempt;
+        },
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readRetryEnabled(existing) {
+    if (!existing || !isRecord(existing.retry))
+        return undefined;
+    if (typeof existing.retry.enabled !== "boolean")
+        return undefined;
+    return existing.retry.enabled;
+}
+/**
+ * Field-level plan for ~/.pi/agent/settings.json retry recommendations.
+ * Never clobbers existing values; never overrides enabled:false.
+ */
+export function planPiRetryMerge(existing) {
+    const settingsPath = "~/.pi/agent/settings.json";
+    if (existing === undefined) {
+        return {
+            action: "write",
+            reason: "missing-file",
+            path: settingsPath,
+            next: { retry: { ...PI_RECOMMENDED_RETRY, provider: { ...PI_RECOMMENDED_RETRY.provider } } },
+        };
+    }
+    if (!isRecord(existing)) {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            message: "Pi settings root must be a JSON object",
+        };
+    }
+    const enabled = readRetryEnabled(existing);
+    if (enabled === false) {
+        return {
+            action: "report",
+            reason: "enabled-false",
+            path: settingsPath,
+            next: existing,
+            message: "retry.enabled=false is preserved; human decision required to enable recovery",
+        };
+    }
+    const retry = isRecord(existing.retry) ? { ...existing.retry } : {};
+    const provider = isRecord(retry.provider) ? { ...retry.provider } : {};
+    let changed = !isRecord(existing.retry) || !isRecord(existing.retry.provider);
+    if (retry.enabled === undefined) {
+        retry.enabled = PI_RECOMMENDED_RETRY.enabled;
+        changed = true;
+    }
+    if (retry.maxRetries === undefined) {
+        retry.maxRetries = PI_RECOMMENDED_RETRY.maxRetries;
+        changed = true;
+    }
+    if (retry.baseDelayMs === undefined) {
+        retry.baseDelayMs = PI_RECOMMENDED_RETRY.baseDelayMs;
+        changed = true;
+    }
+    if (provider.maxRetries === undefined) {
+        provider.maxRetries = PI_RECOMMENDED_RETRY.provider.maxRetries;
+        changed = true;
+    }
+    if (provider.maxRetryDelayMs === undefined) {
+        provider.maxRetryDelayMs = PI_RECOMMENDED_RETRY.provider.maxRetryDelayMs;
+        changed = true;
+    }
+    retry.provider = provider;
+    const next = { ...existing, retry };
+    if (!changed) {
+        return {
+            action: "noop",
+            reason: "matches",
+            path: settingsPath,
+            next,
+        };
+    }
+    return {
+        action: "write",
+        reason: "missing-fields",
+        path: settingsPath,
+        next,
+    };
+}
+export function piSettingsPath(homeDir) {
+    return path.join(homeDir, ".pi", "agent", "settings.json");
+}
+async function writeJsonAtomicHome(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function applyPiRetryMerge(input) {
+    const settingsPath = piSettingsPath(input.homeDir);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        raw = undefined;
+    }
+    if (raw === undefined) {
+        const plan = planPiRetryMerge(undefined);
+        if (plan.action === "write" && plan.next) {
+            await writeJsonAtomicHome(settingsPath, plan.next);
+            return { ...plan, path: settingsPath, wrote: true };
+        }
+        return { ...plan, path: settingsPath, wrote: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+            message: "Pi settings.json is not valid JSON; refusing to write",
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+            message: "Pi settings.json root must be a JSON object; refusing to write",
+        };
+    }
+    const plan = planPiRetryMerge(parsed);
+    if (plan.action === "write" && plan.next) {
+        await writeJsonAtomicHome(settingsPath, plan.next);
+        // Best-effort cleanup of any stray temp files from interrupted prior runs.
+        try {
+            const dir = path.dirname(settingsPath);
+            const entries = await readdir(dir);
+            await Promise.all(entries
+                .filter((name) => name.startsWith(`.${path.basename(settingsPath)}.`) && name.endsWith(".tmp"))
+                .map((name) => rm(path.join(dir, name), { force: true })));
+        }
+        catch {
+            // ignore cleanup failures
+        }
+        return { ...plan, path: settingsPath, wrote: true };
+    }
+    return { ...plan, path: settingsPath, wrote: false };
+}
+/**
+ * Stable generated source for the OpenCode project plugin.
+ * The plugin compensates only transient UnknownError after built-in retry is idle.
+ */
+export function buildOpenCodeTransientRetryPluginSource() {
+    // Keep this template deterministic: no timestamps, no random ids.
+    return `/**
+ * loop-agent OpenCode transient recovery plugin
+ * Path: ${OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH}
+ *
+ * Compensates transient UnknownError cases that OpenCode built-in APIError
+ * retry does not cover. Never runs concurrently with session.status === "retry".
+ * Permanent failures use interaction "${PERMANENT_ERROR_INTERACTION}".
+ */
+const PLUGIN_PATH = ${JSON.stringify(OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH)};
+const PERMANENT_INTERACTION = ${JSON.stringify(PERMANENT_ERROR_INTERACTION)};
+const BACKOFF_MS = ${JSON.stringify([...BACKOFF_MS])};
+const MAX_RETRIES = ${MAX_SESSION_RETRIES};
+
+const sessionState = new Map();
+const sessionStatus = new Map();
+
+function getState(sessionId) {
+  let state = sessionState.get(sessionId);
+  if (!state) {
+    state = { attempt: 0, locked: false };
+    sessionState.set(sessionId, state);
+  }
+  return state;
+}
+
+function textOf(error) {
+  if (!error) return "";
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+function isPermanent(error) {
+  const text = textOf(error);
+  if (error && typeof error === "object" && typeof error.name === "string") {
+    if (/^APIError$/i.test(error.name)) return true;
+    if (/^(AuthError|PermissionError)$/i.test(error.name)) return true;
+  }
+  return /\\b(401|403|unauthorized|forbidden|quota|rate.?limit|context (length )?overflow|too many tokens|cancelled|canceled|business validation|invalid task|schema validation)\\b/i.test(
+    text,
+  );
+}
+
+function isTransientUnknown(error) {
+  if (isPermanent(error)) return false;
+  const text = textOf(error);
+  const hasUnknown = /UnknownError/i.test(text) || (error && /UnknownError/i.test(String(error.name || "")));
+  if (!hasUnknown) return false;
+  return (
+    /\\b(code[:\\s]*502|502|LLMRequestError|TypeValidationError|Type validation failed|network fluctuation|timeout|transient provider failure|non-standard)\\b/i.test(
+      text,
+    ) ||
+    (error && (error.code === 502 || error.status === 502))
+  );
+}
+
+function buildResumePrompt(sessionId, error, attempt) {
+  return [
+    "[loop-agent transient recovery] session=" + sessionId + " attempt=" + attempt,
+    "Previous model turn failed with a transient UnknownError: " + textOf(error),
+    "Before continuing any work, first inspect already completed tool calls and existing file modifications in this session.",
+    "Do not re-run side-effecting tools or rewrite files that already reflect successful prior work.",
+    "Resume only the remaining unfinished work after that check.",
+    "续接前请先检查本 session 已有工具调用与文件改动，避免重复执行有副作用的操作。",
+  ].join("\\n");
+}
+
+async function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function statusType(status) {
+  return status && typeof status.type === "string" ? status.type : undefined;
+}
+
+async function readSessionStatus(client, sessionId) {
+  const cached = sessionStatus.get(sessionId);
+  if (cached === "retry") return cached;
+  try {
+    const response = await client.session.status();
+    const current = statusType(response?.data?.[sessionId]);
+    if (current) sessionStatus.set(sessionId, current);
+    return current || cached || "idle";
+  } catch {
+    return cached || "idle";
+  }
+}
+
+export default async function loopAgentTransientRetryPlugin({ client, $ }) {
+  void $;
+  void PLUGIN_PATH;
+
+  async function maybeResume(sessionId, error) {
+    if (!sessionId) return { interaction: PERMANENT_INTERACTION, reason: "missing-session" };
+    if (!isTransientUnknown(error)) {
+      return { interaction: PERMANENT_INTERACTION, reason: "plugin-ignore-permanent-error" };
+    }
+
+    const state = getState(sessionId);
+    if (state.locked) {
+      return { interaction: PERMANENT_INTERACTION, reason: "session-locked" };
+    }
+    if (state.attempt >= MAX_RETRIES) {
+      return { interaction: PERMANENT_INTERACTION, reason: "max-retries" };
+    }
+
+    state.locked = true;
+    try {
+      let status = await readSessionStatus(client, sessionId);
+      // Never race OpenCode built-in retry.
+      if (status === "retry") {
+        return { interaction: PERMANENT_INTERACTION, reason: "builtin-retry-active" };
+      }
+      if (status === "busy" || status === "running") {
+        return { interaction: PERMANENT_INTERACTION, reason: "session-busy" };
+      }
+
+      const delay = BACKOFF_MS[state.attempt];
+      const nextAttempt = state.attempt + 1;
+      if (typeof delay === "number") await wait(delay);
+      // Re-check idle after backoff.
+      status = await readSessionStatus(client, sessionId);
+      if (status === "retry" || status === "busy" || status === "running") {
+        return { interaction: PERMANENT_INTERACTION, reason: "session-not-idle" };
+      }
+      const prompt = buildResumePrompt(sessionId, error, nextAttempt);
+      state.attempt = nextAttempt;
+      await client.session.promptAsync({
+        path: { id: sessionId },
+        body: { parts: [{ type: "text", text: prompt }] },
+      });
+      return { resumed: true, attempt: state.attempt };
+    } finally {
+      state.locked = false;
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (!event || typeof event !== "object") return;
+      const properties = event.properties || {};
+      const sessionId =
+        properties.sessionID || properties.sessionId || properties.id;
+
+      if (event.type === "session.status") {
+        const current = statusType(properties.status);
+        if (sessionId && current) sessionStatus.set(sessionId, current);
+        return;
+      }
+
+      if (event.type === "message.updated") {
+        const info = properties.info;
+        if (
+          info?.role === "assistant" &&
+          info.sessionID &&
+          info.time?.completed != null &&
+          info.error == null
+        ) {
+          getState(info.sessionID).attempt = 0;
+        }
+        return;
+      }
+
+      if (event.type === "session.error") {
+        return maybeResume(sessionId, properties.error || properties);
+      }
+    },
+  };
+}
+`;
+}
+export async function installProjectOpenCodePlugin(input) {
+    const relativePath = OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH;
+    const target = path.join(input.repoRoot, relativePath);
+    const content = buildOpenCodeTransientRetryPluginSource();
+    if (input.onlyIfMissing) {
+        try {
+            await readFile(target, "utf-8");
+            return { path: relativePath, written: false, reason: "unchanged" };
+        }
+        catch {
+            // missing → write
+        }
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, content, "utf-8");
+    return { path: relativePath, written: true, reason: "written" };
+}
+export async function inspectPiRetryConfig(input) {
+    const homeDir = input.homeDir ?? os.homedir();
+    const settingsPath = piSettingsPath(homeDir);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        return {
+            action: "report",
+            reason: "missing-file",
+            path: settingsPath,
+            wrote: false,
+        };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            return {
+                action: "report",
+                reason: "invalid-json",
+                path: settingsPath,
+                wrote: false,
+            };
+        }
+        const plan = planPiRetryMerge(parsed);
+        return { ...plan, path: settingsPath, wrote: false };
+    }
+    catch {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+        };
+    }
+}
+/**
+ * Install project OpenCode plugin and optionally merge Pi user settings.
+ * - auto/project: project plugin only (no home writes)
+ * - user: project plugin + explicit Pi merge
+ * - off: skip all
+ */
+export async function runClientRecovery(input) {
+    const mode = input.mode ?? "auto";
+    if (mode === "off") {
+        return {
+            mode,
+            plugin: {
+                path: OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
+                written: false,
+                reason: "skipped",
+            },
+        };
+    }
+    const plugin = await installProjectOpenCodePlugin({ repoRoot: input.repoRoot });
+    if (mode !== "user") {
+        return { mode, plugin };
+    }
+    const homeDir = input.homeDir ?? os.homedir();
+    const pi = await applyPiRetryMerge({ homeDir });
+    return { mode, plugin, pi };
+}

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 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";
@@ -871,6 +873,9 @@ function buildManagedAgentsBlock(input) {
         "- 用户明确提出后端测试、接口/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`。",
         "",
         "### 运行看板（只读）",
         "",
@@ -1275,6 +1280,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 +1327,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] };
@@ -2443,9 +2452,30 @@ export async function initializeLoopAgentProject(options) {
     }
     await ensureHarnessDirs(repoRoot, written);
     await writeCompatPrompts({ repoRoot, merge, written, skipped });
+    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")
@@ -2642,12 +2672,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) {
@@ -2811,6 +2848,7 @@ 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" });
         applied.push({
@@ -2824,7 +2862,13 @@ export async function applyInitUpdate(input) {
         // 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 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 +2890,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 +2928,20 @@ 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",
         "",
@@ -2971,6 +3042,7 @@ function parseInitArgs(repoRoot, args) {
     let merge = true;
     let provider;
     let model;
+    let clientRecovery = "auto";
     let json = false;
     let markdown = false;
     let bootstrapSurface = false;
@@ -3005,6 +3077,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 +3104,7 @@ function parseInitArgs(repoRoot, args) {
         merge,
         provider,
         model,
+        clientRecovery,
         subcommand,
         json,
         markdown,

package/docs/architecture/runtime-boundaries.md

@@ -190,6 +190,19 @@ bash scripts/check-skill-entry.sh
 
 Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
 
+## Client session 瞬态恢复边界
+
+主会话模型偶尔会返回非标准 502 / `LLMRequestError` / 网络抖动 / 超时响应；OpenCode 可能先解析为 `TypeValidationError` 再落成 `UnknownError`，导致内置 APIError 重试不命中。loop-agent 通过 **项目级 OpenCode 插件补偿** 与 **Pi 用户级配置显式启用** 处理该缺口，不修改 OpenCode/Pi 上游，也不引入外部监督器。
+
+| 面 | 路径 / 入口 | 边界 |
+|---|---|---|
+| OpenCode 项目插件 | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 直接返回真实 `Hooks.event`，分发 `session.error` / `session.status` / `message.updated`；从 `client.session.status()` 的 session map 判断内置 retry，以 `client.session.promptAsync()` 续接同一 session；只有成功完成的 assistant message 清零连续失败计数。认证/权限/配额/上下文溢出/取消/业务错误走 `plugin-ignore-permanent-error` |
+| Pi 用户配置 | `~/.pi/agent/settings.json` | **不**进入项目 `.harness/init-surface.json` hash；仅 `--client-recovery=user` 可字段级补缺并原子写；`auto`/`project`/`off` 与 `check-update` 默认零写 home；读取时只有 `ENOENT` 视为缺文件，其他 I/O 错误 fail closed |
+| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 只装项目插件；`user` = 项目插件 + 显式 Pi 合并；`off` 全跳过 |
+| Ownership | recorded sha256 + apply-safe | 插件缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
+
+实现落点：`src/commands/client-recovery.ts`（纯逻辑与生成器）+ `src/commands/init.ts`（编排）。
+
 ## 演进里程碑
 
 | Phase | 边界变化 |

package/docs/init-surface.manifest.json

@@ -164,7 +164,8 @@
     "docs/templates/backend-test-analysis.schema.json",
     "docs/templates/backend-test-execution.schema.json",
     "docs/templates/backend-test-result.schema.json",
-    "docs/templates/backend-test-case-manifest.schema.json"
+    "docs/templates/backend-test-case-manifest.schema.json",
+    ".opencode/plugins/loop-agent-transient-retry.js"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -244,7 +245,8 @@
     "docs/templates/backend-test-analysis.schema.json": "copied",
     "docs/templates/backend-test-execution.schema.json": "copied",
     "docs/templates/backend-test-result.schema.json": "copied",
-    "docs/templates/backend-test-case-manifest.schema.json": "copied"
+    "docs/templates/backend-test-case-manifest.schema.json": "copied",
+    ".opencode/plugins/loop-agent-transient-retry.js": "generated"
   },
   "packageExcluded": [
     "docs/progress/20*.md",
@@ -264,6 +266,7 @@
     "harness.json",
     "package.json",
     "src/commands/init.ts",
+    "src/commands/client-recovery.ts",
     "src/cli.ts",
     "src/cli/update/init-surface-notifier.ts",
     "src/cli/update/policy.ts",
@@ -287,6 +290,7 @@
         "description": "Changes that may alter target-project initialization behavior, default DAG role skills, skill resolution, or package/init contracts.",
         "patterns": [
           "src/commands/init.ts",
+          "src/commands/client-recovery.ts",
           "src/cli.ts",
           "src/cli/update/init-surface-notifier.ts",
           "src/cli/update/policy.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -56,9 +56,10 @@ loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
 6. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
 7. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
 8. No hidden state in chat only；verify before completion.
+9. Client recovery：`init --client-recovery=auto|project|user|off`；只有 `user` 写 Pi settings；check/update 遵守 ownership。
 
 ## References
 
 Required（按需 inline）：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`
 
-Optional：`references/command-reference.md`（operator commands、`agent-worker`）、`references/long-running-loop.md`、`references/orchestrator-and-interventions.md`、`references/task-workflow.md`、`references/pi-prompt.md`、`references/one-shot-runs.md`、`references/pi-subagent-assisted-mode.md`、`references/model-routing.md`、`references/multi-worktree.md`、`references/post-implementation-and-patterns.md`、`references/docs-converge.md`
+Optional 索引见 `references/README.md`；常用：`command-reference.md`、`long-running-loop.md`、`orchestrator-and-interventions.md`、`docs-converge.md`。