[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CXHAPD2ND5BW82HVFE52ES":3,"skill-same:01M7CXHAPD2ND5BW82HVFE52ES":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M7CXHAPD2ND5BW82HVFE52ES","dsh-dev",null,"Use when developing, running, or debugging BotHarness against a local DeepSeek Harness instance — the dev loop (profile install, build, restart, HMR), DSH_HOME\u002Fprofile management, the web `\u002Fapi` transport contract, plugin endpoint wiring, and diagnosing 404\u002Fconnection\u002F白屏 failures (\"works in tests, broken in DSH\"). Trigger on dsh profile, web-dev, dev server, bridge RPC, \u002Fapi 404, plugin not loading, HMR, settings\u002F模型\u002F插件页报错.","BotHarness\u002FDeepSeekBot","BotHarness","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F330270786?v=4","01M7CX37EXWM53FHAQ28JNKZTZ","01M7CX37FHA8NY5D2KXFZWV63Y",852,"MIT","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdsh-dev\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: dsh-dev\ndescription: Use when developing, running, or debugging BotHarness against a local DeepSeek Harness instance — the dev loop (profile install, build, restart, HMR), DSH_HOME\u002Fprofile management, the web `\u002Fapi` transport contract, plugin endpoint wiring, and diagnosing 404\u002Fconnection\u002F白屏 failures (\"works in tests, broken in DSH\"). Trigger on dsh profile, web-dev, dev server, bridge RPC, \u002Fapi 404, plugin not loading, HMR, settings\u002F模型\u002F插件页报错.\n---\n\n# DSH development & debugging\n\n### Empty native credential writer lock after interrupted startup (#4114)\n\nOn Windows with DSH 0.2.2-rc.1, an interrupted task-Host startup was followed by a zero-byte\n`.credentials.yaml.lock`; a normal restart refused in the required Connection Plugin with\n`atomic-write: timed out waiting for the writer lock`. The installed native atomic-write\nowner recovers a lock containing an exited PID followed by a newline, but deliberately waits\non an empty or unrecognized record. A printed login URL alone did not prove Plugin health.\nThe exact creator of the empty record was not established; this is a qualified recovery\nprocedure, not a claim that startup cancellation always causes an empty lock.\n\nPreserve the failure and inspect the installed native lock code. Establish exclusion of other\nlaunchers and recovery attempts for this same Home before checking for live or unknown users;\nhold that exclusion through the lock-identity recheck and rename, and refuse recovery if it\ncannot be established. Then prove the exact task Home has no live or unknown users and that the unchanged lock is\na canonical regular zero-byte file with one link. Record its inode and nanosecond timestamps,\nrecheck them immediately before recovery. Retain the original by renaming only that lock\nto a timestamped sibling inside the same Home. Leave credentials and preparation markers\nunchanged. Unknown ownership, redirected paths, nonempty records or changed identity refuse\nthis procedure. Restart through the qualified lifecycle, require authenticated Plugin health\nand normal native lock release, and retain the backup and metadata. This does not authorize\nautomatic lock deletion, a generic stale-lock repair, or a longer startup deadline.\n\n### CredentialKey segments and opaque identifiers\n\nThe pinned native credentials service accepts lowercase letter\u002Fdigit\u002Fhyphen key segments. An opaque application ID can contain uppercase letters or underscores: hash the exact ID for its protected-record key and bind the original identity in the payload. Lowercasing the ID can merge distinct owners. Use `modifyRecord` for writes and keep route admission separate from per-device credentials. Verify protected writes and readback through the running Host, with secret-free output.\n\n### GenUI preview browser startup diagnostics (#4030)\n\nA passing plain timeline opens the Puppeteer driver, not the Host's separate GenUI\npreview browser. Record both executable versions and the runner image before\ncomparing them. The preview uses system discovery by default; the core Plugin's\n`genuiPreviewBrowserPath` selects an absolute executable through the same Browser\nruntime and refuses an invalid explicit path. `dev-instance.mjs` and `verify-app.mjs`\naccept `--genui-preview-browser \u003Cabsolute-executable>` and apply a Patch only to that\nisolated launch. They do not change system PATH or another Profile.\n\nOrdinary CI selects the lockfile-installed Puppeteer executable for preview too,\nso the preview no longer depends on the runner image's independently updated\nsystem Chrome. Its exact executable receives a temporary AppArmor profile allowing\nuser namespaces; the workflow unloads it after stopping its owned Hosts. A quick\n`startup-sandbox` refusal is a separate setup error from `startup-timeout`; preserve\nChrome sandboxing when correcting that permission. Merely setting\n`CHROME_DEVEL_SANDBOX` did not repair the controlled Ubuntu 26 runner (#4030).\n\n`genui-preview-browser-startup-timeout` means no DevTools endpoint appeared within\nthe existing eight-second startup deadline, before CDP connection or document\nrendering. Inspect the retained bounded\u002Fredacted preview owner log; do not infer a\nrich-document rendering regression from an empty rich sample set. The verify\nworkflow's `genui_browser_diagnostic` dispatch input runs system and controlled\nbrowser journeys sequentially on the same runner; both outcomes remain required.\nNo budget increase, product retry or incident-root-cause fix is implied.\n\n### DSH 0.2.2-rc.1 qualification\n\nUse [the recurring RC workflow](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-upgrade.md) and\n[the version-specific record](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-022-rc1-upgrade.md). RC tracking\ndoes not raise the `>=0.2.0-0` admission floor, and a new pin is not runtime evidence.\nOn RC1, select the Agent model before step preparation: Inbox claim precedes the\nloop's model snapshot, while prompt assembly is already too late to change that\nstep's route. The direct Orchestrator-child wake hook preserves historical Session\ngraphs from before #2968; current Orchestrators delegate through Assignments.\nQualify current Assignment background completion and next-DM model changes separately\nfrom legacy graph restoration. Keep asynchronous application authorization before prompt admission.\nNative tool execution now dispatches batches to scoped executors; direct CLI calls\nmust omit model-step logging and verify result identity. An executor disposer leaves\nan unavailable selection, so borrowed application handles must not own its lifetime.\nReviewer schema suppression belongs to the executor's description, not the prompt\npresentation waterfall or inherited-tool restrictions. Verify packaged module loading\nand both API generations in a real Host; source-tree imports can hide missing native\ndependencies.\n\nOn Windows, a retained development-Home resource PID can be reused by an unrelated\nprocess after the task Host exits. A resulting \"Home is in use\" refusal is not proof\nthat the old Host remains alive. Inspect current process identities and the exact\nHome before recovery; never kill a process just because its PID appears in the record.\nPreserve the stale owner record and recover only the verified task-local record after\nchecking that its Host and preparation processes have exited. Retain the refusal and\nrecovery evidence separately from the product restart result.\n\n### DSH 0.2.2 center column and Bot workspace qualification (#3665)\n\nThe real 0.2.2-rc.1 Web shell adds a center-column container between the main-panel\ncontainer and the grid frame. Assuming the main slot's grandparent is the frame\nsilently refuses workspace ownership and shows the Bot-mode sidebar fallback even\nat desktop widths. Qualify the bounded old\u002Fnew structural paths using the direct\nsidebar, rightbar and overlay markers, and mark the grid's center-column child,\nnot the nested main panel. Restore markers and the exact native sidebar command\non exit. Compare the running DOM and loaded Client identity before blaming cached\nassets; Simple\u002FAdvanced is a separate device-local preference. Browser verification\ndoes not qualify an installed Desktop upgrade.\n\n### Empty tool declaration series (#3137)\n\nDSH 0.2.1-rc.3 can record a `request\u002Fheader` with `startsSeries: true` and no tools.\nLater tool additions then all become deferred during LLM route projection, and DeepSeek\nrejects the request because no immediate tool remains. The active header alone hides this:\ninspect `session.toolHistory().tools`, not only `session.requestHeader().tools`.\nFor owned Bot Sessions, the pre-step owner requests a new declaration series after an empty\nbaseline, letting the native loop persist its currently assembled tools. This also repairs\nan already-failing restored Session. Do not invent a resident tool, rewrite prior events,\nweaken tool access checks, or blame an installed Plugin from the HTTP error alone.\nThe regression uses the real native Session fold and LLM projection in\n`packages\u002Fcore\u002Ftest\u002Ftool-declaration-series.test.ts`.\n\nBotHarness is a plugin layer inside DSH: unit tests do not cover the real boot. Every trap in this skill was invisible to `pnpm test` and only appeared in a running `dsh --profile web-dev`. **Validate against the running shell, not the test suite.**\n\n## Proactive Client verification\n\nAfter every isolated launch, Client reload and relevant UI action, read the real browser console and DOM yourself before accepting the result; do not wait for Human-copied errors. Read [the Client diagnostic loop](..\u002F..\u002F..\u002Fdocs\u002Fdev\u002Fguides\u002Fclient-startup-diagnostics.md) for the agent-runnable reader, bounded attempt history, background-tab\u002Ffreshness limits and native RC1 reproductions. Treat API health, Client shell evidence and browser-control failures as separate signals. Preserve first failure and each retry; recovery by reload does not establish a fix.\n\nOrdinary localhost pages do not open the application-defined development-refresh SSE. Add `?botharness-dev-reload=1` only while iterating on Client builds, then remove it for first-run or long-request UX verification.\n\n## Prime directive: `\u002Fapi` belongs to the API gateway\n\n### Timed-question recovery Registry trap (#4066)\n\nThe installed DSH `0.2.2-rc.2` Agent Registry resolves a live Session with `get(sessionId)`;\nit does not expose `roots()`. An invented `roots()` test double hid a real post-restart answer\nrefusal. Verify the exact installed Registry and native question Service contract, and exercise\nthe original durable `continued` call after restart. A rendered card or an `open` native call\nalone does not prove recoverable continuation. Keep application source authority distinct from\nnative answer state; the question's own Bot Source Event is not a fresh Memory admission.\n\nThe web client calls `\u002Fapi\u002F\u003Cendpoint>` over plain HTTP (`fetch` + auth cookie). The route and its **single interceptor** are owned by `@deepseek-ai\u002Fdsh-api-gateway`, which claims endpoints from the **typert registry** (all native controllers register there).\n\n- **Never** call `connection.rpc.intercept('\u002Fapi', …)` from a plugin. The slot is taken; a second interceptor shadows every native API (`settings\u002Fdescribe`, `llm\u002FlistProviders`, plugins, `directoryPicker\u002Flist` …) with a plain-text `404 not found` while your own endpoints keep working.\n- Expose plugin endpoints through the gateway\u002Ftypert claim path: a `TypertRemoteService` subclass with a `typertRemote` binding and remote-method markers (SRC, no codegen). `botharness\u002F*` migrated this way in #50 (`packages\u002Fcore\u002Fsrc\u002Fbridge\u002Frpc.ts`); native `@deepseek-ai\u002Fdsh-api-*` controllers are the reference.\n- Wire contract: `POST \u002Fapi\u002F\u003Cnamespace>\u002F\u003Cmethod>` with `{ type: \"client-request\", rpcId, method, payload: { args: {…named args} } }`; `undefined` fields are rejected by the decoder. Failures come back as a `server-response` envelope (`ok:false`), not HTTP errors.\n\n## Dev loop (WSL, fnm node)\n\n### Isolated dependency copies and legacy reuse (#4135)\n\nThe launcher installs fresh owned CLI runtimes and Profile dependencies with per-command pnpm\ncopy imports. Its completion marker records helper ownership; keep these installs helper-managed.\nUnmarked existing dependencies restart read-only when the requested runtime version and Profile\nmanifest are unchanged, with the normal runtime\u002Fmodel\u002FBundle checks. Legacy reuse also compares\nrequested dependency specifiers with pnpm's installed lockfile importer; missing or divergent\ninstalled records refuse without modifying the Home. A rebuild at the same source\nlink remains usable. Changing a legacy source link, Bundle dependency or runtime version requires\na fresh `--home`; `isolated-imports-required` preserves the old data and dependencies. Failed fresh\ninstalls remain preserved rather than receiving an implicit hardlink migration. The copy option\ndoes not retroactively detach existing files. Keep the old Home for backup or explicit migration.\n\nAn interruption during copy preparation leaves `installing`, including during a normal restart.\nAfter checking the exact Home's current processes, use the ordinary launcher with the same\n`--home`, `--worktree` and `--port` plus `--recover-copy-install`. The launcher still acquires\nthe normal Home lease and refuses live or unknown owners. It only recovers a recognized\ninterrupted copy install: it checks canonical paths, refuses symlinks\u002Fjunctions, retains the\nold dependency tree and preparation records under `.botharness-copy-recovery-*` inside that\ninstallation directory, then performs a fresh copy install. Database, credentials and Profile\ndata remain in place. The launch summary lists retained quarantine paths; never remove those\ntrees without the normal shared-file\u002Fownership audit. A failure remains incomplete and may\nneed the explicit flag again. Never manually change the marker to `complete` (#4172).\n\nOn Windows, two isolated runtimes shared native Client artifact inodes. An experiment on a private\ncopy confirmed that another hardlink changes ctime and the installed DSH metadata-based artifact\nrevision without changing bytes or mtime. Removing an existing live hardlink can itself affect\nother owners, so qualify future copies instead of repairing shared files in place. The original\n`session-maybe` incident's initiator remains unproven; this is an isolation mitigation, not a claim\nthat its Client lifecycle cause is fixed. The workspace-CLI fallback remains read-only and deliberate\nsource Client rebuilds still publish normally. Details: [local development loop](..\u002F..\u002F..\u002Fdocs\u002Fclient-bridge.md#7-本地开发环路).\n\nThe reproducible build baseline is `@deepseek-ai\u002Fdsh@0.2.2-rc.1`. The launcher uses the installed local CLI or an isolated `--dsh-version \u003Cversion>` installation, accepts DSH `>=0.2.0-0` including future prereleases, creates an isolated Web Profile, links all Bundle members as dependencies, enables only the `deepseekbot` umbrella, and probes the authenticated API.\n\n```bash\ncorepack pnpm build\nnode scripts\u002Fdev-instance.mjs --home \u002Ftmp\u002Fbh-020-web --port 31967 --json\ncorepack pnpm dev:client\n```\n\nThe launch summary includes the Host PID and local login URL. For Client edits, open the local Web tab with `?botharness-dev-reload=1`: tsdown rebuilds the linked Client bundle, and the opted-in development listener refreshes the page when the RC publishes a rebuilt frame. The Desktop Client HMR stream replaces the linked `@botharness\u002Fui` Fiber; BotHarness hands off the active Bot\u002FChannel selection during replacement. The Web development listener retains a full-page refresh fallback. For Host edits, build, stop that exact PID, then start the helper again with the same home and port; Host hot replacement is disabled in the pinned RC. Follow `docs\u002Fclient-bridge.md` §7 for the complete steps and measured timings.\n\nThe helper injects a shared machine-local DeepSeek key when available; `node scripts\u002Fdev-secret.mjs check` reports its source without a value. Existing Profile credentials are another DSH source. Confirm model access with a real DM reply. `node scripts\u002Fdev-secret.mjs adopt-profile --home \u003Cexisting-DSH_HOME>` copies only the DeepSeek reference into a private local file for later isolated Profiles.\n\nBefore launch and before finishing or handing off a run, follow\n[verification resource cleanup](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-resource-cleanup.md). The detached Host\noutlives the launcher: record its ownership, then verify process exit and port release before\nremoving its Profile or worktree. Keep a running environment only under the documented handoff\nor shared QA lease.\n\n\nThe launcher holds a Home-wide preparation lock and records the running Host before verification. A live owner prevents dependency\u002FProfile changes, even on another port or Profile. After a launcher exits, its recorded lock can be recovered; a lock without ownership evidence is preserved for manual inspection. On Windows, an unrecorded legacy DSH process whose Home cannot be determined blocks preparation until it is stopped. Startup verification failures terminate the owned Host and observed descendants, wait for exit, and preserve the Profile\u002Flog; an incomplete shutdown retains ownership for recovery. Go adapters containing the exact reviewed native fix skip the local patch; unknown or ambiguous request shapes remain refusals.\n\n\nPreparation commands now wait for an IPC start signal after their independent process-group ownership has been persisted. This covers installs, builds and configuration exports. Reusing a Home checks recorded groups even after the launcher or successfully handed-off Host exits. Failure cleanup stops the parent and repeatedly rescans descendants until release or a bounded refusal. Windows permits CLI paths explicitly belonging to another managed Home; ambiguous legacy CLI ownership remains a refusal.\n\nProfile names accept only letters, digits, underscores and hyphens; missing option values and invalid ports refuse before preparation. The profiles directory, selected Profile, manifest, workspace settings and model patch must not be symbolic links.\n\nOn macOS\u002FLinux, each preparation command also inherits a unique ownership marker, persisted before its IPC start signal. Process scans use this marker to find descendants that create a new session and outlive their parents; preparation refuses and stops such leftovers, and interrupted runs block Home reuse until they exit. Environment output is never logged. This is cooperative lifecycle tracking, not OS containment: commands that deliberately clear the marker must manage and register their own resources. Windows retains parent-chain tracking; independently reparented Windows daemons are not qualified by the POSIX regression and require separate resource ownership.\n\nRestart only after both the Host process and its HTTP listener have stopped. A closed port alone does not prove shutdown. On Linux, an exited zombie may still answer a PID existence probe; lifecycle checks use its process state and still check live descendants.\n\n## DSH 0.2.1 migration contracts\n\nSource inspection of `dsh-subagent\u002Flib\u002Ftypes\u002Ftypes.d.ts` and `lib\u002Findex.js` in `0.2.1-rc.2`:\n`startActivation` replaces `start` and `startContinuable`; `delivery: 'parent'` sends the result\nto the parent, while `'caller'` returns it only to the caller. Its signal owns startup only;\ncallers that retain cancellation ownership must connect later aborts to the receipt's `dispose()`.\nThe old `settleRun` export is gone. `dsh-client-connection` also replaces the shared `operator`\nwith per-Peer identity; Owner-only Remote methods check `invocation.peer.principal.kind`.\n\n### Supporting the 0.2.0 floor while building against 0.2.1\n\nUse application adapters for both API generations rather than raising the install floor to the SDK pin. Detect `startActivation` before starting; otherwise use native `start` \u002F `startContinuable`. Never retry a failed modern operation through the legacy path. Owner checks use the trusted native principal when present, otherwise the exact legacy connection operator object, never caller-supplied identity. Resolve native Shell Plugins from the running Host. A bundled scoped file Plugin must retain the reviewed `read_image` injection patch and adapt the missing `workingDirectory` service locally to the legacy Session cwd. Do not discard that patch by blindly externalizing file tools. A preset containing 0.2.1-only Plugins also fails on the old Host before an adapter can help. Conversely, the old persona `{{cwd}}` suffix fails at conversation assembly on 0.2.1, where that variable is no longer registered; do not inject it into the common preset. The legacy workingDirectory fallback must isolate that Service before providing it; Agent Scope alone does not isolate Cordis Services. Exercise two Agents and dispose one to prove the other retains its file tools. Check the entire boot log: a disabled native dependency can leave an apparently healthy Host with missing features. The product bundles the unchanged ComputerUseRegistry as an owned child Plugin to avoid an incompatible separately installed native manifest. Qualify the same packed product on both released versions; a SemVer preflight is only admission evidence.\n\n## Profile model\n\n- Isolated `DSH_HOME` (one directory per worktree\u002Fport); profiles live in `$DSH_HOME\u002Fprofiles\u002F\u003Cname>`: `package.json` (`dsh.profile.bundles`), `cordis.yml`, user patch layer `cordis.patch.yml`, `node_modules` (our bundles via `link:`).\n- `dsh web …` initializes the **`web` template** (`dsh-base` + `dsh-web-app`); a bare `dsh --profile \u003Cnew>` initializes the minimal template (`dsh-base` only). Our `web-dev` = web template + `deepseekbot`.\n- **Always pass `DSH_HOME`** — without it commands silently target `~\u002F.dsh` and initialize profiles there.\n- `cordis.patch.yml` is the bisect tool: disable a plugin (`- id: botharness-core` \u002F `disabled: true`) or override config, no reinstall needed.\n\nA saved AX model id may disappear from the pinned native catalog. Preserve the launcher's refusal; do not misdiagnose it as a missing credential or silently rewrite the shared selection. For this task's launch only, set `BOTHARNESS_AX_MODEL` to the current catalog model (normally `deepseek-v4.1-flash`), then verify an actual DM reply. The launcher retains catalog validation and the existing private key source.\n\n## Pitfall log\n\n### Windows background command consoles (#3565)\n\nOn a detached Windows DSH Host, a console executable launched by `execFile` without\n`windowsHide: true` can time out before entering its main function. In the task-owned\nTailscale fixture, alternating the flag on the same Host produced eight timeouts out\nof eight with the default, versus eight successful status reads out of eight with\nhidden consoles; the 3000 ms timeout stayed unchanged. Child spawn\u002Fstdout\u002Fexit marks\nand native entry records separated this from Host event-loop starvation. Use hidden\nwindows for noninteractive command runners. The detached-process regression in\n`packages\u002Fcore\u002Ftest\u002Fphone-route-windows.test.ts` exercises the real default route runner.\nThis qualifies Windows process startup, not a real Tailscale daemon or macOS behavior.\n\nThe Typert SRC gateway derives accepted named arguments from the registered Service method signature. Adding a Client argument and reading it in the application owner is insufficient: a missing facade parameter is rejected as `gateway\u002Farguments-invalid` before the owner runs. Keep the facade signature and forwarding payload aligned, and replay the same authenticated `\u002Fapi` request on a rebuilt isolated Host. A domain-only test cannot detect this boundary failure (#3215).\n\nIn DSH 0.2.1-rc.3, never give two Loader rows the same id across Bundle layers. A Bundle `insert` of an existing id such as `ui-theme` makes the Loader start the last row, but native Settings (`configEditor`) composes the Profile Patch and checks the first row; every write then fails with `settings\u002Frejected: Configuration for \"ui-theme\" is overridden by a home patch or command-line overlay`. The theme Client rolls back to the stored preference without a visible error. A non-insert Patch `name` is a selector, not a rename, so a Bundle cannot replace a native Plugin row; use a Profile-local package link instead. Reproduce by clicking Settings → General → Appearance → Dark and reading the `settings\u002Fmutate` reply (#2788).\n\nNative `dsh plugin add` reconciles newly installed Bundle packages into `dsh.profile.bundles`. Installing a renamed product Bundle beside the old one is not command-only installation. For the Tobs coexistence qualification, explicitly restore the previous Bundle selection before booting; for replacement, remove the old product entry and enable Tobs. Keep the same Profile, canonical data and Patch identities, and verify composition plus writes after restart. Never infer that package installation leaves the enabled Bundle list unchanged (#2722).\n\nAn AX launch pins `agent-default-model` through a command-line Patch. On DSH `0.2.1-rc.2`, changing that default through `onboardingModel` can therefore refuse with `Configuration for \"agent-default-model\" is overridden by a home patch or command-line overlay`. This is native configuration ownership, not a Remote Host transport failure. Preserve the refusal and unchanged default; verify preset writes separately. A no-op `home-model-set` does not prove the default can change. Qualify successful default changes on an unlocked isolated Profile, without editing another session's Patch or the shared AX selection (#2500).\n\nThe `tool-subagent-list-agents: never started` preset error can be an import failure, not a missing Service. In #2932, DSH 0.2.2-alpha.2 removed `dsh-tool-subagent-control\u002Flist-agents` and registers `list_agents` in the main Plugin; 0.2.1-rc.2 still exports the separate Plugin. The Bot preset adapter imports through the running Host's Loader and mounts the legacy child only when exported. Only the exact missing legacy export is accepted; other import and activation failures propagate. Verify both versions with `scripts\u002Fverify-subagent-control.mjs`. For a source checkout, use its `tsx\u002Fesm` hook, `TSX_TSCONFIG_PATH`, and `--source` so the test does not mix built and source Scope identities.\n\nNative approval `never` means reject before the answerer waterfall, even under `danger-full-access`; it does not mean automatic approval. In #2080, combining that policy with a BotHarness Human-only permission-management exception swallowed the intended card. Top-level Bot Full Access now uses `ask` and answers ordinary requests automatically at its existing application responder; delegated Subagents keep their native policy. Verify both an ordinary action and a permission-management Human card on the real Host.\n\nOn DSH `0.2.1-rc.2`, the first-run Preview Notice can hide a shell whose Settings entry now lives under the account menu. An older verification prelude that waits for a visible `Settings` button before dismissing overlays times out although Client diagnostics report `shell-ready`. Preserve the failure capture, dismiss the actual `Continue` dialog, then address the observed `Bot mode` or `Account menu` entry by accessible name. This qualifies shell navigation only; it does not establish a model reply or native IM delivery.\n\nRestored application runtime work can run before an undeclared native Service Provider loads. In #2056 a real held-draft Host restart resumed an Orchestrator before `ctx.credentials` existed and published a model-readiness failure, although the same configured key worked after startup. BotHarness now declares `credentials` in its required `inject` dependencies. A real Cordis\u002FLocalCredentialProvider regression starts the Consumer before the Provider and verifies readiness is not attempted until that Provider is available. Do not hide this race with a credential fallback, polling delay or suppressed failure; use the Service dependency lifecycle.\n\nWhen a DSH-side bug or trap is diagnosed, **record it here (or in the playbook) in the same change**. Entries:\n\n| # | Trap | Symptom | Cause \u002F fix |\n| - | ---- | ------- | ----------- |\n| 1 | `\u002Fapi` single interceptor | Native APIs 404 `not found`; custom plugin endpoint works | **Resolved in #50**: api-gateway owns the slot and claims endpoints from the typert registry; `botharness\u002F*` now registers a `TypertRemoteService` (SRC markers). Do not reintroduce `connection.rpc.intercept('\u002Fapi', …)`. |\n| 2 | Half-booted instance | UI loads, every API 404 | restart raced\u002Flost plugin layer; restart again and verify with the cookie probe (playbook §1) |\n| 3 | `pkill -f \"\u003Cpattern>\"` self-match | command dies with no output | the wrapper's own cmdline contains the pattern; use `[x]` trick (`pkill -f \"[n]o-open\"`) |\n| 4 | Shell variables eaten in nested wrappers | `$VAR`\u002F`$(…)` come out empty | write a script file for anything with variables; avoid inline `$` in loop commands |\n| 5 | `DSH_HOME` omitted | profiles\u002Finstalls land in `~\u002F.dsh` | always set `DSH_HOME` for every `dsh` command |\n| 6 | Installed inventory is not loaded code | Package Manager manifests can change while old Plugins still run | For #1980, read module-load snapshots on active Registry callbacks; capture installed composition before staging. Cordis 4.0.4 exposes `FiberState` as an ambient const enum, which cannot be imported with this repo's `verbatimModuleSyntax`; the adapter pins its verified ACTIVE value (2), covered by runtime qualification. |\n| 6 | Standard decorators not emittable | vitest `SyntaxError` on raw `@Remote`; tsdown passes decorators through untouched | this toolchain (oxc\u002Ftsdown) can't compile TC39 decorators — write the `@deepseek-ai\u002Fdsh-typert-protocol\u002Fremote-methods` descriptor manually (`version: 1`, `invocation: { kind: \"direct\" }`) and lock its shape with a test (#50) |\n| 7b | Agent created without an agent preset gets an **empty tool layer** | A BotHarness Orchestrator\u002FAssignment Agent can only call the tools its own setup registered (e.g. `channel_send`, `report_to_orchestrator`) — no file\u002Fbash\u002Fshell tools, so the model reports \"no tools\" | `dsh-agent-presets`: every session must join a preset (`CreateAgentOptions.meta.agentPreset`); an agent published without one \"resolves against the empty global layer\". Pass the bot's preset or a shipped default (`standard`) when creating agents |\n| 7 | `sidebar.panellist` row has no toggle or geometry seam | Clicking the active entry re-runs `selectPanel(id)` (a no-op), so the mode never exits; the shell row spans the full content box, 2px wider per side than the 新会话 row | Own the row from inside the glyph: render a wrapper span, target the shell button with `button:has(.bh-panel-glyph)` (`width: auto; margin-inline: 2px` = native `.newSession` insets), and while active render an `inset: 0` hit layer whose `onClickCapture` stops React propagation and calls `ctx.layout.selectPanel(null)` (`layout` must be declared in the plugin's `inject`) |\n| 8 | `Menu` `autoFocus` + `portal` drops the initial focus | The menu renders but no row is focused (arrow keys dead, submenu closed) | The primitive's autoFocus effect runs before its placement re-render clears the list's `visibility: hidden`, so `.focus()` on the hidden row is ignored. Re-focus the placed list in a `setTimeout(0)` after mount (see `ChannelMoveMenu`) |\n| 9 | Layout shift inside `dragstart` kills the native drag | `dragstart` fires, then a bare `dragend` with no drop; puppeteer's `mouse.drag()` hangs waiting for `dragIntercepted` | Chromium aborts the gesture when the `dragstart` dispatch synchronously moves the source row (e.g. revealing a `display: none` drop zone via React's discrete-event flush). Arm layout-taking drop surfaces one task later (`setTimeout(0)`); absolutely-positioned markers are safe synchronously. Diagnosed on the empty-section drop zone (#56 follow-up) |\n| 10 | Bundle member promoted to a top-level bundle | Boot fails with `duplicate loader entry id: botharness-core` | The `deepseekbot` umbrella patch already inserts core, client, browser and computer. Link all five packages into the profile, but keep only `deepseekbot` under `dsh.profile.bundles`; do not pass any member through `dsh plugin add`. |\n| 11 | `dsh.client.inject` is bundle grouping, not service ordering | Client bundle fails to import: `bundle … loaded without registering \"\u003Cpkg>\" via __ModuleLoader__.load`, often preceded by `duplicate factory registration` for a native module | Listing another plugin's package in `dsh.client.inject` makes the client-modules loader bundle that package **again** in your entry's group; a module that already registered cannot register twice. Keep `inject: []` for cross-package service dependencies and express them only with `ctx.inject(['\u003Cservice>'])` at runtime. Diagnosed in #164. |\n| 12 | Typert descriptor survives Host HMR | A client using a newly added RPC field gets `args fields do not match the descriptor: unexpected \"\u003Cfield>\"`, although the linked Host build contains that field | Remote method descriptors are registered at boot and are not replaced by Host HMR. After changing a `TypertRemoteService` method's parameter shape, build and restart DSH, then verify the endpoint with a no-write API probe. |\n| 13 | Connection Fetch route registered without its \u002Fapi prefix | An authenticated GET to the stream returns generic `not found` even though the plugin loads and unary RPC works | `connection.fetch.register({ path })` matches the full pathname. Register `\u002Fapi\u002Fbotharness\u002Fstream`, not `\u002Fbotharness\u002Fstream`; verify the exact route in a running Host. This is distinct from and does not replace the API gateway's RPC interceptor (#141). |\n| 14 | `ctx.uiWorkspace.pickDirectory()` throws on a deployment without a picker | `TypeError: Cannot read properties of undefined (reading 'pick')` at call time, although `ctx.inject(['uiWorkspace'])` succeeded and the workspace service answers | The `ui-workspace` client service is provided even when no directory-picker pair is mounted (the web-app bundle's `-auto` chooser mounts one asynchronously; a profile can also end up with none). Treat the picker as optional: probe it, catch the failure, and offer a manual path fallback instead of a dead button. Diagnosed in #168. |\n\n| 13b | One-shot login token needs two visits | hand-rolled `curl`\u002F`fetch` against `\u002Fapi` gets `401`, then `404 not found`, although the server is healthy | The first visit arms the login, the second returns the session cookie. The launch token remains valid for that Host process; the helper also saves a private cookie jar for automated probes. Use the login URL in a browser or the jar for authenticated API calls. |\n| 14b | Driving the bridge by hand | plugin endpoints look absent (`404 not found`) while native `\u002Fapi\u002Fsettings\u002Fdescribe` answers `200` | The bridge namespace is `botharness` (the short `n` in an early comment is stale): POST `\u002Fapi\u002Fbotharness\u002F\u003Cmethod>` with `method: \"botharness\u002F\u003Cmethod>\"`. Probe native and plugin endpoints separately before blaming the plugin layer. |\n| 15 | `setsid` on macOS | a manual restart script dies with `command not found: setsid` | This checkout also runs on darwin. Use `scripts\u002Fdev-instance.mjs` (detached spawn) or a `( nohup … & )` subshell; never a bare `&`. |\n| 16 | Streaming Fetch route also registered for GET | POST file upload commits, but an authenticated GET for the file returns an empty HTTP 400 | In pinned DSH `connection`'s HTTP bridge, `requestBody: 'streaming'` constructs a Fetch `Request` with a body for every method; Fetch rejects a GET body before the handler runs. Register distinct exact paths: a streaming POST upload route and a buffered GET download route. Rebuild and restart the Host after changing route registration, then verify both methods in a real browser (#146). |\n| 17 | No process-injected dev key is mistaken for no model access | `dev-instance.mjs` reported “model calls will fail,” yet a PersonaBot DM received a real streamed DeepSeek reply | `dsh-credentials-local` resolves inherited environment before `$DSH_HOME\u002F.credentials.yaml`, then project\u002Fhome `.env`. The AX helper now distinguishes a shared injected key from a profile credential. Confirm the profile source without printing values, then prove usability with a real DM → model → committed Channel reply. |\n| 18 | Runtime skill without explicit `source` lists but never loads | Skill appears in `\u003Cavailable_skills>`; every model `skill({name})` fails `Error: loaded skill \"…\" source must be a string` | Pinned `dsh-skill` `register()` defaults `provider` (→ `\"runtime\"`) but not `source`, while `validateDefinition` on the `get()` path requires both as strings. Always pass explicit `source` (e.g. `'runtime'`) and `provider` in `ctx.skills.register()`. Diagnosed live from an exported session zip (`session.v3.jsonl` tool\u002Fresult) in #248. |\n| 19 | Newer layout facet assumed present crashes client boot | `Failed to load plugins@botharness\u002Fui: can't access property \"subscribe\", ctx.layout.panelInfo is undefined`; whole browser UI dead | `panelInfo` exists in DSH 0.1.7-rc.2 but the composed `layout` service in some profiles lacks the facet. Guard with a `panelInfoOf` helper: skip view-persist\u002Frestore when absent (degraded boot beats dead boot). Contract test boots apply with a panelInfo-less layout stub. Diagnosed live in #357. |\n\n| 19b | Global DSH CLI shadows the worktree's RC2 dependency | The Profile serves 0.1.5 Web assets while the plugin was built against 0.1.7; Bot mode crashes with React's invalid element error because runtime icon exports differ | Launch through `scripts\u002Fdev-instance.mjs`, which runs and version-checks the target worktree's local CLI. Verify the browser's served Web asset and Profile before diagnosing UI data. |\n| 20 | RC2 Web fallback for BotHarness Client rebuilt frames | `pnpm dev:client` rebuilds in ~0.1 s and `\u002Fplugins\u002Fevents` broadcasts the new revision, but the open Bot mode still shows the old tree | Open the local Web tab. BotHarness's development listener performs a full page refresh on its own rebuilt frame; reopen Bot mode after refresh. |\n| 21 | Windows staged SQLite migration enters recovery | A fresh official Desktop profile can show `Operational database is in recovery mode: migration-failed` while adding a Workspace\u002FSession; the same fresh owner test fails on Windows | Node on Windows returns `EPERM` for `fsyncSync` on a file opened `'r'` and for directory `fsync`. The owner now opens the staged database `'r+'` before syncing and skips unsupported directory sync on `win32`. Reproduce with the fresh `mountOperationalDatabase` test plus a real Desktop session. |\n| 22 | RC2 Client Modules strips a package name ending in `\u002Fclient`; Desktop document reload after HMR can use a stale graph | `@botharness\u002Fclient` shows `prefetch(\"@botharness\u002Fclient\") — not a graph entry` in Built-in Plugins. Renaming the unpublished package to `@botharness\u002Fui` enables native linked-bundle HMR and the DM updates in place. After a later full document reload, Web boot may fail with `@botharness\u002Fui: import failed` | Upstream `stripClientSuffix()` treats the package suffix as an export subpath. With the corrected ID, a fresh Desktop document can still receive the old boot revision after HMR: old bundle URL 404, current graph URL 200. The plugin cannot recover before import. Keep Client development on native HMR, avoid full document reload after a rebuild, and cold-restart app plus Host after stopping the watcher when boot fails. Preserve the plugin\u002FProfile; inspect `%APPDATA%\\@deepseek-ai\\dsh-desktop\\logs\\crash-*-web-boot.log`. The packaged Desktop may omit the development-only Reload Page menu. See `docs\u002Fclient-bridge.md` §7 and ADR-0066. |\n| 23 | New BotHarness Orchestrator tool omitted from the internal Messaging allowlist | The model calls `list_bot_contacts`, but the turn parks on a Human tool-approval card before the Bot DM workflow starts | Add Host-checked internal Messaging tools to `BOT_TOOL_NAMES` in `packages\u002Fcore\u002Fsrc\u002Fworkspaces\u002Fgrant-execution.ts`; keep their sender and Channel membership checks in the owning Host command. Verify with a real model turn, not only an adapter fixture (#279). |\n| 24 | Fresh WSL Web Profile cannot create DSH's default Workspace | Native DSH shows “Unable to create default workspace” even when the Bot Client is healthy | `xdg-user-dir DOCUMENTS` can return `$HOME`; DSH rejects Home as its Documents directory. For an isolated QA Profile, set `workspace-controller` `config.documentsDirectory` to an existing Documents directory in `cordis.patch.yml`, restart that Host, and verify a native Workspace appears. This is DSH first-use setup, not a Bot Channel failure. |\n| 25 | Durable Bot Inbox recovery races DSH Agent Loop factory registration on cold start | An unobserved Assignment notice is replayed at BotHarness construction, then the Channel shows `no agent factory registered (load an agent-loop plugin)` even though a later DM works | `ctx.agents` may exist before `dsh-agent-loop` calls `setFactory()`. Treat that specific pre-execution failure as transient: leave the Inbox Admission retryable, retry with a bounded delay, and avoid publishing a premature Session failure card. Verify a pending notice across a real Host restart. |\n| 26 | DSH 0.2.0 UI timing and localization break English-only e2e selectors | Browser e2e times out at `.bh-root`, the create-dialog name input, or the send button although the same flow passed on 0.1.7 RC2 | The first-run notice button is localized (`继续`), menu items render a frame after their trigger, and the BotHarness composer swaps its `textarea` for the rich `[role=\"textbox\"]` once mention candidates load. In e2e scripts: dismiss with `['Continue', '继续']`, wait for `[role=\"menuitem\"]`\u002Fdialog selectors before clicking, and target the rich textbox after the composer settles. Diagnosed in #419\u002F#420. |\n| 27 | Windows isolated dev launcher cannot spawn `pnpm` and can time out before DSH serves | `spawnSync pnpm ENOENT` under fnm PowerShell, or `no token URL after 45000ms` while the Host later becomes healthy | Windows may expose only `pnpm.ps1`, which Node cannot spawn directly; resolve an installed Corepack shim on `PATH` and invoke its JS through the current Node executable. When Corepack is absent, invoke the installed pnpm JS or executable. Store log\u002Fcookie files under `tmpdir()` and allow a longer token wait for Windows startup. A missing model key can also leave a DM turn running; verify Memory Inbox startup admission independently of a real model reply. |\n| 28 | Windows Git subprocess stalls the DSH Host | Memory checkpoint requests take 77–169 seconds and unrelated Channel\u002FAPI loads time out; a `git.exe` child stays alive with near-zero CPU. A standalone Git invocation against the same isolated repo takes milliseconds | Node's synchronous Git launcher in the Windows Host can attach a console process. Set `windowsHide: true` on every Memory `execFileSync('git', …)` path. After the fix, the same checkpoint read took about 1.4 seconds, and changed-state captures took a few seconds. Keep separate DSH_HOME values for concurrent QA instances so their SQLite leases and Git repositories remain isolated. |\n| 29 | WSL shared key is invisible to a Windows-launched instance | An isolated Host reports `MISSING_CREDENTIAL` despite a key in WSL `~\u002F.config\u002Fbotharness\u002Fdev.env` | The AX helper resolves `homedir()` in its own OS. In the Windows terminal, use `node scripts\u002Fdev-secret.mjs adopt-env --from \u003CWSL-dev.env-path>` once, then `check` and restart that Host. The helper creates only the Windows user's private shared file and never prints the key; verify with a real DM reply. |\n| 30 | Agent-scoped native Subagent tools cannot be replaced or globally restricted by name | Registering another `subagent` in the Bot Agent scope fails with `tool \"subagent\" is already registered in this scope`; `tools.restrict({ deny: ['subagent'] })` says the name is not a known global tool | The pinned DSH preset registers native Subagent tools in Agent scope. Register Bot-specific names in that scope, guard native execution, and call DSH Subagent Service after checking the current Bot plan. A child Session uses DSH's native `never` approval override; its inherited Workspace Grant, mode, and cwd still need Host validation (#508). |\n| 31 | Session Remote namespace injected without its parent | Client boot fails before Bot mode appears after adding `ctx.remote.session` | Declare both `remote` and `remote.session` in the Client Plugin dependency list, as the native open-in-app Plugin does. A namespace declaration alone does not establish the parent Remote Proxy. Verify the real shell boot after a Host restart; unit Context stubs must model this capability too (#574). |\n| 32 | Native token-usage projection mistaken for an independently reported total | E2E compares Profile total to an absent `tokenUsage.totals.totalTokens` and fails despite matching provider buckets | DSH 0.2.0 RC1 projection totals contain four disjoint token buckets, not an independent total. Compare each known bucket; sum them only when all four are known. For failed or retried settlements, use the preceding durable `request\u002Fheader` or `request\u002Fcontext` route rather than a later successful Assistant source (#503). |\n| 33 | Bot settings navigation stops matching its decorated button | The native settings dialog opens, but the Bot settings shortcut cannot select its section after the Bot icon is installed | The first-party icon adds a third child to the original two-child nav cell. Exclude only that owned icon when resolving the label; do not require the decorated button to keep its original child count or assume its first span is text. Verify repeated settings opening in the real shell (#621). Decoration must be idempotent: compare the requested markup with a per-element cache, because serialized innerHTML also contains the injected media styles and otherwise an observer can continually rewrite its own DOM. |\n| 34 | Isolated Provider registered but native Consumer activated in the same pending Fiber | Native tool-fs says its confining filesystem has no sandboxPolicy although `provide` ran; preset-only service lookup may also miss Host-provided fs\u002FShell | Cordis `get` exposes a Provider only after its Fiber activates. Await the isolated Provider Fiber, then mount native Consumers as child Plugins and await their activation. Resolve `agentPresets.serviceFor` first and fall back to public Host capabilities when inherited. Native tools capture Policy at registration, so isolation alone does not replace existing closures. Wrap the actual `tools\u002Fexecute` body for per-call context: `tools\u002Fpre-execute` returns before body dispatch. Verified against pinned DSH 0.2.0 RC1 with actual native reads, writes and approved Shell outside Session cwd (#632). |\n| 51 | Packaged Profile install refuses ignored build scripts | `pnpm install` in the Profile fails `ERR_PNPM_IGNORED_BUILDS` for `agent-browser` once Browser joins the product | pnpm 12 requires explicit build approval per workspace. The packaged Profile installs the same tree the repo workspace adjudicated, so `packagedWorkspaceSettings` carries the root `allowBuilds` map (explicit Profile entries keep precedence; a drift test locks the copy to `pnpm-workspace.yaml`). Verified with a real `--product-artifacts` install into an isolated home (#1328). |\n| 52 | Mobile import recovery forwards create-only metadata | Marketplace import previews successfully but fails with `gateway\u002Farguments-invalid` before mutation | The API Gateway rejects named arguments absent from the Remote method signature. `botImportLookup` does not accept `origin`, while `createFromGit` does. Send only lookup fields during recovery; preserve origin for creation. A direct `BridgeMethods` test skips this boundary, so cover the real Typert Gateway with the mobile transport (#2768). |\n\n\n| 28b | Rebooting an isolated Profile drops its optional IM Bundle | dsh-im settings and transport disappear after running the AX helper again | The helper used to replace all dependencies and bundles. It now retains non-BotHarness dependencies and extra Bundle entries while refreshing its own linked packages. Keep the same task-owned home and verify native plus BotHarness APIs after restart. |\n\n| 33 | Core Host types change Client Context augmentation order | Adding a shared Core DTO type import makes Client `ctx.sessions.list()` resolve to a Host function requiring arguments | Keep the Client session-controller type import before shared Core DTO imports in `client\u002Factions.ts`; verify `pnpm typecheck` and the running native Client. Host and Client Context augmentations share a module name; DTO imports can change declaration order (#12). |\n\n| 34 | Optional Provider Service is published before its account registry is ready | The persisted receive grant is present after restart, but BotHarness shows reception unavailable; enabling again works | Service availability alone is not account readiness. Restore the same explicit grant with a bounded retry only for transient `provider-unavailable`; retain its token, revision and group scope, cancel on disposal, and verify automatic intake with a real Host restart (#12). |\n\n| 35 | Native approval requested from an idle Agent probe | A direct `ctx.tools.execute` probe returns `Human approval is unavailable` and no DM card appears | Pinned DSH 0.2.0 RC1 `approval.request` requires an open Turn to enclose `approval\u002Fasked` and `approval\u002Fdecided`. Exercise first approval with a real model Turn, then use native probes for already-authorized operation guards. Verify pending approval cancellation with another real Turn; a completed Agent is insufficient (#460). |\n| 36 | SRC Remote signature omits a newly supported named argument | Profile Save fails with `gateway\u002Farguments-invalid: unexpected \"delivery\"`, although internal bridge-method tests pass | The Gateway builds its named-argument descriptor from the public Remote method signature. Add and forward the argument in that method, not only the owning implementation; verify through `\u002Fapi` and cover the public adapter plus durable owner (#528). |\n| 37 | A saved Bot model preset differs from the resumed native Session request | QA Profile selects Pro\u002Foff but the next request\u002Fheader still records Flash\u002Fhigh in an existing Orchestrator Session | Verify the actual request\u002Fheader, not only the Profile preset or composer label. In the isolated DSH 0.2.0 RC1 QA Profile, explicitly selecting Pro\u002Foff in the native Session chooser emitted model\u002Fselection; the next request used Pro\u002Foff and completed, including after Host restart. The cause of the preset\u002Fresumed-Session mismatch remains unconfirmed; preserve original failures and do not silently rewrite the Session or add an IM-specific model workaround (#613). |\n\n| 38 | Native configForms scope methods lose their receiver in React | Settings crashes inside getSnapshot\u002Fsubscribe despite a ready native scope | Pinned DSH 0.2.0 RC1 scope methods use their instance. Pass stable useMemo closures that call scope.getSnapshot() and scope.subscribe(listener), rather than unbound methods, to useSyncExternalStore. Verify native volatile persistence after Host restart and cover a class-based scope fixture (#726). |\n\n| 39 | WebServer prefix registration includes a trailing slash | Extension POST\u002FOPTIONS falls through to generic 405 even though the Plugin and authenticated API work | Pinned DSH 0.2.0 RC1 WebServer matches `pathname === prefix` or `pathname.startsWith(prefix + '\u002F')`. Register `\u002Fmy-plugin\u002Fextension`, then call `\u002Fmy-plugin\u002Fextension\u002Fpair`. Check preflight on the running raw HTTP route. Connection fetch requests carry transport URLs, so enforce actual network peer checks at the WebServer adapter rather than interpreting `Request.url` as the bind address (#741). |\n\n| 40 | A native Tool approval does not prove Shell execution | A real approved Orchestrator `bash` call can still return `Path is outside this Session's authorized workspace`; a subsequent escalation request is refused | Treat native approval and execution as separate evidence. Inspect the actual persisted Tool result and Session cwd\u002Fauthorized Workspace, including macOS path aliases. Do not relax guards or infer a successful command from the working Projection alone. In #751's pinned DSH 0.2.0 RC1 QA, the granted Assignment path executed while another owned Session retained a native approval; the Orchestrator refusal's underlying workspace mismatch remains unconfirmed. |\n\n| 41 | Nested native Menus compete for Escape and focus return | Escape closes only the inner menu and focusing its trigger reopens the hovered submenu, leaving the sidebar settings menu visible | In pinned DSH 0.2.0 RC1, each Menu owns document key listeners and consumes Escape before returning focus. For coordinated sidebar settings, use one Menu for dismissal and keyboard walking, with MenuSurface and MenuItemButton for nested cards. Verify Escape after repeated selections in the installed shell, including overlay disclosure restoration (#807). |\n\n| 42 | Retrying a timed-out isolated launch leaves two Hosts for one home | API health responds, but Bot commands fail with `lease-unavailable` | A prior launch can leave its detached Host alive after a token wait fails. Before retrying, inspect that exact task home\u002Fport and its `botharness.writer.json` PID; stop only the task-owned Hosts, then cold-launch once. An authenticated API health probe alone does not prove the operational database writer lease is ready. Observed in #811 QA. |\n\n| 43 | A third-party tour shares Escape and focus with a native Modal | Escape dismisses both the tour and the native settings; closing the tour returns focus behind a newly opened Modal | Pinned DSH 0.2.0 RC1 native Modal handles Escape on document bubble and captures its invoking control. Give the tour capture-phase Escape ownership, remove its listener on dismissal, and retarget the actual visible native dialog after asynchronous opening. Driver.js 1.4.0 restores old focus after onDestroyed, so restore focus to the foreground dialog in a microtask after that callback. Verify the actual packaged Client with keyboard navigation and keep reduced-motion behavior covered (#824). |\n\n| 44 | Reused QA Session retains its frozen application role prompt | A newly accepted Memory edit is on disk, but the real model still follows the earlier QA no-reply instruction after Host restart | A persisted Session can retain application-defined role instructions for its lifetime. Verify the actual system\u002Fmessage and Tool results, not only the file or handled Inbox state. For a new QA behavior, start a new application-owned Session through its normal lifecycle; never rewrite Session events or loosen authority. In #905, the first real voice transcript was received but the existing Session deliberately made no external reply. The replacement QA Bot uses the same paired account only after the earlier receiver is stopped. |\n| 45 | Self-update through the Plugin Manager loses its own answer | Bot settings' Update now installs the newer `deepseekbot` (profile `package.json` and `node_modules` change), but the click never shows a result and the Web page reloads into the API-key prompt; DSH's own Plugins page refuses the same spec as `already-installed` | Pinned RC1 `pluginManager.installBundle('deepseekbot@\u003Cv>')` upgrades in place and returns `restart-required`, but the profile HMR reloads the Web document after pnpm, so the in-flight bridge reply is lost and the reloaded page serves the new Client against the old Host. Never rely on the RPC reply: derive the pending restart from `listBundles()`' `deepseekbot` version versus the version snapshotted at module load, and verify with a real old-version profile, a click, the reload, and a restart (#986). |\n| 46 | A plugin cannot restart DSH through any RC API | `dsh web` and Desktop expose no restart; `appExit` only stops the tree, and the launcher has no supervisor to start it again | Restart from the plugin by keeping the process alive: call `ctx.appExit(0)`, and on `beforeExit` (8 s fallback) spawn `process.execPath` with the same `execArgv` and argv (plus `--no-open` for `web`) as a non-detached child with inherited stdio. The terminal keeps the session and Ctrl+C reaches both through the process group. The signed browser cookie survives, so the Client polls `releaseInfo` until a new version answers and reloads. Desktop is unverified, so its Client shows quit-and-reopen instead (#986). |\n\n| 47 | PersonaBot creation passes a BotHarness model-preset ID as the DSH Agent preset | First native Orchestrator Turn fails with `Unknown agent preset` before any Tool executes | PersonaBot `preset` selects a DSH Agent tool preset (for example `standard`), not a BotHarness model preset. Apply the latter with `modelPresetApply` and verify the actual model request independently. Correct the QA configuration through normal Bot update, preserve the failed Turn and use a fresh authorized event; do not treat model-preset selection as native Tool availability (#906). |\n\n| 48 | Native Go adapter forwards Session identity without its required request header | A correctly configured DSH 0.2.0 RC1 Go request fails with HTTP 400 `MissingSessionID` | Native `llm-pi-ai` passes `GenerateOptions.sessionId` to the SDK but omits `x-opencode-session`. The reviewed pnpm patch supplies the actual Session ID only for Go, strips case-insensitive static collisions, and preserves native attribution and other Provider headers. The AX helper carries this pinned patch into an independent CLI per opted-in home. Never use a fixed\u002Frandom substitute header; retain the failed Turn and verify a fresh real model → `channel_send` → committed DM reply. Requalify before changing DSH version or removing the patch (#1079; [guide](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-model.md)). |\n\n| 49 | Windows Modify permission is insufficient for native workspace-write provisioning | Approved native Shell calls fail before launch with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(...)` | The RC1 Windows ACL backend needs effective `WRITE_DAC` and `WRITE_OWNER`; being the directory owner with Modify can still lack the latter. Use the installed `diagnose-windows-sandbox-acl` skill to inspect effective access. With explicit Human approval for exact QA directories, use its backed-up scoped repair, then verify the original confined Shell operation. Preserve owner, deny rules and sandbox policy; follow its restore-and-stop path if verification fails. In #911, real native Orchestrator and Assignment pwsh 30-second waits both succeeded after the approved repairs of their respective QA directories. |\n\n| 50 | Local browser permission display is mistaken for successful tool access | A listed allowed origin still returns ERR_BLOCKED_BY_CLIENT, or DOM reads work while screenshots\u002Finput time out | Qualify exact-origin authorization, listener ownership, Host transport, navigation and actual capture separately. Preserve each result and stop bounded retries without new evidence; see the [AX browser runbook](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-browser.md) (#1225). |\n\n| 51 | A new BotHarness-owned Tool is registered but omitted from the execution policy | The real Orchestrator pauses on a Human approval card for an own-Inbox read, although the Tool contract test passes | `grant-execution.ts` classifies checked application-owned Tools through `BOT_TOOL_NAMES`; registration alone does not exempt a name from generic operation approval. Add only the Host-scoped Tool whose own authority checks are implemented, cover `requiresHumanToolApproval`, then build\u002Frestart the exact owned Host and verify a fresh real model call. Preserve the first approval card rather than approving it to hide the omission (#1278). |\n\n| 52 | Native Settings navigation clicks an unrelated dialog trigger | Onboarding opens the mobile app popup or returns without a model editor | Do not select the first `button[aria-haspopup=\"dialog\"]`. In RC2, native Settings may be an Account menu item whose hidden shortcut contributes to `textContent`; match its accessible label, excluding `aria-hidden` content. A whole-sidebar Bot mode shadow must yield while the native settings shell is needed, then restore on close, timeout or cancellation without switching the main panel. Verify the actual Models page (`Add model provider`), not a generic `Models` label also present in onboarding (#3222). |\n\n| 53 | A gateway concurrency refusal ends the Bot turn without retry | Several Bots woken at once on a serial local model fail within seconds with `PI_AI_ERROR: Concurrency limit exceeded for user, please retry later`, while one direct DSH chat queues and succeeds | Native `llm-pi-ai` classifies failures by text; an in-stream refusal without `429` or `rate limit` becomes non-retryable `PI_AI_ERROR`, so `dsh-llm-retry` never runs, and its default normal budget (5 retries, about 15 s) would be too short anyway. A repo pnpm patch only changes AX\u002Fdev runtimes, never a user's installed DSH. BotHarness owns the fix on the public `agent\u002Frequest-error` waterfall (`runtime\u002Fbot-request-retry.ts`): Bot Sessions retry concurrency-limit, too-many-requests, server-busy and `RATE_LIMIT` failures with 1–10 s backoff for up to 300 s, delegating providers set to `retryPolicy.mode: always` (#3300). |\n\n### Idle Assignment native child wake (#3477)\n\nA DSH-native background child can wake its idle Assignment parent without an application-defined\nAssignment run. Native `turn\u002Fstart` and a relay alone do not restore the report tool's execution\nauthority or its Adapter run context. At claimed-input prompt assembly, validate persisted direct\nSubagent ownership, current Grant\u002FSource, stop\u002Farchive and Bot availability; reacquire application\ncapacity and establish the real Assignment run before continuing the already-claimed input. Do\nnot replay the relay as a followup or change the idle direct-tool guard. Join native `whenIdle`\nand record the actual later Turn's report\u002Fcompletion, then release capacity. Waiting capacity\nuses cancellable commit notifications, not an idle polling loop. Qualify newly frozen bytes with\na real model, native events and the canonical report; fixtures are not native acceptance.\n\n## Reference\n\nFor opted-in AX Go launches on Windows, stage the reviewed adapter patch inside the isolated\nCLI and reference it relative to that CLI's workspace. A drive-qualified absolute pnpm patch\npath can be appended to the runtime path, causing `ERR_PNPM_PATCH_NOT_FOUND` before Host boot.\nVerify staged bytes, preserved workspace settings, and a fresh real DM reply; configuration and\nAPI health alone do not establish model access. Diagnosed with source on D: and home on C: in\n[#1409](https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fissues\u002F1409).\n\nIn pinned RC1, `defineTool` nested object properties mark requiredness with per-property `required: true`; an explicit JSON Schema `required` array is rejected by the authoring DSL. Native `bash` output is a structured foreground\u002Fbackground\u002Fpromoted union, so an interception must preserve the registered result schema instead of returning a string as `value`. #1380 verified both failures through a real PersonaBot; tool-registration\u002Fschema and real runtime checks cover the correction.\n\nNative MCP stdio uses SDK-owned spawn, not the Shell\u002FSubprocess Provider. Its automatic protocol negotiation starts a disposable probe sibling before the live server: a fixed Docker container name conflicts, while a per-owner label lets teardown remove every sibling. Native `dsh-scope` owns a module-local Symbol and WeakMaps; bundling another copy makes native Agent Contexts appear unscoped to the copy. Keep Scope external and resolve the same pinned peer as the Host; verify two real Agents concurrently, not only a raw-source single-Agent test. On Windows the preset's Shell Provider may be PowerShell even behind the `bash` Consumer name; launch a trusted executable with Subprocess argv instead of assuming POSIX Host syntax. The pinned Node image must actually include the Guest shell. These were diagnosed in #1380.\n\nNative Tool Registry `schemas(scope)` and `get(name, scope)` include inherited global and ancestor registrations. A name prefix does not establish an execution boundary; MCP server-name reservations are scoped too. For controlled installation, snapshot pre-install identities and exclude identities visible globally or in every ancestor from the post-install qualification. Verify inherited Host sentinels, including those registered during asynchronous startup, are denied while concurrent Agent-owned Guest tools execute. Use public `scopeParentOf`\u002F`scopeChainOf` rather than private Registry internals. This was reproduced against RC1's native Registry and real Docker in #1380.\n\nPinned DSH 0.2.0 RC1 selects one directory picker interaction at boot. A loopback Windows Host commonly serves native; uiWorkspace.listDirectory() then throws DirectoryBrowseError with rpcError.code = directory-picker\u002Funavailable. A consumer may fall back to uiWorkspace.pickDirectory() only for this capability refusal; unreadable directories and other failures remain errors, and cancellation returns no selection. Authorization still follows an explicit Human choice.\n\nFor isolated browser E2E on Windows, pin the browse pair in that task-owned Profile overlay: disable the directory-picker auto entry, then use a Patch insert list to compose @deepseek-ai\u002Fdsh-host-directory-picker-browse and @deepseek-ai\u002Fdsh-client-ui-directory-picker-browse. A bare new id\u002Fname patch does not insert a Plugin, and changing the name on an existing patch does not swap its implementation. Stop and restart that exact Host, retaining loopback bind and one backend. Verify the running folder-selection path. See the [upstream picker contract](https:\u002F\u002Fgithub.com\u002Fdeepseek-ai\u002Fdeepseek-harness\u002Ftree\u002Fdsh-v0.2.0-rc.1\u002Fpackages\u002Fhost\u002Fdirectory-picker).\n\nFor multi-window headless checks, set the intended viewport on each new page before entering the UI. A fresh page defaults to a narrow viewport, where the DSH sidebar can collapse to icons; a selector waiting for visible Bot-mode text then times out despite a loaded, authenticated shell. Use independent browser contexts with the authorized local session when validating stale replies, and submit through the visible Client action.\n\nDSH 0.2.0 provider token reports use disjoint uncached input, output, cache-read and cache-write buckets. Optional cache fields may be absent even when an exact total is reported: absence is unknown, not zero. `deriveTurnTokenUsage` may return no result when exact lifecycle or usage evidence is incomplete; never substitute token-meter context estimates for observed provider consumption. Read the durable Assistant settlement's actual source route rather than a configured model. Verified with the installed token-meter contracts and a real model request in #499.\n\nPre-execution refusal can leave an application-owned Session ID without a DSH Session. Before retrying that reserved identity, use Session Persistence `stat(id)` to distinguish an absent stored Session from an existing one: create only when `stat` returns `undefined`, and propagate storage failures. Do not infer persistent existence from the live Session Store or blindly resume a reserved ID. Verified against DSH 0.2.0-rc.1 in #500 with a rejected model route followed by a successful Human repair.\n\n- **DSH source checkout**: `reference\u002Fdeepseek-harness` (gitignored, in this worktree) must match the installed tag, now `dsh-v0.2.1-rc.2`. Read the TypeScript source (`packages\u002Ftypert`, `packages\u002F*connection*`, `packages\u002F*gateway*`, `apps\u002Fcli\u002Freference\u002FREADME.md`) when the how\u002Fwhy matters; the installed `lib\u002F*.js` is bundled output. Re-pin when DSH is bumped: `git fetch --depth 1 origin tag \u003Ctag> && git checkout \u003Ctag>`.\n- `references\u002Fdebugging-playbook.md` — boot verification, status-code semantics, WS mux probe, bisect recipes, headless puppeteer probe.\n- `references\u002Fprobe-web.mjs` — headless browser probe (console errors, failed requests, WS, internal fetch); run from the repo.\n- `dsh-ui` skill — in-harness UI rules; `docs\u002Fclient-bridge.md` §7 — dev loop; ADR-0023 \u002F #50 — bridge transport contract.\n\n## Additional verified pitfall — #1425\n\nAn exact DSH peer in any composed Plugin can reject installation before its code is imported.\nThe build pin is not the supported Host floor. Product declarations use `>=0.2.0-0` (1.2.x releases declared `>=0.1.7-0`; the floor moved in #1511) with native\nprerelease semantics and no future-version ceiling; preflight acceptance is not runtime qualification.\nCheck Core and the product-managed Provider together. Preserve each release train's immutable\nProvider source and runtime digest, and qualify its own packages rather than borrowing a maintenance\nrelease's E2E result. Do not use compatibility exemptions as release evidence (#1425).\n\n## Additional verified pitfall — #1138\n\nIn #1459, two real composer tabs showed repeated recovery checks; the store regression independently reproduced redundant durable writes for unchanged recovered text. Publishing a new identical version makes peer tabs request validation again. A no-op validation must retain the durable version, while removal of an invalid reference is persisted once. Keep transient validated reference metadata in the local snapshot without publishing a new unchanged record; verify both idle synchronization and explicit conflict selection against the rebuilt Host. A passing HTTP API probe alone does not qualify a browser whose request slots are occupied.\n\nFor a fresh pinned RC1 local Profile, let native initialization create the Profile directory before applying a task Patch. Precreating the directory makes the native default-profile initializer refuse its destination; initialization also creates an empty `cordis.patch.yml`, so merge intended entries instead of moving another file over it. Preserve native entries, then restart the helper's exact verified Host PID. This was reproduced in #1381.\n\nThe pinned native local Credentials Provider retains record objects in its cache. A trusted private-input owner that clears its incoming submission object must copy the values into the atomic grant payload before handing it to the Provider; otherwise clearing the request also clears the cached grant. Validate the published Host through an actual credential consumer, not only disk serialization. A Fiber's disposal must also drain already-started recovery writes before its storage Providers can close. These native ownership and lifecycle interactions were verified in #1381; the request settlement policy remains application-defined.\n\nA new root overlay must budget its long-lived Connection Fetch streams with existing pages. In official DSH 0.2.0 RC1 Windows Web, adding a separate companion SSE alongside the Bot-mode Activity, Channel and roster consumers left real DM sending pending until Bot mode exited. Reusing the companion's full Activity snapshot for the shared Client Activity store and closing the redundant Activity SSE restored three genuine DM submissions within Bot mode. The symptom is consistent with the per-origin HTTP\u002F1 connection limit; an exact wire connection count was not measured. Validate an actual DM reply while both the overlay and owning page remain visible. On removal, restore ordinary Activity demand; keep listener\u002Fframe\u002Fheartbeat disposal bounded and never weaken authentication to work around the symptom.\n\n## Additional verified pitfalls — #1339\n\nBrowser-bundled dependencies can defer `process.env.NODE_ENV` reads until a control first renders. In #1377, the RC1 Client booted and jsdom interactions passed, but opening the new table crashed the native main Slot with `ReferenceError: process is not defined`. Define the production environment constant at browser build time, retain native React\u002Fprimitive baseline externals, and verify the built Bundle contains no runtime Node environment read plus the actual dialog in the running shell. Do not add a global `process` shim or count a successful initial boot as proof of the interaction.\n\nOn native Windows 11 with DSH 0.2.0 RC1, a real pinned Chrome cold download produced Host progress while the panel's observation took about 81 seconds and showed only Opening. Separate authenticated observations returned bytes immediately. Making the duplicate localhost development-refresh SSE opt-in restored panel percent\u002FMB and 4–5ms observation responses during another real cold download. Preserve ordinary Bot-mode streams and native admission; do not add another progress SSE or treat successful Host polling as Client evidence.\n\nPinned Chrome 154.0.8037.57 can expose DevTools before its first window exists on a fresh Windows browser profile. Explicit `Target.createTarget(newWindow: false)` then refuses with `Failed to open new tab - no browser is open` (a CDP response, not stderr). Omit `newWindow` for background tabs so Chrome selects an existing window or creates the first one, retaining `background: true` and `focus: false`; verify with the real fallback E2E. A task-owned binary marked `Zone.Identifier` \u002F `ZoneId=3` spawned successfully, while moving it immediately before native spawn produced ENOENT \u002F errno -4058 and the existing startup-spawn-failed cause\u002Faction panel. These observations do not justify a new Windows stderr kind or a claim that every antivirus behaves the same.\n\nProvider configuration must be checked against the composed production Controller, not only its bare class. In #1111, dsh-im workspace decoration attached asynchronous catalogs to `registrationStatus()`: the native QR had been generated, but setup reported `setup-failed` when it read a Promise as status. Await the public Controller result and exercise the actual wrapper plus async catalogs through the public setup transport. Verify generation\u002Fpoll\u002Fcancel again in the packaged Host; this does not qualify a new platform pairing.\nA native credential write may commit before its response fails. Application-defined owners must recognize success only by canonical readback of their newly generated opaque revision and exact target grant, rather than treating any current record as success. In #1382, injected post-commit failures proved that unconditionally failing could leave local revocation committed without attempting a running-use stop. Account activation must precede configured Channel publication, with both proofs required at consumption. Startup recovery must finish before Owner mutation APIs admit new grants, otherwise cleanup can mistake an in-flight replacement for an orphan. These behaviors were verified against the pinned RC1 local Credentials Provider; application account lifecycle policy stays outside DSH Context.\n\nQualify a passive model-request probe against the actual selected adapter. In #1383, a DeepSeek-only URL filter would miss the native Go route; the probe now recognizes the observed `\u002Fmessages`, `\u002Fchat\u002Fcompletions` and `\u002Fresponses` paths and records whether the body was available. Clone a Request only when no body override exists; non-string overrides are incomplete evidence, not a clean scan of the original body. Windows `NODE_OPTIONS=--import` requires a `file:\u002F\u002F\u002F` URL, and a synthetic canary file belongs outside DSH_HOME so storage scans do not mistake test instrumentation for leakage. The probe preserves fetch payloads and authentication headers and never records either; unsupported routes or encodings remain unqualified. Verified against pinned RC1 Go requests and isolated body-override regressions.\n\nIn pinned RC1, an exported native `createMcpToolDefinition` input schema with `additionalProperties: false` did not itself reject extra arguments at the adapter entry. Enforce the admitted parameter set in a trusted Consumer before resolving confidential values or invoking a private transport. Verify a real native Tool call with an extra parameter, not only schema inspection. The SDK stdio Client also merges selected default environment names when `env` is supplied; explicitly override inherited names when a fixed child must exclude ambient credentials. Both behaviors were verified in #1384 with the installed native adapter and SDK.\n\nCross-platform Profile migration needs a separate path-metadata audit. In #1386, the qualified dsh-im Provider returned `feishu-startup-config-invalid` and no accounts because its copied `integrations\u002Fdsh-feishu\u002Fworkspaces.json` contained an absolute Windows workspace that is invalid on Linux. The native management `connection.status` surfaced the startup error; translating only the audited source-home workspace field and restarting the exact task-owned Host restored the same account and sole receiver. Native Session header cwd\u002Fproject keys and application ownership metadata also need bounded translation; preserve immutable Session Event frames and the native credential store. A Linux bind-mounted workspace additionally needs the guest UID's POSIX access: Docker Desktop success does not qualify Host umask, directory traversal or file-write behavior. See the [Linux qualification guide](..\u002F..\u002F..\u002Fdocs\u002Fdev\u002Fguides\u002Fprivate-input-linux.md).\n\n## Additional verified pitfalls — #1490\n\nApplication-defined long-lived SSE responses share the browser's HTTP\u002F1.1 per-origin budget (about six) with native HMR. With six held, every ordinary request in every same-origin document timed out while an independent authenticated request still answered at once; the identity, model and message loading states are consequences, not a rejected token. Count long-lived responses per document (HMR included) before adding one, test with one more document than you expect to support, and carry application streams as stream-mode Remote methods on the Gateway's multiplexed socket (ADR-0181). In-flight EventSource requests do not appear in Resource Timing; read the network list instead.\n\nA source-declared stream method needs more than a unary bridge method. Host: mark it `mode: 'stream'` and name its final parameter `signal`. Client: `ctx.remote.$mount` a contribution whose descriptor repeats namespace, method, `mode`, parameters and `cancellation`; every parameter needs a `strict` codec (`create` returning an object with `parse`), while the result may stay `src-json`. Open it through `ctx.remote.$stream`. The mounted namespace is its own Cordis service: read it with `ctx.get('remote.\u003Cnamespace>')` from the mounting Plugin's Context. Reading `.\u003Cnamespace>` off a captured `ctx.remote` object returned nothing, and the stream never opened with no console error. The supervisor retries carrier loss only; a normal Host end or a thrown item is terminal, so the application retries it. Guard `$mount`\u002F`$stream` for older Hosts. Verify with an authenticated open frame on `\u002Fapi\u002Fremote.mux` and with a real page refresh after a Host change, not with unit stubs alone.\n\nTo use the Gateway Client's stream helpers (`RemoteSnapshotStream`, `RemoteJournalStream`, `RemoteStreamCarrierError`) from an application Client bundle, declare `@deepseek-ai\u002Fdsh-api-gateway\u002Fclient` under `dsh.client.external` in the package manifest and externalize the same ID in the bundler, as the official workspace and session controllers do; `dsh.client.inject` can stay empty. That module is a browser closure bundle and throws `window is not defined` when a Node test imports it, so alias it in the test runner to the package's per-file modules under `lib\u002Ftypes\u002Fclient\u002F`. Return a `RemoteStreamCarrierError` from `ended(accepted)` once the baseline was accepted so a normal Host end is retried by the supervisor; any other error makes the snapshot stream terminal (#1498).\n\nA `RemoteError` thrown by a stream method before or between items reaches the Client as an `error` frame with its `code` and ends that logical stream as a terminal failure, not a carrier loss; map application refusals (unknown subject, cursor ahead of the log, invalid cursor) to stable codes and let the consumer decide whether to reload state. When a stream replaces a legacy route, make the subscription a single typed frame source and let both the stream and the route encode it, so their replay and baseline rules cannot drift (#1500).\n\n## Additional verified pitfall — #1528\n\nThe pinned client-modules loader claims every `\u003Cstyle>` without `data-plugin` for the module materializing at that moment (lazy chunks included) and removes those tags when that module is replaced, invalidated or pruned. A plugin that injects an untagged sheet from an effect can therefore lose it to another plugin's reload while it stays active: its UI renders unstyled and DSH's own UI, whose sheets are tagged, looks fine. Set `data-plugin` to the injecting module's id (and a `data-plugin-css` key) on every runtime `\u003Cstyle>` (#1528).\n\n## Additional verified pitfall — #1154\n\nQualify an external Provider's exported Service contract, not only a test fixture or internal sender. In a DSH `0.2.0-rc.2` Host, dsh-im `.20` exported `receiptVersion: 1` and advertised QQ `proactive-fence-checked` per account, but did not export `postFenceVersion`. Requiring the absent global field incorrectly hid a checked QQ post. Consume the actual per-account text, receipt and fence capabilities; still pass the final fence, refuse missing capabilities before native effects, and verify the real saved target's `canPost` after rebuilding and restarting the task Host. This capability proof does not establish QQ permission or rendered delivery.\n\n## Additional verified pitfall — #1155\n\nDirect Controller and Runtime tests do not qualify the application-defined Provider's production factory. In a DSH `0.2.0-rc.2` Host, real QQ plain text reached the native SDK but ordinary delivery stayed unverified because the factory dropped the consumer's `ordinaryText` accessor. Cover the actual production factory through the exported Delivery Service and Runtime, then rebuild and install the immutable Provider artifact. Verify a fresh native event on the new receiver lease; replaying the failed event does not establish recovery. Ordinary delivery qualification and explicit collection opt-in remain separate checks.\n\n## Additional verified pitfall — #1988\n\nThe pinned dsh-im Provider (`beaed4a6`, DSH `0.2.0-rc.2`) exports checked WeChat proactive text, receipt and final-send fence capabilities per account, but no global `postFenceVersion`. Requiring that field hides a real paired-owner forwarding target even though reception is ready. Qualify the account capabilities and receipt contract, pass `beforeSend`, and reject any missing capability before an external effect. The real Host reproduced `canPost: false`; the contract regression omits the legacy field and retains missing-capability\u002Ffinal-revocation cases. Actual phone delivery remains a separate E2E check.\n\n## Additional verified pitfall — #2017 pointer menus\n\nIn the pinned DSH `0.2.0-rc.2` Web Client, native `Menu` with a viewport `getAnchorRect` and a body portal uses CSS positioning coordinates that diverge under body CSS zoom. At 125%, a click at `(136.25, 20)` rendered the popup at `(170, 30)`; 100% retained only the native dropdown gap. The application `ds\u002FPointerMenu` now measures the rendered scale and native popup rectangle, owns the body portal and viewport\u002Ftraffic-light clamping, and leaves ordinary anchored dropdowns native. Callers pass raw viewport points, without local correction constants. The isolated Web regression covers normal\u002Fzoomed placement and edge avoidance; native macOS remains a separate check.\n\nThe rc.2 native `Menu` handles Escape by calling `onClose` and then restoring its own anchor focus. A pointer menu's placeholder anchor contains no trigger button, so its fallback can focus the closing menu row after the application synchronously restores the Panel header. `usePanelMenu` defers trigger focus to a microtask, after native dismissal, and only focuses the same still-connected trigger. This also avoids focusing a header removed by Close. Restore only when focus remains on the closing menu or page body; an outside click that focuses the composer must retain that focus. Verify Escape and Shift+F10 on every Panel header in the workspace journey.\n\n\n## Additional verified pitfalls — #2034\n\nIn rc.2, the Client shortcut catalog can expose a newly registered command before the native preference adapter accepts its definitions. An immediate revision-checked edit can return `not-ready` (or `stale` after a concurrent config publication). Retain accepted bindings and retry those transient outcomes with a bounded delay; show a migration refusal only after the bound or a terminal result. A real old-to-new Web Client upgrade qualified the custom-binding migration and dispatch.\n\nThe native Workspace navigator clears a current Session that appears in `archivedSessionIds`. Opening an auto-archived Assignment directly can leave the landing screen and log a released Sidebar Session reference. Restore the Session through its existing explicit archive action before qualifying navigation; merely leaving an application panel does not prove the target opened. The real rc.2 journey verified the same restored Session ID and visible report from both application views.\n\n## Additional verified pitfalls — #2054 evaluation\n\nIn the pinned DSH `0.2.0-rc.2` Session log, `request\u002Fheader` records request configuration; it is not a per-turn generation barrier. The real two-Bot diagnostic had one header but later `step\u002Fstart` events in additional turns. Use native `step\u002Fstart` timestamps to establish that generation began, and separately record application draft frames and canonical message commits. A missing later header does not prove the Bot never started that turn. Preserve the original misclassified diagnostic when correcting instrumentation.\n\nSumming only `assistant\u002Fmessage` usage omits failed native `assistant\u002Fattempt` events. The same diagnostic recorded an attempt ending with `TRANSPORT` and no usage before a successful response. The existing Host Usage Projection correctly returned unknown totals for that Bot. Export failure metadata and any reported usage separately; completed-response totals are a lower bound, not a replacement for unknown full usage. Retain unknown auxiliary\u002Fprovider retry coverage and omit hidden reasoning chunks from public evidence.\n\n## Additional verified pitfall — #2089\n\nIn rc.2, `tools.restrict({ deny: [...] })` validates names against the global Tool registry even when called from an Agent scope. Naming an application-defined Tool registered only in that Agent scope, or intentionally omitted there, fails Agent setup with `names unknown global tool` before the model runs. Tob creation reproduced this on macOS Desktop with `bot_create`. Omit the legacy registration and use an Agent-scoped `tools.guard` for execution refusal, retaining the callback's current-run authority check for stale references. A mocked restriction collector cannot qualify this behavior; test the pinned `ToolRuntime` with real Cordis scopes.\n\n## Additional verified pitfall — #2056 verification transport\n\nAgainst an idle RC2 Host on Windows, Node's pooled `fetch` reproduced `ECONNRESET` after the probe's event loop was blocked for six seconds: it reused a connection whose close event had not been consumed. An asynchronous six-second wait and a request with `Connection: close` both succeeded. The `verify-app` RPC helper uses one connection per request; it preserves a lost mutation response as an error instead of retrying a possibly committed write. Distinguish this test transport failure from a model-provider failure, and correlate Host health with any deliberate restart before diagnosing a crash. Preserve failed cohort attempts; register changed transport settings before a new comparison rather than replacing old results.\n\n\n## Additional verified pitfall — #2192 Desktop approvals\n\nIn DSH `0.2.1-rc.2`, the native API remotes approval answerer can run before an application's Channel answerer and hold a Session-backed approval without calling `next()`. Native Session events then show `approval\u002Fasked`, but no application Channel card appears and the command times out. Register the application-owned answerer with Cordis `prepend: true`, retaining exact Agent\u002Fcall tracking and owner checks, and delegate unowned requests to `next()`. Native `never` policy still refuses before the waterfall. An isolated macOS Desktop reproduced the missing card; after this change, approving once visibly created a Bot and group through Tob's CLI. Regression coverage must exercise an earlier swallowing answerer, delegation, cancellation and native policy denial; do not bypass approval to make the journey pass.\n\n## Additional verified pitfall — #2221\n\nDeepSeekBot 1.4.0's workspace shell explicitly refused `html[data-windows-titlebar]`, so a Windows Desktop could load current Bot features while retaining the old sidebar. This is a platform fallback, not proof of a stale npm package or cache. In DSH 0.2.0-rc.2 and 0.2.1-rc.2, the native layout reserves the Windows title bar with frame padding; the preload menu is a body-level shadow root and caption buttons remain Electron-owned. The workspace can claim the existing content columns without replacing that frame or its padding. Preserve structural qualification, overlay ownership and disposal; do not clear user layout state or disable native drag regions. Source regression tests cover activation and DOM\u002FCSS ownership, while Windows native title-bar controls, dragging, display scaling and restart persistence remain separate device gates in #2221.\n\nThe Windows 1.4.0 fallback also writes layout version 8 while keeping Sessions and Bot panels flat. On workspace activation, import that geometry based on the absent rail plus flat-panel authority, retain an untouched backup, and update the mounted dock's seeds before it saves. Workspace ownership arrives after the legacy render, so a storage-only migration test misses stale React refs overwriting the imported ratio. Native Windows blank drag regions need explicit CSS: the upstream data-window-drag rules are macOS-only. Verify native drag separately from DOM\u002Fstyle tests.\n\n## Additional verified pitfall — #2214\n\nA bundled Markdown dependency can resolve its package-internal condition imports to Node implementations even in a Client build. With `react-markdown` \u002F `vfile` in the pinned tsdown\u002FRolldown toolchain, the Client required `node:process`, `node:path` and `node:url`; the real DSH loader refused the plugin before Bot mode could mount. Explicit browser export conditions alone did not change vfile's `#minpath` \u002F `#minproc` \u002F `#minurl` resolution. Resolve those three imports only inside vfile to its shipped `.browser.js` implementations in the Client build, retain the native external baseline, and verify both the actual built Bundle and a cold browser boot. Do not add Node modules to the shell baseline or install a global process shim. The browser condition also selects DOM entity decoding; the Bundle execution test needs a real DOM for that browser-only code.\n\n## Additional verified pitfall — #2290 QA\n\nA fresh Windows build on pinned DSH `0.2.1-rc.2` exposed `vfile` Node imports in the Client bundle: the resolver hook matched slash-only importer paths and missed Windows backslashes. Normalizing that task build's importer path selected the existing browser modules and restored boot; no global process shim was needed. Keep this build-environment recovery separate from private-input behavior proof. The existing screenshot helper also waited for Settings before dismissing the native preview dialog; dismiss the observed dialog first. In the current dock, select Messages before opening a Channel from Home. Preserve boot\u002Fdrive failures and inspect the actual console and accessibility tree before retrying.\n\n## Additional verified pitfalls — #2268 desktop zoom composition\n\nThe npm `dsh-client-ui-theme` 0.2.1-rc.2 Host artifact imports Schemastery as ESM.\nA generated local copy that rewrites this to `createRequire.resolve()`'s CommonJS entry\ncan fail full Profile startup with an ESM\u002FCJS loading race. Keep the canonical ESM singleton\n(`lib\u002Findex.mjs`) and verify by importing the generated Host, then cold-booting a complete\nisolated Profile. Do not infer native startup from a syntax-only transformation test.\n\nThe same release's shortcut `normalizeBinding` rejects `NumpadAdd`, `NumpadSubtract` and\n`Numpad0`. Validate contributed defaults against the real pinned protocol before registering;\na thrown registration must revoke earlier commands, restore owned compatibility resources,\nand expose a refusal. Do not silently turn a failed zoom mount into apparent success.\n\n### Native desktop restart and private CLI launch metadata\n\nThe pinned desktop worker chooses a new loopback HTTP port and process launch token on a real\nrestart. A previously saved CLI endpoint can be unreachable; substituting the new port with the\nold token correctly refuses login. For the isolated zoom QA Profile, the launcher's task-only\nBundle consumes the public `webServer.getOrigin()` and `connection.authenticatedUrl()` methods\nand writes fresh 0600 machine-local CLI metadata. It adds no listener or product route. Never\npublish its token or private metadata, weaken authentication, or attribute this refusal to the\nfeature's Host relay before refreshing the launch credentials.\n\n### Stop the owned desktop before a full linked build\n\n`pnpm build` cleans the Client output directories before writing the new bundles. A running\nlinked native Profile can hot-load during that missing-file interval. In the pinned RC, the\nfirst failed script load can poison the current module-loader generation and leave later\nbundle requests marked as skipped even after files return. Preserve the first crash report,\nfinish the build, then restart only that task-owned desktop with the same Profile and user-data\ndirectory. Stop the owned process before future full builds; never disable third-party Plugins\nor erase the Profile to recover this development sequencing failure. A Client-only iteration\nand an installed immutable product build are separate paths.\n\n### Zoomed settings navigation and native portals (#2269)\n\nIn pinned 0.2.1-rc.2, root CSS zoom changes the body's local layout width but leaves\n`matchMedia('(max-width: 648px)')` tied to the original viewport. At 430%, a wide Settings\nsidebar survives in a 293px local layout. The native Modal also scales its frame overlay\npadding, leaving only 235 viewport pixels for the card. Measure the local body width and\nnormalize only the application Settings overlay's safe-area padding; keep the card zoomed.\nThe native Menu's portaled anchor can be multiplied again (observed y=1247 in an 820px\nviewport). The compact application section picker reuses the existing viewport menu owner,\nwhich clamps and converts coordinates. This does not qualify other native dropdowns.\n\n## Additional verified pitfall — #2268 desktop theme packaging\n\nA Bundle Patch's `name` guards an existing row; it does not replace its implementation.\nRenaming a replacement row to `qualified-theme` breaks the native Client's hardcoded\n`configForms.get('ui-theme')`; a successful boot and one Client module id do not prove font\nsettings preservation. Startup Node hooks also failed to redirect the native Client metadata\nresolver in the actual Host, despite standalone Node resolver tests passing. Do not use those\napproaches as qualified delivery. Retain the original row and use an explicit Profile-local\npackage override through `deepseekbot-zoom-setup enable`, then restart. The command refuses\nunsupported platforms\u002Freleases or other owners and exposes `runtimeVerified:false`.\nDisable before product removal. pnpm can leave an unlisted `link:` symlink after remove;\nthe owner removes only its exact link and verifies it is absent. Native `ui-theme` reads,\nwrites, restart and disable must retain the same font preference. Keep the copied identity,\nlicense and relative ESM schema import; no installed ASAR or upstream files are changed.\n\nThe copied Client exposes its zoom lease only when the actual `__DSH_BOOT__.release.version`\nis 0.2.1-rc.2. Unknown\u002Fmissing releases retain the font-key scope and expose no zoom capability.\nThis runtime guard does not remove an already installed Profile package override or qualify\nthat copied theme on another Host. Disable the override before switching outside the verified\nDesktop\u002FHost\u002FClient tuple; re-enable only after qualifying the new combination.\n## Windows vfile browser imports (#2289)\n\nRolldown can pass a Windows importer path with backslashes. The vfile browser-variant override must normalize separators before matching `node_modules\u002Fvfile\u002Flib`; otherwise a successful build can retain `require(\"node:process\")`, and the real Client refuses @botharness\u002Fui before its Services exist. The existing Client bundle contract reproduces this: two assertions fail before normalization and all seven pass after it. Rebuild the Client and restart the task-owned Host, then inspect its actual browser console; API health alone does not qualify plugin boot.\n\n\n### Desktop plain-library overrides require an explicit offline installer (#2268)\n\nThe 0.2.1-rc.2 CLI refuses `desktop` because Electron owns its lifecycle. The native Plugin\nManager's `installBundle` validates installation-first metadata; adding `dsh.bundle` only to a\nProfile-local copy of the shipped theme still returns `not-bundle`. Headless Profile setup\nsuccess did not qualify Desktop. DeepSeekBot's opt-in setup uses the explicitly selected app's\nbundled pnpm only after the target Desktop Host exits, takes the native Profile manifest writer\nlock, disables scripts and preserves the native `ui-theme` row and preference Patch. Keep the\napp closed until setup returns. Refuse other owners, a busy Profile, an unsupported app version\nor a running target; do not edit ASARs, silently replay uncertain writes or relabel failed\nnative-manager attempts as installation proof. Reopen the same Profile\u002Fuser-data for acceptance.\n\n### Desktop plugin-event stream churn (#2269)\n\nOn the actual 0.2.1-rc.2 Desktop, a passive Network observer recorded `\u002Fplugins\u002Fevents`\nreturning HTTP 200 plus a graph frame, failing with `net::ERR_FAILED` after about 301 seconds,\nand reconnecting three seconds later with HTTP 200 and a fresh graph. The shipped Desktop\nforwards this scheme route through Node fetch; the shipped HMR Client uses EventSource.\nThis identifies native plugin-event transport churn and observed recovery, not the exact\nunderlying timeout source. Do not report that cohort as console-error-free, infer webview\npainting from the stream, or add guest reload\u002Frecreation to conceal it. Preserve the full\nrequest\u002Ffailure\u002Freconnect sequence without auth data and distinguish a page exception or\nfailed reconnection from this measured sequence.\n\n### Windows Desktop zoom candidate (#2270)\n\nOn the official Windows 0.2.1-rc.2 executable, `FileVersion` retains `0.2.1-rc.2` while\n`ProductVersion` reports only `0.2.1.0`. Qualify the former. The real shell publishes `win32`;\nthe Shortcut Service names its platform `windows`. Verify both independently and retain the\nexact boot-release and platform-matching compatibility lease checks. Native caption controls\nremain Windows-owned; the macOS 88×40 corner does not apply.\n\nWindows absolute module paths need `pathToFileURL` before dynamic ESM import. The workspace\nchrome and Select\u002FTooltip QA scripts failed before their fixtures loaded until their Vite\nimport used a file URL. External pnpm invocations use `pnpmCommand`, rather than executing a\nWindows command shim directly. After those fixes, the real dependency fixtures passed;\nfixture pixels still do not qualify native Desktop guests.\n\nThe Windows input tool emitted Ctrl+= with an empty physical `KeyboardEvent.code`, producing\nno native zoom dispatch. A Human's physical Ctrl+0 produced `Digit0`, one native event, one\nzoom handler invocation and one storage write, restoring saved 120% from current 144% while\nretaining the draft and selection. Record the driver limitation separately from application\nbehavior; use the [desktop zoom journey](..\u002Fverify-deepseekbot\u002Ffeatures\u002Fdesktop-window-zoom.md)\nfor the remaining input, IME, guest, DPI and lifecycle gates. A source test or a Client DOM\nevent is not a substitute for the native route.\n\nAn immutable Provider's provenance records the DSH version of its pinned input, while an\nartifact manifest records the current composed Host. After the RC2 upgrade, comparing those\ndifferent facts rejected an otherwise hash-matching installed package. Compare provenance\nto `productImProvider.upstream.dsh`, preserve source and runtime digest checks, and qualify\nthe current composition separately. Do not rewrite the original Provider provenance to make\nit look newly qualified.\n\n### Remote Host QA profiles and hidden sidebar copies (#2500)\n\nThe launcher and `verify-app` share a temporary cookie jar named from `basename(DSH_HOME)`. Two isolated homes named `home` in different parent folders overwrite that jar, so the second launch can make the first Host's doctor return 401 while its own browser still works. Give concurrent homes distinct basenames (`host-a`, `host-b`), preserve the first refusal and verify each Host separately. Do not treat this verification-cookie collision as a product authentication failure.\n\nThe qualified workspace retains a hidden sidebar copy beside the visible Channels panel. The two Add remote buttons can have the same accessible name. A first-match selector can click or fill the hidden copy; choose visible elements as the two-Host journey requires, and wait for the submit button to become enabled after input. The real Windows Web baseline paired successfully after the driver selected visible controls and used keyboard input; no product change was required.\n\n### Connect route provenance in pinned DSH 0.2.1-rc.2 (#2541)\n\nArbitrary HTTP route headers do not enter Typert invocation context, and cookie-authenticated\nbrowser calls share a Peer. The `connection\u002Frequest` waterfall does not admit `remote.mux`\nopens. A header-only or unary-only guard therefore cannot restrict all Connect calls.\nBotHarness stamps its cloudflared-only origin with a process-local capability and owns both\nunary admission and a bounded mux adapter at the Device Gateway, before native dispatch.\nThe shared client refuses before serializing secret arguments: a Host refusal cannot remove\nplaintext already sent through Cloudflare. Verify HTTP, mux and ordinary streams against the\npinned Host; this adapter is not encryption or an upstream DSH API extension.\n\n### Device gateway forwarding and Fetch Metadata\n\nThe pinned DSH `0.2.1-rc.2` browser admission guard rejects `Sec-Fetch-Site: cross-site` even when a Host-held cookie is valid. After the application-defined device gateway has checked the external Origin, refused ambient cookies and admitted the device credential, its own loopback request must discard the browser’s `Sec-Fetch-*` metadata along with Origin\u002FReferer. These headers describe the external browser hop, not the gateway’s authenticated internal hop. Preserve all external admission checks and native DSH checks; do not relax either to repair remote tabs. A real two-Host desktop browser reproduced HTTP403 with the cross-site header and HTTP200 when only that metadata was omitted (#2584).\n\n### PersonaBot native question answerer precedence (#2590)\n\nThe pinned DSH `0.2.1-rc.2` dispatches `user-questions\u002Frequest` as a Cordis waterfall. A prior native Client answerer can wait without calling `next`, preventing a later application-defined Channel answerer from seeing the request. Register the existing Channel question owner with `prepend: true`, as Channel approvals already do. Retain its exact live-Agent and Session Ownership checks; unowned requests must still call `next`. A real two-Host browser must show the card in both the owning conversation and remote Activity, accept an answer and resume the same native tool call. A pending tool trace alone does not prove a Channel card was created.\n\n### DSH 0.2.1-rc.3 upgrade\n\nThe development CLI and SDK pin is rc.3. Preserve the independently pinned rc.2\n`dsh-client-ui-theme` build input for reproducibility. The copied Desktop zoom adapter\nnow checks protocol and content integrity instead of rejecting another rc label. Ordinary\nHosts supply their own native theme unless the optional override is explicitly installed.\nNative Desktop qualification remains separate. Keep Provider build provenance unchanged.\nThe rc.3 file-tool and Go Session patches retain the reviewed rc.2 implementation.\n\n### Forward-compatible launch admission (#2713)\n\nBuild pins and historical qualification versions are evidence, not runtime allowlists. `--dsh-version \u003Cversion>` selects an isolated CLI without editing workspace dependencies; otherwise use the installed CLI. Native Host metadata owns the API floor (`>=0.2.0-0`, prereleases included), and Host-provided DSH modules have no npm peer ranges that exclude future prerelease tuples. The Go runtime first installs the selected native adapter, locates the unique matching request shape, and stages the reviewed patch at its actual line number; changed or ambiguous code is refused with a concrete diagnostic. This avoids pnpm patch failures caused only by line-number drift between rc versions; catalog and authenticated API checks still fail on real incompatibility. The optional zoom adapter checks its protocol, platform and transformed bytes rather than a Desktop version label. Stop a task-owned Host before switching its Profile runtime; never mutate another task’s Profile. Forward admission is not proof of future runtime behavior.\n\nThe verification wrapper also accepts `verify-app launch --dsh-version \u003Cversion>`. Its doctor reads the recorded launched runtime and compares it with the recorded launch version, not the workspace SDK; older instance records without a runtime path must be relaunched before claiming version verification. Packaged artifact `dsh` records build provenance and does not need to equal the current SDK. Stage Go patches using the actual installed adapter package version, which can differ from the CLI version. Optional IM launch metadata is prepared before starting the detached Host.\n\n### Home ownership scan exceeds the default process-output buffer\n\nOn a busy macOS development machine, `dev-instance.mjs` can refuse a fresh Home with\n`Cannot verify development Home process ownership` before launching a Host. Inspect the\n`spawnSync` result without printing process environments: `error.code === \"ENOBUFS\"`\nmeans the full `ps axeww` output exceeded Node's default buffer, not that the Home is owned\nby another task. Keep the complete scan and its fail-closed error handling; use the same\nbounded 32 MiB buffer as the child-process ownership scan. Do not truncate process rows,\nskip ownership checks, or print raw environments, which can contain credentials.\n\n### Native Subagent wake and prompt assembly (#2435)\n\nIn DSH 0.2.1-rc.3, native child reports wake an idle parent independently of an application turn. Agent inbox claim notifications precede system-prompt assembly; assembly precedes agent\u002Fpre-step and snapshots installModelSelection. Establish the application-owned Bot turn before assembly, or the first resumed request can use a stale model. Observe trusted source metadata, validate Session Ownership, and join the existing Bot queue; never replay the report or borrow a prior Human source. Tie readiness to the actual Adapter tool context, not slower Runtime cleanup. Direct CLI calls are not live Orchestrator turns for stop\u002Fsteer selection. Qualify this sequence against the running Host; an API send receipt alone is insufficient.\n\n\n## Additional verified pitfall — #2761 desktop ASAR filesystem\n\nThe Electron desktop carrier patches Node filesystem APIs to interpret `.asar` archives as virtual directories. A downloaded capture-runtime archive must instead be inventoried, hashed and cleaned as physical files. In Electron, use its built-in `original-fs` for those installer operations; keep ordinary Node filesystem APIs in CLI Hosts. Do not toggle process-wide `noAsar`, which affects unrelated DSH modules. A valid cache can pass CLI verification but fail the desktop carrier, trigger another download and leave cleanup with `ENOTEMPTY`. Qualify both carriers: `BH_TEST_ELECTRON=\u003Cdesktop executable> pnpm exec vitest run packages\u002Fcomputer\u002Ftest\u002Flocal-video-electron.test.ts` verifies two starts with zero downloads. Full archive installation, native UI readiness and mobile viewing remain separate acceptance steps.\n\n### Completed preparation PID reused by an unrelated process (#3519)\n\nA development Home can refuse recovery as `Home is in use` after its Host has stopped if an old launch record retains an exited preparation PID that the OS has reused. Successful preparation must retire its resource record only after process exit and descendant verification; live resources and unresolved cleanup remain protected. Old records are not automatically safe to remove: compare the process creation time, command ownership and Home listeners, preserve the original metadata, and remove only a proven stale entry. Never kill a currently live PID based only on an old record or weaken the ownership scan. This was observed during Android QA recovery; the unrelated application process was left running and normal startup succeeded after the verified stale entry was removed.\n\n### DSH 0.2.2-rc.2 Client anchors and Subagent requests (#4019)\n\nThe official macOS rc.2 Desktop removes `useAnchoredPosition` and replaces\n`Menu.getAnchorRect` with `anchorRef`. Opening a model picker with the old hook\ncrashes the Bot Client subtree even though Host boot and a plain DM work. The\napplication-owned anchored-panel adapter retains the native hook when exported;\notherwise it uses CSS anchors. The Menu adapter supplies the same trigger to\nboth generations. Verify focus, Escape, selection, zoom and constrained viewports\nin the actual Client; successful Host health does not prove this seam.\n\nThe rc.2 `subagents.startActivation` reads the live parent, prompt and child\noptions directly from the spec instead of from `spec.request`. Passing only the\nold nested request fails at `spec.parent.id`. The compatibility boundary supplies\nthe same request fields in both locations in one call, preserving the exact live\nparent, model policy, signal and delivery owner. Never retry a failed activation\nthrough a second API shape. Qualify caller-delivered and parent-delivered children\non both generations; a completed Assignment alone does not prove a native child.\n\nThe npm rc.2 CLI can lag the official Desktop feed. Inspect the signed Desktop's\nactual `__DSH_BOOT__.release` and archive digest separately from the public tag:\nthe tested rc.2 Desktop reports commit `a6b1b85`, whereas the public rc.2 tag points\nto `ddac96760b6edf8fa0fe17cbdcf0b512f4c12b2c`. Do not substitute a source tag for\nruntime artifact provenance or describe the Desktop run as npm qualification.\n\nFor an exact npm 404, run `scripts\u002Fdsh-npm-availability.mjs \u003Cexact-version>` and\nretain the timestamped JSON. A missing version is established only by the exact\nendpoint's 404 plus valid package metadata omitting that version; network\u002Fauth\nfailures remain inconclusive. See the [upgrade runbook](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-upgrade.md).\nIn #4024 both official rc.2 npm packages were absent while Desktop was available.\nOptional Desktop zoom uses the product's packaged, hash-checked Theme via a local\nlink, not an rc.2 npm Theme download. Do not change pins, weaken integrity checks,\nor treat the metadata probe as installation\u002Fruntime qualification.\n\n\n### Packaged member carrier checks (#4140)\n\nA bundled consumer can contain a second DSH Connection class. Its `instanceof` check then refuses the live Host's compatible service, leaving the member entry at `member-carrier-unavailable` while Owner RPC works. Check the required service capabilities at the boundary and invoke the Host's own `createPeer`, Gateway and resource APIs. Qualify the built package in an isolated Host; source tests sharing one constructor do not expose this failure. Keep the first refusal and verify the member's opening access snapshot, calls and streams before claiming shell readiness.\n\n### Revisioned Client evidence after an artifact swap (#4114)\n\nIn DSH 0.2.2-rc.1 (`c59d10a`), a revisioned `\u002Fplugins\u002F` URL identifies an advertised artifact generation. Fetching an earlier page's URL with `cache: 'no-store'` still requests that generation; it does not establish which Client the restarted Host currently advertises. A task-owned baseline check rejected this stale-URL observation before measuring. After stopping the owning Host, swapping only independent Client artifacts and restarting, read the new authenticated root document's `__DSH_BOOT__`, fetch its advertised UI batch and compare the complete expected execution segment after removing its source-map directive. Short prefixes and suffixes can match both builds. Preserve the rejected observation, resolved Profile path, artifact hashes and final restoration proof; do not clear caches, invent revisions or change Profile credentials to make the check pass.\n","# DSH development & debugging\n\n### Empty native credential writer lock after interrupted startup (#4114)\n\nOn Windows with DSH 0.2.2-rc.1, an interrupted task-Host startup was followed by a zero-byte\n`.credentials.yaml.lock`; a normal restart refused in the required Connection Plugin with\n`atomic-write: timed out waiting for the writer lock`. The installed native atomic-write\nowner recovers a lock containing an exited PID followed by a newline, but deliberately waits\non an empty or unrecognized record. A printed login URL alone did not prove Plugin health.\nThe exact creator of the empty record was not established; this is a qualified recovery\nprocedure, not a claim that startup cancellation always causes an empty lock.\n\nPreserve the failure and inspect the installed native lock code. Establish exclusion of other\nlaunchers and recovery attempts for this same Home before checking for live or unknown users;\nhold that exclusion through the lock-identity recheck and rename, and refuse recovery if it\ncannot be established. Then prove the exact task Home has no live or unknown users and that the unchanged lock is\na canonical regular zero-byte file with one link. Record its inode and nanosecond timestamps,\nrecheck them immediately before recovery. Retain the original by renaming only that lock\nto a timestamped sibling inside the same Home. Leave credentials and preparation markers\nunchanged. Unknown ownership, redirected paths, nonempty records or changed identity refuse\nthis procedure. Restart through the qualified lifecycle, require authenticated Plugin health\nand normal native lock release, and retain the backup and metadata. This does not authorize\nautomatic lock deletion, a generic stale-lock repair, or a longer startup deadline.\n\n### CredentialKey segments and opaque identifiers\n\nThe pinned native credentials service accepts lowercase letter\u002Fdigit\u002Fhyphen key segments. An opaque application ID can contain uppercase letters or underscores: hash the exact ID for its protected-record key and bind the original identity in the payload. Lowercasing the ID can merge distinct owners. Use `modifyRecord` for writes and keep route admission separate from per-device credentials. Verify protected writes and readback through the running Host, with secret-free output.\n\n### GenUI preview browser startup diagnostics (#4030)\n\nA passing plain timeline opens the Puppeteer driver, not the Host's separate GenUI\npreview browser. Record both executable versions and the runner image before\ncomparing them. The preview uses system discovery by default; the core Plugin's\n`genuiPreviewBrowserPath` selects an absolute executable through the same Browser\nruntime and refuses an invalid explicit path. `dev-instance.mjs` and `verify-app.mjs`\naccept `--genui-preview-browser \u003Cabsolute-executable>` and apply a Patch only to that\nisolated launch. They do not change system PATH or another Profile.\n\nOrdinary CI selects the lockfile-installed Puppeteer executable for preview too,\nso the preview no longer depends on the runner image's independently updated\nsystem Chrome. Its exact executable receives a temporary AppArmor profile allowing\nuser namespaces; the workflow unloads it after stopping its owned Hosts. A quick\n`startup-sandbox` refusal is a separate setup error from `startup-timeout`; preserve\nChrome sandboxing when correcting that permission. Merely setting\n`CHROME_DEVEL_SANDBOX` did not repair the controlled Ubuntu 26 runner (#4030).\n\n`genui-preview-browser-startup-timeout` means no DevTools endpoint appeared within\nthe existing eight-second startup deadline, before CDP connection or document\nrendering. Inspect the retained bounded\u002Fredacted preview owner log; do not infer a\nrich-document rendering regression from an empty rich sample set. The verify\nworkflow's `genui_browser_diagnostic` dispatch input runs system and controlled\nbrowser journeys sequentially on the same runner; both outcomes remain required.\nNo budget increase, product retry or incident-root-cause fix is implied.\n\n### DSH 0.2.2-rc.1 qualification\n\nUse [the recurring RC workflow](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-upgrade.md) and\n[the version-specific record](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-022-rc1-upgrade.md). RC tracking\ndoes not raise the `>=0.2.0-0` admission floor, and a new pin is not runtime evidence.\nOn RC1, select the Agent model before step preparation: Inbox claim precedes the\nloop's model snapshot, while prompt assembly is already too late to change that\nstep's route. The direct Orchestrator-child wake hook preserves historical Session\ngraphs from before #2968; current Orchestrators delegate through Assignments.\nQualify current Assignment background completion and next-DM model changes separately\nfrom legacy graph restoration. Keep asynchronous application authorization before prompt admission.\nNative tool execution now dispatches batches to scoped executors; direct CLI calls\nmust omit model-step logging and verify result identity. An executor disposer leaves\nan unavailable selection, so borrowed application handles must not own its lifetime.\nReviewer schema suppression belongs to the executor's description, not the prompt\npresentation waterfall or inherited-tool restrictions. Verify packaged module loading\nand both API generations in a real Host; source-tree imports can hide missing native\ndependencies.\n\nOn Windows, a retained development-Home resource PID can be reused by an unrelated\nprocess after the task Host exits. A resulting \"Home is in use\" refusal is not proof\nthat the old Host remains alive. Inspect current process identities and the exact\nHome before recovery; never kill a process just because its PID appears in the record.\nPreserve the stale owner record and recover only the verified task-local record after\nchecking that its Host and preparation processes have exited. Retain the refusal and\nrecovery evidence separately from the product restart result.\n\n### DSH 0.2.2 center column and Bot workspace qualification (#3665)\n\nThe real 0.2.2-rc.1 Web shell adds a center-column container between the main-panel\ncontainer and the grid frame. Assuming the main slot's grandparent is the frame\nsilently refuses workspace ownership and shows the Bot-mode sidebar fallback even\nat desktop widths. Qualify the bounded old\u002Fnew structural paths using the direct\nsidebar, rightbar and overlay markers, and mark the grid's center-column child,\nnot the nested main panel. Restore markers and the exact native sidebar command\non exit. Compare the running DOM and loaded Client identity before blaming cached\nassets; Simple\u002FAdvanced is a separate device-local preference. Browser verification\ndoes not qualify an installed Desktop upgrade.\n\n### Empty tool declaration series (#3137)\n\nDSH 0.2.1-rc.3 can record a `request\u002Fheader` with `startsSeries: true` and no tools.\nLater tool additions then all become deferred during LLM route projection, and DeepSeek\nrejects the request because no immediate tool remains. The active header alone hides this:\ninspect `session.toolHistory().tools`, not only `session.requestHeader().tools`.\nFor owned Bot Sessions, the pre-step owner requests a new declaration series after an empty\nbaseline, letting the native loop persist its currently assembled tools. This also repairs\nan already-failing restored Session. Do not invent a resident tool, rewrite prior events,\nweaken tool access checks, or blame an installed Plugin from the HTTP error alone.\nThe regression uses the real native Session fold and LLM projection in\n`packages\u002Fcore\u002Ftest\u002Ftool-declaration-series.test.ts`.\n\nBotHarness is a plugin layer inside DSH: unit tests do not cover the real boot. Every trap in this skill was invisible to `pnpm test` and only appeared in a running `dsh --profile web-dev`. **Validate against the running shell, not the test suite.**\n\n## Proactive Client verification\n\nAfter every isolated launch, Client reload and relevant UI action, read the real browser console and DOM yourself before accepting the result; do not wait for Human-copied errors. Read [the Client diagnostic loop](..\u002F..\u002F..\u002Fdocs\u002Fdev\u002Fguides\u002Fclient-startup-diagnostics.md) for the agent-runnable reader, bounded attempt history, background-tab\u002Ffreshness limits and native RC1 reproductions. Treat API health, Client shell evidence and browser-control failures as separate signals. Preserve first failure and each retry; recovery by reload does not establish a fix.\n\nOrdinary localhost pages do not open the application-defined development-refresh SSE. Add `?botharness-dev-reload=1` only while iterating on Client builds, then remove it for first-run or long-request UX verification.\n\n## Prime directive: `\u002Fapi` belongs to the API gateway\n\n### Timed-question recovery Registry trap (#4066)\n\nThe installed DSH `0.2.2-rc.2` Agent Registry resolves a live Session with `get(sessionId)`;\nit does not expose `roots()`. An invented `roots()` test double hid a real post-restart answer\nrefusal. Verify the exact installed Registry and native question Service contract, and exercise\nthe original durable `continued` call after restart. A rendered card or an `open` native call\nalone does not prove recoverable continuation. Keep application source authority distinct from\nnative answer state; the question's own Bot Source Event is not a fresh Memory admission.\n\nThe web client calls `\u002Fapi\u002F\u003Cendpoint>` over plain HTTP (`fetch` + auth cookie). The route and its **single interceptor** are owned by `@deepseek-ai\u002Fdsh-api-gateway`, which claims endpoints from the **typert registry** (all native controllers register there).\n\n- **Never** call `connection.rpc.intercept('\u002Fapi', …)` from a plugin. The slot is taken; a second interceptor shadows every native API (`settings\u002Fdescribe`, `llm\u002FlistProviders`, plugins, `directoryPicker\u002Flist` …) with a plain-text `404 not found` while your own endpoints keep working.\n- Expose plugin endpoints through the gateway\u002Ftypert claim path: a `TypertRemoteService` subclass with a `typertRemote` binding and remote-method markers (SRC, no codegen). `botharness\u002F*` migrated this way in #50 (`packages\u002Fcore\u002Fsrc\u002Fbridge\u002Frpc.ts`); native `@deepseek-ai\u002Fdsh-api-*` controllers are the reference.\n- Wire contract: `POST \u002Fapi\u002F\u003Cnamespace>\u002F\u003Cmethod>` with `{ type: \"client-request\", rpcId, method, payload: { args: {…named args} } }`; `undefined` fields are rejected by the decoder. Failures come back as a `server-response` envelope (`ok:false`), not HTTP errors.\n\n## Dev loop (WSL, fnm node)\n\n### Isolated dependency copies and legacy reuse (#4135)\n\nThe launcher installs fresh owned CLI runtimes and Profile dependencies with per-command pnpm\ncopy imports. Its completion marker records helper ownership; keep these installs helper-managed.\nUnmarked existing dependencies restart read-only when the requested runtime version and Profile\nmanifest are unchanged, with the normal runtime\u002Fmodel\u002FBundle checks. Legacy reuse also compares\nrequested dependency specifiers with pnpm's installed lockfile importer; missing or divergent\ninstalled records refuse without modifying the Home. A rebuild at the same source\nlink remains usable. Changing a legacy source link, Bundle dependency or runtime version requires\na fresh `--home`; `isolated-imports-required` preserves the old data and dependencies. Failed fresh\ninstalls remain preserved rather than receiving an implicit hardlink migration. The copy option\ndoes not retroactively detach existing files. Keep the old Home for backup or explicit migration.\n\nAn interruption during copy preparation leaves `installing`, including during a normal restart.\nAfter checking the exact Home's current processes, use the ordinary launcher with the same\n`--home`, `--worktree` and `--port` plus `--recover-copy-install`. The launcher still acquires\nthe normal Home lease and refuses live or unknown owners. It only recovers a recognized\ninterrupted copy install: it checks canonical paths, refuses symlinks\u002Fjunctions, retains the\nold dependency tree and preparation records under `.botharness-copy-recovery-*` inside that\ninstallation directory, then performs a fresh copy install. Database, credentials and Profile\ndata remain in place. The launch summary lists retained quarantine paths; never remove those\ntrees without the normal shared-file\u002Fownership audit. A failure remains incomplete and may\nneed the explicit flag again. Never manually change the marker to `complete` (#4172).\n\nOn Windows, two isolated runtimes shared native Client artifact inodes. An experiment on a private\ncopy confirmed that another hardlink changes ctime and the installed DSH metadata-based artifact\nrevision without changing bytes or mtime. Removing an existing live hardlink can itself affect\nother owners, so qualify future copies instead of repairing shared files in place. The original\n`session-maybe` incident's initiator remains unproven; this is an isolation mitigation, not a claim\nthat its Client lifecycle cause is fixed. The workspace-CLI fallback remains read-only and deliberate\nsource Client rebuilds still publish normally. Details: [local development loop](..\u002F..\u002F..\u002Fdocs\u002Fclient-bridge.md#7-本地开发环路).\n\nThe reproducible build baseline is `@deepseek-ai\u002Fdsh@0.2.2-rc.1`. The launcher uses the installed local CLI or an isolated `--dsh-version \u003Cversion>` installation, accepts DSH `>=0.2.0-0` including future prereleases, creates an isolated Web Profile, links all Bundle members as dependencies, enables only the `deepseekbot` umbrella, and probes the authenticated API.\n\n```bash\ncorepack pnpm build\nnode scripts\u002Fdev-instance.mjs --home \u002Ftmp\u002Fbh-020-web --port 31967 --json\ncorepack pnpm dev:client\n```\n\nThe launch summary includes the Host PID and local login URL. For Client edits, open the local Web tab with `?botharness-dev-reload=1`: tsdown rebuilds the linked Client bundle, and the opted-in development listener refreshes the page when the RC publishes a rebuilt frame. The Desktop Client HMR stream replaces the linked `@botharness\u002Fui` Fiber; BotHarness hands off the active Bot\u002FChannel selection during replacement. The Web development listener retains a full-page refresh fallback. For Host edits, build, stop that exact PID, then start the helper again with the same home and port; Host hot replacement is disabled in the pinned RC. Follow `docs\u002Fclient-bridge.md` §7 for the complete steps and measured timings.\n\nThe helper injects a shared machine-local DeepSeek key when available; `node scripts\u002Fdev-secret.mjs check` reports its source without a value. Existing Profile credentials are another DSH source. Confirm model access with a real DM reply. `node scripts\u002Fdev-secret.mjs adopt-profile --home \u003Cexisting-DSH_HOME>` copies only the DeepSeek reference into a private local file for later isolated Profiles.\n\nBefore launch and before finishing or handing off a run, follow\n[verification resource cleanup](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-resource-cleanup.md). The detached Host\noutlives the launcher: record its ownership, then verify process exit and port release before\nremoving its Profile or worktree. Keep a running environment only under the documented handoff\nor shared QA lease.\n\n\nThe launcher holds a Home-wide preparation lock and records the running Host before verification. A live owner prevents dependency\u002FProfile changes, even on another port or Profile. After a launcher exits, its recorded lock can be recovered; a lock without ownership evidence is preserved for manual inspection. On Windows, an unrecorded legacy DSH process whose Home cannot be determined blocks preparation until it is stopped. Startup verification failures terminate the owned Host and observed descendants, wait for exit, and preserve the Profile\u002Flog; an incomplete shutdown retains ownership for recovery. Go adapters containing the exact reviewed native fix skip the local patch; unknown or ambiguous request shapes remain refusals.\n\n\nPreparation commands now wait for an IPC start signal after their independent process-group ownership has been persisted. This covers installs, builds and configuration exports. Reusing a Home checks recorded groups even after the launcher or successfully handed-off Host exits. Failure cleanup stops the parent and repeatedly rescans descendants until release or a bounded refusal. Windows permits CLI paths explicitly belonging to another managed Home; ambiguous legacy CLI ownership remains a refusal.\n\nProfile names accept only letters, digits, underscores and hyphens; missing option values and invalid ports refuse before preparation. The profiles directory, selected Profile, manifest, workspace settings and model patch must not be symbolic links.\n\nOn macOS\u002FLinux, each preparation command also inherits a unique ownership marker, persisted before its IPC start signal. Process scans use this marker to find descendants that create a new session and outlive their parents; preparation refuses and stops such leftovers, and interrupted runs block Home reuse until they exit. Environment output is never logged. This is cooperative lifecycle tracking, not OS containment: commands that deliberately clear the marker must manage and register their own resources. Windows retains parent-chain tracking; independently reparented Windows daemons are not qualified by the POSIX regression and require separate resource ownership.\n\nRestart only after both the Host process and its HTTP listener have stopped. A closed port alone does not prove shutdown. On Linux, an exited zombie may still answer a PID existence probe; lifecycle checks use its process state and still check live descendants.\n\n## DSH 0.2.1 migration contracts\n\nSource inspection of `dsh-subagent\u002Flib\u002Ftypes\u002Ftypes.d.ts` and `lib\u002Findex.js` in `0.2.1-rc.2`:\n`startActivation` replaces `start` and `startContinuable`; `delivery: 'parent'` sends the result\nto the parent, while `'caller'` returns it only to the caller. Its signal owns startup only;\ncallers that retain cancellation ownership must connect later aborts to the receipt's `dispose()`.\nThe old `settleRun` export is gone. `dsh-client-connection` also replaces the shared `operator`\nwith per-Peer identity; Owner-only Remote methods check `invocation.peer.principal.kind`.\n\n### Supporting the 0.2.0 floor while building against 0.2.1\n\nUse application adapters for both API generations rather than raising the install floor to the SDK pin. Detect `startActivation` before starting; otherwise use native `start` \u002F `startContinuable`. Never retry a failed modern operation through the legacy path. Owner checks use the trusted native principal when present, otherwise the exact legacy connection operator object, never caller-supplied identity. Resolve native Shell Plugins from the running Host. A bundled scoped file Plugin must retain the reviewed `read_image` injection patch and adapt the missing `workingDirectory` service locally to the legacy Session cwd. Do not discard that patch by blindly externalizing file tools. A preset containing 0.2.1-only Plugins also fails on the old Host before an adapter can help. Conversely, the old persona `{{cwd}}` suffix fails at conversation assembly on 0.2.1, where that variable is no longer registered; do not inject it into the common preset. The legacy workingDirectory fallback must isolate that Service before providing it; Agent Scope alone does not isolate Cordis Services. Exercise two Agents and dispose one to prove the other retains its file tools. Check the entire boot log: a disabled native dependency can leave an apparently healthy Host with missing features. The product bundles the unchanged ComputerUseRegistry as an owned child Plugin to avoid an incompatible separately installed native manifest. Qualify the same packed product on both released versions; a SemVer preflight is only admission evidence.\n\n## Profile model\n\n- Isolated `DSH_HOME` (one directory per worktree\u002Fport); profiles live in `$DSH_HOME\u002Fprofiles\u002F\u003Cname>`: `package.json` (`dsh.profile.bundles`), `cordis.yml`, user patch layer `cordis.patch.yml`, `node_modules` (our bundles via `link:`).\n- `dsh web …` initializes the **`web` template** (`dsh-base` + `dsh-web-app`); a bare `dsh --profile \u003Cnew>` initializes the minimal template (`dsh-base` only). Our `web-dev` = web template + `deepseekbot`.\n- **Always pass `DSH_HOME`** — without it commands silently target `~\u002F.dsh` and initialize profiles there.\n- `cordis.patch.yml` is the bisect tool: disable a plugin (`- id: botharness-core` \u002F `disabled: true`) or override config, no reinstall needed.\n\nA saved AX model id may disappear from the pinned native catalog. Preserve the launcher's refusal; do not misdiagnose it as a missing credential or silently rewrite the shared selection. For this task's launch only, set `BOTHARNESS_AX_MODEL` to the current catalog model (normally `deepseek-v4.1-flash`), then verify an actual DM reply. The launcher retains catalog validation and the existing private key source.\n\n## Pitfall log\n\n### Windows background command consoles (#3565)\n\nOn a detached Windows DSH Host, a console executable launched by `execFile` without\n`windowsHide: true` can time out before entering its main function. In the task-owned\nTailscale fixture, alternating the flag on the same Host produced eight timeouts out\nof eight with the default, versus eight successful status reads out of eight with\nhidden consoles; the 3000 ms timeout stayed unchanged. Child spawn\u002Fstdout\u002Fexit marks\nand native entry records separated this from Host event-loop starvation. Use hidden\nwindows for noninteractive command runners. The detached-process regression in\n`packages\u002Fcore\u002Ftest\u002Fphone-route-windows.test.ts` exercises the real default route runner.\nThis qualifies Windows process startup, not a real Tailscale daemon or macOS behavior.\n\nThe Typert SRC gateway derives accepted named arguments from the registered Service method signature. Adding a Client argument and reading it in the application owner is insufficient: a missing facade parameter is rejected as `gateway\u002Farguments-invalid` before the owner runs. Keep the facade signature and forwarding payload aligned, and replay the same authenticated `\u002Fapi` request on a rebuilt isolated Host. A domain-only test cannot detect this boundary failure (#3215).\n\nIn DSH 0.2.1-rc.3, never give two Loader rows the same id across Bundle layers. A Bundle `insert` of an existing id such as `ui-theme` makes the Loader start the last row, but native Settings (`configEditor`) composes the Profile Patch and checks the first row; every write then fails with `settings\u002Frejected: Configuration for \"ui-theme\" is overridden by a home patch or command-line overlay`. The theme Client rolls back to the stored preference without a visible error. A non-insert Patch `name` is a selector, not a rename, so a Bundle cannot replace a native Plugin row; use a Profile-local package link instead. Reproduce by clicking Settings → General → Appearance → Dark and reading the `settings\u002Fmutate` reply (#2788).\n\nNative `dsh plugin add` reconciles newly installed Bundle packages into `dsh.profile.bundles`. Installing a renamed product Bundle beside the old one is not command-only installation. For the Tobs coexistence qualification, explicitly restore the previous Bundle selection before booting; for replacement, remove the old product entry and enable Tobs. Keep the same Profile, canonical data and Patch identities, and verify composition plus writes after restart. Never infer that package installation leaves the enabled Bundle list unchanged (#2722).\n\nAn AX launch pins `agent-default-model` through a command-line Patch. On DSH `0.2.1-rc.2`, changing that default through `onboardingModel` can therefore refuse with `Configuration for \"agent-default-model\" is overridden by a home patch or command-line overlay`. This is native configuration ownership, not a Remote Host transport failure. Preserve the refusal and unchanged default; verify preset writes separately. A no-op `home-model-set` does not prove the default can change. Qualify successful default changes on an unlocked isolated Profile, without editing another session's Patch or the shared AX selection (#2500).\n\nThe `tool-subagent-list-agents: never started` preset error can be an import failure, not a missing Service. In #2932, DSH 0.2.2-alpha.2 removed `dsh-tool-subagent-control\u002Flist-agents` and registers `list_agents` in the main Plugin; 0.2.1-rc.2 still exports the separate Plugin. The Bot preset adapter imports through the running Host's Loader and mounts the legacy child only when exported. Only the exact missing legacy export is accepted; other import and activation failures propagate. Verify both versions with `scripts\u002Fverify-subagent-control.mjs`. For a source checkout, use its `tsx\u002Fesm` hook, `TSX_TSCONFIG_PATH`, and `--source` so the test does not mix built and source Scope identities.\n\nNative approval `never` means reject before the answerer waterfall, even under `danger-full-access`; it does not mean automatic approval. In #2080, combining that policy with a BotHarness Human-only permission-management exception swallowed the intended card. Top-level Bot Full Access now uses `ask` and answers ordinary requests automatically at its existing application responder; delegated Subagents keep their native policy. Verify both an ordinary action and a permission-management Human card on the real Host.\n\nOn DSH `0.2.1-rc.2`, the first-run Preview Notice can hide a shell whose Settings entry now lives under the account menu. An older verification prelude that waits for a visible `Settings` button before dismissing overlays times out although Client diagnostics report `shell-ready`. Preserve the failure capture, dismiss the actual `Continue` dialog, then address the observed `Bot mode` or `Account menu` entry by accessible name. This qualifies shell navigation only; it does not establish a model reply or native IM delivery.\n\nRestored application runtime work can run before an undeclared native Service Provider loads. In #2056 a real held-draft Host restart resumed an Orchestrator before `ctx.credentials` existed and published a model-readiness failure, although the same configured key worked after startup. BotHarness now declares `credentials` in its required `inject` dependencies. A real Cordis\u002FLocalCredentialProvider regression starts the Consumer before the Provider and verifies readiness is not attempted until that Provider is available. Do not hide this race with a credential fallback, polling delay or suppressed failure; use the Service dependency lifecycle.\n\nWhen a DSH-side bug or trap is diagnosed, **record it here (or in the playbook) in the same change**. Entries:\n\n| # | Trap | Symptom | Cause \u002F fix |\n| - | ---- | ------- | ----------- |\n| 1 | `\u002Fapi` single interceptor | Native APIs 404 `not found`; custom plugin endpoint works | **Resolved in #50**: api-gateway owns the slot and claims endpoints from the typert registry; `botharness\u002F*` now registers a `TypertRemoteService` (SRC markers). Do not reintroduce `connection.rpc.intercept('\u002Fapi', …)`. |\n| 2 | Half-booted instance | UI loads, every API 404 | restart raced\u002Flost plugin layer; restart again and verify with the cookie probe (playbook §1) |\n| 3 | `pkill -f \"\u003Cpattern>\"` self-match | command dies with no output | the wrapper's own cmdline contains the pattern; use `[x]` trick (`pkill -f \"[n]o-open\"`) |\n| 4 | Shell variables eaten in nested wrappers | `$VAR`\u002F`$(…)` come out empty | write a script file for anything with variables; avoid inline `$` in loop commands |\n| 5 | `DSH_HOME` omitted | profiles\u002Finstalls land in `~\u002F.dsh` | always set `DSH_HOME` for every `dsh` command |\n| 6 | Installed inventory is not loaded code | Package Manager manifests can change while old Plugins still run | For #1980, read module-load snapshots on active Registry callbacks; capture installed composition before staging. Cordis 4.0.4 exposes `FiberState` as an ambient const enum, which cannot be imported with this repo's `verbatimModuleSyntax`; the adapter pins its verified ACTIVE value (2), covered by runtime qualification. |\n| 6 | Standard decorators not emittable | vitest `SyntaxError` on raw `@Remote`; tsdown passes decorators through untouched | this toolchain (oxc\u002Ftsdown) can't compile TC39 decorators — write the `@deepseek-ai\u002Fdsh-typert-protocol\u002Fremote-methods` descriptor manually (`version: 1`, `invocation: { kind: \"direct\" }`) and lock its shape with a test (#50) |\n| 7b | Agent created without an agent preset gets an **empty tool layer** | A BotHarness Orchestrator\u002FAssignment Agent can only call the tools its own setup registered (e.g. `channel_send`, `report_to_orchestrator`) — no file\u002Fbash\u002Fshell tools, so the model reports \"no tools\" | `dsh-agent-presets`: every session must join a preset (`CreateAgentOptions.meta.agentPreset`); an agent published without one \"resolves against the empty global layer\". Pass the bot's preset or a shipped default (`standard`) when creating agents |\n| 7 | `sidebar.panellist` row has no toggle or geometry seam | Clicking the active entry re-runs `selectPanel(id)` (a no-op), so the mode never exits; the shell row spans the full content box, 2px wider per side than the 新会话 row | Own the row from inside the glyph: render a wrapper span, target the shell button with `button:has(.bh-panel-glyph)` (`width: auto; margin-inline: 2px` = native `.newSession` insets), and while active render an `inset: 0` hit layer whose `onClickCapture` stops React propagation and calls `ctx.layout.selectPanel(null)` (`layout` must be declared in the plugin's `inject`) |\n| 8 | `Menu` `autoFocus` + `portal` drops the initial focus | The menu renders but no row is focused (arrow keys dead, submenu closed) | The primitive's autoFocus effect runs before its placement re-render clears the list's `visibility: hidden`, so `.focus()` on the hidden row is ignored. Re-focus the placed list in a `setTimeout(0)` after mount (see `ChannelMoveMenu`) |\n| 9 | Layout shift inside `dragstart` kills the native drag | `dragstart` fires, then a bare `dragend` with no drop; puppeteer's `mouse.drag()` hangs waiting for `dragIntercepted` | Chromium aborts the gesture when the `dragstart` dispatch synchronously moves the source row (e.g. revealing a `display: none` drop zone via React's discrete-event flush). Arm layout-taking drop surfaces one task later (`setTimeout(0)`); absolutely-positioned markers are safe synchronously. Diagnosed on the empty-section drop zone (#56 follow-up) |\n| 10 | Bundle member promoted to a top-level bundle | Boot fails with `duplicate loader entry id: botharness-core` | The `deepseekbot` umbrella patch already inserts core, client, browser and computer. Link all five packages into the profile, but keep only `deepseekbot` under `dsh.profile.bundles`; do not pass any member through `dsh plugin add`. |\n| 11 | `dsh.client.inject` is bundle grouping, not service ordering | Client bundle fails to import: `bundle … loaded without registering \"\u003Cpkg>\" via __ModuleLoader__.load`, often preceded by `duplicate factory registration` for a native module | Listing another plugin's package in `dsh.client.inject` makes the client-modules loader bundle that package **again** in your entry's group; a module that already registered cannot register twice. Keep `inject: []` for cross-package service dependencies and express them only with `ctx.inject(['\u003Cservice>'])` at runtime. Diagnosed in #164. |\n| 12 | Typert descriptor survives Host HMR | A client using a newly added RPC field gets `args fields do not match the descriptor: unexpected \"\u003Cfield>\"`, although the linked Host build contains that field | Remote method descriptors are registered at boot and are not replaced by Host HMR. After changing a `TypertRemoteService` method's parameter shape, build and restart DSH, then verify the endpoint with a no-write API probe. |\n| 13 | Connection Fetch route registered without its \u002Fapi prefix | An authenticated GET to the stream returns generic `not found` even though the plugin loads and unary RPC works | `connection.fetch.register({ path })` matches the full pathname. Register `\u002Fapi\u002Fbotharness\u002Fstream`, not `\u002Fbotharness\u002Fstream`; verify the exact route in a running Host. This is distinct from and does not replace the API gateway's RPC interceptor (#141). |\n| 14 | `ctx.uiWorkspace.pickDirectory()` throws on a deployment without a picker | `TypeError: Cannot read properties of undefined (reading 'pick')` at call time, although `ctx.inject(['uiWorkspace'])` succeeded and the workspace service answers | The `ui-workspace` client service is provided even when no directory-picker pair is mounted (the web-app bundle's `-auto` chooser mounts one asynchronously; a profile can also end up with none). Treat the picker as optional: probe it, catch the failure, and offer a manual path fallback instead of a dead button. Diagnosed in #168. |\n\n| 13b | One-shot login token needs two visits | hand-rolled `curl`\u002F`fetch` against `\u002Fapi` gets `401`, then `404 not found`, although the server is healthy | The first visit arms the login, the second returns the session cookie. The launch token remains valid for that Host process; the helper also saves a private cookie jar for automated probes. Use the login URL in a browser or the jar for authenticated API calls. |\n| 14b | Driving the bridge by hand | plugin endpoints look absent (`404 not found`) while native `\u002Fapi\u002Fsettings\u002Fdescribe` answers `200` | The bridge namespace is `botharness` (the short `n` in an early comment is stale): POST `\u002Fapi\u002Fbotharness\u002F\u003Cmethod>` with `method: \"botharness\u002F\u003Cmethod>\"`. Probe native and plugin endpoints separately before blaming the plugin layer. |\n| 15 | `setsid` on macOS | a manual restart script dies with `command not found: setsid` | This checkout also runs on darwin. Use `scripts\u002Fdev-instance.mjs` (detached spawn) or a `( nohup … & )` subshell; never a bare `&`. |\n| 16 | Streaming Fetch route also registered for GET | POST file upload commits, but an authenticated GET for the file returns an empty HTTP 400 | In pinned DSH `connection`'s HTTP bridge, `requestBody: 'streaming'` constructs a Fetch `Request` with a body for every method; Fetch rejects a GET body before the handler runs. Register distinct exact paths: a streaming POST upload route and a buffered GET download route. Rebuild and restart the Host after changing route registration, then verify both methods in a real browser (#146). |\n| 17 | No process-injected dev key is mistaken for no model access | `dev-instance.mjs` reported “model calls will fail,” yet a PersonaBot DM received a real streamed DeepSeek reply | `dsh-credentials-local` resolves inherited environment before `$DSH_HOME\u002F.credentials.yaml`, then project\u002Fhome `.env`. The AX helper now distinguishes a shared injected key from a profile credential. Confirm the profile source without printing values, then prove usability with a real DM → model → committed Channel reply. |\n| 18 | Runtime skill without explicit `source` lists but never loads | Skill appears in `\u003Cavailable_skills>`; every model `skill({name})` fails `Error: loaded skill \"…\" source must be a string` | Pinned `dsh-skill` `register()` defaults `provider` (→ `\"runtime\"`) but not `source`, while `validateDefinition` on the `get()` path requires both as strings. Always pass explicit `source` (e.g. `'runtime'`) and `provider` in `ctx.skills.register()`. Diagnosed live from an exported session zip (`session.v3.jsonl` tool\u002Fresult) in #248. |\n| 19 | Newer layout facet assumed present crashes client boot | `Failed to load plugins@botharness\u002Fui: can't access property \"subscribe\", ctx.layout.panelInfo is undefined`; whole browser UI dead | `panelInfo` exists in DSH 0.1.7-rc.2 but the composed `layout` service in some profiles lacks the facet. Guard with a `panelInfoOf` helper: skip view-persist\u002Frestore when absent (degraded boot beats dead boot). Contract test boots apply with a panelInfo-less layout stub. Diagnosed live in #357. |\n\n| 19b | Global DSH CLI shadows the worktree's RC2 dependency | The Profile serves 0.1.5 Web assets while the plugin was built against 0.1.7; Bot mode crashes with React's invalid element error because runtime icon exports differ | Launch through `scripts\u002Fdev-instance.mjs`, which runs and version-checks the target worktree's local CLI. Verify the browser's served Web asset and Profile before diagnosing UI data. |\n| 20 | RC2 Web fallback for BotHarness Client rebuilt frames | `pnpm dev:client` rebuilds in ~0.1 s and `\u002Fplugins\u002Fevents` broadcasts the new revision, but the open Bot mode still shows the old tree | Open the local Web tab. BotHarness's development listener performs a full page refresh on its own rebuilt frame; reopen Bot mode after refresh. |\n| 21 | Windows staged SQLite migration enters recovery | A fresh official Desktop profile can show `Operational database is in recovery mode: migration-failed` while adding a Workspace\u002FSession; the same fresh owner test fails on Windows | Node on Windows returns `EPERM` for `fsyncSync` on a file opened `'r'` and for directory `fsync`. The owner now opens the staged database `'r+'` before syncing and skips unsupported directory sync on `win32`. Reproduce with the fresh `mountOperationalDatabase` test plus a real Desktop session. |\n| 22 | RC2 Client Modules strips a package name ending in `\u002Fclient`; Desktop document reload after HMR can use a stale graph | `@botharness\u002Fclient` shows `prefetch(\"@botharness\u002Fclient\") — not a graph entry` in Built-in Plugins. Renaming the unpublished package to `@botharness\u002Fui` enables native linked-bundle HMR and the DM updates in place. After a later full document reload, Web boot may fail with `@botharness\u002Fui: import failed` | Upstream `stripClientSuffix()` treats the package suffix as an export subpath. With the corrected ID, a fresh Desktop document can still receive the old boot revision after HMR: old bundle URL 404, current graph URL 200. The plugin cannot recover before import. Keep Client development on native HMR, avoid full document reload after a rebuild, and cold-restart app plus Host after stopping the watcher when boot fails. Preserve the plugin\u002FProfile; inspect `%APPDATA%\\@deepseek-ai\\dsh-desktop\\logs\\crash-*-web-boot.log`. The packaged Desktop may omit the development-only Reload Page menu. See `docs\u002Fclient-bridge.md` §7 and ADR-0066. |\n| 23 | New BotHarness Orchestrator tool omitted from the internal Messaging allowlist | The model calls `list_bot_contacts`, but the turn parks on a Human tool-approval card before the Bot DM workflow starts | Add Host-checked internal Messaging tools to `BOT_TOOL_NAMES` in `packages\u002Fcore\u002Fsrc\u002Fworkspaces\u002Fgrant-execution.ts`; keep their sender and Channel membership checks in the owning Host command. Verify with a real model turn, not only an adapter fixture (#279). |\n| 24 | Fresh WSL Web Profile cannot create DSH's default Workspace | Native DSH shows “Unable to create default workspace” even when the Bot Client is healthy | `xdg-user-dir DOCUMENTS` can return `$HOME`; DSH rejects Home as its Documents directory. For an isolated QA Profile, set `workspace-controller` `config.documentsDirectory` to an existing Documents directory in `cordis.patch.yml`, restart that Host, and verify a native Workspace appears. This is DSH first-use setup, not a Bot Channel failure. |\n| 25 | Durable Bot Inbox recovery races DSH Agent Loop factory registration on cold start | An unobserved Assignment notice is replayed at BotHarness construction, then the Channel shows `no agent factory registered (load an agent-loop plugin)` even though a later DM works | `ctx.agents` may exist before `dsh-agent-loop` calls `setFactory()`. Treat that specific pre-execution failure as transient: leave the Inbox Admission retryable, retry with a bounded delay, and avoid publishing a premature Session failure card. Verify a pending notice across a real Host restart. |\n| 26 | DSH 0.2.0 UI timing and localization break English-only e2e selectors | Browser e2e times out at `.bh-root`, the create-dialog name input, or the send button although the same flow passed on 0.1.7 RC2 | The first-run notice button is localized (`继续`), menu items render a frame after their trigger, and the BotHarness composer swaps its `textarea` for the rich `[role=\"textbox\"]` once mention candidates load. In e2e scripts: dismiss with `['Continue', '继续']`, wait for `[role=\"menuitem\"]`\u002Fdialog selectors before clicking, and target the rich textbox after the composer settles. Diagnosed in #419\u002F#420. |\n| 27 | Windows isolated dev launcher cannot spawn `pnpm` and can time out before DSH serves | `spawnSync pnpm ENOENT` under fnm PowerShell, or `no token URL after 45000ms` while the Host later becomes healthy | Windows may expose only `pnpm.ps1`, which Node cannot spawn directly; resolve an installed Corepack shim on `PATH` and invoke its JS through the current Node executable. When Corepack is absent, invoke the installed pnpm JS or executable. Store log\u002Fcookie files under `tmpdir()` and allow a longer token wait for Windows startup. A missing model key can also leave a DM turn running; verify Memory Inbox startup admission independently of a real model reply. |\n| 28 | Windows Git subprocess stalls the DSH Host | Memory checkpoint requests take 77–169 seconds and unrelated Channel\u002FAPI loads time out; a `git.exe` child stays alive with near-zero CPU. A standalone Git invocation against the same isolated repo takes milliseconds | Node's synchronous Git launcher in the Windows Host can attach a console process. Set `windowsHide: true` on every Memory `execFileSync('git', …)` path. After the fix, the same checkpoint read took about 1.4 seconds, and changed-state captures took a few seconds. Keep separate DSH_HOME values for concurrent QA instances so their SQLite leases and Git repositories remain isolated. |\n| 29 | WSL shared key is invisible to a Windows-launched instance | An isolated Host reports `MISSING_CREDENTIAL` despite a key in WSL `~\u002F.config\u002Fbotharness\u002Fdev.env` | The AX helper resolves `homedir()` in its own OS. In the Windows terminal, use `node scripts\u002Fdev-secret.mjs adopt-env --from \u003CWSL-dev.env-path>` once, then `check` and restart that Host. The helper creates only the Windows user's private shared file and never prints the key; verify with a real DM reply. |\n| 30 | Agent-scoped native Subagent tools cannot be replaced or globally restricted by name | Registering another `subagent` in the Bot Agent scope fails with `tool \"subagent\" is already registered in this scope`; `tools.restrict({ deny: ['subagent'] })` says the name is not a known global tool | The pinned DSH preset registers native Subagent tools in Agent scope. Register Bot-specific names in that scope, guard native execution, and call DSH Subagent Service after checking the current Bot plan. A child Session uses DSH's native `never` approval override; its inherited Workspace Grant, mode, and cwd still need Host validation (#508). |\n| 31 | Session Remote namespace injected without its parent | Client boot fails before Bot mode appears after adding `ctx.remote.session` | Declare both `remote` and `remote.session` in the Client Plugin dependency list, as the native open-in-app Plugin does. A namespace declaration alone does not establish the parent Remote Proxy. Verify the real shell boot after a Host restart; unit Context stubs must model this capability too (#574). |\n| 32 | Native token-usage projection mistaken for an independently reported total | E2E compares Profile total to an absent `tokenUsage.totals.totalTokens` and fails despite matching provider buckets | DSH 0.2.0 RC1 projection totals contain four disjoint token buckets, not an independent total. Compare each known bucket; sum them only when all four are known. For failed or retried settlements, use the preceding durable `request\u002Fheader` or `request\u002Fcontext` route rather than a later successful Assistant source (#503). |\n| 33 | Bot settings navigation stops matching its decorated button | The native settings dialog opens, but the Bot settings shortcut cannot select its section after the Bot icon is installed | The first-party icon adds a third child to the original two-child nav cell. Exclude only that owned icon when resolving the label; do not require the decorated button to keep its original child count or assume its first span is text. Verify repeated settings opening in the real shell (#621). Decoration must be idempotent: compare the requested markup with a per-element cache, because serialized innerHTML also contains the injected media styles and otherwise an observer can continually rewrite its own DOM. |\n| 34 | Isolated Provider registered but native Consumer activated in the same pending Fiber | Native tool-fs says its confining filesystem has no sandboxPolicy although `provide` ran; preset-only service lookup may also miss Host-provided fs\u002FShell | Cordis `get` exposes a Provider only after its Fiber activates. Await the isolated Provider Fiber, then mount native Consumers as child Plugins and await their activation. Resolve `agentPresets.serviceFor` first and fall back to public Host capabilities when inherited. Native tools capture Policy at registration, so isolation alone does not replace existing closures. Wrap the actual `tools\u002Fexecute` body for per-call context: `tools\u002Fpre-execute` returns before body dispatch. Verified against pinned DSH 0.2.0 RC1 with actual native reads, writes and approved Shell outside Session cwd (#632). |\n| 51 | Packaged Profile install refuses ignored build scripts | `pnpm install` in the Profile fails `ERR_PNPM_IGNORED_BUILDS` for `agent-browser` once Browser joins the product | pnpm 12 requires explicit build approval per workspace. The packaged Profile installs the same tree the repo workspace adjudicated, so `packagedWorkspaceSettings` carries the root `allowBuilds` map (explicit Profile entries keep precedence; a drift test locks the copy to `pnpm-workspace.yaml`). Verified with a real `--product-artifacts` install into an isolated home (#1328). |\n| 52 | Mobile import recovery forwards create-only metadata | Marketplace import previews successfully but fails with `gateway\u002Farguments-invalid` before mutation | The API Gateway rejects named arguments absent from the Remote method signature. `botImportLookup` does not accept `origin`, while `createFromGit` does. Send only lookup fields during recovery; preserve origin for creation. A direct `BridgeMethods` test skips this boundary, so cover the real Typert Gateway with the mobile transport (#2768). |\n\n\n| 28b | Rebooting an isolated Profile drops its optional IM Bundle | dsh-im settings and transport disappear after running the AX helper again | The helper used to replace all dependencies and bundles. It now retains non-BotHarness dependencies and extra Bundle entries while refreshing its own linked packages. Keep the same task-owned home and verify native plus BotHarness APIs after restart. |\n\n| 33 | Core Host types change Client Context augmentation order | Adding a shared Core DTO type import makes Client `ctx.sessions.list()` resolve to a Host function requiring arguments | Keep the Client session-controller type import before shared Core DTO imports in `client\u002Factions.ts`; verify `pnpm typecheck` and the running native Client. Host and Client Context augmentations share a module name; DTO imports can change declaration order (#12). |\n\n| 34 | Optional Provider Service is published before its account registry is ready | The persisted receive grant is present after restart, but BotHarness shows reception unavailable; enabling again works | Service availability alone is not account readiness. Restore the same explicit grant with a bounded retry only for transient `provider-unavailable`; retain its token, revision and group scope, cancel on disposal, and verify automatic intake with a real Host restart (#12). |\n\n| 35 | Native approval requested from an idle Agent probe | A direct `ctx.tools.execute` probe returns `Human approval is unavailable` and no DM card appears | Pinned DSH 0.2.0 RC1 `approval.request` requires an open Turn to enclose `approval\u002Fasked` and `approval\u002Fdecided`. Exercise first approval with a real model Turn, then use native probes for already-authorized operation guards. Verify pending approval cancellation with another real Turn; a completed Agent is insufficient (#460). |\n| 36 | SRC Remote signature omits a newly supported named argument | Profile Save fails with `gateway\u002Farguments-invalid: unexpected \"delivery\"`, although internal bridge-method tests pass | The Gateway builds its named-argument descriptor from the public Remote method signature. Add and forward the argument in that method, not only the owning implementation; verify through `\u002Fapi` and cover the public adapter plus durable owner (#528). |\n| 37 | A saved Bot model preset differs from the resumed native Session request | QA Profile selects Pro\u002Foff but the next request\u002Fheader still records Flash\u002Fhigh in an existing Orchestrator Session | Verify the actual request\u002Fheader, not only the Profile preset or composer label. In the isolated DSH 0.2.0 RC1 QA Profile, explicitly selecting Pro\u002Foff in the native Session chooser emitted model\u002Fselection; the next request used Pro\u002Foff and completed, including after Host restart. The cause of the preset\u002Fresumed-Session mismatch remains unconfirmed; preserve original failures and do not silently rewrite the Session or add an IM-specific model workaround (#613). |\n\n| 38 | Native configForms scope methods lose their receiver in React | Settings crashes inside getSnapshot\u002Fsubscribe despite a ready native scope | Pinned DSH 0.2.0 RC1 scope methods use their instance. Pass stable useMemo closures that call scope.getSnapshot() and scope.subscribe(listener), rather than unbound methods, to useSyncExternalStore. Verify native volatile persistence after Host restart and cover a class-based scope fixture (#726). |\n\n| 39 | WebServer prefix registration includes a trailing slash | Extension POST\u002FOPTIONS falls through to generic 405 even though the Plugin and authenticated API work | Pinned DSH 0.2.0 RC1 WebServer matches `pathname === prefix` or `pathname.startsWith(prefix + '\u002F')`. Register `\u002Fmy-plugin\u002Fextension`, then call `\u002Fmy-plugin\u002Fextension\u002Fpair`. Check preflight on the running raw HTTP route. Connection fetch requests carry transport URLs, so enforce actual network peer checks at the WebServer adapter rather than interpreting `Request.url` as the bind address (#741). |\n\n| 40 | A native Tool approval does not prove Shell execution | A real approved Orchestrator `bash` call can still return `Path is outside this Session's authorized workspace`; a subsequent escalation request is refused | Treat native approval and execution as separate evidence. Inspect the actual persisted Tool result and Session cwd\u002Fauthorized Workspace, including macOS path aliases. Do not relax guards or infer a successful command from the working Projection alone. In #751's pinned DSH 0.2.0 RC1 QA, the granted Assignment path executed while another owned Session retained a native approval; the Orchestrator refusal's underlying workspace mismatch remains unconfirmed. |\n\n| 41 | Nested native Menus compete for Escape and focus return | Escape closes only the inner menu and focusing its trigger reopens the hovered submenu, leaving the sidebar settings menu visible | In pinned DSH 0.2.0 RC1, each Menu owns document key listeners and consumes Escape before returning focus. For coordinated sidebar settings, use one Menu for dismissal and keyboard walking, with MenuSurface and MenuItemButton for nested cards. Verify Escape after repeated selections in the installed shell, including overlay disclosure restoration (#807). |\n\n| 42 | Retrying a timed-out isolated launch leaves two Hosts for one home | API health responds, but Bot commands fail with `lease-unavailable` | A prior launch can leave its detached Host alive after a token wait fails. Before retrying, inspect that exact task home\u002Fport and its `botharness.writer.json` PID; stop only the task-owned Hosts, then cold-launch once. An authenticated API health probe alone does not prove the operational database writer lease is ready. Observed in #811 QA. |\n\n| 43 | A third-party tour shares Escape and focus with a native Modal | Escape dismisses both the tour and the native settings; closing the tour returns focus behind a newly opened Modal | Pinned DSH 0.2.0 RC1 native Modal handles Escape on document bubble and captures its invoking control. Give the tour capture-phase Escape ownership, remove its listener on dismissal, and retarget the actual visible native dialog after asynchronous opening. Driver.js 1.4.0 restores old focus after onDestroyed, so restore focus to the foreground dialog in a microtask after that callback. Verify the actual packaged Client with keyboard navigation and keep reduced-motion behavior covered (#824). |\n\n| 44 | Reused QA Session retains its frozen application role prompt | A newly accepted Memory edit is on disk, but the real model still follows the earlier QA no-reply instruction after Host restart | A persisted Session can retain application-defined role instructions for its lifetime. Verify the actual system\u002Fmessage and Tool results, not only the file or handled Inbox state. For a new QA behavior, start a new application-owned Session through its normal lifecycle; never rewrite Session events or loosen authority. In #905, the first real voice transcript was received but the existing Session deliberately made no external reply. The replacement QA Bot uses the same paired account only after the earlier receiver is stopped. |\n| 45 | Self-update through the Plugin Manager loses its own answer | Bot settings' Update now installs the newer `deepseekbot` (profile `package.json` and `node_modules` change), but the click never shows a result and the Web page reloads into the API-key prompt; DSH's own Plugins page refuses the same spec as `already-installed` | Pinned RC1 `pluginManager.installBundle('deepseekbot@\u003Cv>')` upgrades in place and returns `restart-required`, but the profile HMR reloads the Web document after pnpm, so the in-flight bridge reply is lost and the reloaded page serves the new Client against the old Host. Never rely on the RPC reply: derive the pending restart from `listBundles()`' `deepseekbot` version versus the version snapshotted at module load, and verify with a real old-version profile, a click, the reload, and a restart (#986). |\n| 46 | A plugin cannot restart DSH through any RC API | `dsh web` and Desktop expose no restart; `appExit` only stops the tree, and the launcher has no supervisor to start it again | Restart from the plugin by keeping the process alive: call `ctx.appExit(0)`, and on `beforeExit` (8 s fallback) spawn `process.execPath` with the same `execArgv` and argv (plus `--no-open` for `web`) as a non-detached child with inherited stdio. The terminal keeps the session and Ctrl+C reaches both through the process group. The signed browser cookie survives, so the Client polls `releaseInfo` until a new version answers and reloads. Desktop is unverified, so its Client shows quit-and-reopen instead (#986). |\n\n| 47 | PersonaBot creation passes a BotHarness model-preset ID as the DSH Agent preset | First native Orchestrator Turn fails with `Unknown agent preset` before any Tool executes | PersonaBot `preset` selects a DSH Agent tool preset (for example `standard`), not a BotHarness model preset. Apply the latter with `modelPresetApply` and verify the actual model request independently. Correct the QA configuration through normal Bot update, preserve the failed Turn and use a fresh authorized event; do not treat model-preset selection as native Tool availability (#906). |\n\n| 48 | Native Go adapter forwards Session identity without its required request header | A correctly configured DSH 0.2.0 RC1 Go request fails with HTTP 400 `MissingSessionID` | Native `llm-pi-ai` passes `GenerateOptions.sessionId` to the SDK but omits `x-opencode-session`. The reviewed pnpm patch supplies the actual Session ID only for Go, strips case-insensitive static collisions, and preserves native attribution and other Provider headers. The AX helper carries this pinned patch into an independent CLI per opted-in home. Never use a fixed\u002Frandom substitute header; retain the failed Turn and verify a fresh real model → `channel_send` → committed DM reply. Requalify before changing DSH version or removing the patch (#1079; [guide](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-model.md)). |\n\n| 49 | Windows Modify permission is insufficient for native workspace-write provisioning | Approved native Shell calls fail before launch with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(...)` | The RC1 Windows ACL backend needs effective `WRITE_DAC` and `WRITE_OWNER`; being the directory owner with Modify can still lack the latter. Use the installed `diagnose-windows-sandbox-acl` skill to inspect effective access. With explicit Human approval for exact QA directories, use its backed-up scoped repair, then verify the original confined Shell operation. Preserve owner, deny rules and sandbox policy; follow its restore-and-stop path if verification fails. In #911, real native Orchestrator and Assignment pwsh 30-second waits both succeeded after the approved repairs of their respective QA directories. |\n\n| 50 | Local browser permission display is mistaken for successful tool access | A listed allowed origin still returns ERR_BLOCKED_BY_CLIENT, or DOM reads work while screenshots\u002Finput time out | Qualify exact-origin authorization, listener ownership, Host transport, navigation and actual capture separately. Preserve each result and stop bounded retries without new evidence; see the [AX browser runbook](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fax-browser.md) (#1225). |\n\n| 51 | A new BotHarness-owned Tool is registered but omitted from the execution policy | The real Orchestrator pauses on a Human approval card for an own-Inbox read, although the Tool contract test passes | `grant-execution.ts` classifies checked application-owned Tools through `BOT_TOOL_NAMES`; registration alone does not exempt a name from generic operation approval. Add only the Host-scoped Tool whose own authority checks are implemented, cover `requiresHumanToolApproval`, then build\u002Frestart the exact owned Host and verify a fresh real model call. Preserve the first approval card rather than approving it to hide the omission (#1278). |\n\n| 52 | Native Settings navigation clicks an unrelated dialog trigger | Onboarding opens the mobile app popup or returns without a model editor | Do not select the first `button[aria-haspopup=\"dialog\"]`. In RC2, native Settings may be an Account menu item whose hidden shortcut contributes to `textContent`; match its accessible label, excluding `aria-hidden` content. A whole-sidebar Bot mode shadow must yield while the native settings shell is needed, then restore on close, timeout or cancellation without switching the main panel. Verify the actual Models page (`Add model provider`), not a generic `Models` label also present in onboarding (#3222). |\n\n| 53 | A gateway concurrency refusal ends the Bot turn without retry | Several Bots woken at once on a serial local model fail within seconds with `PI_AI_ERROR: Concurrency limit exceeded for user, please retry later`, while one direct DSH chat queues and succeeds | Native `llm-pi-ai` classifies failures by text; an in-stream refusal without `429` or `rate limit` becomes non-retryable `PI_AI_ERROR`, so `dsh-llm-retry` never runs, and its default normal budget (5 retries, about 15 s) would be too short anyway. A repo pnpm patch only changes AX\u002Fdev runtimes, never a user's installed DSH. BotHarness owns the fix on the public `agent\u002Frequest-error` waterfall (`runtime\u002Fbot-request-retry.ts`): Bot Sessions retry concurrency-limit, too-many-requests, server-busy and `RATE_LIMIT` failures with 1–10 s backoff for up to 300 s, delegating providers set to `retryPolicy.mode: always` (#3300). |\n\n### Idle Assignment native child wake (#3477)\n\nA DSH-native background child can wake its idle Assignment parent without an application-defined\nAssignment run. Native `turn\u002Fstart` and a relay alone do not restore the report tool's execution\nauthority or its Adapter run context. At claimed-input prompt assembly, validate persisted direct\nSubagent ownership, current Grant\u002FSource, stop\u002Farchive and Bot availability; reacquire application\ncapacity and establish the real Assignment run before continuing the already-claimed input. Do\nnot replay the relay as a followup or change the idle direct-tool guard. Join native `whenIdle`\nand record the actual later Turn's report\u002Fcompletion, then release capacity. Waiting capacity\nuses cancellable commit notifications, not an idle polling loop. Qualify newly frozen bytes with\na real model, native events and the canonical report; fixtures are not native acceptance.\n\n## Reference\n\nFor opted-in AX Go launches on Windows, stage the reviewed adapter patch inside the isolated\nCLI and reference it relative to that CLI's workspace. A drive-qualified absolute pnpm patch\npath can be appended to the runtime path, causing `ERR_PNPM_PATCH_NOT_FOUND` before Host boot.\nVerify staged bytes, preserved workspace settings, and a fresh real DM reply; configuration and\nAPI health alone do not establish model access. Diagnosed with source on D: and home on C: in\n[#1409](https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fissues\u002F1409).\n\nIn pinned RC1, `defineTool` nested object properties mark requiredness with per-property `required: true`; an explicit JSON Schema `required` array is rejected by the authoring DSL. Native `bash` output is a structured foreground\u002Fbackground\u002Fpromoted union, so an interception must preserve the registered result schema instead of returning a string as `value`. #1380 verified both failures through a real PersonaBot; tool-registration\u002Fschema and real runtime checks cover the correction.\n\nNative MCP stdio uses SDK-owned spawn, not the Shell\u002FSubprocess Provider. Its automatic protocol negotiation starts a disposable probe sibling before the live server: a fixed Docker container name conflicts, while a per-owner label lets teardown remove every sibling. Native `dsh-scope` owns a module-local Symbol and WeakMaps; bundling another copy makes native Agent Contexts appear unscoped to the copy. Keep Scope external and resolve the same pinned peer as the Host; verify two real Agents concurrently, not only a raw-source single-Agent test. On Windows the preset's Shell Provider may be PowerShell even behind the `bash` Consumer name; launch a trusted executable with Subprocess argv instead of assuming POSIX Host syntax. The pinned Node image must actually include the Guest shell. These were diagnosed in #1380.\n\nNative Tool Registry `schemas(scope)` and `get(name, scope)` include inherited global and ancestor registrations. A name prefix does not establish an execution boundary; MCP server-name reservations are scoped too. For controlled installation, snapshot pre-install identities and exclude identities visible globally or in every ancestor from the post-install qualification. Verify inherited Host sentinels, including those registered during asynchronous startup, are denied while concurrent Agent-owned Guest tools execute. Use public `scopeParentOf`\u002F`scopeChainOf` rather than private Registry internals. This was reproduced against RC1's native Registry and real Docker in #1380.\n\nPinned DSH 0.2.0 RC1 selects one directory picker interaction at boot. A loopback Windows Host commonly serves native; uiWorkspace.listDirectory() then throws DirectoryBrowseError with rpcError.code = directory-picker\u002Funavailable. A consumer may fall back to uiWorkspace.pickDirectory() only for this capability refusal; unreadable directories and other failures remain errors, and cancellation returns no selection. Authorization still follows an explicit Human choice.\n\nFor isolated browser E2E on Windows, pin the browse pair in that task-owned Profile overlay: disable the directory-picker auto entry, then use a Patch insert list to compose @deepseek-ai\u002Fdsh-host-directory-picker-browse and @deepseek-ai\u002Fdsh-client-ui-directory-picker-browse. A bare new id\u002Fname patch does not insert a Plugin, and changing the name on an existing patch does not swap its implementation. Stop and restart that exact Host, retaining loopback bind and one backend. Verify the running folder-selection path. See the [upstream picker contract](https:\u002F\u002Fgithub.com\u002Fdeepseek-ai\u002Fdeepseek-harness\u002Ftree\u002Fdsh-v0.2.0-rc.1\u002Fpackages\u002Fhost\u002Fdirectory-picker).\n\nFor multi-window headless checks, set the intended viewport on each new page before entering the UI. A fresh page defaults to a narrow viewport, where the DSH sidebar can collapse to icons; a selector waiting for visible Bot-mode text then times out despite a loaded, authenticated shell. Use independent browser contexts with the authorized local session when validating stale replies, and submit through the visible Client action.\n\nDSH 0.2.0 provider token reports use disjoint uncached input, output, cache-read and cache-write buckets. Optional cache fields may be absent even when an exact total is reported: absence is unknown, not zero. `deriveTurnTokenUsage` may return no result when exact lifecycle or usage evidence is incomplete; never substitute token-meter context estimates for observed provider consumption. Read the durable Assistant settlement's actual source route rather than a configured model. Verified with the installed token-meter contracts and a real model request in #499.\n\nPre-execution refusal can leave an application-owned Session ID without a DSH Session. Before retrying that reserved identity, use Session Persistence `stat(id)` to distinguish an absent stored Session from an existing one: create only when `stat` returns `undefined`, and propagate storage failures. Do not infer persistent existence from the live Session Store or blindly resume a reserved ID. Verified against DSH 0.2.0-rc.1 in #500 with a rejected model route followed by a successful Human repair.\n\n- **DSH source checkout**: `reference\u002Fdeepseek-harness` (gitignored, in this worktree) must match the installed tag, now `dsh-v0.2.1-rc.2`. Read the TypeScript source (`packages\u002Ftypert`, `packages\u002F*connection*`, `packages\u002F*gateway*`, `apps\u002Fcli\u002Freference\u002FREADME.md`) when the how\u002Fwhy matters; the installed `lib\u002F*.js` is bundled output. Re-pin when DSH is bumped: `git fetch --depth 1 origin tag \u003Ctag> && git checkout \u003Ctag>`.\n- `references\u002Fdebugging-playbook.md` — boot verification, status-code semantics, WS mux probe, bisect recipes, headless puppeteer probe.\n- `references\u002Fprobe-web.mjs` — headless browser probe (console errors, failed requests, WS, internal fetch); run from the repo.\n- `dsh-ui` skill — in-harness UI rules; `docs\u002Fclient-bridge.md` §7 — dev loop; ADR-0023 \u002F #50 — bridge transport contract.\n\n## Additional verified pitfall — #1425\n\nAn exact DSH peer in any composed Plugin can reject installation before its code is imported.\nThe build pin is not the supported Host floor. Product declarations use `>=0.2.0-0` (1.2.x releases declared `>=0.1.7-0`; the floor moved in #1511) with native\nprerelease semantics and no future-version ceiling; preflight acceptance is not runtime qualification.\nCheck Core and the product-managed Provider together. Preserve each release train's immutable\nProvider source and runtime digest, and qualify its own packages rather than borrowing a maintenance\nrelease's E2E result. Do not use compatibility exemptions as release evidence (#1425).\n\n## Additional verified pitfall — #1138\n\nIn #1459, two real composer tabs showed repeated recovery checks; the store regression independently reproduced redundant durable writes for unchanged recovered text. Publishing a new identical version makes peer tabs request validation again. A no-op validation must retain the durable version, while removal of an invalid reference is persisted once. Keep transient validated reference metadata in the local snapshot without publishing a new unchanged record; verify both idle synchronization and explicit conflict selection against the rebuilt Host. A passing HTTP API probe alone does not qualify a browser whose request slots are occupied.\n\nFor a fresh pinned RC1 local Profile, let native initialization create the Profile directory before applying a task Patch. Precreating the directory makes the native default-profile initializer refuse its destination; initialization also creates an empty `cordis.patch.yml`, so merge intended entries instead of moving another file over it. Preserve native entries, then restart the helper's exact verified Host PID. This was reproduced in #1381.\n\nThe pinned native local Credentials Provider retains record objects in its cache. A trusted private-input owner that clears its incoming submission object must copy the values into the atomic grant payload before handing it to the Provider; otherwise clearing the request also clears the cached grant. Validate the published Host through an actual credential consumer, not only disk serialization. A Fiber's disposal must also drain already-started recovery writes before its storage Providers can close. These native ownership and lifecycle interactions were verified in #1381; the request settlement policy remains application-defined.\n\nA new root overlay must budget its long-lived Connection Fetch streams with existing pages. In official DSH 0.2.0 RC1 Windows Web, adding a separate companion SSE alongside the Bot-mode Activity, Channel and roster consumers left real DM sending pending until Bot mode exited. Reusing the companion's full Activity snapshot for the shared Client Activity store and closing the redundant Activity SSE restored three genuine DM submissions within Bot mode. The symptom is consistent with the per-origin HTTP\u002F1 connection limit; an exact wire connection count was not measured. Validate an actual DM reply while both the overlay and owning page remain visible. On removal, restore ordinary Activity demand; keep listener\u002Fframe\u002Fheartbeat disposal bounded and never weaken authentication to work around the symptom.\n\n## Additional verified pitfalls — #1339\n\nBrowser-bundled dependencies can defer `process.env.NODE_ENV` reads until a control first renders. In #1377, the RC1 Client booted and jsdom interactions passed, but opening the new table crashed the native main Slot with `ReferenceError: process is not defined`. Define the production environment constant at browser build time, retain native React\u002Fprimitive baseline externals, and verify the built Bundle contains no runtime Node environment read plus the actual dialog in the running shell. Do not add a global `process` shim or count a successful initial boot as proof of the interaction.\n\nOn native Windows 11 with DSH 0.2.0 RC1, a real pinned Chrome cold download produced Host progress while the panel's observation took about 81 seconds and showed only Opening. Separate authenticated observations returned bytes immediately. Making the duplicate localhost development-refresh SSE opt-in restored panel percent\u002FMB and 4–5ms observation responses during another real cold download. Preserve ordinary Bot-mode streams and native admission; do not add another progress SSE or treat successful Host polling as Client evidence.\n\nPinned Chrome 154.0.8037.57 can expose DevTools before its first window exists on a fresh Windows browser profile. Explicit `Target.createTarget(newWindow: false)` then refuses with `Failed to open new tab - no browser is open` (a CDP response, not stderr). Omit `newWindow` for background tabs so Chrome selects an existing window or creates the first one, retaining `background: true` and `focus: false`; verify with the real fallback E2E. A task-owned binary marked `Zone.Identifier` \u002F `ZoneId=3` spawned successfully, while moving it immediately before native spawn produced ENOENT \u002F errno -4058 and the existing startup-spawn-failed cause\u002Faction panel. These observations do not justify a new Windows stderr kind or a claim that every antivirus behaves the same.\n\nProvider configuration must be checked against the composed production Controller, not only its bare class. In #1111, dsh-im workspace decoration attached asynchronous catalogs to `registrationStatus()`: the native QR had been generated, but setup reported `setup-failed` when it read a Promise as status. Await the public Controller result and exercise the actual wrapper plus async catalogs through the public setup transport. Verify generation\u002Fpoll\u002Fcancel again in the packaged Host; this does not qualify a new platform pairing.\nA native credential write may commit before its response fails. Application-defined owners must recognize success only by canonical readback of their newly generated opaque revision and exact target grant, rather than treating any current record as success. In #1382, injected post-commit failures proved that unconditionally failing could leave local revocation committed without attempting a running-use stop. Account activation must precede configured Channel publication, with both proofs required at consumption. Startup recovery must finish before Owner mutation APIs admit new grants, otherwise cleanup can mistake an in-flight replacement for an orphan. These behaviors were verified against the pinned RC1 local Credentials Provider; application account lifecycle policy stays outside DSH Context.\n\nQualify a passive model-request probe against the actual selected adapter. In #1383, a DeepSeek-only URL filter would miss the native Go route; the probe now recognizes the observed `\u002Fmessages`, `\u002Fchat\u002Fcompletions` and `\u002Fresponses` paths and records whether the body was available. Clone a Request only when no body override exists; non-string overrides are incomplete evidence, not a clean scan of the original body. Windows `NODE_OPTIONS=--import` requires a `file:\u002F\u002F\u002F` URL, and a synthetic canary file belongs outside DSH_HOME so storage scans do not mistake test instrumentation for leakage. The probe preserves fetch payloads and authentication headers and never records either; unsupported routes or encodings remain unqualified. Verified against pinned RC1 Go requests and isolated body-override regressions.\n\nIn pinned RC1, an exported native `createMcpToolDefinition` input schema with `additionalProperties: false` did not itself reject extra arguments at the adapter entry. Enforce the admitted parameter set in a trusted Consumer before resolving confidential values or invoking a private transport. Verify a real native Tool call with an extra parameter, not only schema inspection. The SDK stdio Client also merges selected default environment names when `env` is supplied; explicitly override inherited names when a fixed child must exclude ambient credentials. Both behaviors were verified in #1384 with the installed native adapter and SDK.\n\nCross-platform Profile migration needs a separate path-metadata audit. In #1386, the qualified dsh-im Provider returned `feishu-startup-config-invalid` and no accounts because its copied `integrations\u002Fdsh-feishu\u002Fworkspaces.json` contained an absolute Windows workspace that is invalid on Linux. The native management `connection.status` surfaced the startup error; translating only the audited source-home workspace field and restarting the exact task-owned Host restored the same account and sole receiver. Native Session header cwd\u002Fproject keys and application ownership metadata also need bounded translation; preserve immutable Session Event frames and the native credential store. A Linux bind-mounted workspace additionally needs the guest UID's POSIX access: Docker Desktop success does not qualify Host umask, directory traversal or file-write behavior. See the [Linux qualification guide](..\u002F..\u002F..\u002Fdocs\u002Fdev\u002Fguides\u002Fprivate-input-linux.md).\n\n## Additional verified pitfalls — #1490\n\nApplication-defined long-lived SSE responses share the browser's HTTP\u002F1.1 per-origin budget (about six) with native HMR. With six held, every ordinary request in every same-origin document timed out while an independent authenticated request still answered at once; the identity, model and message loading states are consequences, not a rejected token. Count long-lived responses per document (HMR included) before adding one, test with one more document than you expect to support, and carry application streams as stream-mode Remote methods on the Gateway's multiplexed socket (ADR-0181). In-flight EventSource requests do not appear in Resource Timing; read the network list instead.\n\nA source-declared stream method needs more than a unary bridge method. Host: mark it `mode: 'stream'` and name its final parameter `signal`. Client: `ctx.remote.$mount` a contribution whose descriptor repeats namespace, method, `mode`, parameters and `cancellation`; every parameter needs a `strict` codec (`create` returning an object with `parse`), while the result may stay `src-json`. Open it through `ctx.remote.$stream`. The mounted namespace is its own Cordis service: read it with `ctx.get('remote.\u003Cnamespace>')` from the mounting Plugin's Context. Reading `.\u003Cnamespace>` off a captured `ctx.remote` object returned nothing, and the stream never opened with no console error. The supervisor retries carrier loss only; a normal Host end or a thrown item is terminal, so the application retries it. Guard `$mount`\u002F`$stream` for older Hosts. Verify with an authenticated open frame on `\u002Fapi\u002Fremote.mux` and with a real page refresh after a Host change, not with unit stubs alone.\n\nTo use the Gateway Client's stream helpers (`RemoteSnapshotStream`, `RemoteJournalStream`, `RemoteStreamCarrierError`) from an application Client bundle, declare `@deepseek-ai\u002Fdsh-api-gateway\u002Fclient` under `dsh.client.external` in the package manifest and externalize the same ID in the bundler, as the official workspace and session controllers do; `dsh.client.inject` can stay empty. That module is a browser closure bundle and throws `window is not defined` when a Node test imports it, so alias it in the test runner to the package's per-file modules under `lib\u002Ftypes\u002Fclient\u002F`. Return a `RemoteStreamCarrierError` from `ended(accepted)` once the baseline was accepted so a normal Host end is retried by the supervisor; any other error makes the snapshot stream terminal (#1498).\n\nA `RemoteError` thrown by a stream method before or between items reaches the Client as an `error` frame with its `code` and ends that logical stream as a terminal failure, not a carrier loss; map application refusals (unknown subject, cursor ahead of the log, invalid cursor) to stable codes and let the consumer decide whether to reload state. When a stream replaces a legacy route, make the subscription a single typed frame source and let both the stream and the route encode it, so their replay and baseline rules cannot drift (#1500).\n\n## Additional verified pitfall — #1528\n\nThe pinned client-modules loader claims every `\u003Cstyle>` without `data-plugin` for the module materializing at that moment (lazy chunks included) and removes those tags when that module is replaced, invalidated or pruned. A plugin that injects an untagged sheet from an effect can therefore lose it to another plugin's reload while it stays active: its UI renders unstyled and DSH's own UI, whose sheets are tagged, looks fine. Set `data-plugin` to the injecting module's id (and a `data-plugin-css` key) on every runtime `\u003Cstyle>` (#1528).\n\n## Additional verified pitfall — #1154\n\nQualify an external Provider's exported Service contract, not only a test fixture or internal sender. In a DSH `0.2.0-rc.2` Host, dsh-im `.20` exported `receiptVersion: 1` and advertised QQ `proactive-fence-checked` per account, but did not export `postFenceVersion`. Requiring the absent global field incorrectly hid a checked QQ post. Consume the actual per-account text, receipt and fence capabilities; still pass the final fence, refuse missing capabilities before native effects, and verify the real saved target's `canPost` after rebuilding and restarting the task Host. This capability proof does not establish QQ permission or rendered delivery.\n\n## Additional verified pitfall — #1155\n\nDirect Controller and Runtime tests do not qualify the application-defined Provider's production factory. In a DSH `0.2.0-rc.2` Host, real QQ plain text reached the native SDK but ordinary delivery stayed unverified because the factory dropped the consumer's `ordinaryText` accessor. Cover the actual production factory through the exported Delivery Service and Runtime, then rebuild and install the immutable Provider artifact. Verify a fresh native event on the new receiver lease; replaying the failed event does not establish recovery. Ordinary delivery qualification and explicit collection opt-in remain separate checks.\n\n## Additional verified pitfall — #1988\n\nThe pinned dsh-im Provider (`beaed4a6`, DSH `0.2.0-rc.2`) exports checked WeChat proactive text, receipt and final-send fence capabilities per account, but no global `postFenceVersion`. Requiring that field hides a real paired-owner forwarding target even though reception is ready. Qualify the account capabilities and receipt contract, pass `beforeSend`, and reject any missing capability before an external effect. The real Host reproduced `canPost: false`; the contract regression omits the legacy field and retains missing-capability\u002Ffinal-revocation cases. Actual phone delivery remains a separate E2E check.\n\n## Additional verified pitfall — #2017 pointer menus\n\nIn the pinned DSH `0.2.0-rc.2` Web Client, native `Menu` with a viewport `getAnchorRect` and a body portal uses CSS positioning coordinates that diverge under body CSS zoom. At 125%, a click at `(136.25, 20)` rendered the popup at `(170, 30)`; 100% retained only the native dropdown gap. The application `ds\u002FPointerMenu` now measures the rendered scale and native popup rectangle, owns the body portal and viewport\u002Ftraffic-light clamping, and leaves ordinary anchored dropdowns native. Callers pass raw viewport points, without local correction constants. The isolated Web regression covers normal\u002Fzoomed placement and edge avoidance; native macOS remains a separate check.\n\nThe rc.2 native `Menu` handles Escape by calling `onClose` and then restoring its own anchor focus. A pointer menu's placeholder anchor contains no trigger button, so its fallback can focus the closing menu row after the application synchronously restores the Panel header. `usePanelMenu` defers trigger focus to a microtask, after native dismissal, and only focuses the same still-connected trigger. This also avoids focusing a header removed by Close. Restore only when focus remains on the closing menu or page body; an outside click that focuses the composer must retain that focus. Verify Escape and Shift+F10 on every Panel header in the workspace journey.\n\n\n## Additional verified pitfalls — #2034\n\nIn rc.2, the Client shortcut catalog can expose a newly registered command before the native preference adapter accepts its definitions. An immediate revision-checked edit can return `not-ready` (or `stale` after a concurrent config publication). Retain accepted bindings and retry those transient outcomes with a bounded delay; show a migration refusal only after the bound or a terminal result. A real old-to-new Web Client upgrade qualified the custom-binding migration and dispatch.\n\nThe native Workspace navigator clears a current Session that appears in `archivedSessionIds`. Opening an auto-archived Assignment directly can leave the landing screen and log a released Sidebar Session reference. Restore the Session through its existing explicit archive action before qualifying navigation; merely leaving an application panel does not prove the target opened. The real rc.2 journey verified the same restored Session ID and visible report from both application views.\n\n## Additional verified pitfalls — #2054 evaluation\n\nIn the pinned DSH `0.2.0-rc.2` Session log, `request\u002Fheader` records request configuration; it is not a per-turn generation barrier. The real two-Bot diagnostic had one header but later `step\u002Fstart` events in additional turns. Use native `step\u002Fstart` timestamps to establish that generation began, and separately record application draft frames and canonical message commits. A missing later header does not prove the Bot never started that turn. Preserve the original misclassified diagnostic when correcting instrumentation.\n\nSumming only `assistant\u002Fmessage` usage omits failed native `assistant\u002Fattempt` events. The same diagnostic recorded an attempt ending with `TRANSPORT` and no usage before a successful response. The existing Host Usage Projection correctly returned unknown totals for that Bot. Export failure metadata and any reported usage separately; completed-response totals are a lower bound, not a replacement for unknown full usage. Retain unknown auxiliary\u002Fprovider retry coverage and omit hidden reasoning chunks from public evidence.\n\n## Additional verified pitfall — #2089\n\nIn rc.2, `tools.restrict({ deny: [...] })` validates names against the global Tool registry even when called from an Agent scope. Naming an application-defined Tool registered only in that Agent scope, or intentionally omitted there, fails Agent setup with `names unknown global tool` before the model runs. Tob creation reproduced this on macOS Desktop with `bot_create`. Omit the legacy registration and use an Agent-scoped `tools.guard` for execution refusal, retaining the callback's current-run authority check for stale references. A mocked restriction collector cannot qualify this behavior; test the pinned `ToolRuntime` with real Cordis scopes.\n\n## Additional verified pitfall — #2056 verification transport\n\nAgainst an idle RC2 Host on Windows, Node's pooled `fetch` reproduced `ECONNRESET` after the probe's event loop was blocked for six seconds: it reused a connection whose close event had not been consumed. An asynchronous six-second wait and a request with `Connection: close` both succeeded. The `verify-app` RPC helper uses one connection per request; it preserves a lost mutation response as an error instead of retrying a possibly committed write. Distinguish this test transport failure from a model-provider failure, and correlate Host health with any deliberate restart before diagnosing a crash. Preserve failed cohort attempts; register changed transport settings before a new comparison rather than replacing old results.\n\n\n## Additional verified pitfall — #2192 Desktop approvals\n\nIn DSH `0.2.1-rc.2`, the native API remotes approval answerer can run before an application's Channel answerer and hold a Session-backed approval without calling `next()`. Native Session events then show `approval\u002Fasked`, but no application Channel card appears and the command times out. Register the application-owned answerer with Cordis `prepend: true`, retaining exact Agent\u002Fcall tracking and owner checks, and delegate unowned requests to `next()`. Native `never` policy still refuses before the waterfall. An isolated macOS Desktop reproduced the missing card; after this change, approving once visibly created a Bot and group through Tob's CLI. Regression coverage must exercise an earlier swallowing answerer, delegation, cancellation and native policy denial; do not bypass approval to make the journey pass.\n\n## Additional verified pitfall — #2221\n\nDeepSeekBot 1.4.0's workspace shell explicitly refused `html[data-windows-titlebar]`, so a Windows Desktop could load current Bot features while retaining the old sidebar. This is a platform fallback, not proof of a stale npm package or cache. In DSH 0.2.0-rc.2 and 0.2.1-rc.2, the native layout reserves the Windows title bar with frame padding; the preload menu is a body-level shadow root and caption buttons remain Electron-owned. The workspace can claim the existing content columns without replacing that frame or its padding. Preserve structural qualification, overlay ownership and disposal; do not clear user layout state or disable native drag regions. Source regression tests cover activation and DOM\u002FCSS ownership, while Windows native title-bar controls, dragging, display scaling and restart persistence remain separate device gates in #2221.\n\nThe Windows 1.4.0 fallback also writes layout version 8 while keeping Sessions and Bot panels flat. On workspace activation, import that geometry based on the absent rail plus flat-panel authority, retain an untouched backup, and update the mounted dock's seeds before it saves. Workspace ownership arrives after the legacy render, so a storage-only migration test misses stale React refs overwriting the imported ratio. Native Windows blank drag regions need explicit CSS: the upstream data-window-drag rules are macOS-only. Verify native drag separately from DOM\u002Fstyle tests.\n\n## Additional verified pitfall — #2214\n\nA bundled Markdown dependency can resolve its package-internal condition imports to Node implementations even in a Client build. With `react-markdown` \u002F `vfile` in the pinned tsdown\u002FRolldown toolchain, the Client required `node:process`, `node:path` and `node:url`; the real DSH loader refused the plugin before Bot mode could mount. Explicit browser export conditions alone did not change vfile's `#minpath` \u002F `#minproc` \u002F `#minurl` resolution. Resolve those three imports only inside vfile to its shipped `.browser.js` implementations in the Client build, retain the native external baseline, and verify both the actual built Bundle and a cold browser boot. Do not add Node modules to the shell baseline or install a global process shim. The browser condition also selects DOM entity decoding; the Bundle execution test needs a real DOM for that browser-only code.\n\n## Additional verified pitfall — #2290 QA\n\nA fresh Windows build on pinned DSH `0.2.1-rc.2` exposed `vfile` Node imports in the Client bundle: the resolver hook matched slash-only importer paths and missed Windows backslashes. Normalizing that task build's importer path selected the existing browser modules and restored boot; no global process shim was needed. Keep this build-environment recovery separate from private-input behavior proof. The existing screenshot helper also waited for Settings before dismissing the native preview dialog; dismiss the observed dialog first. In the current dock, select Messages before opening a Channel from Home. Preserve boot\u002Fdrive failures and inspect the actual console and accessibility tree before retrying.\n\n## Additional verified pitfalls — #2268 desktop zoom composition\n\nThe npm `dsh-client-ui-theme` 0.2.1-rc.2 Host artifact imports Schemastery as ESM.\nA generated local copy that rewrites this to `createRequire.resolve()`'s CommonJS entry\ncan fail full Profile startup with an ESM\u002FCJS loading race. Keep the canonical ESM singleton\n(`lib\u002Findex.mjs`) and verify by importing the generated Host, then cold-booting a complete\nisolated Profile. Do not infer native startup from a syntax-only transformation test.\n\nThe same release's shortcut `normalizeBinding` rejects `NumpadAdd`, `NumpadSubtract` and\n`Numpad0`. Validate contributed defaults against the real pinned protocol before registering;\na thrown registration must revoke earlier commands, restore owned compatibility resources,\nand expose a refusal. Do not silently turn a failed zoom mount into apparent success.\n\n### Native desktop restart and private CLI launch metadata\n\nThe pinned desktop worker chooses a new loopback HTTP port and process launch token on a real\nrestart. A previously saved CLI endpoint can be unreachable; substituting the new port with the\nold token correctly refuses login. For the isolated zoom QA Profile, the launcher's task-only\nBundle consumes the public `webServer.getOrigin()` and `connection.authenticatedUrl()` methods\nand writes fresh 0600 machine-local CLI metadata. It adds no listener or product route. Never\npublish its token or private metadata, weaken authentication, or attribute this refusal to the\nfeature's Host relay before refreshing the launch credentials.\n\n### Stop the owned desktop before a full linked build\n\n`pnpm build` cleans the Client output directories before writing the new bundles. A running\nlinked native Profile can hot-load during that missing-file interval. In the pinned RC, the\nfirst failed script load can poison the current module-loader generation and leave later\nbundle requests marked as skipped even after files return. Preserve the first crash report,\nfinish the build, then restart only that task-owned desktop with the same Profile and user-data\ndirectory. Stop the owned process before future full builds; never disable third-party Plugins\nor erase the Profile to recover this development sequencing failure. A Client-only iteration\nand an installed immutable product build are separate paths.\n\n### Zoomed settings navigation and native portals (#2269)\n\nIn pinned 0.2.1-rc.2, root CSS zoom changes the body's local layout width but leaves\n`matchMedia('(max-width: 648px)')` tied to the original viewport. At 430%, a wide Settings\nsidebar survives in a 293px local layout. The native Modal also scales its frame overlay\npadding, leaving only 235 viewport pixels for the card. Measure the local body width and\nnormalize only the application Settings overlay's safe-area padding; keep the card zoomed.\nThe native Menu's portaled anchor can be multiplied again (observed y=1247 in an 820px\nviewport). The compact application section picker reuses the existing viewport menu owner,\nwhich clamps and converts coordinates. This does not qualify other native dropdowns.\n\n## Additional verified pitfall — #2268 desktop theme packaging\n\nA Bundle Patch's `name` guards an existing row; it does not replace its implementation.\nRenaming a replacement row to `qualified-theme` breaks the native Client's hardcoded\n`configForms.get('ui-theme')`; a successful boot and one Client module id do not prove font\nsettings preservation. Startup Node hooks also failed to redirect the native Client metadata\nresolver in the actual Host, despite standalone Node resolver tests passing. Do not use those\napproaches as qualified delivery. Retain the original row and use an explicit Profile-local\npackage override through `deepseekbot-zoom-setup enable`, then restart. The command refuses\nunsupported platforms\u002Freleases or other owners and exposes `runtimeVerified:false`.\nDisable before product removal. pnpm can leave an unlisted `link:` symlink after remove;\nthe owner removes only its exact link and verifies it is absent. Native `ui-theme` reads,\nwrites, restart and disable must retain the same font preference. Keep the copied identity,\nlicense and relative ESM schema import; no installed ASAR or upstream files are changed.\n\nThe copied Client exposes its zoom lease only when the actual `__DSH_BOOT__.release.version`\nis 0.2.1-rc.2. Unknown\u002Fmissing releases retain the font-key scope and expose no zoom capability.\nThis runtime guard does not remove an already installed Profile package override or qualify\nthat copied theme on another Host. Disable the override before switching outside the verified\nDesktop\u002FHost\u002FClient tuple; re-enable only after qualifying the new combination.\n## Windows vfile browser imports (#2289)\n\nRolldown can pass a Windows importer path with backslashes. The vfile browser-variant override must normalize separators before matching `node_modules\u002Fvfile\u002Flib`; otherwise a successful build can retain `require(\"node:process\")`, and the real Client refuses @botharness\u002Fui before its Services exist. The existing Client bundle contract reproduces this: two assertions fail before normalization and all seven pass after it. Rebuild the Client and restart the task-owned Host, then inspect its actual browser console; API health alone does not qualify plugin boot.\n\n\n### Desktop plain-library overrides require an explicit offline installer (#2268)\n\nThe 0.2.1-rc.2 CLI refuses `desktop` because Electron owns its lifecycle. The native Plugin\nManager's `installBundle` validates installation-first metadata; adding `dsh.bundle` only to a\nProfile-local copy of the shipped theme still returns `not-bundle`. Headless Profile setup\nsuccess did not qualify Desktop. DeepSeekBot's opt-in setup uses the explicitly selected app's\nbundled pnpm only after the target Desktop Host exits, takes the native Profile manifest writer\nlock, disables scripts and preserves the native `ui-theme` row and preference Patch. Keep the\napp closed until setup returns. Refuse other owners, a busy Profile, an unsupported app version\nor a running target; do not edit ASARs, silently replay uncertain writes or relabel failed\nnative-manager attempts as installation proof. Reopen the same Profile\u002Fuser-data for acceptance.\n\n### Desktop plugin-event stream churn (#2269)\n\nOn the actual 0.2.1-rc.2 Desktop, a passive Network observer recorded `\u002Fplugins\u002Fevents`\nreturning HTTP 200 plus a graph frame, failing with `net::ERR_FAILED` after about 301 seconds,\nand reconnecting three seconds later with HTTP 200 and a fresh graph. The shipped Desktop\nforwards this scheme route through Node fetch; the shipped HMR Client uses EventSource.\nThis identifies native plugin-event transport churn and observed recovery, not the exact\nunderlying timeout source. Do not report that cohort as console-error-free, infer webview\npainting from the stream, or add guest reload\u002Frecreation to conceal it. Preserve the full\nrequest\u002Ffailure\u002Freconnect sequence without auth data and distinguish a page exception or\nfailed reconnection from this measured sequence.\n\n### Windows Desktop zoom candidate (#2270)\n\nOn the official Windows 0.2.1-rc.2 executable, `FileVersion` retains `0.2.1-rc.2` while\n`ProductVersion` reports only `0.2.1.0`. Qualify the former. The real shell publishes `win32`;\nthe Shortcut Service names its platform `windows`. Verify both independently and retain the\nexact boot-release and platform-matching compatibility lease checks. Native caption controls\nremain Windows-owned; the macOS 88×40 corner does not apply.\n\nWindows absolute module paths need `pathToFileURL` before dynamic ESM import. The workspace\nchrome and Select\u002FTooltip QA scripts failed before their fixtures loaded until their Vite\nimport used a file URL. External pnpm invocations use `pnpmCommand`, rather than executing a\nWindows command shim directly. After those fixes, the real dependency fixtures passed;\nfixture pixels still do not qualify native Desktop guests.\n\nThe Windows input tool emitted Ctrl+= with an empty physical `KeyboardEvent.code`, producing\nno native zoom dispatch. A Human's physical Ctrl+0 produced `Digit0`, one native event, one\nzoom handler invocation and one storage write, restoring saved 120% from current 144% while\nretaining the draft and selection. Record the driver limitation separately from application\nbehavior; use the [desktop zoom journey](..\u002Fverify-deepseekbot\u002Ffeatures\u002Fdesktop-window-zoom.md)\nfor the remaining input, IME, guest, DPI and lifecycle gates. A source test or a Client DOM\nevent is not a substitute for the native route.\n\nAn immutable Provider's provenance records the DSH version of its pinned input, while an\nartifact manifest records the current composed Host. After the RC2 upgrade, comparing those\ndifferent facts rejected an otherwise hash-matching installed package. Compare provenance\nto `productImProvider.upstream.dsh`, preserve source and runtime digest checks, and qualify\nthe current composition separately. Do not rewrite the original Provider provenance to make\nit look newly qualified.\n\n### Remote Host QA profiles and hidden sidebar copies (#2500)\n\nThe launcher and `verify-app` share a temporary cookie jar named from `basename(DSH_HOME)`. Two isolated homes named `home` in different parent folders overwrite that jar, so the second launch can make the first Host's doctor return 401 while its own browser still works. Give concurrent homes distinct basenames (`host-a`, `host-b`), preserve the first refusal and verify each Host separately. Do not treat this verification-cookie collision as a product authentication failure.\n\nThe qualified workspace retains a hidden sidebar copy beside the visible Channels panel. The two Add remote buttons can have the same accessible name. A first-match selector can click or fill the hidden copy; choose visible elements as the two-Host journey requires, and wait for the submit button to become enabled after input. The real Windows Web baseline paired successfully after the driver selected visible controls and used keyboard input; no product change was required.\n\n### Connect route provenance in pinned DSH 0.2.1-rc.2 (#2541)\n\nArbitrary HTTP route headers do not enter Typert invocation context, and cookie-authenticated\nbrowser calls share a Peer. The `connection\u002Frequest` waterfall does not admit `remote.mux`\nopens. A header-only or unary-only guard therefore cannot restrict all Connect calls.\nBotHarness stamps its cloudflared-only origin with a process-local capability and owns both\nunary admission and a bounded mux adapter at the Device Gateway, before native dispatch.\nThe shared client refuses before serializing secret arguments: a Host refusal cannot remove\nplaintext already sent through Cloudflare. Verify HTTP, mux and ordinary streams against the\npinned Host; this adapter is not encryption or an upstream DSH API extension.\n\n### Device gateway forwarding and Fetch Metadata\n\nThe pinned DSH `0.2.1-rc.2` browser admission guard rejects `Sec-Fetch-Site: cross-site` even when a Host-held cookie is valid. After the application-defined device gateway has checked the external Origin, refused ambient cookies and admitted the device credential, its own loopback request must discard the browser’s `Sec-Fetch-*` metadata along with Origin\u002FReferer. These headers describe the external browser hop, not the gateway’s authenticated internal hop. Preserve all external admission checks and native DSH checks; do not relax either to repair remote tabs. A real two-Host desktop browser reproduced HTTP403 with the cross-site header and HTTP200 when only that metadata was omitted (#2584).\n\n### PersonaBot native question answerer precedence (#2590)\n\nThe pinned DSH `0.2.1-rc.2` dispatches `user-questions\u002Frequest` as a Cordis waterfall. A prior native Client answerer can wait without calling `next`, preventing a later application-defined Channel answerer from seeing the request. Register the existing Channel question owner with `prepend: true`, as Channel approvals already do. Retain its exact live-Agent and Session Ownership checks; unowned requests must still call `next`. A real two-Host browser must show the card in both the owning conversation and remote Activity, accept an answer and resume the same native tool call. A pending tool trace alone does not prove a Channel card was created.\n\n### DSH 0.2.1-rc.3 upgrade\n\nThe development CLI and SDK pin is rc.3. Preserve the independently pinned rc.2\n`dsh-client-ui-theme` build input for reproducibility. The copied Desktop zoom adapter\nnow checks protocol and content integrity instead of rejecting another rc label. Ordinary\nHosts supply their own native theme unless the optional override is explicitly installed.\nNative Desktop qualification remains separate. Keep Provider build provenance unchanged.\nThe rc.3 file-tool and Go Session patches retain the reviewed rc.2 implementation.\n\n### Forward-compatible launch admission (#2713)\n\nBuild pins and historical qualification versions are evidence, not runtime allowlists. `--dsh-version \u003Cversion>` selects an isolated CLI without editing workspace dependencies; otherwise use the installed CLI. Native Host metadata owns the API floor (`>=0.2.0-0`, prereleases included), and Host-provided DSH modules have no npm peer ranges that exclude future prerelease tuples. The Go runtime first installs the selected native adapter, locates the unique matching request shape, and stages the reviewed patch at its actual line number; changed or ambiguous code is refused with a concrete diagnostic. This avoids pnpm patch failures caused only by line-number drift between rc versions; catalog and authenticated API checks still fail on real incompatibility. The optional zoom adapter checks its protocol, platform and transformed bytes rather than a Desktop version label. Stop a task-owned Host before switching its Profile runtime; never mutate another task’s Profile. Forward admission is not proof of future runtime behavior.\n\nThe verification wrapper also accepts `verify-app launch --dsh-version \u003Cversion>`. Its doctor reads the recorded launched runtime and compares it with the recorded launch version, not the workspace SDK; older instance records without a runtime path must be relaunched before claiming version verification. Packaged artifact `dsh` records build provenance and does not need to equal the current SDK. Stage Go patches using the actual installed adapter package version, which can differ from the CLI version. Optional IM launch metadata is prepared before starting the detached Host.\n\n### Home ownership scan exceeds the default process-output buffer\n\nOn a busy macOS development machine, `dev-instance.mjs` can refuse a fresh Home with\n`Cannot verify development Home process ownership` before launching a Host. Inspect the\n`spawnSync` result without printing process environments: `error.code === \"ENOBUFS\"`\nmeans the full `ps axeww` output exceeded Node's default buffer, not that the Home is owned\nby another task. Keep the complete scan and its fail-closed error handling; use the same\nbounded 32 MiB buffer as the child-process ownership scan. Do not truncate process rows,\nskip ownership checks, or print raw environments, which can contain credentials.\n\n### Native Subagent wake and prompt assembly (#2435)\n\nIn DSH 0.2.1-rc.3, native child reports wake an idle parent independently of an application turn. Agent inbox claim notifications precede system-prompt assembly; assembly precedes agent\u002Fpre-step and snapshots installModelSelection. Establish the application-owned Bot turn before assembly, or the first resumed request can use a stale model. Observe trusted source metadata, validate Session Ownership, and join the existing Bot queue; never replay the report or borrow a prior Human source. Tie readiness to the actual Adapter tool context, not slower Runtime cleanup. Direct CLI calls are not live Orchestrator turns for stop\u002Fsteer selection. Qualify this sequence against the running Host; an API send receipt alone is insufficient.\n\n\n## Additional verified pitfall — #2761 desktop ASAR filesystem\n\nThe Electron desktop carrier patches Node filesystem APIs to interpret `.asar` archives as virtual directories. A downloaded capture-runtime archive must instead be inventoried, hashed and cleaned as physical files. In Electron, use its built-in `original-fs` for those installer operations; keep ordinary Node filesystem APIs in CLI Hosts. Do not toggle process-wide `noAsar`, which affects unrelated DSH modules. A valid cache can pass CLI verification but fail the desktop carrier, trigger another download and leave cleanup with `ENOTEMPTY`. Qualify both carriers: `BH_TEST_ELECTRON=\u003Cdesktop executable> pnpm exec vitest run packages\u002Fcomputer\u002Ftest\u002Flocal-video-electron.test.ts` verifies two starts with zero downloads. Full archive installation, native UI readiness and mobile viewing remain separate acceptance steps.\n\n### Completed preparation PID reused by an unrelated process (#3519)\n\nA development Home can refuse recovery as `Home is in use` after its Host has stopped if an old launch record retains an exited preparation PID that the OS has reused. Successful preparation must retire its resource record only after process exit and descendant verification; live resources and unresolved cleanup remain protected. Old records are not automatically safe to remove: compare the process creation time, command ownership and Home listeners, preserve the original metadata, and remove only a proven stale entry. Never kill a currently live PID based only on an old record or weaken the ownership scan. This was observed during Android QA recovery; the unrelated application process was left running and normal startup succeeded after the verified stale entry was removed.\n\n### DSH 0.2.2-rc.2 Client anchors and Subagent requests (#4019)\n\nThe official macOS rc.2 Desktop removes `useAnchoredPosition` and replaces\n`Menu.getAnchorRect` with `anchorRef`. Opening a model picker with the old hook\ncrashes the Bot Client subtree even though Host boot and a plain DM work. The\napplication-owned anchored-panel adapter retains the native hook when exported;\notherwise it uses CSS anchors. The Menu adapter supplies the same trigger to\nboth generations. Verify focus, Escape, selection, zoom and constrained viewports\nin the actual Client; successful Host health does not prove this seam.\n\nThe rc.2 `subagents.startActivation` reads the live parent, prompt and child\noptions directly from the spec instead of from `spec.request`. Passing only the\nold nested request fails at `spec.parent.id`. The compatibility boundary supplies\nthe same request fields in both locations in one call, preserving the exact live\nparent, model policy, signal and delivery owner. Never retry a failed activation\nthrough a second API shape. Qualify caller-delivered and parent-delivered children\non both generations; a completed Assignment alone does not prove a native child.\n\nThe npm rc.2 CLI can lag the official Desktop feed. Inspect the signed Desktop's\nactual `__DSH_BOOT__.release` and archive digest separately from the public tag:\nthe tested rc.2 Desktop reports commit `a6b1b85`, whereas the public rc.2 tag points\nto `ddac96760b6edf8fa0fe17cbdcf0b512f4c12b2c`. Do not substitute a source tag for\nruntime artifact provenance or describe the Desktop run as npm qualification.\n\nFor an exact npm 404, run `scripts\u002Fdsh-npm-availability.mjs \u003Cexact-version>` and\nretain the timestamped JSON. A missing version is established only by the exact\nendpoint's 404 plus valid package metadata omitting that version; network\u002Fauth\nfailures remain inconclusive. See the [upgrade runbook](..\u002F..\u002F..\u002Fdocs\u002Fagents\u002Fdsh-upgrade.md).\nIn #4024 both official rc.2 npm packages were absent while Desktop was available.\nOptional Desktop zoom uses the product's packaged, hash-checked Theme via a local\nlink, not an rc.2 npm Theme download. Do not change pins, weaken integrity checks,\nor treat the metadata probe as installation\u002Fruntime qualification.\n\n\n### Packaged member carrier checks (#4140)\n\nA bundled consumer can contain a second DSH Connection class. Its `instanceof` check then refuses the live Host's compatible service, leaving the member entry at `member-carrier-unavailable` while Owner RPC works. Check the required service capabilities at the boundary and invoke the Host's own `createPeer`, Gateway and resource APIs. Qualify the built package in an isolated Host; source tests sharing one constructor do not expose this failure. Keep the first refusal and verify the member's opening access snapshot, calls and streams before claiming shell readiness.\n\n### Revisioned Client evidence after an artifact swap (#4114)\n\nIn DSH 0.2.2-rc.1 (`c59d10a`), a revisioned `\u002Fplugins\u002F` URL identifies an advertised artifact generation. Fetching an earlier page's URL with `cache: 'no-store'` still requests that generation; it does not establish which Client the restarted Host currently advertises. A task-owned baseline check rejected this stale-URL observation before measuring. After stopping the owning Host, swapping only independent Client artifacts and restarting, read the new authenticated root document's `__DSH_BOOT__`, fetch its advertised UI batch and compare the complete expected execution segment after removing its source-map directive. Short prefixes and suffixes can match both builds. Preserve the rejected observation, resolved Profile path, artifact hashes and final restoration proof; do not clear caches, invent revisions or change Profile credentials to make the check pass.\n",{"name":5,"description":7},"main","3dcdf62375a6c36482888241eda7d6783f707da1",".agents\u002Fskills\u002Fdsh-dev",63,"https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot","https:\u002F\u002Ftobs.app","https:\u002F\u002Fgithub.com\u002FBotHarness","https:\u002F\u002Fdeepseekbot.app\u002F","2026-11-15 06:17:31",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add BotHarness\u002FDeepSeekBot --skill dsh-dev",{"tool":38,"command":39},"bunx","bunx skills add BotHarness\u002FDeepSeekBot --skill dsh-dev",{"tool":41,"command":42},"pnpm","pnpm dlx skills add BotHarness\u002FDeepSeekBot --skill dsh-dev","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdsh-dev\u002FSKILL.md",true,[46,52],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fdebugging-playbook.md","REFERENCE","参考文档",26463,"https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdsh-dev\u002Freferences\u002Fdebugging-playbook.md",{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fprobe-web.mjs","SCRIPT","脚本",3697,"https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdsh-dev\u002Freferences\u002Fprobe-web.mjs",[59,66,73,80,87,94],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M7CY5WHFGASZATK5CQF05G0A","slide-authoring","Technical reference for writing or editing open-slide pages — file contract, 1920×1080 canvas, type scale, layout, palette\u002Fvisual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides\u002F\u003Cid>\u002F`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like \"edit slide\", \"tweak this page\", \"fix the layout\", \"change the palette\", \"reveal one by one\", \"add a transition\", \"morph transition\", \"write the speaker notes\", \"generate the script \u002F talk track\", \"investigate the slide framework\", \"how do slides work here\".","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fapps\u002Fpresentations\u002F.agents\u002Fskills\u002Fslide-authoring\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M7CY5NMS099ZRH9ECYS47ZKG","current-slide","Resolve which slide, page, and (optionally) selected element the user is currently viewing in the open-slide dev server. Consult this whenever the user references \"this page\", \"this slide\", \"this element\", \"the slide I'm on\", \"the current page\", or any deictic reference to slide content without naming it. Re-read `node_modules\u002F.open-slide\u002Fcurrent.json` at the start of every such turn — the user navigates between turns, so a value you read earlier in the conversation is almost certainly stale.","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fapps\u002Fpresentations\u002F.agents\u002Fskills\u002Fcurrent-slide\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M7CY5G6XHNY7Y8KVGGKF654E","create-theme","Use this skill when the user wants to create, draft, author, or extract a slide theme in this open-slide repo. Triggers on phrases like \"create a theme\", \"make a theme called X\", \"extract a theme from \u003Cslide>\", \"build a theme from these images\". Produces two paired files under `themes\u002F` — `\u003Cid>.md` (palette, typography, layout, fixed Title\u002FFooter components, motion) and `\u003Cid>.demo.tsx` (a runnable demo slide that the dev-UI Themes panel previews). Do NOT use for editing real slides — only for authoring the theme bundle.","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fapps\u002Fpresentations\u002F.agents\u002Fskills\u002Fcreate-theme\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M7CY5B0DZNEVRY95X3QEKW3C","create-slide","Use this skill when the user wants to create, draft, author, or generate new slides \u002F a presentation in this open-slide repo. Triggers on phrases like \"make slides about X\", \"make a deck about X\", \"create a presentation\", \"draft slides for\", \"new slide\", \"a deck with speaker notes \u002F a script\", or when the user asks to add content under `slides\u002F`. Do NOT use for editing the framework itself — only for authoring content inside `slides\u002F\u003Cid>\u002F`.","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fapps\u002Fpresentations\u002F.agents\u002Fskills\u002Fcreate-slide\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M7CY57ED279GA6QC3BFMPXG5","apply-comments","Apply pending @slide-comment markers written by the open-slide inspector tool. Use when the user asks to \"apply comments\", \"process slide comments\", \"apply the inspector comments\", or references markers left inside `slides\u002F\u003Cid>\u002Findex.tsx`.","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fapps\u002Fpresentations\u002F.agents\u002Fskills\u002Fapply-comments\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":18},"01M7CY53ZCYB0P3GYM2V3MEN1N","writing-shape","Writing, exploit: shape raw material into an article, paragraph by paragraph.","https:\u002F\u002Fgithub.com\u002FBotHarness\u002FDeepSeekBot\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fwriting-shape\u002FSKILL.md",[],[]]