codex-overleaf-link 1.3.6 → 1.3.8

package/README.md

@@ -3,7 +3,7 @@
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-1.3.6-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.3.8-blue" alt="version">
     <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="platform">
     <img src="https://img.shields.io/badge/chrome-MV3-green" alt="chrome manifest v3">
     <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version">
@@ -38,14 +38,14 @@ One command installs the native host **and** sets up the extension: the script r
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.3.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.6/install.sh)"
+CODEX_OVERLEAF_REF=v1.3.8 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.8/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.6/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.3.6'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.8/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.3.8'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -56,10 +56,10 @@ Then, in the `chrome://extensions` tab the script opened: enable **Developer mod
 `npm exec` installs and updates the **native host only** — it does not include the Chrome extension. Use it if you prefer a pinned npm package to a source checkout.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.3.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.8 -- install-native
 ```
 
-Then add the extension yourself: download `codex-overleaf-link-extension-v1.3.6.zip` from the [v1.3.6 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.3.6), unzip it to a stable folder, and in `chrome://extensions` enable **Developer mode**, click **Load unpacked**, and select that folder.
+Then add the extension yourself: download `codex-overleaf-link-extension-v1.3.8.zip` from the [v1.3.8 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.3.8), unzip it to a stable folder, and in `chrome://extensions` enable **Developer mode**, click **Load unpacked**, and select that folder.
 
 ### Open Overleaf
 
@@ -86,9 +86,9 @@ npm installs, updates, uninstalls, and diagnoses the native host only. npm does
 
 | Action | Command |
 |--------|---------|
-| Install / update | `npm exec --yes codex-overleaf-link@1.3.6 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.3.6 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native` |
+| Install / update | `npm exec --yes codex-overleaf-link@1.3.8 -- install-native` |
+| Diagnose | `npm exec --yes codex-overleaf-link@1.3.8 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native` |
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
 
