@puddle-code/cli 0.3.14 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/CHANGELOG.md +15 -5
  2. package/README.md +33 -19
  3. package/dist/host-control.mjs +1980 -133
  4. package/dist/index.js +4342 -970
  5. package/dist/install.sh +401 -40
  6. package/dist/public/assets/App-CbjV_eCr.js +19 -0
  7. package/dist/public/assets/{CompilationCommandForm-8ipw9M-Z.js → CompilationCommandForm-C71yC-_B.js} +1 -1
  8. package/dist/public/assets/Dashboard-CaVEQBQm.js +1 -0
  9. package/dist/public/assets/{EditorTabClose-o1L4BgTN.js → EditorTabClose-CHZNbZkD.js} +1 -1
  10. package/dist/public/assets/{FindWidget-CVH9U-_P.js → FindWidget-CaVwYvST.js} +1 -1
  11. package/dist/public/assets/LazyTerminal-BvZY-D0f.js +2 -0
  12. package/dist/public/assets/{ModelRefcount-0o8MEOUT.js → ModelRefcount-R_PJzn4E.js} +1 -1
  13. package/dist/public/assets/NewProjectDialog-B6wof57i.js +1 -0
  14. package/dist/public/assets/{NotebookWidget-Ci7TAuWd.js → NotebookWidget-D6vzMCnH.js} +1 -1
  15. package/dist/public/assets/PaneEditorBody-Bn8cmN5i.js +284 -0
  16. package/dist/public/assets/PdfViewer-C-dXDOjG.js +2 -0
  17. package/dist/public/assets/ReleaseNotesDialog-Z7jtCZYz.js +1 -0
  18. package/dist/public/assets/SettingsDialog-lSPFdtsX.js +8 -0
  19. package/dist/public/assets/{Terminal-B3Iw783s.js → Terminal-C9fEeTMx.js} +5 -5
  20. package/dist/public/assets/Workspace-DleYwgSG.js +20 -0
  21. package/dist/public/assets/api-BOuyloUi.js +1 -0
  22. package/dist/public/assets/auth-olLlgxc3.js +64 -0
  23. package/dist/public/assets/{buffer-store-B2nYD11t.js → buffer-store-DeLu2KS4.js} +1 -1
  24. package/dist/public/assets/button-q0ardkfx.js +1 -0
  25. package/dist/public/assets/{chevron-down--sjpQEHH.js → chevron-down-HQLVE6o5.js} +1 -1
  26. package/dist/public/assets/chevron-right-BP2NLwlG.js +1 -0
  27. package/dist/public/assets/code-Cf4ftdOa.js +1 -0
  28. package/dist/public/assets/command-BkdEYC1b.js +1 -0
  29. package/dist/public/assets/{context-CwZ4epwz.js → context-C3-WejyN.js} +1 -1
  30. package/dist/public/assets/context-menu-C0cOAj0E.js +1 -0
  31. package/dist/public/assets/control-tray-D7OXXkAy.css +1 -0
  32. package/dist/public/assets/control-tray-OJfh0_ml.js +1 -0
  33. package/dist/public/assets/{copy-CGsu8426.js → copy-D0Theg4Q.js} +1 -1
  34. package/dist/public/assets/createLucideIcon-C9A1vLE-.js +1 -0
  35. package/dist/public/assets/dialog-IU2fjIs9.js +41 -0
  36. package/dist/public/assets/{dist-Cde1E3eV.js → dist-BHBQY7ao.js} +1 -1
  37. package/dist/public/assets/{dist-CBag2On7.js → dist-CGlwr6Pc.js} +1 -1
  38. package/dist/public/assets/dist-eLNGMhYC.js +1 -0
  39. package/dist/public/assets/{forward-link-C-8Xn8gf.js → forward-link-DMvLf0Xw.js} +1 -1
  40. package/dist/public/assets/{hotkeys-DOpJ1a7g.js → hotkeys-Cu0t6sbz.js} +1 -1
  41. package/dist/public/assets/index-C3TPFFMc.css +2 -0
  42. package/dist/public/assets/{index-B9DFgBft.js → index-DK1twGI0.js} +3 -3
  43. package/dist/public/assets/markdown-CMSzQtLp.js +8 -0
  44. package/dist/public/assets/markdown-it-CWoG9_Dn.js +13 -0
  45. package/dist/public/assets/{markdown-mermaid-CZnHoKN5.js → markdown-mermaid-B648xTNp.js} +1 -1
  46. package/dist/public/assets/media-refresh-store-CHPkX-XV.js +1 -0
  47. package/dist/public/assets/notification-delivery-BlvH2Ojs.js +1 -0
  48. package/dist/public/assets/popover-B5Bw2ljC.js +1 -0
  49. package/dist/public/assets/{preview-kind-DiWpvEc0.js → preview-kind-CPkO-rSz.js} +1 -1
  50. package/dist/public/assets/protocol-support-CsLR9u7d.js +1 -0
  51. package/dist/public/assets/queue-BlrQxHDl.js +3 -0
  52. package/dist/public/assets/{rotate-ccw-CNjR2LSi.js → rotate-ccw-BI2k_h3A.js} +1 -1
  53. package/dist/public/assets/{scroll-restoration-gKZDDamc.js → scroll-restoration-CwXbvZvT.js} +1 -1
  54. package/dist/public/assets/{select-9OADuw7W.js → select-C0UTbo8D.js} +1 -1
  55. package/dist/public/assets/selection-actions-BLoNrxbO.js +1 -0
  56. package/dist/public/assets/session-order-2oedrwDu.js +1 -0
  57. package/dist/public/assets/switch-DihTSmnc.js +1 -0
  58. package/dist/public/assets/{use-ui-state-CQp93ZE4.js → use-ui-state-e6mUjW-H.js} +1 -1
  59. package/dist/public/assets/{view-state-store-CVAUWqnG.js → view-state-store-Cy9sQJoZ.js} +1 -1
  60. package/dist/public/assets/{whole-word-2m2pmAFT.js → whole-word-BJjKpISQ.js} +1 -1
  61. package/dist/public/assets/ws-BX1iQbeP.js +1 -0
  62. package/dist/public/assets/x-Dq6POV20.js +1 -0
  63. package/dist/public/file-icons/material/LICENSE +8 -0
  64. package/dist/public/file-icons/material/SOURCE.txt +4 -0
  65. package/dist/public/file-icons/material/astro.svg +1 -0
  66. package/dist/public/file-icons/material/audio.svg +1 -0
  67. package/dist/public/file-icons/material/c.svg +1 -0
  68. package/dist/public/file-icons/material/console.svg +1 -0
  69. package/dist/public/file-icons/material/cpp.svg +1 -0
  70. package/dist/public/file-icons/material/csharp.svg +1 -0
  71. package/dist/public/file-icons/material/css.svg +1 -0
  72. package/dist/public/file-icons/material/dart.svg +1 -0
  73. package/dist/public/file-icons/material/database.svg +1 -0
  74. package/dist/public/file-icons/material/docker.svg +1 -0
  75. package/dist/public/file-icons/material/document.svg +1 -0
  76. package/dist/public/file-icons/material/eslint.svg +1 -0
  77. package/dist/public/file-icons/material/font.svg +1 -0
  78. package/dist/public/file-icons/material/git.svg +1 -0
  79. package/dist/public/file-icons/material/go-mod.svg +1 -0
  80. package/dist/public/file-icons/material/go.svg +1 -0
  81. package/dist/public/file-icons/material/h.svg +1 -0
  82. package/dist/public/file-icons/material/hpp.svg +1 -0
  83. package/dist/public/file-icons/material/html.svg +1 -0
  84. package/dist/public/file-icons/material/image.svg +1 -0
  85. package/dist/public/file-icons/material/java.svg +1 -0
  86. package/dist/public/file-icons/material/javascript.svg +1 -0
  87. package/dist/public/file-icons/material/json.svg +1 -0
  88. package/dist/public/file-icons/material/jupyter.svg +1 -0
  89. package/dist/public/file-icons/material/kotlin.svg +1 -0
  90. package/dist/public/file-icons/material/less.svg +1 -0
  91. package/dist/public/file-icons/material/license.svg +1 -0
  92. package/dist/public/file-icons/material/lock.svg +1 -0
  93. package/dist/public/file-icons/material/markdown.svg +1 -0
  94. package/dist/public/file-icons/material/npm.svg +1 -0
  95. package/dist/public/file-icons/material/pdf.svg +1 -0
  96. package/dist/public/file-icons/material/php.svg +1 -0
  97. package/dist/public/file-icons/material/pnpm.svg +1 -0
  98. package/dist/public/file-icons/material/prettier.svg +1 -0
  99. package/dist/public/file-icons/material/python.svg +1 -0
  100. package/dist/public/file-icons/material/react.svg +1 -0
  101. package/dist/public/file-icons/material/react_ts.svg +1 -0
  102. package/dist/public/file-icons/material/readme.svg +1 -0
  103. package/dist/public/file-icons/material/ruby.svg +1 -0
  104. package/dist/public/file-icons/material/rust.svg +1 -0
  105. package/dist/public/file-icons/material/sass.svg +1 -0
  106. package/dist/public/file-icons/material/settings.svg +1 -0
  107. package/dist/public/file-icons/material/svelte.svg +1 -0
  108. package/dist/public/file-icons/material/svg.svg +1 -0
  109. package/dist/public/file-icons/material/swift.svg +1 -0
  110. package/dist/public/file-icons/material/table.svg +1 -0
  111. package/dist/public/file-icons/material/toml.svg +1 -0
  112. package/dist/public/file-icons/material/tune.svg +1 -0
  113. package/dist/public/file-icons/material/typescript-def.svg +1 -0
  114. package/dist/public/file-icons/material/typescript.svg +1 -0
  115. package/dist/public/file-icons/material/video.svg +1 -0
  116. package/dist/public/file-icons/material/vite.svg +1 -0
  117. package/dist/public/file-icons/material/vitest.svg +1 -0
  118. package/dist/public/file-icons/material/vue.svg +1 -0
  119. package/dist/public/file-icons/material/xml.svg +1 -0
  120. package/dist/public/file-icons/material/yaml.svg +1 -0
  121. package/dist/public/file-icons/material/yarn.svg +1 -0
  122. package/dist/public/file-icons/material/zip.svg +1 -0
  123. package/dist/public/index.html +3 -3
  124. package/dist/pudl.js +1996 -183
  125. package/package.json +1 -1
  126. package/dist/public/assets/App-5QiKmUI_.js +0 -2
  127. package/dist/public/assets/Dashboard-B9v8mQKk.js +0 -1
  128. package/dist/public/assets/LazyTerminal-Crwcrh-K.js +0 -2
  129. package/dist/public/assets/NewProjectDialog-qFDLTphH.js +0 -1
  130. package/dist/public/assets/PaneEditorBody-C8uTV9yU.js +0 -303
  131. package/dist/public/assets/PdfViewer-BoFsXAue.js +0 -2
  132. package/dist/public/assets/SettingsDialog-tW18Y_Wr.js +0 -8
  133. package/dist/public/assets/Workspace-D2IYXJV2.js +0 -20
  134. package/dist/public/assets/api-CfmzEbQ_.js +0 -1
  135. package/dist/public/assets/auth-CIb9G2C5.js +0 -64
  136. package/dist/public/assets/button-9AVMLaMQ.js +0 -1
  137. package/dist/public/assets/chevron-right-BRjnLYaO.js +0 -1
  138. package/dist/public/assets/code-DRWf9a5s.js +0 -1
  139. package/dist/public/assets/command-BUOkDmUW.js +0 -1
  140. package/dist/public/assets/context-menu-D-5BvS0X.js +0 -1
  141. package/dist/public/assets/createLucideIcon-DyMAgLa3.js +0 -1
  142. package/dist/public/assets/dialog-BMWRC2HO.js +0 -41
  143. package/dist/public/assets/dist-CcLyf3-2.js +0 -1
  144. package/dist/public/assets/errors-DTaodZDR.js +0 -1
  145. package/dist/public/assets/index-DwtrJj9v.css +0 -2
  146. package/dist/public/assets/media-refresh-store-DDvrEM5K.js +0 -1
  147. package/dist/public/assets/notification-delivery-DdTD40aA.js +0 -1
  148. package/dist/public/assets/popover-CtxJVkPi.js +0 -1
  149. package/dist/public/assets/protocol-support-BGk73LFk.js +0 -1
  150. package/dist/public/assets/selection-actions-BjVj7hXw.js +0 -1
  151. package/dist/public/assets/session-order-SN_zG4Us.js +0 -1
  152. package/dist/public/assets/switch-iVuj74VW.js +0 -1
  153. package/dist/public/assets/ws-CspBmo8M.js +0 -1
  154. package/dist/public/assets/x-DCpy1q13.js +0 -1
