QAQ — DeepSeek Harness Launch Resilience Guard

QAQ is a launch resilience guard for DeepSeek Harness (DSH). When a disrupted profile configuration prevents DSH from starting normally — a crashed host or a red-screened Web UI — QAQ automatically restores the configuration snapshot from the last successful boot and restarts, while preserving the broken config for manual recovery.

Author: WTStarMark

Non-invasive: QAQ never edits DSH source. The guard is a standalone executable that supervises the dsh web process and reads the browser's real DOM over CDP; the backup plugin only reads configuration and never changes behavior.

What it solves

DSH's Web surface has a failure mode where the host is alive but the UI red-screens: the host process runs, the port responds, yet the browser renders Failed to load plugins. Such failures are invisible to host-process monitoring and cannot be detected by curl (the server-side HTML ships an empty , rendered client-side). The only reliable non-invasive probe is to open the page in a headless browser and read the actual DOM. QAQ's UI-detection line is exactly that.

Requirements

Node.js >= 22
A Chrome/Chromium/Edge binary on the machine (used headlessly via CDP; no Playwright/Puppeteer dependency)
The dsh command on PATH, or an explicit QAQ_DSH_CMD / --cwd

Install / Quick start

One-click (Windows): double-click bin\qaq-install.cmd (installs deps + builds), then double-click bin\qaq-web.cmd to open the interactive guard console — no commands to remember. (Chinese launcher variants: bin\qaq-web.zh.cmd / bin\qaq-install.zh.cmd.)

Or manually:

pnpm install
pnpm build   # emits a single-file executable at dist/qaq.mjs

Take over dsh web from a visible CMD window:

bin\qaq-web.cmd [--port 3080] [--yes]

Command	Purpose
`qaq dsh web [--port N] [--yes]`	supervised startup: detect host/UI failure -> count -> roll back when triggered -> restart (with anti-loop)
`qaq status`	print a summary of `~/.dsh/.qaq/state.json`
`qaq backup [--profile web]`	snapshot the current profile as last-good
`qaq restore --to [--profile web]`	restore a profile from a snapshot directory
`qaq reset --profile web`	zero the failure counters
`qaq console`	open the interactive menu (lazy launcher, same as `bin\qaq-web.cmd`)
`qaq install-plugin [--profile web]`	auto-mount the `dsh-qaq` backup plugin into a profile

Symptom	What to do
`Pre-launch self-check failed` — dsh not found	Put `dsh` on `PATH`, set `QAQ_DSH_CMD`, or pass `--cwd` pointing at the DSH checkout
`Port already in use` — port busy	Stop the other process, or pick another port: `--port N`
UI red-screens again after a rollback	Inspect the logs and the preserved bad config: `qaq console` → [7], or read `~/.dsh/.qaq/log/` (`error.log`, `access.log`, `host.log`)
Guard says `anti-loop fence is active`	A rollback already happened within the last 5 minutes. Fix the config manually (see `rolled-back/`), then `qaq reset --profile web` to clear the counters
Want to undo a rollback	`qaq restore --to --profile web` with any directory under `~/.dsh/.qaq/history/` (or `rolled-back/`)
dsh-qaq not snapshotting	The plugin only writes on a clean host settle; it does not write on a failed boot. Confirm it is listed in the profile bundles (`qaq console` → [2] shows the last snapshot) and that `install-plugin` reported success

Option	Meaning	Default
`--confirm-ms`	stable-healthy confirmation window before snapshotting	`20000`
`--ui-timeout`	max wait for the UI to settle during the L3 probe	`25000`
`--threshold`	consecutive same-kind failures that trigger a rollback	`3`
`--cwd`	working directory for the supervised `dsh` (set to the checkout for source launch)	process cwd

File	Content
`qaq.log`	everything (info + warn + error), the canonical record
`error.log`	warn/error only — grep for trouble fast
`access.log`	crash-audit trail: boot verdicts, snapshots, rollbacks, resets, plugin mounts, manual restore
`host.log`	raw supervised `dsh` stdout/stderr (mirrored to the visible window)

Path	Purpose
`src/cli.ts`	command surface + supervised loop
`src/guard.ts`	superviseBoot orchestration (host ready -> UI detect -> count/rollback)
`src/spawn-dsh.ts`	spawn dsh web, inherit env, readiness/exit tracking
`src/cdp.ts`	minimal CDP client (headless Chrome, no Playwright)
`src/detector-ui.ts`	L3 text criteria
`src/store.ts`	atomic `~/.dsh/.qaq` read/write + snapshot management + lock

dsh-qaq

安装

说明文档

QAQ — DeepSeek Harness Launch Resilience Guard

What it solves

Requirements

Install / Quick start

Commands

One-click console (`qaq console` / `bin\qaq-web.cmd`)

Operations guide

First-time setup (Windows)

Everyday use

Troubleshooting

Data locations

Supervised `dsh web` options

Detection criteria (L3, empirically verified)

State & storage (`~/.dsh/.qaq/`)

Logging (for developer troubleshooting)

Trigger & anti-loop

Reliability features

Testing

Repository layout

安装

说明文档

QAQ — DeepSeek Harness Launch Resilience Guard

What it solves

Requirements

Install / Quick start

Commands

One-click console (qaq console / bin\qaq-web.cmd)

Operations guide

First-time setup (Windows)

Everyday use

Troubleshooting

Data locations

Supervised dsh web options

Detection criteria (L3, empirically verified)

State & storage (~/.dsh/.qaq/)

Logging (for developer troubleshooting)

Trigger & anti-loop

Reliability features

Testing

Repository layout

One-click console (`qaq console` / `bin\qaq-web.cmd`)

Supervised `dsh web` options

State & storage (`~/.dsh/.qaq/`)