DSH Performance Guard

DSH Performance Guard is a DeepSeek Harness Host + Web Client plugin for diagnosing long-session, UI-rendering, background-request, tool-task, watcher, timer, and third-party plugin-group pressure. It provides reversible profile isolation and measured before/after verification.

Version: 0.3.0

Capabilities

• A 60-second browser check with per-second FPS, Long Task, Event Timing, Layout Shift, Resource Timing, DOM size, and ConversationSnapshot-open-plus-two-paints session readiness.
• Host process CPU, RSS, heap, excess event-loop delay, and Node active-resource counts for watchers, timers, and child-process resources.
• DSH-native tools/execute, llm/stream, and session/event observations during an active check: tool duration/failures, model duration/first chunk/cache tokens, and broad session-event categories.
• Content-free long-session structure: event, turn, message, tool call/result, assistant chunk, and compaction counts.
• Explicit measurement coverage: foreground/background time, generated/uploaded/accepted/invalid/rejected/evicted events, Host/FPS coverage, and sampler overhead.
• A per-second timeline aligning browser, Host, tool, model, and session activity.
• A/B validity gates for session, duration, session size, coverage, browser capabilities, viewport, environment versions, and workload fingerprints.
• Reversible third-party plugin isolation with a stable half-set suggested by default, exact isolated-set reporting, and history baseline selection.
• Persisted multi-run campaigns with at least three valid indexed pairs, one predeclared primary metric, paired-difference Student 95% confidence intervals, bias-corrected paired Hedges' g, and conservative improved / regressed / no-effect / inconclusive outcomes. Manual campaigns never receive a high confidence label.
• Cross-restart plugin bisection guidance that tests an improving half, then a measured no-effect complement, and identifies one plugin only after repeated significant improvement. Non-monotonic or underpowered results stop as inconclusive.
• A Recovery Center that inventories incomplete, unverified, and rollback-incomplete profile transactions without exposing filesystem paths. Cleanup is offered only for an incomplete safe profile with an exact transaction ownership marker.
• Redacted local JSON and static HTML reports for both individual benchmarks and aggregate campaigns, including methodology, confidence intervals, effect size, tested sets, environment, activity, and comparison details.

Install

pnpm install
pnpm run build
dsh plugin --profile web add link:$(pwd)

Restart DSH Web and open Settings → Performance Guard. After an npm release:

dsh plugin --profile web add dsh-performance-guard

Workflow

1. Open the target session and start a 60-second baseline.
2. Reproduce the same session switching, scrolling, tool-card expansion, and tool execution that feels slow.
3. Inspect findings, timeline, Host activity, and measurement coverage.
4. In Repeated experiments, select a valid baseline, plugin pool, primary metric, and three, five, or seven runs per arm. Complete the remaining baseline runs with the same workload.
5. Create the campaign's isolation profile, restart with the generated command, and explicitly collect each candidate run after the same session is ready.
6. Follow the persisted next step: recurse into an improving half or test the no-effect complement. Return to the source profile before creating each new isolation profile. Inconclusive and regressed steps never auto-narrow.
7. Export the aggregate campaign JSON/HTML, inspect Recovery Center when a transaction needs attention, or use the existing rollback flow.

DSH exposes no in-shell restart API. The plugin returns an exact launch command and never terminates DSH or auto-starts a retest before the workload is ready. Between bisection steps it also returns the source-profile launch command; the next isolation action stays disabled until that source Profile is active. Cancelling a campaign atomically disables its linked automatic retest marker but never deletes or silently rolls back the generated Profile.

Safety and transactions

Safe mode creates $DSH_HOME/profiles/<profile>-perf-safe-<id>, copies profile metadata, links the existing node_modules, and adds a final overlay for selected eligible Loader entries. It writes a prepare journal before creating files, persists an optimization-owned marker immediately after directory creation, and writes a separate completion marker last. Startup preserves every still-present incomplete or replaced directory for Recovery Center review. User-triggered cleanup delegates to the existing rollback primitive and is enabled only when the canonical target directory and exact ownership marker match. The source profile is unchanged.

