@puddle-code/cli 0.0.12 → 0.0.14

package/CHANGELOG.md

@@ -7,89 +7,53 @@ Past releases: see docs/changelogs/.
 
 # Changelog
 
-## [0.0.12] — 2026-07-28
+## [0.0.14] — 2026-07-28
 
 ### Added
 
-- Notifications actually fire now: when an agent flips to waiting for input,
-  puddle shows a desktop notification (while the window is unfocused; clicking
-  it opens the session), plays the optional sound, and badges the tab title
-  with the count of waiting agents — honouring the Notifications settings and
-  per-project mutes. Enabling the desktop toggle asks for browser permission.
-
-- A `running` agent that has recorded no transcript activity for over an hour
-  is flagged `stale_running` (computed on read, protocol **10.1** — additive):
-  the UI fades its status dot, drops the ripple, and hints "possibly stalled".
-  Advisory only — the daemon never interrupts an agent over it.
-
-- Desktop shell (`packages/desktop`): puddle now also builds as a standalone
-  Electron app. The main process drives the exact same cockpit engine as the
-  `puddle` CLI (`startLocal` from the new embedder surface
-  `@puddle-code/cli/lib`) and opens a window on the embedded cockpit — one
-  codebase, two downstream builds. External links and editor deep links open
-  via the OS, the connection banner's refresh restarts the cockpit
-  in-process, notification clicks raise the window, and quitting never
-  touches the daemon or running agents. `pnpm --filter @puddle/desktop start`
-  to run, `… dist` to package (dmg/zip/AppImage).
-- Desktop remote hosts: File → "Connect to SSH Host…" (⌘⇧O, with a Recent
-  Hosts submenu) drives the CLI's `connectRemote` — one window per host,
-  closing it stops only that cockpit's tunnel/UI server. Key-authenticated
-  hosts only (no TTY for ssh prompts); the dialogue points password/2FA
-  hosts at `puddle connect`.
-- Desktop release packaging: tags now also build the app (dmg/zip on macOS
-  arm64, AppImage on linux x64) and attach it to the GitHub release with
-  checksums in SHA256SUMS. macOS signing + notarisation switch on when the
-  `MAC_CERT_P12`/`MAC_CERT_PASSWORD` and `APPLE_ID`/`APPLE_APP_SPECIFIC_PASSWORD`/
-  `APPLE_TEAM_ID` secrets exist; unsigned otherwise — the accepted default,
-  with the Gatekeeper "Open Anyway"/`xattr` path documented in the README.
-- Desktop app icon: the puddle mark in dark-theme gold on a navy squircle
-  (icon.svg → committed png/icns via `packages/desktop/scripts/render-icon.sh`).
+- Desktop self-update, no code signing required: the app polls GitHub
+  releases, downloads and SHA256SUMS-verifies the new build into
+  `~/.puddle/cache/desktop/`, and offers a "Restart to update" banner; a
+  detached helper swaps the install after quit and relaunches (SPEC §10 —
+  the CLI-style alternative to Squirrel, which refuses unsigned bundles).
+  The helper strips `com.apple.quarantine` from the swapped bundle as
+  defence in depth, and a Linux AppImage updates in place at `$APPIMAGE`,
+  wherever the user keeps it.
+- `puddle upgrade` now names its subject: `puddle upgrade daemon [user@host]`
+  (the previous behaviour), `puddle upgrade cli` (npm under the hood), and
+  `puddle upgrade desktop` (the app's update pipeline, run while the app is
+  closed). `cli`/`desktop` refuse remote targets — only the daemon lives on
+  remote hosts.
 
 ### Fixed
 
