opencode-metrics-plugin 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.4（2026-09-14）
+
+- 修复 0.3.3 发布事故：package.json 误带 UTF-8 BOM，npm 可安装但 opencode 解析插件清单失败并**静默跳过加载**——所有 0.3.3 用户完全不采集、不上传、日志无任何痕迹。升级本版后必须删除插件缓存并重启 opencode（Windows `%USERPROFILE%\.cache\opencode\packages\opencode-metrics-plugin*`，macOS `~/Library/Caches/opencode/packages/` 同名目录）；事故期间未采集的会话无法补录，装好后孤儿补传会自动补传 7 天内未上终态的历史快照。
+- 用户可编辑文件读取容忍 BOM：`opencode-metrics.json(.jsonc)` 与 `agc-apiclient.json` 用 Windows PowerShell 或旧版编辑器保存不再静默失效。
+- 发布防复发：`prepublishOnly` 增加 package.json BOM 守卫，命中即发布失败。
+
+## 0.3.3（2026-09-12）
+
+- session-end 三层保障，修复宿主进程突然死亡导致会话终态包永不产出的问题：
+  - **task 工具终态触发**：根会话的 task 工具 `completed` / `error` 即刻打包上传 session-end（子代理嵌套调用不触发，callID 去重）；
+  - **打包前快照终稿化**：打包前先冲刷事件日志与引擎快照，包内快照必含触发事件本身（原 2s 冷却可能落后）；
+  - **孤儿快照补传**：启动时扫描静默超 24h 且未上云终态的快照（`metrics/.sent/` 已传标记防重），按快照证据补打 session-end 包，超 7 天放弃（`upload.orphanRescue` 可调）。
+- 场景系统支持 `tools` 工具名匹配器（内置 session-end 即 `tools: ["task"]`）；`session.created` 即种子工作区证据，纯 task 会话也能完成根推断与包名推断。
+
 ## 0.3.2（2026-09-12）
 
 - 产物根推断增强：迁移工作区标记修正为 `.migration`；安卓工程根容器化降级（向内提升鸿蒙子工程与 `.migration`/`.harmonyos` 工作区）；会话时间窗内新建的相邻鸿蒙工程纳入，邻居老工程不混入；纯安卓工程不打包。

package/README.md

@@ -4,7 +4,7 @@
 
 - **开箱即用**：宿主只需在 `opencode.json` 加一行，无需任何配置
 - **实时落盘**：会话进行中每 2s 增量写盘，中途退出不丢数据
-- **开箱即传**：上传默认开启（包内 AGC 凭证），`git commit` / 会话结束自动打包上传，安卓源码工程自动剔除，`upload.enabled: false` 可关
+- **开箱即传**：上传默认开启（包内 AGC 凭证），`git commit` / 根会话 task 完成 / 会话结束自动打包上传，安卓源码工程自动剔除，`upload.enabled: false` 可关
 - **独立配置文件**：`.opencode/opencode-metrics.json(.jsonc)` 支持注释，存在即完全接管内联配置；用户目录 `~/.config/opencode/` 可放全局兜底配置
 - **失败不丢**：上传失败的包保留在 `failed/`（与云端路径同构，可手动上传），下次启动自动补偿重传
 - **零打扰**：不修改工作区、不执行 clean
@@ -57,12 +57,13 @@
 
 默认开启（`upload.enabled: false` 可关）：
 
