@loicngr/kobo 2.1.16 → 2.1.19

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
 
@@ -125,6 +126,7 @@ src/
 | `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 |
+| `session_progress_bars` | agent-reported session activities, producer ordering, terminal state and durable individual dismissal (v54); CASCADE DELETE on workspace/session |
 | `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 |
@@ -199,6 +201,31 @@ Every feature that touches the schema:
 
 ## WebSocket protocol
 
+Session progress bars use the separate `progress:changed` ephemeral event with a
+public record payload and workspace/session envelope. Persist the row before
+broadcasting; never append numeric updates to chat history or overload native
+`subagent:progress`. Clients hydrate on selected-session changes and reconnect,
+merge server revisions, and preserve dismissal across races. Success visibility
+expires at the stored completion time plus five seconds, not five seconds after
+each fetch. Three rows are initially visible with bounded expandable overflow.
+
+The four progress MCP tools share service validation across workspace stdio,
+global stdio and HTTP. Internal ownership comes from the dedicated per-launch
+`KOBO_PROGRESS_SESSION_TOKEN`, independent of memory modes/budgets; external
+calls explicitly select an existing workspace/session. Revoke internal writers
+when stopping starts, but interrupt their remaining bars only on confirmed
+controller closure. Late callbacks must not affect a replacement launch or
+reopen a closed database. Startup reconciles lost internal reporters while
+preserving external ones. An interrupted reporter is not proof of cancelled
+background work. Operational reporting never satisfies auto-loop verification.
+
+Retain scoped activity-key fingerprints, producer sequences and dismissed rows
+for retries; subsequent updates cannot resurrect a dismissed indicator or undo a
+terminal state. Bound labels, steps, page size, active/retained records and update
+frequency. Launch prompts instruct parent agents and their delegates to report
+long-running work; restricted review/handoff launches receive only the explicit
+operational-tool exception, never broader mutation permissions.
+
 Claude streaming input is correlated by per-message UUIDs. A result can cover
 several prompts through `user_message_uuids` (messages folded into one turn),
 not one result per sent message. Retire only the matching yielded inputs;
@@ -248,6 +275,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.
@@ -267,6 +345,29 @@ When adding features touching `notion-service.ts`, remember: **no token = no fea
 
 See the "Notion integration" section of the README for the end-user setup guide.
 