-- Battery: the web UI now idles properly. Terminals detach from their PTY
-  stream while hidden (background tab of a pane, or the whole browser tab
-  hidden) and repaint from the daemon's replay when shown again — a hidden
-  terminal no longer receives and parses every output byte. Visible terminals
-  render on the GPU (`@xterm/addon-webgl`, DOM-renderer fallback). The status
-  ripples/pulses are finite (~30 s / ~1 min after a status change) instead of
-  animating forever, and the ports/env (5 s) and git status/diff (10 s) polls
-  stretch 12× while the window is unfocused, snapping back on refocus. Agent
-  processes and PTYs are untouched by all of this — pausing is viewer-side
-  only.
-- Battery, daemon-side: the 3 s agent-title refresh stat-guards the transcript
-  and skips the 128 KiB read when unchanged; PTY log writes coalesce on a
-  100 ms flush instead of one synchronous write per output chunk; session logs
-  are now actually capped at `logMaxBytes` (the config existed but was never
-  enforced — logs grew without bound), rotating to the newest half; the status
-  detector compiles its regexes once instead of per chunk; and the WS gateway
-  stops JSON-encoding output for streams whose last viewer detached.
-- Replayed terminal history no longer re-executes OSC side effects: a stale
-  OSC 52 copy can't clobber the clipboard and stale colour-query replies are
-  never written into a working agent's stdin; a re-attach also repaints the
-  buffer from scratch instead of appending the replay to what it showed.
-- Status detection no longer sticks on green: agent status is now driven by
-  the agent's own hooks instead of scraping the terminal. For Claude Code the
-  daemon installs Stop / Notification(permission_prompt, idle_prompt) /
-  UserPromptSubmit / PreToolUse hooks (verified against 2.1.219) whose helper
-  reports to a new nonce-gated `POST /agent-signal` endpoint (protocol 9.4);
-  the old regex detection remains as a fallback until a session's first
-  signal. Existing accounts pick the hooks up at the next daemon boot.
-- Desktop Linux packaging: the AppImage build failed because electron-builder derived the executable name from the package name (`@puddle/desktop` → `@puddledesktop`, rejected for the `@`); set `linux.executableName: puddle-desktop` explicitly, plus `desktopName` + `linux.syncDesktopName` so the `.desktop` entry, `StartupWMClass`, and Electron's app_id all match for window association.
+- Battery: the file explorer no longer pins a CPU core for as long as it is
+  mounted. Its query-cache subscription reacted to *observer* events — which
+  fire during React renders themselves — so every workspace window sat in a
+  permanent render → cache-event → re-render loop (the "Puddle is using
+  significant energy" report). The subscription now only reacts to query-state
+  events (data landing, cache add/remove). Measured on an idle workspace
+  (file tree + attached terminal): 83–112% CPU per window before, 0–1.2%
+  after; whole app now idles at ~1–2% of one core total, below macOS's
+  significant-energy threshold. Full write-up with methodology in
+  `docs/reports/2026-07-28-explorer-render-loop.md`.
 
 ### Changed
 
-- `PROTOCOL_VERSION` → **10.0**: a deliberate major bump (the 6.0/8.0
-  pattern) so every connected daemon auto-upgrades at the next handshake —
-  this release's hook-driven status detection and archive-kills-live
-  behaviour live daemon-side, and a 9.x daemon would leave sessions stuck
-  green. Rolls up the unreleased 9.3/9.4 additions (`POST /agent-signal`,
-  archive accepting live sessions).
-
-- Archiving is one gesture for any session: the ⋯/right-click menu offers
-  Archive on live agents and terminals too — the daemon kills the session as
-  part of archiving (still a reversible hide; unarchive brings it back
-  resumable), so there is no kill-first dance and no confirmation dialog.
-  Protocol 9.3.
-- Kill lost its confirmation dialog too: it only stops the agent process (the
-  conversation stays resumable), so the menu action now fires immediately.
+- `puddle start` and `puddle connect` are unified into
+  `puddle launch [local | user@host]` — no target means local, and every flag
+  from both verbs (`--port`, `--prefer-port`, `--remote-port`, `--no-browser`,
+  `--no-upgrade`, `--tarball`, `--foreground`) rides along. The old verbs
+  error with the exact replacement.
+- Desktop: new windows no longer default to local. Launching the app, ⌘N,
+  Window → New Window, and the macOS dock icon's right-click New Window all
+  open a host picker — "This machine" on top, then recent hosts, then
+  "Other SSH host…" — and nothing connects until you pick.
+- Desktop: recent hosts moved from the app's userData dir to
+  `~/.puddle/recent-hosts.json` (migrated automatically), so they survive
+  app updates and reinstalls.
+- Desktop (macOS): the merged title bar is a little slimmer (44 → 40px, traffic
+  lights re-centred), so the workspace chrome sits closer to the lights.
+
+- Light theme: exited/idle status dots are neutral grey instead of warm bark brown (matching the 2026-07-16 muted-text re-grey; dark theme was already grey).
+- Desktop (macOS): more breathing room between the traffic lights and the host name in the merged title bar.

package/README.md

@@ -6,7 +6,7 @@
 Puddle is an open-source, multi-account coding agent orchestrator with first-class SSH support and a lightweight GUI. With a single command,
 
 ```bash
-puddle connect <user>@<host>
+puddle launch <user>@<host>
 ```
 
 Puddle manages parallel agents anywhere you SSH into, insulates agents in dedicated worktrees, and keeps your agents alive across disconnects and restarts.
@@ -22,7 +22,7 @@ npm install -g @puddle-code/cli
 **To launch agents on a remote host:**
 
 ```sh
-puddle connect <user>@<host>
+puddle launch <user>@<host>
 ```
 
 This connects Puddle to the remote host over SSH, bootstrapping the Puddle daemon on first contact and enabling you to begin development.
@@ -32,7 +32,7 @@ Puddle works using your system `ssh`, so `~/.ssh/config`, agents, and jump hosts
 **For development on your own machine:**
 
 ```sh
-puddle start
+puddle launch
 ```
 
 This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
@@ -106,7 +106,7 @@ systemctl --user disable --now puddled              # Linux (systemd user unit)
 kill "$(cat ~/.puddle/puddled.pid)"                 # nohup fallback (no supervisor)
 ```
 
-**Restore the production daemon.** When you're done testing, put the release build back over your dev one: stop the daemon (above), clear the installed binaries with `rm -rf ~/.puddle/bin` (your `~/.puddle` state — profiles, sessions, worktrees — is untouched), then run the production `puddle start`, which refetches the daemon from GitHub Releases. (Clearing `bin` is what forces the refetch: the installer skips a version whose files are already present, so a dev build sharing the release's version number would otherwise stay put.)
+**Restore the production daemon.** When you're done testing, put the release build back over your dev one: stop the daemon (above), clear the installed binaries with `rm -rf ~/.puddle/bin` (your `~/.puddle` state — profiles, sessions, worktrees — is untouched), then run the production `puddle launch`, which refetches the daemon from GitHub Releases. (Clearing `bin` is what forces the refetch: the installer skips a version whose files are already present, so a dev build sharing the release's version number would otherwise stay put.)
 
 **Uninstall.** Removing the CLI alone leaves the daemon installed and running — a full teardown stops the daemon, then removes its state, its service file, and the production CLI: