codex-overleaf-link 1.3.7 → 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.7-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.7 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.7/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.7/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.3.7'
+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.7 -- 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.7.zip` from the [v1.3.7 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.3.7), 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.7 -- install-native` |
-| Diagnose | `npm exec --yes codex-overleaf-link@1.3.7 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@1.3.7 -- 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.7 GitHub Release contains:
+The v1.3.8 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.3.7.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.3.7.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.3.7.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.7` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.3.7` 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.7 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@1.3.7 -- 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.7 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.3.7/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.7 -- uninstall-native --browser chromium
+npm exec --yes codex-overleaf-link@1.3.8 -- uninstall-native --browser chromium
 ```
 
 ## Features
@@ -289,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.7 -- install-native
+npm exec --yes codex-overleaf-link@1.3.8 -- install-native
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -338,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.7 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- install-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.3.7 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.3.7 -- 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.7';
+  const BUILD_TARGET_VERSION = '1.3.8';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',