package/CHANGELOG.md CHANGED
@@ -4,10 +4,20 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
4
4
 
5
5
  # Changelog
6
6
 
7
- ## [0.3.14] — 2026-11-03
7
+ ## [0.4.2] — 2026-11-04
8
8
 
9
- ### Fixed
9
+ ### Cockpit
10
10
 
11
- - Suppress duplicate terminal colour replies from xterm when the daemon answers startup theme queries, preserving legacy viewer replies and replay suppression.
12
- - Keep notebook code visible during editor mounting and stabilise cell sizing, vertical scrolling, focused editing and reading-position restoration.
13
- - Keep the profile name and neighbouring icons stationary when entering inline rename, then resize the field with each edit.
11
+ - Float workspace panes and sidebars as rounded, outlined islands with shared spacing, while keeping editor surfaces inset and resize handles unobtrusive.
12
+ - Unify navigator and action trays, using gold for selected modes, clearer hover feedback, and matching collapsed controls, project groups and archive targets.
13
+ - Present the header as one compact island with inset vertical separators and a screen-centred command hint; clicking its central area opens the palette.
14
+ - Separate History and expanded Archive into independent, resizable sidebar islands; separate repository and project groups with horizontal dividers.
15
+ - Apply shared island outlines and rounding to dashboard tiles, the home terminal, dialogs and popouts while preserving overlay shadows and the Settings divider.
16
+ - Restyle the file tree with roomier inset rows and filled theme-coloured folders that follow Git status, including descendant changes.
17
+ - Bundle MIT-licensed Material file-type icons and share them across the explorer, editor tabs, Search and Changes.
18
+ - Show the navigator's folder basename in bold at the file-tree font size, scroll from the left, and reveal the full path in a right-aligned hover tooltip.
19
+ - Float active tabs and support dragging whole panes from blank tab-strip space to swap or reposition them without losing their tabs.
20
+ - Balance editor gutter spacing and grow the line-number width with the file length.
21
+ - Group notebook actions and PDF zoom controls into shared trays, and give notebook source and output areas separate borderless, deeper-background subislands.
22
+ - Fix inline diff close clicks intercepted by Monaco's text layer and detach diff controllers before shared models are disposed during responsive layout changes.
23
+ - Add a daemon-free UI preview with editable sample files, notebook/PDF fixtures and browser checks for navigation, pane dragging and inline diff controls.
package/README.md CHANGED
@@ -9,7 +9,7 @@ Puddle is an open-source, multi-account coding agent orchestrator with first-cla
9
9
  puddle launch <user>@<host>
