@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.2

package/dist/worker/console/operator-actions.js

@@ -4,13 +4,14 @@ import { DAG_RERUN_PROMPT_OVERRIDE_ENV, isDagRerunPromptOverrideEnabled, MAX_DAG
 import { buildOperatorResult, operatorFailed, operatorSucceeded, } from "../../shared/operator/envelope.js";
 import { CANONICAL_TASK_ID_PATTERN, formatLocalBusinessDate, getTaskPaths, loadTaskConfig, } from "../../task/runtime.js";
 import { diffTaskContract, validateDraftForTask, } from "../../task/contract/index.js";
-import { stageUtf8Text } from "./app-data.js";
+import { stageUtf8Text } from "../../infrastructure/console/app-data.js";
 import { ALL_CONFIRMATION_CHALLENGES, hashDagBytes, } from "./dag-confirmation.js";
 import { capabilityForObserveTarget, DEFAULT_OBSERVE_BASE_URL, OBSERVE_START_COMMAND, probeAndClassifyObserve, } from "./observe-health-match.js";
 import { buildInspectDeepLink, buildObserveDeepLink, } from "./observe-link.js";
 import { resolveLatestDagRunIdForTask } from "./resolve-dag-run-for-task.js";
-import { repoFingerprintV1 } from "./repo-fingerprint.js";
+import { repoFingerprintV1 } from "../../infrastructure/console/repo-fingerprint.js";
 import { scheduleOperation, } from "./operation-runner.js";
+import { recordContextTransferEvent } from "./context-transfer-diagnostics.js";
 import { readinessGateFailure, } from "./pi-readiness.js";
 import { validatePiModelMatrixTiers, writePiModelMatrix, } from "./harness-pi-model-matrix.js";
 import { isAssessmentFreshForDraft } from "./interview/assessment.js";
@@ -64,10 +65,6 @@ function paramsOf(req) {
 function str(v) {
     return typeof v === "string" && v.trim() ? v.trim() : undefined;
 }
-function appendExplicitTaskKindArg(args, taskKind, taskKindExplicit) {
-    if (taskKindExplicit)
-        args.push("--task-kind", taskKind);
-}
 const TASK_ID_PLACEHOLDER_RE = /[<>]|^(?:id|task-?id|your-task-id|todo|tbd)$/i;
 /** Mirror of runtime GENERIC_TASK_SLUGS (not exported there); keep in sync. */
 const GENERIC_SLUG_SET = new Set(["test", "fix", "tmp", "new-task"]);
@@ -485,7 +482,7 @@ async function buildPromptOverrideCliArgs(ctx, overrides) {
     }
     return args;
 }
-async function acceptOperation(ctx, input) {
+export async function acceptOperation(ctx, input) {
     const created = await ctx.operations.create({
         clientRequestId: input.clientRequestId,
         action: input.action,
@@ -521,12 +518,55 @@ async function acceptOperation(ctx, input) {
             },
         };
     }
+    if (input.onAdmitted) {
+        try {
+            await input.onAdmitted(created.operation);
+        }
+        catch {
+            // Lifecycle observation must never block admission.
+        }
+    }
+    if (input.prepare) {
+        try {
+            await input.prepare();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const preparedFailure = input.prepareFailure?.(error);
+            await ctx.operations.update(created.operation.operationId, {
+                state: "failed",
+                startedAt: created.operation.createdAt,
+                finishedAt: new Date().toISOString(),
+                errorCode: preparedFailure?.errorCode ?? "INVALID_INPUT",
+                errorMessage: message,
+            });
+            return {
+                kind: "error",
+                status: preparedFailure?.status ?? 400,
+                body: preparedFailure?.body ?? operatorFailed({
+                    command: input.action,
+                    outcome: "blocked",
+                    code: "INVALID_INPUT",
+                    message,
+                }),
+            };
+        }
+    }
+    const transferObserver = contextTransferSettledObserver(ctx, input.action, input.actionParams);
     const runnerDeps = {
         store: ctx.operations,
         events: ctx.events,
         client: ctx.client,
         repoRoot: ctx.repoRoot,
+        env: { ...process.env, LOOP_CONSOLE_APP_DATA: ctx.appData.root },
         runCommand: ctx.runCommand,
+        beforeTerminal: input.beforeTerminal,
+        onSettled: async (operation, state, info) => {
+            // Diagnostics are best-effort and must not prevent authoritative Worker
+            // settlement from running.
+            await Promise.resolve(transferObserver?.(operation, state, info)).catch(() => undefined);
+            await input.onSettled?.(operation, state, info);
+        },
     };
     scheduleOperation(created.operation.operationId, runnerDeps);
     return {
@@ -540,83 +580,62 @@ async function acceptOperation(ctx, input) {
         },
     };
 }
-function splitRuntimeMissing(action) {
-    return {
-        kind: "error",
-        status: 503,
-        body: operatorFailed({
-            command: action,
-            outcome: "blocked",
-            code: "INTERNAL_ERROR",
-            message: `${action} is unavailable: frontend split runtime is not wired`,
-        }),
+/**
+ * Map artifact revision / rerun operation outcomes onto the append-only
+ * context-transfer lifecycle event log. Only stages the Console truly
+ * observes (admission + settle) are recorded; CLI-kernel-internal stages
+ * stay in the kernel. Unknown actions emit nothing.
+ */
+function contextTransferSettledObserver(ctx, action, actionParams) {
+    if (action !== "artifactRevisionStage" &&
+        action !== "artifactRevisionPlan" &&
+        action !== "artifactRevisionExecute") {
+        return undefined;
+    }
+    const strParam = (key) => {
+        const value = actionParams[key];
+        return typeof value === "string" ? value.trim() : undefined;
     };
-}
-function numOf(v) {
-    return typeof v === "number" ? v : Number(v);
-}
-function splitCommandBase(p) {
-    return {
-        operationId: str(p.operationId) ?? "",
-        expectedRevision: numOf(p.expectedRevision),
-        expectedParentDigest: str(p.expectedParentDigest) ?? "",
-        expectedManifestDigest: str(p.expectedManifestDigest) ?? "",
+    const baseFields = {
+        runId: strParam("runId"),
+        nodeId: strParam("nodeId"),
+        revisionId: strParam("revisionId"),
     };
-}
-function splitCommandDispatch(action, result) {
-    if (result.outcome === "conflict") {
-        return {
-            kind: "error",
-            status: 409,
-            body: operatorFailed({
-                command: action,
-                outcome: "conflict",
-                code: "CONFLICT",
-                message: "frontend split CAS conflict (stale revision or binding)",
-            }),
-        };
-    }
-    return { kind: "sync", status: 200, body: operatorSucceeded(action, result) };
-}
-async function runSplitAction(action, run) {
-    try {
-        const result = await run();
-        if (result && typeof result === "object" && "outcome" in result) {
-            return splitCommandDispatch(action, result);
+    return (operation, state, info) => {
+        let event;
+        if (action === "artifactRevisionStage") {
+            event = info.ok ? "artifact_revision.validated" : "artifact_revision.rejected";
         }
-        return {
-            kind: "sync",
-            status: 200,
-            body: operatorSucceeded(action, result),
-        };
-    }
-    catch (error) {
-        return invalid(action, error instanceof Error ? error.message : String(error));
-    }
-}
-function humanDecisionDispatch(action, result) {
-    if (result.outcome === "rejected") {
-        return {
-            kind: "error",
-            status: 409,
-            body: operatorFailed({
-                command: action,
-                outcome: "conflict",
-                code: "CONFLICT",
-                message: result.reason,
-                details: { projection: result.projection },
-            }),
-        };
-    }
-    return { kind: "sync", status: 200, body: operatorSucceeded(action, result) };
-}
-async function runHumanDecisionAction(action, run) {
-    try {
-        return humanDecisionDispatch(action, await run());
-    }
-    catch (error) {
-        return invalid(action, error instanceof Error ? error.message : String(error));
-    }
+        else if (action === "artifactRevisionPlan") {
+            event = info.ok ? "artifact_rerun.plan_created" : "artifact_rerun.blocked";
+        }
+        else if (state === "needs-reconcile") {
+            event = "artifact_rerun.needs_reconcile";
+        }
+        else {
+            event = info.ok ? "artifact_rerun.finished" : "artifact_rerun.failed";
+        }
+        // The stage CLI assigns the revision id; it only exists in the settle
+        // result, never in admission params.
+        let resultRevisionId;
+        const resultRevision = operation.result
+            ?.revision;
+        if (resultRevision && typeof resultRevision === "object") {
+            resultRevisionId = resultRevision.revisionId;
+        }
+        return recordContextTransferEvent({
+            appData: ctx.appData,
+            event,
+            fields: {
+                ...baseFields,
+                ...(typeof resultRevisionId === "string"
+                    ? { revisionId: resultRevisionId }
+                    : {}),
+                operationId: operation.operationId,
+                ...(info.ok ? {} : { reasonCode: info.errorCode ?? "INTERNAL_ERROR" }),
+            },
+        }).catch(() => undefined);
+    };
 }
 async function acceptConsoleUpdateAndInit(ctx, clientRequestId, channel) {
     if (!ctx.consoleUpdateExecutor) {
@@ -1959,7 +1978,7 @@ export async function dispatchOperatorAction(ctx, req) {
             const staged = await stageUtf8Text(ctx.appData, content, {
                 extension: ".md",
             });
-            const importArgs = [
+            const imported = await run([
                 "task",
                 "advance",
                 taskId,
@@ -1968,10 +1987,8 @@ export async function dispatchOperatorAction(ctx, req) {
                 staged.path,
                 "--role",
                 "requirement",
-            ];
-            appendExplicitTaskKindArg(importArgs, taskKind, taskKindExplicit);
-            importArgs.push("--json");
-            const imported = await run(importArgs, {
+                "--json",
+            ], {
                 cwd: ctx.repoRoot,
                 artifactName: "import-prd-task-advance",
                 expectJson: true,
@@ -2946,75 +2963,6 @@ export async function dispatchOperatorAction(ctx, req) {
                 }),
             };
         }
-        case "frontendSplitWakeup": {
-            if (!ctx.splitOrchestrator)
-                return splitRuntimeMissing(action);
-            return runSplitAction(action, () => ctx.splitOrchestrator.wakeupChildren(splitCommandBase(p)));
-        }
-        case "frontendSplitChildCallback": {
-            if (!ctx.splitOrchestrator)
-                return splitRuntimeMissing(action);
-            return runSplitAction(action, () => ctx.splitOrchestrator.childCallback({
-                ...splitCommandBase(p),
-                observation: p.observation,
-            }));
-        }
-        case "frontendSplitWakeupIntegration": {
-            if (!ctx.splitOrchestrator)
-                return splitRuntimeMissing(action);
-            return runSplitAction(action, () => ctx.splitOrchestrator.wakeupIntegration(splitCommandBase(p)));
-        }
-        case "frontendSplitIntegrationCallback": {
-            if (!ctx.splitOrchestrator)
-                return splitRuntimeMissing(action);
-            return runSplitAction(action, () => ctx.splitOrchestrator.integrationCallback({
-                ...splitCommandBase(p),
-                completion: p.completion,
-            }));
-        }
-        case "frontendSplitFinalize": {
-            if (!ctx.splitOrchestrator)
-                return splitRuntimeMissing(action);
-            return runSplitAction(action, () => ctx.splitOrchestrator.finalize(splitCommandBase(p)));
-        }
-        case "frontendHumanDecisionMaterialize": {
-            if (!ctx.humanDecisionAdapter)
-                return splitRuntimeMissing(action);
-            return runHumanDecisionAction(action, () => ctx.humanDecisionAdapter.materialize({
-                operationId: str(p.operationId) ?? "",
-                expectedRecordRevision: numOf(p.expectedRecordRevision),
-                expectedProjectionDigest: str(p.expectedProjectionDigest) ?? "",
-                envelope: p.envelope,
-            }));
-        }
-        case "frontendHumanDecisionApprove": {
-            if (!ctx.humanDecisionAdapter)
-                return splitRuntimeMissing(action);
-            return runHumanDecisionAction(action, () => ctx.humanDecisionAdapter.consume({
-                operationId: str(p.operationId) ?? "",
-                expectedRecordRevision: numOf(p.expectedRecordRevision),
-                expectedProjectionDigest: str(p.expectedProjectionDigest) ?? "",
-                receipt: p.receipt,
-                currentTargetDigest: str(p.currentTargetDigest) ?? "",
-                now: str(p.now) ?? new Date().toISOString(),
-            }));
-        }
-        case "frontendSplitInitialize": {
-            if (!ctx.humanDecisionAdapter)
-                return splitRuntimeMissing(action);
-            return runHumanDecisionAction(action, () => ctx.humanDecisionAdapter.initializeSplit({
-                operationId: str(p.operationId) ?? "",
-                expectedRecordRevision: numOf(p.expectedRecordRevision),
-                expectedProjectionDigest: str(p.expectedProjectionDigest) ?? "",
-                execution: p.execution,
-                manifest: p.manifest,
-                receipt: p.receipt,
-                currentTargetDigest: str(p.currentTargetDigest) ?? "",
-                now: str(p.now) ?? new Date().toISOString(),
-                activeWriterOperationId: str(p.activeWriterOperationId) ?? null,
-                activeProviderOperationId: str(p.activeProviderOperationId) ?? null,
-            }));
-        }
         default: {
             // M5 official-command coverage uses one generic tail for newly registered
             // CLI actions. It remains inside dispatchOperatorAction (the sole dispatch
@@ -3399,14 +3347,7 @@ async function dispatchBootstrapFromPrd(ctx, p) {
     const title = identity.title;
     const run = ctx.runCommand ?? ((a, o) => ctx.client.run(a, o));
     // Standard lifecycle entry: task advance create + PRD import(s).
-    // Preserve an explicitly selected business workflow from the very first
-    // task.json write. The task lifecycle otherwise defaults new tasks to
-    // standard, which caused frontend tasks to be promoted only during the
-    // final intake pass.
-    const createArgs = ["task", "advance", taskId, title];
-    appendExplicitTaskKindArg(createArgs, taskKind, taskKindExplicit);
-    createArgs.push("--json");
-    const advanceCreate = await run(createArgs, {
+    const advanceCreate = await run(["task", "advance", taskId, title, "--json"], {
         cwd: ctx.repoRoot,
         artifactName: "bootstrap-task-advance-create",
         expectJson: true,
@@ -3440,7 +3381,7 @@ async function dispatchBootstrapFromPrd(ctx, p) {
         const staged = await stageUtf8Text(ctx.appData, text, {
             extension: ".md",
         });
-        const importArgs = [
+        const imported = await run([
             "task",
             "advance",
             taskId,
@@ -3448,10 +3389,8 @@ async function dispatchBootstrapFromPrd(ctx, p) {
             staged.path,
             "--role",
             role,
-        ];
-        appendExplicitTaskKindArg(importArgs, taskKind, taskKindExplicit);
-        importArgs.push("--json");
-        const imported = await run(importArgs, {
+            "--json",
+        ], {
             cwd: ctx.repoRoot,
             artifactName: `bootstrap-task-advance-prd-${label}`,
             expectJson: true,

package/dist/worker/console/operator-surface-health.js

@@ -1,5 +1,5 @@
 import { deriveObserveRouteCapabilities, resolveObservePackageIdentity, } from "../observe/health.js";
-import { repoFingerprintV1 } from "./repo-fingerprint.js";
+import { repoFingerprintV1 } from "../../infrastructure/console/repo-fingerprint.js";
 export function buildOperatorSurfaceHealthV1(input) {
     const { packageName, packageVersion } = resolveObservePackageIdentity();
     const snapshotAvailable = input.routes.some((route) => route.method === "GET" && route.pattern.test("/api/snapshot"));

package/dist/worker/console/operator-user-error.js

@@ -14,6 +14,162 @@ const MUTATION_GATE_COPY = [
         copy: "请求主机校验失败：非回环绑定时要求 Host 头，请刷新页面或检查访问地址。",
     },
 ];
+/**
+ * Context-transfer / artifact-revision 稳定 reason code（kernel CLI 会原样
+ * 透传到操作错误信息里）→ 面向操作者的中文语义。与 observe 侧
+ * dag-context-reason-labels.js 同源，保留原码便于诊断。
+ */
+const CONTEXT_TRANSFER_CODE_COPY = [
+    {
+        pattern: /\bCONTEXT_RECEIPT_MISSING\b/,
+        copy: "该节点没有执行时上下文回执（CONTEXT_RECEIPT_MISSING）：只有真实执行过的模型节点才有可导出的上下文；历史 run 不做事后回填。",
+    },
+    {
+        pattern: /\bCONTEXT_COMPONENT_UNAVAILABLE\b/,
+        copy: "部分上下文组件当前不可用（CONTEXT_COMPONENT_UNAVAILABLE），无法生成完整交接包。",
+    },
+    {
+        pattern: /\bCONTEXT_BUNDLE_TOO_LARGE\b/,
+        copy: "导出内容超出体积上限（CONTEXT_BUNDLE_TOO_LARGE），请缩小节点范围或联系维护者调整上限。",
+    },
+    {
+        pattern: /\bRAW_EXPORT_ACKNOWLEDGEMENT_REQUIRED\b/,
+        copy: "原文导出包含敏感数据风险（RAW_EXPORT_ACKNOWLEDGEMENT_REQUIRED），需要先勾选风险确认。",
+    },
+    {
+        pattern: /\bSECRET_SCAN_CONFIRMATION_REQUIRED\b/,
+        copy: "候选文件疑似包含凭据（SECRET_SCAN_CONFIRMATION_REQUIRED），确认风险后才能继续。",
+    },
+    {
+        pattern: /\bARTIFACT_BINDING_UNAVAILABLE\b/,
+        copy: "缺少结构化产物关系（ARTIFACT_BINDING_UNAVAILABLE）：只有带产物绑定的新 run 支持修订与派生，历史 run 仅可查看/下载。",
+    },
+    {
+        pattern: /\bARTIFACT_NOT_REVISION_ELIGIBLE\b/,
+        copy: "该产物不允许修订替换（ARTIFACT_NOT_REVISION_ELIGIBLE）。",
+    },
+    {
+        pattern: /\bARTIFACT_IDENTITY_AMBIGUOUS\b/,
+        copy: "产物身份不唯一（ARTIFACT_IDENTITY_AMBIGUOUS），无法安全定位修订目标。",
+    },
+    {
+        pattern: /\bARTIFACT_REVISION_SCHEMA_INVALID\b/,
+        copy: "候选文件不符合该产物声明的数据结构（ARTIFACT_REVISION_SCHEMA_INVALID），已拒绝入库。",
+    },
+    {
+        pattern: /\bARTIFACT_REVISION_PATH_INVALID\b/,
+        copy: "候选目标路径无效（ARTIFACT_REVISION_PATH_INVALID），已拒绝。",
+    },
+    {
+        pattern: /\bARTIFACT_REVISION_EXPIRED\b/,
+        copy: "修订候选已过期（ARTIFACT_REVISION_EXPIRED），请重新上传后再继续。",
+    },
+    {
+        pattern: /\bARTIFACT_REVISION_DRIFT\b/,
+        copy: "候选文件与登记内容不一致（ARTIFACT_REVISION_DRIFT），请重新上传。",
+    },
+    {
+        pattern: /\bARTIFACT_REVISION_QUOTA_EXCEEDED\b/,
+        copy: "修订暂存区配额已满（ARTIFACT_REVISION_QUOTA_EXCEEDED），请先丢弃不需要的修订或等待过期回收。",
+    },
+    {
+        pattern: /\bARTIFACT_CONSUMER_UNKNOWN\b/,
+        copy: "无法确定受影响的下游节点（ARTIFACT_CONSUMER_UNKNOWN），派生继续已被阻止。",
+    },
+    {
+        pattern: /\bARTIFACT_IMPACT_UNSAFE\b/,
+        copy: "影响范围包含不能自动重跑的节点（ARTIFACT_IMPACT_UNSAFE），派生继续已被阻止。",
+    },
+    {
+        pattern: /\bRERUN_PLAN_DRIFT\b|\bPLAN_DRIFT\b/,
+        copy: "继续运行计划与当前事实发生漂移（RERUN_PLAN_DRIFT），请重新生成计划后再执行。",
+    },
+    {
+        pattern: /\bWORKER_MANAGED_CONTINUATION_UNSUPPORTED\b/,
+        copy: "由 Worker 托管的运行暂不支持派生继续（WORKER_MANAGED_CONTINUATION_UNSUPPORTED），这是当前版本的明确边界，不是失败。",
+    },
+    {
+        pattern: /\bWORKER_CONTINUATION_AUTHORITY_MISMATCH\b/,
+        copy: "Worker 派生运行的归属事实不一致（WORKER_CONTINUATION_AUTHORITY_MISMATCH），请刷新计划并核对 Task Pool 状态。",
+    },
+    {
+        pattern: /\bWORKER_CONTINUATION_LEASE_CONFLICT\b/,
+        copy: "该 Worker Task 已有运行占用（WORKER_CONTINUATION_LEASE_CONFLICT），请等待当前运行结束或先完成恢复核对。",
+    },
+    {
+        pattern: /\bWORKER_CONTINUATION_NEEDS_RECONCILE\b/,
+        copy: "Worker 派生运行已存在但终态尚未完成核对（WORKER_CONTINUATION_NEEDS_RECONCILE），不会再次启动；请先执行恢复核对。",
+    },
+    {
+        pattern: /\bPARENT_IMMUTABILITY_VIOLATION\b/,
+        copy: "父运行事实发生变化（PARENT_IMMUTABILITY_VIOLATION），已阻止派生以保护历史证据。",
+    },
+    {
+        pattern: /\bPARENT_LIFECYCLE\b/,
+        copy: "父运行当前状态不允许派生继续（PARENT_LIFECYCLE）。",
+    },
+    {
+        pattern: /\bREQUEST_ID_REUSE_CONFLICT\b/,
+        copy: "相同请求 ID 已被其他操作占用（REQUEST_ID_REUSE_CONFLICT），请更换请求 ID 重试。",
+    },
+    {
+        pattern: /\bOPERATION_NEEDS_RECONCILE\b/,
+        copy: "操作记录需要先恢复核对（OPERATION_NEEDS_RECONCILE）：上次执行未确认结束，请刷新操作状态后重试。",
+    },
+    {
+        pattern: /\bCONTEXT_EXPORT_FAILED\b/,
+        copy: "上下文导出失败（CONTEXT_EXPORT_FAILED），请稍后重试；若持续失败请检查该节点是否存在可导出的执行事实。",
+    },
+    {
+        pattern: /\bCONTEXT_EXPORT_UNAVAILABLE\b/,
+        copy: "导出内容不存在或已过期（CONTEXT_EXPORT_UNAVAILABLE），请重新生成。",
+    },
+    {
+        pattern: /\bLEASE_HELD\b/,
+        copy: "资源正被其他操作占用（LEASE_HELD），请等待当前操作结束或稍后重试。",
+    },
+    // 更新并初始化链路的稳定错误码。
+    {
+        pattern: /\bREGISTRY_VERSION_REGRESSION\b/,
+        copy: "所选渠道的最新版本比当前安装的版本更旧（REGISTRY_VERSION_REGRESSION），已阻止降级更新。请改用包含更新版本的渠道（如 next/beta）。",
+    },
+    {
+        pattern: /\bUPDATE_LOCKED\b/,
+        copy: "另一个 loop-agent 更新正在进行（UPDATE_LOCKED），请等待其结束后重试。",
+    },
+    {
+        pattern: /\bINSTALL_FAILED\b/,
+        copy: "新版本安装失败（INSTALL_FAILED），请检查网络与 npm registry 后重试。",
+    },
+    {
+        pattern: /\bINSTALL_VERIFICATION_FAILED\b/,
+        copy: "安装后校验未通过（INSTALL_VERIFICATION_FAILED），未接棒新版本；请重试或手动安装。",
+    },
+    {
+        pattern: /\bACTIVE_RUNTIME\b/,
+        copy: "当前存在活跃的 DAG/Worker 运行（ACTIVE_RUNTIME），更新已推迟；请等待运行结束后再更新。",
+    },
+    {
+        pattern: /\bCHAT_TURN_ACTIVE\b/,
+        copy: "对话正在执行中（CHAT_TURN_ACTIVE），更新已推迟；请等待当前回合结束后再更新。",
+    },
+    {
+        pattern: /\bOPERATION_ACTIVE\b/,
+        copy: "另一个 Console 操作正在进行（OPERATION_ACTIVE），请等待其结束后再更新。",
+    },
+    {
+        pattern: /\bHANDOFF_FAILED\b/,
+        copy: "新版本已安装，但接棒启动新 Console 失败（HANDOFF_FAILED）；旧进程未被关闭，可直接重试或手动重启 Console。",
+    },
+    {
+        pattern: /\bINIT_NEEDS_RECONCILE\b/,
+        copy: "安全初始化未完全通过（INIT_NEEDS_RECONCILE）：版本已就绪，请查看初始化待处理项后重试。",
+    },
+    {
+        pattern: /\bINVALID_VERSION\b/,
+        copy: "安装版本或渠道版本号无法解析（INVALID_VERSION），请重试；若持续出现请反馈。",
+    },
+];
 /** Map internal spawn/controller errors to actionable Chinese copy. */
 export function formatOperatorUserError(message) {
     const raw = (message ?? "").trim();
@@ -37,6 +193,19 @@ export function formatOperatorUserError(message) {
     if (/force-required|requires --force/i.test(raw)) {
         return "该终态需要强制 Discard。请确认后勾选强制再试。";
     }
+    if (/not-global|GLOBAL_INSTALL_UNPROVEN/i.test(raw)) {
+        return "当前 Console 由仓库内构建启动，不是全局 npm 安装，一键更新不可用。请全局安装（npm i -g @tea-agent/loop-agent）后从全局命令启动 Console 再更新，或手动更新本仓库后重启。";
+    }
+    if (/could not verify npm (?:latest|next) \(timeout\)/i.test(raw)) {
+        return "检查 npm 更新渠道超时：请确认本机网络或 npm registry 镜像可访问后重试。";
+    }
+    if (/could not verify npm (?:latest|next) \(/i.test(raw)) {
+        return "检查 npm 更新渠道失败：请确认本机 npm 可用、网络可访问 registry 后重试。";
+    }
+    for (const entry of CONTEXT_TRANSFER_CODE_COPY) {
+        if (entry.pattern.test(raw))
+            return entry.copy;
+    }
     for (const entry of MUTATION_GATE_COPY) {
         if (entry.pattern.test(raw))
             return entry.copy;

package/dist/worker/console/pi-plugins.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
+import semver from "semver";
 import catalogData from "./pi-plugins.catalog.json" with { type: "json" };
 export function getPiAgentDir() {
     const envDir = process.env.PI_CODING_AGENT_DIR;
@@ -98,7 +99,9 @@ function getNpmRegistry() {
 /** 从 npm 配置的仓库拉取某包的全部已发布版本 + latest。 */
 export async function listPiPluginVersions(name) {
     const registry = (await getNpmRegistry()).replace(/\/+$/, "");
-    const url = `${registry}/${encodeURIComponent(name).replace(/%2F/g, "/")}`;
+    // scoped 包名整段编码（@scope/name → %40scope%2Fname）：与 npm 客户端请求
+    // packument 的形式一致，npmjs.org 与内网 Nexus（要求 %2F 不还原）都接受。
+    const url = `${registry}/${encodeURIComponent(name)}`;
     try {
         const res = await fetch(url, {
             headers: { accept: "application/json", "user-agent": "loop-agent/1.0" },
@@ -123,6 +126,62 @@ export async function listPiPluginVersions(name) {
         };
     }
 }
+/** 单个已装插件的升级判定：latest 严格大于已装版本才算有更新。 */
+export function isPluginUpgradable(installed, latest) {
+    if (!installed || !latest)
+        return false;
+    const current = semver.valid(installed);
+    const next = semver.valid(latest);
+    if (!current || !next)
+        return false;
+    return semver.gt(next, current);
+}
+/** 已装插件更新检查结果的最短缓存时长：避免前端频繁刷新打爆 registry。 */
+const UPDATES_CACHE_TTL_MS = 60_000;
+let cachedUpdates;
+/**
+ * 检查所有已安装插件的可用更新：并发拉取每个包的 dist-tags.latest，
+ * 与 node_modules 里的实际版本做 semver 比较。单包失败不阻塞其它包。
+ * TTL 内重复调用直接复用上次结果（`force: true` 可绕过）。
+ */
+export async function checkPiPluginUpdates(options) {
+    const now = options?.now ?? Date.now;
+    if (!options?.force &&
+        cachedUpdates &&
+        now() - cachedUpdates.at < UPDATES_CACHE_TTL_MS) {
+        return cachedUpdates.view;
+    }
+    const fetchPackument = options?.fetchPackument ?? listPiPluginVersions;
+    const installed = options?.listInstalled?.() ??
+        listPiPlugins()
+            .plugins.filter((p) => p.installed)
+            .map((p) => ({ name: p.name, installedVersion: p.installedVersion }));
+    const statuses = await Promise.all(installed.map(async (p) => {
+        const result = await fetchPackument(p.name);
+        if (!result.ok) {
+            return {
+                name: p.name,
+                installedVersion: p.installedVersion,
+                upgradable: false,
+                error: result.error,
+            };
+        }
+        return {
+            name: p.name,
+            installedVersion: p.installedVersion,
+            latest: result.latest,
+            upgradable: isPluginUpgradable(p.installedVersion, result.latest),
+        };
+    }));
+    const view = {
+        checked: statuses.length,
+        upgradableCount: statuses.filter((s) => s.upgradable).length,
+        checkedAt: new Date().toISOString(),
+        plugins: statuses,
+    };
+    cachedUpdates = { at: now(), view };
+    return view;
+}
 function runPi(args) {
     return new Promise((resolve) => {
         mkdirSync(getPiAgentDir(), { recursive: true });