@loicngr/kobo 2.1.15 → 2.1.18

package/AGENTS.md

@@ -41,6 +41,7 @@ npm run typecheck:tests             # type check backend test fixtures and tests
 npm test                            # backend vitest suite
 (cd src/client && npm test)         # client stores, utilities, composables and components
 npm run test:all                    # backend + client suites
+npm run test:deployment             # Python 3.10+ / OpenSSL tooling tests; no Docker/network/production data
 make ci                            # install, audit, lint, type checks, build, both suites
 npm run test:watch                  # vitest in watch mode
 
@@ -124,6 +125,7 @@ src/
 | `session_event_metrics` / `usage_snapshots` | session event counters and provider usage snapshots |
 | `workspace_activity` | significant lifecycle/PR events for the absence digest |
 | `search_*` | derived logical-message search index and indexing progress; see `search-schema.ts` |
+| `workspace_message_batches` | immutable recipient snapshots, request fingerprint and per-recipient delivery outcomes (v53); no stored message body |
 | `mcp_message_requests` | durable external-message idempotency ledger; independent of event retention |
 | `schema_migrations` | applied migration versions, names and timestamps |
 | `workspace_chat_history` | chat-input history per workspace: message text + `created_at`, ordered by autoincrement id, capped at 200 entries by the service; CASCADE DELETE on workspace |
@@ -211,6 +213,8 @@ Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `tas
 
 ### External MCP dialogue and update checks
 
+Workspace-bound stdio, global stdio and HTTP expose shared `create_workspace` / `diagnose_workspace_pr` definitions in `src/shared/workspace-creation-tools.ts`. Stdio forwards them to the backend. `workspace-creation-mcp-service.ts` validates inputs and dispatches through the existing workspace and PR routes in process; preserve UI validation, checkout fingerprints, lifecycle guards and rollback. Inputs use snake_case except the existing camelCase PR checkout decisions. Attachments are inline base64, bounded to the shared 10-file/50 MiB decoded limit before checkout mutations. Keep SDK HTTP/stdio limits aligned with the shared creation envelope budget. Only creation envelopes get the larger base64 HTTP body budget; ordinary MCP requests remain 1 MiB. After a known PR creation failure, rollback only a checkout proven newly created, unchanged, clean (including ignored files) and unowned, under the Git repository lock; retain other checkouts and expose recovery details. Do not retry uncertain creation automatically or treat `creation_id` as an idempotency key. Restricted review/handoff launches cannot create workspaces or invoke lifecycle mutations. Shared lifecycle tools (`workspace-lifecycle-tools.ts` / `workspace-lifecycle-mcp-service.ts`) also expose archive, purge, delete, unarchive and restore through the same transports. Reject reserved/bulk/path-like IDs, require explicit purge/delete flags, and preserve warnings. Single-workspace DELETE accepts optional `confirmationBranch`, rechecked under its lifecycle guard before stopping processes; MCP always supplies it. Branch rename/resync share this guard so the confirmed branch and checkout path cannot change during teardown. Recovery uses `restore-worktree` before unarchive and never starts an agent.
+
 `POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind the existing Host/Origin and network-token gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.
 
 Optional `send_workspace_message.idempotency_key` uses `mcp_message_requests` (migration v43). Reserve before dispatch, preserve fingerprints and terminal outcomes, and never automatically resend an unfinished request after restart. The user event and accepted receipt commit in one SQLite transaction; broadcast follows commit. Dispatch may precede persistence, so interrupted requests are explicitly `delivery_unknown`, not an exactly-once execution promise. The backend alone calls `reconcileMessageRequests` on startup. History retention does not delete the ledger; workspace deletion cascades it.
@@ -245,6 +249,57 @@ Two emit flavors in `websocket-service.ts`:
 
 ## External integrations
 
+### VPS deployment tooling
+
+`docker-compose.vps.yml` is the standalone fresh-instance example for an existing
+Traefik network. It persists `/root`, mounts project paths identically on host and
+container, and leaves the Docker socket opt-in. `docs/deployment-vps.md` owns the
+operator walkthrough; `CONFIGURATION.md` compares all Compose topologies.
+
+`scripts/kobo-install` guides a fresh installation; it does not adopt existing
+unmanaged stacks. Preserve its read-only `--check`, explicit Docker-socket opt-in,
+managed-file fingerprints, shared updater lock, and durable start phases. Completed
+reruns must never restart containers or replace credentials. Only the updater's
+image pin may differ from the managed Compose fingerprint. Interrupted starts
+require diagnosis instead of automatic recreation. This tool reuses the updater's
+release resolution/build helpers; no separate public image registry is assumed.
+
+Optional GitHub App authentication uses `scripts/kobo-gh` and
+`scripts/kobo-github-app-token`, mounted read-only with the user's RSA key. The
+wrapper honors explicit `GH_TOKEN` / `GITHUB_TOKEN`, otherwise obtains a renewable
+installation token from the private, locked cache. Keep JWTs, PEM contents and
+tokens out of logs/errors. HTTPS Git uses the same wrapper via a github.com-scoped
+credential helper; commit author identity is configured separately. Never bake
+credentials into an image or add web settings for these host-managed secrets.
+
+`scripts/kobo-update` is a Python 3.10+ operator tool for this layout, separate
+from the backend's update notifications. Preserve explicit invocation, idle checks,
+unique image tags, private stopped-volume backups, migration tests on a copy,
+and durable failure records. The authenticated `/api/maintenance/update` reservation
+checks runtime ownership and closes agent admission synchronously before shutdown.
+Track in-flight workspace creations and PR checkouts through all asynchronous
+steps and rollback. Maintenance and creation admission must exclude each other
+synchronously; rejecting only the final agent start is too late. Direct HTTP and
+MCP creation paths share this guard.
+Scheduled cron/wakeup/quota deliveries defer without consuming persisted intent;
+valid pending wakeups get `retry_at=target_at` before successful reservation (only
+when `retry_at` was null), so long maintenance does not expire them at boot. Keep
+the requested deadline/prompt and existing retry metadata; do not revive already
+stale, never-attempted wakeups. New wakeups scheduled during maintenance get the
+same durable deferral marker.
+Replaced timers must invalidate deferred callbacks. Legacy runtimes without this
+protocol refuse automatic deployment while `--prepare` remains available. Failed
+pre-stop requests release their reservation; uncertain stops must be confirmed
+before restarting. A crashed updater may require the documented manual recovery. Never automatically run an old image against a
+potentially migrated database or restore snapshots after new work may have run.
+No deployment-specific hostname, App credentials or private source paths belong
+in this script. Its deterministic tests run through `npm run test:deployment`,
+`make ci` and the PR workflow; live deployment is not a CI test.
+Installer/updater Compose commands explicitly select the stack's `.env` and strip
+the template's Kobo/Traefik interpolation variables plus `COMPOSE_*` from a copy
+of the child environment. Apply the same policy to captured and logged commands;
+never mutate the parent environment or lose Docker/forge authentication settings.
+
 ### Forge providers
 
 `src/server/services/forge/` implements `ForgeProvider` for `github` (`gh`), `gitlab` (`glab`), `bitbucket-community` (`bkt`), and `none` (disables PR/MR features). `getForgeProvider(id)` resolves a provider; `resolveForge(projectPath)` first reads the explicit project setting, then classifies the `origin` URL by `github.com`, `gitlab`, or `bitbucket`, falling back to `none`. Successful remote reads are cached for five minutes. PR routes and the watcher use the resolved provider. **Kōbō ships no forge credentials**: users authenticate `gh`/`glab` themselves; Bitbucket uses the email and API token entered in Settings, passed to `bkt` and excluded from settings exports. Missing or unauthenticated CLIs disable PR/MR actions with an explanation.
