@loicngr/kobo 2.1.16 → 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
 
@@ -248,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.

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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

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`:
@@ -1108,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).
@@ -1142,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
@@ -1157,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
 
@@ -1175,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
@@ -1264,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

@@ -116,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
 
@@ -164,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/server/index.js

@@ -20,6 +20,7 @@ import gitRouter from './routes/git.js';
 import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
 import integrationsRouter from './routes/integrations.js';
+import maintenanceRouter from './routes/maintenance.js';
 import mcpRouter from './routes/mcp.js';
 import memoryRouter from './routes/memory.js';
 import { migrationRouter } from './routes/migration.js';
@@ -178,6 +179,7 @@ app.route('/api/workspaces', documentsRouter);
 app.route('/api/workspaces', exportRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
+app.route('/api/maintenance', maintenanceRouter);
 app.route('/api/engines', enginesRouter);
 app.route('/api/environment', environmentRouter);
 app.route('/api/integrations', integrationsRouter);

package/dist/server/middleware/workspace-creation-maintenance.js

@@ -0,0 +1,13 @@
+import { beginWorkspaceCreation } from '../services/update-maintenance-service.js';
+/** Admission remains held across every await and the handler's rollback paths. */
+export const workspaceCreationMaintenance = async (c, next) => {
+    const release = beginWorkspaceCreation();
+    if (!release)
+        return c.json({ code: 'update-maintenance', error: 'Workspace creation is unavailable during update maintenance' }, 503);
+    try {
+        await next();
+    }
+    finally {
+        release();
+    }
+};

package/dist/server/routes/maintenance.js

@@ -0,0 +1,32 @@
+import { Hono } from 'hono';
+import { isIdleForUpdate, resumeAfterUpdateMaintenance } from '../services/agent/orchestrator.js';
+import { acquireUpdateMaintenance, isUpdateMaintenanceActive, releaseUpdateMaintenance, } from '../services/update-maintenance-service.js';
+import { preserveForUpdateMaintenance } from '../services/wakeup-service.js';
+/** Protected by the same network-token/Host/Origin middleware as other APIs. */
+const app = new Hono();
+app.get('/update', (c) => c.json({ protocol: 1, active: isUpdateMaintenanceActive() }));
+app.on(['POST', 'DELETE'], '/update', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.owner !== 'string' || !/^[a-f0-9]{32}$/.test(body.owner)) {
+        return c.json({ error: 'Expected a 32-character update reservation identifier' }, 400);
+    }
+    if (c.req.method === 'DELETE') {
+        if (!releaseUpdateMaintenance(body.owner))
+            return c.json({ error: 'Update reservation belongs to another owner' }, 409);
+        resumeAfterUpdateMaintenance();
+        return c.json({ protocol: 1, active: false });
+    }
+    // Both operations are synchronous: no agent can start between this check and reservation.
+    const result = acquireUpdateMaintenance(body.owner, () => {
+        if (!isIdleForUpdate())
+            return false;
+        // Commit deferral before acknowledging admission. Future wakeups may become
+        // overdue while the stopped volume is backed up and migrated.
+        preserveForUpdateMaintenance();
+        return true;
+    });
+    if (result !== 'acquired')
+        return c.json({ error: result === 'busy' ? 'Kōbō is busy' : 'Update already reserved' }, 409);
+    return c.json({ protocol: 1, active: true });
+});
+export default app;

package/dist/server/routes/pull-requests.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { Hono } from 'hono';
+import { workspaceCreationMaintenance } from '../middleware/workspace-creation-maintenance.js';
 import { getForgeProvider } from '../services/forge/registry.js';
 import { resolveForge } from '../services/forge/resolve.js';
 import * as prCheckout from '../services/pr-checkout-service.js';
@@ -86,7 +87,7 @@ app.post('/diagnose', async (c) => {
         return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
     }
 });
-app.post('/resolve', async (c) => {
+app.post('/resolve', workspaceCreationMaintenance, async (c) => {
     try {
         const body = await c.req
             .json()

package/dist/server/routes/workspaces.js

@@ -19,6 +19,7 @@ import { MAX_ATTACHMENT_REQUEST_BYTES } from '../../shared/attachments.js';
 import { AUTO_LOOP_HARD_RULES, buildAutoLoopGroomingSteps, buildGroomingIntro } from '../../shared/auto-loop-prompts.js';
 import { getDb } from '../db/index.js';
 import { migrationGuard } from '../middleware/migration-guard.js';
+import { workspaceCreationMaintenance } from '../middleware/workspace-creation-maintenance.js';
 import { listEngines } from '../services/agent/engines/registry.js';
 import * as agentManager from '../services/agent/orchestrator.js';
 import * as archiveScriptService from '../services/archive-script-service.js';
@@ -452,7 +453,7 @@ const creationBodyLimit = bodyLimit({
     maxSize: MAX_ATTACHMENT_REQUEST_BYTES,
     onError: (c) => c.json({ error: 'Workspace creation request is too large', step: 'validate' }, 413),
 });
-app.post('/', migrationGuard, creationBodyLimit, async (c) => {
+app.post('/', workspaceCreationMaintenance, migrationGuard, creationBodyLimit, async (c) => {
     // Declared outside the try so the outermost catch (any unforeseen throw,
     // including a malformed request body) can still name a step instead of
     // leaving the create-progress channel silent. Updated in lockstep with

package/dist/server/services/agent/orchestrator.js

@@ -20,6 +20,7 @@ import { buildReviewReturnPrompt, claimReviewReturn, completeReviewReturn, getRe
 import { activateSession, SESSION_RECENCY_ORDER } from '../session-activity-service.js';
 import { requestHandoffStop, suspendHandoffTransfers } from '../session-handoff-runtime.js';
 import { getEffectiveSettings, getGlobalSettings } from '../settings-service.js';
+import { isUpdateMaintenanceActive } from '../update-maintenance-service.js';
 import { refreshNow } from '../usage/poller.js';
 import * as wakeupService from '../wakeup-service.js';
 import { emit, emitEphemeral } from '../websocket-service.js';
@@ -67,7 +68,7 @@ let shuttingDown = false;
 let capacityTimer;
 const stoppedCapacityOwners = new Set();
 function notifyCapacityAvailable(stoppedWorkspaceId) {
-    if (shuttingDown)
+    if (isShuttingDown())
         return;
     stoppedCapacityOwners.add(stoppedWorkspaceId);
     if (capacityTimer)
@@ -77,7 +78,7 @@ function notifyCapacityAvailable(stoppedWorkspaceId) {
         capacityTimer = undefined;
         const excluded = new Set(stoppedCapacityOwners);
         stoppedCapacityOwners.clear();
-        if (shuttingDown)
+        if (isShuttingDown())
             return;
         try {
             resumePendingReviewReturns();
@@ -1365,7 +1366,7 @@ function revokeControllerMemoryCapability(controller) {
 const reviewReturnDispatchOwners = new Map();
 /** Resume durable review work only after the previous runtime has closed and admission allows it. */
 export function resumePendingReviewReturns(onlyWorkspaceId) {
-    if (shuttingDown)
+    if (isShuttingDown())
         return;
     for (const pending of listReviewReturns()) {
         const id = pending.workspaceId;
@@ -1465,6 +1466,8 @@ export function cancelReviewReturn(workspaceId) {
  * query the controller via `_getControllers()` for tests.
  */
 export function startAgent(workspaceId, workingDir, prompt, model, resume = false, agentPermissionMode, existingSessionId, reasoningEffort, beforeDispatch, launch) {
+    if (isUpdateMaintenanceActive())
+        throw new Error('Cannot start an agent during update maintenance');
     if (shuttingDown)
         throw new Error('Cannot start an agent while the server is shutting down');
     assertWorkspaceLifecycleAvailable(workspaceId, launch?.lifecycleOwner);
@@ -1914,7 +1917,20 @@ export async function stopAllAgents(timeoutMs = 3_000) {
 }
 /** Automatic continuations must preserve their durable intent during teardown. */
 export function isShuttingDown() {
-    return shuttingDown;
+    return shuttingDown || isUpdateMaintenanceActive();
+}
+/** Used synchronously by update reservation; include runtimes still closing and pending replacements. */
+export function isIdleForUpdate() {
+    if (shuttingDown || controllers.size || pendingStarts.size)
+        return false;
+    const db = getDb();
+    return (!db.prepare("SELECT 1 FROM agent_sessions WHERE status = 'running' LIMIT 1").get() &&
+        !db
+            .prepare("SELECT 1 FROM workspaces WHERE status IN ('extracting','brainstorming','executing','compacting') LIMIT 1")
+            .get());
+}
+export function resumeAfterUpdateMaintenance() {
+    notifyCapacityAvailable('');
 }
 /** Deliver a scheduled check without stopping background work or cancelling the wakeup as user input. */
 export function sendWakeupIfWaiting(workspaceId, content, expectedSessionId) {

package/dist/server/services/cron-service.js

@@ -7,6 +7,7 @@ import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as autoLoopService from './auto-loop-service.js';
 import * as settingsService from './settings-service.js';
+import { deferForUpdateMaintenance } from './update-maintenance-service.js';
 import { emitEphemeral } from './websocket-service.js';
 export const MIN_DELAY_BETWEEN_FIRES_SECONDS = 60;
 // Node `setTimeout` stores the delay as a 32-bit signed int. Anything above
@@ -185,6 +186,12 @@ export function listAll() {
 function fireOrSkip(id) {
     if (suspended)
         return;
+    const pendingTimer = timers.get(id);
+    if (deferForUpdateMaintenance(`cron:${id}`, () => {
+        if (timers.get(id) === pendingTimer)
+            fireOrSkip(id);
+    }))
+        return;
     try {
         timers.delete(id);
         const db = getDb();

package/dist/server/services/quota-backoff-service.js

@@ -1,4 +1,5 @@
 import { getDb } from '../db/index.js';
+import { deferForUpdateMaintenance } from './update-maintenance-service.js';
 import { emitEphemeral } from './websocket-service.js';
 import { getWorkspace } from './workspace-service.js';
 const timers = new Map();
@@ -142,6 +143,12 @@ export function restoreOnBoot(onFire) {
 function fireOrSkip(workspaceId) {
     if (suspended)
         return;
+    const pendingTimer = timers.get(workspaceId);
+    if (deferForUpdateMaintenance(`quota-backoff:${workspaceId}`, () => {
+        if (timers.get(workspaceId) === pendingTimer)
+            fireOrSkip(workspaceId);
+    }))
+        return;
     timers.delete(workspaceId);
     const pending = getPending(workspaceId);
     if (!pending)

package/dist/server/services/update-maintenance-service.js

@@ -0,0 +1,44 @@
+/** Process-local reservation: restart clears it; only its owner may cancel it. */
+let owner;
+const deferred = new Map();
+const creations = new Set();
+/** Reserve the entire creation/checkout, including asynchronous setup and rollback. */
+export function beginWorkspaceCreation() {
+    if (owner !== undefined)
+        return null;
+    const creation = Symbol('workspace-creation');
+    creations.add(creation);
+    return () => {
+        creations.delete(creation);
+    };
+}
+export function isUpdateMaintenanceActive() {
+    return owner !== undefined;
+}
+/** No await between inspecting runtime ownership and closing admission. */
+export function acquireUpdateMaintenance(candidate, isIdle) {
+    if (owner !== undefined)
+        return owner === candidate ? 'acquired' : 'conflict';
+    if (creations.size || !isIdle())
+        return 'busy';
+    owner = candidate;
+    return 'acquired';
+}
+/** Keep scheduler rows/deadlines untouched while delivery is suspended. */
+export function deferForUpdateMaintenance(key, callback) {
+    if (owner === undefined)
+        return false;
+    deferred.set(key, callback);
+    return true;
+}
+export function releaseUpdateMaintenance(candidate) {
+    if (owner !== candidate)
+        return false;
+    owner = undefined;
+    for (const callback of deferred.values()) {
+        const timer = setTimeout(callback, 0);
+        timer.unref?.();
+    }
+    deferred.clear();
+    return true;
+}

package/dist/server/services/wakeup-service.js

@@ -5,6 +5,7 @@ import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as autoLoopService from './auto-loop-service.js';
 import * as settingsService from './settings-service.js';
+import { deferForUpdateMaintenance, isUpdateMaintenanceActive } from './update-maintenance-service.js';
 import { emitEphemeral } from './websocket-service.js';
 const MIN_DELAY_SECONDS = 60;
 const MAX_DELAY_SECONDS = 21600;
@@ -22,6 +23,17 @@ export function suspendForShutdown() {
         clearTimeout(timer);
     timers.clear();
 }
+/** Claim valid pending wakeups before planned downtime, without changing their requested deadline. */
+export function preserveForUpdateMaintenance() {
+    const cutoff = new Date(Date.now() - STALE_WAKEUP_GRACE_MS).toISOString();
+    getDb()
+        .prepare(`UPDATE pending_wakeups SET retry_at = target_at
+       WHERE retry_at IS NULL AND julianday(target_at) >= julianday(?)
+       AND workspace_id IN (
+         SELECT id FROM workspaces WHERE archived_at IS NULL AND worktree_purged_at IS NULL
+       )`)
+        .run(cutoff);
+}
 function clamp(n, lo, hi) {
     return Math.max(lo, Math.min(hi, n));
 }
@@ -60,10 +72,10 @@ export function schedule(workspaceId, delaySeconds, prompt, reason, agentSession
     // the original durable wakeup and its timer intact, and fail the MCP receipt.
     const row = getDb()
         .prepare(`INSERT OR REPLACE INTO pending_wakeups
