@twinsearth/w2m-dsh-plugin 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.60.0] — 2026-10-16
+
+**Two things learned from a client that would not start, neither of which was a crash in this plugin.**
+
+### §3.1 in `TROUBLESHOOTING.md`: check the lock before you check the plugin
+
+A launch that leaves **no process at all** is a different failure from one that starts and reports something, and
+the existing §3 procedure will mislead anyone who skips that distinction — it assumes the application *ran*.
+
+**The mechanism is one function in `@deepseek-ai/dsh-desktop`'s `lib/main.js`:**
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers it against
+the *application*, not a directory — which is why the two natural remedies both fail, and why the section now says
+so before offering any plugin diagnosis:
+
+| What was tried | Why it did nothing |
+|---|---|
+| disable third-party plugins before restarting | the new process quits at the lock, before plugin loading |
+| reinstall the client (new folder, new exe) | a new directory does not release an application-scoped lock |
+
+**Deleting `~/.dsh` fixed it — not because anything in it was corrupt, but because the deletion took down the
+process still holding the lock.** The section now leads with the measurement that costs nothing:
+
+```powershell
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+**Processes listed → it is the lock, end them and retry. Nothing listed → the failure really is pre-lock, and §3's
+procedure applies.** The deleted directory carried session history and profile configuration; **`Stop-Process`
+would have cost nothing.**
+
+### `scripts/session-retention.mjs`: the store is bounded, out-of-band, as DSH says it must be
+
+`@deepseek-ai/dsh-session-persistence`'s README, under *Known Limitations*:
+
+> **No deletion or retention API** — pruning stored sessions is **out-of-band backend maintenance**.
+
+**So this is not a workaround for a missing feature: the host states retention is the operator's job.** The
+measurement that motivated it is that **one session reached 18.03 MiB of an 18.07 MiB store**, nothing bounds it,
+and every start reads the store.
+
+Three refusals are built in, and each is a deliberate limit rather than an omission:
+
+* **The newest session of every workspace is never removed.** DSH writes to it, and *which* process is writing
+  cannot be checked reliably from outside — so the rule is the one that needs no knowledge of the running
+  process.
+* **`--apply` is required.** The default prints the plan and exits 0. **A tool that removes conversation history
+  shows what it will remove before it removes it.**
+* **A directory that is not a session is reported, not touched**, because the layout is read from the filesystem
+  rather than assumed.
+
+**Verified against the real store:** at a 256 MiB cap it reports *"under the cap — nothing to remove"*; at a
+1 MiB cap it plans two removals and leaves the 18 MiB live session alone.
+
+**No test count change** — both additions are a document and a script, and the script is exercised by hand against
+the store it bounds rather than by a fixture that would not resemble it.
+
 ## [0.59.0] — 2026-10-16
 
 **Every published bin can now be imported without killing the importing process — measured, not reasoned about.**

package/TROUBLESHOOTING.md

@@ -258,6 +258,59 @@ after removal, remove the `w2m` row from `cordis.patch.yml` by hand (§2) before
 **Not us.** If the failure is in a _different_ plugin's entry and this one is merely in the same
 profile, the loader reports the package name in the same line — read it before assuming it is ours.
 
+### 3.1 First rule: if a double-click produces NO process, it is not a plugin
+
+**This section's decision procedure below will mislead you if you skip this step.** It assumes the
+application *ran and reported something*. A launch that leaves **no process at all** — nothing in Task
+Manager, no window, no dialog — is a different failure, and the plugin is not the cause.
+
+**The mechanism**, read out of `@deepseek-ai/dsh-desktop`'s `lib/main.js`:
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+  application.on("second-instance", focusOwner);
+  return true;
+}
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers that
+lock against the *application*, not against a directory, which is why the two most natural remedies both
+fail:
+
+| What you try | Why it does nothing |
+|---|---|
+| **Disable third-party plugins before restarting** | The new process never reaches plugin loading — it quits at the lock |
+| **Reinstall the client (new folder, new exe)** | A new directory does not release a lock registered against the application |
+
+**Check the lock before touching anything else:**
+
+```powershell
+# Windows
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+```bash
+# macOS / Linux
+pgrep -fl "DeepSeek Harness"
+```
+
+* **Processes listed** → it is the lock, and the app is not broken. **End them and start again.** On
+  Windows: `Stop-Process -Name 'DeepSeek Harness' -Force`. Do **not** delete `~/.dsh`.
+* **Nothing listed** → the failure really is before the lock, and *then* §3's procedure below applies.
+
+**A measured case, so the cost is on record.** A restart after upgrading to **v0.58.0** produced no
+process. Disabling third-party plugins and reinstalling the client both changed nothing; **deleting the
+entire `~/.dsh` directory fixed it** — not because anything in that directory was corrupt, but because
+**the deletion took down the process still holding the lock**, and the next launch then became the first
+instance. **Killing that process is the smaller, safer step, and it is the one to try first.**
+
+**What this cost, stated plainly:** the deleted directory carried session history and profile
+configuration that no longer exists. **`Stop-Process` would have cost nothing.**
+
 ---
 
 ## 4. A machine is listed but never answers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Cross-platform fleet execution between Windows and macOS: one DeepSeek Harness account, a Rabbit relay, and signed device identity. Ships four Agent Skills describing fleet dispatch, field-level memory acceptance, session references, and resource scheduling.",
   "license": "MIT",
   "keywords": [

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.59.0';
+const PLUGIN_VERSION = '0.60.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;