@puddle-code/cli 0.4.17 → 0.5.3

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 (142) hide show
  1. package/CHANGELOG.md +6 -27
  2. package/README.md +10 -10
  3. package/dist/host-control.mjs +4420 -388
  4. package/dist/index.js +5058 -833
  5. package/dist/install-cli.sh +2 -2
  6. package/dist/install.sh +10 -6
  7. package/dist/public/assets/App-BV_yiDsr.js +19 -0
  8. package/dist/public/assets/CompilationCommandForm-DXHvwQ8Y.js +1 -0
  9. package/dist/public/assets/Dashboard-BF-uKZKM.js +1 -0
  10. package/dist/public/assets/DraftRecovery-B8Ld4_1b.js +1 -0
  11. package/dist/public/assets/EditorTabClose-CGYLU9GK.js +1 -0
  12. package/dist/public/assets/FileCloseScope-DoZ0oLf8.js +1 -0
  13. package/dist/public/assets/{FileEditorSettingsMenu-JUB6GRyp.js → FileEditorSettingsMenu-BbRHII96.js} +1 -1
  14. package/dist/public/assets/HuddlePane-LF3pjMQM.js +219 -0
  15. package/dist/public/assets/LazyTerminal-9xIh2FZq.js +2 -0
  16. package/dist/public/assets/ModelRefcount-CWfA9XXu.js +1 -0
  17. package/dist/public/assets/NotebookWidget-BDdx0BOy.js +7 -0
  18. package/dist/public/assets/PaneEditorBody-C1uu9cRG.js +284 -0
  19. package/dist/public/assets/PdfViewer-DLCPKybn.js +2 -0
  20. package/dist/public/assets/ReadOnlyDiff-C7ZSVRt-.js +2 -0
  21. package/dist/public/assets/{ReleaseNotesDialog-sQVKJ6dm.js → ReleaseNotesDialog-B9fRaZNN.js} +1 -1
  22. package/dist/public/assets/Ripple-BBMjOG3U.css +1 -0
  23. package/dist/public/assets/Ripple-Dzg6tdOM.js +11 -0
  24. package/dist/public/assets/SettingsDialog-BpB0nPgh.js +8 -0
  25. package/dist/public/assets/Terminal-4785ZuI8.js +65 -0
  26. package/dist/public/assets/Workspace-DARXD6Je.js +20 -0
  27. package/dist/public/assets/api-CrP4jl9e.js +1 -0
  28. package/dist/public/assets/auth-1SSLu56b.js +1 -0
  29. package/dist/public/assets/{buffer-logic-BAkSBQT7.js → buffer-logic-D9FvoilV.js} +1 -1
  30. package/dist/public/assets/buffer-store-OTFEYxTw.js +1 -0
  31. package/dist/public/assets/colour-picker-DZdAiaVI.js +1 -0
  32. package/dist/public/assets/content-state-CROLtMfN.js +1 -0
  33. package/dist/public/assets/context-NsaMZKAN.js +1 -0
  34. package/dist/public/assets/{cssMode-C63oO3vc.js → cssMode-BSxvHUeX.js} +1 -1
  35. package/dist/public/assets/disclosure-CpSwsC7J.js +1 -0
  36. package/dist/public/assets/drafts-CBbjQQbz.js +1 -0
  37. package/dist/public/assets/editor-context-T5zIHY3K.js +5 -0
  38. package/dist/public/assets/editor-sync-BOfDr2yY.js +1 -0
  39. package/dist/public/assets/{editor.api2-DTL_SiN1.js → editor.api2-Cyagyq8b.js} +1 -1
  40. package/dist/public/assets/{errors-CD96hLph.js → errors-CviT-mvB.js} +1 -1
  41. package/dist/public/assets/expanding-content-ES1E2jvo.js +1 -0
  42. package/dist/public/assets/{file-editor-settings-CzybzK8S.js → file-editor-settings-BXTs1F7S.js} +1 -1
  43. package/dist/public/assets/{file-links-BWU9Vnfc.js → file-links-CgOYgoMC.js} +1 -1
  44. package/dist/public/assets/forward-link-qOyuWj08.js +1 -0
  45. package/dist/public/assets/{freemarker2-DKWtaCtp.js → freemarker2-RlVF_xG6.js} +1 -1
  46. package/dist/public/assets/{handlebars-uU1ujPOt.js → handlebars-2p1QNu5W.js} +1 -1
  47. package/dist/public/assets/hotkeys-nP8gYtE7.js +1 -0
  48. package/dist/public/assets/{html-CrP_wDJ5.js → html-BOC2G_CE.js} +1 -1
  49. package/dist/public/assets/{htmlMode-lNJ18wA0.js → htmlMode-933MVCdH.js} +1 -1
  50. package/dist/public/assets/index-BB_BPKbu.css +2 -0
  51. package/dist/public/assets/{index-ncmnNFLA.js → index-TMXTPMjv.js} +3 -3
  52. package/dist/public/assets/{javascript-WHxEzdgn.js → javascript-C77bzTLL.js} +1 -1
  53. package/dist/public/assets/{jsonMode-xHnT5kRj.js → jsonMode-Cvtq6-nG.js} +1 -1
  54. package/dist/public/assets/{languages-MEV5hj_8.js → languages-O6mK4sJI.js} +3 -3
  55. package/dist/public/assets/{liquid-B1ddyofJ.js → liquid-CTjKJxys.js} +1 -1
  56. package/dist/public/assets/local-store-Dy1Cd8sn.js +276 -0
  57. package/dist/public/assets/{lspLanguageFeatures-CCO_e4_t.js → lspLanguageFeatures-DJLTbYTu.js} +1 -1
  58. package/dist/public/assets/{markdown-Cseepnv3.js → markdown-Dj7Cr7RL.js} +4 -4
  59. package/dist/public/assets/{mdx-m1X3FtyX.js → mdx-CCh44hnn.js} +1 -1
  60. package/dist/public/assets/{monaco.contribution-BXkMDWX9.js → monaco.contribution-DOhsxmke.js} +2 -2
  61. package/dist/public/assets/notification-delivery-DWXh5nfv.js +1 -0
  62. package/dist/public/assets/{preferences-BX4iJsv8.js → preferences-CvSHA-AA.js} +1 -1
  63. package/dist/public/assets/profile-icons-BI2xFWcB.js +1 -0
  64. package/dist/public/assets/profile-store-D4lZiXgL.js +2 -0
  65. package/dist/public/assets/project-actions-Ck504AFM.js +1 -0
  66. package/dist/public/assets/project-drag-BnkK15qk.js +1 -0
  67. package/dist/public/assets/protocol-support-iXloAH0N.js +1 -0
  68. package/dist/public/assets/{python-CRTN4ovU.js → python-mu5lS7bI.js} +1 -1
  69. package/dist/public/assets/queries-BSkHGZG8.js +1 -0
  70. package/dist/public/assets/queue-4USHmW_D.js +3 -0
  71. package/dist/public/assets/{razor-Cj7Cr6Fr.js → razor-ChcAhcMd.js} +1 -1
  72. package/dist/public/assets/{render-rich-content-cSjuhT75.js → render-rich-content-fo4uQVWR.js} +1 -1
  73. package/dist/public/assets/save-BT7q_AMN.js +1 -0
  74. package/dist/public/assets/scroll-restoration-C_ly1bKS.js +1 -0
  75. package/dist/public/assets/select-DzQdQNsv.js +1 -0
  76. package/dist/public/assets/selection-actions-2wBZeOyh.js +1 -0
  77. package/dist/public/assets/session-display-BUDNzNmg.js +1 -0
  78. package/dist/public/assets/session-order-b3nCJcCG.js +1 -0
  79. package/dist/public/assets/shield-check-CY69Ons-.js +1 -0
  80. package/dist/public/assets/source-anchor-map-BNxSa_bJ.js +1 -0
  81. package/dist/public/assets/square-terminal-CrlDquCd.js +1 -0
  82. package/dist/public/assets/state-CuUqRNo7.js +1 -0
  83. package/dist/public/assets/switch-CGrhQUXr.js +1 -0
  84. package/dist/public/assets/tooltip-Ek-eHPZu.js +1 -0
  85. package/dist/public/assets/trash-2-WYPJMQLN.js +1 -0
  86. package/dist/public/assets/{tsMode-D0nEO9DL.js → tsMode-B7nLznL7.js} +1 -1
  87. package/dist/public/assets/{typescript-CQjjq4UE.js → typescript-DmvD4smm.js} +1 -1
  88. package/dist/public/assets/use-arrangement-ready-1vmV5np6.js +1 -0
  89. package/dist/public/assets/use-desktop-state-CBTzsmlz.js +2 -0
  90. package/dist/public/assets/view-state-store-Dqk7M5ei.js +1 -0
  91. package/dist/public/assets/{workers-m2qsiPbB.js → workers-CqunsJhE.js} +1 -1
  92. package/dist/public/assets/ws-CDXOuBYB.js +1 -0
  93. package/dist/public/assets/{xml-Ci2P6_gm.js → xml-CX8dI9sv.js} +1 -1
  94. package/dist/public/assets/{yaml-76T3bIWj.js → yaml-DbxzTbJh.js} +1 -1
  95. package/dist/public/assets/zoom-intent-vemBFIak.js +1 -0
  96. package/dist/public/index.html +8 -7
  97. package/dist/public/manifest.webmanifest +1 -1
  98. package/dist/public/notification-worker.js +1 -1
  99. package/dist/public/puddle-app.png +0 -0
  100. package/dist/public/puddle.svg +6 -5
  101. package/dist/pudl.js +6217 -585
  102. package/package.json +2 -2
  103. package/dist/public/assets/App-ZtJSRE8n.js +0 -40
  104. package/dist/public/assets/CompilationCommandForm-BGIgFAkM.js +0 -1
  105. package/dist/public/assets/Dashboard-B_m3VKHu.js +0 -1
  106. package/dist/public/assets/EditorTabClose-CNB0NsZQ.js +0 -1
  107. package/dist/public/assets/LazyTerminal-SbouF2Y_.js +0 -2
  108. package/dist/public/assets/ModelRefcount-Bbr8zY_6.js +0 -1
  109. package/dist/public/assets/NotebookWidget-9z2Xca7D.js +0 -7
  110. package/dist/public/assets/PaneEditorBody-nc1Z681y.js +0 -284
  111. package/dist/public/assets/PdfViewer-FWSPsqTc.js +0 -2
  112. package/dist/public/assets/Ripple-B2KIWnc_.js +0 -11
  113. package/dist/public/assets/Ripple-DYosRAZ1.css +0 -1
  114. package/dist/public/assets/SettingsDialog-DKnJSEij.js +0 -8
  115. package/dist/public/assets/Terminal-B2FWGxlE.js +0 -65
  116. package/dist/public/assets/Workspace-DUBYqpNS.js +0 -20
  117. package/dist/public/assets/api-BwP0jv_V.js +0 -1
  118. package/dist/public/assets/archive-BYp06n6i.js +0 -1
  119. package/dist/public/assets/auth-DYEjEl0U.js +0 -64
  120. package/dist/public/assets/buffer-store-fV6iYuCU.js +0 -1
  121. package/dist/public/assets/context-B6lkZJoM.js +0 -1
  122. package/dist/public/assets/dist-cvE69gWt.js +0 -1
  123. package/dist/public/assets/drafts-B_tChlzR.js +0 -1
  124. package/dist/public/assets/editor-sync-W1bamxAP.js +0 -1
  125. package/dist/public/assets/expanding-content-UT_6Fp5v.js +0 -1
  126. package/dist/public/assets/forward-link-CkdngF7C.js +0 -1
  127. package/dist/public/assets/index-DtbUW4I4.css +0 -2
  128. package/dist/public/assets/local-store-yUq3FKdV.js +0 -1
  129. package/dist/public/assets/media-refresh-store-Dxq65ATq.js +0 -1
  130. package/dist/public/assets/notification-delivery-NbIhmidu.js +0 -1
  131. package/dist/public/assets/profile-store-B54YLXa8.js +0 -1
  132. package/dist/public/assets/protocol-support-sBpa8MZK.js +0 -1
  133. package/dist/public/assets/queue-BlrQxHDl.js +0 -3
  134. package/dist/public/assets/scroll-restoration-D-jpZqdR.js +0 -1
  135. package/dist/public/assets/select-CCBPniW9.js +0 -1
  136. package/dist/public/assets/selection-actions-C33evFaY.js +0 -1
  137. package/dist/public/assets/session-order-DilOGTOO.js +0 -1
  138. package/dist/public/assets/switch-B3zcD6GH.js +0 -1
  139. package/dist/public/assets/trash-2-DQeNROsF.js +0 -1
  140. package/dist/public/assets/use-ui-state-BLOunpIh.js +0 -1
  141. package/dist/public/assets/view-state-store-BLCtem0t.js +0 -1
  142. package/dist/public/assets/ws-DkbvXbTZ.js +0 -1
