dsh-adb 1.4.0 → 1.6.0

package/README.md

@@ -42,6 +42,8 @@ Topics: `dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_device_report` | One-click health report: device identity + top-RSS processes + crash buffer (real crashes w/ stacks vs. boot markers) + W/E/F logcat aggregated by tag + storage + health verdict; each section degrades independently; persisted under `reportDir` |
 | `adb_wait_for` | Wait until a device condition holds — device-online / boot-complete / process appeared / logcat keyword — polling up to a budget, instead of sleeping a fixed number of seconds; returns `matched:false` on timeout |
 | `adb_operation_ledger` | Append-only device operation ledger (record/list/rollback): record installs/pushes/etc., list history, or roll an app back to its last known-good APK (`adb install -r`); persisted as `operations.json` — the trust base for agent-driven device modification |
+| `adb_screenshot` | Capture the device screen into a local PNG (screencap → pull), returning the saved path, byte size, and pixel dimensions — durable evidence for crash scenes / UI states / test frames |
+| `adb_watch_crash` | Watch the crash buffer for NEW real crashes (foreground poll or background job; boot markers ignored; `matched:false` on timeout) — the first link of the monitor→capture→attribute chain |
 
 Errors are structured `AdbError` with stable codes: `ADB_NOT_FOUND`, `ADB_UNAVAILABLE`, `DEVICE_NOT_FOUND`, `NO_DEVICES`, `CONNECT_FAILED`, `INSTALL_FAILED`, `ADB_EXIT_<code>`, etc.
 
@@ -65,6 +67,7 @@ Set the `config` block in `cordis.patch.yml` (or a profile patch):
 | `timeoutMs` | Per-command timeout | 30000 |
 | `baselineDir` | Directory for `adb_perf_baseline` storage | `~/.dsh/storages/dsh-adb` |
 | `reportDir` | Directory for `adb_device_report` storage | `<baselineDir>/reports` |
+| `screenshotDir` | Directory for `adb_screenshot` storage | `<baselineDir>/screenshots` |
 
 ## Development
 

package/README.zh-CN.md