10
10
  ```
11
11
 
12
- Puddle manages parallel agents anywhere you SSH into, insulates agents in dedicated worktrees, and keeps your agents alive across disconnects and restarts.
12
+ Puddle manages parallel agents on local and SSH hosts, isolates work in dedicated worktrees, and retains conversations and workspace state across reconnects. Independently supervised runtimes in the 0.4.0 architecture preserve live processes across daemon replacement; hosts with limited session lifetimes have narrower guarantees below.
13
13
 
14
14
  <p align="center">
15
15
  <picture>
@@ -75,10 +75,12 @@ puddle launch
75
75
 
76
76
  This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
77
77
 
78
- Ctrl-C normally closes only the GUI while agent sessions keep running. On an SSH host that reaps
79
- detached processes, Puddle instead keeps the daemon attached to the cockpit; closing it interrupts
80
- live processes. The next `puddle launch` restarts the daemon from the host's persistent state and,
81
- when auto-resume is enabled (the default), restores the interrupted sessions.
78
+ Ctrl-C normally closes only the GUI while independently supervised runtimes keep running.
79
+ Some SSH hosts require a cockpit-held daemon. Closing that cockpit stops the daemon and
80
+ detaches its independent owners; host policy may retain or reap those host-session runtimes.
81
+ Reconnection adopts survivors and restores interrupted sessions according to the host's
82
+ auto-resume setting. These limited hosts do not support managed updates without a usable
83
+ service manager.
82
84
 
83
85
  The [deployed app](docs/mobile-access.md#host-the-installer) serves `/install.sh`
84
86
  as the single public installer. Install daemon and desktop components through
@@ -88,14 +90,18 @@ GitHub Releases.
88
90
 
89
91
  **Managing components:**
90
92
 
91
- The CLI installs, upgrades, and removes all three components — daemon, desktop app, and itself — with optional versions and SSH targets:
93
+ The CLI manages the daemon, runtime software, desktop app and itself, with optional versions and SSH targets:
92
94
 
93
95
  ```sh