Direct disable writes a durable backup and prepare journal before atomically replacing cordis.patch.yml. Profile changes and rollback share a cross-process transaction lock; persisted transitions use expected-state compare-and-set checks. State, backup, patch, and restore writes fsync file data and containing-directory metadata. Symlinked patch/backup targets are refused. Rollback also verifies the post-change SHA-256 and stops instead of overwriting a newer user edit. Startup reconciliation completes or reverses interrupted transactions.

Evidence policy

• Suspected: a risk metric or process resource is abnormal without isolation evidence.
• Correlated: timing overlap or one or more comparable manual A/B improvements for the exact isolated group.
• Confirmed: reserved for repeatable controlled scripted workloads. Version 0.3.0 multi-run statistics improve confidence but manual checks never upgrade to confirmed causation.

Ordinary Resource Timing cannot reliably identify an originating plugin. A plugin bundle URL only proves bundle loading, not later CPU or render ownership. Watcher and timer counts are process-level. Campaign runs are paired by server-issued repeatIndex, but repeated manual work in one session can remain autocorrelated, so confidence is capped at moderate. Specific attribution therefore requires exact group isolation and repeated narrowing, and remains correlated rather than controlled evidence.

Privacy

The Client ring is capped at 5,000 events and 8 MiB. Host sampling runs only during a check, and the plugin excludes its own /api/performance-guard/* traffic from Resource Timing.

The plugin does not collect or export prompts, responses, DOM text, raw session IDs, tool arguments/results, request paths/bodies/headers, cookies, credentials, environment-variable values, or raw session-log bodies. Reports retain plugin names/versions, tool names, and model provider/model/purpose because those identifiers are necessary for diagnosis. Runtime fingerprints contain only software/browser versions, platform/architecture, CPU count, total memory, viewport, and DPR. Resource domains and session identifiers are hashed before persistence.

Benchmarks, campaigns, and transaction records stay under $DSH_HOME/performance-guard. The ordinary history retains 50 benchmarks; benchmark IDs referenced by retained campaigns are pinned so campaign evidence is not orphaned. Reports are generated and downloaded locally and are never uploaded automatically.

Lifecycle and boundaries

Host routes/listeners, Client slots, locale dictionaries, styles, observers, RAF callbacks, timers, and event-loop monitors are Fiber-owned. POST routes require loopback transport, JSON, explicit same-origin browser metadata, and an ephemeral process token. Finish, cancel, or unload clears transient sampling state.

The plugin does not register model tools, add Agent context/tokens, monkey-patch the DOM/network/timer/subprocess APIs, rewrite third-party source, replace the DSH conversation renderer, or claim to repair core virtualization.

Development

pnpm run typecheck
pnpm test
pnpm run build
pnpm pack --dry-run
DPG_TEST_URL=http://127.0.0.1:<port> pnpm run verify:ui
PNPM_BIN=/absolute/path/to/pnpm pnpm run verify:packed-profile
PNPM_BIN=/absolute/path/to/pnpm pnpm run verify:release

UI verification covers desktop, a 320px container, 390×844, 200% zoom, keyboard tab navigation, destructive-confirmation focus, start/cancel behavior, and root overflow. verify:packed-profile builds a real tarball, installs it into a temporary DSH_HOME, validates the packed manifest/client graph/bundle bytes, and starts a short-lived loopback-only Web profile for browser boot. Set DSH_CLI, NODE_BIN, PNPM_BIN, and CHROME_BIN explicitly outside the installed macOS layout. Registry access is required for the clean install stage unless CI supplies a populated pinned pnpm store; the boot and browser stages allow loopback traffic only.

Requires Node.js 22.19+ or 24+, and targets DSH 0.1.1-rc.2+.