-       (workspace_id, target_at, prompt, reason, created_at, agent_session_id)
-     VALUES (?, ?, ?, ?, ?, ?)
+       (workspace_id, target_at, prompt, reason, created_at, agent_session_id, retry_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
      RETURNING target_at, reason`)
-        .get(workspaceId, targetAtIso, effectivePrompt, reason ?? null, new Date().toISOString(), agentSessionId ?? null);
+        .get(workspaceId, targetAtIso, effectivePrompt, reason ?? null, new Date().toISOString(), agentSessionId ?? null, isUpdateMaintenanceActive() ? targetAtIso : null);
     const pending = { targetAt: row.target_at, reason: row.reason ?? undefined };
     const existing = timers.get(workspaceId);
     if (existing)
@@ -168,6 +180,12 @@ export function rehydrate() {
 function fire(workspaceId) {
     if (suspended)
         return;
+    const pendingTimer = timers.get(workspaceId);
+    if (deferForUpdateMaintenance(`wakeup:${workspaceId}`, () => {
+        if (timers.get(workspaceId) === pendingTimer)
+            fire(workspaceId);
+    }))
+        return;
     try {
         const db = getDb();
         const row = db.prepare('SELECT * FROM pending_wakeups WHERE workspace_id = ?').get(workspaceId);

package/dist/server/services/workspace-creation-mcp-service.js

@@ -3,6 +3,7 @@ import { validateWorkspaceCreationArguments } from '../../shared/workspace-creat
 import { CLAUDE_CODE_CAPABILITIES } from './agent/engines/claude-code/capabilities.js';
 import { CODEX_CAPABILITIES } from './agent/engines/codex/capabilities.js';
 import { rollbackCreatedPrCheckout } from './pr-checkout-rollback-service.js';
+import { beginWorkspaceCreation } from './update-maintenance-service.js';
 export class WorkspaceCreationMcpError extends Error {
     status;
     stage;
@@ -79,6 +80,21 @@ function mapInput(input) {
 }
 /** Reuses the application's route validation, lifecycle guards, Git locks and rollback. */
 export async function executeWorkspaceCreationTool(name, raw, dispatch) {
+    if (name !== 'create_workspace')
+        return executeCreation(name, raw, dispatch);
+    // One lease spans both in-process routes and any compensating checkout rollback.
+    // Each route also guards direct HTTP callers; nested leases are safe.
+    const release = beginWorkspaceCreation();
+    if (!release)
+        throw new WorkspaceCreationMcpError('Workspace creation is unavailable during update maintenance', 503, 'maintenance');
+    try {
+        return await executeCreation(name, raw, dispatch);
+    }
+    finally {
+        release();
+    }
+}
+async function executeCreation(name, raw, dispatch) {
     let input;
     try {
         input = validateWorkspaceCreationArguments(name, raw);