@loicngr/kobo 2.1.20 → 2.1.22

package/AGENTS.md

@@ -201,6 +201,10 @@ Every feature that touches the schema:
 
 ## WebSocket protocol
 
+Global `showProgressBars` defaults to true (settings migration v65). The panel
+honors this preference without resetting its store or dismissing rows: MCP writes,
+revisions and success expiry continue while hidden.
+
 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
@@ -233,7 +237,7 @@ locally queued or unacknowledged messages still block `turn:completed` and
 input closure. UUID-less legacy results retain a conservative one-input
 fallback for already yielded inputs only; a result never credits a future send.
 Backpressure caps unacknowledged yielded inputs at 64, matching the SDK's result
-UUID list bound. Keep the inactivity watchdog for genuinely unanswered work.
+UUID list bound. Keep the opt-in inactivity watchdog for genuinely unanswered work.
 
 Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `task_type` by task/tool identity across progress and terminal messages, which often omit it. The existing `subagent:progress` envelope also carries this lifecycle metadata for compatibility; `local_bash`, `local_workflow` and `mcp_task` must be excluded from agent cards, busy-agent counts, chat agent-name resolution and the selective stop-subagents action. Keep tracking these jobs for engine liveness and whole-session interruption. Legacy/unknown classifications and Codex agents remain supported; never classify from a description or from the agent's last tool (`Bash` can be a real agent's current action).
 
@@ -282,6 +286,21 @@ Traefik network. It persists `/root`, mounts project paths identically on host a
 container, and leaves the Docker socket opt-in. `docs/deployment-vps.md` owns the
 operator walkthrough; `CONFIGURATION.md` compares all Compose topologies.
 