@@ -98,13 +98,13 @@ To update, re-run any of the [native host installers](#install) — they install
 
 ## GitHub Release Artifacts
 
-The v1.3.6 GitHub Release contains:
+The v1.3.8 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.3.6.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.3.6.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.3.6.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.3.6` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.3.6` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.3.8.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.3.8.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.3.8.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.3.8` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.3.8` when run directly from the release artifact.
 - `uninstall-native-host.mjs`: native host uninstaller that removes the Chrome Native Messaging manifest, bridge executable, and runtime copy.
 - `nativeHostPlatform.js`, `manifest.js`, `runtimeInstaller.js`: helper files required by the loose uninstaller asset.
 - `SHA256SUMS` and `release-manifest.json`: checksum and artifact metadata for release verification.
@@ -115,7 +115,7 @@ The v1.3.6 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native
 ```
 
 The same command works on Windows PowerShell. If you installed from a manual checkout or source installer, you can also run `npm run uninstall:native` inside the repo, use `node ~/.codex-overleaf/source/scripts/uninstall-native-host.mjs` on macOS / Linux, or use `node $env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs` on Windows PowerShell.
@@ -150,13 +150,13 @@ Then remove the extension from `chrome://extensions`. To delete local data: on m
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.3.6 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.6/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.3.8 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.8/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -167,6 +167,7 @@ npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native --browser chromium
 - **Diff review** — per-file diff view before accepting changes.
 - **Undo checkpoint** — one-click revert of browser writes.
 - **Track Changes integration** — optionally enables Overleaf Reviewing before writing.
+- **Accept / Undo per run** — when a run wrote in Reviewing mode, accept or revert all of its tracked changes from the run card in one click. Accept replays the run's edits as untracked text via Overleaf's native undo path, with stable-Editing waits and an automatic rollback if Overleaf reintroduces tracked changes during the replay.
 - **Auto-recompile** — triggers Overleaf recompile after writeback; logs compile errors as context.
 - **@ context** — attach specific files, `@compile-log`, or `@current-section` to the prompt.
 - **Composer attachments and binary writeback** — paste or drop PDFs, images, and files into the composer as turn-scoped Codex context, and review Codex-created assets before creating or replacing them in Overleaf.
@@ -288,7 +289,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Re-run any [native host installer](#install), reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This also fixes extension/native version mismatch and native protocol mismatch.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.3.6 -- install-native
+npm exec --yes codex-overleaf-link@1.3.8 -- install-native
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -337,8 +338,8 @@ Use this matrix for release-candidate signoff and compatibility reports. Record
 | Browser/channel/version | Google Chrome channel and version. | Google Chrome channel and version. | Google Chrome channel and version. | Chromium channel/package and version. |
 | Install mode | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout; native host installed with `--browser chromium`. |
 | Extension id | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. |
-| Installer/update command | `npm exec --yes codex-overleaf-link@1.3.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.6 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.3.8 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native --browser chromium` |
 | Manifest/registry path | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` -> `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
 | Bridge/runtime/source path | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `%LOCALAPPDATA%\CodexOverleaf\codex-overleaf-bridge.cmd`; runtime `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime`; source `%LOCALAPPDATA%\CodexOverleaf\source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. |
 | Node/Git/Codex/TeX | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. |

package/extension/src/shared/agentTranscript.js

@@ -1,12 +1,27 @@
 (function initAgentTranscript(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory({
+      getFailureReasons: function getFailureReasonsCjs() { return require('./failureReasons.js'); },
+      getI18n: function getI18nCjs() { return require('./i18n.js'); }
+    });
   } else {
-    root.CodexOverleafAgentTranscript = factory();
+    // Browser script-tag load order is determined by manifest.json content_scripts;
+    // resolve dependencies lazily so this module can be listed before its deps.
+    root.CodexOverleafAgentTranscript = factory({
+      getFailureReasons: function getFailureReasonsWindow() { return root.CodexOverleafFailureReasons || null; },
+      getI18n: function getI18nWindow() { return root.CodexOverleafI18n || null; }
+    });
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function agentTranscriptFactory() {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function agentTranscriptFactory(deps) {
   'use strict';
 
+  const getFailureReasonsModule = (deps && deps.getFailureReasons) instanceof Function
+    ? deps.getFailureReasons
+    : function noFailureReasons() { return null; };
+  const getI18nModule = (deps && deps.getI18n) instanceof Function
+    ? deps.getI18n
+    : function noI18n() { return null; };
+
   const TECHNICAL_EVENT_PATTERNS = [
     /^agent\.command\./,
     /^native\.task\./,
@@ -523,6 +538,16 @@
         nextStep: textFor(locale, '请确认终端里可以运行 `codex`，然后重新安装 native host 或刷新扩展后重试。', 'Confirm `codex` works in Terminal, then reinstall the native host or reload the extension.')
       };
     }
+    if (/project_locked|currently in use by codex\.run/i.test(text)) {
+      return {
+        conclusion: textFor(locale,
+          '这轮没有启动：同一个 Overleaf 项目里已经有一轮 Codex 任务正在运行。',
+          'This run did not start: another Codex task is already running for this Overleaf project.'),
+        nextStep: textFor(locale,
+          '请等待当前任务完成，或先取消当前任务后再重试。',
+          'Wait for the current task to finish, or cancel it before retrying.')
+      };
+    }
     if (/unsupported[_ ]parameter/i.test(text) && /reasoning\.summary|summary/i.test(text)) {
       return {
         conclusion: textFor(locale, '这轮没有继续：当前 Codex 模型不支持插件请求的推理摘要参数。', 'This run did not continue: the selected Codex model does not support the requested reasoning summary parameter.'),
@@ -548,6 +573,21 @@
       };
     }
 
+    // When the caller signals Codex DID produce an answer (assistantMessage
+    // arrived on the stream) but an unrelated exception still escaped to the
+    // outer catch — the original 'no usable result' copy is wrong-by-design
+    // because the user can see Codex's answer in chat. Surface the real
+    // shape: Codex returned, post-processing failed, the answer is preserved.
+    if (context.codexReturned) {
+      return {
+        conclusion: textFor(locale,
+          'Codex 已经返回了结果，但本地处理这一轮时出错了。',
+          'Codex returned a result, but local post-processing of this run failed.'),
+        nextStep: textFor(locale,
+          '请打开技术详情查看错误。Codex 的回答仍保留在会话中。',
+          'Open Technical Details to inspect the error. Codex\'s answer is preserved in the conversation.')
+      };
+    }
     return {
       conclusion: context.mode === 'ask'
         ? textFor(locale, '这轮只问不改没有完成：本地 Codex 没有正常完成，因此没有生成最终说明。', 'This Ask run did not complete: local Codex did not finish normally, so no final answer was generated.')
@@ -582,10 +622,88 @@
     return {
       title: textFor(locale, '本轮完成报告', 'Task report'),
       status: failed ? 'failed' : 'completed',
-      text: formatHumanReport(report, locale)
+      text: formatHumanReport(report, locale),
+      structured: buildStructuredHumanReport(report, locale)
     };
   }
 
+  /**
+   * Thin wrapper that renders just the fallback final-report text for a
+   * writeback `apply` payload. Used by tests and by callers that only need the
+   * skipped-block formatting without the full completion-report envelope.
+   * @param {{ apply: { applied?: any[], skipped?: any[] }, locale?: string, includeWriteResult?: boolean, status?: string }} input
+   * @returns {string}
+   */
+  function formatFallbackFinalReport(input = {}) {
+    const locale = normalizeLocale(input);
+    const apply = (input && input.apply) || {};
+    const report = buildHumanCompletionReport({
+      locale,
+      status: input.status || 'failed',
+      operations: [],
+      applyResults: [apply],
+      includeWriteResult: input.includeWriteResult !== false,
+      undoCount: 0
+    });
+    return report.text;
+  }
+
+  /**
+   * Splits the human report into a conclusion (the human-language outcome),
+   * a body of list-style content sections (checked / findings / planned /
+   * changes / skipped), and a meta block of run-metadata key/value rows
+   * (unchanged reason, write result, undo, next). The renderer uses this to
+   * visually demote the meta block — it is system info about the run, not
+   * part of Codex's answer. `formatHumanReport` retains the legacy flat-text
+   * shape for transcripts, storage fallback, and existing assertions.
+   */
+  function buildStructuredHumanReport(report = {}, locale = 'zh') {
+    const conclusion = cleanVisibleMarkdownText(report.conclusion || '');
+
+    const bodySections = [];
+    addListSection(bodySections, textFor(locale, '检查范围', 'Checked'), report.checked, locale);
+    addListSection(bodySections, textFor(locale, '发现', 'Findings'), report.findings, locale);
+    addListSection(bodySections, textFor(locale, '计划修改', 'Planned changes'), report.plannedChanges, locale);
+    addListSection(bodySections, textFor(locale, '修改', 'Changes'), report.appliedChanges, locale);
+    addStructuredListSection(bodySections, textFor(locale, '跳过原因', 'Skipped'), report.skippedChanges, locale);
+
+    const meta = [];
+    const unchangedReason = localizeVisibleReason(report.unchangedReason || '', locale);
+    if (unchangedReason) {
+      meta.push({
+        key: 'unchangedReason',
+        label: textFor(locale, '未修改原因', 'Why nothing changed'),
+        value: unchangedReason
+      });
+    }
+    const writeResult = cleanVisibleText(report.writeResult || '');
+    if (writeResult) {
+      meta.push({
+        key: 'writeResult',
+        label: textFor(locale, '写入结果', 'Write result'),
+        value: writeResult
+      });
+    }
+    const undo = cleanVisibleText(report.undo || '');
+    if (undo) {
+      meta.push({
+        key: 'undo',
+        label: textFor(locale, '可撤销', 'Undo'),
+        value: undo
+      });
+    }
+    const nextStep = cleanVisibleText(report.nextStep || '');
+    if (nextStep) {
+      meta.push({
+        key: 'nextStep',
+        label: textFor(locale, '下一步', 'Next'),
+        value: nextStep
+      });
+    }
+
+    return { conclusion, body: bodySections.join('\n\n'), meta };
+  }
+
   function formatHumanReport(report = {}, locale = 'zh') {
     const sections = [];
     const conclusion = cleanVisibleMarkdownText(report.conclusion || '');
@@ -604,7 +722,7 @@
     if (writeResult) {
       sections.push(textFor(locale, `写入结果：${writeResult}`, `Write result: ${writeResult}`));
     }
-    addListSection(sections, textFor(locale, '跳过原因', 'Skipped'), report.skippedChanges, locale);
+    addStructuredListSection(sections, textFor(locale, '跳过原因', 'Skipped'), report.skippedChanges, locale);
     const undo = cleanVisibleText(report.undo || '');
     if (undo) {
       sections.push(textFor(locale, `可撤销：${undo}`, `Undo: ${undo}`));
@@ -640,10 +758,36 @@
         ? formatWriteResult(counts.appliedCount, counts.skippedCount, locale)
         : ''),
       undo: input.undo,
-      nextStep: input.nextStep || counts.translatedError?.nextStep || formatFallbackNextStep(input, counts.skippedCount, affectedFiles, locale)
+      nextStep: input.nextStep
+        || counts.translatedError?.nextStep
+        || formatPrimaryFailureNextStep(input.applyResults, locale)
+        || formatFallbackNextStep(input, counts.skippedCount, affectedFiles, locale)
     };
   }
 
+  /**
+   * Derive the run-level next-step from the highest-priority skipped failure
+   * via `selectPrimaryFailure`. Returns '' when no usable primary failure
+   * exists, so callers can fall through to the generic copy.
+   */
+  function formatPrimaryFailureNextStep(applyResults, locale) {
+    const failureReasons = getFailureReasonsModule();
+    if (!failureReasons || !failureReasons.selectPrimaryFailure || !failureReasons.normalizeFailureReason) {
+      return '';
+    }
+    const skipped = collectSkippedOperations(applyResults);
+    if (!skipped.length) {
+      return '';
+    }
+    const failures = skipped.map(item =>
+      failureReasons.normalizeFailureReason(item.result, item.operation || {}, { locale })
+    ).filter(Boolean);
+    const primary = failureReasons.selectPrimaryFailure(failures);
+    if (!primary) return '';
+    const localized = failureReasons.localizeFailureReason(primary, locale, failureI18nLookup(locale));
+    return localized.nextAction || primary.nextAction || '';
+  }
+
   function formatWriteResult(appliedCount, skippedCount, locale = 'zh') {
     return textFor(
       locale,
@@ -919,6 +1063,27 @@
     sections.push(`${label}${locale === 'en' ? ':' : '：'}\n${items.map(item => `- ${item}`).join('\n')}`);
   }
 
+  /**
+   * Same as `addListSection` but preserves item-internal newlines so that
+   * structured FailureReason blocks (Reason/Stage/Code/Next) survive into the
+   * rendered report. Per-item first line gets the `- ` bullet; subsequent
+   * lines pass through verbatim (the formatter already indents them).
+   */
+  function addStructuredListSection(sections, label, values, locale = 'zh') {
+    const items = normalizeMultilineStringList(values);
+    if (!items.length) {
+      return;
+    }
+    sections.push(`${label}${locale === 'en' ? ':' : '：'}\n${items.map(item => `- ${item}`).join('\n')}`);
+  }
+
+  function normalizeMultilineStringList(value) {
+    const values = Array.isArray(value) ? value : (value ? [value] : []);
+    return values
+      .map(item => cleanVisibleMarkdownText(item))
+      .filter(Boolean);
+  }
+
   function normalizeStringList(value) {
     const values = Array.isArray(value) ? value : (value ? [value] : []);
     return values
@@ -1034,12 +1199,107 @@
     const operation = item?.operation || {};
     const labels = OPERATION_LABELS[locale] || OPERATION_LABELS.zh;
     const label = labels[operation.type] || operation.type || textFor(locale, '处理', 'process');
-    const filePath = operation.path || operation.from || operation.to || textFor(locale, '未知文件', 'unknown file');
     const result = item?.result || {};
-    const reason = formatSkippedReason(result, operation, locale);
+    const filePath = operation.path || operation.from || operation.to || (
+      result?.failure?.stage === 'write' || result?.code === 'editor_project_id_unavailable' || result?.code === 'aborted_project_changed'
+        ? textFor(locale, '写入流程', 'writeback process')
+        : textFor(locale, '未知文件', 'unknown file')
+    );
+    const headerLine = locale === 'en'
+      ? `${filePath}: ${label} was not written`
+      : `${filePath}：${label}没有写入`;
+    const block = formatFailureBlockForResult(result, operation, locale);
+    if (block) {
+      return `${headerLine}\n${block}`;
+    }
+    // Last-resort fallback: legacy parenthesized form, only when neither
+    // a structured failure nor the normalizer surfaces a usable record.
+    const legacyReason = formatSkippedReason(result, operation, locale);
     return locale === 'en'
-      ? `${filePath}: ${label} was not written (${reason})`
-      : `${filePath}：${label}没有写入（${reason}）`;
+      ? `${headerLine} (${legacyReason})`
+      : `${headerLine}（${legacyReason}）`;
+  }
+
+  /**
+   * Render a `FailureReason` (already localized) as a four-line indented block:
+   *   <indent>Reason: <userMessage>
+   *   <indent>Stage: <stage>
+   *   <indent>Code: <code>
+   *   <indent>Next: <nextAction>   (only when present)
+   * The `Next` line is omitted when the failure has no `nextAction`.
+   * @param {{ userMessage: string, stage: string, code: string, nextAction?: string }} failure
+   * @param {string} locale - 'en' or 'zh'.
+   * @param {string} [indent='  '] - String prefix applied to every line.
+   * @returns {string}
+   */
+  function formatFailureBlock(failure, locale, indent) {
+    const pad = indent === undefined ? '  ' : indent;
+    const i18nModule = getI18nModule();
+    const headingKey = label => (
+      i18nModule && i18nModule.t ? i18nModule.t(locale, label) : null
+    ) || defaultSectionHeading(label, locale);
+    const sectionHeading = headingKey('failureReason_section_heading');
+    const sectionStage = headingKey('failureReason_section_stage');
+    const sectionCode = headingKey('failureReason_section_code');
+    const sectionNext = headingKey('failureReason_section_next');
+    const lines = [];
+    lines.push(`${pad}${sectionHeading}: ${failure.userMessage || ''}`);
+    lines.push(`${pad}${sectionStage}: ${failure.stage || ''}`);
+    lines.push(`${pad}${sectionCode}: ${failure.code || ''}`);
+    if (failure.nextAction) {
+      lines.push(`${pad}${sectionNext}: ${failure.nextAction}`);
+    }
+    return lines.join('\n');
+  }
+
+  function defaultSectionHeading(key, locale) {
+    const en = {
+      failureReason_section_heading: 'Reason',
+      failureReason_section_stage: 'Stage',
+      failureReason_section_code: 'Code',
+      failureReason_section_next: 'Next'
+    };
+    const zh = {
+      failureReason_section_heading: '原因',
+      failureReason_section_stage: '阶段',
+      failureReason_section_code: '代码',
+      failureReason_section_next: '下一步'
+    };
+    const dict = locale === 'zh' ? zh : en;
+    return dict[key] || key;
+  }
+
+  /**
+   * Build the localized FailureReason block for a skipped writeback item.
+   * Returns '' when the failureReasons module is unavailable, which makes
+   * callers fall back to the legacy parenthesized form.
+   */
+  function formatFailureBlockForResult(result, operation, locale) {
+    const failureReasons = getFailureReasonsModule();
+    if (!failureReasons || !failureReasons.normalizeFailureReason) {
+      return '';
+    }
+    const failure = failureReasons.normalizeFailureReason(result, operation || {}, { locale });
+    if (!failure || !failure.code) {
+      return '';
+    }
+    const localized = failureReasons.localizeFailureReason(failure, locale, failureI18nLookup(locale));
+    const rendered = Object.assign({}, failure, {
+      userMessage: localized.userMessage || failure.userMessage,
+      nextAction: localized.nextAction || failure.nextAction
+    });
+    return formatFailureBlock(rendered, locale, '  ');
+  }
+
+  function failureI18nLookup(locale) {
+    return function lookup(key) {
+      const i18nModule = getI18nModule();
+      if (!i18nModule || !i18nModule.t) return undefined;
+      const localized = i18nModule.t(locale, key);
+      // i18n.t returns the key itself on miss; treat that as miss so the
+      // catalog fallback wins for codes without bespoke localization.
+      return localized && localized !== key ? localized : undefined;
+    };
   }
 
   function formatSkippedReason(result = {}, operation = {}, locale = 'zh') {
@@ -1204,6 +1464,9 @@
 
   return {
     buildHumanCompletionReport,
+    buildStructuredHumanReport,
+    formatFallbackFinalReport,
+    formatFailureBlock,
     formatHumanReport,
     mapAgentEventToActivity,
     translateRawError

package/extension/src/shared/compatibility.js

@@ -12,7 +12,7 @@
   const MIN_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_EXTENSION_VERSION = '1.0.0';
-  const BUILD_TARGET_VERSION = '1.3.6';
+  const BUILD_TARGET_VERSION = '1.3.8';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',