@@ -42,6 +42,8 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_device_report` | 一键体检：设备信息 + Top RSS 进程 + 崩溃缓冲（真实崩溃带堆栈/启动标记分类）+ W/E/F 日志按 tag 聚合 + 存储用量 + 健康结论；每节独立降级；落盘到 `reportDir` |
 | `adb_wait_for` | 等待原语：等设备上线 / 启动完成 / 进程出现 / logcat 出现关键字，轮询到预算上限，替代盲目 sleep；超时返回 `matched:false` |
 | `adb_operation_ledger` | 操作回滚台账（record/list/rollback）：追加记录安装/推送等操作，查询历史，或回滚到最近一次成功安装的 APK（`adb install -r`）；落盘 `operations.json` —— agent 自主改设备的信任基础 |
+| `adb_screenshot` | 截图落盘 PNG（screencap → pull），返回路径/字节数/像素尺寸 —— 崩溃现场、UI 状态、测试前后对比的持久证据 |
+| `adb_watch_crash` | 崩溃看门狗：监控 crash buffer 的**新**真实崩溃（前台轮询或后台 job；启动标记不算；超时返回 `matched:false`）—— 「盯崩溃→采集→归因」链第一环 |
 
 错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
 
@@ -65,6 +67,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `timeoutMs` | 命令超时 | 30000 |
 | `baselineDir` | `adb_perf_baseline` 基线存储目录 | `~/.dsh/storages/dsh-adb` |
 | `reportDir` | `adb_device_report` 体检报告存储目录 | `<baselineDir>/reports` |
+| `screenshotDir` | `adb_screenshot` 截图存储目录 | `<baselineDir>/screenshots` |
 
 ## 开发
 

package/lib/index.d.ts

@@ -15,6 +15,8 @@ export interface Config {
     baselineDir?: string;
     /** Directory for adb_device_report storage; defaults to <baselineDir>/reports. */
     reportDir?: string;
+    /** Directory for adb_screenshot storage; defaults to <baselineDir>/screenshots. */
+    screenshotDir?: string;
 }
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,6 +10,8 @@ import { registerPerfTool } from './tools/perf.js';
 import { registerPerfBaselineTool } from './tools/perf-baseline.js';
 import { registerWaitTool } from './tools/wait.js';
 import { registerOperationLedgerTool } from './tools/operation-ledger.js';
+import { registerScreenshotTool } from './tools/screenshot.js';
+import { registerWatchCrashTool } from './tools/watch-crash.js';
 import { registerRpc } from './rpc.js';
 import { registerSkills } from './skill.js';
 export const name = 'dsh-adb';
@@ -21,24 +23,29 @@ export const Config = Schema.object({
     timeoutMs: Schema.number().default(30000).description('adb 命令超时（毫秒）'),
     baselineDir: Schema.string().description('adb_perf_baseline 基线存储目录；缺省 ~/.dsh/storages/dsh-adb'),
     reportDir: Schema.string().description('adb_device_report 报告存储目录；缺省 ~/.dsh/storages/dsh-adb/reports'),
+    screenshotDir: Schema.string().description('adb_screenshot 截图存储目录；缺省 ~/.dsh/storages/dsh-adb/screenshots'),
 });
 export function apply(ctx, config) {
     const cfg = config;
-    const reportDir = config.reportDir ?? `${(config.baselineDir ?? DEFAULT_BASELINE_DIR).replace(/\\/g, '/')}/reports`;
+    const baselineDir = config.baselineDir ?? DEFAULT_BASELINE_DIR;
+    const reportDir = config.reportDir ?? `${baselineDir.replace(/\\/g, '/')}/reports`;
+    const screenshotDir = config.screenshotDir ?? `${baselineDir.replace(/\\/g, '/')}/screenshots`;
     registerDeviceTools(ctx, cfg);
     registerInstallTool(ctx, cfg);
     registerFileTool(ctx, cfg);
     registerLogcatTool(ctx, cfg);
     registerPerfTool(ctx, cfg);
-    registerPerfBaselineTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
+    registerPerfBaselineTool(ctx, cfg, baselineDir);
     registerCrashReportTool(ctx, cfg);
     registerDeviceReportTool(ctx, cfg, reportDir);
     registerWaitTool(ctx, cfg);
-    registerOperationLedgerTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
+    registerOperationLedgerTool(ctx, cfg, baselineDir);
+    registerScreenshotTool(ctx, cfg, screenshotDir);
+    registerWatchCrashTool(ctx, cfg);
     registerSkills(ctx);
     // The RPC channel needs the client connection, which mounts after this
     // plugin starts in web compositions; register lazily so headless profiles
     // (no connection) stay unaffected.
     ctx.inject(['connection'], (readyCtx) => registerRpc(readyCtx, cfg, reportDir));
-    ctx.logger.info('[dsh-adb] loaded: 12 tools + web device panel rpc');
+    ctx.logger.info('[dsh-adb] loaded: 14 tools + web device panel rpc');
 }

package/lib/tools/screenshot.d.ts

@@ -0,0 +1,37 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+interface ScreenshotArgs {
+    serial?: string;
+    /** Local directory to save the PNG into; defaults to the plugin screenshotDir. */
+    dir?: string;
+    /** Basename for the PNG; defaults to <serial>-<epoch>.png. */
+    name?: string;
+}
+export interface ScreenshotResult {
+    savedTo: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    serial: string;
+}
+/** Stable local-path convention for screenshot saves: <dir>/<serial>-<epoch>.png. */
+export declare function screenshotPathFor(dir: string, serial: string): string;
+/**
+ * Capture the device screen into a local PNG: screencap on the device, pull to
+ * the local dir, then best-effort rm of the on-device temp. Returns the saved
+ * path, byte size, and (when the PNG header parses) pixel dimensions.
+ */
+export declare function captureScreenshot(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: ScreenshotArgs, screenshotDir: string): Promise<ScreenshotResult>;
+/** Parse PNG dimensions from the IHDR chunk (pure; unit-tested). */
+export declare function pngDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * adb_screenshot: capture the device screen (screencap → pull) into a local
+ * PNG under the screenshot dir, and return its path + byte size. Screenshots
+ * are durable evidence: crash scenes, UI states, before/after test frames —
+ * the primitive behind the vision-based features (ROADMAP ③).
+ */
+export declare function registerScreenshotTool(ctx: Context, cfg: AdbConfig, screenshotDir: string): void;
+export {};

package/lib/tools/screenshot.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+/** Stable local-path convention for screenshot saves: <dir>/<serial>-<epoch>.png. */
+export function screenshotPathFor(dir, serial) {
+    return join(dir, `${serial.replace(/[^A-Za-z0-9._-]/g, '_')}-${Date.now()}.png`);
+}
+/**
+ * Capture the device screen into a local PNG: screencap on the device, pull to
+ * the local dir, then best-effort rm of the on-device temp. Returns the saved
+ * path, byte size, and (when the PNG header parses) pixel dimensions.
+ */
+export async function captureScreenshot(ctx, cfg, signal, args, screenshotDir) {
+    const serial = args.serial ?? cfg.defaultSerial;
+    const devicePath = `/data/local/tmp/dsh-shot-${Date.now()}.png`;
+    const dir = args.dir ?? screenshotDir;
+    mkdirSync(dir, { recursive: true });
+    const localPath = args.name !== undefined
+        ? join(dir, args.name.endsWith('.png') ? args.name : `${args.name}.png`)
+        : screenshotPathFor(dir, serial ?? 'device');
+    try {
+        const cap = await runAdb(ctx, cfg, ['shell', 'screencap', '-p', devicePath], { signal, serial });
+        if (cap.exitCode !== 0)
+            throw classifyFailure(cap);
+        const pull = await runAdb(ctx, cfg, ['pull', devicePath, localPath], { signal, serial });
+        if (pull.exitCode !== 0)
+            throw classifyFailure(pull);
+    }
+    finally {
+        // Best-effort cleanup of the on-device temp file.
+        try {
+            await runAdb(ctx, cfg, ['shell', 'rm', '-f', devicePath], { signal, serial });
+        }
+        catch { /* cleanup is best-effort */ }
+    }
+    if (!existsSync(localPath)) {
+        throw new AdbError('SCREENSHOT_FAILED', `screencap succeeded but no file at ${localPath}`);
+    }
+    const bytes = readFileSync(localPath);
+    const dimensions = pngDimensions(bytes);
+    return {
+        savedTo: localPath,
+        bytes: bytes.length,
+        ...(dimensions !== undefined ? { width: dimensions.width, height: dimensions.height } : {}),
+        serial: serial ?? 'default',
+    };
+}
+/** Parse PNG dimensions from the IHDR chunk (pure; unit-tested). */
+export function pngDimensions(bytes) {
+    // PNG signature (8 bytes) + IHDR length (4) + "IHDR" (4) + width (4) + height (4).
+    if (bytes.length < 24)
+        return undefined;
+    const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+    for (let i = 0; i < 8; i++) {
+        if (bytes[i] !== sig[i])
+            return undefined;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return {
+        width: view.getUint32(16),
+        height: view.getUint32(20),
+    };
+}
+/**
+ * adb_screenshot: capture the device screen (screencap → pull) into a local
+ * PNG under the screenshot dir, and return its path + byte size. Screenshots
+ * are durable evidence: crash scenes, UI states, before/after test frames —
+ * the primitive behind the vision-based features (ROADMAP ③).
+ */
+export function registerScreenshotTool(ctx, cfg, screenshotDir) {
+    ctx.tools.register({
+        name: 'adb_screenshot',
+        description: 'Capture the device screen into a local PNG (screencap on device → pull to host) and return the saved path, byte size, and pixel dimensions. Screenshots are durable evidence for crash scenes, UI states, or before/after test frames. Saves under the screenshotDir (default ~/.dsh/storages/dsh-adb/screenshots).',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                dir: { type: 'string', description: 'Local directory to save into; defaults to the plugin screenshotDir.' },
+                name: { type: 'string', description: 'Basename for the PNG; defaults to <serial>-<epoch>.png.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            return captureScreenshot(ctx, cfg, exec.signal, args, screenshotDir);
+        },
+    });
+}

package/lib/tools/watch-crash.d.ts

@@ -0,0 +1,46 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+import { parseLogcat } from '../parsers/logcat.js';
+import { type CrashChain } from '../report.js';
+/**
+ * adb_watch_crash: watch the crash buffer for NEW real crashes. Foreground:
+ * poll until a new real crash appears or the budget expires (returns
+ * matched:false on timeout, not an error). Background: run as a job that keeps
+ * polling; job_output returns a text summary of each newly detected crash.
+ *
+ * Reuses the crash classification from the health report (real crash vs. boot
+ * markers), so "a new crash" means a real one — not another mtk-brm line.
+ */
+export interface WatchCrashArgs {
+    serial?: string;
+    /** Overall watch budget in milliseconds; defaults to 60000, capped at 600000. */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds; defaults to 1000. */
+    intervalMs?: number;
+    /** Include the following same-pid lines (stack) per crash in the result. */
+    withStacks?: boolean;
+    run_in_background?: boolean;
+}
+export interface CrashDetection {
+    matched: boolean;
+    waitedMs: number;
+    crashes: Array<{
+        time: string;
+        pid: string;
+        tag: string;
+        message: string;
+        stack: string[];
+    }>;
+}
+/** A stable identity for one crash occurrence: time+pid+tag+message. */
+export declare function crashSignature(chain: CrashChain): string;
+/** Map crash chains to the public detection shape. */
+export declare function chainToDetection(chain: CrashChain, withStacks: boolean): CrashDetection['crashes'][number];
+/** One poll: return chains not seen in `seen`, and update `seen`. */
+export declare function detectNewCrashes(entries: ReturnType<typeof parseLogcat>, seen: Set<string>, withStacks: boolean): CrashDetection['crashes'];
+/** Poll the crash buffer until a new real crash appears or the budget expires. */
+export declare function watchForCrash(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: WatchCrashArgs): Promise<CrashDetection>;
+/** Format detected crashes as a job_output-friendly text block. */
+export declare function formatCrashDetections(detection: CrashDetection): string;
+/** adb_watch_crash: watch the crash buffer for NEW real crashes (foreground poll or background job). */
+export declare function registerWatchCrashTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/watch-crash.js

@@ -0,0 +1,199 @@
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+import { parseLogcat } from '../parsers/logcat.js';
+import { classifyCrashBuffer } from '../report.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_TIMEOUT_MS = 600_000;
+const DEFAULT_INTERVAL_MS = 1_000;
+/** A stable identity for one crash occurrence: time+pid+tag+message. */
+export function crashSignature(chain) {
+    const sig = chain.signature;
+    return `${sig.time}|${sig.pid}|${sig.tag}|${sig.message}`;
+}
+/** Map crash chains to the public detection shape. */
+export function chainToDetection(chain, withStacks) {
+    return {
+        time: chain.signature.time,
+        pid: chain.signature.pid,
+        tag: chain.signature.tag,
+        message: chain.signature.message,
+        stack: withStacks ? chain.following.map((entry) => `${entry.tag}: ${entry.message}`) : [],
+    };
+}
+/** One poll: return chains not seen in `seen`, and update `seen`. */
+export function detectNewCrashes(entries, seen, withStacks) {
+    const summary = classifyCrashBuffer(entries);
+    const fresh = [];
+    for (const chain of summary.chains) {
+        const key = crashSignature(chain);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        fresh.push(chainToDetection(chain, withStacks));
+    }
+    return fresh;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('tool call aborted'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new Error('tool call aborted'));
+        }, { once: true });
+    });
+}
+/** Poll the crash buffer until a new real crash appears or the budget expires. */
+export async function watchForCrash(ctx, cfg, signal, args) {
+    const timeoutMs = Math.min(Math.floor(args.timeoutMs ?? DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+    const intervalMs = Math.max(Math.floor(args.intervalMs ?? DEFAULT_INTERVAL_MS), 250);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    const seen = new Set();
+    const withStacks = args.withStacks ?? true;
+    let lastError;
+    // Seed: remember every crash already in the buffer, so only NEW ones match.
+    try {
+        const seed = await runAdb(ctx, cfg, ['logcat', '-b', 'crash', '-v', 'threadtime', '-d'], { signal, serial: args.serial, maxBytes: 8 * 1024 * 1024 });
+        if (seed.exitCode !== 0)
+            throw classifyFailure(seed);
+        for (const chain of classifyCrashBuffer(parseLogcat(seed.stdout)).chains) {
+            seen.add(crashSignature(chain));
+        }
+    }
+    catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+    }
+    while (true) {
+        try {
+            const result = await runAdb(ctx, cfg, ['logcat', '-b', 'crash', '-v', 'threadtime', '-d'], { signal, serial: args.serial, maxBytes: 8 * 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            const fresh = detectNewCrashes(parseLogcat(result.stdout), seen, withStacks);
+            if (fresh.length > 0) {
+                return { matched: true, waitedMs: Date.now() - start, crashes: fresh };
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        if (Date.now() >= deadline) {
+            return {
+                matched: false,
+                waitedMs: timeoutMs,
+                crashes: [],
+                ...(lastError !== undefined ? { reason: lastError } : { reason: `no new crash within ${timeoutMs}ms` }),
+            };
+        }
+        await sleep(Math.min(intervalMs, deadline - Date.now()), signal);
+    }
+}
+/** Format detected crashes as a job_output-friendly text block. */
+export function formatCrashDetections(detection) {
+    const lines = [`[adb_watch_crash] ${detection.matched ? `detected ${detection.crashes.length} new crash(es) after ${detection.waitedMs}ms` : `no new crash within ${detection.waitedMs}ms`}`];
+    for (const crash of detection.crashes) {
+        lines.push(`- ${crash.time} pid=${crash.pid} ${crash.tag}: ${crash.message}`);
+        for (const line of crash.stack)
+            lines.push(`    ${line}`);
+    }
+    return lines.join('\n');
+}
+/** adb_watch_crash: watch the crash buffer for NEW real crashes (foreground poll or background job). */
+export function registerWatchCrashTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_watch_crash',
+        description: 'Watch the crash buffer for NEW real crashes. Foreground: poll until a new real crash (FATAL EXCEPTION / Fatal signal / SIG*) appears or the budget expires — returns matched:false on timeout (not an error), so you can react. Background (run_in_background): keeps polling as a job; job_output returns a text summary of each newly detected crash. Boot markers (mtk-brm) are not crashes. Pair with adb_crash_report / adb_screenshot to capture the scene when a crash is detected.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                timeoutMs: { type: 'integer', description: 'Overall watch budget in ms; defaults to 60000, capped at 600000.' },
+                intervalMs: { type: 'integer', description: 'Poll interval in ms; defaults to 1000, minimum 250.' },
+                withStacks: { type: 'boolean', description: 'Include the following same-pid lines (stack) per crash; defaults to true.' },
+                run_in_background: { type: 'boolean', description: 'Run as a background job and return a job id immediately.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            if (args.run_in_background === true) {
+                return startBackgroundWatch(ctx, cfg, args, exec);
+            }
+            return watchForCrash(ctx, cfg, exec.signal, args);
+        },
+    });
+}
+function startBackgroundWatch(ctx, cfg, args, exec) {
+    const jobs = ctx.get('jobs');
+    if (jobs === undefined) {
+        throw new AdbError('JOBS_UNAVAILABLE', 'background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs');
+    }
+    if (exec.signal.aborted) {
+        const error = new Error('tool call aborted');
+        error.name = 'AbortError';
+        throw error;
+    }
+    // The background loop must outlive the tool call: no exec.signal in the loop.
+    const controller = new AbortController();
+    let latestDetection;
+    let done = false;
+    const id = jobs.start({
+        kind: 'adb-watch-crash',
+        label: `watch-crash${args.serial !== undefined ? ` ${args.serial}` : ''}`,
+        ...(exec.agent !== undefined ? { owner: exec.agent } : {}),
+        run: () => {
+            const loop = (async () => {
+                const start = Date.now();
+                const timeoutMs = Math.min(Math.floor(args.timeoutMs ?? DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+                const intervalMs = Math.max(Math.floor(args.intervalMs ?? DEFAULT_INTERVAL_MS), 250);
+                const seen = new Set();
+                const withStacks = args.withStacks ?? true;
+                const deadline = start + timeoutMs;
+                let lastError;
+                try {
+                    const seed = await runAdb(ctx, cfg, ['logcat', '-b', 'crash', '-v', 'threadtime', '-d'], { signal: controller.signal, serial: args.serial, maxBytes: 8 * 1024 * 1024 });
+                    if (seed.exitCode !== 0)
+                        throw classifyFailure(seed);
+                    for (const chain of classifyCrashBuffer(parseLogcat(seed.stdout)).chains) {
+                        seen.add(crashSignature(chain));
+                    }
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error.message : String(error);
+                }
+                while (!done && Date.now() < deadline) {
+                    try {
+                        const result = await runAdb(ctx, cfg, ['logcat', '-b', 'crash', '-v', 'threadtime', '-d'], { signal: controller.signal, serial: args.serial, maxBytes: 8 * 1024 * 1024 });
+                        if (result.exitCode !== 0)
+                            throw classifyFailure(result);
+                        const fresh = detectNewCrashes(parseLogcat(result.stdout), seen, withStacks);
+                        if (fresh.length > 0) {
+                            latestDetection = { matched: true, waitedMs: Date.now() - start, crashes: fresh };
+                        }
+                    }
+                    catch (error) {
+                        lastError = error instanceof Error ? error.message : String(error);
+                    }
+                    await sleep(Math.min(intervalMs, deadline - Date.now()), controller.signal).catch(() => { });
+                }
+                done = true;
+                if (latestDetection === undefined) {
+                    latestDetection = {
+                        matched: false,
+                        waitedMs: timeoutMs,
+                        crashes: [],
+                        ...(lastError !== undefined ? { reason: lastError } : { reason: `no new crash within ${timeoutMs}ms` }),
+                    };
+                }
+            })();
+            return {
+                cancel: () => { done = true; },
+                done: loop.then(() => ({ exitCode: 0, signal: null })),
+                readOutput: () => latestDetection === undefined ? '' : formatCrashDetections(latestDetection),
+            };
+        },
+    });
+    return { kind: 'background', jobId: id };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-adb",
-  "version": "1.4.0",
-  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, condition waits, operation ledger w/ rollback, web device panel (autocomplete, live logcat, profiler)",
+  "version": "1.6.0",
+  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, condition waits, operation ledger w/ rollback, screenshots, crash watchdog, web device panel (autocomplete, live logcat, profiler)",
   "type": "module",
   "main": "lib/index.js",
   "exports": {