dsh-zen-remote 1.1.15 → 2.0.0

package/lib/types/share-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared "which sessions have remote enabled" table (2.0.0 remote-session
+ * groundwork): pure logic plus a small JSON file under the DSH data dir. The
+ * server opens/closes remote per session; a paired desktop client may close
+ * but never open; everything else here exists to make one rule survivable
+ * across restarts — an idle shared session must put itself away.
+ *
+ * Three clock rules, all driven by the caller:
+ * - `touch()` marks activity (turn start/end, message sent, approval or
+ *   question answered — opening a session to look at it is NOT activity).
+ * - `setBusy()` marks running/waiting; busy sessions never idle out and the
+ *   idle clock restarts from the moment busy ends.
+ * - everything else is derived: `sweep()` closes whatever has been idle past
+ *   `idleHours`, `remainingMs()` reports the countdown.
+ *
+ * Accessibility crosses generations: subagent and fork sessions are reachable
+ * when any ancestor is shared, without themselves appearing in the table
+ * (`isAccessible` walks `parentOf`).
+ *
+ * Persistence is deliberately dumb: one JSON file, rewritten atomically
+ * (tmp + rename) after every operation that changes what the file would say,
+ * synchronously, because a crash right after "share" must not silently
+ * un-share. `busy` is never persisted — after a restart every session is
+ * idle by definition until the caller says otherwise.
+ */
+/** One row of the table, as `list()` reports it. */
+export interface ShareEntry {
+    sessionId: string;
+    /** When remote was first enabled (repeat `share` does not move it). */
+    sharedAt: number;
+    /** Last activity the caller announced via `touch()` (or busy-end). */
+    lastActivityAt: number;
+    /** Memory-only: never persisted, always false after a restart. */
+    busy: boolean;
+}
+/** Why a session left the table. `manual` = server-side close, `client` =
+ * desktop-client close, `idle` = automatic idle shutdown. */
+export type UnshareReason = 'manual' | 'client' | 'idle';
+export type ShareEvent = {
+    type: 'shared';
+    sessionId: string;
+} | {
+    type: 'unshared';
+    sessionId: string;
+    reason: UnshareReason;
+};
+export interface ShareStoreOptions {
+    /** Absolute path of the persistence file. */
+    file: string;
+    /** Idle budget in hours; must be 0 < x ≤ 8760, anything else falls back
+     * to 48. Changeable later via `setIdleHours`. */
+    idleHours: number;
+    /** Injectable clock; defaults to Date.now. */
+    now?: () => number;
+}
+export interface ShareStore {
+    /** Enable remote for a session. True when newly shared; false when it was
+     * already shared (sharedAt stays put, lastActivityAt refreshes to now). */
+    share(sessionId: string): boolean;
+    /** Remove a session from the table. True when it was actually removed. */
+    unshare(sessionId: string, reason: UnshareReason): boolean;
+    /** Whether the session itself is in the table (inheritance NOT applied). */
+    isShared(sessionId: string): boolean;
+    /** Whether the session is reachable for remote access: itself shared, or
+     * some ancestor within 16 `parentOf` hops shared. */
+    isAccessible(sessionId: string, parentOf: (id: string) => string | undefined): boolean;
+    /** Announce activity. No-op for sessions not in the table. */
+    touch(sessionId: string): void;
+    /** Announce running/waiting state. No-op for sessions not in the table.
+     * busy true→false restarts the idle clock from now. */
+    setBusy(sessionId: string, busy: boolean): void;
+    /** Close every expired session now. Returns the closed ids, sorted. */
+    sweep(): string[];
+    /** undefined when not shared; Infinity while busy; otherwise how many ms
+     * are left before this session would idle out (never negative). */
+    remainingMs(sessionId: string): number | undefined;
+    /** Snapshot of the table, sharedAt ascending (ties broken by id). */
+    list(): ShareEntry[];
+    /** Replace the idle budget. Invalid values are ignored; takes effect
+     * immediately for subsequent sweep/remainingMs calls. */
+    setIdleHours(hours: number): void;
+    /** Observe share/unshare events. Listener errors are swallowed. Returns
+     * an unsubscribe function. */
+    subscribe(listener: (event: ShareEvent) => void): () => void;
+}
+export declare function createShareStore(options: ShareStoreOptions): ShareStore;
+//# sourceMappingURL=share-store.d.ts.map