+The VPS launcher `scripts/kobo-vps-entrypoint` bootstraps the dedicated home and
+executes Kōbō as positive `KOBO_UID:KOBO_GID`, adding the socket's numeric group
+when mounted. Keep `HOME=/root` and the existing volume for compatibility. Do not
+chown existing project mounts, follow home symlinks, or resolve root bootstrap
+commands through user-writable skill/tool paths. `--exec` runs operator commands
+as the agent without rescanning ownership. Legacy root Compose entrypoints are
+preserved by the updater and need the documented explicit migration. New installer
+identity fields must not silently reconfigure old completed manifests.
+
+The updater needs the launcher beside its script to build its compatibility layer
+(including netcat/Buildx). `docs/vps-projects-and-skills.md` covers dependency/env
+setup, private registry auth, SSH dev-server access, scoped cleanup, native
+Claude/Codex skills and persistence. Project-specific OS packages and host inotify
+changes are operator-managed; the updater does not preserve arbitrary image layers.
+
 `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
@@ -300,13 +319,20 @@ 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,
+unique image tags, private backups of `/root/.config/kobo` while stopped, 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.
+The updater's `kobo.tar.gz` contains only Kōbō data, with paths relative to `/root`;
+never archive engine homes, skills, caches or projects as part of routine updates.
+Record the archive name/scope in update state. Migration checks extract regular
+SQLite files and sidecars only. Recovery must preserve the original volume and
+clone it before replacing only `.config/kobo` in the clone; a partial data archive
+must not be described as a complete home snapshot. Old `home.tar.gz` jobs retain
+their original recovery instructions.
 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
@@ -372,11 +398,18 @@ through `ExitPlanMode`; a permission change requires a new launch.
 
 Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:
 
-**Claude Code** (`claude-code/`): consumes the `@anthropic-ai/claude-agent-sdk` async iterator. The SDK manages the Claude runtime; Kōbō does not launch a separate `claude` CLI command. Authentication reuses the user's Claude login or `ANTHROPIC_API_KEY`. A settled result gets a **3 s continuation grace**, then a **15 s result-drain watchdog**. Trailing metadata and child output must not cancel the parent's drain/grace. Silence is bounded at **2 minutes** without tools, **30 minutes** for foreground tools and background shell/workflow/MCP jobs, and **10 minutes** for agents. Compaction has an absolute **10-minute** ceiling; repeated status messages cannot extend it. Human questions/permissions pause inactivity; resolution AND SDK cancellation re-evaluate that pause. Watchdogs request abort plus SDK `query.close()`; neither is proof of closure: controller ownership is released only when `EngineProcess.closed` confirms it. Never fake closure or allow a second writer if the SDK ignores termination. End emission is idempotent and timers are cleared on termination and in `finally`.
+Global `agentWatchdogEnabled` is opt-in (false for fresh and existing installs;
+settings migration v64). The orchestrator snapshots it into `StartOptions.watchdogEnabled`
+on every launch/resume for both engines. Gate stream/tool inactivity, background
+stall, compaction and failed-result-drain watchdogs; retain normal completion,
+manual stop, protocol/startup deadlines and confirmed-dead-process cleanup.
+The toggle is first in Settings → Agents and does not reconfigure active launches.
+
+**Claude Code** (`claude-code/`): consumes the `@anthropic-ai/claude-agent-sdk` async iterator. The SDK manages the Claude runtime; Kōbō does not launch a separate `claude` CLI command. Authentication reuses the user's Claude login or `ANTHROPIC_API_KEY`. A settled result gets a **3 s continuation grace**, then an opt-in **15 s result-drain watchdog**. Trailing metadata and child output must not cancel the parent's drain/grace. When watchdogs are enabled, silence is bounded at **2 minutes** without tools, **30 minutes** for foreground tools and background shell/workflow/MCP jobs, and **10 minutes** for agents. Compaction has an absolute **10-minute** ceiling; repeated status messages cannot extend it. Human questions/permissions pause inactivity; resolution AND SDK cancellation re-evaluate that pause. Watchdogs request abort plus SDK `query.close()`; neither is proof of closure: controller ownership is released only when `EngineProcess.closed` confirms it. Never fake closure or allow a second writer if the SDK ignores termination. End emission is idempotent and timers are cleared on termination and in `finally`.
 
 After the continuation grace, Claude explicitly calls `query.close()`; closing
 the input iterator alone can leave the SDK waiting for an idle notification after
-a successful result. The 15-second drain watchdog is a failed-close backstop,
+a successful result. The opt-in 15-second drain watchdog is a failed-close backstop,
 not normal cleanup. The SDK still constructs its runtime command; Kōbō's
 `spawnClaudeCodeProcess` hook tracks actual child exit and forwards stderr.
 `EngineProcess.closed` waits for both that exit and iterator completion because

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.22
+
+- feat(settings): make agent watchdogs opt-in and progress bars configurable
+- feat(update): refine `kobo-update` to backup only `.config/kobo` and improve migration handling
+
+## 2.1.21
+
+- feat(vps): introduce non-root runtime launcher and UID/GID support
+
 ## 2.1.20
 
 - fix(progress): clarify activity updates and completion

package/CONFIGURATION.md

@@ -859,6 +859,12 @@ External senders can supply `idempotency_key` once per intended message and reus
 
 ## Session progress bars
 
+**Settings → Agents → Show progress bars** (`showProgressBars`) is enabled by
+default. Saving this global preference hides or restores the panel immediately in
+the current client; other clients receive it on their next settings refresh.
+Hiding the panel does not stop reporting, dismiss activities or reset their
+success expiry timer. Individually dismissed bars stay dismissed when re-enabled.
+
 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
@@ -1183,17 +1189,20 @@ Traefik already exists. Build the image from a source checkout before starting.
 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
+The VPS example uses `kobo-vps-entrypoint`: it prepares the dedicated home volume
+then drops to `KOBO_UID:KOBO_GID` before starting Node, without `sshd`. The original
 files use the image entrypoint, which starts `sshd` even when port 22 is not published.
+See the [VPS runtime user and migration procedure](./docs/deployment-vps.md#runtime-user-and-existing-installations)
+and [project/skills operations guide](./docs/vps-projects-and-skills.md).
 
 ### 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 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.
+- **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, Compose and Buildx plugins (talk to a mounted host socket, see [Volumes](#volumes)), netcat (`nc`), `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.
+- **`git config --system --add safe.directory '*'`**: legacy Compose examples run as root while mounted repos retain the host UID; the VPS example instead uses a matching non-root UID. The image still pre-trusts mounted Git repositories. This broad trust is for a single-user environment, not 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).
 - **`EXPOSE 3000`**, `ENV SERVER_PORT=3000`, entrypoint `docker-entrypoint.sh` → `npm start`.
 
