@konnga/dsh-hud 0.9.1 → 0.9.2

package/lib/host/git.js

@@ -0,0 +1,188 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * git 的调用与解析：执行 git、取 blob 字节、把 sha/路径归一成仓库内的提交与文件。
+ */
+/** 本地 git 超时：大仓库的 `git status` 也可能要几秒。 */
+export const GIT_TIMEOUT_MS = 30_000;
+/** execFile 输出上限，防止异常仓库把内存吃满。 */
+export const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+/** 同一 cwd 的状态缓存时长。 */
+export const MAX_PATH_LENGTH = 4_096;
+/** 请求体上限。 */
+/** 控制字符（含 NUL、换行）——出现在路径里即视为非法入参。 */
+export const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/** 运行一条 git 命令；永不自造结果，失败就把失败原因交回调用方。 */
+export function runGit(cwd, args, timeoutMs = GIT_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES, windowsHide: true, encoding: 'utf8' }, (error, stdout, stderr) => {
+            if (!error) {
+                resolve({ ok: true, stdout: stdout || '' });
+                return;
+            }
+            resolve({
+                ok: false,
+                stdout: stdout || '',
+                stderr: stderr || '',
+                killed: Boolean(error.killed) || Boolean(error.signal),
+                code: typeof error.code === 'number' ? error.code : (error.code ?? null),
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+    });
+}
+/** 校验浏览器传来的 cwd，只接受绝对、无控制字符、长度有界的路径。 */
+export function validateCwd(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return { ok: false, code: 'invalid-cwd', message: 'cwd must be a non-empty string' };
+    if (value.length > MAX_PATH_LENGTH)
+        return { ok: false, code: 'invalid-cwd', message: 'cwd is too long' };
+    if (CONTROL_CHARS.test(value))
+        return { ok: false, code: 'invalid-cwd', message: 'cwd contains control characters' };
+    if (!path.isAbsolute(value))
+        return { ok: false, code: 'invalid-cwd', message: 'cwd must be an absolute path' };
+    return { ok: true, value };
+}
+/** 提交 sha 的形状：只用十六进制，长度 4..40（面板给的是短 sha）。 */
+export const COMMIT_SHA = /^[0-9a-fA-F]{4,40}$/;
+/**
+ * 校验提交 sha。
+ *
+ * 只收十六进制，因此 `HEAD~1`、`--help`、`origin/main` 这类都进不来——`sha` 会作为
+ * 位置参数交给 `git`，只靠 `--` 分隔路径是不够的，必须在入口就把选项形状挡掉。
+ */
+export function validateCommitSha(value, label = 'sha') {
+    const reject = (message) => ({
+        ok: false,
+        code: 'invalid-sha',
+        message: `${label}: ${message}`,
+    });
+    if (typeof value !== 'string' || value.length === 0)
+        return reject('must be a non-empty string');
+    if (!COMMIT_SHA.test(value))
+        return reject('must be 4..40 hex characters');
+    return { ok: true, value };
+}
+/** 校验 diff 的仓库内相对路径：必须是相对、无控制字符、无 `..`、不以 `-` 开头。 */
+export function validateDiffPath(value, label = 'path') {
+    const reject = (message) => ({
+        ok: false,
+        code: 'invalid-path',
+        message: `${label}: ${message}`,
+    });
+    if (typeof value !== 'string' || value.length === 0)
+        return reject('must be a non-empty string');
+    if (value.length > MAX_PATH_LENGTH)
+        return reject('is too long');
+    if (CONTROL_CHARS.test(value))
+        return reject('contains control characters');
+    if (path.isAbsolute(value))
+        return reject('must be repo-relative, not absolute');
+    if (/^[\\/]/.test(value))
+        return reject('must not start with a separator');
+    if (value.startsWith('-'))
+        return reject('must not start with "-"');
+    if (value.split(/[\\/]/).includes('..'))
+        return reject('must not contain ".."');
+    return { ok: true, value };
+}
+/**
+ * 解析仓库根与目标提交的元信息（含父提交），`readCommit` / `readCommitDiff` 共用。
+ *
+ * 父提交直接从 `%P` 拿：`git log -1` 已经把它给了出来，不必再跑一次 `rev-parse`。
+ * 取**第一个**父提交作为比较基准——"这次提交改了什么"对合并提交也是这个意思，
+ * 而 `git show` 对合并提交默认给的是"组合差异"，常常是空的，对用户没意义。
+ *
+ * @returns `{ repo, sha, shortSha, subject, author, date, committedAt, refs, parents, base }`；
+ *   `base` 为空串表示这是根提交（与空树比较）。非仓库时 `repo` 为 null。
+ */
+export async function resolveCommit(cwd, sha) {
+    const root = await runGit(cwd, ['rev-parse', '--show-toplevel']);
+    if (!root.ok) {
+        if (root.killed)
+            throw Object.assign(new Error('git rev-parse timed out'), { code: 'timeout' });
+        if (root.code === 'ENOENT' && !fs.existsSync(cwd))
+            throw Object.assign(new Error('cwd does not exist'), { code: 'no-cwd' });
+        if (root.code === 'ENOENT')
+            throw Object.assign(new Error('git executable not found'), { code: 'git-missing' });
+        return {
+            repo: null,
+            sha,
+            shortSha: sha,
+            subject: '',
+            author: '',
+            date: '',
+            committedAt: null,
+            refs: [],
+            parents: [],
+            base: null,
+        };
+    }
+    const repoRoot = root.stdout.split('\n')[0].trim();
+    if (!repoRoot)
+        return {
+            repo: null,
+            sha,
+            shortSha: sha,
+            subject: '',
+            author: '',
+            date: '',
+            committedAt: null,
+            refs: [],
+            parents: [],
+            base: null,
+        };
+    const result = await runGit(repoRoot, [
+        'log',
+        '-1',
+        '--no-color',
+        '--date=short',
+        '--pretty=format:%H%x00%h%x00%an%x00%ad%x00%ct%x00%D%x00%P%x00%s',
+        sha,
+    ]);
+    if (!result.ok) {
+        throw Object.assign(new Error(result.stderr.trim() || 'unknown commit'), {
+            code: result.killed ? 'timeout' : 'unknown-commit',
+        });
+    }
+    const [full, short, author, date, seconds, refs, parents, subject] = result.stdout.split('\0');
+    const at = Number(seconds);
+    const parentList = typeof parents === 'string' && parents.length > 0 ? parents.split(' ').filter(Boolean) : [];
+    return {
+        repo: repoRoot,
+        sha: full || sha,
+        shortSha: short || sha,
+        subject: subject ?? '',
+        author: author ?? '',
+        date: date ?? '',
+        committedAt: Number.isFinite(at) ? at * 1000 : null,
+        refs: refs ? refs.split(', ').filter(Boolean) : [],
+        parents: parentList,
+        base: parentList.length > 0 ? parentList[0] : null,
+    };
+}
+/**
+ * `runGit` 的字节版。
+ *
+ * `cat-file blob` 的输出是任意二进制，按 utf8 解码会毁掉它（非法序列变成 U+FFFD，
+ * 再编码回去就不是原文件了），所以这条路径必须单独走 buffer 编码。
+ */
+export function runGitBytes(cwd, args, maxBytes) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: maxBytes, windowsHide: true, encoding: 'buffer' }, (error, stdout, stderr) => {
+            if (!error) {
+                resolve({ ok: true, stdout });
+                return;
+            }
+            resolve({
+                ok: false,
+                stdout,
+                stderr: stderr ? stderr.toString('utf8') : '',
+                killed: Boolean(error.killed) || Boolean(error.signal),
+                code: typeof error.code === 'number' ? error.code : (error.code ?? null),
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+    });
+}