package/lib/types/share-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-store.d.ts","sourceRoot":"","sources":["../../src/share-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAA;IACtB,kEAAkE;IAClE,IAAI,EAAE,OAAO,CAAA;CACd;AAED;6DAC6D;AAC7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAElE,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ;qDACiD;IACjD,SAAS,EAAE,MAAM,CAAA;IACjB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB;+EAC2E;IAC3E,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,0EAA0E;IAC1E,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;IAC1D,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACpC;yDACqD;IACrD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IACtF,8DAA8D;IAC9D,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;2DACuD;IACvD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/C,uEAAuE;IACvE,KAAK,IAAI,MAAM,EAAE,CAAA;IACjB;uEACmE;IACnE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAClD,qEAAqE;IACrE,IAAI,IAAI,UAAU,EAAE,CAAA;IACpB;6DACyD;IACzD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;kCAC8B;IAC9B,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CAC7D;AAgDD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA6OvE"}

package/lib/types/virtual-id.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reversible virtual ids for sessions and workspaces the sub-client surfaces
+ * locally while their real records live on a relay server (T23b-1). The UI
+ * only ever sees `zr~<serverId>~<original id>`; the interceptor maps those
+ * back to the original ids before a call travels, and maps server-returned
+ * ids back to virtual form on the way out.
+ *
+ * The mapping is deliberately a PURE function of (serverId, id), not a
+ * session-table lookup: every shared session of one server gets the same
+ * virtual id whether or not this process ever opened it, so result rewriting
+ * needs no state. Parsing validates the fixed skeleton (`zr~` + the 8 hex
+ * chars `loadServerId` mints, relay-server.ts) and keeps the remainder
+ * VERBATIM — the original id may contain any characters, including `~`, so
+ * nothing after the second separator is interpreted.
+ *
+ * A local DSH id can never collide with the prefix: real session ids are
+ * `session-<uuid>` and workspace ids are bare uuids.
+ */
+/** The fixed prefix every virtual id starts with. */
+export declare const VIRTUAL_ID_PREFIX = "zr~";
+/** The two halves {@link fromVirtual} recovers from a virtual id. */
+export interface VirtualIdParts {
+    serverId: string;
+    id: string;
+}
+/** Build the virtual form of one server-side session or workspace id. */
+export declare function toVirtual(serverId: string, id: string): string;
+/**
+ * Parse one virtual id back into its halves, or `undefined` for anything
+ * that does not match the skeleton. Strict on the parts that carry meaning:
+ * the literal prefix, exactly 8 lowercase hex server id chars, and the
+ * separating `~` after them. The remainder is not validated — any string,
+ * including the empty one, is a legal original id.
+ */
+export declare function fromVirtual(id: unknown): VirtualIdParts | undefined;
+/** True when {@link fromVirtual} would parse this value. */
+export declare function isVirtual(id: unknown): boolean;
+//# sourceMappingURL=virtual-id.d.ts.map

package/lib/types/virtual-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-id.d.ts","sourceRoot":"","sources":["../../src/virtual-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,QAAQ,CAAA;AAMtC,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,EAAE,EAAE,MAAM,CAAA;CACX;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CASnE;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAE9C"}

package/lib/virtual-id.js