94
96
  puddle upgrade # everything installed → the newest release
95
97
  puddle install daemon@v0.0.32 user@host # pin a host's daemon to a version
98
+ puddle upgrade runtime user@host # select the default build for future runtimes
99
+ puddle updates user@host # inspect the host's current update operation
96
100
  puddle remove daemon # uninstall; your data stays unless you --purge
97
101
  ```
98
102
 
103
+ Runtime install/upgrade requires a running daemon with host-update support (application protocol 25.7+) and an available user service manager. Existing runtimes retain their pinned build. `puddle updates --operation <id> --cancel` abandons an exact preparation before dispatch; accepted work is observed without replay.
104
+
99
105
  **Desktop app (optional):**
100
106
 
101
107
  The same cockpit also ships as a standalone desktop app — identical UI and engine, plus a File → "Connect to SSH Host…" menu for remote hosts. Install it with `puddle install desktop` (macOS arm64 or Linux x64). Once installed, it runs independently of the CLI.
@@ -109,7 +115,7 @@ auth prompts unless you use a key).
109
115
 
110
116
  ## How it works
111
117
 
112
- - **The Puddle daemon works anywhere you can SSH into.** It is installed on your host during every fresh connect, relaying information across SSH to your local GUI. The daemon is the parent of every agent process, keeping sessions running when your laptop sleeps, the window closes, or the SSH connection drops. Puddle also maintains a stateful memory of your conversations to survive machine reboots.
118
+ - **Puddle separates host management from live execution.** First connection installs a missing daemon on a supported local or SSH host. In the 0.4.0 architecture, `puddled` manages worktrees and application state, while one independent `puddler` per runtime owns agent and shell PTYs and provider sidecars. Supervised owners survive daemon replacement and cockpit disconnects. After machine reboot, saved conversations can resume according to host settings; live process state does not survive reboot. Hosts without a usable service manager retain the limited host-session fallback described above.
113
119
  - **Puddle orchestrates parallel isolated agents** each working in a unique git worktree and branch. You can choose the branch and worktree during session creation.
114
120
  - **Puddle's lightweight GUI** allows you to track agent progress, session usage, and active worktrees.
115
121
  - **Puddle's philosophy is that any good developer must stay grounded in their code.** Puddle natively integrates live terminals, file editing in Monaco, git commit grahps, diff views, and opens worktrees in your favourite IDE.
@@ -118,36 +124,44 @@ auth prompts unless you use a key).
118
124
  ```