@@ -1201,6 +1210,15 @@ Build once: `docker build -t kobo:local .`
 
 ### Environment variables (Docker)
 
+The VPS template accepts `KOBO_UID` and `KOBO_GID` (positive numeric IDs, default
+1000); the installer defaults to the invoking host user's IDs. It retains
+`HOME=/root` for volume compatibility and adds the mounted Docker socket's group
+when applicable. Use `docker compose exec kobo kobo-vps-entrypoint --exec <command>`
+for logins, skills and project tooling as that user. It also sets
+`NODE_ENV=development` and `NPM_CONFIG_INCLUDE=dev` for project subprocesses;
+Kōbō continues serving its prebuilt UI/server. The base image retains its
+production default for other deployment layouts.
+
 Beyond the [general environment variables](#environment-variables), these matter specifically for a container deployment:
 
 | Variable | Where it's set | Purpose |
@@ -1353,6 +1371,9 @@ 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.
+Its `kobo.tar.gz` backup contains only `/root/.config/kobo` (database, settings and
+other Kōbō data). The rest of the persistent home, including engine credentials,
+skills and caches, is preserved in place but is not included in this backup.
 
 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
@@ -1404,15 +1425,27 @@ The model selector is populated from [`src/shared/models.ts`](./src/shared/model
 
 #### Session watchdogs
 
+**Settings → Agents → Enable agent inactivity watchdogs**, at the top of the tab,
+controls the global `agentWatchdogEnabled` boolean. It is **off by default**, for
+both new and existing installations. Each Claude/Codex launch or resume captures
+the current value; saving the toggle does not interrupt or reconfigure an already
+running agent. Stop and resume that agent to apply the new value.
+
+When off, Kōbō does not force-close a session because of stream/tool silence,
+background agents/jobs, stalled compaction, or a stalled result drain. Long silent
+CI monitoring can continue. Normal completion, manual Stop, provider failures,
+protocol request/startup deadlines and cleanup of confirmed dead processes still
+work; this switch only controls the engine watchdog deadlines described below.
+
 Kōbō distinguishes a finished response from a fully closed SDK session. Once a
 response is settled, it allows 3 seconds for continuation, then explicitly closes
 the SDK query. Normal cleanup is reported as completion, not a watchdog failure.
-A 15-second drain watchdog remains if that close fails to end the iterator.
+When watchdogs are enabled, a 15-second drain watchdog remains if that close fails to end the iterator.
 Metadata alone cannot extend this cleanup deadline. Writer ownership waits for
 both iterator completion and confirmed runtime exit, even if the SDK's own
 bounded cleanup returns earlier.
 
-Silence limits are 2 minutes without a pending tool, 10 minutes for background
+With watchdogs enabled, silence limits are 2 minutes without a pending tool, 10 minutes for background
 agents, and 30 minutes for tools (including background Bash, workflow and MCP
 jobs). A compaction has a separate absolute 10-minute limit. Waiting for your
 answer or permission pauses the inactivity watchdog.
@@ -1482,6 +1515,10 @@ rules survive restarts and can be removed from the workspace's permission UI.
 
 Each workspace can run its own dev server. The **Tools** panel shows its status, a clickable URL, the live container count, and a logs button. That works only when your project follows a small contract. This section documents the contract so the panel lights up for *your* project, not just Docker-instance projects.
 
+For remote installations, `localhost` in that link is the browser's computer.
+See [VPS dev-server access](./docs/vps-projects-and-skills.md#reach-a-development-server-from-your-pc)
+for SSH forwarding, separate proxy routes and scoped stop/cleanup commands.
+
 ### What the panel actually does
 
 Kōbō treats the dev server in two independent layers:

package/dist/server/services/agent/engines/claude-code/engine.js

@@ -565,6 +565,7 @@ export function createClaudeCodeEngine() {
             // first SDK message, re-armed on meaningful progress, suspended while a human
             // decision or a background subagent is outstanding, stopped in `finally`.
             const turnLiveness = createTurnLiveness({
+                enabled: options.watchdogEnabled === true,
                 timeoutMs: CLAUDE_STREAM_IDLE_TIMEOUT_MS,
                 onTimeout() {
                     // The armed deadline tracks whether a foreground tool call is in
@@ -618,7 +619,7 @@ export function createClaudeCodeEngine() {
                 compactionStallTimer = undefined;
             };
             const armCompactionStallTimer = () => {
-                if (compactionStallTimer)
+                if (!options.watchdogEnabled || compactionStallTimer)
                     return;
                 compactionStallTimer = setTimeout(() => {
                     compactionStallTimer = undefined;
@@ -639,7 +640,7 @@ export function createClaudeCodeEngine() {
                 compactionStallTimer.unref?.();
             };
             const armResultDrainWatchdog = () => {
-                if (resultDrainTimer)
+                if (!options.watchdogEnabled || resultDrainTimer)
                     return;
                 resultDrainTimer = setTimeout(() => {
                     console.warn(`[claude-engine] SDK generator still open ${RESULT_DRAIN_TIMEOUT_MS}ms after 'result' — forcing session:ended`);
@@ -725,6 +726,8 @@ export function createClaudeCodeEngine() {
             // Human waits suspend it independently; genuine activity restarts it.
             const armSubagentStallWatchdog = () => {
                 clearSubagentStallWatchdog();
+                if (!options.watchdogEnabled)
+                    return;
                 if (pendingResolvers.size > 0 || activeSubagentTaskIds.size === 0)
                     return;
                 const hasAgent = [...activeSubagentTaskIds].some((id) => isSubagentTask({ taskType: mapperState.taskTypes.get(id) }));

package/dist/server/services/agent/engines/codex/engine.js

@@ -205,6 +205,8 @@ export function createCodexEngine() {
             // deadline tracks the last activity, not the start of the wait.
             const armSubagentStallWatchdog = () => {
                 clearSubagentStallWatchdog();
+                if (!options.watchdogEnabled)
+                    return;
                 if (!waitingForBackgroundSubagents || pendingByCallId.size > 0 || activeSubagentThreads.size === 0)
                     return;
                 subagentStallTimer = setTimeout(() => {
@@ -251,6 +253,7 @@ export function createCodexEngine() {
                 }
             };
             const turnLiveness = createTurnLiveness({
+                enabled: options.watchdogEnabled === true,
                 timeoutMs: CODEX_TURN_IDLE_TIMEOUT_MS,
                 onTimeout() {
                     watchdogEnded = true;

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

@@ -496,6 +496,7 @@ function readEffectiveSettingsSafe(projectPath) {
 function buildMcpServers(workspaceId, extraEnv, memoryCapability) {
     const mcpServerCompiled = getCompiledMcpServerPath();
     const mcpServerSource = getMcpServerSourcePath();
+    const global = getGlobalSettings();
     return [
         {
             name: 'kobo-tasks',
@@ -508,6 +509,11 @@ function buildMcpServers(workspaceId, extraEnv, memoryCapability) {
                 KOBO_DB_PATH: getDbPath(),
                 KOBO_SETTINGS_PATH: getSettingsPath(),
                 KOBO_BACKEND_URL: `http://127.0.0.1:${backendPort}`,
+                // Behind a proxy, even internal loopback requests require network auth.
+                // Per-launch memory/progress capabilities remain independently required.
+                ...(global.networkAccessBehindProxy && global.networkAccessToken
+                    ? { KOBO_NETWORK_TOKEN: global.networkAccessToken }
+                    : {}),
             },
         },
     ];
@@ -1571,6 +1577,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), engine.id, (name) => unavailableIntegrations.push(name));
     const options = {
         workspaceId,
+        watchdogEnabled: getGlobalSettings().agentWatchdogEnabled === true,
         workingDir,
         prompt: buildAgentPrompt(`${ws ? renderWorkflowPolicy(ws.workflowPolicy) : ''}\n${integrationMcpPrompt(integrationServers, unavailableIntegrations)}\n${prompt}`, ws?.projectPath),
         model,

package/dist/server/services/agent/turn-liveness.js

@@ -13,7 +13,7 @@ export function createTurnLiveness(input) {
     let timedOut = false;
     let currentTimeoutMs = input.timeoutMs;
     const arm = () => {
-        if (!active || paused || timedOut)
+        if (input.enabled === false || !active || paused || timedOut)
             return;
         if (timer)
             clearTimeout(timer);

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

@@ -980,6 +980,22 @@ const settingsMigrations = [
                 global.memoryMode = 'hybrid';
         },
     },
+    {
+        version: 64,
+        name: 'opt-in-agent-watchdogs',
+        migrate: ({ global }) => {
+            if (typeof global.agentWatchdogEnabled !== 'boolean')
+                global.agentWatchdogEnabled = false;
+        },
+    },
+    {
+        version: 65,
+        name: 'session-progress-visibility',
+        migrate: ({ global }) => {
+            if (typeof global.showProgressBars !== 'boolean')
+                global.showProgressBars = true;
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -1035,6 +1051,8 @@ function defaultSettings() {
             terminalCommand: '',
             autoPurgeOnPrMerged: false,
             autoLoopMaxRetries: 5,
+            agentWatchdogEnabled: false,
+            showProgressBars: true,
             awaitingUserReminderMinutes: 0,
             activityDigestEnabled: true,
             maxConcurrentAgents: 2,
@@ -1183,6 +1201,10 @@ export function runSettingsMigrations(raw) {
     current.global.workflowPolicy = resolveWorkflowPolicy(current.global.workflowPolicy);
     if (!isMemoryMode(current.global.memoryMode))
         current.global.memoryMode = 'hybrid';
+    if (typeof current.global.showProgressBars !== 'boolean')
+        current.global.showProgressBars = true;
+    if (typeof current.global.agentWatchdogEnabled !== 'boolean')
+        current.global.agentWatchdogEnabled = false;
     for (const project of current.projects) {
         if (!isWorkflowPolicy(project.workflowPolicy))
             project.workflowPolicy = {};
@@ -1535,6 +1557,12 @@ export function updateGlobalSettings(input) {
             delete data.autoLoopMaxRetries;
         }
     }
+    if ('showProgressBars' in data && typeof data.showProgressBars !== 'boolean') {
+        delete data.showProgressBars;
+    }
+    if ('agentWatchdogEnabled' in data && typeof data.agentWatchdogEnabled !== 'boolean') {
+        delete data.agentWatchdogEnabled;
+    }
     // 0 is a legitimate value here — it means "never remind me" — so the floor is
     // 0, not 1. The ceiling of a day keeps a typo from arming a reminder that
     // never fires and looks like a broken feature.
@@ -1598,6 +1626,8 @@ export function updateGlobalSettings(input) {
         'terminalCommand',
         'autoPurgeOnPrMerged',
         'autoLoopMaxRetries',
+        'agentWatchdogEnabled',
+        'showProgressBars',
         'awaitingUserReminderMinutes',
         'activityDigestEnabled',
         'maxConcurrentAgents',

package/docker-compose.vps.yml

@@ -10,10 +10,16 @@ services:
     init: true
     restart: unless-stopped
     # Use the host's SSH and `docker compose exec`; no container SSH daemon.
-    entrypoint: ["node"]
-    command: ["dist/server/index.js"]
+    # Bootstrap permissions as root, then execute Kōbō/agents as this host UID/GID.
+    entrypoint: ["kobo-vps-entrypoint"]
+    command: ["node", "dist/server/index.js"]
     environment:
-      NODE_ENV: production
+      KOBO_UID: ${KOBO_UID:-1000}
+      KOBO_GID: ${KOBO_GID:-1000}
+      HOME: /root
+      # Kōbō serves its built assets; project commands need development dependencies.
+      NODE_ENV: development
+      NPM_CONFIG_INCLUDE: dev
       SERVER_PORT: "3000"
       KOBO_HOME: /root/.config/kobo
       KOBO_NETWORK_ACCESS_ENABLED: "true"