@tea-agent/loop-agent 0.40.0-next.9 → 0.41.0-beta.1

package/dist/worker/console/dag-execution-receipt.js

@@ -20,7 +20,7 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
-import { readJsonIfExists, sha256Utf8, writeSecureJson, } from "./app-data.js";
+import { readJsonIfExists, sha256Utf8, writeSecureJson, } from "../../infrastructure/console/app-data.js";
 import { hashDagBytes, } from "./dag-confirmation.js";
 /**
  * Structured verification command patterns for the G2 autonomous-execution
@@ -176,8 +176,26 @@ export function deriveEligibilityFactsFromDagSpec(input) {
     }));
     const allWriteSetEntries = writers.flatMap((writer) => writer.writeSet);
     const broadWriteSetRisk = allWriteSetEntries.some(isBroadWriteSetEntry);
-    const forbiddenOverlapRisk = tasks.some((task) => stringList(task.writeSet).some((entry) => [...stringList(task.forbiddenPaths), ...input.forbiddenPaths].some((forbidden) => pathMatchesPattern(entry, forbidden) ||
-        pathMatchesPattern(forbidden, entry))));
+    const taskForbidden = input.forbiddenPaths.map(normalizePathEntry);
+    const forbiddenOverlapRisk = tasks.some((task) => stringList(task.writeSet).some((entry) => {
+        const normalizedEntry = normalizePathEntry(entry);
+        return stringList(task.forbiddenPaths).some((forbidden) => {
+            const normalizedForbidden = normalizePathEntry(forbidden);
+            const isTaskGlobal = taskForbidden.includes(normalizedForbidden);
+            if (isTaskGlobal) {
+                // Task-level forbidden paths are hard global boundaries. A broad
+                // writer that could include one is not autonomously eligible.
+                return (pathMatchesPattern(normalizedEntry, normalizedForbidden) ||
+                    pathMatchesPattern(normalizedForbidden, normalizedEntry));
+            }
+            // Node-local forbidden paths may intentionally carve a narrower
+            // child (for example md/README.md) out of a broader writer
+            // writeSet. That exclusion is enforced by the runtime write guard.
+            // It is a conflict only when the writer entry itself is wholly
+            // inside the forbidden boundary.
+            return pathMatchesPattern(normalizedEntry, normalizedForbidden);
+        });
+    }));
     const hasStructuredVerification = tasks.some((task) => {
         if (task.executor !== "shell" || !task.shell)
             return false;

package/dist/worker/console/doctor.js

@@ -6,7 +6,7 @@ import { LoopAgentClient } from "../loop-agent/loop-agent-client.js";
 import { preflightTargetRepo } from "../preflight.js";
 import { probePiReadiness, } from "./pi-readiness.js";
 import { DEFAULT_OBSERVE_BASE_URL, OBSERVE_START_COMMAND, probeAndClassifyObserve, } from "./observe-health-match.js";
-import { repoFingerprintV1 } from "./repo-fingerprint.js";
+import { repoFingerprintV1 } from "../../infrastructure/console/repo-fingerprint.js";
 import { resolveSiblingLoopAgentBin } from "./sibling-controller.js";
 import { defaultObserveStaticDir, ROUTES } from "../observe/routes.js";
 import { deriveObserveRouteCapabilities } from "../observe/health.js";

package/dist/worker/console/draft-store.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { readJsonIfExists, sha256Json, writeSecureJson, } from "./app-data.js";
+import { readJsonIfExists, sha256Json, writeSecureJson, } from "../../infrastructure/console/app-data.js";
 /**
  * 从任意上游载荷安全投影 ledger 摘要（未知形状丢弃，绝不抛错、绝不信任字段外的数据）。
  * 供 DraftStore / prd-intake-bridge 把 prepare/advance 结果中的 ledger 摘要带入草稿。

package/dist/worker/console/human-gate-token.js

@@ -85,7 +85,7 @@ export function verifyHumanGateToken(presented, expected, secret, now = new Date
  * invalidates the token (defense against drift-then-confirm).
  */
 import { createHash } from "node:crypto";