119
125
  client machine host machine (local or remote)
120
126
  ┌──────────────────────────────┐ ┌───────────────────────────────────┐
121
- │ browser ── localhost:7433 │ │ puddled (systemd user service) │
127
+ │ browser ── localhost:7433 │ │ puddled │
122
128
  │ │ │ local: │ ├─ REST + WS API │
123
- │ puddle CLI ◄─┘ │ direct │ ├─ PTY manager │
124
- │ ├─ static web UI assets │───────►│ ├─ git worktree manager │
125
- │ └─ /api + /ws proxy │ remote:│ ├─ per-agent adapters │
126
- └──────────────────────────────┘ ssh -L │ └─ SQLite + append-only logs │
129
+ │ puddle CLI ◄───┘ │ direct │ ├─ runtime controller │
130
+ │ ├─ static web UI assets │───────►│ ├─ worktrees + SQLite │
131
+ │ └─ /api + /ws proxy │ remote:│ └─ daemon-owned execution │
132
+ └──────────────────────────────┘ ssh -L └───────────────────────────────────┘
133
+ │ private IPC
134
+ ┌───────────────────────────────────┐
135
+ │ puddler (one owner per runtime) │
136
+ │ PTYs, sidecars, output, journal │
127
137
  └───────────────────────────────────┘
128
138
  ```
129
139
 
130
- The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI (`puddle upgrade cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the launcher asks for approval before updating it. The prompt shows the host, both protocols and how many live sessions the restart interrupts; declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
140
+ The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI. Compatible cockpit and daemon releases may differ; the launcher requires approval when an older application protocol is incompatible. Explicit daemon/runtime updates also use the CLI or supporting cockpit Host settings. Review distinguishes unaffected independent runtimes from work requiring interruption; first upgrades from daemon-owned sessions report their interruption count. Declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
131
141
 