package/CHANGELOG.md CHANGED
@@ -4,41 +4,20 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
4
4
 
5
5
  # Changelog
6
6
 
7
- ## [0.4.17] — 2026-11-07
7
+ ## [0.5.3] — 2026-11-09
8
8
 
9
- ### Cockpit
9
+ ### Frontend
10
10
 
11
- #### Added
11
+ #### Changed
12
12
 
13
- - Compile or run the focused source file with Command+Enter through the existing save-before-run flow.
14
-
15
- - Add per-file editor settings for tab size, word wrap and searchable syntax language, with inherited defaults and window-local overrides.
13
+ - Include the changes prepared for [v0.5.1](https://github.com/PerceptronV/puddle-code/blob/v0.5.3/docs/changelogs/CHANGELOG-v0.5.1.md) and [v0.5.2](https://github.com/PerceptronV/puddle-code/blob/v0.5.3/docs/changelogs/CHANGELOG-v0.5.2.md), whose release assets were not published.
16
14
 
17
15
  #### Fixed
18
16
 
19
- - Run CI only for release tags and explicit `ci` / `ci/**` tags, instead of every main-branch push and pull request.
20
-
21
- - Halve the PDF zoom overlay inset, keeping equal spacing from the top and right edges.
22
-
23
- - Suspend eager compilation while source-input save conflicts remain unresolved, including across reconnects, and resume after a checked editor resolution.
24
-
25
- - Keep eager compilation registered across pane moves and background tabs, and restore observation and PDF refresh after idle expiry or daemon replacement.
26
-
27
- - Move the Ripple handle into the right pane gutter on desktop and mobile without changing the terminal grid or reading width, retaining the mobile touch target.
28
- - Remove the mobile session sidebar and move project switching, session creation and archived sessions into the title dropdown.
29
-
30
- - Keep single-tab action trays above file details and reachable from the top-right corner, including narrow LaTeX panes.
31
-
32
- - Keep the newest covered Ripple output visible at a high boundary by omitting older complete blocks first, preserving pinned prompts, fixed typography and original terminal click anchors. Restore omitted content when the reading area expands.
33
- - Remove the Ripple divider line and place a vertical handle at the far-right edge, retaining the larger mobile touch target.
34
-
35
- - Keep Ripple scrolling in the underlying CLI, reserve two terminal rows for breathing room and keep its reading view top-aligned with fixed typography. Restore the full grid for CLI-only viewing; preserve anchored clicks and normal scrollback, and clip excess output without a second vertical scroller or changing styles.
36
- - Use primary text for non-ignored explorer names, including dotfiles, while retaining muted ignored files and Git status colours.
17
+ - Verify Electron downloads against the official checksums in its locked npm package, avoiding repeated GitHub checksum-download timeouts during desktop packaging.
37
18
 
38
19
  ### Daemon
39
20
 
40
21
  #### Fixed
41
22
 
42
- - Preserve file timestamps and skip eager rebuilds for unchanged saves; hold queued builds after stale saves until their input conflicts resolve.
43
-
44
- - Trigger eager compilation directly after successful saves, retain source watches across incomplete dependency reports, verify missed external source changes each second, and preserve LaTeX dependencies through symlinked roots.
23
+ - Make private runtime fixtures independent of the host umask, wait for uncontended pre-launch admission, and end the owner first when testing crash recovery.
package/README.md CHANGED
@@ -13,8 +13,8 @@ Puddle manages parallel agents on local and SSH hosts, isolates work in dedicate
13
13
 
14
14
  <p align="center">
15
15
  <picture>
16
- <source media="(prefers-color-scheme: dark)" srcset="docs/assets/cockpit-dark.png">
17
- <img src="docs/assets/cockpit-light.png" alt="The Puddle desktop app: a live Claude Code session split beside the rendered README, with the file explorer on the left and parallel agent sessions on their own branches and accounts in the sidebar" width="920">
16
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/frontend-dark.png">
17
+ <img src="docs/assets/frontend-light.png" alt="The Puddle desktop app: a live Claude Code session split beside the rendered README, with the file explorer on the left and parallel agent sessions on their own branches and accounts in the sidebar" width="920">
18
18
  </picture>
19
19
  </p>
20
20
 
@@ -76,7 +76,7 @@ puddle launch
76
76
  This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
77
77
 
78
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
79
+ Some SSH hosts require a frontend-held daemon. Closing that frontend stops the daemon and
80
80
  detaches its independent owners; host policy may retain or reap those host-session runtimes.
81
81
  Reconnection adopts survivors and restores interrupted sessions according to the host's
82
82
  auto-resume setting. These limited hosts do not support managed updates without a usable
@@ -104,7 +104,7 @@ Runtime install/upgrade requires a running daemon with host-update support (appl
104
104
 
105
105
  **Desktop app (optional):**
106
106
 
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/arm64). Once installed, it runs independently of the CLI.
107
+ The same frontend 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/arm64). Once installed, it runs independently of the CLI.
108
108
 