@@ -0,0 +1,52 @@
+/**
+ * Reversible virtual ids for sessions and workspaces the sub-client surfaces
+ * locally while their real records live on a relay server (T23b-1). The UI
+ * only ever sees `zr~<serverId>~<original id>`; the interceptor maps those
+ * back to the original ids before a call travels, and maps server-returned
+ * ids back to virtual form on the way out.
+ *
+ * The mapping is deliberately a PURE function of (serverId, id), not a
+ * session-table lookup: every shared session of one server gets the same
+ * virtual id whether or not this process ever opened it, so result rewriting
+ * needs no state. Parsing validates the fixed skeleton (`zr~` + the 8 hex
+ * chars `loadServerId` mints, relay-server.ts) and keeps the remainder
+ * VERBATIM — the original id may contain any characters, including `~`, so
+ * nothing after the second separator is interpreted.
+ *
+ * A local DSH id can never collide with the prefix: real session ids are
+ * `session-<uuid>` and workspace ids are bare uuids.
+ */
+/** The fixed prefix every virtual id starts with. */
+export const VIRTUAL_ID_PREFIX = 'zr~';
+/** The server id half: exactly the 8 lowercase hex chars relay-server.ts
+ * mints (`randomBytes(4).toString('hex')`). */
+const SERVER_ID_PATTERN = /^[0-9a-f]{8}$/;
+/** Build the virtual form of one server-side session or workspace id. */
+export function toVirtual(serverId, id) {
+    return `${VIRTUAL_ID_PREFIX}${serverId}~${id}`;
+}
+/**
+ * Parse one virtual id back into its halves, or `undefined` for anything
+ * that does not match the skeleton. Strict on the parts that carry meaning:
+ * the literal prefix, exactly 8 lowercase hex server id chars, and the
+ * separating `~` after them. The remainder is not validated — any string,
+ * including the empty one, is a legal original id.
+ */
+export function fromVirtual(id) {
+    if (typeof id !== 'string' || !id.startsWith(VIRTUAL_ID_PREFIX))
+        return undefined;
+    const rest = id.slice(VIRTUAL_ID_PREFIX.length);
+    // The shortest legal remainder is `<8 hex>~` — 9 chars with the separator
+    // at index 8. Anything shorter cannot carry a server id.
+    if (rest.length < 9 || rest[8] !== '~')
+        return undefined;
+    const serverId = rest.slice(0, 8);
+    if (!SERVER_ID_PATTERN.test(serverId))
+        return undefined;
+    return { serverId, id: rest.slice(9) };
+}
+/** True when {@link fromVirtual} would parse this value. */
+export function isVirtual(id) {
+    return fromVirtual(id) !== undefined;
+}
+//# sourceMappingURL=virtual-id.js.map

package/lib/virtual-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-id.js","sourceRoot":"","sources":["../src/virtual-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAA;AAEtC;+CAC+C;AAC/C,MAAM,iBAAiB,GAAG,eAAe,CAAA;AAQzC,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,EAAU;IACpD,OAAO,GAAG,iBAAiB,GAAG,QAAQ,IAAI,EAAE,EAAE,CAAA;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,EAAW;IACrC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC;QAAE,OAAO,SAAS,CAAA;IACjF,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,yDAAyD;IACzD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,SAAS,CAAA;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAA;IACvD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AACxC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,OAAO,WAAW,CAAC,EAAE,CAAC,KAAK,SAAS,CAAA;AACtC,CAAC"}

package/llms.txt

@@ -1,20 +1,23 @@
 # dsh-zen-remote
 
-> Complete mobile plugin for DeepSeek Harness (DSH), shipped as ONE npm package: app-shell mobile UI (two-level page stack, session-list home, reworked composer, gestures, phone-local attachment upload) + pairing-code/device-token gateway for public-internet access behind your own reverse proxy + installable PWA + offline service worker + real Web Push agent-done notifications.
+> One DeepSeek Harness plugin, two roles, shipped as ONE npm package. The **host** role: app-shell mobile UI (two-level page stack, session-list home, reworked composer, gestures, phone-local attachment upload), pairing-code/device-token gateway for public-internet access behind your own reverse proxy, installable PWA, real Web Push, and per-session sharing to paired desktops. The **client** role: runs inside another DSH desktop app and surfaces the host's remote-enabled sessions in its own sidebar — history, live progress, messages, approvals, terminals; everything executes on the host over zen-remote's relay protocol.
 
 ## Key facts
