dsh-mizar 0.8.6 → 0.8.8

package/README.md

@@ -135,10 +135,30 @@ DSH 自己的 Web 接口暴露出去（那是 DSH 的安全边界，插件不碰
   漂到 19391、19392，手机配对里保存的直连地址就永远失效了。现在一个进程只保留**一个**挂载：
   新挂载要等旧挂载完全释放监听之后才绑端口；网络变化导致监听地址改变时，隧道也会立刻用新
   地址重拨，并把监听端口的变化同步给隧道（否则隧道健康、手机请求却全部 502）。
+- **0.8.7 修了 0.8.6 单实例的漏洞。** 0.8.6 的注册表是模块级的，而 DSH 会在同一进程里多次
+  加载插件模块，每份副本各有一张空注册表——实测一个进程因此挂了 8 个监听（19390–19397）。
+  0.8.7 把注册表放到 `globalThis`（`Symbol.for('dsh-mizar.mount-registry')`），所有模块副本
+  共用同一个槽位，一个进程只剩一个监听。
 
 日志里对应 `relay: the tunnel has been silent for …s — redialling it`、
 `relay: the network changed — redialling the tunnel` 和 `relay: the listener moved to port …`。
 
+### 付费账户的高带宽中继（0.8.8）
+
+付费账户的隧道现在会跟着订阅走：App 知道账户是否付费，插件不知道，所以由 App 调
+`relay.set` 请求电脑把隧道移到账号中继（`dshmizar-1.shirazu-nagisa.com`）；免费账户
+仍走 `dshmizar.shirazu-nagisa.com`，登录/登出或订阅到期时会自动切回。
+
+- 隧道令牌不变 ⇒ 房间不变，**已配对关系不受影响**，只是断开重拨。
+- 选择持久化在插件状态目录（`relay-override.json`，600），重启后继续生效。
+- 插件只接受两个公共中继，自建 `relay.url` 时该能力不出现；旧宿主回 `NOT_IMPLEMENTED`，
+  旧客户端不会调用，行为完全不变。
+- 切换前插件广播 `relay.changed`，其它已配对设备会更新保存的中继地址；离线的手机下次
+  连接时会用同一房间尝试另一个公共中继自愈。
+- 连接面板里的「高带宽服务器 / 免费版服务器」现在按**实际所在中继**显示，不再只看账户等级。
+
+协议细节（`relay.set`、`host.info.relay`、`relay.changed`）见 `docs/protocol-v1.md`。
+
 ### 对话只传总结
 
 一页历史里只保留这些：你的提问、每一轮的 `turn/start` 和 `turn/end`、每个 `step/start`

package/lib/bridge/index.d.ts

@@ -14,6 +14,27 @@ export interface MethodContext {
 }
 /** A wire method implementation. */
 export type MethodHandler = (payload: unknown, context: MethodContext) => Promise<unknown>;
