dbdeveloper
diff --git a/‎CHANGELOG.md‎
Lines changed: 139 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 139 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 21 additions & 6 deletions b/‎CLAUDE.md‎
Lines changed: 21 additions & 6 deletions
diff --git a/‎README.md‎
Lines changed: 7 additions & 3 deletions b/‎README.md‎
Lines changed: 7 additions & 3 deletions
@@ -11,6 +11,145 @@ For the full design rationale behind any change below, see
 
 ---
 
+## 2.0.2-beta — 2026-05-30
+
+Major architectural rework, no breaking changes for the default
+configuration. The engine now runs CPU- and network-heavy work in
+a small Web Worker orchestra so the UI stays responsive even
+during multi-megabyte syncs on Obsidian Mobile. New optional
+split between **Commit** (stage changes locally) and **Sync**
+(upload to GitHub) for users who want to batch commits offline
+and push only on WiFi. A new **Settings → GitHub sync status**
+section gives a live view of the current upload + the cancel
+button. Expired GitHub tokens now surface as a step-by-step modal
+instead of silent 5-minute retry loops.
+
+If you're a single-device user with `Sync starts with commit:
+true` (the default) and `Show commit ribbon button: false` (also
+the default), nothing about your day-to-day workflow changes —
+the **Sync with GitHub** button still commits + pushes in one
+click. Everything below is additive.
+
+### Added
+
+- **Worker orchestra (Stages 3-6).** A small pool of Web Workers
+  now handles 3-way text merge, SHA computation, base64 decode,
+  and every GitHub API call. The main thread stays free for the
+  editor; "click Sync, keep editing" works as a hard guarantee
+  even at multi-megabyte file sizes. Threshold-gated so small
+  operations stay inline (no postMessage overhead). The CORS
+  feasibility was validated on Capacitor Android (Pixel 6 Pro) —
+  worker `fetch` against `api.github.com` round-trips in
+  ~800 ms.
+- **SHA-first reconcile (Stage 5).** Reconcile now fetches GitHub
+  metadata (sha + size) before pulling blob content. ~75 % of
+  paths resolve from SHAs alone (no remote change / ours wins /
+  already in sync) — no blob fetch, no base64 decode, no merge.
+  Saves multi-MB of redundant downloads on every multi-device
+  sync.
+- **Split Commit / Sync (Settings → "Sync starts with commit",
+  default ON).** Turning the master toggle OFF means the
+  **Sync** button only uploads what's already staged; committing
+  becomes a separate **[Commit]** ribbon button (also a
+  command-palette entry and a hotkey-bindable action). Useful
+  for staging commits offline and pushing only on WiFi.
+- **Show commit ribbon button toggle (Settings, default OFF).**
+  Independent of the master toggle. Lets the user surface a
+  **[Commit]** ribbon icon even when Sync still commits + uploads
+  in one click.
+- **"Upload pending commits to GitHub (no new commit)" command.**
+  Pure-drain hotkey for users who hide all ribbon icons.
+  Independent of the master toggle.
+- **Settings → GitHub sync status section.** Top of the page,
+  always visible. Shows: live timer while a sync is running, the
+  file being processed (N of M counter), last error (with
+  elapsed time prefix), and a `[Stop sync]` button to cancel an
+  in-flight upload.
+- **`Sync2Manager.cancelDrain()` API.** Cancellation propagates
+  via an abort flag the reconcile loop checks between files.
+- **Maximum auto-merge file size (Settings → Performance, default
+  1024 KB).** Exposes the previously-hardcoded
+  `RECONCILE_AUTO_MERGE_LIMIT`; tune up if your corpus needs
+  auto-merge on bigger files (validate on the slowest device
+  first — see `tests/perf/README.md`).
+- **Expired-token modal.** When GitHub returns 401 ("Bad
+  credentials") the plugin now opens a guided recovery modal:
+  intro + the three steps + buttons to open the GitHub token
+  page, the README walkthrough, and the plugin's own settings
+  tab. Throttled to once per hour. Catches the common
+  "fine-grained PAT hit its 366-day cap and the daily 5-minute
+  interval drain silently fails" scenario.
+- **Modify-in-place crash safety (Stage 7).** When the engine
+  writes to a file that's currently open in an editor, it now
+  uses `vault.modifyBinary` to preserve the editor's cursor and
+  scroll position — instead of the rename-aside strategy that
+  closes the view. Backed by a marker-file protocol that
+  forward-completes any interrupted modify on next plugin
+  onload.
+- **CPU micro-benchmarks under `tests/perf/perf-cpu-*`.** Diff3
+  timing matrix, base64 decode, git-blob SHA, WorkerClient
+  dispatch overhead. Baselines documented in
+  `tests/perf/README.md`.
+
+### Changed
+
+- **`Sync2Manager.timed()` HTTP wrapper routes through the
+  network worker** when `WorkerClient` is provided. Existing
+  `requestUrl` path stays as fallback for the Settings-tab
+  connection probe and unit tests.
+- **Reconcile loop reads ours bytes FIRST**, then fetches base +
+  theirs metadata. Together with the SHA-first decision tree
+  this means the cheap local read happens before any network
+  round-trip, and the expensive byte-fetches only happen for
+  paths that truly need them.
+- **`setTimeout(0)` yields between reconcile path iterations.**
+  Prevents the macrotask queue from starving during long drains.
+- **`PushQueue.readFile` uses `fetch(getResourcePath(...))`.**
+  Documented part of Obsidian's `DataAdapter` API; on mobile
+  this resolves to a `http://localhost/_capacitor_file_/...`
+  URL that bypasses the JS↔native bridge. Faster and noticeably
+  more reliable than `adapter.readBinary` for multi-MB files.
+
+### Renamed
+
+The following data.json keys were renamed. Existing values are
+still loaded transparently and a one-time log line + 30-second
+Notice on first run instructs you to copy the new shape
+manually. The OLD keys keep working (loaded but no longer read).
+
+- `autoCommitOnSync` → `syncStartsWithCommit` (also unifies
+  manual / interval / startup behaviour under one toggle —
+  default `true` to preserve today's manual-click semantics)
+- `accumulateOfflineSyncs` → `consolidateCommits`
+- "Push plugins data.json to GitHub" (UI label) → "Sync plugins
+  data.json"
+
+### Removed
+
+- The 9 mobile-diagnostic buttons under Settings → "Mobile
+  diagnostics" (added during the May 2026 field investigation).
+  The empirically-validated learnings landed as proper engine
+  changes; the diagnostic surface is now redundant.
+
+### Fixed
+
+- **Open file no longer closes when a remote change lands.**
+  Was caused by the atomic-rename strategy (renames the live
+  file aside, then renames new bytes over the slot — Obsidian
+  sees the file disappear and unloads the editor). Replaced with
+  `vault.modifyBinary` for existing TFiles; the rename strategy
+  still runs for brand-new files where there's no open editor
+  to preserve.
+
+### Internal
+
+- 49 commits on `sync2-worker-reorg`, 51 if you count the merge
+  commit. Branch cut from `main` at `fead510` (2.0.1-beta5).
+- 679 unit tests + 114 integration tests + 24 perf baselines.
+  All green at merge.
+
+---
+
 ## 2.0.1-beta5 — 2026-05-29
 
 Hotfix release. Fixes a critical sync bug that could overwrite
 
@@ -57,10 +57,18 @@ src/
 │                                    #  4 status subclasses, PlatformError, StaleStateError, makeGithubAPIError
 │                                    #  dispatcher. PSEUDO-MERGE-MODE §13.
 ├── github/client.ts                 # Thin requestUrl wrapper, retryUntil; throws via makeGithubAPIError;
-│                                    #  getContentsAtRef does Blobs-API fallback for >1MB files (PSEUDO-MERGE-MODE §16.6)
+│                                    #  getContentsAtRef does Blobs-API fallback for >1MB files (PSEUDO-MERGE-MODE §16.6);
+│                                    #  every HTTP call routes through WorkerClient.httpRequest when one is wired
 ├── settings/
-│   ├── settings.ts                  # GitHubSyncSettings + DEFAULT_SETTINGS
-│   └── tab.ts                       # Settings UI (trim onChange, Reset modal)
+│   ├── settings.ts                  # GitHubSyncSettings + DEFAULT_SETTINGS (syncStartsWithCommit,
+│   │                                #  showCommitRibbonButton, consolidateCommits, maxAutoMergeSizeBytes)
+│   └── tab.ts                       # Settings UI (trim onChange, Reset modal, GitHub sync status section,
+│                                    #  Performance group with max-auto-merge KB input)
+├── worker/                          # Web Worker orchestra (PSEUDO-MERGE-MODE §17). esbuild emits each entry
+│   ├── types.ts                     #  point as an IIFE, inlines as string via `define`, runtime wraps in Blob URL.
+│   ├── cpu-worker.ts                # CPU pool: decode-base64, compute-git-blob-sha, merge-text (bundles node-diff3)
+│   ├── network-worker.ts            # Single dedicated thread; native fetch executor for every GitHub HTTP call
+│   └── worker-client.ts             # Main-thread controller; pool dispatch, request-id multiplex, terminate, fallback
 └── sync2/
     ├── sync2-manager.ts             # Orchestrator: syncAll, syncFile, drain, processBatch,
     │                                #  validateDeletionsAgainstHead (pre-flight, §12.1),
@@ -77,7 +85,9 @@ src/
     │                                #  Unicode), encodePathForGithub, safeRename. PSEUDO-MERGE-MODE §11.
     ├── gitignore-invariants.ts      # Invariant .gitignore blocks; always-write enforce
     ├── commit-message.ts            # Hardcoded format* helpers; commitMessageForBatch
-    ├── atomic-write.ts              # 5-step atomicWriteFile + stagingPathFor + AtomicWriteRecovery.sweep
+    ├── atomic-write.ts              # 5-step atomicWriteFile + stagingPathFor + AtomicWriteRecovery.sweep;
+    │                                #  fast-path uses vault.modifyBinary for open TFiles (preserves editor cursor/scroll)
+    │                                #  via a .sync-tmp + .<basename>.sync-tmp. marker forward-recovery protocol
     ├── conflict-store.ts            # ConflictRecord + 3-step create + renameVaultSiblingsToUnresolved
     ├── conflict-classifier.ts       # Pure classify() + evaluateConflictState (Phase A + Phase B)
     ├── conflict-watcher.ts          # vault.on listener; READ-ONLY counter.markDirty()
@@ -90,7 +100,8 @@ src/
     ├── types.ts                     # QueueBatch, FileChange, EnqueueMeta
     └── views/
         ├── conflict-status-indicator.ts   # Status-bar 🔀 count
-        └── pre-sync-conflict-modal.ts     # Pre-Sync confirmation modal
+        ├── pre-sync-conflict-modal.ts     # Pre-Sync confirmation modal
+        └── token-expired-modal.ts         # 401 / 403 recovery dialog (Stage 7)
 ```
 
 ## Testing
@@ -177,7 +188,11 @@ The bucket form takes a glob — `tests/integration/scenarios/sync2/conflicts*`
 - **Don't add files to the hardcoded `isSyncable` blocklist** without a real reason. The default for new "should we sync this?" rules is to add patterns to the seeded gitignore (`CONFIG_DIR_SEED` / `ROOT_SEED` in `gitignore-invariants.ts`) — that way users can opt out.
 - **Don't hand-edit the canonical block in `<configDir>/.gitignore`** — `GitignoreInvariants.enforce()` will rewrite it on the next plugin load. To customise the truly-required behaviour, edit the constants in `gitignore-invariants.ts` and ship a new build.
 - **Polling, not events, for the sync engine.** `findChanges` walks the vault on each sync click; no `vault.on` subscription for sync purposes. Implication: edits made while the plugin was disabled get picked up on the next sync click without any "missed events" failure mode. The conflict layer's `ConflictWatcher` IS event-driven (`vault.on('delete'|'modify'|'rename')`), but **read-only** — it only calls `counter.markDirty()`, never mutates store; all conflict mutations happen at drain-start. See [`docs/PSEUDO-MERGE-MODE.md`](./docs/PSEUDO-MERGE-MODE.md) §5.
-- **No scheduler logic in `main.ts`.** Periodic-tick decisions (interval enabled vs watchdog vs `autoCommitOnSync`) and the onload-startup pulse live in `src/sync2/interval-scheduler.ts` so they can be unit-tested in isolation under a fake timer. If you find yourself adding an `setInterval` or `app.workspace.onLayoutReady` callback for sync purposes inside `main.ts`, move it into `IntervalScheduler` instead.
+- **No scheduler logic in `main.ts`.** Periodic-tick decisions (interval enabled vs watchdog vs `syncStartsWithCommit`) and the onload-startup pulse live in `src/sync2/interval-scheduler.ts` so they can be unit-tested in isolation under a fake timer. If you find yourself adding an `setInterval` or `app.workspace.onLayoutReady` callback for sync purposes inside `main.ts`, move it into `IntervalScheduler` instead.
+- **Worker orchestra: CPU pool + dedicated network worker.** Stage 4-6 of the 2.0.2-beta rework moved every hot-path CPU operation (3-way merge, base64 decode, SHA computation) and every GitHub HTTP call off the main thread. The orchestra lives in `src/worker/`; esbuild emits each worker entry point as a standalone IIFE and inlines the source as a string constant via `define`, so `main.js` ships a single bundle. Runtime wraps each string in a `Blob` URL and constructs `new Worker(url)` from it — no `importScripts`, no separate file fetch, no Capacitor `app://` URL ambiguity. Workers CANNOT touch any Obsidian API (`vault.adapter.*`, `app.workspace`, settings) — those stay on main. **All HTTP calls from the engine MUST go through `WorkerClient.httpRequest`** (CORS-validated against `api.github.com` on Capacitor Android). The Settings-tab connection probe is the one allowed exception — it uses `requestUrl` directly so a click never touches plugin state.
+- **Modify-in-place uses `vault.modifyBinary` + a `.sync-tmp.` marker for crash safety.** When the engine writes to a file that already exists as a TFile, `atomicWriteFile` takes a fast path that preserves any open editor's cursor + scroll position. Protocol: stage new bytes in `<file>.sync-tmp.<ext>` → drop a zero-byte marker at `.<basename>.sync-tmp.` (leading + trailing dot — syntactically distinct from staging files) → `modifyBinary(target, newBytes)` → cleanup. On crash, `AtomicWriteRecovery.sweep` sees the marker, renames sync-tmp over the target (forward-complete), and removes the marker. Recovery runs at plugin onload BEFORE `workspace.onLayoutReady` so the rename's editor-close side effect is moot. The rename strategy still runs for brand-new files (no existing TFile to modify); SHA-based recovery handles its `.sync-bak` orphans, unchanged from 2.0.1.
+- **`syncStartsWithCommit` master toggle controls all sync surfaces (default `true`).** Manual `[Sync]` click, interval tick, and startup sync all branch on this single setting. `true` → commit + drain (today's manual-click semantic; preserves backward compat). `false` → drain only; commit becomes the user's separate action via the `[Commit]` ribbon button or the `commit-local` command. The `showCommitRibbonButton` toggle controls the ribbon icon independently — it's a UI affordance, not a semantic.
+- **`atomicWriteFile` is invoked from many places. Settings-tab UI text should NOT name engine concepts ("drain", "queue", "batch") — use plain English for users.** Engine identifiers (cancelDrain, DrainStatus, setDrainStatusListener) stay as code-level jargon because they're API names, not user copy. Stage 7 specifically swapped UI copy: "Drain status" → "GitHub sync status", "Stop drain" → "Stop sync", "Drain running" → "Syncing with GitHub".
 - **`drain()` is re-entrant-safe via a `running` flag** on `Sync2Manager`. Concurrent `syncAll()` calls (e.g. interval tick fires while user click is mid-flight) collapse into one drain — the second call returns immediately. Don't bypass this with a separate code path; the integration suite's H3 test pins the serialisation.
 - **Commit messages are hardcoded** in `src/sync2/commit-message.ts` (`formatSyncMessage`, `formatResolveConflictMessage`, etc.). Don't reintroduce a per-user template field — the design choice was deliberate (date/time live in commit metadata; provenance lives in the trailing `(deviceLabel)` suffix).
 - **When working on conflict resolution OR the push pipeline OR cross-cutting infrastructure** (cross-platform contracts in `cross-platform.ts`, typed errors in `errors.ts`, pending-deletions in `pending-deletions-store.ts`, skip-class annotations in any loop), [`docs/PSEUDO-MERGE-MODE.md`](./docs/PSEUDO-MERGE-MODE.md) is the canonical spec the code targets. Code comments reference the article's section numbers (e.g. `§9.4`, `§10 Scenario E`, `§11 cross-platform contracts`, `§12.1 pre-flight validation`, `§13 error taxonomy`, `§14 skip-class`); use those to navigate between code and design rationale. The bug catalog in `§16 Field Postmortems` is the triage index for similar future symptoms.
@@ -11,9 +11,11 @@ Version `2.0.1-beta` · AGPL-3.0 · Fork of
 ## What's new
 
 Per-release notes live in [`CHANGELOG.md`](./CHANGELOG.md).
-Latest: **2.0.1-beta5** — hotfix for >1 MB-file sync; see
-[CHANGELOG.md](./CHANGELOG.md#201-beta5--2026-05-29) for the
-recovery checklist if you were affected.
+Latest: **2.0.2-beta** — Worker orchestra, SHA-first reconcile,
+split `[Commit]` / `[Sync]` UX, cancellable in-flight uploads,
+expired-token modal. See
+[CHANGELOG.md](./CHANGELOG.md#202-beta--2026-05-30) for the
+full list.
 
 The full design rationale behind any release is in
 [`docs/PSEUDO-MERGE-MODE.md`](./docs/PSEUDO-MERGE-MODE.md).
@@ -133,6 +135,8 @@ want your notes public → leave "Initialize with README" unchecked
 
 <!-- SCREENSHOT: empty repo creation form -->
 
+<a id="github-token-setup"></a>
+
 #### 3. Generate a fine-grained Personal Access Token
 
 [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)