Diagnostics

dsh-local-link keeps a small local history of failed connection and UI actions. It exists so an npm installation can be debugged without enabling verbose logs or reproducing the problem under a debugger. It is not telemetry and has no upload path.

What is recorded

An event is created only when an operation fails or a request is rejected:

• generating a one-time connection code;
• consuming an expired, replaced, reused, or malformed invitation;
• opening the gateway from an unpaired browser or an invalid network/Host boundary;
• reaching the loopback Harness HTTP server or event WebSocket;
• rewriting the authenticated Harness index;
• copying the one-time link;
• renaming or revoking a paired device;
• recovering an unreadable diagnostics file.

Successful starts, requests, pairing, link copies, renames, revocations, and ordinary UI clicks are never recorded. Diagnostics are event-driven: there is no sampling loop, heartbeat, analytics client, or remote collector.

The QR popover separately checks every two seconds whether its visible one-time invitation has been consumed. That short-lived status check runs only while the popover is open and neither reads nor writes diagnostics.

Retention and I/O

• Default file: ~/.dsh/local-link/diagnostics.json.
• Default retention: the latest 15 events; configurable from 5 through 200.
• Settings view: the latest 12 events.
• Repeated identical events inside a five-second burst are stored once.
• Opening Settings → Local access reads the report once. Refresh is the only repeated UI read.
• The file is written only for a retained failure, an explicit clear, or migration away from unreadable/obsolete entries.
• Background event writes use an atomic temporary-file replacement and fail soft; diagnostics cannot take down pairing or proxy traffic. The explicit Clear action reports a persistence failure instead of claiming that the on-disk report was removed.

Set diagnosticsEnabled: false to stop retaining new events. Clear immediately removes the retained history.

Privacy contract

Every event contains only:

• a random event ID;
• an ISO timestamp;
• warn or error severity;
• a stable event code;
• optional context restricted to reason, method, and requestKind.

Context strings are stripped of control characters and limited to 80 characters. The store rejects unknown event codes and removes obsolete or malformed entries when it loads.

Reports never contain pairing tokens, cookies, credentials, IP addresses, device or session IDs, device names, URLs, request paths, exception messages, stack traces, prompts, conversations, workspace names, or project files. Client-side reporting accepts only three fixed error codes and cannot submit arbitrary text.

Collect a report

1. Reproduce the failed action once.
2. Open Settings → Local access → Diagnostics.
3. Click Refresh if the panel was already open during reproduction.
4. Inspect the newest code and timestamp.
5. Click Copy report.
6. Review the JSON before attaching it to an issue.

The copied report wraps the retained events with a schema version and export timestamp:

{
  "schemaVersion": 1,
  "exportedAt": "2026-08-28T00:00:00.000Z",
  "events": [
    {
      "id": "generated-event-id",
      "at": "2026-08-28T00:00:00.000Z",
      "level": "error",
      "code": "HTTP_UPSTREAM_ERROR",
      "context": { "requestKind": "root" }
    }
  ]
}

Event reference

Code	Trigger	First check
PAIRING_GENERATION_FAILED	Generate another code could not produce an invitation or QR image.	Confirm the desktop Harness process is healthy, then retry once.
PAIRING_REJECTED	The invitation was expired, replaced, or already consumed.	Generate a new code; each invitation is one-use.
PAIRING_INVALID	The phone submitted malformed pairing data or device state could not be saved.	Generate a new code; if it repeats, inspect file permissions for ~/.dsh/local-link/.
REQUEST_REJECTED	Source-address or Host validation rejected the LAN request.	Confirm both devices use the same private network and the QR URL contains the computer's current private address.
AUTH_REQUIRED	An unpaired browser opened a protected gateway page.	Pair that browser with a fresh QR/link; direct :3088 access is intentionally rejected.
HTTP_UPSTREAM_ERROR	The gateway could not reach Harness on 127.0.0.1:3080.	Confirm dsh web is running and upstreamOrigin matches its port.
BROWSER_AUTH_HANDOFF_FAILED	Harness returned an invalid browser-authentication handoff target.	Confirm the installed Harness version is supported and restart dsh web.
INDEX_REWRITE_ERROR	The returned Harness index did not match the supported boot contract.	Confirm the installed Harness version appears in the compatibility matrix and restart dsh web.
WS_REJECTED	A WebSocket upgrade failed trust, authorization, or path validation.	Re-pair the browser and verify no proxy rewrites the URL.
WS_UPSTREAM_ERROR	The gateway could not open the loopback Harness event socket.	Confirm the desktop Harness process is still running and reload the paired browser.
CLIPBOARD_COPY_FAILED	The browser refused or failed to copy the one-time link.	Grant clipboard permission or select and copy the displayed link manually.
DEVICE_REVOKE_FAILED	A requested device revocation failed.	Refresh the device list and retry; inspect local state-file permissions if it repeats.
DEVICE_RENAME_FAILED	A requested device rename failed.	Refresh the device list and retry with a non-empty name.
DIAGNOSTICS_STATE_RESET	The previous diagnostics file was unreadable and was replaced safely.	Usually no action; inspect disk health or permissions if it returns.

Maintainer rules

• Record failures and rejections only; do not add success or lifecycle noise.
• Add a stable code instead of persisting exception messages.
• Add context only through SAFE_CONTEXT_KEYS in src/diagnostics.ts.
• Never add request headers, URLs, filesystem paths, identifiers, user-entered text, or user content.
• A diagnostics write failure must never block pairing or proxy traffic.
• Update this reference and the privacy/retention tests whenever an event changes.