dsh-hooks 0.12.0 → 0.13.0

package/lib/index.d.ts

@@ -59,7 +59,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed\u3001usage/daily \u5171 18 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219/\u6570\u503C\u6BD4\u8F83\u8FC7\u6EE4\uFF08\u5982 '>10000'\uFF09\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u6267\u884C\u9009\u9879\uFF08enabled \u505C\u7528 / cwd \u5DE5\u4F5C\u76EE\u5F55 / maxConcurrent + debounceMs \u9632\u9AD8\u9891\u98CE\u66B4\uFF09\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF1B`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed\u3001usage/daily \u5171 18 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219/\u6570\u503C\u6BD4\u8F83\u8FC7\u6EE4\uFF08\u5982 '>10000'\uFF09\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u6267\u884C\u9009\u9879\uFF08enabled \u505C\u7528 / cwd \u5DE5\u4F5C\u76EE\u5F55 / maxConcurrent + debounceMs \u9632\u9AD8\u9891\u98CE\u66B4\uFF09\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF0C`dsh-hooks tail` \u53EF\u5B9E\u65F6\u8DDF\u8E2A\u3001`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\uFF08\u542B runningSubagents/usage \u7B49\u6570\u503C\u5B57\u6BB5\uFF09\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 export declare function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;

package/lib/index.js

@@ -74,7 +74,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed、usage/daily 共 18 类事件），支持 when 原因过滤、match 字段正则/数值比较过滤（如 \'>10000\'）、stdin JSON 输入、opt-in 重试、执行选项（enabled 停用 / cwd 工作目录 / maxConcurrent + debounceMs 防高频风暴）、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl；`dsh-hooks dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
+export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed、usage/daily 共 18 类事件），支持 when 原因过滤、match 字段正则/数值比较过滤（如 \'>10000\'）、stdin JSON 输入、opt-in 重试、执行选项（enabled 停用 / cwd 工作目录 / maxConcurrent + debounceMs 防高频风暴）、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl，`dsh-hooks tail` 可实时跟踪、`dsh-hooks dry-run <event>` 可模拟事件（含 runningSubagents/usage 等数值字段）验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
 export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
@@ -171,7 +171,12 @@ export function apply(ctx, config = {}) {
             }
         };
         if (hook.notify) {
-            void fireNotify(hook.notify, ctxValue, track);
+            // Retries ride the same per-hook options as `run` (webhook channel only;
+            // the desktop channel is a local spawn and never retries).
+            void fireNotify(hook.notify, ctxValue, track, {
+                retries: hook.retries,
+                retryDelayMs: hook.retryDelayMs,
+            });
             return;
         }
         if (hook.run) {

package/lib/notify.d.ts

@@ -6,23 +6,49 @@ export interface NotifyResult {
     error?: string;
 }
 export type NotifyRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
+/**
+ * Retry policy for the built-in notify channels — the same two knobs the
+ * `run` channel takes, resolved from the hook declaration by the caller.
+ */
+export interface NotifyRetryOptions {
+    /** Retries after the first attempt. Defaults to 0 (one attempt, never retried). */
+    retries?: number;
+    /** Base delay between retries in milliseconds; doubles per attempt. Defaults to 500. */
+    retryDelayMs?: number;
+    /** Retry progress lines (defaults to `console.warn`). */
+    log?: (line: string) => void;
+}
 /** Fetch timeout for webhook sends (ms). */
 export declare const NOTIFY_TIMEOUT_MS = 10000;
+/**
+ * HTTP statuses worth retrying: rate limiting, request timeout, and
+ * server-side failures (a cold endpoint answering 502/503 is the classic
+ * case). Any other 4xx means the request itself is wrong — retrying it can
+ * only waste time.
+ */
+export declare function isRetryableStatus(status: number): boolean;
 /** One-line summary for Slack-style and desktop notifications. */
 export declare function summarizeContext(ctx: HookContext): string;
 /** Structured JSON document for the webhook channel (present fields only). */
 export declare function webhookPayload(ctx: HookContext): Record<string, unknown>;
 /**
- * POST the context to a webhook endpoint. One retry on transport failure
- * (webhook endpoints often drop the first request when cold). The URL comes
- * from `spec.url` or the `DSH_HOOKS_WEBHOOK_URL` environment variable.
+ * POST the context to a webhook endpoint, honouring the hook's
+ * `retries` / `retryDelayMs` exactly like the `run` channel: up to
+ * `retries` extra attempts after the first one, with the delay doubling per
+ * attempt. Retryable failures are transport errors (connection reset,
+ * timeout) and HTTP 408/429/5xx. The URL comes from `spec.url` or the
+ * `DSH_HOOKS_WEBHOOK_URL` environment variable.
  */
-export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: NodeJS.ProcessEnv): Promise<NotifyResult>;
+export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: NodeJS.ProcessEnv, retry?: NotifyRetryOptions): Promise<NotifyResult>;
 /**
  * Desktop balloon/toast notification. The summary travels through an
  * environment variable (Windows PowerShell) or argv (macOS/Linux), never
  * through shell-string interpolation.
  */
 export declare function sendDesktop(spec: NotifySpec, ctx: HookContext): Promise<NotifyResult>;