+### Launch instructions
+
+`src/shared/launch-instructions.ts` composes application-owned MCP discovery,
+permissions, progress reporting and continuation rules for both engines on every
+fresh/resumed launch. Prefer discovering the available tool schemas to embedding
+a duplicate catalogue. Keep Plan conversation-only; template approval cannot
+expand tool permissions. Initial writable auto-loop launches seed tasks and end;
+manual launches implement under the workflow policy. Preserve custom templates
+and frozen migration text when changing generated guidance.
+
+The engine's `onPromptPrepared` callback supplies only its textual Kōbō prefix and
+system append. Initial creation and pending initial retries opt into a single
+session-scoped `user:message` with `sender: system-prompt`, displayed as Kōbō
+instructions. Snapshot the orchestration context before memory is appended; never
+serialize engine options, capability tokens or memory bodies into chat. This is
+a prepared-launch record, not delivery confirmation. Snapshot failures must not
+prevent launch. Require durable snapshot persistence before clearing the pending
+initial prompt, using a compare-and-clear against the original mission. Async
+preparation failures must leave that pending prompt available for retry. Historical rows remain unchanged. Handoff generation is enforced
+read-only with only its managed capability-scoped report and operational progress
+metadata exceptions. Ordinary Claude Plan launches cannot promote themselves
+through `ExitPlanMode`; a permission change requires a new launch.
+
 ### Agent engines
 
 Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:

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.19
+
+- feat(progress): add session activity bars and improve launch prompts
+
+## 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

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`:
@@ -849,6 +857,44 @@ The **External LLM access (MCP)** panel within global Network access settings pr
 
 External senders can supply `idempotency_key` once per intended message and reuse it on retries. The durable receipt survives backend restarts and event retention. An uncertain delivery is explicitly reported and never automatically sent again; see the MCP guide for response codes and limitations.
 
+## Session progress bars
+
+Agents can report long-running tests, builds or reviews through the
+`create_progress_bar`, `update_progress_bar`, `finish_progress_bar` and
+`list_progress_bars` MCP tools. These tools are available through the workspace
+MCP server, global stdio and the external HTTP endpoint. External clients select
+an existing workspace and session; reporting progress never launches an agent.
+
+Bars appear above the message input for the **selected session**, even while you
+scroll its conversation. Each has an activity label, an optional current step,
+and either measured progress or an indeterminate indicator. Three bars are shown
+initially; **See others** expands a bounded list. Progress is reported by the
+agent, not measured automatically by Kōbō, and does not validate workspace tasks
+or acceptance criteria.
+
+A successful bar disappears five seconds after its recorded completion. Failed
+activities stay visible until you dismiss them. Closing a bar only hides that
+indicator: work continues, later updates cannot bring it back, and new activities
+still appear. Dismissal is saved on the server and shared across browser tabs
+and reloads. Reconnecting does not restart the success display timer.
+
+If an internal reporter's agent runtime closes before completion, its bar shows
+that **reporting was interrupted**. This does not prove that an independently
+running shell command was cancelled. On server restart, internal reporters from
+the previous process are interrupted; external reporters may still be running
+elsewhere, so their last state is preserved. A new internal launch uses a new
+reporting identity.
+
+Workspace launch instructions require agents to use these tools for long tasks
+and pass the requirement to subagents. When a restricted subagent cannot access
+the tools, its parent reports the activity on its behalf. Reporting permissions
+do not grant permission to edit project files or complete tasks during a review.
+
+The service retains at most 1,000 indicators per session, with at most 32 running
+at once. Hidden records are retained so retries cannot recreate dismissed bars.
+The [MCP progress guide](src/mcp-server/README.md#session-progress-tools) documents
+arguments, ordering, retry behavior and update limits.
+
 ## Persistent memory
 
 Kōbō stores deliberate, concise facts in SQLite, independently of Claude Code's native memory and provider chat history. Claude Code and Codex read the same Kōbō scopes, so a fact saved in one engine can be available to the other. There is no background transcript extractor or extra LLM call: agents must deliberately use the memory tools to save useful knowledge.
@@ -1108,27 +1154,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).
@@ -1142,11 +1192,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
@@ -1157,14 +1209,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
 
@@ -1175,12 +1228,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
@@ -1264,6 +1317,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
@@ -2042,11 +2125,19 @@ for the same reason the API refuses the change. A change returns HTTP 409 while
 
 Fresh defaults are manual. Existing settings/workspaces migrate to the previous automatic behavior for compatibility. Manual requires an explicit user request for that action; automatic supplies the workflow preference for the mission. Narrower user instructions always win. Publish means PR/MR creation, description updates and comments; merging needs separate authorization. Explicit Git-panel actions remain available. These preferences are agent instructions, not a shell-command filter or an OS sandbox.
 
-Plan is never promoted to Bypass by auto-loop preparation, an agent tool event, or loop enablement. Preparation can run in Plan; execution/finalization blocks with an actionable message until an execution mode is explicitly selected.
+Plan is never promoted to Bypass by auto-loop preparation, an agent tool event, or loop enablement. The initial Plan session provides its plan in the conversation without saving files or seeding tasks. Autonomous task preparation, execution and finalization block with an actionable message until an execution mode is explicitly selected.
 
 Notion token environment overrides are applied consistently to both token variables passed to the child process. Explicit `OPENAPI_MCP_HEADERS` remain authoritative for compatibility and are not replaced by the resolved token. Direct integration configuration and legacy fallback are only read when an integration is used; opening Settings does not start a Notion users lookup. Connection tests and users refresh are explicit actions.
 
 
+### Initial Kōbō instructions
+
+New workspaces receive the mission, repository context, current permissions, current phase and expected result. Agents first consult the available managed MCP tool descriptions and schemas, then prefer relevant Kōbō tools for workspace operations. This is not a request to call every tool or poll. Long tasks and delegated work use labeled progress bars; dismissing a bar hides only that activity and does not cancel its work.
+
+Plan launches remain conversation-only. Writable auto-loop launches prepare the plan and task list before returning control to the loop; writable manual launches implement after plan approval, under the configured Git policy. Custom brainstorming, Notion and Sentry templates are preserved; they cannot expand launch permissions or authorize commits automatically. Review returns and handoff reports remain read-only, with only their scoped report and operational progress tools allowed. Plan approval does not change permissions; explicitly select an execution mode in Kōbō and start a new launch to implement.
+
+The expandable **Kōbō instructions** chat entry records the application-owned text prepared by the engine builder for the initial launch or a pending initial-prompt retry, including progress guidance, continuation rules, workflow policy and managed integration notices. The pending initial mission is retained until this entry is durably recorded, so a failure during asynchronous launch preparation remains retryable. A later replacement mission is never cleared by an earlier launch. Preparation is not proof of provider delivery. The provider's own system preset is not included. Retrieved memory bodies and capability tokens are not copied to chat; memory usage remains visible separately in the Memory panel. Existing historical prompt entries retain their original content. Ordinary resumes receive current instructions without creating another initial-prompt entry.
+
 ### Managed integration MCPs in agent sessions
 
 **Test connection** uses the saved direct configuration when present, otherwise the

package/README.md

@@ -24,6 +24,8 @@ Kōbō (工房, "workshop") turns *one agent, one terminal* into a real workflow
 
 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.
 
+[Session progress bars](CONFIGURATION.md#session-progress-bars) show labelled long-running activities above the message input, including work delegated to subagents. Agents report progress through internal or external MCP; you can dismiss an individual bar without stopping its work.
+
 ## 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.
@@ -116,7 +118,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
 
@@ -164,4 +168,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,12 +4,14 @@ 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 { INTERNAL_PROGRESS_BAR_TOOLS, isProgressBarTool, PROGRESS_BAR_TOOLS } from '../shared/progress-bar-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 { callProgressBarTool } from './progress-bar-client.js';
 import { callWorkspaceDialogueTool } from './workspace-dialogue-client.js';
 const finalReviewToken = process.env.KOBO_FINAL_REVIEW_TOKEN;
 const finalReviewSessionId = process.env.KOBO_FINAL_REVIEW_SESSION_ID;
@@ -213,7 +215,7 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'mark_auto_loop_ready',
-        description: 'CALL ONLY at the end of a `/kobo-prep-autoloop` grooming session, once all tasks look atomic and implementable in one session. Flips a flag on the workspace that unlocks the auto-loop toggle in the UI. Do NOT call during normal sessions.',
+        description: 'CALL at the end of authorized auto-loop preparation, either during initial workspace creation with auto-loop or a later `/kobo-prep-autoloop` grooming session. First ensure tasks are atomic, implementable, and include the required verification/finalization work. Marks preparation ready; this is a mutation and cannot be called from a read-only launch. Do NOT call during unrelated normal sessions.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
@@ -328,7 +330,7 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'cron_create',
-        description: 'Schedule a recurring trigger on THIS workspace. At each fire, Kōbō waits for the workspace to be idle (no active session) and then resumes the same conversation by injecting `prompt` as the next user message — same UX as `schedule_wakeup` but recurring. Skip-if-active: if a session is already running when the timer fires, that occurrence is skipped, the next occurrence is computed, and the cron continues. The cron persists across server restarts (skip-missed semantics on boot — no catchup spam). Delete with `cron_delete(id)`. Multiple crons per workspace are allowed.',
+        description: 'Schedule a recurring trigger on THIS workspace. At each fire, Kōbō checks that the workspace is idle (no active session), then injects `prompt` into the conversation pinned when scheduled (`mode=resume`) or starts a new session (`mode=fresh`). Skip-if-active: if a session is already running when the timer fires, that occurrence is skipped, the next occurrence is computed, and the cron continues. The cron persists across server restarts (skip-missed semantics on boot — no catchup spam). Delete with `cron_delete(id)`. Multiple crons per workspace are allowed.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -538,7 +540,7 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'schedule_wakeup',
-        description: 'WHEN: use this whenever you would otherwise WAIT for or POLL a long-running task (test suite, CI, build, deploy, or external state) — never block your turn with sleep/poll loops, and never end a turn merely "waiting" on a background job, because the session goes idle and will not resume on its own. CALL to schedule a follow-up turn on THIS workspace after a delay. End the current turn normally; once it finishes and the workspace is idle, Kōbō waits `delaySeconds`, then resumes the same conversation by injecting `prompt` as the next user message. The wakeup is scoped to the current workspace and resumes its latest session — you cannot target another workspace or another session. If a turn is still active when the timer fires, the wakeup is skipped (status: `session-active`). Replaces any previously pending wakeup on this workspace. Delay is clamped to [60, 21600] seconds (1min to 6h). Prefer this over the built-in `ScheduleWakeup` tool — it is the SDK-supported entry point.',
+        description: 'WHEN: the parent agent needs a durable later check for detached work or external state without a tracked completion notification. Do not duplicate SDK tracked-job continuation or schedule merely to advance auto-loop; subagents must leave the one workspace wakeup to their parent. Delay is measured from this call and clamped to [60, 21600] seconds. The wakeup targets this workspace and the session selected at scheduling time, not whichever session is newest later. It is deferred while busy when it cannot be delivered to the waiting controller; active auto-loop receives it as a queued instruction. Replaces the existing pending wakeup on this workspace, so preserve unrelated scheduled intent. Supply a concrete follow-up prompt and optional reason. End the current turn normally; delivery timing also depends on workspace availability. Prefer this durable Kōbō tool over native ScheduleWakeup',
         inputSchema: {
             type: 'object',
             properties: {
@@ -566,6 +568,7 @@ const WORKSPACE_SCOPED_TOOLS = [
         annotations: { destructiveHint: false, openWorldHint: false },
     },
     ...MEMORY_TOOL_DEFINITIONS,
+    ...INTERNAL_PROGRESS_BAR_TOOLS,
 ];
 const GLOBAL_TOOLS = [
     ...WORKSPACE_DIALOGUE_TOOLS,
@@ -573,6 +576,7 @@ const GLOBAL_TOOLS = [
     ...WORKSPACE_LIFECYCLE_TOOLS,
     ...WORKSPACE_GROUP_MESSAGE_TOOLS,
     ...EXTERNAL_MEMORY_TOOL_DEFINITIONS,
+    ...PROGRESS_BAR_TOOLS,
     {
         name: 'list_workspaces',
         description: 'List Kōbō workspaces with their id, title, status, tags, and creation date. Set tag to return only workspaces carrying that exact tag. Works even when the Kōbō backend server is not running (reads the database directly). Use this to discover existing workspaces before creating one or targeting one with archive_workspace/stop_workspace.',
@@ -617,12 +621,19 @@ function availableTools() {
     // A workspace process exposes the capability-bound memory tools exactly once.
     // Unbound/global stdio exposes the external bridge variant instead.
     const tools = workspaceId
-        ? [...WORKSPACE_SCOPED_TOOLS, ...GLOBAL_TOOLS.filter((tool) => !isMemoryToolName(tool.name))]
+        ? [
+            ...WORKSPACE_SCOPED_TOOLS,
+            ...GLOBAL_TOOLS.filter((tool) => !isMemoryToolName(tool.name) && !isProgressBarTool(tool.name)),
+        ]
         : GLOBAL_TOOLS;
     return tools.filter((tool) => handoffId && handoffToken
-        ? tool.name === 'submit_session_handoff' || tool.annotations?.readOnlyHint === true
+        ? tool.name === 'submit_session_handoff' ||
+            tool.annotations?.readOnlyHint === true ||
+            (isProgressBarTool(tool.name) && !!process.env.KOBO_PROGRESS_SESSION_TOKEN)
         : finalReviewToken && finalReviewSessionId
-            ? tool.name === 'submit_final_review' || tool.annotations?.readOnlyHint === true
+            ? tool.name === 'submit_final_review' ||
+                tool.annotations?.readOnlyHint === true ||
+                (isProgressBarTool(tool.name) && !!process.env.KOBO_PROGRESS_SESSION_TOKEN)
             : tool.name !== 'submit_session_handoff' && tool.name !== 'submit_final_review');
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: availableTools() }));
@@ -676,6 +687,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 report: a.report,
             }));
         }
+        if (isProgressBarTool(name)) {
+            if (!workspaceId)
+                return await callWorkspaceDialogueTool(backendUrl, name, a, process.env.KOBO_NETWORK_TOKEN, process.env.KOBO_MCP_CLIENT_NAME ?? server.getClientVersion()?.name);
+            return await callProgressBarTool({
+                backendUrl,
+                name,
+                args: a,
+                capability: process.env.KOBO_PROGRESS_SESSION_TOKEN,
+                networkToken: process.env.KOBO_NETWORK_TOKEN,
+            });
+        }
         if (isMemoryToolName(name)) {
             if (!workspaceId) {
                 return await callWorkspaceDialogueTool(backendUrl, name, a, process.env.KOBO_NETWORK_TOKEN, process.env.KOBO_MCP_CLIENT_NAME ?? server.getClientVersion()?.name);

package/dist/mcp-server/progress-bar-client.js

@@ -0,0 +1,20 @@
+import { isProgressBarTool } from '../shared/progress-bar-tools.js';
+export async function callProgressBarTool(input) {
+    if (!isProgressBarTool(input.name))
+        throw new TypeError('Unknown progress tool');
+    if (!input.capability)
+        throw new Error('Progress capability is unavailable for this process');
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Kobo-Progress-Session': input.capability,
+    };
+    if (input.networkToken)
+        headers['X-Kobo-Token'] = input.networkToken;
+    const response = await (input.fetcher ?? fetch)(`${input.backendUrl.replace(/\/$/, '')}/api/progress-bars/agent/${input.name}`, { method: 'POST', headers, body: JSON.stringify(input.args), signal: AbortSignal.timeout(30_000) });
+    const data = (await response.json());
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+        structuredContent: data,
+        ...(!response.ok ? { isError: true } : {}),
+    };
+}

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

@@ -1,6 +1,7 @@
 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 { isProgressBarTool, validateProgressBarArguments } from '../shared/progress-bar-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';
@@ -8,15 +9,34 @@ import { isWorkspaceLifecycleTool, validateWorkspaceLifecycleArguments } from '.
 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) {
+    if (isProgressBarTool(name)) {
+        try {
+            validateProgressBarArguments(name, args, true);
+        }
+        catch (error) {
+            const data = {
+                error: error instanceof Error ? error.message : 'Invalid arguments',
+                status: 400,
+                code: 'invalid_arguments',
+            };
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(data) }],
+                structuredContent: data,
+            };
+        }
+    }
     const arguments_ = isMemoryToolName(name)
         ? validateMemoryToolArguments(name, args, true)
-        : isWorkspaceCreationTool(name)
-            ? validateWorkspaceCreationArguments(name, args)
-            : isWorkspaceLifecycleTool(name)
-                ? validateWorkspaceLifecycleArguments(name, args)
-                : isWorkspaceGroupMessageTool(name)
-                    ? validateWorkspaceGroupMessageArguments(name, args)
-                    : validateDialogueArguments(name, args);
+        : isProgressBarTool(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' });
     // Creation can include forge reads, worktree setup and user setup scripts.
     // A timed-out creation is ambiguous and must never be retried automatically.

package/dist/server/db/migrations.js

@@ -2,6 +2,7 @@ import { initAutoLoopFinalReviewSchema } from './auto-loop-final-review-schema.j
 import { initAutoLoopSchema } from './auto-loop-schema.js';
 import { initMcpMessageSchema } from './mcp-message-schema.js';
 import { migrateMemorySchema } from './memory-schema.js';
+import { initProgressBarSchema } from './progress-bar-schema.js';
 import { initReviewReturnSchema, migrateDurableReviewReturns } from './review-return-schema.js';
 import { initSchema } from './schema.js';
 import { initSearchSchema } from './search-schema.js';
@@ -810,6 +811,7 @@ export const migrations = [
         },
     },
     { version: 53, name: 'workspace-group-message-receipts', migrate: initWorkspaceMessageBatchSchema },
+    { version: 54, name: 'session-progress-bars', migrate: initProgressBarSchema },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;