132
142
  Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
133
143
 
134
144
  ## Development & teardown
135
145
 
136
- **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. They never run side by side, and there is no separate "dev daemon" alongside a "production daemon".
146
+ **UI preview without a daemon.** Run `pnpm --filter @puddle/web dev:preview` and open <http://localhost:5174>. The real cockpit opens a sample project with coloured file icons, expandable folders and editable sample files. Appearance settings work normally. Sample saves last until reload; terminals, agents and host operations are unavailable. This mode uses browser-only fixtures, has no host gateway and is excluded from production builds. The sample `examples/` folder includes a notebook and PDF; Search, Changes, Worktrees and ended sample sessions exercise the navigator layouts. With the preview running, `pnpm --filter @puddle/web test:preview` checks the sample screens, repeated editor resizing, whole-pane dragging and inline diff close controls in Chromium. Use `pnpm --filter @puddle/web dev` to work against a compatible local daemon instead.
147
+
148
+ **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. Multiple clients can share that daemon; there is no automatically separate "dev daemon" alongside a "production daemon".
137
149
 
138
150
  **Dev build vs. production.** The standalone installer or `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
139
151
 
140
152
  ```sh
141
153
  pnpm build && pnpm build:tarball
142
- node packages/cli/dist/index.js launch --tarball dist-release/puddled-v*.tar.gz --foreground
154
+ node packages/cli/dist/index.js upgrade daemon@X.Y.Z --tarball dist-release/puddled-vX.Y.Z-PLATFORM-ARCH.tar.gz
155
+ node packages/cli/dist/index.js launch --foreground
143
156
  ```
144
157
 
145
- `--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `launch` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `launch --tarball …`. `--foreground` keeps the cockpit attached (`launch <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
158
+ Replace `X.Y.Z`, `PLATFORM` and `ARCH` with the version and target printed by `build:tarball`; keep the generated `.sha256` file beside the archive. Add `user@host` after the component for an SSH target. A modern stopped installation starts its selected service before an explicit upgrade; `launch --tarball` alone does not replace that selected build. A compatible running daemon also ignores the launch tarball. To select the same archive for future runtime launches, use `upgrade runtime@X.Y.Z --tarball …`; existing owners remain pinned until explicitly restarted. First installation and approved legacy transitions still use the embedded bootstrap. Both clients share the host's daemon and cockpit registry. Never launch the daemon from inside a coding-agent shell: it inherits the agent's environment and can break conversation resume; use a plain terminal.
146
159
 
147
160
  **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
148
161
  UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
149
- the daemon attached over SSH, killing that cockpit cleanly interrupts its processes instead; the
150
- next launch reconciles them from `~/.puddle` and auto-resumes them when that host setting is enabled.
162
+ the daemon attached over SSH, killing that cockpit stops the daemon. Host-session owners may
163
+ survive or be reaped by host policy; the next launch adopts survivors and reconciles ended
164
+ owners according to the host auto-resume setting.
151
165
  A supervised daemon is auto-restarting
152
166
  (launchd `KeepAlive`, systemd `Restart=always`), so a plain `kill <pid>` bounces straight back — stop
153
167
  it through its supervisor:
@@ -158,7 +172,7 @@ systemctl --user disable --now puddled # Linux (systemd user unit)
158
172
  kill "$(cat ~/.puddle/puddled.pid)" # nohup fallback (no supervisor)
159
173
  ```
160
174
 
161
- **Restore the production daemon.** When you're done testing, `puddle remove daemon` (answer no to the purge question — your profiles, sessions, and worktrees stay), then run the production `puddle launch`, which refetches the daemon from GitHub Releases. (Removal 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.)
175
+ **Restore published software.** Use a compatible CLI to explicitly upgrade to a chosen compatible published version: `puddle upgrade daemon@X.Y.Z` (and `puddle upgrade runtime@X.Y.Z` for future runtimes). Replace `X.Y.Z` with that release; compatibility and recovery checks still apply. Removing and reinstalling a modern daemon can restore its retained service and selected generation, so it is not a way to force a download. Existing runtime processes keep their pinned build until explicitly restarted.
162
176
 
163
177
  **Uninstall.** Removing the CLI alone leaves the daemon installed and running — a full teardown is:
164
178