@@ -527,6 +582,12 @@ unread events or deleting history; re-enabling resumes from the saved checkpoint
 
 `src/client/src/utils/workspace-attention.ts` derives a small set of badges (CI failure, changes-requested) from the PR snapshot + git stats stored on each workspace. `WorkspaceAttentionLabels.vue` renders them inline on the workspace cards in the left drawer. The derivation is a pure function, easy to unit-test and free of IO. Drawer cards therefore stay reactive to whatever the pr-watcher / bulk-info refresh writes back into the store.
 
+### Group workspace messages
+
+`workspace-group-message-service.ts` owns durable group receipts and a server-wide queue capped at three simultaneous delivery attempts. `/api/workspace-messages` creates a batch (202); `/:id` reads its receipt. Requests contain explicit unique workspace IDs, one content body and a stable request ID. A repeated ID is observation only; different content/recipients/source conflicts. Tags/status filters are preview helpers (OR within each group, AND across groups); archived/purged workspaces cannot receive messages. The optional `devServerRunning` preview filter (`dev_server_running` in MCP) requires exact dev-server status `running` and intersects tags/statuses. The dialog prefers the live dev-server store status over the workspace snapshot. Both UI tag filters union the global settings catalogue with assigned tags via `collectTags`; unused catalogue tags have count zero. Wait for settings and archived workspaces to load before pruning a remembered sidebar selection.
+
+Snapshot each target and its delivery mode before scheduling: auto-loop uses `next_iteration`, other workspaces normal chat. Preserve common lifecycle, human-input and compaction guards; a mode change rejects instead of silently changing behavior. For an existing controller, run `beforeDispatch` after its startup promise settles and immediately before engine delivery, so a mode change during startup is still rejected. Receipt completion means accepted/queued, not an agent reply. Persist chat event and accepted outcome transactionally; failed notification cannot undo acceptance. Startup marks pending targets `not_sent` and in-flight ones `unknown`, never replays them. Shutdown stops scheduling before draining active attempts and closing SQLite. Migration v53 and fresh schema share `initWorkspaceMessageBatchSchema`. The dialog stores its immutable request in per-tab sessionStorage for reload recovery and never POSTs automatically on reload. Keep all MCP transports on the same backend owner, launch read-only restrictions and own-workspace exclusion.
+
 ### Bulk workspace info refresh
 
 `GET /api/workspaces/info` returns `{ workspaces, prSnapshots, gitStats }` in one shot. The client polls this endpoint every 15 s so every non-archived workspace stays ≤ 15 s fresh without a per-card stats request. The poll is skipped while the browser tab is hidden and fires once immediately when the tab becomes visible again. The server-side pr-watcher feeds the same caches (`lastKnownGitStats` map, PR snapshots) so the work is shared between the polling client and the watchdog loop.

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.18
+
+- fix(tests): resolve deployment paths on macos
+
+## 2.1.17
+
+- feat(kobo): add VPS tooling and touch drawer resizing
+
+## 2.1.16
+
+- feat(workspaces): add group messaging and expand mcp lifecycle tools
+
 ## 2.1.15
 
 - feat(auto-loop): add durable final reviews and correction cycles

package/CONFIGURATION.md

