Merge main; use the shared chatShutdownDetacher for OpenCode and Codex

OpenCode and Codex chats implement Detach (called by chatManager.Close)
instead of a parallel DetachSessions interface. Docs follow the Claude Code
host and the systemd KillMode=process unit. The opt-in live restart check
copies only the stage provider's login row into its scratch OpenCode
database, builds the CLI for skill install and removes its scratch tree.
This commit is contained in:
2026-11-04 16:24:17 +00:00
26 changed files with 2463 additions and 101 deletions
+72 -7
View File
@@ -25,8 +25,9 @@ the text the harness recorded), and queued prompts are delivered in order. The
older start-up probe of recently used chats still runs for anything not
recorded, for example after a crash.
Per backend (the contract is `chatSessionDetacher` in
`internal/server/chat_detach.go`):
Per backend (the contract is `chatShutdownDetacher.Detach`, which
`chatManager.Close` calls instead of `Close`, plus `chatSessionReleaser` for
chat_close; see `internal/server/chat_manager.go` and `chat_detach.go`):
- **OpenCode**: sessions live in the OpenCode service. An attached endpoint
(the operator's CLI-managed service) already outlives the server. Without
@@ -39,8 +40,8 @@ Per backend (the contract is `chatSessionDetacher` in
control connection, and the next server reconciles through `thread/read`.
An approval or question the App Server sent to the old connection is bound to
it, so one still pending at shutdown cannot be answered after the restart.
- **Claude Code**: closed as before until its host implements
`DetachSessions`.
- **Claude Code**: its detachable hosts keep the CLI running (see the Claude
Code section).
`PIPELINES_SHUTDOWN_SESSIONS=stop` restores the old shutdown, which closes the
chat clients and records nothing. See [Installation](install.md#restarts-keep-sessions-running).
@@ -82,9 +83,73 @@ credential or alter global settings. `PIPELINES_CLAUDE` may name the executable;
otherwise `claude` is resolved from `PATH` and common per-user locations.
A new session pins a generated UUID with `--session-id`. When the process is
released (idle or server restart), the next prompt resumes the same conversation
with `--resume <id>`, so context and the selected model survive. Chat creation is
local: the CLI starts on the first prompt or model-catalog read.
released (idle, an explicit close, or a host that crashed), the next prompt
resumes the same conversation with `--resume <id>`, so context and the selected
model survive. Chat creation is local: the CLI starts on the first prompt or
model-catalog read.
### Surviving a server restart
A server restart does not stop a Claude Code chat. The installed server runs each
CLI inside `pipelines-claude-host` (`cmd/pipelines-claude-host`,
`internal/claudehost`), a small helper installed next to `pipelines-server`. The
host starts in its own session and process group, so neither launchd nor the
supervisor stops it with the server (the systemd unit uses `KillMode=process`
for the same reason). The host owns the CLI's stdin/stdout. It appends every
output line to a per-session spool file with byte offsets and serves a Unix
socket. The socket is mode 0600 in a 0700 directory:
`<user cache dir>/pipelines/claude-hosts/<hash of the database path>/`. Two
servers of one user never adopt each other's chats. Each host also writes a
registry file (`<key>.json`) there.
The socket speaks one JSON object per line: `attach` (deliver output from an
offset; a newer attach replaces the older connection), `in` (one stdin frame),
`ack` (output processed up to an offset), `status` and `close`. Interrupts,
model and mode switches travel as the CLI's own control requests inside `in`. The
host snoops these frames to keep the CLI's initialize response (models, account),
the applied model and permission mode, a turn's running state, and the control
requests nobody has answered yet (`can_use_tool`, `AskUserQuestion`).
On shutdown the server only disconnects (`Detach`). On start it reads the
registry and reattaches to every live host before serving. It replays the spool
from its start without broadcasting, which rebuilds the session's stream state,
background commands and agents, and pending approvals and questions. Requests
already answered are skipped. Output after the last acknowledged offset, written
while no server was attached, is then processed live. The turn is shown running
if it was running at that offset, watchers get a resync, and the start-up turn
probe keeps observing it for notifications. An approval or question asked before
the restart can be answered after it. Stop works as usual, and the CLI is never
restarted or initialized twice.
The host stops the CLI (EOF, then SIGINT, then SIGKILL to its process group) and
removes its files only when one of these happens:
- The operator closes the chat (`chat_close`).
- The server's idle release or live-process cap fires.
- The CLI exits; the server then gets its stderr.
- With no server attached, the CLI has been idle for the same 20 minutes, or
no server has attached for 24 hours.
If the host itself dies, the server first tries to reconnect once. If that fails,
it stops the orphaned CLI's process group (only when that pid's command line
still names the session) and removes the host files. A running turn ends with
the notice "the Claude Code host stopped unexpectedly; the next prompt resumes
this session with --resume". The next prompt then resumes the session.
Limits:
- A container restart (Docker) still ends every host. So does a reboot or
logout. The transcript survives and `--resume` applies.
- The spool keeps at most 64 MiB of acknowledged output. Older output is
dropped, so background-task state from before that point is not rebuilt after
a restart. Unacknowledged output is dropped only beyond 256 MiB; the server
then logs the gap and clients reload the transcript.
- Turn bookkeeping that lived only in server memory restarts fresh: the turn id,
and which mid-turn messages are still outstanding. Output that begins a
follow-up turn after a reconnect is adopted as a running turn.
- Without the host binary (`PIPELINES_CLAUDE_HOST=off`, or not found next to the
server or on `PATH`), the CLI is the server's child as before and a restart
resumes it.
Text and reasoning stream from the CLI's partial-message events; completed
messages are de-duplicated against the streamed text. Tool calls appear as normal
+8 -7
View File
@@ -42,7 +42,8 @@ Linux needs `systemctl --user`. Other platforms are refused.
2. Builds the Flutter web app in Docker (pinned to `app/.flutter-version`).
Builds are cached in `~/.cache/pipelines/app-builds` by a digest of the app
sources, so an unchanged app is reused.
3. Builds `pipelines-server` and `pipelines` with `go build -trimpath`.
3. Builds `pipelines-server`, `pipelines` and `pipelines-claude-host` (keeps
Claude Code chats alive across server restarts) with `go build -trimpath`.
4. Installs into the prefix: binaries in `bin/`, web app in `lib/app-web`, web
proxy in `lib/web`, `lib/manage.py`, and an empty `lib/app-updates` for APKs.
5. Runs `pipelines skill install` (the authoring skill for OpenCode and Claude
@@ -222,11 +223,11 @@ endpoint, keeps running and is reused. Stop it by killing the `pid` in
clients as before, add `"PIPELINES_SHUTDOWN_SESSIONS": "stop"` to
`opencode_env` in `<prefix>/pipelines-install.json` and restart.
Limit on Linux: systemd stops every process in the service's cgroup. The
OpenCode services the server starts (stage service, owned chat service) end
with `pipelines stop`/`restart`, and their runs fall back as described above.
An attached OpenCode endpoint and the Codex App Server are separate and
survive. macOS launchd does not kill them.
The OpenCode services the server starts (stage service, owned chat service)
run in their own process session, so macOS launchd leaves them running. The
systemd unit uses `KillMode=process`, so Linux stops only the supervisor, which
stops its own children; the detached services survive. An attached OpenCode
endpoint and the Codex App Server are separate processes anyway.
The login service is `~/Library/LaunchAgents/net.a-wan.pipelines.plist` on
macOS and `~/.config/systemd/user/net.a-wan.pipelines.service` on Linux. It
@@ -238,7 +239,7 @@ autostart, not boot-without-login.
| Path | Contents |
| --- | --- |
| `<prefix>/pipelines-install.json` | manifest (ports, paths, install args, environment) |
| `<prefix>/bin/` | `pipelines`, `pipelines-server`, `ntfy` |
| `<prefix>/bin/` | `pipelines`, `pipelines-server`, `pipelines-claude-host`, `ntfy` |
| `<prefix>/data/pipelines.db` | SQLite database (definitions, runs, chats, settings) |
| `<prefix>/data/artifacts/` | run artifacts and session exports |
| `<prefix>/data/ntfy/` | ntfy config, cache and accounts |