package/lib/host/image.js

@@ -0,0 +1,265 @@
+import { resolveCommit, runGit, runGitBytes } from './git.js';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * 图片改动：按文件头认图片、读两侧尺寸与字节、把不可预览的原因说清楚。
+ */
+/**
+ * 单侧图片预览的字节上限。
+ *
+ * 超限不等于"看不了这个改动"：仍然回报真实字节数，只是不把内容塞进 JSON
+ * （base64 还要再涨 1/3，RPC 体量必须有界）。
+ */
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+/** PNG 的签名（8 字节）。 */
+export const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * 从**内容**而不是扩展名认图片类型（扩展名会骗人：`.png` 里放 gif 很常见）。
+ *
+ * @param buffer - 文件头若干字节。
+ * @returns MIME 字符串，认不出返回 null。
+ */
+export function sniffImageMime(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 12)
+        return null;
+    if (buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE))
+        return 'image/png';
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
+        return 'image/jpeg';
+    const gif = buffer.subarray(0, 6).toString('latin1');
+    if (gif === 'GIF87a' || gif === 'GIF89a')
+        return 'image/gif';
+    if (buffer.subarray(0, 4).toString('latin1') === 'RIFF' &&
+        buffer.subarray(8, 12).toString('latin1') === 'WEBP')
+        return 'image/webp';
+    if (buffer.subarray(0, 2).toString('latin1') === 'BM')
+        return 'image/bmp';
+    return null;
+}
+/** PNG：IHDR 紧跟签名，宽高各 4 字节大端。 */
+export function pngSize(buffer) {
+    if (buffer.length < 24)
+        return null;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+/** GIF：逻辑屏幕描述符，宽高各 2 字节小端。 */
+export function gifSize(buffer) {
+    if (buffer.length < 10)
+        return null;
+    return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+}
+/**
+ * JPEG：从头扫段，找 SOFn（C0–CF，但 C4/C8/CC 不是）里的高/宽。
+ *
+ * 段长字段是**含自身两字节**的长度，所以下一段起点是 `index + 2 + length`；
+ * 填充 0xFF、TEM 与 RSTn 都没有长度字段，只前进一字节。
+ */
+export function jpegSize(buffer) {
+    let index = 2;
+    while (index + 9 < buffer.length) {
+        if (buffer[index] !== 0xff) {
+            index += 1;
+            continue;
+        }
+        const marker = buffer[index + 1];
+        if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            index += 1;
+            continue;
+        }
+        const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isFrame)
+            return { width: buffer.readUInt16BE(index + 7), height: buffer.readUInt16BE(index + 5) };
+        const length = buffer.readUInt16BE(index + 2);
+        if (length < 2)
+            return null;
+        index += 2 + length;
+    }
+    return null;
+}
+/** WebP：VP8X 是 24 位减一、VP8（有损）内嵌 14 位、VP8L（无损）打包在 32 位里。 */
+export function webpSize(buffer) {
+    if (buffer.length < 30)
+        return null;
+    const chunk = buffer.subarray(12, 16).toString('latin1');
+    if (chunk === 'VP8X')
+        return { width: buffer.readUIntLE(24, 3) + 1, height: buffer.readUIntLE(27, 3) + 1 };
+    if (chunk === 'VP8 ' && buffer[23] === 0x9d && buffer[24] === 0x01 && buffer[25] === 0x2a) {
+        return { width: buffer.readUInt16LE(26) & 0x3fff, height: buffer.readUInt16LE(28) & 0x3fff };
+    }
+    if (chunk === 'VP8L' && buffer[20] === 0x2f) {
+        const packed = buffer.readUInt32LE(21);
+        return { width: (packed & 0x3fff) + 1, height: ((packed >> 14) & 0x3fff) + 1 };
+    }
+    return null;
+}
+/** BMP：BITMAPINFOHEADER 的宽为有符号、高可为负（自上而下）。 */
+export function bmpSize(buffer) {
+    if (buffer.length < 26)
+        return null;
+    const width = buffer.readInt32LE(18);
+    const height = buffer.readInt32LE(22);
+    if (width <= 0 || height === 0)
+        return null;
+    return { width, height: Math.abs(height) };
+}
+/**
+ * 读出图片的像素尺寸。纯函数，只读头部，认不出返回 `null`（绝不抛）。
+ *
+ * @param buffer - 文件内容（头部足够即可，但这里拿的是完整内容）。
+ * @param mime - `sniffImageMime` 的结果。
+ * @returns `{ width, height }` 或 null。
+ */
+export function readImageSize(buffer, mime) {
+    try {
+        if (mime === 'image/png')
+            return pngSize(buffer);
+        if (mime === 'image/jpeg')
+            return jpegSize(buffer);
+        if (mime === 'image/gif')
+            return gifSize(buffer);
+        if (mime === 'image/webp')
+            return webpSize(buffer);
+        if (mime === 'image/bmp')
+            return bmpSize(buffer);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 一个 git 对象的字节数；对象不存在（新文件还没有索引副本）返回 null。 */
+export async function gitBlobSize(repoRoot, spec) {
+    const result = await runGit(repoRoot, ['cat-file', '-s', spec]);
+    if (!result.ok)
+        return null;
+    const size = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isFinite(size) && size >= 0 ? size : null;
+}
+/** 判断一侧的内容：能预览就带上 base64 与像素尺寸，否则只说"为什么不能"。 */
+export function describeSide(buffer) {
+    const bytes = buffer.length;
+    const mime = sniffImageMime(buffer);
+    if (mime === null)
+        return { kind: 'not-image', bytes };
+    const size = readImageSize(buffer, mime);
+    return {
+        kind: 'image',
+        mime,
+        bytes,
+        width: size === null ? null : size.width,
+        height: size === null ? null : size.height,
+        base64: buffer.toString('base64'),
+    };
+}
+/** 读工作区里的一个文件；不是普通文件、或超过上限，都只回报状态。 */
+export async function readWorktreeSide(repoRoot, file) {
+    const full = path.resolve(repoRoot, file);
+    const rootPrefix = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep;
+    // validateDiffPath 已经挡掉绝对路径与 `..`；这里再确认落在仓库内（软链接不越界）。
+    if (!full.startsWith(rootPrefix))
+        return { kind: 'missing' };
+    let stats;
+    try {
+        stats = await fs.promises.stat(full);
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+    if (!stats.isFile())
+        return { kind: 'missing' };
+    if (stats.size > MAX_IMAGE_BYTES)
+        return { kind: 'too-large', bytes: stats.size, limit: MAX_IMAGE_BYTES };
+    try {
+        return describeSide(await fs.promises.readFile(full));
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+}
+/** 读一个 git 对象（`<rev>:<path>`，rev 为空串即索引）：不存在即 missing，超限只回报字节数。 */
+export async function readGitSide(repoRoot, rev, file) {
+    const spec = `${rev}:${file}`;
+    const size = await gitBlobSize(repoRoot, spec);
+    if (size === null)
+        return { kind: 'missing' };
+    if (size > MAX_IMAGE_BYTES)
+        return { kind: 'too-large', bytes: size, limit: MAX_IMAGE_BYTES };
+    const result = await runGitBytes(repoRoot, ['cat-file', 'blob', spec], MAX_IMAGE_BYTES + 64 * 1024);
+    if (!result.ok) {
+        if (result.killed)
+            throw Object.assign(new Error('git cat-file timed out'), { code: 'timeout' });
+        return { kind: 'missing' };
+    }
+    return describeSide(result.stdout);
+}
+/**
+ * 读一个二进制（图片）改动的两侧字节与像素尺寸，全部只读。
+ *
+ * `side` 与文本 diff 的两枚页签一一对应，这样"未暂存 / 已暂存"在两个视图里指的是同一件事：
+ *   - `worktree`（未暂存）：基线 = 索引 `:<path>`，新 = 工作区文件；
+ *   - `index`（已暂存）：基线 = `HEAD`，新 = 索引 `:<path>`；
+ *   - 给了 `sha`（提交明细）：基线 = 第一父提交（根提交则为空），新 = 该提交。
+ *
+ * 两侧各自回答"能不能预览"：`kind` 为 `image` / `too-large` / `not-image` / `missing`。
+ * 任一侧不可预览都不算失败 —— 另一侧照样能看。
+ *
+ * @param cwd - 会话工作区（绝对路径）。
+ * @param file - 仓库内相对路径。
+ * @param origFile - 重命名/复制的原路径，可选。
+ * @param side - `'worktree'` | `'index'`，给了 sha 时忽略。
+ * @param sha - 提交 sha（提交明细用），可选。
+ * @returns `{ repo, path, origPath, side, sha, before, after }`。
+ */
+export async function readImagePair(cwd, file, origFile = null, side = 'worktree', sha = null) {
+    const base = {
+        path: file,
+        origPath: origFile ?? null,
+        side: sha === null ? side : 'commit',
+        sha,
+    };
+    const empty = {
+        repo: null,
+        ...base,
+        before: { kind: 'missing' },
+        after: { kind: 'missing' },
+    };
+    if (sha !== null) {
+        const commit = await resolveCommit(cwd, sha);
+        if (!commit.repo)
+            return empty;
+        return {
+            repo: commit.repo,
+            shortSha: commit.shortSha,
+            ...base,
+            before: commit.base === null
+                ? { kind: 'missing' }
+                : await readGitSide(commit.repo, commit.base, origFile ?? file),
+            after: await readGitSide(commit.repo, commit.sha, file),
+        };
+    }
+    const root = await runGit(cwd, ['rev-parse', '--show-toplevel']);
+    if (!root.ok) {
+        if (root.killed)
+            throw Object.assign(new Error('git rev-parse timed out'), { code: 'timeout' });
+        if (root.code === 'ENOENT' && !fs.existsSync(cwd))
+            throw Object.assign(new Error('cwd does not exist'), { code: 'no-cwd' });
+        if (root.code === 'ENOENT')
+            throw Object.assign(new Error('git executable not found'), { code: 'git-missing' });
+        return empty;
+    }
+    const repoRoot = root.stdout.split('\n')[0].trim();
+    if (side === 'index') {
+        return {
+            repo: repoRoot,
+            ...base,
+            before: await readGitSide(repoRoot, 'HEAD', origFile ?? file),
+            after: await readGitSide(repoRoot, '', file),
+        };
+    }
+    return {
+        repo: repoRoot,
+        ...base,
+        before: await readGitSide(repoRoot, '', origFile ?? file),
+        after: await readWorktreeSide(repoRoot, file),
+    };
+}

package/lib/host/index.js

@@ -0,0 +1,90 @@
+/**
+ * dsh-hud — 宿主半边（Cordis 插件）。
+ *
+ * 在自己的 `ctx.webServer` 上挂 `/dsh-hud-rpc` 前缀路由，收发与内置 `/api` 完全相同的
+ * Connection RPC 信封，并把请求围栏交给 `connection.requestRejection`
+ * （Host/Origin + 浏览器会话认证），因此信任等级与内置通道一致。
+ *
+ * 为什么不直接调用内置通道：dsh >= 0.1.5-rc.1 起，外部插件无法使用
+ * `ctx.connection.rpc.handle()` —— Connection 插件是在自己内部
+ * `ctx.inject(["webServer"], …)` 作用域里注册路由的，无论调用方 inject 了什么，
+ * 那一行都会以 `cannot get property "webServer" without inject` 挂载失败。
+ * 因此本插件自持路由，只借用 Connection 的信任判定。
+ *
+ * 端点（全部只读，不写 index / 工作区 / 配置）：
+ *   - `status { cwd }` → 仓库事实：当前分支（或 detached）、ahead/behind、脏状态、
+ *     按类型分组的改动计数，以及改动清单（porcelain-v2 的两个字母 + 路径）。
+ *   - `diff { cwd, path, origPath? }` → 一个改动文件的**两侧** unified diff
+ *     （工作区 / 已暂存），已解析成带行号的 rows；未跟踪文件与 `--no-index` 对齐，
+ *     文本按行截断、行数有上限，二进制只报 `binary`。
+ *   - `image { cwd, path, origPath?, side?, sha? }` → 图片改动**两侧**的字节与像素尺寸
+ *     （`kind` 为 `image` / `too-large` / `not-image` / `missing`），给二进制预览用；
+ *     单侧上限 `MAX_IMAGE_BYTES`，超限只回报字节数。
+ *   - `session-time { sessionId }` → 该会话的创建时刻与累计墙钟（`llmMs` / `toolMs` /
+ *     `turns` / `steps`，来自内置 `sessionStats` 投影；服务缺失时 `available: false`）。
+ *   - `prompt-history { sessionId, limit? }` → 该会话的用户 prompt（**新的在前**，来自内置
+ *     `turnOutline` 投影；相邻重复只留一条，默认最多 100 条）。
+ *   - `log { cwd, count? }` → 最近提交（短 sha、作者、日期、refs、标题），条数钳制 1..50。
+ *   - `commit { cwd, sha }` → 某次提交的元信息与改动清单（相对**第一个父提交**，
+ *     合并提交也按第一父提交看），清单形状与 `status.changes` 一致。
+ *   - `commit-diff { cwd, sha, path, origPath? }` → 该提交里某个文件的 unified diff，
+ *     已解析成带行号的 rows（形状与 `diff` 的**单侧**一致）。
+ *   - `session-changes { cwd, sessionId }` → **本会话改过哪些文件**（按会话归因，见下）：
+ *     路径、写入/编辑次数、首次与末次改动时间，以及"自 … 起记录"的时间戳。
+ *
+ * git 调用一律 `execFile`（无 shell）、带超时、有界输出，并对同一 cwd 做短 TTL 缓存 +
+ * 在途请求合并，避免面板轮询时反复跑 `git status`。
+ */
+export { parseDiff, parseNameStatus, parseStatus } from './parse.js';
+export { validateCommitSha, validateCwd, validateDiffPath } from './git.js';
+export { MAX_IMAGE_BYTES, readImagePair, readImageSize, sniffImageMime } from './image.js';
+export { readCommit, readCommitDiff, readDiff, readLog, readReviewSignatures, readStatus, readTags, } from './readers.js';
+import { trackSessionChanges, } from './session.js';
+export { PROMPT_HISTORY_MAX, readPromptHistory, readSessionChanges, readSessionOverview, readSessionTime, readSessionTools, } from './session.js';
+import { CHANNEL, handleRequest, } from './rpc.js';
+export { CHANNEL } from './rpc.js';
+import { rememberContext, } from './services.js';
+/** 本插件独占的 RPC 通道前缀（浏览器侧用同一常量调用）。 */
+/** 插件名：`cordis.patch.yml` 用包名插入，Cordis 读的就是这个导出。 */
+export const name = 'dsh-hud';
+/**
+ * 模块自带的硬依赖声明：Cordis 读这里的 `inject` 做激活门控，
+ * `cordis.patch.yml` 的行里因此不再重复写一遍。
+ */
+export const inject = ['webServer', 'connection'];
+/* --------------------------------------------- 二进制预览（图片，只读） */
+/* ------------------------------------------------- 会话改动（按会话归因） */
+/**
+ * "哪个会话写过哪个文件"——事实源是 fs seam 派发的两类事件：
+ *
+ *   - `fs/write-intent` / `fs/edit-intent`（waterfall，参数 `(target, exec)`）：这次**要**动
+ *     哪个文件。`dsh-tool-fs` 的写入/编辑工具与 `dsh-tool-str-replace-editor` 都走 `ctx.fs`，
+ *     因此都会发这两个意图事件。
+ *   - `fs/observed`（emit，参数 `(target, observation, exec)`）：那一下**之后**文件是 `present`
+ *     还是 `absent`。注意它对**读取**也发（"编辑前必须先读"那个策略插件就是靠它），所以不能
+ *     只看它 —— 必须与意图配对：同一个工具调用里先有意图、后有观察，才算这次改动落了地。
+ *
+ * `exec.agent.session.header` 同时给出 `id`（哪个会话）与 `cwd`（哪个工作区），所以"谁改的"
+ * 不用猜。只记 cwd 之内的路径（git 只关心这些），每个会话与全局都有上限，避免长会话吃内存。
+ *
+ * 已知不覆盖（界面上如实标注，不假装全知）：
+ *   - agent 通过 bash 间接改的文件（`sed -i`、脚本、格式化、`git` 操作）；
+ *   - 本进程启动**之前**的改动（fs 观察不持久化）——所以每个会话都报一个 `since`。
+ */
+/* ------------------------------------------------------------------ 线路层 */
+/* ------------------------------------------------------------------- 插件 */
+/**
+ * 插件入口。
+ * @param ctx - 已注入 webServer 与 connection 的 Cordis 上下文。
+ */
+export function apply(ctx) {
+    rememberContext(ctx);
+    trackSessionChanges(ctx);
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: CHANNEL,
+        handler: (req, res) => handleRequest(ctx, req, res),
+    }), `dsh-hud: POST ${CHANNEL}/*`);
+}
+// 导出即插件面：`apply` / `inject` / `name` 供 Cordis 读取；`CHANNEL` / `parseStatus` /
+// `validateCwd` / `readStatus` 是可直接单测的单元（前两个是纯函数，最后一个需要真实仓库）。