-- **触发场景**：bash 执行 `git commit`（label=`git`）、会话结束/插件退出（label=`session-end`）；可自定义场景（命令正则或事件名）
+- **触发场景**：bash 执行 `git commit`（label=`git`）；会话结束/插件退出（label=`session-end`）；**根会话 task 工具完成或失败即刻触发 session-end**（子代理嵌套调用不触发）。可自定义场景（命令正则、事件名或工具名）
 - **打包内容**：时点快照 JSON + 事件日志（恒含）+ 会话动过的工作区产物根（鸿蒙工程标记探测，≤3 个）+ build 目录内的 `.hap` 产物包（借道组装目录，不受 build 黑名单影响）
 - **根推断增强**：安卓工程根（如 gradle 外壳）不整根保留也不丢弃——向内扫描提升鸿蒙子工程（`ohos/` 等）与迁移工作区（`.migration` / `.harmonyos`）；会话期间新建的相邻鸿蒙工程（目录 mtime 在会话开始之后）也会纳入，邻居老工程不混入；纯安卓工程（无任何鸿蒙子根）不打包
 - **自动剔除**：黑名单目录（`oh_modules` / `build` / `node_modules` 等 8 项）；安卓工程（根级 + 子树级，gradle 信号 ≥2 判定，可用 `excludeAndroidProjects: false` 关闭）
 - **云端路径**：`YYYYMMDD/<安卓包名或项目名>-<sessionId>/<agent缩写>-<触发>-v<n>/<agent缩写>-<触发>-v<n>.tar.gz` 与同名 `.json`（一个版本一个目录，双文件归拢；日期取包创建日）
 - **可靠性**：串行队列 + 指数退避重试（默认 5 次，4xx 不重试）；失败包移入暂存目录 `failed/` 下**与云端同构的目录**（含 meta 元数据，可整目录手动上传），下次启动自动补偿重传，重传成功即清理；保留超期（默认 7 天）或超量（默认 1GB，从最旧删）自动清理
+- **进程死亡兜底**：宿主突然退出（session-end 从未触发）时，下次启动对静默超 24h 且未传终态的快照自动补打 session-end 包（`metrics/.sent/` 已传标记防重传，超 7 天放弃）
 
 ## 输出目录
 
@@ -70,10 +71,16 @@
 
 | 平台 | 路径 |
 |---|---|
-| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}`、`...\Log\log\plugin\YYYYMMDD.log`（运行日志按日期归档，保留 30 天）、`...\Data\upload-staging` |
+| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}`（metrics 下另有 `.sent/` 已传终态标记）、`...\Log\log\plugin\YYYYMMDD.log`（运行日志按日期归档，保留 30 天）、`...\Data\upload-staging` |
 | Linux | `~/.local/state/opencode-metrics-plugin/{metrics,events}` |
 | macOS | `~/Library/Logs/opencode-metrics-plugin/{metrics,events}` |
 
+## 升级与排障
+
+- **升级不生效**：opencode 将插件缓存在本机且不自动更新，升级后须删缓存再重启——Windows `%USERPROFILE%\.cache\opencode\packages\` 下的 `opencode-metrics-plugin*` 目录，macOS `~/Library/Caches/opencode/packages/` 下同名目录。
+- **装上完全没反应（日志无 `[MetricsPlugin] started`）**：若装的是 0.3.3，系发布事故——该版 package.json 误带 UTF-8 BOM，opencode 静默跳过插件（不采集、不上传、无报错）。升级 0.3.4+ 并删缓存即恢复；期间丢的会话无法补录，装好后 7 天内未上终态的老快照会被孤儿补传自动救回。
+- **验证插件已加载**：插件日志（`log/plugin/YYYYMMDD.log`）首屏出现 `[MetricsPlugin] started` 行。
+
 ## 配置项速查
 
 全部可选；独立文件与内联第二参字段相同。
@@ -93,13 +100,14 @@
 |---|---|---|---|
 | `upload.enabled` | boolean | `true` | 上传总开关；`false` 显式关闭 |
 | `upload.uploader.agcConfigPath` | string | 包内凭证 | `agc-apiclient.json` 绝对路径（client_id/secret/project_id/region/bucket） |
-| `upload.scenarios` | object | 内置两场景 | 按 key 合并：`enabled:false` 禁用内置；自定义场景提供 `commands`（正则）或 `events`（事件名）与 `label`（进文件名） |
+| `upload.scenarios` | object | 内置两场景 | 按 key 合并：`enabled:false` 禁用内置；自定义场景提供 `commands`（正则）/ `events`（事件名）/ `tools`（工具名，终态触发）与 `label`（进文件名） |
 | `upload.appendArtifacts` | array | — | 追加产物规则：`path`（绝对或相对会话工作目录）+ `matchBy`（`session-activity` 会话动过才纳入 / `existence` 存在即纳入）+ `dirMarkers`/`fileMarkers` |
 | `upload.blacklist` | string[] | 默认 8 项 | 打包排除的目录/文件名（追加，不替换） |
 | `upload.excludeAndroidProjects` | boolean | `true` | 剔除安卓工程（根级 + 根内子树） |
 | `upload.maxArtifactBytes` | number | `524288000` | 单包体积上限（默认 500MB），超限该次标失败 |
 | `upload.retry` | object | `{5, 1000}` | `maxAttempts` 最大尝试次数；`backoffMs` 退避基数（1s/4s/16s/64s/256s） |
 | `upload.retryRescue` | object | `{true, 7, 1GB}` | 失败保留与补偿重传：`enabled` 开关；`retentionDays` 保留天数；`maxFailedBytes` failed/ 总量上限（超限从最旧删） |
+| `upload.orphanRescue` | object | `{true, 24, 7}` | 孤儿快照补传：`enabled` 开关；`idleHours` 静默下限（小时）；`maxAgeDays` 最大快照年龄（天），超龄放弃 |
 
 ## 可编程 API
 
@@ -125,7 +133,7 @@ rt.engine.dispose()
 
 ```bash
 npm run typecheck   # tsc --noEmit