+/**
+ * Where this computer's tunnel currently points, as a phone reads it.
+ *
+ * `baseURL` is the address a phone should dial for this room (the relay origin
+ * plus `/r/<room>`), and is `null` until the relay has assigned a room.
+ */
+export interface HostRelayState {
+    /** The canonical relay origin the tunnel dials. */
+    readonly url: string;
+    /** The room the relay assigned, once connected. */
+    readonly room: string | null;
+    /** The base URL a phone should dial, or `null` before the first welcome. */
+    readonly baseURL: string | null;
+}
+/** Move this computer's tunnel between the public relays, or report where it is. */
+export interface HostRelayControl {
+    /** Read the current relay facts. */
+    current(): HostRelayState;
+    /** Remember and apply a new relay; the caller has already checked the allowlist. */
+    set(url: string): Promise<HostRelayState>;
+}
 /** What the bridge needs from its host to answer `host.info`. */
 export interface HostFacts {
     readonly hostId: string;
@@ -35,6 +56,14 @@ export interface HostFacts {
      * the second justifies a phone giving up on the direct route.
      */
     readonly authorities?: () => readonly string[];
+    /**
+     * Relay control, when this host may be moved between the two public relays.
+     *
+     * Absent for a self-hosted relay: there is no account tier to move between,
+     * so `relay.set` is not in the method table and an old-style host answers
+     * `NOT_IMPLEMENTED` exactly as it would for any other method it does not know.
+     */
+    readonly relay?: HostRelayControl;
 }
 /**
  * Build the method table for one plugin mount.

package/lib/bridge/index.js

@@ -21,7 +21,8 @@ import { modelCatalog, selectModel } from './models.js';
 import { permissionCatalog, setPermissionPreset } from './permissions.js';
 import { archiveSession, listWorkspaces } from './workspaces.js';
 import { cancelSession, createSession, listSessions, promptSession, renameSession, sessionActivity, sessionMessages, sessionStats, } from './sessions.js';
-import { parseUploadBegin, parseUploadChunk, UploadStore } from './uploads.js';
+import { parseUploadBegin, parseUploadChunk, PromptReplayGuard, UploadStore } from './uploads.js';
+import { canonicalRelayURL, isSelectableRelayURL } from '../relay/selection.js';
 /**
  * Translate any thrown value into a wire-coded failure.
  * @param handler - the raw implementation.
@@ -288,6 +289,13 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
             root: join(facts.home, 'uploads'),
             attachmentsRoot: join(facts.home, 'attachments'),
         });
+    // A prompt that carries attachments is retried with the same requestId when
+    // its answer is lost. That is safe only while the request is identical: DSH
+    // deduplicates by (session, requestId), so the same key with different
+    // content must be refused before it can borrow the first answer. Ported
+    // from XEPX2's PR #2.
+    const replayGuard = new PromptReplayGuard();
+    const relay = facts.relay;
     const table = {
         /**
          * Host identity and protocol facts.
@@ -306,7 +314,32 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
             home: facts.home,
             protocolVersion: facts.protocolVersion,
             ...(facts.authorities === undefined ? {} : { addresses: facts.authorities() }),
+            ...(relay === undefined ? {} : { relay: relay.current() }),
         }),
+        /**
+         * Move this computer's tunnel to the free or the paid relay.
+         *
+         * The phone asks because only the phone knows the account tier; the host
+         * owns the allowlist and the persistence so a paired device cannot point
+         * this computer's tunnel at an arbitrary server. The tunnel credential is
+         * unchanged, so the room is unchanged and every existing pairing survives;
+         * what changes is the address a phone dials, and the answer carries it.
+         *
+         * Additive, so no protocol version bump: an old host answers
+         * `NOT_IMPLEMENTED`, which is how the app knows to keep its current relay.
+         */
+        ...(relay === undefined
+            ? {}
+            : {
+                'relay.set': async (payload) => {
+                    const requested = requireString(payload, 'url', 'relay.set');
+                    const canonical = canonicalRelayURL(requested);
+                    if (canonical === null || !isSelectableRelayURL(canonical)) {
+                        throw new MethodError('MALFORMED_FRAME', 'relay.set: payload."url" must be the free or the paid relay');
+                    }
+                    return relay.set(canonical);
+                },
+            }),
         /** Every session DSH would list, newest activity first. */
         'session.list': async () => listSessions(ctx),
         /**
@@ -347,6 +380,11 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
             const before = fields?.['beforeSeq'];
             const after = fields?.['afterSeq'];
             const sessionId = requireString(payload, 'sessionId', 'session.messages');
+            // A delegated child is not addressable as a session: the host refuses the
+            // read with `session/agent-busy` unless the child is named through its
+            // parent. The phone knows the lineage from `session.list` and sends it
+            // back here, so the address can be rebuilt on the way in.
+            const parentSessionId = optionalString(payload, 'parentSessionId');
             const explicit = typeof after === 'number' && Number.isFinite(after) ? after : undefined;
             // `null` is the phone saying it holds nothing -- a reinstall, a cleared
             // cache. Silence is not that claim: it is a request with no cursor, which
@@ -355,7 +393,7 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
             const remembered = holdsNothing || explicit !== undefined
                 ? undefined
                 : delivery?.deliveredThrough(context.deviceId, sessionId);
-            return sessionMessages(ctx, sessionId, typeof limit === 'number' ? limit : undefined, typeof before === 'number' ? before : undefined, explicit ?? remembered);
+            return sessionMessages(ctx, sessionId, typeof limit === 'number' ? limit : undefined, typeof before === 'number' ? before : undefined, explicit ?? remembered, parentSessionId);
         },
         /**
          * The running turn's compact process detail.
@@ -414,6 +452,15 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
             if (text === undefined && attachmentIds.length === 0) {
                 throw new MethodError('MALFORMED_FRAME', 'session.prompt: payload."text" must be a non-empty string when no attachments are given');
             }
+            const requestId = optionalString(payload, 'requestId');
+            if (attachmentIds.length > 0 && requestId !== undefined) {
+                replayGuard.check(context.deviceId, sessionId, requestId, {
+                    text,
+                    mode,
+                    clientTimeZone: optionalString(payload, 'clientTimeZone'),
+                    attachmentIds,
+                });
+            }
             const attachments = attachmentIds.length === 0
                 ? []
                 : await uploadStore.resolveForPrompt(context.deviceId, sessionId, attachmentIds);
@@ -422,7 +469,7 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
                 ...(text === undefined ? {} : { text }),
                 ...(attachments.length === 0 ? {} : { attachments }),
                 mode,
-                requestId: optionalString(payload, 'requestId'),
+                requestId,
                 clientTimeZone: optionalString(payload, 'clientTimeZone'),
             });
         },
@@ -445,6 +492,14 @@ export function createMethodTable(ctx, facts, broker, push, delivery, uploads) {
         'upload.finish': async (payload, context) => uploadStore.finish(context.deviceId, requireString(payload, 'uploadId', 'upload.finish')),
         /** Discard a half-sent upload and its bytes. */
         'upload.abort': async (payload, context) => uploadStore.abort(context.deviceId, requireString(payload, 'uploadId', 'upload.abort')),
+        /**
+         * The attachment limits as this host enforces them.
+         *
+         * Additive and optional: a client may hardcode the documented numbers and
+         * never call this, but one that asks first survives a host that tunes
+         * them. Ported from XEPX2's PR #2.
+         */
+        'upload.capabilities': async () => uploadStore.capabilities(),
         /** Interrupt the running turn. */
         'session.cancel': async (payload) => cancelSession(ctx, requireString(payload, 'sessionId', 'session.cancel')),
         /** Rename a session. */

package/lib/bridge/private-directory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Create (if needed) and secure one staging directory for the current user.
+ *
+ * The directory is created first when absent, because the ACL reset below is
+ * what makes it private — creating it already-secured avoids a window in which
+ * an inherited-ACL directory exists.
+ *
+ * @param path - the directory to create and secure.
+ * @throws when the directory cannot be created or its ACL cannot be secured
+ *   and verified; the caller must not write bytes into it afterwards.
+ */
+export declare function makePrivateDirectory(path: string): Promise<void>;

package/lib/bridge/private-directory.js

@@ -0,0 +1,97 @@
+/**
+ * Secure a staging directory so only the current user can reach it.
+ *
+ * Ported from XEPX2's PR #2 (`src/attachments/private-directory.ts`), which
+ * guarded its attachment staging area; this module uses it for the same job on
+ * the `upload.*` staging roots. `mode: 0o700` is enough on POSIX, but Windows
+ * ignores it: a fresh directory under the user profile inherits grants
+ * (SYSTEM, Administrators, the user) that `chmod` cannot remove. The OS answer
+ * is to reset the ACL to exactly one rule for the current SID — and to verify
+ * the reset afterwards rather than trust it.
+ *
+ * The verification is the point. Writing bytes into a directory whose ACL did
+ * not actually tighten would be silent exposure, so the script re-reads the
+ * ACL and fails unless it sees the protection flag, exactly one rule, and that
+ * rule naming the current user. Every failure path throws before the caller
+ * writes a byte.
+ *
+ * The parent directory (the plugin's state home, never TEMP itself) is left
+ * untouched, and no elevation is requested: if the current user cannot secure
+ * its own directory, staging is refused, not de-scoped.
+ *
+ * @module dsh-mizar/bridge/private-directory
+ */
+import { spawn } from 'node:child_process';
+import { chmod, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+// Current-user SID, not localized account-name parsing. The path is passed as
+// data in the child environment, not interpolated into PowerShell source.
+const WINDOWS_ACL = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$path = $env:MIZAR_PRIVATE_UPLOAD_DIRECTORY
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl = New-Object System.Security.AccessControl.DirectorySecurity
+$acl.SetOwner($sid)
+$acl.SetAccessRuleProtection($true, $false)
+$inheritance = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+$propagation = [System.Security.AccessControl.PropagationFlags]::None
+$allow = [System.Security.AccessControl.AccessControlType]::Allow
+$rights = [System.Security.AccessControl.FileSystemRights]::FullControl
+$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($sid, $rights, $inheritance, $propagation, $allow)
+$acl.AddAccessRule($rule)
+$directory = [System.IO.DirectoryInfo]::new($path)
+$directory.SetAccessControl($acl)
+$check = $directory.GetAccessControl()
+if (-not $check.AreAccessRulesProtected) { throw 'Private upload ACL was not protected' }
+$rules = $check.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])
+if ($rules.Count -ne 1) { throw 'Private upload ACL has an unexpected rule count' }
+foreach ($entry in $rules) {
+  if ($entry.IdentityReference.Value -ne $sid.Value) {
+    throw 'Private upload ACL contains an unexpected principal'
+  }
+}
+`;
+/**
+ * Create (if needed) and secure one staging directory for the current user.
+ *
+ * The directory is created first when absent, because the ACL reset below is
+ * what makes it private — creating it already-secured avoids a window in which
+ * an inherited-ACL directory exists.
+ *
+ * @param path - the directory to create and secure.
+ * @throws when the directory cannot be created or its ACL cannot be secured
+ *   and verified; the caller must not write bytes into it afterwards.
+ */
+export async function makePrivateDirectory(path) {
+    await mkdir(path, { recursive: true });
+    if (process.platform !== 'win32') {
+        await chmod(path, 0o700);
+        return;
+    }
+    // Windows chmod cannot remove inherited ACL grants. Use the OS-supplied
+    // Windows PowerShell, with no profile, no shell interpolation and no pipes.
+    const executable = join(process.env['SystemRoot'] ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(WINDOWS_ACL, 'utf16le').toString('base64')], {
+            windowsHide: true,
+            stdio: 'ignore',
+            env: { ...process.env, MIZAR_PRIVATE_UPLOAD_DIRECTORY: path },
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error('Private upload ACL setup timed out'));
+        }, 15_000);
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('exit', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error('Cannot secure private upload directory ACL'));
+        });
+    });
+}

package/lib/bridge/sessions.d.ts

@@ -72,9 +72,13 @@ export declare function sessionStats(ctx: Context, sessionId: string): Promise<S
  * @param afterSeq - the log position the caller already holds; only records
  *   after it travel. Ignored together with `beforeSeq`, because a page paged
  *   backwards is not a page of new records.
+ * @param parentSessionId - the parent of a delegated child. Supplying it is what
+ *   makes a child's history readable at all: without it the host refuses the
+ *   read outright (`session/agent-busy`), because a child is not addressable as
+ *   a session. See {@link logAddress}.
  * @returns the page, or no records when the session is unknown.
  */
-export declare function sessionMessages(ctx: Context, sessionId: string, maxMessages?: number, beforeSeq?: number, afterSeq?: number): Promise<SessionMessagesResult>;
+export declare function sessionMessages(ctx: Context, sessionId: string, maxMessages?: number, beforeSeq?: number, afterSeq?: number, parentSessionId?: string): Promise<SessionMessagesResult>;
 /** One page of a session's log. */
 export interface SessionMessagesResult {
     readonly sessionId: string;

package/lib/bridge/sessions.js

@@ -457,6 +457,19 @@ function turnOf(event) {
  * answer this way, not for one that is merely slow.
  */
 const FOLLOW_TIMEOUT_MS = 30_000;
+/**
+ * Address one session's log, as a child when its parent is known.
+ *
+ * @param sessionId - the session whose log is being read.
+ * @param parentSessionId - the parent of a delegated child, or absent for an
+ *   ordinary conversation (and for a fork, which is a session of its own).
+ * @returns the address to send.
+ */
+function logAddress(sessionId, parentSessionId) {
+    return parentSessionId === undefined
+        ? { kind: 'session', sessionId }
+        : { kind: 'subagent', parentSessionId, childSessionId: sessionId, mode: 'unknown' };
+}
 /**
  * The log cut, from the opening frame of `session/follow`.
  *
@@ -485,17 +498,17 @@ const FOLLOW_TIMEOUT_MS = 30_000;
  * leak that only shows up after an hour of use.
  *
  * @param ctx - a context observing `ctx.typertGateway`.
- * @param sessionId - the session to open.
+ * @param address - the durable address to open; see {@link logAddress}.
  * @returns the cursor, or `null` when the host would not answer this way.
  */
-async function followCursor(ctx, sessionId) {
+async function followCursor(ctx, address) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), FOLLOW_TIMEOUT_MS);
     try {
         const iterable = await streamRemote(ctx, {
             namespace: 'session',
             method: 'follow',
-            args: { request: { address: { kind: 'session', sessionId } } },
+            args: { request: { address } },
             signal: controller.signal,
         });
         const iterator = iterable[Symbol.asyncIterator]();
@@ -584,10 +597,13 @@ async function projectionsCut(ctx, sessionId) {
  * @param sessionId - the session to read.
  * @param maxMessages - how many messages to ask for; absent uses the host default.
  * @param beforeSeq - the exclusive upper bound, for paging backwards.
+ * @param parentSessionId - the parent of a delegated child; absent reads the
+ *   session as a session. See {@link logAddress}.
  * @returns the page, or `null` when the session has no log to read.
  */
-async function readLogPage(ctx, sessionId, maxMessages, beforeSeq) {
-    const cut = (await followCursor(ctx, sessionId)) ?? (await projectionsCut(ctx, sessionId));
+async function readLogPage(ctx, sessionId, maxMessages, beforeSeq, parentSessionId) {
+    const address = logAddress(sessionId, parentSessionId);
+    const cut = (await followCursor(ctx, address)) ?? (await projectionsCut(ctx, sessionId));
     if (cut === null) {
         // No cut, no page: the session has no log to read.
         return null;
@@ -597,7 +613,7 @@ async function readLogPage(ctx, sessionId, maxMessages, beforeSeq) {
         method: 'page',
         args: {
             request: {
-                address: { kind: 'session', sessionId },
+                address,
                 throughSeq: cut,
                 // The lower bound. Without it a page starts at the beginning of the log,
                 // which for a session with any history means a conversation view made
@@ -631,10 +647,14 @@ async function readLogPage(ctx, sessionId, maxMessages, beforeSeq) {
  * @param afterSeq - the log position the caller already holds; only records
  *   after it travel. Ignored together with `beforeSeq`, because a page paged
  *   backwards is not a page of new records.
+ * @param parentSessionId - the parent of a delegated child. Supplying it is what
+ *   makes a child's history readable at all: without it the host refuses the
+ *   read outright (`session/agent-busy`), because a child is not addressable as
+ *   a session. See {@link logAddress}.
  * @returns the page, or no records when the session is unknown.
  */
-export async function sessionMessages(ctx, sessionId, maxMessages, beforeSeq, afterSeq) {
-    const page = await readLogPage(ctx, sessionId, maxMessages, beforeSeq);
+export async function sessionMessages(ctx, sessionId, maxMessages, beforeSeq, afterSeq, parentSessionId) {
+    const page = await readLogPage(ctx, sessionId, maxMessages, beforeSeq, parentSessionId);
     if (page === null) {
         return { sessionId, asOfSeq: null, records: [], hasMore: false };
     }

package/lib/bridge/uploads.d.ts

@@ -15,6 +15,22 @@ export declare const UPLOAD_LIMITS: {
     /** Most images one prompt may carry. */
     readonly images: 4;
 };
+/**
+ * Resource quotas the staging area enforces on top of the documented limits.
+ *
+ * The per-prompt limits bound one message; these bound the desktop. Ported
+ * from XEPX2's PR #2. `reservedBytes` is the sum of what live uploads have
+ * declared; the reservation ends when the upload completes (its bytes then
+ * become an attachment, bounded at prompt time) or expires.
+ */
+export declare const UPLOAD_QUOTAS: {
+    /** Largest total of declared-but-unreceived bytes across all live uploads. */
+    readonly reservedBytes: number;
+    /** Most uploads in flight, across every device. */
+    readonly active: 100;
+    /** Most uploads in flight for one device. */
+    readonly perDevice: 10;
+};
 /**
  * Media types DSH accepts as image content.
  *
@@ -33,6 +49,8 @@ export interface UploadBeginRequest {
     readonly name: string;
     readonly mediaType: string;
     readonly byteSize: number;
+    /** Lowercase hex SHA-256 of the full payload, when the client declares it. */
+    readonly sha256?: string;
 }
 /** `upload.chunk` arguments after validation. */
 export interface UploadChunkRequest {
@@ -54,6 +72,19 @@ export interface UploadFinishResult {
     readonly mediaType: string;
     readonly byteSize: number;
 }
+/** What `upload.capabilities` answers. */
+export interface UploadCapabilities {
+    readonly chunkBytes: number;
+    readonly imageBytes: number;
+    readonly fileBytes: number;
+    readonly promptBytes: number;
+    readonly attachments: number;
+    readonly images: number;
+    readonly expiresSeconds: number;
+    readonly imageMediaTypes: readonly string[];
+    /** Whether the host verifies a client-declared SHA-256. */
+    readonly sha256: boolean;
+}
 /**
  * One finished upload, as the session bridge consumes it.
  *
@@ -90,6 +121,18 @@ export interface UploadStoreOptions {
     readonly chunkBytes?: number;
     /** Clock override, used by tests to age an upload without sleeping. */
     readonly now?: () => number;
+    /** Largest total of declared bytes across live uploads (tests shrink this). */
+    readonly maxReservedBytes?: number;
+    /** Most uploads in flight across every device (tests shrink this). */
+    readonly maxActiveUploads?: number;
+    /** Most uploads in flight for one device (tests shrink this). */
+    readonly maxDeviceUploads?: number;
+    /**
+     * Whether `begin` secures the staging roots before writing (tests pass
+     * `false` so a hundred cases do not each spawn the ACL tooling; the real
+     * behavior has its own test).
+     */
+    readonly secureRoots?: boolean;
 }
 /**
  * Read `upload.begin`'s payload.
@@ -160,6 +203,11 @@ export declare class UploadStore {
      * @param options - where uploads live and how long they last.
      */
     constructor(options: UploadStoreOptions);
+    /**
+     * The limits a client should obey, as this store enforces them.
+     * @returns the capability record `upload.capabilities` answers with.
+     */
+    capabilities(): UploadCapabilities;
     /**
      * Begin one upload.
      *
@@ -234,3 +282,43 @@ export declare class UploadStore {
      */
     resolveForPrompt(deviceId: string, sessionId: string, attachmentIds: readonly string[]): Promise<PromptAttachment[]>;
 }
+/**
+ * Refuses a `requestId` reused for a different attachment prompt.
+ *
+ * DSH deduplicates prompts by session and request id: the same key always
+ * returns the first answer. For a text prompt that is the client's own
+ * idempotency choice; for a prompt that carries attachments, the key plus the
+ * content is the contract — the same retry must carry the same text, the same
+ * attachments in the same order, the same mode and timezone, from the same
+ * device. Anything else is either a client bug or an attempt to borrow another
+ * request's acceptance, and it is refused rather than second-guessed.
+ *
+ * The ledger is memory-only and bounded: at most 1000 keys globally, 100 per
+ * device, each forgotten 30 minutes after it was last seen — the same bounds
+ * XEPX2's PR #2 chose, for the same reason: a restart is allowed to forget,
+ * because DSH's own persistence is the final guard against duplicates.
+ */
+export declare class PromptReplayGuard {
+    #private;
+    /**
+     * @param now - the clock, overridable for tests.
+     */
+    constructor(now?: () => number);
+    /**
+     * Record one attachment prompt, refusing a key reused with different content.
+     *
+     * @param deviceId - the authenticated device.
+     * @param sessionId - the target session.
+     * @param requestId - the client's idempotency key.
+     * @param content - everything that makes this prompt this prompt.
+     * @throws MethodError `ATTACHMENT_INVALID` when the key was seen with a
+     *   different device or content.
+     * @throws MethodError `UPLOAD_LIMIT_REACHED` when the ledger is full.
+     */
+    check(deviceId: string, sessionId: string, requestId: string, content: {
+        readonly text?: string;
+        readonly mode: 'queue' | 'steer';
+        readonly clientTimeZone?: string;
+        readonly attachmentIds: readonly string[];
+    }): void;
+}