Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(updates): document the updater gate, macOS staging wait and quiet-check rules
reviewefadea871730
diff --git a/CLAUDE.md b/CLAUDE.mdindex c06ca6534..2daa0d6a7 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -9420,14 +9420,36 @@ claim to the user and to review — unicast LAN access needs the usage descriptiwhat makes the denial grantable; it is not itself proof anyone's access came back. Guarded as anallowlist-with-reasons by `src/main/info-plist.test.ts`, the sibling of the entitlements guard.-Auto-update uses **electron-updater** (`src/main/updater.ts`, `initUpdater(onBeforeRestart?)` from `index.ts`):+Auto-update uses **electron-updater** (`src/main/updater.ts`, `initUpdater(hooks)` from `index.ts`):runs **only when `app.isPackaged`** (dev = no-op), checks on launch + every 6h, auto-downloads,forwards the lifecycle (`update-available` / `download-progress` / `update-downloaded` / errors)to the renderer over IPC. `components/UpdateCard.tsx` shows the strip + **Restart to update** →-`updates.restart()` → `autoUpdater.quitAndInstall()`; on `update-downloaded` an OS notification-also fires when the window is unfocused. Exposed via `window.nodeTerminal.updates` (`UpdateApi`).-macOS *silent* self-install requires a signed+notarized build; unsigned builds still surface-the card for a manual download.+`updates.restart()` → the guarded `restartToUpdate()` (also the background-mode tray's "Restart to+update vX" item); on `update-downloaded` an OS notification also fires when the window is+unfocused. Exposed via `window.nodeTerminal.updates` (`UpdateApi`). macOS *silent* self-install+requires a signed+notarized build; unsigned builds still surface the card for a manual download.+Rules a refactor must not undo (pure + tested: `shared/update-gate.ts`, `renderer/lib/updateCardState.ts`):+- **electron-updater keeps re-announcing a STAGED update** (the running binary is still old, so every+ 6h check emits `update-available` → cached `update-downloaded` again, and on macOS re-stages the zip+ through Squirrel). The gate forwards and notifies **once per version**; once staged, `autoDownload`+ goes off and only a strictly newer release is downloaded (`downloadUpdate()` on purpose). The card+ never downgrades `downloaded`/`required`, never un-minimizes on a repeat, respects a dismissed version.+- **macOS `update-downloaded` fires BEFORE Squirrel.Mac has the update** (MacUpdater dispatches, then+ asks the native updater to fetch + verify the zip). Until Electron's own `autoUpdater` emits+ `update-downloaded`, `quitAndInstall()` only queues a listener. So a click there sends+ `app:update-installing {phase:'preparing'}` and waits; only when ready does it send `restarting`,+ flush the renderer's canvas save (`main/renderer-flush.ts` — must happen HERE: quitAndInstall closes+ the windows before `before-quit`), and only THEN run `onBeforeRestart` (the `quitting` /+ `skipQuitConfirmation` flags). A native/install error calls `onRestartAborted` to put them back.+- **One error owner, and background failures are not cards**: the `'error'` listener classifies by+ origin (`classifyUpdaterError`) — an automatic check or background download failing (offline, captive+ portal, feed 5xx) only logs; a background download retries at 15/30/60/120 min. User-initiated+ checks (every button goes through `checkForUpdatesNow`, which is how the card knows) get a plain+ sentence (`friendlyUpdateErrorMessage`). Automatic checks are silent until `downloaded`.+- The mandatory policy is re-read every 6 h (one 60 s retry after an empty/failed first read); release+ highlights come from the feed's `releaseNotes` or `/v1/check` `update.notes` + `latestVersion`.+Server Edition: no updater (stubs; `onInstalling`/`onFlushRequest` are documented no-ops). Mobile: N/A.+The "auto-download off" setting is NOT here — that is PR #956's.**Backend check feed** (`src/core/check.ts`, successor to the static `announcements.json`): the**main process** calls `GET https://api.nodeterm.dev/v1/check?version=&os=&channel=stable` (so thediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 4794b1458..5b19ca186 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -95,6 +95,10 @@ and uploads `latest.yml`, so the app shows a passive "new version — Download"downloads or installs, and main refuses restart-to-update for any non-self-installing build.Keep local `dist:win` on `disabled`, and never upload Windows `*.blockmap`s until signing lands.+Updater UX: an update-check button must call `checkForUpdatesNow()` (`state/pendingUpdate.ts`) —+the card treats every other check as automatic and silent. Never flip quitting flags before+the install can start (macOS waits for Squirrel.Mac); see CLAUDE.md "Packaging & auto-update".+Windows installer safety (#829): `build/installer.nsh` overrides NSIS's process-killing check.A running app or session host blocks install/uninstall, and a failed process query blocks too.Never restore automatic host termination: quitting the app preserves those live sessions.