@@ -35,6 +35,8 @@ Reference for Kōbō configuration and external integrations. The tables cover t
   - [Quick local test — docker-compose.local.yml](#quick-local-test--docker-composelocalyml)
   - [Rehearsing the reverse-proxy stack — docker-compose.local-traefikyml](#rehearsing-the-reverse-proxy-stack--docker-composelocal-traefikyml)
   - [Real deployment — docker-compose.exampleyml](#real-deployment--docker-composeexampleyml)
+  - [VPS with existing Traefik](#vps-with-existing-traefik)
+  - [Docker updates and backups](#docker-updates-and-backups)
   - [Troubleshooting](#troubleshooting)
 - [Agent runtimes](#agent-runtimes)
   - [Claude Code](#claude-code)
@@ -255,6 +257,12 @@ When working from source, `npm run install-all` installs the root, client, and
 build-only Workbox dependencies and is required by `npm run build`, but not by
 the normal development client.
 
+On touch screens, drag the inner edge of either side panel to resize it. The
+horizontal divider inside the right panel can also be dragged. Widths and the
+split position are remembered in this browser; on small screens, a strip of the
+chat remains visible so you can tap outside a panel to close it. Sidebar actions
+wrap onto additional lines when needed, keeping Settings and Create accessible.
+
 ## Custom change-source-branch script
 
 The **Change source branch** action uses the effective `changeSourceBranchScript`:
@@ -502,6 +510,18 @@ Two consequences worth knowing:
 - However far behind the loop falls (a laptop waking from sleep, say), it sends
   **one** reminder per pass, not one per missed interval.
 
+## Group workspace messages
+
+Use **Group message** in the workspace drawer to send the same instruction to several workspaces. Combine tags and workspace statuses, review the named recipient list, and deselect individual workspaces before sending. Selected tags match any tag; selected statuses match any status; both filter groups must match. Enable **Only workspaces with a running development server** to further restrict the list to server status `running`; starting, stopping, stopped, unknown and failed servers are excluded. This filter updates with received server status changes. Empty filters include all non-archived, non-purged workspaces. Both the group-message tag selector and the sidebar tag filter include the saved global tag catalogue plus tags already assigned to workspaces. Unused catalogue tags remain visible (with a zero count in the sidebar); assign a tag through a workspace menu before using it to target that workspace.
+
+Auto-loop recipients receive a durable instruction for their next iteration, without stopping the loop. Other recipients use normal chat delivery, which can resume an inactive agent. Normal chat restrictions still apply: pending human questions, compaction and lifecycle operations are not bypassed. The delivery mode is fixed when submitted; a subsequent auto-loop mode change rejects that recipient rather than silently switching modes.
+
+Each batch accepts up to 200 recipients and 100,000 characters of plain text. Delivery runs on the server with at most three attempts in flight. Results distinguish sent, queued for auto-loop, rejected, not sent and uncertain delivery. **Queued** means saved for an upcoming iteration, not already processed by the agent. Failures do not stop delivery to the other recipients.
+
+Closing the dialog or disconnecting the browser does not cancel an accepted batch. The browser tab retains the request ID and original payload across reloads to recover its receipt, independently of other tabs. **Check this delivery** reuses that request and cannot duplicate accepted deliveries. After a server restart, unstarted recipients become **Not sent**, and interrupted attempts become **Delivery uncertain**; they are never resent automatically. Inspect the affected workspace's chat before creating a new message for an uncertain result.
+
+The same feature is available through internal/global stdio and external HTTP MCP; see the [MCP guide](src/mcp-server/README.md). Batch receipts retain recipient names, IDs, modes and outcomes independently of workspace deletion. The batch table stores a content fingerprint, not the message body; accepted messages retain normal workspace chat history.
+
 ## Attachments in the creation description
 
 On the create page, paste or drop files into the mission description, or use
@@ -827,7 +847,7 @@ The setting lives in `settings.json` under `global` and has no UI control yet:
 
 ## External LLM access through MCP
 
-An external MCP client can connect to `http://127.0.0.1:3000/api/mcp` using Streamable HTTP (use your backend's configured port). It can discover workspaces, read their conversations, send messages to their agents and answer pending questions. The existing global stdio MCP server exposes these conversation tools too.
+An external MCP client can connect to `http://127.0.0.1:3000/api/mcp` using Streamable HTTP (use your backend's configured port). It can create workspaces with the same options as the form, diagnose and check out existing PRs, discover workspaces, read their conversations, send messages and answer pending questions. Workspace-bound stdio, global stdio and HTTP share the creation contract, including brainstorm settings, final auto-loop review, workflow policy, imports, existing worktrees, comparison grouping and inline attachments. All three transports also expose archive, disk-space purge, permanent deletion with explicit branch confirmation, unarchive and recovery of purged worktrees. See the [creation and PR guide](src/mcp-server/README.md#create_workspace) for fields, explicit checkout decisions and timeout/retry behavior.
 
 Remote HTTP clients follow the [network access](#network-access) settings and supply the Kōbō token as `Authorization: Bearer <token>` or `X-Kobo-Token`. The endpoint uses the same Host/Origin and reverse-proxy policy as the rest of the backend. No network setting is changed automatically.
 
@@ -1096,27 +1116,31 @@ For the concrete Docker setup (which compose file, which env vars, which volumes
 
 ## Docker deployment
 
-Kōbō ships an official `Dockerfile` and three ready-to-use Compose files, one per use case. All
-three build from the same image; only the topology and a handful of env vars differ.
+Kōbō ships an official `Dockerfile` and four Compose examples. Choose whether you
+want to reuse host credentials or start an independent instance, and whether
+Traefik already exists. Build the image from a source checkout before starting.
 
 ### Choosing a compose file
 
 | File | Topology | Use it for |
 |---|---|---|
-| [`docker-compose.local.yml`](./docker-compose.local.yml) | Kōbō only, port `3000` published directly. No Traefik, no TLS, no SSH server, no Docker socket. | Trying Kōbō out or poking at a change locally — the fastest path to a running instance. |
+| [`docker-compose.local.yml`](./docker-compose.local.yml) | Kōbō only, port `3000` published directly. No Traefik, TLS, published SSH port or Docker socket. | Trying Kōbō out or poking at a change locally — the fastest path to a running instance. |
 | [`docker-compose.local-traefik.yml`](./docker-compose.local-traefik.yml) | Traefik in front, Kōbō never on a published port, `kobo.localhost` (auto-resolves to `127.0.0.1`, no `/etc/hosts` editing). | Rehearsing the exact reverse-proxy topology/auth/mount setup locally, before touching a real VPS. |
+| [`docker-compose.vps.yml`](./docker-compose.vps.yml) | Kōbō only, existing external Traefik network, persistent `/root`, no published ports or host credential mounts. | A fresh, independent remote instance; follow the [VPS guide](./docs/deployment-vps.md). |
 | [`docker-compose.example.yml`](./docker-compose.example.yml) | Traefik + Let's Encrypt (real domain, real TLS), SSH access, optional Docker-socket passthrough. | The reference for an actual production deployment (VPS behind a reverse proxy). |
 
-All three share the same underlying image (`docker build -t kobo:local .` from the repo root,
-once) and the same core volume set; they differ in network topology and which optional pieces
-(SSH server, Docker socket, TLS) are wired in.
+All four use the same underlying image (`docker build -t kobo:local .` from the
+repo root). The original three mount provider/Git configuration from the host;
+the VPS example keeps independent credentials in a persistent container home.
+The VPS example overrides the entrypoint to start Node directly; the original
+files use the image entrypoint, which starts `sshd` even when port 22 is not published.
 
 ### The image
 
 Multi-stage `Dockerfile`, `node:24.19.0-slim` base:
 
 - **Build stage**: installs root, client, and PWA deps, then runs `npm run build` (client via Quasar, server via `tsc`).
-- **Runtime stage**: production deps only, plus OS tooling the agents and forge CLIs need — `git`, `openssh-client` + `openssh-server`, `ripgrep`, `fd-find`, `jq`, `curl`, Python + build tools, the Docker CLI (talks to a mounted host socket, see [Volumes](#volumes)), `gh`, `glab`, `tmux`, `vim`/`nano`, and more for interactive shell use.
+- **Runtime stage**: production deps only, plus OS tooling the agents and forge CLIs need — `git`, `openssh-client` + `openssh-server`, `ripgrep`, `fd-find`, `jq`, `curl`, Python + build tools, the Docker CLI and Compose plugin (`docker compose`, talks to a mounted host socket, see [Volumes](#volumes)), `gh`, `glab`, `tmux`, `vim`/`nano`, and more for interactive shell use.
 - **Global CLIs**: `@anthropic-ai/claude-code` and `@openai/codex` are installed globally for interactive login (`claude /login`, `codex login` over SSH) — separate from Kōbō's own bundled SDK/subprocess usage, which needs no global install.
 - **`git config --system --add safe.directory '*'`**: the container runs as root, but bind-mounted project repos keep the *host* user's UID on disk. Git's ownership check (CVE-2022-24765 mitigation) refuses to touch a repo it doesn't "own" unless told otherwise. This line pre-trusts every mounted path — fine for a single-user dev container, not something you'd do on a multi-tenant host.
 - **`HEALTHCHECK`**: `curl -f http://localhost:$SERVER_PORT/api/health` every 30s. `/api/health` is exempt from the network-access token gate unconditionally (even with `networkAccessBehindProxy` on) — Docker's `HEALTHCHECK` process has no way to supply the runtime-generated token, and without the exemption a "behind a reverse proxy" container never reports healthy, which makes Traefik's Docker provider filter it out of its router table entirely (Traefik drops unhealthy/starting containers from routing).
@@ -1130,11 +1154,13 @@ Beyond the [general environment variables](#environment-variables), these matter
 
 | Variable | Where it's set | Purpose |
 |---|---|---|
-| `KOBO_HOME` | all three compose files | Points at the named volume mount (`/root/.config/kobo`) so state survives `docker compose down`. |
-| `KOBO_NETWORK_ACCESS_ENABLED` | all three | Binds Kōbō to `0.0.0.0` inside the container at boot — required, since a Docker-forwarded or Traefik-proxied connection never looks like true loopback from Kōbō's point of view, even locally. Without it the container's `127.0.0.1`-only default blocks every external route. |
-| `KOBO_NETWORK_ACCESS_BEHIND_PROXY` | `local-traefik.yml`, `example.yml` | Disables the loopback-trust bypass entirely — needed whenever a reverse proxy sits in front, since every request now looks like it comes from the proxy. Not set in `local.yml`, which publishes Kōbō's port directly with no proxy in between. |
-| `GH_TOKEN` / `GITLAB_TOKEN` | `example.yml` (bring your own via `.env`) | Non-interactive auth for `gh`/`glab` inside the container — there's no browser to complete an interactive `gh auth login` on a headless VPS. |
-| `KOBO_PROJECTS_DIR` | host-side, read by all three via `${KOBO_PROJECTS_DIR:-./kobo-projects}` | Not a container env var — a *host* shell variable that picks the bind-mount source for `/projects`. Defaults to `./kobo-projects` next to the compose file. |
+| `KOBO_HOME` | all four Compose files | Kōbō state at `/root/.config/kobo`, inside a named volume; survives `docker compose down` without `-v`. The VPS example persists all of `/root`. |
+| `KOBO_NETWORK_ACCESS_ENABLED` | all four | Binds Kōbō to `0.0.0.0` inside the container at boot — required, since a Docker-forwarded or Traefik-proxied connection never looks like true loopback from Kōbō's point of view, even locally. Without it the container's `127.0.0.1`-only default blocks every external route. |
+| `KOBO_NETWORK_ACCESS_BEHIND_PROXY` | `local-traefik.yml`, `example.yml`, `vps.yml` | Disables the loopback-trust bypass entirely — needed whenever a reverse proxy sits in front, since every request now looks like it comes from the proxy. Not set in `local.yml`, which publishes Kōbō's port directly with no proxy in between. |
+| `GH_TOKEN` / `GITLAB_TOKEN` | `example.yml` (bring your own via `.env`) | Optional non-interactive auth for `gh`/`glab` inside the container. A CLI browser/device flow can also be completed from your PC. Expiring GitHub App tokens need a [renewable helper](./docs/deployment-vps.md#github-app-bot-authentication), not a static token in `.env`. |
+| `KOBO_PROJECTS_DIR` | Compose interpolation on the host | Original three: source for `/projects`, default `./kobo-projects`. VPS: required existing absolute directory, mounted at the **same path** in the container for host-Docker bind mounts. |
+| `KOBO_DOMAIN` | `vps.yml`, Compose interpolation | Public hostname used in the Traefik rule and `KOBO_NETWORK_ACCESS_PROXY_HOST`; required, without `https://`. |
+| `TRAEFIK_NETWORK` / `TRAEFIK_ENTRYPOINT` / `TRAEFIK_CERTRESOLVER` | `vps.yml`, Compose interpolation | Existing Traefik names; defaults `web` / `websecure` / `letsencrypt`. Adapt to your proxy. |
 
 Both `KOBO_NETWORK_ACCESS_ENABLED` and `KOBO_NETWORK_ACCESS_BEHIND_PROXY` are read once at boot —
 this is what lets the container come up fully configured with no manual Settings-UI step (there's
@@ -1145,14 +1171,15 @@ retrieved once — see [Token / login flow](#token--login-flow).
 
 | Mount | RO/RW | Purpose |
 |---|---|---|
+| `kobo-home:/root` (`vps.yml`, named volume) | RW | Independent Kōbō, Claude/Codex, Git and forge state. Authenticate inside the container; no PC credential files are required. |
 | `<name>-data:/root/.config/kobo` (named volume) | RW | Kōbō's own state — SQLite DB, `settings.json`, etc. Named (not bind-mounted) so it survives `docker compose down` without `-v`, and so it can be deliberately **shared** across compose files by reusing the same volume name (see the two local files, both `kobo-test-data`). |
-| `${KOBO_PROJECTS_DIR:-./kobo-projects}:/projects` | RW | The repos you create workspaces against, and their worktrees — all on one filesystem, so a worktree created next to a project lands on the same volume as the project itself. |
+| `${KOBO_PROJECTS_DIR:-./kobo-projects}:/projects` | RW | Your project repositories. Ensure the configured worktree directory is also persistent. For project Docker bind mounts, use the VPS example’s identical host/container paths; see the [path setup](./docs/deployment-vps.md#optional-project-docker-environments). |
 | `${HOME}/.ssh:/root/.ssh` | RO | Git SSH auth — needed to push/pull over SSH remotes. |
 | `${HOME}/.gitconfig:/root/.gitconfig` | RO | Commit author identity. Without it, agent-authored commits fail with "please tell me who you are". |
 | `${HOME}/.claude.json:/root/.claude.json` | RW | Claude Code auth + MCP server registrations. **Must already exist as a file on the host** (run `claude /login` locally first if it doesn't) — Docker silently creates an empty *directory* instead of erroring on a missing bind-mount source, which breaks auth in a confusing way. |
 | `${HOME}/.claude:/root/.claude` | RW | Claude Code's full state directory (skills/plugins cache, session transcripts, memory) — Claude Code writes into this tree during normal operation. |
 | `${HOME}/.codex:/root/.codex` | RW | Codex's full state directory (`auth.json`, `config.toml`). Harmless to mount even if you only use Claude Code. |
-| `/var/run/docker.sock:/var/run/docker.sock` | RW, `example.yml` only | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Remove this line if you don't need the dev-server panel. |
+| `/var/run/docker.sock:/var/run/docker.sock` | RW, enabled in `example.yml`, opt-in in `vps.yml` | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Remove this line if you don't need the dev-server panel. |
 
 ### Ports
 
@@ -1163,12 +1190,12 @@ retrieved once — see [Token / login flow](#token--login-flow).
 | `443` | `example.yml` | Traefik's TLS entrypoint (Let's Encrypt via the `le` cert resolver), routes your real domain. |
 | `2222 → 22` (published) | `example.yml` only | SSH into the container (`ssh -p 2222 root@<host>`), key-based auth only via the same mounted `~/.ssh`, no password login. The one exception to "no published ports" — Traefik proxies HTTP/WS, not raw TCP, so SSH needs its own path. Rebuilding the image regenerates the SSH host keys, so expect a one-time "host key changed" warning from your SSH client after a rebuild. |
 
-Kōbō itself is **never** published directly in the two Traefik-fronted files — only Traefik is
+Kōbō itself is **never** published directly in the three Traefik-fronted files — only Traefik is
 reachable, matching the real production posture.
 
 ### Token / login flow
 
-All three files pre-enable network access via env vars, so there's no interactive Settings-UI step.
+All four files pre-enable network access via env vars, so there's no interactive Settings-UI step.
 Retrieve the auto-generated token from the container's boot log, then bookmark the token-bearing URL:
 
 ```bash
@@ -1252,6 +1279,36 @@ Open `https://kobo.example.com/?token=<token>`. SSH access: `ssh -p 2222 root@<h
 only). See [Ports](#ports) and [Volumes](#volumes) above for the full rationale on the Docker socket
 and SSH tradeoffs before deploying this to a real machine.
 
+### VPS with existing Traefik
+
+Use [`docker-compose.vps.yml`](./docker-compose.vps.yml) and the
+[step-by-step VPS guide](./docs/deployment-vps.md). This variant runs only Kōbō,
+keeps agent credentials in its own persistent home and joins an existing proxy
+network. Your browser's project picker refers to paths on the VPS/container,
+not your PC. The guide covers provider login, GitHub App bots, Git HTTPS helpers
+and the host/container path requirements for project Docker environments.
+
+For a fresh stack, [`scripts/kobo-install`](./scripts/kobo-install) guides domain,
+project path, existing Traefik settings and optional GitHub App credentials.
+`--check` performs read-only checks; `--prepare` builds without starting. Its
+private manifest protects managed files from accidental replacement. GitHub App
+configuration stays in private host files with read-only container mounts, outside
+web settings. See the [guided installation](./docs/deployment-vps.md#guided-installation)
+and [manual bot configuration](./docs/deployment-vps.md#github-app-bot-authentication).
+
+### Docker updates and backups
+
+For the independent VPS layout, [`scripts/kobo-update`](./scripts/kobo-update)
+accepts a stable version or defaults to npm `latest`. It has `--check`, `--prepare`
+and `--directory` options. See [updater usage and recovery](./docs/deployment-vps.md#update-with-kobo-update).
+This is an operator-invoked script; the in-app update banner does not install releases.
+
+A source-built image needs rebuilding for a new release; `docker compose pull`
+alone cannot update an image that only exists locally. Recreate the service
+with the same persistent volumes and credential mounts after backing up its
+state. Preserve repository/worktree data and project databases separately.
+An old image alone is not a complete rollback after database migrations.
+
 ### Troubleshooting
 
 - **`fatal: detected dubious ownership in repository at '/projects/<name>'`** — only happens if you

package/README.md

@@ -22,6 +22,8 @@ Kōbō (工房, "workshop") turns *one agent, one terminal* into a real workflow
 | **🔁 Auto-loop, cron, wakeups** | Turn an agent loose on the task list: it works through tasks, retries on rate limits, and stops itself when there's nothing left, progress stalls, or it needs you. An optional [independent final review](CONFIGURATION.md#final-review-for-auto-loop) returns findings to the original session for automatic correction and repeats until none remain, with durable recovery after restart. Cron schedules and one-shot wakeups keep workspaces moving on their own timeline. |
 | **🔀 Create from a PR/MR, or from a ticket** | Pick an open pull/merge request from GitHub, GitLab, or Bitbucket and Kōbō resolves every local conflict for you before spinning up the workspace. Or start straight from a Notion page or a Sentry issue URL. |
 
+Use [group messages](CONFIGURATION.md#group-workspace-messages) to send one instruction to selected workspaces, filtered by tags and status, from the interface or MCP. Auto-loops receive it on their next iteration; each recipient has a durable delivery result.
+
 ## Quick start
 
 Requires Node.js ≥ 24.15, Git, Bash and your own Claude Code **or** Codex authentication. No skill plugin or ticket integration is required. Kōbō is a local, single-user tool; each user installs their own instance.
@@ -51,7 +53,7 @@ Kōbō's production build is an installable PWA — use your browser's **Install
 - **Attachments from the first prompt**: paste, drop or attach screenshots, Markdown, text files or PDFs to the creation description or workspace chat. Kōbō copies them into the worktree for the agent. See [creation attachments](./CONFIGURATION.md#attachments-in-the-creation-description) and [chat attachments](./CONFIGURATION.md#attachments-in-workspace-chat).
 
 - **Command palette & search**: `/` autocompletes skills and commands, `@` fuzzy-completes worktree file paths, `Ctrl+F` searches readable messages, `Ctrl+K` opens a command palette. The global search page deep-links to the same spot.
-- **MCP toolset (`kobo-tasks`)**: task/acceptance-criteria CRUD, dev server control, a unified `get_ticket` (Notion or Sentry), cross-workspace conversation search, per-session usage, and a `.ai/thoughts` decision log — see the [MCP guide](./src/mcp-server/README.md#tools). External MCP clients can also discover workspaces, read conversations, send messages, and answer questions through HTTP or global stdio.
+- **MCP toolset (`kobo-tasks`)**: task/acceptance-criteria CRUD, dev server control, a unified `get_ticket` (Notion or Sentry), cross-workspace conversation search, per-session usage, and a `.ai/thoughts` decision log — see the [MCP guide](./src/mcp-server/README.md#tools). Internal and external MCP clients can create fully configured workspaces, including final auto-loop review, attachments and checkout of an existing PR. HTTP and stdio clients can also archive, purge, delete or restore workspaces, read conversations, send messages, and answer questions.
 
   ![Sub-agents panel showing parallel tool calls](docs/assets/images/sub-agents-panel.png)
 - **Multi-forge Git panel**: GitHub (`gh`), GitLab (`glab`), or Bitbucket Community (`bkt`), auto-detected from the remote — `Open PR`, `Merge ready PR`, `Change PR base`, `Change source branch`, all from the UI.
@@ -114,7 +116,9 @@ for credential priority and native-configuration scope.
 
 ### Docker
 
-An official `Dockerfile` and three ready-to-use Compose files ship in this repository: a quick local test stack, a Traefik-fronted local rehearsal (no domain needed), and a full VPS reference (Traefik + Let's Encrypt, SSH access, optional Docker-socket passthrough). See [`CONFIGURATION.md`](./CONFIGURATION.md#docker-deployment) for every compose file, env var, and volume mount.
+An official `Dockerfile` and four Compose examples ship in this repository: a local test stack, a local Traefik rehearsal, a deployment including Traefik, and a fresh VPS instance behind an existing Traefik.
+
+**Working remotely on your own VPS?** The [VPS deployment guide](./docs/deployment-vps.md) includes a guided `kobo-install` installer, optional renewable GitHub App authentication, persistent agent logins and Docker updates. Your browser runs on your PC; repositories and agents run on the VPS. See [`CONFIGURATION.md`](./CONFIGURATION.md#docker-deployment) for the Compose comparison and shared settings.
 
 ### Network access
 
@@ -162,4 +166,4 @@ GPL-3.0-or-later. See [`LICENSE`](./LICENSE).
 
 Report reproducible bugs and feature requests in [GitHub Issues](https://github.com/loicngr/Kobo/issues). Read [Contributing](./CONTRIBUTING.md) and the [Code of conduct](./CODE_OF_CONDUCT.md) before participating. Vulnerabilities belong in the private channel described in [Security](./SECURITY.md), not public issues. Support is maintained on a best-effort basis; no response-time commitment is implied.
 
-Platform validation and release blockers are recorded in the [public-readiness evidence](./docs/release/public-readiness-evidence.md). Linux is locally exercised; macOS CI, WSL and real-provider beta sessions require their own evidence. See [third-party notices](./THIRD_PARTY_NOTICES.md) for redistributed assets.
+Linux is locally exercised; macOS CI, WSL and real-provider beta sessions require their own evidence. See [third-party notices](./THIRD_PARTY_NOTICES.md) for redistributed assets.

package/dist/mcp-server/kobo-tasks-server.js

@@ -4,7 +4,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getDb } from '../server/db/index.js';
 import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName, MEMORY_TOOL_DEFINITIONS } from '../shared/memory-tools.js';
+import { isWorkspaceCreationTool, MAX_MCP_CREATION_REQUEST_BYTES, WORKSPACE_CREATION_TOOLS, } from '../shared/workspace-creation-tools.js';
 import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
+import { isWorkspaceGroupMessageTool, WORKSPACE_GROUP_MESSAGE_TOOLS } from '../shared/workspace-group-message-tools.js';
+import { isWorkspaceLifecycleTool, WORKSPACE_LIFECYCLE_TOOLS } from '../shared/workspace-lifecycle-tools.js';
 import { createTaskHandler, cronListHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getTicketSourcesHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, listWorkspacesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, readWorkspaceEventsCsvHandler, setWorkspaceAgentDescriptionHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
 import { callMemoryTool, isMemoryOutputSuppressed } from './memory-client.js';
 import { callWorkspaceDialogueTool } from './workspace-dialogue-client.js';
@@ -566,6 +569,9 @@ const WORKSPACE_SCOPED_TOOLS = [
 ];
 const GLOBAL_TOOLS = [
     ...WORKSPACE_DIALOGUE_TOOLS,
+    ...WORKSPACE_CREATION_TOOLS,
+    ...WORKSPACE_LIFECYCLE_TOOLS,
+    ...WORKSPACE_GROUP_MESSAGE_TOOLS,
     ...EXTERNAL_MEMORY_TOOL_DEFINITIONS,
     {
         name: 'list_workspaces',
@@ -587,63 +593,6 @@ const GLOBAL_TOOLS = [
         },
         annotations: { readOnlyHint: true, openWorldHint: false },
     },
-    {
-        name: 'create_workspace',
-        description: 'Create a new Kōbō workspace (git worktree + agent session), like the "Créer" button on the Create page. Requires the Kōbō backend server to be running and reachable at KOBO_BACKEND_URL. name/project_path/source_branch/working_branch are mandatory — unlike the UI, this API does not auto-derive a branch name from the workspace name.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Workspace display name.' },
-                project_path: { type: 'string', description: 'Absolute path to the project on disk.' },
-                source_branch: { type: 'string', description: 'Branch to base the new worktree on (e.g. "develop").' },
-                working_branch: {
-                    type: 'string',
-                    description: 'New branch name for the worktree (e.g. "feature/my-thing").',
-                },
-                model: { type: 'string', description: 'Model id override (optional, defaults to project/global setting).' },
-                reasoning_effort: { type: 'string', description: 'Reasoning effort override (optional).' },
-                engine: { type: 'string', description: 'Agent engine id, e.g. "claude-code" or "codex" (optional).' },
-                description: { type: 'string', description: 'Task description / initial brainstorming prompt (optional).' },
-                tags: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Workspace tags to assign at creation (optional).',
-                },
-                tasks: { type: 'array', items: { type: 'string' }, description: 'Initial manual task titles (optional).' },
-                acceptance_criteria: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Initial manual acceptance criteria (optional).',
-                },
-                agent_permission_mode: {
-                    type: 'string',
-                    enum: ['plan', 'bypass', 'strict', 'interactive'],
-                    description: 'Permission mode for the new session (optional).',
-                },
-                auto_loop: { type: 'boolean', description: 'Start the workspace in auto-loop mode (optional).' },
-                auto_loop_session_mode: {
-                    type: 'string',
-                    enum: ['per_task', 'continuous'],
-                    description: "Auto-loop session mode when auto_loop is true (optional, default 'per_task').",
-                },
-                skip_setup_script: { type: 'boolean', description: "Skip the project's setup script (optional)." },
-            },
-            required: ['name', 'project_path', 'source_branch', 'working_branch'],
-        },
-        annotations: { destructiveHint: false, openWorldHint: false },
-    },
-    {
-        name: 'archive_workspace',
-        description: 'Archive a workspace by id, like the "Archiver" action in the workspace context menu. Requires the Kōbō backend server to be running.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                workspace_id: { type: 'string', description: 'Workspace id, from list_workspaces.' },
-            },
-            required: ['workspace_id'],
-        },
-        annotations: { destructiveHint: false, openWorldHint: false },
-    },
     {
         name: 'stop_workspace',
         description: 'Force-stop the currently running agent session on a workspace, like the red "Arrêter" button in the chat header. Requires the Kōbō backend server to be running. Safe to call when nothing is running.',
@@ -751,8 +700,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     : {}),
             };
         }
-        if (WORKSPACE_DIALOGUE_TOOLS.some((tool) => tool.name === name)) {
-            if (workspaceId && a.workspace_id === workspaceId && name === 'send_workspace_message')
+        if (isWorkspaceCreationTool(name) ||
+            isWorkspaceLifecycleTool(name) ||
+            isWorkspaceGroupMessageTool(name) ||
+            WORKSPACE_DIALOGUE_TOOLS.some((tool) => tool.name === name)) {
+            if (workspaceId &&
+                ((a.workspace_id === workspaceId && name === 'send_workspace_message') ||
+                    (name === 'send_workspace_group_message' &&
+                        Array.isArray(a.workspace_ids) &&
+                        a.workspace_ids.includes(workspaceId))))
                 return fail('Use the normal conversation to communicate in your own workspace.');
             return await callWorkspaceDialogueTool(backendUrl, name, a, process.env.KOBO_NETWORK_TOKEN, process.env.KOBO_MCP_CLIENT_NAME ?? server.getClientVersion()?.name);
         }
@@ -1025,50 +981,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const tag = typeof a.tag === 'string' ? a.tag : undefined;
             return ok(listWorkspacesHandler(db, { includeArchived, tag }));
         }
-        if (name === 'create_workspace') {
-            const workspaceName = a.name;
-            const projectPath = a.project_path;
-            const sourceBranch = a.source_branch;
-            const workingBranch = a.working_branch;
-            if (!workspaceName || !projectPath || !sourceBranch || !workingBranch) {
-                return fail('name, project_path, source_branch, and working_branch parameters are required');
-            }
-            try {
-                const created = await backendRequest('POST', '/api/workspaces', {
-                    name: workspaceName,
-                    projectPath,
-                    sourceBranch,
-                    workingBranch,
-                    model: a.model,
-                    reasoningEffort: a.reasoning_effort,
-                    engine: a.engine,
-                    description: a.description,
-                    tags: a.tags,
-                    tasks: a.tasks,
-                    acceptanceCriteria: a.acceptance_criteria,
-                    agentPermissionMode: a.agent_permission_mode,
-                    autoLoop: a.auto_loop,
-                    autoLoopSessionMode: a.auto_loop_session_mode,
-                    skipSetupScript: a.skip_setup_script,
-                });
-                return ok(created);
-            }
-            catch (err) {
-                return fail(backendErrorMessage(err));
-            }
-        }
-        if (name === 'archive_workspace') {
-            const targetId = a.workspace_id;
-            if (!targetId)
-                return fail('workspace_id parameter is required');
-            try {
-                const result = await backendRequest('POST', `/api/workspaces/${targetId}/archive`);
-                return ok(result);
-            }
-            catch (err) {
-                return fail(backendErrorMessage(err));
-            }
-        }
         if (name === 'stop_workspace') {
             const targetId = a.workspace_id;
             if (!targetId)
@@ -1087,7 +999,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return fail(err instanceof Error ? err.message : String(err));
     }
 });
-const transport = new StdioServerTransport();
+const transport = new StdioServerTransport(process.stdin, process.stdout, {
+    // Include the JSON-lines delimiter in addition to the HTTP envelope budget.
+    maxBufferSize: MAX_MCP_CREATION_REQUEST_BYTES + 1,
+});
 server.connect(transport).catch((err) => {
     console.error('[kobo-tasks-server] Fatal:', err);
     process.exit(1);

package/dist/mcp-server/workspace-dialogue-client.js

@@ -1,15 +1,27 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { isMemoryToolName, validateMemoryToolArguments } from '../shared/memory-tools.js';
+import { isWorkspaceCreationTool, validateWorkspaceCreationArguments } from '../shared/workspace-creation-tools.js';
 import { validateDialogueArguments } from '../shared/workspace-dialogue-tools.js';
+import { isWorkspaceGroupMessageTool, validateWorkspaceGroupMessageArguments, } from '../shared/workspace-group-message-tools.js';
+import { isWorkspaceLifecycleTool, validateWorkspaceLifecycleArguments } from '../shared/workspace-lifecycle-tools.js';
 import { normalizeClientName } from '../shared/workspace-message-types.js';
 /** Stateless HTTP bridge: external stdio clients never own agent runtime state. */
 export async function callWorkspaceDialogueTool(backendUrl, name, args, token, clientName) {
     const arguments_ = isMemoryToolName(name)
         ? validateMemoryToolArguments(name, args, true)
-        : validateDialogueArguments(name, args);
+        : isWorkspaceCreationTool(name)
+            ? validateWorkspaceCreationArguments(name, args)
+            : isWorkspaceLifecycleTool(name)
+                ? validateWorkspaceLifecycleArguments(name, args)
+                : isWorkspaceGroupMessageTool(name)
+                    ? validateWorkspaceGroupMessageArguments(name, args)
+                    : validateDialogueArguments(name, args);
     const client = new Client({ name: 'kobo-stdio-bridge', version: '1.0.0' });
-    const signal = AbortSignal.timeout(30_000);
+    // Creation can include forge reads, worktree setup and user setup scripts.
+    // A timed-out creation is ambiguous and must never be retried automatically.
+    const timeout = isWorkspaceCreationTool(name) || isWorkspaceLifecycleTool(name) ? 15 * 60_000 : 30_000;
+    const signal = AbortSignal.timeout(timeout);
     const transport = new StreamableHTTPClientTransport(new URL(`${backendUrl.replace(/\/$/, '')}/api/mcp`), {
         requestInit: {
             signal,
@@ -23,7 +35,7 @@ export async function callWorkspaceDialogueTool(backendUrl, name, args, token, c
     });
     try {
         await client.connect(transport, { signal });
-        return await client.callTool({ name, arguments: arguments_ }, undefined, { signal });
+        return await client.callTool({ name, arguments: arguments_ }, undefined, { signal, timeout });
     }
     finally {
         await client.close();

package/dist/server/db/migrations.js

@@ -6,6 +6,7 @@ import { initReviewReturnSchema, migrateDurableReviewReturns } from './review-re
 import { initSchema } from './schema.js';
 import { initSearchSchema } from './search-schema.js';
 import { initSessionHandoffSchema } from './session-handoff-schema.js';
+import { initWorkspaceMessageBatchSchema } from './workspace-message-batch-schema.js';
 /** Ordered registry of all schema migrations. Append new entries at the end. */
 export const migrations = [
     {
@@ -808,6 +809,7 @@ export const migrations = [
             initAutoLoopFinalReviewSchema(db);
         },
     },
+    { version: 53, name: 'workspace-group-message-receipts', migrate: initWorkspaceMessageBatchSchema },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -5,6 +5,7 @@ import { initMemorySchema } from './memory-schema.js';
 import { initReviewReturnSchema } from './review-return-schema.js';
 import { initSearchSchema } from './search-schema.js';
 import { initSessionHandoffSchema } from './session-handoff-schema.js';
+import { initWorkspaceMessageBatchSchema } from './workspace-message-batch-schema.js';
 /** Create all tables and indexes for a fresh install. Not used for upgrades -- see migrations.ts. */
 export function initSchema(db) {
     db.exec(`
@@ -240,4 +241,5 @@ export function initSchema(db) {
     initAutoLoopFinalReviewSchema(db);
     initSessionHandoffSchema(db);
     initMemorySchema(db);
+    initWorkspaceMessageBatchSchema(db);
 }

package/dist/server/db/workspace-message-batch-schema.js

@@ -0,0 +1,9 @@
+/** Receipts survive workspace deletion; message bodies live only in normal chat/loop storage. */
+export function initWorkspaceMessageBatchSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS workspace_message_batches (
+    id TEXT PRIMARY KEY,
+    fingerprint TEXT NOT NULL,
+    receipt_json TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`);
+}