-npm test            # 冒烟测试（example/smoke.mts，71 断言）
+npm test            # 冒烟测试（example/smoke.mts，90 断言）
 npm run build       # 清空 dist 后 tsc
 ```
 

package/dist/metrics/configLoader.js

@@ -58,7 +58,7 @@ function readFirstExisting(baseDirectory, names) {
     for (const name of names) {
         const candidate = path.join(baseDirectory, name);
         try {
-            return { configPath: candidate, raw: fs.readFileSync(candidate, "utf-8") };
+            return { configPath: candidate, raw: fs.readFileSync(candidate, "utf-8").replace(/^\uFEFF/, "") };
         }
         catch {
             // 该名字的文件不存在，尝试下一个

package/dist/metrics/runtime.js

@@ -21,7 +21,11 @@ export function createMetricsRuntime(opts = {}) {
     const uploadManager = createUploadManager({
         config: opts.upload,
         dirs,
-        onBeforeArchive: () => eventLogger?.flush(),
+        onBeforeArchive: (sessionId) => {
+            eventLogger?.flush();
+            // 引擎快照即时落盘：包内快照为触发时刻终稿（而非落后 checkpoint 间隔的旧稿）
+            engine.flush(sessionId);
+        },
     });
     return {
         dirs,

package/dist/metrics/upload/agcUploader.js

@@ -31,7 +31,7 @@ export function defaultAgcConfigPath() {
 export function loadAgcCredentials(configPath, tokenCacheDir) {
     let raw;
     try {
-        raw = fs.readFileSync(configPath, "utf-8");
+        raw = fs.readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
     }
     catch (err) {
         return { ok: false, reason: `读取配置失败 ${configPath}: ${String(err)}` };

package/dist/metrics/upload/scenarios.d.ts

@@ -1,5 +1,5 @@
 import type { ScenarioConfig } from "./types.js";
-/** 解析后的触发场景：label 用于文件命名，commands/events 为两类匹配源 */
+/** 解析后的触发场景：label 用于文件命名，commands/events/tools 为三类匹配源 */
 export interface ResolvedScenario {
     key: string;
     /** 命名标签（文件名 <sessionId>-<agentName>-<label>-v<n> 的一段） */
@@ -9,12 +9,25 @@ export interface ResolvedScenario {
     commandRegexes: RegExp[];
     /** 匹配的事件名（含特殊值 "dispose"，由管理器结束时触发） */
     events: string[];
+    /** 匹配的工具名（根会话直接调用的工具 completed/error 时触发） */
+    toolNames: string[];
 }
 /**
- * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
- * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events/tools
+ * 可覆盖、enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
  *
  * @param configs opencode.json upload.scenarios
  * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
  */
 export declare function resolveScenarios(configs?: Record<string, ScenarioConfig>): ResolvedScenario[];
+/**
+ * 判定工具终态事件命中的场景：根会话直接调用的工具进入终态
+ * （completed/error）时命中其 toolNames；子代理嵌套调用不命中。
+ *
+ * @param scenarios    已解析场景（含禁用项，函数内过滤 enabled）
+ * @param tool         工具名
+ * @param status       工具状态（仅 completed/error 视为终态）
+ * @param isRootSession 事件原始会话是否根会话（未被子代理映射）
+ * @returns             命中的启用场景列表
+ */
+export declare function matchToolScenarios(scenarios: ResolvedScenario[], tool: string, status: string, isRootSession: boolean): ResolvedScenario[];

package/dist/metrics/upload/scenarios.js

@@ -1,12 +1,16 @@
 import { log } from "../../shared/log.js";
 /** 内置默认场景（opencode.json scenarios 按 key 合并覆盖） */
 const BUILTIN_SCENARIOS = {
-    "session-end": { label: "session-end", events: ["dispose", "session.deleted"] },
+    "session-end": {
+        label: "session-end",
+        events: ["dispose", "session.deleted"],
+        tools: ["task"],
+    },
     "git-commit": { label: "git", commands: ["\\bgit\\s+commit\\b"] },
 };
 /**
- * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
- * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events/tools
+ * 可覆盖、enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
  *
  * @param configs opencode.json upload.scenarios
  * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
@@ -37,7 +41,25 @@ export function resolveScenarios(configs) {
             enabled: config.enabled !== false,
             commandRegexes,
             events: config.events ?? [],
+            toolNames: config.tools ?? [],
         });
     }
     return result;
 }
+/**
+ * 判定工具终态事件命中的场景：根会话直接调用的工具进入终态
+ * （completed/error）时命中其 toolNames；子代理嵌套调用不命中。
+ *
+ * @param scenarios    已解析场景（含禁用项，函数内过滤 enabled）
+ * @param tool         工具名
+ * @param status       工具状态（仅 completed/error 视为终态）
+ * @param isRootSession 事件原始会话是否根会话（未被子代理映射）
+ * @returns             命中的启用场景列表
+ */
+export function matchToolScenarios(scenarios, tool, status, isRootSession) {
+    if (!isRootSession || !tool)
+        return [];
+    if (status !== "completed" && status !== "error")
+        return [];
+    return scenarios.filter((scenario) => scenario.enabled && scenario.toolNames.includes(tool));
+}

package/dist/metrics/upload/types.d.ts

@@ -25,6 +25,8 @@ export interface ScenarioConfig {
     commands?: string[];
     /** TRACKED_EVENT_TYPES 内事件名 */
     events?: string[];
+    /** 工具名匹配器：根会话直接调用的工具进入终态（completed/error）时触发 */
+    tools?: string[];
 }
 /** 上传通道配置（当前仅 agc） */
 export interface UploaderConfig {
@@ -46,6 +48,15 @@ export interface RetryRescueConfig {
     /** failed/ 总量字节上限，超限从最旧删除（缺省 1GB） */
     maxFailedBytes?: number;
 }
+/** 孤儿快照补传：宿主死亡导致终态触发从未发生时，启动后按快照年龄补打 session-end 包 */
+export interface OrphanRescueConfig {
+    /** 缺省 true：启用孤儿快照补传 */
+    enabled?: boolean;
+    /** 快照静默多久视为孤儿（小时，缺省 24；活跃会话快照始终排除） */
+    idleHours?: number;
+    /** 快照最大补传年龄（天，缺省 7，超过视为陈旧放弃） */
+    maxAgeDays?: number;
+}
 /** opencode.json 的 upload 配置整块（§13.8） */
 export interface UploadConfig {
     /** 上传总开关，缺省 true（装上即上传）；false 显式关闭 */
@@ -61,6 +72,7 @@ export interface UploadConfig {
     maxArtifactBytes?: number;
     retry?: UploadRetryConfig;
     retryRescue?: RetryRescueConfig;
+    orphanRescue?: OrphanRescueConfig;
 }
 /** 暂存目录内的单个上传文件（归档包或快照） */
 export interface UploadPackageFile {

package/dist/metrics/upload/uploadManager.d.ts

@@ -4,8 +4,8 @@ export interface UploadManagerOptions {
     config?: UploadConfig;
     /** 实例目录（metricsDir/eventsDir/uploadStagingDir） */
     dirs: MetricsDirs;
-    /** 归档前回调（事件日志冲刷落盘，消除缓冲延迟导致的空 events 竞态） */
-    onBeforeArchive?: () => void;
+    /** 归档前回调（事件日志冲刷 + 引擎快照落盘，消除缓冲延迟导致的旧快照/空 events 竞态） */
+    onBeforeArchive?: (sessionId: string) => void;
 }
 export interface UploadManager {
     /** 旁路观察事件：收集证据 + 场景命中判定（须在 engine.ingest 之后调用，保证快照先落盘） */
@@ -23,3 +23,30 @@ export interface UploadManager {
  * @param options 配置与目录
  */
 export declare function createUploadManager(options: UploadManagerOptions): UploadManager | null;
+/**
+ * 记录会话终态包已成功上云。
+ * 快照原件（metrics/<sessionId>.json）会永久保留为本地记录，
+ * "已传标记"才是孤儿扫描防重复上传的依据。
+ */
+export declare function markSessionUploaded(metricsDir: string, sessionId: string): void;
+/** 会话终态包是否已成功上云 */
+export declare function isSessionUploaded(metricsDir: string, sessionId: string): boolean;
+/** 孤儿快照候选：从磁盘快照恢复的会话证据 */
+export interface OrphanSnapshot {
+    sessionId: string;
+    filePath: string;
+    workingDirectory: string;
+    agentName: string;
+    startedAt: number;
+}
+/**
+ * 扫描目录选出孤儿快照候选：mtime 静默 [idleMs, maxAgeMs] 且不在活跃集的快照。
+ * 上传成功后快照即被删除，"文件仍在"天然等价于"终态未传出"。
+ *
+ * @param metricsDir 快照目录
+ * @param idleMs     静默下限（毫秒）
+ * @param maxAgeMs   年龄上限（毫秒）
+ * @param isActive   活跃会话判定（IO 前后各查一次，防竞态）
+ * @returns           候选列表（无法解析的快照跳过）
+ */
+export declare function selectOrphanSnapshots(metricsDir: string, idleMs: number, maxAgeMs: number, isActive: (sessionId: string) => boolean): Promise<OrphanSnapshot[]>;

package/dist/metrics/upload/uploadManager.js

@@ -5,7 +5,7 @@ import { EvidenceCollector, isPathInside, resolveAndroidProjectName, resolveWork
 import { archiveSessionPackage } from "./packageArchiver.js";
 import { createAgcUploader, composeRemoteBase, defaultAgcConfigPath, loadAgcCredentials, remoteArchiveKey } from "./agcUploader.js";
 import { createUploadQueue } from "./uploadQueue.js";
-import { resolveScenarios } from "./scenarios.js";
+import { resolveScenarios, matchToolScenarios } from "./scenarios.js";
 import { MAX_ROOTS } from "./types.js";
 /**
  * 创建上传管理器：串联证据 → 根推断 → 打包 → 队列 → AGC 上传，
@@ -25,6 +25,10 @@ export function createUploadManager(options) {
     const uploader = createAgcUploader(credentialsResult.credentials);
     const scenarios = resolveScenarios(config.scenarios);
     const directories = options.dirs;
+    // 终态场景标签集合：这些标签的包上传成功即写已传标记（孤儿扫描防重依据）
+    const terminalLabels = new Set(scenarios
+        .filter((s) => s.enabled && (s.events.includes("session.deleted") || s.toolNames.length > 0))
+        .map((s) => s.label));
     // 失败保留与启动补偿配置（默认开启）
     const rescueEnabled = config.retryRescue?.enabled !== false;
     const retentionMs = (config.retryRescue?.retentionDays ?? 7) * 24 * 60 * 60 * 1000;
@@ -41,6 +45,10 @@ export function createUploadManager(options) {
                 removeQuietly(uploadPackage.archive.filePath);
                 removeQuietly(uploadPackage.snapshot.filePath);
                 removeQuietly(metaPath);
+                // 终态包上云成功：写已传标记，孤儿扫描据此跳过该会话
+                if (terminalLabels.has(uploadPackage.trigger)) {
+                    markSessionUploaded(directories.metricsDir, uploadPackage.sessionId);
+                }
                 // 来自 failed/ 的补偿重传：清掉可能残留的空目录
                 removeEmptyDirsUp(path.dirname(uploadPackage.archive.filePath), path.join(directories.uploadStagingDir, "failed"));
                 log.info("[Metrics] 上传完成", {
@@ -81,9 +89,16 @@ export function createUploadManager(options) {
         for (const pkg of rescued)
             queue.enqueue(pkg);
     }
+    // 孤儿快照补传：宿主死亡导致终态触发从未发生时，按快照年龄补打 session-end 包
+    if (config.orphanRescue?.enabled !== false) {
+        const idleMs = (config.orphanRescue?.idleHours ?? 24) * 3_600_000;
+        const maxAgeMs = (config.orphanRescue?.maxAgeDays ?? 7) * 86_400_000;
+        void rescueOrphanSnapshots(idleMs, maxAgeMs);
+    }
     const sessions = new Map();
     const childToParent = new Map();
     const completedBashCalls = new Set();
+    const toolTriggeredCalls = new Set();
     function resolveSessionId(rawId) {
         return childToParent.get(rawId) ?? rawId;
     }
@@ -98,11 +113,13 @@ export function createUploadManager(options) {
     /**
      * 触发一次上传：根推断 + 包名推断 + 打包入队。
      *
-     * @param sessionId    会话 id
-     * @param triggerLabel 场景命名标签
+     * @param sessionId        会话 id
+     * @param triggerLabel     场景命名标签
+     * @param evidenceOverride 证据覆盖（孤儿补传时由快照构造，代替内存证据）
      */
-    async function triggerUpload(sessionId, triggerLabel) {
-        const evidence = sessions.get(sessionId) ??
+    async function triggerUpload(sessionId, triggerLabel, evidenceOverride) {
+        const evidence = evidenceOverride ??
+            sessions.get(sessionId) ??
             { collector: new EvidenceCollector(), agentName: "", workingDirectory: "", startedAt: Date.now() };
         const seeds = evidence.collector.seeds();
         const { directRoots, extraMarkers } = collectArtifactRules(seeds, evidence.workingDirectory, config.appendArtifacts ?? []);
@@ -116,7 +133,7 @@ export function createUploadManager(options) {
         const projectName = resolveAndroidProjectName(seeds, {
             fallbackDirectory: evidence.workingDirectory || roots[0] || "",
         }) ?? "project";
-        options.onBeforeArchive?.();
+        options.onBeforeArchive?.(sessionId);
         const archiveResult = await archiveSessionPackage({
             sessionId,
             trigger: triggerLabel,
@@ -151,8 +168,12 @@ export function createUploadManager(options) {
             const evidence = getOrCreateEvidence(resolveSessionId(id));
             if (event.type === "session.created") {
                 const directory = info.directory;
-                if (directory)
+                if (directory) {
                     evidence.workingDirectory = directory;
+                    // 工作目录作为证据种子：即使全程无 write/bash 证据（如纯 task 转换会话），
+                    // 触发上传时也能扫描工作区完成根推断与包名推断
+                    evidence.collector.recordBash(directory, "");
+                }
             }
             else {
                 const agent = info.agent;
@@ -171,18 +192,19 @@ export function createUploadManager(options) {
             if (!part || part.type !== "tool")
                 return;
             const toolState = part.state;
-            if (toolState?.status !== "completed")
+            const status = toolState?.status;
+            if (status !== "completed" && status !== "error")
                 return;
             const tool = part.tool;
-            const input = toolState.input;
+            const input = toolState?.input;
             const callID = part.callID;
-            if (tool === "write" || tool === "edit") {
+            if (status === "completed" && (tool === "write" || tool === "edit")) {
                 const filePath = input?.filePath || input?.path;
                 if (filePath)
                     evidence.collector.recordFileEdit(filePath);
                 return;
             }
-            if (tool === "bash") {
+            if (status === "completed" && tool === "bash") {
                 const command = input?.command || "";
                 const workdir = input?.workdir;
                 evidence.collector.recordBash(workdir, command);
@@ -198,6 +220,18 @@ export function createUploadManager(options) {
                         void triggerUpload(sessionId, scenario.label);
                     }
                 }
+                return;
+            }
+            // 工具名场景命中：根会话直接调用的工具进入终态（completed/error）即触发
+            // （task 委派返回即业务终态，失败也存终态；子代理内部的嵌套调用不触发）
+            const matched = matchToolScenarios(scenarios, tool ?? "", status ?? "", !childToParent.has(rawSessionId));
+            if (matched.length > 0 && (!callID || !toolTriggeredCalls.has(callID))) {
+                if (callID)
+                    toolTriggeredCalls.add(callID);
+                for (const scenario of matched) {
+                    log.info("[Metrics] 工具终态触发", { sessionId, tool, status, scenario: scenario.label });
+                    void triggerUpload(sessionId, scenario.label);
+                }
             }
             return;
         }
@@ -219,6 +253,40 @@ export function createUploadManager(options) {
         }
         await queue.drain(10_000);
     }
+    /** 终态场景标签：事件含 session.deleted 的启用场景，缺省回退 session-end */
+    function terminalScenarioLabel() {
+        return scenarios.find((s) => s.enabled && s.events.includes("session.deleted"))?.label ?? "session-end";
+    }
+    /**
+     * 扫描 metrics 目录孤儿快照并补打 session-end 包：mtime 静默 [idleMs, maxAgeMs]、
+     * 无已传标记（metrics/.sent/<sessionId>）且不属于本进程活跃会话的快照视为孤儿。
+     * 快照原件永久保留为本地记录，已传标记才是防重复补传的依据。
+     *
+     * @param idleMs   静默下限（毫秒）
+     * @param maxAgeMs 年龄上限（毫秒）
+     */
+    async function rescueOrphanSnapshots(idleMs, maxAgeMs) {
+        const triggerLabel = terminalScenarioLabel();
+        const orphans = await selectOrphanSnapshots(directories.metricsDir, idleMs, maxAgeMs, (sessionId) => sessions.has(sessionId));
+        for (const orphan of orphans) {
+            try {
+                // 工作目录作为证据种子：推断产物根与项目名（内存证据已随进程丢失）
+                const collector = new EvidenceCollector();
+                if (orphan.workingDirectory)
+                    collector.recordBash(orphan.workingDirectory, "");
+                await triggerUpload(orphan.sessionId, triggerLabel, {
+                    collector,
+                    agentName: orphan.agentName,
+                    workingDirectory: orphan.workingDirectory,
+                    startedAt: orphan.startedAt,
+                });
+                log.info("[Metrics] 孤儿快照补传", { sessionId: orphan.sessionId, trigger: triggerLabel });
+            }
+            catch (err) {
+                log.warn("[Metrics] 孤儿快照补传失败", { sessionId: orphan.sessionId, error: String(err) });
+            }
+        }
+    }
     return { observe, dispose };
 }
 /** 应用 appendArtifacts 规则：marker 进探测扩展，显式路径按 matchBy 命中后作为直接根 */
@@ -467,3 +535,78 @@ function removeQuietly(filePath) {
         // 删除失败只记日志层面忽略
     }
 }
+// ─── 孤儿快照补传（§13 失败补偿链路） ─────────────────────────────────────────
+/** 已传终态标记目录名（metrics/.sent/<sessionId>） */
+const SENT_MARKER_DIR = ".sent";
+/**
+ * 记录会话终态包已成功上云。
+ * 快照原件（metrics/<sessionId>.json）会永久保留为本地记录，
+ * "已传标记"才是孤儿扫描防重复上传的依据。
+ */
+export function markSessionUploaded(metricsDir, sessionId) {
+    try {
+        fs.mkdirSync(path.join(metricsDir, SENT_MARKER_DIR), { recursive: true });
+        fs.writeFileSync(path.join(metricsDir, SENT_MARKER_DIR, sessionId), String(Date.now()));
+    }
+    catch {
+        // 标记失败仅导致下次启动多一次补传判断，不阻塞上传链路
+    }
+}
+/** 会话终态包是否已成功上云 */
+export function isSessionUploaded(metricsDir, sessionId) {
+    return fs.existsSync(path.join(metricsDir, SENT_MARKER_DIR, sessionId));
+}
+/**
+ * 扫描目录选出孤儿快照候选：mtime 静默 [idleMs, maxAgeMs] 且不在活跃集的快照。
+ * 上传成功后快照即被删除，"文件仍在"天然等价于"终态未传出"。
+ *
+ * @param metricsDir 快照目录
+ * @param idleMs     静默下限（毫秒）
+ * @param maxAgeMs   年龄上限（毫秒）
+ * @param isActive   活跃会话判定（IO 前后各查一次，防竞态）
+ * @returns           候选列表（无法解析的快照跳过）
+ */
+export async function selectOrphanSnapshots(metricsDir, idleMs, maxAgeMs, isActive) {
+    const result = [];
+    let entries;
+    try {
+        entries = await fs.promises.readdir(metricsDir);
+    }
+    catch {
+        return result;
+    }
+    const now = Date.now();
+    for (const entry of entries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const sessionId = entry.slice(0, -".json".length);
+        if (isSessionUploaded(metricsDir, sessionId))
+            continue;
+        const filePath = path.join(metricsDir, entry);
+        try {
+            const stats = await fs.promises.stat(filePath);
+            const age = now - stats.mtimeMs;
+            if (age < idleMs || age > maxAgeMs)
+                continue;
+            if (isActive(sessionId))
+                continue;
+            const snapshot = JSON.parse(await fs.promises.readFile(filePath, "utf-8"));
+            if (isActive(sessionId))
+                continue;
+            const header = (snapshot.header ?? {});
+            result.push({
+                sessionId,
+                filePath,
+                workingDirectory: header.workingDirectory || "",
+                agentName: header.agent || "",
+                startedAt: (typeof snapshot.startTime === "number" && snapshot.startTime > 0 && snapshot.startTime) ||
+                    Date.parse(header.startTime || "") ||
+                    stats.mtimeMs,
+            });
+        }
+        catch {
+            // 无法解析的快照跳过，不阻塞其余候选
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-metrics-plugin",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "opencode plugin: auto-records every session's metrics (tokens/rounds/steps/sub-agents/hvigor builds) to snapshot JSON. Zero DB, zero config. Pair with session-viewer for visualization.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc",
     "typecheck": "tsc --noEmit",
     "test": "tsx example/smoke.mts",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "node -e \"if(require('fs').readFileSync('package.json','utf8').charCodeAt(0)===0xFEFF){console.error('package.json 含 BOM，禁止发布');process.exit(1)}\" && npm run build && npm test"
   },
   "engines": {
     "node": ">=18"