-import { sha256Utf8 } from "./app-data.js";
+import { sha256Utf8 } from "../../infrastructure/console/app-data.js";
 export function confirmationPayloadHash(b) {
     const canonical = [
         `dag=${b.dagSha256}`,

package/dist/worker/console/index.js

@@ -3,14 +3,14 @@ export { buildOperatorSurfaceHealthV1 } from "./operator-surface-health.js";
 export { runConsoleDoctor, formatConsoleDoctorHuman } from "./doctor.js";
 export { isLoopbackHost } from "./loopback.js";
 export { shouldOpenConsoleBrowser, normalizeConsoleBrowserUrl, openSystemBrowser, maybeOpenConsoleBrowser, } from "./open-browser.js";
-export { repoFingerprintV1, normalizeWorktreeRealpath, } from "./repo-fingerprint.js";
+export { repoFingerprintV1, normalizeWorktreeRealpath, } from "../../infrastructure/console/repo-fingerprint.js";
 export { buildObserveDeepLink } from "./observe-link.js";
 export { classifyObserveHealth, probeAndClassifyObserve, capabilityForObserveTarget, OBSERVE_START_COMMAND, DEFAULT_OBSERVE_BASE_URL, } from "./observe-health-match.js";
 export { allowedRecoveryCtas, classifyRecoveryFact, partitionRecoveryCtas, recoveryMatrixInvariants, } from "./recovery-cta.js";
 export { createClosedResourceLoader, createInterviewResourceLoader, tryActivateTool, assertOfficialToolAllowed, listOfficialTools, OFFICIAL_DENIED_TOOL_IDS, INTERVIEW_ALLOWED_TOOLS, INTERVIEW_DENIED_TOOLS, authorizeInterviewTool, } from "./resource-loader.js";
 export { resolveSiblingLoopAgentBin } from "./sibling-controller.js";
-export { openConsoleAppData, defaultConsoleAppDataRoot } from "./app-data.js";
-export { OperationStore } from "./operation-store.js";
+export { openConsoleAppData, defaultConsoleAppDataRoot } from "../../infrastructure/console/app-data.js";
+export { OperationStore } from "../../infrastructure/console/operation-store.js";
 export { createOperationEventStore } from "./operation-sse.js";
 export { DagConfirmationStore } from "./dag-confirmation.js";
 export { DraftStore } from "./draft-store.js";

package/dist/worker/console/interview/assessment.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
-import { readJsonIfExists, writeSecureJson, } from "../app-data.js";
+import { readJsonIfExists, writeSecureJson, } from "../../../infrastructure/console/app-data.js";
 import { computeDraftSha256, } from "../draft-store.js";
 function assessmentPath(appData, assessmentId) {
     return path.join(appData.assessments, `${assessmentId}.json`);

package/dist/worker/console/interview/session.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
-import { readJsonIfExists, writeSecureJson, } from "../app-data.js";
+import { readJsonIfExists, writeSecureJson, } from "../../../infrastructure/console/app-data.js";
 import { createInterviewResourceLoader, } from "./tools.js";
 function sessionPath(appData, sessionId) {
     return path.join(appData.interviews, `${sessionId}.json`);

package/dist/worker/console/operation-runner.js

@@ -1,6 +1,14 @@
-import { clipPreview, } from "./operation-store.js";
+import { clipPreview, } from "../../infrastructure/console/operation-store.js";
 import { stateEvent } from "./operation-sse.js";
 import { extractTrustedRunFacts } from "./operation-run-facts.js";
+/** Swallow-all invoker so observers can never break the state path. */
+function notifySettled(deps, operation, state, info) {
+    if (!deps.onSettled)
+        return;
+    void Promise.resolve()
+        .then(() => deps.onSettled?.(operation, state, info))
+        .catch(() => undefined);
+}
 /**
  * Execute a queued operation via LoopAgentClient (or inject).
  * Timeout without proven exit → needs-reconcile (never Cancel).
@@ -42,6 +50,7 @@ export async function runOperation(operationId, deps) {
             artifactName: `operation-${operationId}`,
             expectJson: true,
             timeoutMs: deps.defaultTimeoutMs,
+            env: deps.env,
             onSpawn: (info) => {
                 // Chain onto the per-operation write lock; never fire-and-forget a
                 // rejected update (unhandled rejection can crash Console on Windows).
@@ -119,6 +128,10 @@ export async function runOperation(operationId, deps) {
             message: finished.errorMessage,
             state: "needs-reconcile",
         });
+        notifySettled(deps, finished, "needs-reconcile", {
+            ok: false,
+            errorCode: finished.errorCode,
+        });
     }
     return finished;
 }
@@ -169,9 +182,10 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
         // Supervisory timeout without classified CLI timeout → needs-reconcile
         // Only mark timed-out when we have a machine timeout result after exit.
         const state = result.exitCode !== null ? "timed-out" : "needs-reconcile";
-        const updated = await deps.store.update(operationId, {
+        const finishedAt = new Date().toISOString();
+        const patch = {
             state,
-            finishedAt: new Date().toISOString(),
+            finishedAt,
             artifactRefs,
             stdoutPreview: previewStdout,
             stderrPreview: previewStderr,
@@ -186,7 +200,15 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
                     ...(runFacts.runSummary ? { runSummary: runFacts.runSummary } : {}),
                 }
                 : {}),
+        };
+        const current = await deps.store.get(operationId);
+        if (!current)
+            throw new Error(`operation not found: ${operationId}`);
+        await deps.beforeTerminal?.({ ...current, ...patch }, state, {
+            ok: false,
+            errorCode: patch.errorCode,
         });
+        const updated = await deps.store.update(operationId, patch);
         stateEvent(deps.events, updated, state, updated.errorMessage);
         if (runFacts) {
             appendSafeResultEvent(deps, operationId, state, {
@@ -202,6 +224,10 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
                 data: { ok: false, exitCode: result.exitCode },
             });
         }
+        notifySettled(deps, updated, state, {
+            ok: false,
+            errorCode: updated.errorCode,
+        });
         return updated;
     }
     const envelope = coerceEnvelope(result);
@@ -210,7 +236,7 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
     const processOk = envelope?.ok === true || (result.ok && result.exitCode === 0);
     const ok = processOk && !businessBlock;
     const state = ok ? "succeeded" : "failed";
-    const updated = await deps.store.update(operationId, {
+    const patch = {
         state,
         finishedAt: new Date().toISOString(),
         artifactRefs,
@@ -238,9 +264,20 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
                 ...(runFacts.runSummary ? { runSummary: runFacts.runSummary } : {}),
             }
             : {}),
+    };
+    if (!operation)
+        throw new Error(`operation not found: ${operationId}`);
+    await deps.beforeTerminal?.({ ...operation, ...patch }, state, {
+        ok,
+        errorCode: patch.errorCode,
     });
+    const updated = await deps.store.update(operationId, patch);
     stateEvent(deps.events, updated, state, updated.errorMessage);
     appendSafeResultEvent(deps, operationId, state, { ok, exitCode: result.exitCode }, runFacts);
+    notifySettled(deps, updated, state, {
+        ok,
+        errorCode: updated.errorCode,
+    });
     if (ok && operation?.action === "dagRequestInterrupt") {
         await projectInterruptRequestOntoTarget(operation, result.json, deps);
     }
@@ -300,6 +337,10 @@ export function scheduleOperation(operationId, deps) {
         })
             .then((updated) => {
             stateEvent(deps.events, updated, "needs-reconcile", message);
+            notifySettled(deps, updated, "needs-reconcile", {
+                ok: false,
+                errorCode: updated.errorCode,
+            });
         })
             .catch(() => {
             // A failed canonical store update cannot be represented safely.

package/dist/worker/console/operation-sse.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
-import { ensureSecureDir, writeSecureJsonSync } from "./app-data.js";
+import { ensureSecureDir, writeSecureJsonSync } from "../../infrastructure/console/app-data.js";
 const DEFAULT_MAX_EVENTS = 1000;
 function safeOperationId(operationId) {
     return operationId.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 180);

package/dist/worker/console/operation-wait.js

@@ -1,5 +1,5 @@
 import { projectOperationEventSummary, projectOperationForChat, } from "./chat/chat-event-store.js";
-import { isTerminalOperationState, } from "./operation-store.js";
+import { isTerminalOperationState, } from "../../infrastructure/console/operation-store.js";
 /**
  * P2: read-only event-driven long poll on the canonical operation event ring
  * (2026-08-13 Operator Chat long-run supervision). Server contract bounds:

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";
@@ -481,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,
@@ -517,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 {
@@ -536,6 +580,63 @@ async function acceptOperation(ctx, input) {
         },
     };
 }
+/**
+ * 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;
+    };
+    const baseFields = {
+        runId: strParam("runId"),
+        nodeId: strParam("nodeId"),
+        revisionId: strParam("revisionId"),
+    };
+    return (operation, state, info) => {
+        let event;
+        if (action === "artifactRevisionStage") {
+            event = info.ok ? "artifact_revision.validated" : "artifact_revision.rejected";
+        }
+        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) {
         return {
@@ -1148,14 +1249,14 @@ export async function dispatchOperatorAction(ctx, req) {
             if (usesUnifiedSurface) {
                 const inspectPath = target
                     ? buildInspectDeepLink(consoleOrigin, target).slice(consoleOrigin.length)
-                    : "/inspect/#/";
+                    : "/#/inspect";
                 return {
                     kind: "sync",
                     status: 200,
                     body: operatorSucceeded("observeLink", {
                         url: target
                             ? buildInspectDeepLink(consoleOrigin, target)
-                            : `${consoleOrigin.replace(/\/+$/, "")}/inspect/#/`,
+                            : `${consoleOrigin.replace(/\/+$/, "")}/#/inspect`,
                         inspectPath,
                         status: "same-origin",
                         requiredCapability: requiredCapability ?? null,
@@ -1641,9 +1742,10 @@ export async function dispatchOperatorAction(ctx, req) {
                 broadWriteSetRisk: typeof reviewPacket.broadWriteSetRisk === "boolean"
                     ? reviewPacket.broadWriteSetRisk
                     : derivedFacts.broadWriteSetRisk,
-                forbiddenOverlapRisk: typeof reviewPacket.forbiddenOverlapRisk === "boolean"
-                    ? reviewPacket.forbiddenOverlapRisk
-                    : derivedFacts.forbiddenOverlapRisk,
+                // Always use the staged DAG + live task boundary derivation here.
+                // The generation review packet lacks task-boundary scope and can
+                // mistake a narrower node-local exclusion for a global overlap.
+                forbiddenOverlapRisk: derivedFacts.forbiddenOverlapRisk,
                 hasStructuredVerification: packetShellVerification,
             };
             const assessment = assessAutonomousExecutionEligibility(eligibility);
@@ -1816,6 +1918,18 @@ export async function dispatchOperatorAction(ctx, req) {
             const taskIdError = taskIdInputError(taskId);
             if (taskIdError)
                 return invalid(action, taskIdError);
+            // Optional write-set gate approval: the token is the server-issued
+            // `<gate-id>:sha256:<hex>` that `task status` reports in
+            // gate.approveCommand. Forwarded as --approve-gate so an operator can
+            // complete the human approval through the Console operation path
+            // instead of dropping to a raw terminal. This dispatch already sits
+            // behind the Console mutation gate (boot cookie + confirmation
+            // header), so it carries the same authority as typing the CLI flag.
+            const approveGateRaw = str(p.approveGate);
+            if (approveGateRaw &&
+                !/^[A-Za-z0-9._-]+:sha256:[0-9a-f]{64}$/.test(approveGateRaw)) {
+                return invalid(action, "approveGate must look like <gate-id>:sha256:<64-hex> (copy the token from task status gate.approveCommand)");
+            }
             const args = ["task", "advance", taskId];
             const title = str(p.title);
             if (title)
@@ -1829,6 +1943,8 @@ export async function dispatchOperatorAction(ctx, req) {
             const profile = str(p.profile);
             if (profile)
                 args.push("--profile", profile);
+            if (approveGateRaw)
+                args.push("--approve-gate", approveGateRaw);
             appendEngineeringCliArgs(args, parseEngineeringBoundaryFromParams(p));
             args.push("--json");
             return acceptOperation(ctx, {

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

@@ -27,7 +27,11 @@ export function encodeInspectHash(selection) {
     }
 }
 export function buildInspectPath(selection) {
-    return `/inspect/${selection ? encodeInspectHash(selection) : "#/"}`;
+    if (!selection)
+        return "/#/inspect";
+    const hash = encodeInspectHash(selection);
+    const internal = hash.startsWith("#") ? hash.slice(1) : hash;
+    return `/#/inspect${internal}`;
 }
 export function buildInspectUrl(origin, selection) {
     const base = origin.trim().replace(/\/+$/, "");
@@ -99,7 +103,7 @@ export function selectionFromObserveLinkTarget(target) {
 export function normalizeLegacyConsoleDagHash(pathnameAndHash) {
     const [pathname, hash = ""] = pathnameAndHash.split("#", 2);
     if ((pathname === "/" || pathname === "") && /^\/dag\/[^/]+$/.test(hash)) {
-        return `/inspect/#${hash}`;
+        return `/#/inspect${hash}`;
     }
     return pathnameAndHash;
 }

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;