-/** Fire a built-in notification; failures only warn and surface in the result. */
-export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord): Promise<NotifyResult>;
+/**
+ * Fire a built-in notification; failures only warn and surface in the result.
+ * `retry` carries the hook's `retries` / `retryDelayMs` — honoured by the
+ * webhook channel; the desktop channel is a local spawn and never retries.
+ */
+export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord, retry?: NotifyRetryOptions): Promise<NotifyResult>;

package/lib/notify.js

@@ -6,8 +6,25 @@
  */
 import { spawn } from 'node:child_process';
 import { eventLabel } from './context.js';
+import { DEFAULT_RETRY_DELAY_MS } from './runner.js';
 /** Fetch timeout for webhook sends (ms). */
 export const NOTIFY_TIMEOUT_MS = 10000;
+/**
+ * HTTP statuses worth retrying: rate limiting, request timeout, and
+ * server-side failures (a cold endpoint answering 502/503 is the classic
+ * case). Any other 4xx means the request itself is wrong — retrying it can
+ * only waste time.
+ */
+export function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/** Sleep without holding the event loop open (retries never outlive the plugin). */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
 /** One-line summary for Slack-style and desktop notifications. */
 export function summarizeContext(ctx) {
     const label = ctx.sessionName || ctx.sessionId || '';
@@ -93,15 +110,21 @@ export function webhookPayload(ctx) {
     return payload;
 }
 /**
- * POST the context to a webhook endpoint. One retry on transport failure
- * (webhook endpoints often drop the first request when cold). The URL comes
- * from `spec.url` or the `DSH_HOOKS_WEBHOOK_URL` environment variable.
+ * POST the context to a webhook endpoint, honouring the hook's
+ * `retries` / `retryDelayMs` exactly like the `run` channel: up to
+ * `retries` extra attempts after the first one, with the delay doubling per
+ * attempt. Retryable failures are transport errors (connection reset,
+ * timeout) and HTTP 408/429/5xx. The URL comes from `spec.url` or the
+ * `DSH_HOOKS_WEBHOOK_URL` environment variable.
  */
-export async function sendWebhook(spec, ctx, env = process.env) {
+export async function sendWebhook(spec, ctx, env = process.env, retry = {}) {
     const url = spec.url || env.DSH_HOOKS_WEBHOOK_URL;
     if (!url)
         return { ok: false, error: '缺少 webhook URL（notify.url 或 DSH_HOOKS_WEBHOOK_URL）' };
     const body = spec.slack ? { text: summarizeContext(ctx) } : webhookPayload(ctx);
+    const retries = Math.max(0, retry.retries ?? 0);
+    const baseDelay = Math.max(0, retry.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS);
+    const log = retry.log ?? ((line) => console.warn(line));
     const attempt = async () => {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), NOTIFY_TIMEOUT_MS);
@@ -117,22 +140,31 @@ export async function sendWebhook(spec, ctx, env = process.env) {
             clearTimeout(timer);
         }
     };
-    let response;
-    try {
-        response = await attempt();
-    }
-    catch (error) {
+    // Attempt loop: `retries` counts the attempts AFTER the first one, so the
+    // total is `1 + retries` — identical to the run channel's semantics.
+    for (let attemptNumber = 0;; attemptNumber++) {
+        let failure;
+        let retryable;
         try {
-            response = await attempt();
+            const response = await attempt();
+            if (response.ok)
+                return { ok: true };
+            failure = `webhook 响应 HTTP ${response.status}`;
+            retryable = isRetryableStatus(response.status);
+        }
+        catch (error) {
+            failure = `webhook 请求失败: ${error instanceof Error ? error.message : String(error)}`;
+            // Transport failures are always worth another attempt.
+            retryable = true;
         }
-        catch (retryError) {
-            const cause = retryError instanceof Error ? retryError.message : String(retryError);
-            return { ok: false, error: `webhook 请求失败（重试后仍失败）: ${cause}` };
+        const attempts = attemptNumber + 1;
+        if (!retryable || attempts > retries) {
+            return { ok: false, error: attempts > 1 ? `${failure}（${attempts} 次尝试后仍失败）` : failure };
         }
+        const delay = baseDelay * 2 ** attemptNumber;
+        log(`[dsh-hooks] 通知发送失败（${failure}），${delay}ms 后重试（${attempts}/${retries}）：${eventLabel(ctx)}`);
+        await sleep(delay);
     }
-    if (!response.ok)
-        return { ok: false, error: `webhook 响应 HTTP ${response.status}` };
-    return { ok: true };
 }
 /**
  * Desktop balloon/toast notification. The summary travels through an
@@ -196,10 +228,14 @@ function runAndWait(argv, env, timeoutMs) {
         });
     });
 }
-/** Fire a built-in notification; failures only warn and surface in the result. */
-export async function fireNotify(spec, ctx, record) {
+/**
+ * Fire a built-in notification; failures only warn and surface in the result.
+ * `retry` carries the hook's `retries` / `retryDelayMs` — honoured by the
+ * webhook channel; the desktop channel is a local spawn and never retries.
+ */
+export async function fireNotify(spec, ctx, record, retry = {}) {
     const startedAt = Date.now();
-    const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx) : await sendDesktop(spec, ctx);
+    const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx, process.env, retry) : await sendDesktop(spec, ctx);
     if (!result.ok) {
         console.warn(`[dsh-hooks] 通知发送失败 (${eventLabel(ctx)}): ${result.error}`);
         record?.({

package/lib/server.js

@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module';
-import { describeHook, evaluateHooks, mockContext, patchFilePath } from './dry-run.js';
+import { applyMockFields, describeHook, evaluateHooks, MOCK_NUMERIC_FIELDS, mockContext, patchFilePath } from './dry-run.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify, summarizeContext } from './notify.js';
 import { FEISHU_SETUP_BUSY } from './feishu-session.js';
@@ -153,11 +153,27 @@ export function createHookHandler(options) {
                 return;
             }
             const reason = typeof body.reason === 'string' && body.reason !== '' ? body.reason : undefined;
-            const ctx = mockContext(event, {
+            const rawFields = body.fields;
+            if (rawFields !== undefined && (typeof rawFields !== 'object' || rawFields === null || Array.isArray(rawFields))) {
+                json(res, FAIL('bad-request', 'fields 必须是对象（模拟字段 → 数字）'), 400);
+                return;
+            }
+            const simulated = applyMockFields(mockContext(event, {
                 reason,
                 tool: typeof body.tool === 'string' ? body.tool : undefined,
                 sessionName: typeof body.sessionName === 'string' ? body.sessionName : undefined,
-            });
+            }), rawFields);
+            if (simulated.ignored.length > 0) {
+                json(res, FAIL('bad-request', `无法模拟的字段：${simulated.ignored.join(', ')}（可用：${MOCK_NUMERIC_FIELDS.join(' / ')}）`), 400);
+                return;
+            }
+            const ctx = simulated.ctx;
+            // Echo every numeric field the simulated context actually carries (mock
+            // defaults + explicit overrides) so the panel can show what was matched.
+            const fields = Object.fromEntries(MOCK_NUMERIC_FIELDS.filter((key) => ctx[key] !== undefined).map((key) => [
+                key,
+                ctx[key],
+            ]));
             const lines = evaluateHooks(hooks, event, ctx, reason);
             const matchedHooks = lines.filter((line) => line.matched);
             const execute = body.execute === true;
@@ -168,12 +184,13 @@ export function createHookHandler(options) {
                     if (hook.run)
                         runner.run(hook, ctx);
                     else if (hook.notify)
-                        void fireNotify(hook.notify, ctx);
+                        void fireNotify(hook.notify, ctx, undefined, { retries: hook.retries, retryDelayMs: hook.retryDelayMs });
                 }
             }
             json(res, OK({
                 event,
                 reason,
+                fields,
                 executed: execute,
                 total: hooks.length,
                 matched: matchedHooks.length,

package/lib/tail.d.ts

@@ -0,0 +1,44 @@
+import type { HookRunRecord } from './history.js';
+/** Bytes of the file tail read for the initial backfill. */
+export declare const TAIL_BACKFILL_BYTES: number;
+export interface TailBatch {
+    /** Parsed records of the complete lines in this batch, in file order. */
+    records: HookRunRecord[];
+    /** The same lines verbatim, for `--json` passthrough. */
+    lines: string[];
+    /** The file shrank (rotation/truncation) and reading restarted from 0. */
+    reset: boolean;
+}
+/** Optional filters for `tail` (all are AND-ed; unset means "no filter"). */
+export interface TailFilter {
+    /** Exact event name (`turn/end`, …). */
+    event?: string;
+    /** Exact outcome (`exit-nonzero`, `send-failed`, …). */
+    outcome?: string;
+    /** Substring of the hook identity (the rendered command / `notify:<channel>`). */
+    hook?: string;
+}
+/** Does a record pass every configured filter? */
+export declare function matchesTailFilter(record: HookRunRecord, filter: TailFilter): boolean;
+/** One human-readable line, aligned with the Web GUI's history timeline. */
+export declare function formatTailRecord(record: HookRunRecord): string;
+export declare class HistoryTailer {
+    #private;
+    readonly file: string;
+    constructor(file: string);
+    /** Bytes already consumed (the next read starts here). */
+    get offset(): number;
+    /**
+     * The last `limit` records (`limit <= 0` = all of them), read from at most
+     * `maxBytes` of the file tail so a large log is never slurped just to print
+     * a few lines. Leaves the reader positioned at EOF, so the following
+     * {@link readNew} only reports what is appended afterwards.
+     */
+    backfill(limit?: number, maxBytes?: number): HookRunRecord[];
+    /**
+     * Complete lines appended since the previous call. A file that shrank since
+     * then was rotated/truncated: reading restarts from 0 and `reset` is set so
+     * the caller can say so out loud.
+     */
+    readNew(): TailBatch;
+}

package/lib/tail.js

@@ -0,0 +1,154 @@
+/**
+ * Incremental reader for the hook history JSONL log, behind
+ * `dsh-hooks tail`. It follows the same rules as the history sink — complete
+ * lines only, a shrinking file means rotation/truncation and resets the
+ * offset, a broken line never throws — but it is strictly read-only and keeps
+ * no ring buffer: it hands each new batch to the caller.
+ *
+ * The reader tracks a byte offset plus the trailing fragment of the last read
+ * (a line can be observed mid-write). Decoding happens per chunk, exactly like
+ * the sink does, so a multibyte character split across two reads can cost one
+ * malformed line at worst — never a crash.
+ */
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+/** Bytes of the file tail read for the initial backfill. */
+export const TAIL_BACKFILL_BYTES = 64 * 1024;
+/** Does a record pass every configured filter? */
+export function matchesTailFilter(record, filter) {
+    if (filter.event !== undefined && record.event !== filter.event)
+        return false;
+    if (filter.outcome !== undefined && record.outcome !== filter.outcome)
+        return false;
+    if (filter.hook !== undefined && !record.command.includes(filter.hook))
+        return false;
+    return true;
+}
+/** Local `HH:MM:SS` stamp for a record's epoch-ms timestamp. */
+function clockTime(ts) {
+    const date = new Date(ts);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/** One human-readable line, aligned with the Web GUI's history timeline. */
+export function formatTailRecord(record) {
+    const parts = [clockTime(record.ts), record.event, record.command, record.outcome];
+    if (record.durationMs !== undefined)
+        parts.push(`${record.durationMs}ms`);
+    if (record.exitCode !== undefined && record.exitCode !== 0)
+        parts.push(`exit=${record.exitCode}`);
+    if (record.sessionName || record.sessionId)
+        parts.push(record.sessionName ?? String(record.sessionId));
+    let line = parts.join('  ');
+    if (record.error)
+        line += `\n    ${record.error.replace(/\s+/g, ' ').slice(0, 300)}`;
+    return line;
+}
+/** Parse one JSONL line into a record, or undefined when it is unreadable. */
+function parseRecord(line) {
+    try {
+        const entry = JSON.parse(line);
+        if (typeof entry !== 'object' || entry === null || typeof entry.ts !== 'number')
+            return undefined;
+        return entry;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class HistoryTailer {
+    file;
+    #offset = 0;
+    #pending = '';
+    constructor(file) {
+        this.file = file;
+    }
+    /** Bytes already consumed (the next read starts here). */
+    get offset() {
+        return this.#offset;
+    }
+    /** Read `[start, end)` as text (best-effort: returns '' when unreadable). */
+    #read(start, end) {
+        const length = end - start;
+        if (length <= 0)
+            return '';
+        const fd = openSync(this.file, 'r');
+        try {
+            const chunk = Buffer.allocUnsafe(length);
+            let total = 0;
+            while (total < length) {
+                const read = readSync(fd, chunk, total, length - total, start + total);
+                if (read <= 0)
+                    break;
+                total += read;
+            }
+            return chunk.subarray(0, total).toString('utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /**
+     * The last `limit` records (`limit <= 0` = all of them), read from at most
+     * `maxBytes` of the file tail so a large log is never slurped just to print
+     * a few lines. Leaves the reader positioned at EOF, so the following
+     * {@link readNew} only reports what is appended afterwards.
+     */
+    backfill(limit = 10, maxBytes = TAIL_BACKFILL_BYTES) {
+        if (!existsSync(this.file))
+            return [];
+        const size = statSync(this.file).size;
+        if (size === 0) {
+            this.#offset = 0;
+            this.#pending = '';
+            return [];
+        }
+        const start = Math.max(0, size - Math.max(0, maxBytes));
+        const text = this.#read(start, size);
+        this.#offset = size;
+        this.#pending = '';
+        let lines = text.split('\n');
+        // Reading from the middle of the file starts mid-line: drop that fragment.
+        if (start > 0)
+            lines = lines.slice(1);
+        const records = [];
+        for (const line of lines) {
+            if (line === '')
+                continue;
+            const record = parseRecord(line);
+            if (record !== undefined)
+                records.push(record);
+        }
+        return limit > 0 ? records.slice(-limit) : records;
+    }
+    /**
+     * Complete lines appended since the previous call. A file that shrank since
+     * then was rotated/truncated: reading restarts from 0 and `reset` is set so
+     * the caller can say so out loud.
+     */
+    readNew() {
+        const batch = { records: [], lines: [], reset: false };
+        if (!existsSync(this.file))
+            return batch;
+        const size = statSync(this.file).size;
+        if (size < this.#offset) {
+            this.#offset = 0;
+            this.#pending = '';
+            batch.reset = true;
+        }
+        if (size === this.#offset)
+            return batch;
+        const text = this.#pending + this.#read(this.#offset, size);
+        this.#offset = size;
+        const parts = text.split('\n');
+        this.#pending = parts.pop() ?? '';
+        for (const line of parts) {
+            if (line === '')
+                continue;
+            batch.lines.push(line);
+            const record = parseRecord(line);
+            if (record !== undefined)
+                batch.records.push(record);
+        }
+        return batch;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "packageManager": "pnpm@11.21.0",
   "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required. Includes a Hooks section in the Web GUI settings (history timeline + manual tester + notify tests + hook editor + Feishu connect).",
   "author": "PeterBon",