-- One npm package `dsh-zen-remote`, MIT. Install: `dsh plugin add dsh-zen-remote`, then restart `dsh web`.
-- Declares `dsh.bundle.patch` → `cordis.patch.yml` with three insert rows, all self-contained (no manual profile patching needed):
-  `dsh-zen-remote` (host upload route + browser client via `dsh.client`), `dsh-zen-remote-gateway` (`lan-gate.mjs`), `dsh-zen-remote-push` (`dsh-push.mjs`).
-- Interface half: browser client bundle (`lib/client.js`, registered as `__ModuleLoader__.load({id:"dsh-zen-remote"})`); <768px app shell, 768–1023px drawer, ≥1024px strict no-op. Host route `POST /_dsh/mobile-nav/upload` writes phone-picked files into the session workspace's `.dsh-uploads/`.
-- Gateway half: standalone child-process Node gateway (`lib/lan-gate-server.cjs`, Node stdlib + one runtime dep `web-push`), listens on `127.0.0.1:3088`, sits behind a user-run TLS-terminating reverse proxy (nginx/Caddy/Lucky). Device identity = pairing token (cookie `lg_device`), not source IP. Reverse-proxies paired devices to DSH on `127.0.0.1:3080`; DSH webserver untouched. HTML injection adds the PWA manifest link, service-worker bootstrap, `viewport-fit=cover`, shell CSS, randomUUID polyfill.
-- Push half: two legs. Event leg (always on, debounce-exempt) fires when a tool is waiting on approval (`approval/asked` with no `approval/decided` within 1.5s) or `ask_user_question` is unanswered; turn end (`agent/turn-stopping`, configurable) is OPT-IN via `DSH_PUSH_TURN_END` and top-level-only. Also registers the model-callable `push_notify` tool. All deliver through the gateway's local `/pwa/push/send` (VAPID + aes128gcm).
-- Env: `LAN_GATE_PORT` (3088), `LAN_GATE_HOST` (127.0.0.1), `LAN_GATE_TARGET_PORT` (3080), `LAN_GATE_RATE_LIMIT` (120), `LAN_GATE_TRUSTED_PROXIES`, `LAN_GATE_VAPID_SUBJECT`, `DSH_PUSH_EVENTS`, `DSH_PUSH_DEBOUNCE_MS`, `DSH_PUSH_SUMMARY`, `DSH_PUSH_TOOL`. Same keys (lowerCamelCase) in `~/.dsh/lan-gate.config.json`.
-- Admin (local-direct-connection only, 403 otherwise): `http://127.0.0.1:3088/lan-gate/admin` — generate pairing codes, rename/set-kind/revoke devices, trigger a push.
-- Security: 8-char one-time pairing code (10 min TTL), 5-wrong-code lockout (15 min), revocable per-device tokens, 120 req/min per resolved client IP, admin surface rejects any request carrying `X-Forwarded-*`.
+- One npm package `dsh-zen-remote`, MIT. Install: DSH Plugins page → Add plugin → `dsh-zen-remote` → Enable now (desktop app and web UI), or `dsh plugin --profile web add dsh-zen-remote` on a headless web service (the CLI requires `--profile` and refuses `--profile desktop`); by hand: one dependency line in `~/.dsh/profiles/desktop|web/package.json` + `pnpm install` + `dsh-zen-remote` appended to that file's `dsh.profile.bundles`. Then restart DSH. The composition layer is a single row `dsh-zen-remote`; the main entry loads the gateway and push sub-plugins itself according to the `role` config. Old `dsh-zen-remote-gateway` / `dsh-zen-remote-push` rows are warned and skipped — do not re-add them (a second gateway would fight over port 3088).
+- Roles: `role: host` (default) runs mobile UI + gateway child + push + session sharing + the relay server; `role: client` runs the relay client and the sidebar/session-page remote parts only — no gateway, no push, no phone UI. Anything that is not exactly `client` degrades to host.
+- Config lives in the DSH Plugins page settings block; per field the first legal value wins: environment variable > plugin row settings > `~/.dsh/lan-gate.config.json` > default. Restart-required fields (`role`, `port`, `host`, `targetPort`, `rateLimit`, `trustedProxies`, `vapidSubject`, `lang`, push fields) reload the plugin row automatically; everything else is volatile and read live.
+- Host sharing: per-session remote toggle from four places (sidebar session "…" menu, title-row icon with confirm, settings list, the phone session info card's remote access switch); idle sleep after 48h without session activity (running/waiting sessions exempt, viewers don't count); auto-share new sessions (opt-in; relay-created sessions always auto-share); subagent/fork sessions follow the parent.
+- Pairing codes are role-bound: web app devices (phones/browsers, see all sessions) redeem on the pairing page; desktop app devices pair from the client's settings page via `/lan-gate/pair/claim-desktop` and only ever reach the relay prefix (everything else 403 `relay-only`).
+- Relay protocol (prefix `/_dsh/zen-remote/relay`): `GET ping`, `POST v1/handshake` (relay protocol version + DSH interface fingerprints — version mismatch refuses; fingerprint mismatch annotates and degrades; the answer carries `serverName`/`deviceName`), `POST v1/invoke`, `POST v1/stream` (NDJSON, ping heartbeats that carry the current `serverName`/`deviceName`, `unshared` error line on close), `POST v1/event-result`, `POST v1/http` (the plain-HTTP long tail: only `changes.summary` / `changes.diff`, GET only, query normalized to `sessionId`/`seq`/`index`, dispatched in-process through the host's shared `/api` handler), `POST v1/upload` (a remote session's non-image attachments: raw byte stream, share-checked, query normalized to `sessionId`/`name`, 100 MiB cap answers 413, 8 concurrent per device answers 429, dispatched in-process through the same shared handler), `POST v1/unshare`, `POST v1/device/name` (gateway-handled rename of the CALLING device's own record — paired desktop clients only, never forwarded to DSH; 1–40 chars). Access control is a per-method allowlist (`src/relay-access.ts` RELAY_METHODS, mirrored by intercept.ts CLIENT_METHOD_FIELDS, pinned identical by test); global reads (`session/control`, `session/list`, `workspace/follow`) and the @-mention candidates are output-filtered (candidates list only shared sessions); `session/modelCatalog` is a parameter-less global read whose `failures` array the server empties; `dsh-session:` references are scanned wherever DSH would inject them — prompt content, queue-edit content, every string of a `commands/execute` call — and a reference naming an unshared session refuses the call. Approval/question events forward first come, first served; the relay never answers on the client's behalf (an unshared session's approval waits for the server UI or the next subscription), and unshared sessions' notification-type events are never forwarded.
+- Remote extras: a remote session can attach non-image files — the sub-client's own backend wraps the host's `fetchRoutes` upload entry and streams the bytes through `v1/upload` (the 100 MiB cap is the relay's own, an over-limit pick is refused locally on the client, slow links are bounded by a 300 s client-side timeout; export is disabled remotely instead — menu item hidden, backend 403 for virtual ids). The model picker in a remote session lists the SERVER's catalog (groups named "server name · group name"); local sessions list only local models, the last server groups survive relay offline, and virtual groups never appear in local settings such as the vision router (boundary: a server-created session that never sent a message shows the local default model).
+- Gateway auth chain: device token (Bearer) → gateway marker headers `x-zen-remote-via/-role/-device` + `x-zen-remote-secret` (per-load shared secret, `LAN_GATE_RELAY_SECRET`, not externally settable, re-verified with timingSafeEqual) → per-method share-table check. Admin API stays loopback-only; forwarded requests may read status but never mutate.
+- Admin surface: the dsh-zen-remote settings block (pairing with role picker, device list with rename/set-role/revoke, push test, shares list). `/lan-gate/admin` is now just a notice pointing there.
+- Trust model: a paired desktop client is a TRUSTED DEVICE — server-user terminal without sandbox/approval gates, file previews not contained to the session dir, session creation in any workspace. "Shared only" constrains session data (lists, history, events are refused/filtered server-side; @ candidates list only shared sessions; references in messages, queue edits and slash commands naming an unshared session refuse the call), not the machine.
+- Env: `LAN_GATE_PORT` (3088), `LAN_GATE_HOST`, `LAN_GATE_TARGET_PORT` (auto-discovered), `LAN_GATE_RATE_LIMIT` (120), `LAN_GATE_TRUSTED_PROXIES`, `LAN_GATE_VAPID_SUBJECT`, `LAN_GATE_LANG`, `LAN_GATE_RELAY_SECRET` (auto), `DSH_PUSH_*`, `DSH_PUSH_APPROVAL_GRACE_MS`. Same keys (lowerCamelCase) in `lan-gate.config.json`.
+- Security: 8-char one-time role-bound pairing code (10 min TTL), 5-wrong-code lockout, revocable per-device tokens (kills connections + push subscription), 120 req/min per client IP for unpaired requests.
+- Known limits: remote sessions disable export (menu item hidden, backend 403 for virtual ids); changes summary/diff work remotely but the "open on the server machine" entries (open / reveal in Finder / open in app) are hidden there; with dsh-better-sidebar installed, its file surfaces (file browser, editor, git, tasks, bottom workbench, floating windows) are hidden in remote sessions because they act on the CLIENT machine's own files — so remote sessions have no sidebar file browser (it takes over the host's "Files" tab) and file links in chat or deliverables open an empty right column; @ candidates are truncated to 50 by the host BEFORE share filtering (a shared session can be missing from the list on a session-heavy server); third-party plugins' non-standard endpoints are not forwarded — their tools run on the server and are unaffected, what breaks is UI calling the plugin's own backend with a session id (better-sidebar, handled as above); both ends need zen-remote 2.0.x; server switch-back or workspace-id reuse needs a page reload; several DSH windows at once (including the desktop backend opened in a browser) can misjudge which session is currently open — closed-remote hiding can fire at the wrong moment and worst case dismiss an open session to the home page. Dev only (see AGENTS.md hard constraints): same-machine testing must reach the gateway over a LAN IP (loopback = local-direct, skips token checks) — normal two-machine use is unaffected.
 
 ## Docs
-- README.md (English, install + config), README.zh-CN.md (same in Chinese), AGENTS.md (repo guide), LICENSE.
-- docs/remote-access.md(.en.md) — gateway detail: reverse proxy, pairing, env, admin API, push, security boundary.
-- docs/interface.md — interface detail: breakpoints, debug badge, safe-area system, compatible plugins.
-- .ai/ — AI Project OS state, memory, decisions, tasks.
+- README.md (English, install + config + migration + security model), README.zh-CN.md (same in Chinese), AGENTS.md (repo guide), LICENSE.
+- docs/remote-access.md(.en.md) — gateway detail: reverse proxy, roles and pairing, env, admin API, relay protocol, security boundary.
+- docs/interface.md — interface detail: breakpoints, settings block and remote parts, debug badge, safe-area system, compatible plugins.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-zen-remote",
-  "version": "1.1.15",
-  "description": "把 DeepSeek Harness 变成手机 App：移动端界面重排（两级页面栈、会话列表主屏、composer 重排、手势、附件上传）+ 配对码认证网关 + PWA 安装 + 真 Web Push。Complete mobile plugin for DeepSeek Harness (DSH): app-shell mobile UI, pairing-code gateway for public-internet access behind your own reverse proxy, installable PWA, offline service worker, and real Web Push agent-done notifications.",
+  "version": "2.0.0",
+  "description": "一个插件、两种角色：主服务端把 DeepSeek Harness 变成手机能安全访问的 PWA（移动端界面、配对码网关、Web Push），并把选定会话共享给已配对的桌面端；子客户端在另一台 DSH 桌面端的侧边栏里远程使用这些会话。One DSH plugin, two roles: the host turns DeepSeek Harness into a phone-reachable PWA (mobile UI, pairing-code gateway behind your own reverse proxy, Web Push) and shares chosen sessions to paired desktops; the client uses those sessions remotely from another DSH desktop app's sidebar.",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",
@@ -36,7 +36,10 @@
     "README.md",
     "README.zh-CN.md",
     "LICENSE",
-    "!docs/push-policy.md"
+    "!docs/push-policy.md",
+    "!docs/SPEC.md",
+    "!docs/spike-relay.md",
+    "!docs/images"
   ],
   "dsh": {
     "bundle": {
@@ -78,20 +81,21 @@
     "web-push": "^3.6.7"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-client-ui-layout": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-session": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-session-log-export": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-session-query": ">=0.1.0-rc.7 <0.2.0-0 || >=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "react": "^18.2.0",
-    "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0",
-    "@deepseek-ai/dsh-workspace": ">=0.1.1-rc.0 <0.2.0-0 || >=0.1.2-rc.0 <0.2.0-0"
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-log-export": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-workspace": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "*",
+    "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-host-webserver": {
@@ -111,38 +115,44 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/cosmokit": "^1.8.3",
-    "@deepseek-ai/dsh-api-remotes": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-workspace-controller": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-brand": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-connection": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-store": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-session": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-scope": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-log-export": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-query": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-stats": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-token-meter": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-crypto": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-workspace": "0.1.2-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-log-export": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-query": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-stats": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-timeout": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-crypto": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-workspace": "0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^26.2.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
@@ -151,7 +161,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs",
     "verify": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "test": "node --test \"test/*.test.cjs\" && node scripts/check-sunk-viewport.mjs && node scripts/check-keyboard-avoid.mjs && node scripts/check-attach-upload.mjs && node scripts/check-share-image.mjs && node scripts/check-upload-endpoint.mjs && node scripts/check-host-shadow.mjs && node scripts/check-compat-store.mjs && node scripts/check-client-externals.mjs && node scripts/check-info-sheet-stacking.mjs && node scripts/sync-doc-version.mjs --check",
+    "test": "node --test \"test/*.test.cjs\" && node scripts/check-sunk-viewport.mjs && node scripts/check-keyboard-avoid.mjs && node scripts/check-attach-upload.mjs && node scripts/check-share-image.mjs && node scripts/check-upload-endpoint.mjs && node scripts/check-host-shadow.mjs && node scripts/check-compat-store.mjs && node scripts/check-settings-form.mjs && node scripts/check-shares.mjs && node scripts/check-client-externals.mjs && node scripts/check-info-sheet-stacking.mjs && node scripts/sync-doc-version.mjs --check",
     "version": "node scripts/sync-doc-version.mjs && git add README.md README.zh-CN.md"
   }
 }

package/scripts/build-client.mjs

@@ -49,7 +49,9 @@ const resolveChild = (parent, rel) => {
   return joined === '.' ? '' : joined
 }
 
-// Dependency-first topological order from the entry.
+// Dependency-first topological order from the entry. The client tsconfig's
+// rootDir is `src` (so src/client-data can sit beside src/client), which puts
+// the emit under .client-build/client/.
 const visited = new Set()
 const order = []
 const visit = (file) => {
@@ -62,7 +64,7 @@ const visit = (file) => {
   }
   order.push(file)
 }
-visit('index.js')
+visit('client/index.js')
 
 const modules = order
   .map((file) => {
@@ -89,7 +91,7 @@ const wrapped = [
   '  return module.exports;',
   '}',
   'var module = { exports: {} };',
-  '__modules["index.js"](__localRequire, module, module.exports);',
+  '__modules["client/index.js"](__localRequire, module, module.exports);',
   'return module.exports; } });',
   '',
 ].join('\n')

package/scripts/check-host-shadow.mjs

@@ -78,6 +78,19 @@ const require = createRequire(import.meta.url)
 //   devDep then.
 // - npm-published tarballs contain no node_modules, so this shadow only
 //   exists on dev machines where the plugin is link-installed.
+// NOTE (T42-fix): src/fingerprint.ts resolves @deepseek-ai packages at
+// runtime — deliberately through the HOST process entry FIRST
+// (process.argv[1]), with the plugin location as a fallback — so a
+// link-installed plugin no longer fingerprints its own devDependency copies.
+// What argv[1] actually is, per launch shape (T23b2-fix3): under the npm
+// CLI it is a SYMLINK (…/bin/dsh into the real install), and fingerprint.ts
+// realpaths it before anchoring — walking node_modules upward from the bin
+// directory would find nothing and silently fall through to this plugin's
+// copies. Under the desktop App it lives inside app.asar (not exercised in
+// practice). Those resolutions are createRequire(...).resolve()
+// calls whose specifier this file's scan regex cannot see, and the runtime
+// priority makes a plugin-copy shadow the fallback, not the read — so no
+// SHADOW_ALLOWED entry is registered for them.
 const SHADOW_ALLOWED = ['@deepseek-ai/dsh-tools', '@deepseek-ai/dsh-session']
 
 // Packages that must never exist in this plugin's node_modules at all: DSH
@@ -86,8 +99,12 @@ const SHADOW_ALLOWED = ['@deepseek-ai/dsh-tools', '@deepseek-ai/dsh-session']
 const BANNED_PACKAGES = ['@deepseek-ai/dsh-client-runtime', '@deepseek-ai/dsh-host-apiproxy']
 
 // The files the host half actually loads. lib/share-export.js is statically
-// imported by lib/index.js, so it is part of the same runtime graph.
-const HOST_ENTRY_FILES = ['dsh-push.mjs', 'lan-gate.mjs', 'lib/index.js', 'lib/share-export.js']
+// imported by lib/index.js; lib/fingerprint.js rides the same runtime graph
+// (T42). It is listed here because the scan's whole purpose is watching
+// THIS graph for @deepseek-ai imports: its own package resolutions are
+// createRequire(...).resolve() calls the regex cannot see, but any literal
+// import someone adds there later WILL be caught.
+const HOST_ENTRY_FILES = ['dsh-push.mjs', 'lan-gate.mjs', 'lib/index.js', 'lib/share-export.js', 'lib/fingerprint.js']
 
 // Matches the specifier of real module statements only — `... from 'pkg'`,
 // `import 'pkg'`, `import('pkg')`, `require('pkg')` — so @deepseek-ai names