dsh-remote-control 1.0.0

package/dist/src/shell/config.js

@@ -0,0 +1,212 @@
+/**
+ * config — 插件配置：合成、校验、夹取。
+ *
+ * 优先级与旧实现一致：**环境变量 > patch 注入的 config > 默认值**
+ * （取证 docs/legacy-spec/host-plugin-cordis.md §5.1）。
+ * **键名一律继承旧名**：这些键写在用户的 `~/.dsh/profiles/desktop/cordis.patch.yml` 里，
+ * 改名等于让线上配置静默失效——那是"语义继承"允许、而"结构照抄"禁止的分界线上
+ * 唯一必须站在继承一侧的维度（复核 §5.4）。
+ *
+ * 校验只拦"真的不能工作"的两件事（serverUrl 与 hostToken），其余一律 warn + 夹回默认值：
+ * 一个 GUI 宿主里，插件因为某个可选参数写错而不加载，比带着次优参数跑起来更难排查。
+ * error 时也不抛，只写一次 status.json 留下面包屑（§5.2 的原话动机：
+ * 「otherwise "why is nothing happening?" has no answer」）。
+ */
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+export const DEFAULT_CONFIG = {
+    enabled: true,
+    serverUrl: 'ws://127.0.0.1:8787',
+    hostToken: '',
+    hostTokenEnv: 'DRC_HOST_TOKEN',
+    hostId: '',
+    hostLabel: 'dsh-host',
+    keepAwake: { enabled: true, idleReleaseSec: 300, keepDisplay: false },
+    mockBridge: false,
+    statusFile: path.join(homedir(), '.dsh', 'dsh-remote-control', 'status.json'),
+    unarchiveOnPrompt: true,
+    pairOnStartSec: 0,
+    pairTtlMs: 120_000,
+    // **默认走图片**。2026-10-02 取证推翻了原判断（原判断：文本二维码在任何等宽渲染器下
+    // 都能扫，图片是可有可无的旁路）：
+    //   · DSH 命令卡的等宽输出块是 `white-space: pre` + `line-height: 1.6`（app bundle 里
+    //     的那条规则，实测行间留白约占行高 37%），每两行模块之间被塞进一条整行宽的缝隙，
+    //     半块二维码被横切成条。
+    //   · 用用户真机贴出来的那段输出做受控实验：把字号行距调到 1.0 时 zxing 解得出来，
+    //     调到 ≥1.15 就扫不出来；而 DSH 固定 1.6。也就是说"文本码能扫"在**唯一宿主**上不成立。
+    //   · 而 ANSI 反色救不了：TerminalBlock 把每行渲染成内联 span，背景只覆盖字形盒，
+    //     不覆盖行间留白（见 dsh-client-ui-primitives 的 parseAnsiLines/renderLine）。
+    // 图片是自包含位图矩阵，跟宿主的行高、字体、配色都无关——这才是"扫得出来"的那条路。
+    qrImage: true,
+    // 写图片 ≠ 替用户打开查看器：仍然默认关（原话「不要用打开一个图片的方式」）。
+    qrOpen: false,
+    qrAnsi: false,
+    qrStyle: 'half',
+    carrierGraceMs: 5000,
+    takeOverQuestions: false,
+    approvalTimeoutSec: 180,
+    listingRefreshSec: 15,
+    conversationIdleTtlSec: 86_400,
+};
+const loopback = /^wss?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/;
+const wsUrl = /^wss?:\/\/.+/;
+/**
+ * 环境变量里的数字：只收「有限的非负数」，其余折成 0（= 关）。
+ *
+ * 为什么不能写成 `Number(v) || 0`：`Number('Infinity')` 是 Infinity，而它是**真值**，
+ * `|| 0` 放过去了——`pairOnStartSec=Infinity` 的语义是"这张仍然带着 PSK 的配对码
+ * 永久有效"，正好是这条配置想避免的事。NaN 侥幸会被 `|| 0` 折掉，但那是巧合不是规则。
+ */
+function envSeconds(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+/** 布尔开关的环境变量写法：`1`/`0`（`true`/`false` 也认）是这里的运维习惯，其余值不猜、退回上层值。 */
+function envFlag(value, fallback) {
+    if (value === '1' || value === 'true')
+        return true;
+    if (value === '0' || value === 'false')
+        return false;
+    return fallback;
+}
+/** 合成三级配置。`injected` 来自 cordis 的 patch 层。 */
+export function readConfig(injected, env = process.env) {
+    const merged = {
+        ...DEFAULT_CONFIG,
+        ...(injected ?? {}),
+        keepAwake: { ...DEFAULT_CONFIG.keepAwake, ...(injected?.keepAwake ?? {}) },
+    };
+    const fromEnv = (name) => env[name];
+    if (fromEnv('DRC_SERVER_URL'))
+        merged.serverUrl = env.DRC_SERVER_URL;
+    if (fromEnv('DRC_HOST_LABEL'))
+        merged.hostLabel = env.DRC_HOST_LABEL;
+    if (fromEnv('DRC_HOST_ID'))
+        merged.hostId = env.DRC_HOST_ID;
+    if (fromEnv('DRC_PAIR_ON_START_SEC'))
+        merged.pairOnStartSec = envSeconds(env.DRC_PAIR_ON_START_SEC);
+    // 这两个开关默认就是关的，所以环境变量只用于**打开**（`=1`）；
+    // 仍然接受 `=0` 显式关闭，覆盖 patch 里开的情况。
+    if (fromEnv('DRC_QR_IMAGE'))
+        merged.qrImage = envFlag(env.DRC_QR_IMAGE, merged.qrImage);
+    if (fromEnv('DRC_QR_OPEN'))
+        merged.qrOpen = envFlag(env.DRC_QR_OPEN, merged.qrOpen);
+    if (fromEnv('DRC_QR_ANSI'))
+        merged.qrAnsi = envFlag(env.DRC_QR_ANSI, merged.qrAnsi);
+    if (fromEnv('DRC_QR_STYLE')) {
+        const style = env.DRC_QR_STYLE;
+        // 不猜：值不认识就保留上层（patch 或默认）的值，并由 validateConfig 负责 warn。
+        if (['ascii', 'block', 'half'].includes(style))
+            merged.qrStyle = style;
+    }
+    if (fromEnv('DRC_MOCK_BRIDGE') === '1')
+        merged.mockBridge = true;
+    if (fromEnv('DRC_TAKE_OVER_QUESTIONS') === '1')
+        merged.takeOverQuestions = true;
+    // token 只从环境变量取：patch 文件是 600 权限的 yaml，但把凭据写在配置文件里
+    // 比留在环境变量里更容易被顺手提交或贴进工单。
+    if (merged.hostTokenEnv)
+        merged.hostToken = env[merged.hostTokenEnv] ?? merged.hostToken;
+    return merged;
+}
+const secondsSchema = z.number().finite();
+/** 校验 + 就地夹取。error 级问题会让上层拒绝启动 runtime（但仍留 status 面包屑）。 */
+export function validateConfig(config) {
+    const problems = [];
+    if (!wsUrl.test(config.serverUrl)) {
+        problems.push({
+            level: 'error',
+            field: 'serverUrl',
+            message: `serverUrl 必须是 ws:// 或 wss:// 开头的地址，收到 ${JSON.stringify(config.serverUrl)}`,
+        });
+    }
+    else if (config.serverUrl.startsWith('ws://') && !loopback.test(config.serverUrl)) {
+        problems.push({
+            level: 'warn',
+            field: 'serverUrl',
+            message: '向非回环地址走明文 ws://，配对码与密文在链路上是可见的（生产请用 wss://）',
+        });
+    }
+    if (!config.hostToken) {
+        problems.push({
+            level: 'error',
+            field: 'hostToken',
+            message: `缺少 host token：请把中继的 DRC_HOST_TOKEN 写进环境变量 ${config.hostTokenEnv || '(hostTokenEnv 为空)'}，或在 patch 里直接给 hostToken`,
+        });
+    }
+    else if (config.hostToken.length < 24) {
+        problems.push({
+            level: 'warn',
+            field: 'hostToken',
+            message: 'host token 短于 24 字符，建议 `openssl rand -hex 24`',
+        });
+    }
+    if (!secondsSchema.safeParse(config.keepAwake.idleReleaseSec).success || config.keepAwake.idleReleaseSec < 0) {
+        problems.push({
+            level: 'warn',
+            field: 'keepAwake.idleReleaseSec',
+            message: '不是有效的非负秒数，已夹回 300（KeepAwake 绝不能拿到 NaN）',
+        });
+        config.keepAwake.idleReleaseSec = 300;
+    }
+    if (config.pairTtlMs <= 0) {
+        problems.push({ level: 'warn', field: 'pairTtlMs', message: '必须为正数，已夹回 120000' });
+        config.pairTtlMs = 120_000;
+    }
+    if (!secondsSchema.safeParse(config.pairOnStartSec).success || config.pairOnStartSec < 0) {
+        // patch 文件里写 `pairOnStartSec: .inf` 也会走到这里：env 侧已经折掉了，注入侧不能漏。
+        problems.push({ level: 'warn', field: 'pairOnStartSec', message: '必须是非负的有限秒数，已折回 0（关闭自动发码）' });
+        config.pairOnStartSec = 0;
+    }
+    if (config.qrOpen && !config.qrImage) {
+        problems.push({
+            level: 'warn',
+            field: 'qrOpen',
+            message: 'qrOpen 需要 qrImage=true 才会写图片文件；现在只出文本二维码（文本码在 DSH 命令卡里扫不出来，见 config.ts 默认值注释）',
+        });
+    }
+    if (!['ascii', 'block', 'half'].includes(config.qrStyle)) {
+        problems.push({
+            level: 'warn',
+            field: 'qrStyle',
+            message: `qrStyle 只认 ascii/block/half，收到 ${JSON.stringify(config.qrStyle)}，已退回 half`,
+        });
+        config.qrStyle = 'half';
+    }
+    if (!secondsSchema.safeParse(config.conversationIdleTtlSec).success || config.conversationIdleTtlSec <= 0) {
+        // 0 或非法值**不表示"永不剪枝"**：永不剪枝就是那条无界的密钥簿。夹回默认值并说明。
+        problems.push({
+            level: 'warn',
+            field: 'conversationIdleTtlSec',
+            message: '必须是正数秒；这里不接受"永不剪枝"（无界的 PSK 簿是复核 🟡8 的原始缺陷），已夹回 86400',
+        });
+        config.conversationIdleTtlSec = 86_400;
+    }
+    if (config.pairOnStartSec > 0) {
+        problems.push({
+            level: 'warn',
+            field: 'pairOnStartSec',
+            message: '开启后会把"仍然有效的配对码（含 PSK）"发布进 0600 的 status.json；这是验证辅助，用完请关掉',
+        });
+    }
+    if (!config.statusFile) {
+        problems.push({ level: 'warn', field: 'statusFile', message: '为空将关闭状态快照；GUI 宿主里这是唯一的排错入口' });
+    }
+    if (config.takeOverQuestions) {
+        problems.push({
+            level: 'warn',
+            field: 'takeOverQuestions',
+            message: '提问接管会**取代桌面 UI 的提问能力**（ctx.userQuestions 只允许一个活跃 provider）；手机端不在线时提问会直接失败',
+        });
+    }
+    return problems;
+}
+/** 令牌脱敏：日志与 status.json 里都只允许出现这个形态。 */
+export function redactSecret(value) {
+    if (value.length <= 8)
+        return '****';
+    return `${value.slice(0, 4)}…${value.slice(-2)}(${value.length})`;
+}
+export { redactSecret as redact };
+//# sourceMappingURL=config.js.map

package/dist/src/shell/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/shell/config.ts"],"names":[],"mappings":"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"}

package/dist/src/shell/pairing-text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * pairing-text — `/drc pair` 的文本输出（纯函数，所以这条拍板能被单测锁住）。
+ *
+ * **2026-10-02 翻转**：原拍板是「出文本二维码，图片版是显式旁路」。真机取证推翻了它——
+ * DSH 命令卡把等宽输出按 `line-height: 1.6` 渲染，行间留白把半块二维码横切成条，
+ * zxing 在 ≥1.15 行距就解不出来（实测，见 `shell/config.ts` 的 `qrImage` 默认值注释）。
+ * 所以现在**默认输出图片路径**，文本二维码降级为 `qrImage:false` 时的退路。
+ *
+ * 无论走哪条路，输出本身必须自足：6 位配对码 + 可粘贴的 URI + TTL + 一次性提示。
+ * 这条如果没有测试，将来很容易又"顺手加一句 open 更好用"。
+ *
+ * 为什么最终仍可能落到文本：宿主的命令 API 只接受纯文本结果（没有图片/附件返回类型），
+ * 所以我们能把 PNG 写到磁盘、把**路径**写进文本，但不能把图直接塞进卡片。
+ */
+export interface PairingTextView {
+    /** 6 位配对码。 */
+    token: string;
+    /** 完整的 `dshr:/p?...` 载荷：既是二维码的内容，也是可粘贴的那一行。 */
+    qr: string;
+    /** 本地记录的过期时刻（毫秒）；服务端权威 TTL 到达后已改写。 */
+    expiresAt: number;
+    /** 当前时刻（注入，便于测试）。 */
+    now: number;
+    qrImage: boolean;
+    /**
+     * 二维码 PNG 的**绝对路径**，由调用方按当前会话的工作区解析好后传进来
+     * （`<workspace>/.dsh/pairing-qr.png`，解析不出工作区时是 `~/.dsh/pairing-qr.png`）。
+     * 这里是纯函数，不认识"工作区"这个概念，也就不该自己去拼路径——拼法只有 `shell/status.ts`
+     * 一处，卡片上印的路径与真正落盘的路径因此不可能分叉。
+     * 空串 = 这一版没有图（图片模式关掉，或 statusFile 没配），正文不许报路径。
+     */
+    imageFile: string;
+    /** 已经渲染好的终端二维码；`qrImage` 模式下不需要它，所以可选。 */
+    terminalQr?: string;
+}
+/** 中继没连上时的说法：必须指出去哪看原因，而不是"失败了"。 */
+export declare const PAIR_UNAVAILABLE_TEXT = "\u4E2D\u7EE7\u8FD8\u6CA1\u8FDE\u4E0A\uFF0C\u6682\u65F6\u65E0\u6CD5\u914D\u5BF9\u3002\u770B status.json \u7684 relayProblem\u3002";
+export declare function pairingPairText(view: PairingTextView): string;

package/dist/src/shell/pairing-text.js

@@ -0,0 +1,22 @@
+/** 中继没连上时的说法：必须指出去哪看原因，而不是"失败了"。 */
+export const PAIR_UNAVAILABLE_TEXT = '中继还没连上，暂时无法配对。看 status.json 的 relayProblem。';
+export function pairingPairText(view) {
+    const ttlSec = Math.max(0, Math.round((view.expiresAt - view.now) / 1000));
+    const lines = [`配对码 ${view.token} · ${ttlSec} 秒内有效 · 一次性`, '小程序里扫码，或手输这 6 位数字。'];
+    if (view.qrImage && view.imageFile) {
+        // 图片是默认路径：正文只说"扫这张图"，不再塞那段在 DSH 里扫不出来的文本码。
+        // "打开这张 PNG"只能当兜底：`/drc pair` 之后右栏会**自己弹出**二维码
+        // （`packages/presentation`，装了那一行才成立），把开图写成主路径等于让用户
+        // 白跑一趟去找文件——而这正是本命令当初被要求别做的事。
+        lines.push('', `二维码会自动弹出到右栏；没弹出就打开这张 PNG 再扫：${view.imageFile}`);
+    }
+    else if (view.terminalQr) {
+        lines.push('', view.terminalQr);
+    }
+    // 扫不出来时（比例字体、吞字形的渲染器、或行高把码切开了）这条路仍然成立：配对页可以直接粘这一行。
+    lines.push('', view.qr);
+    if (!view.qrImage)
+        lines.push('', '（如需图片版：把 patch 里的 qrImage 设为 true）');
+    return lines.join('\n');
+}
+//# sourceMappingURL=pairing-text.js.map

package/dist/src/shell/pairing-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-text.js","sourceRoot":"","sources":["../../../src/shell/pairing-text.ts"],"names":[],"mappings":"AAoCA,oCAAoC;AACpC,MAAM,CAAC,MAAM,qBAAqB,GAAG,6CAA6C,CAAA;AAElF,MAAM,UAAU,eAAe,CAAC,IAAqB;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAA;IAC1E,MAAM,KAAK,GAAG,CAAC,OAAO,IAAI,CAAC,KAAK,MAAM,MAAM,aAAa,EAAE,oBAAoB,CAAC,CAAA;IAChF,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,2CAA2C;QAC3C,+CAA+C;QAC/C,mDAAmD;QACnD,8BAA8B;QAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,+BAA+B,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;IACjE,CAAC;SAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;IACjC,CAAC;IACD,mDAAmD;IACnD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;IACvB,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,oCAAoC,CAAC,CAAA;IACvE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/src/shell/status.d.ts

@@ -0,0 +1,39 @@
+import type { Clock, StatusSink } from '../ports/index.js';
+export declare class StatusFile implements StatusSink {
+    private readonly file;
+    private readonly clock;
+    private readonly refreshMs;
+    private timer;
+    private lastWritten;
+    constructor(file: string, clock: Clock, refreshMs?: number);
+    write(snapshot: Record<string, unknown>): void;
+    /**
+     * 打开定时器刷新（调用方提供的是**纯构造器**：只负责返回当下最新的状态）。
+     *
+     * 写盘这件事归本类，不归调用方：第一版这里只 `refresh()` 把返回值丢掉了，
+     * 于是 status.json 永远停在启动那一版——而 live-e2e 与外部脚本取配对码读的就是
+     * 这个文件（取证 docs/legacy-spec/host-plugin-cordis.md §5.3 的"年龄 < 25s"判据）。
+     * 更糟的是 `carrier`/`relay` 再也不更新，GUI 宿主里唯一的排错入口变成了死数据。
+     */
+    start(refresh: () => Record<string, unknown>): void;
+    stop(): void;
+    /** 此刻是否在按节拍刷新（测试与 status 自身的 `refreshing` 字段读它）。 */
+    get refreshing(): boolean;
+    get path(): string;
+}
+/**
+ * 配对二维码 PNG 的落点（0600）：**当前会话的工作区**下的 `.dsh/pairing-qr.png`。
+ *
+ * 2026-10-02 用户拍板改的落点（原话「要保存到工作区的 .dsh 不是 home 下的 .dsh」）：
+ * 二维码属于"这次配对属于哪个项目"这件事，跟着会话的工作区走比跟着 home 走更符合直觉，
+ * 也不会在用户机器上多出一个与项目无关的固定文件。
+ *
+ * `workspaceDir` 解析不出来时退回 `~/.dsh/pairing-qr.png`（配置目录根部）——**不是**退回
+ * 与 status.json 同目录：PNG 是给用户/扫码器看的东西，不该埋进 `~/.dsh/dsh-remote-control/`
+ * 这个实现目录里。
+ *
+ * statusFile 只当开关用——空串表示这一行没配过，此时返回空串，调用方据此退回文本码
+ * （空串路径绝不能去 `path.join`，否则 PNG 会写到进程 CWD）。
+ */
+export declare function pairingImagePath(statusFile: string, workspaceDir?: string): string;
+export declare function writePrivateFile(file: string, data: Buffer | string): boolean;

package/dist/src/shell/status.js

@@ -0,0 +1,119 @@
+/**
+ * status — 运行状态快照（`~/.dsh/dsh-remote-control/status.json`）。
+ *
+ * 为什么非有不可：宿主是 GUI 应用，stdout 没人看，插件"没反应"时用户与开发者
+ * 都没有入口。旧实现把它做成排错第一入口，靠两个字段区分了两类完全不同的故障——
+ * `carrier`（`services` 真内核 / `mock` 内存替身 / `none` 配置不合法）
+ * 与 `relay` + `relayProblem`（连不上中继还是内核没接上）。
+ * 取证 docs/legacy-spec/host-plugin-cordis.md §5.3。
+ *
+ * 三条实现要求：
+ * 1. **0600 + 临时文件改名**。文件里可能出现"仍然有效的配对码 + PSK"（pairOnStartSec），
+ *    半写状态被读到也会让人误判。
+ * 2. **绝不含 token**（测试断言 `hostToken` 这个键不存在，只能出现脱敏形态）。
+ * 3. **按定时器刷新，不按消费刷新**。这条不是偷懒：它决定了外部脚本只能接受
+ *    "年龄 < 25s 且本轮未用过"的配对码（取证 HANDOFF.md §4.5 第 3 条）。
+ */
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export class StatusFile {
+    file;
+    clock;
+    refreshMs;
+    timer;
+    lastWritten = 0;
+    constructor(file, clock, refreshMs = 3000) {
+        this.file = file;
+        this.clock = clock;
+        this.refreshMs = refreshMs;
+    }
+    write(snapshot) {
+        if (!this.file)
+            return;
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true });
+            const tmp = `${this.file}.tmp-${process.pid}`;
+            // mode 在文件已存在时不生效，所以再 chmod 一次。
+            writeFileSync(tmp, JSON.stringify({ ...snapshot, updatedAt: new Date().toISOString(), pid: process.pid }, null, 2) + '\n', {
+                mode: 0o600,
+            });
+            renameSync(tmp, this.file);
+            this.lastWritten = this.clock.now();
+        }
+        catch {
+            // 快照写失败绝不能影响主流程；排错入口没了是遗憾，插件崩了是事故。
+        }
+    }
+    /**
+     * 打开定时器刷新（调用方提供的是**纯构造器**：只负责返回当下最新的状态）。
+     *
+     * 写盘这件事归本类，不归调用方：第一版这里只 `refresh()` 把返回值丢掉了，
+     * 于是 status.json 永远停在启动那一版——而 live-e2e 与外部脚本取配对码读的就是
+     * 这个文件（取证 docs/legacy-spec/host-plugin-cordis.md §5.3 的"年龄 < 25s"判据）。
+     * 更糟的是 `carrier`/`relay` 再也不更新，GUI 宿主里唯一的排错入口变成了死数据。
+     */
+    start(refresh) {
+        if (!this.file || this.timer !== undefined)
+            return;
+        const tick = () => {
+            // 先续期再写：写盘内部已经吞异常，但构造器是调用方的代码，
+            // 它抛了也不该让刷新节拍断掉——节拍一断就等于回到"停在启动那一版"。
+            this.timer = this.clock.setTimeout(tick, this.refreshMs);
+            try {
+                this.write(refresh());
+            }
+            catch {
+                /* 同上：状态入口不许成为崩溃源 */
+            }
+        };
+        this.timer = this.clock.setTimeout(tick, this.refreshMs);
+    }
+    stop() {
+        if (this.timer !== undefined) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /** 此刻是否在按节拍刷新（测试与 status 自身的 `refreshing` 字段读它）。 */
+    get refreshing() {
+        return this.timer !== undefined;
+    }
+    get path() {
+        return this.file;
+    }
+}
+/**
+ * 配对二维码 PNG 的落点（0600）：**当前会话的工作区**下的 `.dsh/pairing-qr.png`。
+ *
+ * 2026-10-02 用户拍板改的落点（原话「要保存到工作区的 .dsh 不是 home 下的 .dsh」）：
+ * 二维码属于"这次配对属于哪个项目"这件事，跟着会话的工作区走比跟着 home 走更符合直觉，
+ * 也不会在用户机器上多出一个与项目无关的固定文件。
+ *
+ * `workspaceDir` 解析不出来时退回 `~/.dsh/pairing-qr.png`（配置目录根部）——**不是**退回
+ * 与 status.json 同目录：PNG 是给用户/扫码器看的东西，不该埋进 `~/.dsh/dsh-remote-control/`
+ * 这个实现目录里。
+ *
+ * statusFile 只当开关用——空串表示这一行没配过，此时返回空串，调用方据此退回文本码
+ * （空串路径绝不能去 `path.join`，否则 PNG 会写到进程 CWD）。
+ */
+export function pairingImagePath(statusFile, workspaceDir) {
+    if (!statusFile)
+        return '';
+    if (workspaceDir)
+        return path.join(workspaceDir, '.dsh', 'pairing-qr.png');
+    return path.join(homedir(), '.dsh', 'pairing-qr.png');
+}
+export function writePrivateFile(file, data) {
+    if (!file)
+        return false;
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, data, { mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/src/shell/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/shell/status.ts"],"names":[],"mappings":"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"}

package/dist/src/transport/relay.d.ts

@@ -0,0 +1,107 @@
+import { type CmdPayload, type EvPayload } from 'dsh-remote-wire';
+import { ConversationBook, type PairSlot, type PrunePolicy } from '../core/keys.js';
+import type { Clock } from '../ports/index.js';
+export interface RelayClientOptions {
+    url: string;
+    hostId: string;
+    label: string;
+    /** 中继侧 `DRC_HOST_TOKEN` 的同值副本；只在这一条出站帧上出现。 */
+    token: string;
+    clock: Clock;
+    log: (message: string, fields?: Record<string, string | number | boolean | undefined>) => void;
+    /** 解出一条命令（已经过 MAC 校验）。 */
+    onCommand: (conversationId: string, cmd: CmdPayload, clientId?: string) => void;
+    /** 一条新配对建立：调用方要立刻把会话与防休眠状态推过去。 */
+    onPeerJoined: (conversationId: string, pairingToken: string | undefined) => void;
+    /** 一条配对通道被彻底作废（本端解不开、或本端主动声明它没人接了）。 */
+    onConversationGone: (conversationId: string) => void;
+    /** 某个客户端离开，但**会话保留**（D3）：它下次用同一个 convId 回来时还能接上。 */
+    onClientLeft: (conversationId: string, clientId: string) => void;
+    /**
+     * 按 `peer-joined` 回传的 pairingToken 取本地那张码。
+     * 取不到必须返回 null 并由调用方拒绝这条配对——**不允许**退化成"取最新的一张"，
+     * 那正是多码并存事故的形状。
+     */
+    lookupPairingSlot: (token: string) => PairSlot | null;
+    /** `pair-ready` 到达：调用方据此改写本地 PSK 过期时间。 */
+    onPairReady: (pairingToken: string, ttlMs: number) => void;
+    /**
+     * 中继宣告"这张配对码没配上"（`expired` / `already_used` / `rate_limited` /
+     * `invalid_or_expired`）。主机侧唯一的用处是**退避自动补发**：
+     * 被限速时还按原节拍发码，只会让自己继续被拒。
+     */
+    onPairFail?: (reason: string) => void;
+    /** 连接状态变化，直接进 status.json。 */
+    onState: (state: RelayStateInfo) => void;
+    /** 重连后的第一批帧之前要不要等一会（手机端可能还在旧 convId 上发）。 */
+    handshakeTimeoutMs?: number;
+    /** 配对通道的剪枝策略（不传用默认：空闲 24h 或超过 64 条）。 */
+    prunePolicy?: PrunePolicy;
+}
+export interface RelayStateInfo {
+    relay: 'online' | 'connecting' | 'offline';
+    problem?: string;
+    clients: number;
+    conversations: number;
+    generation: number;
+}
+export declare class RelayClient {
+    private readonly options;
+    readonly conversations: ConversationBook;
+    private socket;
+    private generation;
+    private attempts;
+    private stopped;
+    private reconnectTimer;
+    private handshakeTimer;
+    /** 连续解不开的会话：解不开说明这端已经没有对应密钥，留着它只会让手机永远转圈。 */
+    private readonly undecryptable;
+    /** 已经向中继声明过的 convId（防重复 `session-leave`）；有上界，见 {@link VOIDED_MAX}。 */
+    private readonly voided;
+    constructor(options: RelayClientOptions);
+    /** 已配对的会话数（`status.json` 与"有没有人能收"的判据都读它）。 */
+    get conversationCount(): number;
+    connect(): void;
+    stop(): void;
+    /** 发布一张新的配对码（PSK 留在本地，中继只拿到 6 位码）。
+     *
+     * 返回 false = socket 不在 OPEN 状态、这条 `pair-begin` **根本没上过网**。
+     * 调用方不能把这张码记成"有效"，否则 status.json 会展示一张中继没见过的码，
+     * 而手机扫它必然失败（取证 docs/legacy-spec/host-plugin-runtime.md §6.2）。
+     */
+    publishPairing(slot: PairSlot): boolean;
+    /**
+     * 按策略剪掉"再也不会被用"的配对通道（一天没收发，或超出条数上界）。
+     *
+     * 必须**同时**告诉中继与上层：只删本地内存的话，中继仍会把手机的密文转过来，
+     * 而手机看到的是一个不再有人应答的对端——正是复核 R1 那个静默黑洞的另一个入口。
+     * 所以这里走 `voidConversation`（发 `session-leave` + 回调 `onConversationGone`）。
+     */
+    pruneConversations(now?: number): string[];
+    /** 向一条配对会话发一条载荷；返回 false = 这条会话已经没了或没人接。 */
+    send(conversationId: string, payload: EvPayload): boolean;
+    broadcast(payload: EvPayload): number;
+    hasPeer(conversationId: string): boolean;
+    conversationIds(): string[];
+    /**
+     * 作废一条配对通道：本地删密钥 + 告诉中继"这条别再转给我了" + 通知上层。
+     *
+     * **本端没有记录时同样要发 `session-leave`**（复核 R1①）。这是"主机重启之后"的出口：
+     * PSK 随进程没了，中继却还留着会话并继续把手机的密文转过来。若这里因为
+     * `!has(id)` 直接 return（第一版就是这么写的），中继永远不知道该删这条会话，
+     * 手机也就永远撞不上 `unknown_session` → 表现是"发什么都没反应、也不提示重新配对"，
+     * 而这是整条链路上唯一能让手机脱身的机制。
+     *
+     * 幂等：同一条通道只声明一次（`voided` 有上界，避免长会话里堆内存）。
+     * 重新配对（`peer-joined`）会清掉这条记录，所以下次作废仍能声明。
+     */
+    voidConversation(conversationId: string): void;
+    private raw;
+    private onFrame;
+    private onEncrypted;
+    /** 两次解不开就作废（与手机端"两帧解不开就丢配对"对称，避免一端永久静默）。 */
+    private noteUndecryptable;
+    private scheduleReconnect;
+    private closeSocket;
+    private emitState;
+}