109
109
  An installed Puddle CLI manages the desktop app directly: quit Puddle, then `puddle install desktop`, `puddle upgrade desktop`, or `puddle remove desktop`. On macOS a fresh install goes to `/Applications` when writable, otherwise `~/Applications`; on Linux `install desktop` asks where to put the AppImage (default `~/puddle`) and opens the folder — later updates happen from inside the app.
110
110
 
@@ -115,7 +115,7 @@ auth prompts unless you use a key).
115
115
 
116
116
  ## How it works
117
117
 
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.
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 frontend 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.
119
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.
120
120
  - **Puddle's lightweight GUI** allows you to track agent progress, session usage, and active worktrees.
121
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.
@@ -137,13 +137,13 @@ auth prompts unless you use a key).
137
137
  └───────────────────────────────────┘
138
138
  ```
139
139
 
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.
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 frontend 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 frontend 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 frontend Host/Origin checks guard local access. Launch invitations are single-use; browser login survives frontend restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
141
141
 
142
142
  Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
143
143
 
144
144
  ## Development & teardown
145
145
 
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.
146
+ **UI preview without a daemon.** Run `pnpm --filter @puddle/web dev:preview` and open <http://localhost:5174>. The real frontend 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
147
 
148
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".
149
149
 
@@ -155,11 +155,11 @@ node packages/cli/dist/index.js upgrade daemon@X.Y.Z --tarball dist-release/pudd
155
155
  node packages/cli/dist/index.js launch --foreground
156
156
  ```
157
157
 
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.
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 frontend 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.
159
159
 
160
- **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
160
+ **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local frontend
161
161
  UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
162
- the daemon attached over SSH, killing that cockpit stops the daemon. Host-session owners may
162
+ the daemon attached over SSH, killing that frontend stops the daemon. Host-session owners may
163
163
  survive or be reaped by host policy; the next launch adopts survivors and reconciles ended
164
164
  owners according to the host auto-resume setting.
165
165
  A supervised daemon is auto-restarting