@loicngr/kobo 2.1.21 → 2.1.23

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).
 
@@ -275,6 +279,26 @@ Two emit flavors in `websocket-service.ts`:
 
 ## External integrations
 
+### Graceful shutdown and development services
+
+`stopDevServersOnShutdown` is a global boolean, default `true` (JSON settings
+migration v66). Shutdown first rejects new dev-server starts and stops tracked
+local processes/agents. Disabling the setting skips configured dev stop commands
+and Compose teardown, preserving independent Docker services; manual Stop and
+workspace deletion/purge remain unchanged. Status recovery uses the existing
+instance-file and exact Compose-label inspection, never a duplicate startup.
+
+`shutdownScript` follows the global/project script cascade: empty inherits,
+whitespace disables. The `kobo-shutdown` lifecycle hook runs once per persisted
+workspace with an existing, non-purged worktree (including archived workspaces),
+after local writers stop and before optional Docker teardown. Skip unconfirmed
+agent stops. Each hook has a 1-minute timeout, and the outer shutdown deadline
+is 150 seconds (supervisors need at least 180 seconds). Inject `PROJECT_NAME` from
+the workspace instance config, empty if unavailable, and `INSTANCE`; never guess
+a Compose project. User hooks may explicitly remove Docker resources even when
+automatic shutdown is disabled. Preserve hook outputs and keep SQLite open until
+hooks settle. Do not run scripts on abrupt exits or claim they survive SIGKILL.
+
 ### VPS deployment tooling
 
 `docker-compose.vps.yml` is the standalone fresh-instance example for an existing
@@ -315,13 +339,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
@@ -370,6 +401,33 @@ 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.
 
+Prefer dedicated managed MCP operations and require checking their results.
+Writable launches synchronize task progress and blockers during work using only
+supported statuses; restricted launches must not receive task mutation guidance.
+Delegation passes the objective, worktree path, constraints, permissions, test
+runtime and applicable MCP/reporting rules explicitly. Keep final reporting
+evidence-based and phase-aware: distinguish actual checks, delegated results,
+blocked/unverified work and jobs still running. Reuse the shared progress lifecycle
+instead of duplicating it or finishing ongoing work at the end of a turn.
+
+Dev-server lifecycle guidance must cover backend/integration dependencies as well
+as frontend/E2E checks. Agents and delegates inspect/reuse the managed instance,
+start/stop only through its MCP tools under writable launch permissions, and
+report unavailable tools/configuration or startup failures instead of bypassing
+Kōbō with direct shell startup commands. Keep tool descriptions in sync.
+Distinguish the agent runtime from project containers, running status from
+application readiness, and interrupted reporting from terminated work. Keep
+readiness probes bounded and do not suggest bypassing failed MCP authentication
+or replaying an ambiguous mutation without checking its outcome.
+
+Launch guidance explicitly directs agents to consult injected Kōbō
+memory before targeted retrieval, and to save confirmed reusable facts through
+`remember` only under the current mode/permissions. Preserve retrieval budgets,
+scope selection and Hybrid proposal semantics; native provider memory is not a
+replacement for this shared store.
+Keep detailed workflow guidance in the application launch instructions: the
+separate mode-specific memory bootstrap has a strict total retrieval budget.
+
 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ō
@@ -387,11 +445,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.23
+
+- feat: configure shutdown hooks and improve agent guidance
+
+## 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

package/CONFIGURATION.md

@@ -234,6 +234,8 @@ Projects override a subset of global settings. Anything you set here takes prece
 | `taskPromptTemplate` | `string` | Prompt used to prefill the mission description when this project is selected. Empty leaves the description without a project-provided prompt. |
 | `forge` | `'auto' \| 'github' \| 'gitlab' \| 'bitbucket-community' \| 'none'` | Which forge provides PR/MR features. `auto` detects from the git remote URL. See [Forge integration](#forge-integration). |
 | `devServer.startCommand` / `stopCommand` | `string` | Per-workspace dev server commands. Docker, npm, or any shell-startable process. See [Dev server](#dev-server) for the status/URL contract. |
+| `stopDevServersOnShutdown` | `boolean` | Global, default `true`. Disable to leave Docker services running when Kōbō exits or updates. Tracked local processes always stop. Explicit Stop and workspace teardown still stop services. |
+| `shutdownScript` | `string` | Optional global/per-project shutdown hook, run in each existing workspace worktree before automatic Docker teardown. Empty project value inherits; whitespace disables. See [Kōbō shutdown](#kōbō-shutdown). |
 | `e2e.framework` | `'cypress' \| 'playwright' \| 'jest' \| 'vitest' \| 'other' \| ''` | E2E framework auto-loop grooming should target. |
 | `e2e.skill` | `string` | Optional skill name injected into the E2E grooming prompt. |
 | `e2e.prompt` | `string` | Free-form prompt appended to every `[E2E] ` sub-task. |
@@ -859,6 +861,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
@@ -1365,6 +1373,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
@@ -1416,15 +1427,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.
@@ -1576,6 +1599,48 @@ logs contract does not provide general process health monitoring.
 **No instance file at all**: Start/Stop run your commands; the panel uses the
 saved status when available, otherwise `unknown`, with no URL or Docker logs.
 
+### Kōbō shutdown
+
+In **Settings → Scripts**, **Stop development servers when Kōbō exits** defaults
+to enabled. Disable it to preserve independently running Docker containers during
+an update/restart. Kōbō still terminates its tracked local processes, including
+startup commands. Use detached Docker services (`docker compose up -d`); a
+foreground Compose process or a custom signal trap can itself stop containers.
+After restart, the existing instance-file/Compose-label contract lets the panel
+inspect those containers and recover their URL and logs without starting them.
+The setting does not change manual Stop, workspace deletion/purge, or user hooks.
+
+The optional **Hook: Kōbō shutdown** uses the global script by default. A project
+script replaces it; an empty project field inherits and whitespace disables it.
+It runs **once per workspace, in that workspace's worktree**, including archived
+workspaces with an existing checkout. Purged/missing worktrees and workspaces
+whose agent stop is unconfirmed are skipped. Scripts run after tracked agent/local
+process shutdown and before automatic Docker teardown, even when automatic Docker
+shutdown is disabled. Each script has a **1-minute timeout**; failures are logged
+and do not cancel shutdown. Output is recorded under `hook:kobo-shutdown`.
+
+Available variables include `WORKSPACE_ID`, `WORKSPACE_NAME`, `BRANCH_NAME`,
+`SOURCE_BRANCH`, `PROJECT_PATH`, `KOBO_HOOK_EVENT=kobo-shutdown`, and
+`KOBO_SHUTDOWN_SIGNAL` (`SIGTERM`, `SIGINT`, etc.). `INSTANCE` and `PROJECT_NAME`
+come from that workspace's dev-server instance configuration. `PROJECT_NAME` is
+empty when no matching Docker instance is known; never guess a shared stack name.
+
+For explicit destructive cleanup of the workspace's Compose resources:
+
+```bash
+docker compose -p "${PROJECT_NAME:?Missing Docker project}" down --remove-orphans --volumes --rmi local
+```
+
+This removes Compose-managed volumes and images without custom tags; external
+volumes and tagged images remain. It can stop containers **even with automatic
+Docker shutdown disabled**, because the hook is an explicit user command. Supply
+any `-f` or `--env-file` arguments your project's Compose setup requires.
+
+These hooks require a graceful Kōbō shutdown; they cannot run after `SIGKILL`,
+a host power loss or a crash that bypasses teardown. Kōbō's total shutdown deadline
+is 150 seconds. Allow at least 180 seconds in a container/process supervisor
+(`stop_grace_period: 180s` in the Compose examples).
+
 ### Example: the full convention end-to-end
 
 The reference implementation is the `sekur` project. Its Kōbō `startCommand` is effectively `make dev-docker`, where the `Makefile` calls `./sh/dev-docker.sh $(INSTANCE)` and `$(INSTANCE)` reads the `INSTANCE` env var Kōbō injects. The script:
@@ -2163,6 +2228,51 @@ Notion token environment overrides are applied consistently to both token variab
 
 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.
 
+For tasks, development services, shared memory, workspace messages and state,
+agents prefer the dedicated managed MCP tool and check its result. Writable
+launches keep existing tasks current during work: `in_progress` when starting,
+blockers promptly reported in the conversation with the affected task, and done
+only after required checks pass. Task requirements and evidence are preserved.
+Blocked tasks stay unfinished; no unsupported field or status is invented.
+Delegates receive the objective, exact worktree path, user constraints, launch
+permissions, test runtime and applicable MCP/reporting rules. When a delegate
+lacks the tools, its parent coordinates the operation under the same permissions.
+The final report identifies changes/findings, checks actually executed and their
+results, and remaining blockers or ongoing work. Delegated results are attributed;
+progress bars finish only for activities with a known outcome, and completing a
+phase or review does not imply the whole mission is done.
+
+Agents explicitly use Kōbō internal memory for shared knowledge across sessions,
+workspaces and engines. At task start/resume, they consult injected facts before
+targeted retrieval of missing decisions, conventions and known pitfalls. When
+permitted, they save confirmed reusable facts through `remember` in the narrowest
+scope, updating existing entries rather than duplicating them. Native provider
+memory does not replace this shared store. Retrieval budgets, Manual/read-only
+restrictions and Hybrid approval requirements still apply; secrets, raw logs and
+routine progress are not memory entries.
+
+Development services have an explicit managed lifecycle rule: before backend,
+frontend, integration or E2E checks that need workspace services, inspect
+`get_dev_server_status` and reuse the existing instance. Authorized writable
+launches start/stop it through the Kōbō MCP tools, never by invoking the startup
+script, `make dev-docker` or Docker Compose directly. Diagnose failures with
+`get_dev_server_logs`; unavailable tools or configuration are reported as blockers.
+Delegates follow the same rule. Read-only launches cannot start/stop services;
+test execution inside an existing container still follows current permissions.
+
+Agents choose test commands and runtimes from the project Makefile, scripts and
+documentation. Missing dependencies in the agent environment do not establish a
+project configuration defect when tests belong in a service container. A running
+dev server is not proof of application readiness: dependent checks require a
+documented health check or non-mutating URL probe with a timeout and bounded
+retries. Independent unit tests need not wait for application readiness.
+
+After interruption/resume, agents verify relevant task/Git state and ongoing
+jobs, tests and containers before repeating work. MCP failures must be reported
+as failures, with safe diagnostics; authentication/permission errors never justify
+modifying credentials or Kōbō storage to bypass the tools. Ambiguous mutation
+outcomes require checking available status/receipts before retrying.
+
 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.

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

@@ -408,25 +408,25 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'get_dev_server_status',
-        description: 'CALL BEFORE asking the user whether the app is running, or when your change is dev-server-sensitive. Returns `not_configured` when this project has no dev server: do not start one manually in that case. Otherwise returns running/stopped/starting/error + URL, port, container names.',
+        description: 'CALL BEFORE backend, frontend, integration or E2E tests that need workspace services, or before asking the user whether the app is running. Reuse the existing instance and its returned URL/container names. Returns `not_configured` when this project has no dev server: report the blocker, do not launch one manually. Otherwise returns running/stopped/starting/error + URL, port, container names. Running is lifecycle status, not application readiness: use the documented health check with bounded retries before dependent tests.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { readOnlyHint: true, openWorldHint: false },
     },
     {
         name: 'start_dev_server',
-        description: 'CALL WHEN the user asks you to test the running app and the dev server is stopped.',
+        description: 'CALL WHEN an authorized task needs workspace services for app checks or backend/frontend/integration/E2E tests and get_dev_server_status reports stopped. Kōbō runs the configured startup command and tracks the instance. Use this tool instead of shell lifecycle commands such as make dev-docker, sh/dev-docker.sh, docker compose up or npm run dev. Respect launch permissions; read-only sessions cannot start services. On failure, inspect get_dev_server_logs and report the blocker, without a manual shell fallback.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
     {
         name: 'stop_dev_server',
-        description: 'CALL WHEN the user explicitly asks to stop the dev server, or before destructive operations that require a clean boot.',
+        description: 'CALL WHEN the user explicitly asks to stop the dev server, or when an authorized operation requires a restart. Use this tool instead of shell shutdown commands such as docker compose down or killing the server process directly. Respect launch permissions; read-only sessions cannot stop services. Do not stop a shared workspace instance merely because your tests finished.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
     {
         name: 'get_dev_server_logs',
-        description: 'CALL WHEN debugging a runtime issue the user describes as happening in the running app. Returns the last N lines of logs (default 200). Cheaper than asking the user to paste them.',
+        description: 'CALL WHEN diagnosing a dev-server startup failure or a runtime issue during app checks or tests. Returns the last N lines of logs (default 200). Use these logs with get_dev_server_status before reporting a blocker; do not bypass a failed managed startup with a shell launch.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/server/index.js

@@ -37,13 +37,14 @@ import voiceRouter from './routes/voice.js';
 import workspaceMessagesRouter from './routes/workspace-messages.js';
 import workspaceTemplatesRouter from './routes/workspace-templates.js';
 import workspacesRouter from './routes/workspaces.js';
-import { getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb, resumePendingReviewReturns, setBackendPort, startAgent, startWatchdog, stopAgentAndWait, stopAllAgents, stopWatchdog, } from './services/agent/orchestrator.js';
+import { getActiveSessionId, getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb, resumePendingReviewReturns, setBackendPort, startAgent, startWatchdog, stopAgentAndWait, stopAllAgents, stopWatchdog, } from './services/agent/orchestrator.js';
 import * as autoLoopService from './services/auto-loop-service.js';
 import { startAwaitingUserReminder, stopAwaitingUserReminder } from './services/awaiting-user-reminder-service.js';
 import { runContentMigrationIfNeeded } from './services/content-migration-service.js';
 import * as cronService from './services/cron-service.js';
 import { createDailyDbBackupIfNeeded, createPreMigrationBackup, startDailyDbBackupScheduler, } from './services/db-backup-service.js';
-import { startDevServer, stopAllDevServers, stopDevServer } from './services/dev-server-service.js';
+import { beginDevServerShutdown, startDevServer, stopAllDevServers, stopDevServer, } from './services/dev-server-service.js';
+import { onKoboShutdown } from './services/lifecycle-hook-service.js';
 import { reconcileMessageRequests } from './services/mcp-message-request-service.js';
 import { reconcileMemoryContextsOnStartup } from './services/memory-context-service.js';
 import { authorizeWsUpgrade, generateToken, getLanHostnames, getLanUrls, isAllowedOrigin, isAllowedRequestHost, resolveBindHost, resolveDevClientOrigin, resolveNetworkAccessEnvOverrides, resolveProxyHostname, } from './services/network-access-service.js';
@@ -422,13 +423,15 @@ async function gracefulShutdown(signal, exitCode = 0) {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
+    beginDevServerShutdown();
+    const stopDevServersOnShutdown = getGlobalSettings().stopDevServersOnShutdown !== false;
     stopUpdateChecker();
     const groupMessagesStopped = stopGroupMessageBatches();
     console.log(`\n[kobo] Received ${signal}, shutting down gracefully…`);
     const forceExitTimer = setTimeout(() => {
         console.error('[kobo] Graceful shutdown timed out; forcing exit');
         process.exit(1);
-    }, 5_000);
+    }, 150_000);
     forceExitTimer.unref();
     // Ask WebSocket clients to leave so their upgraded HTTP connections do not
     // keep server.close() waiting indefinitely.
@@ -469,14 +472,26 @@ async function gracefulShutdown(signal, exitCode = 0) {
         // Best-effort
     }
     clearInterval(retentionTimer);
-    // Stop managed agents and both direct/Docker dev servers before closing DB.
+    // Stop local writers before user hooks, leaving Docker available to those hooks.
     try {
-        await Promise.all([stopAllAgents(), stopAllDevServers()]);
-        console.log('[kobo] Agents and dev servers stopped');
+        await Promise.all([stopAllAgents(), stopAllDevServers({ preserveDocker: true })]);
+        await onKoboShutdown(signal, (workspaceId) => getActiveSessionId(workspaceId) !== undefined);
     }
     catch {
         // Best-effort
     }
+    try {
+        if (stopDevServersOnShutdown) {
+            await stopAllDevServers();
+            console.log('[kobo] Dev servers stopped');
+        }
+        else {
+            console.log('[kobo] Local dev processes stopped; Docker services left to the configured shutdown hooks');
+        }
+    }
+    catch (err) {
+        console.error('[kobo] Dev-server shutdown failed:', err);
+    }
     // Stop accepting new HTTP/WS work, then let in-flight handlers finish before
     // closing SQLite. Closing the DB earlier makes those handlers fail midway.
     try {

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

@@ -486,6 +486,7 @@ function readEffectiveSettingsSafe(projectPath) {
             archiveScript: '',
             changeSourceBranchScript: '',
             sessionEndedScript: '',
+            shutdownScript: '',
             prMergedScript: '',
             autoLoopDisabledScript: '',
             notionStatusProperty: '',
@@ -1577,6 +1578,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/dev-server-service.js

@@ -26,11 +26,16 @@ function runCommand(command, args, options = {}) {
 const trackedProcesses = new Map();
 const stoppingProcesses = new Map();
 const generations = new Map();
+let shuttingDown = false;
+export function beginDevServerShutdown() {
+    shuttingDown = true;
+}
 /** Test-only: clear the tracked-processes map between tests. */
 export function _resetTrackedProcessesForTests() {
     trackedProcesses.clear();
     stoppingProcesses.clear();
     generations.clear();
+    shuttingDown = false;
 }
 // ── Pure helpers ───────────────────────────────────────────────────────────────
 /**
@@ -177,6 +182,8 @@ export async function getStatus(projectPath, workingBranch, workspaceId) {
  * Start the dev-server for a workspace.
  */
 export function startDevServer(workspaceId) {
+    if (shuttingDown)
+        throw new Error('Kōbō is shutting down');
     assertWorkspaceLifecycleAvailable(workspaceId);
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
@@ -231,7 +238,7 @@ export function startDevServer(workspaceId) {
                     return;
                 trackedProcesses.delete(workspaceId);
                 const currentStatus = await getStatus(workspace.projectPath, workspace.workingBranch);
-                if (generations.get(workspaceId) !== generation || stoppingProcesses.has(workspaceId))
+                if (shuttingDown || generations.get(workspaceId) !== generation || stoppingProcesses.has(workspaceId))
                     return;
                 updateDevServerStatus(workspaceId, currentStatus.status);
                 emitEphemeral(workspaceId, 'devserver:status', currentStatus);
@@ -244,7 +251,7 @@ export function startDevServer(workspaceId) {
             console.error(`[dev-server] Process exited with code ${code} for workspace ${workspaceId}`);
     });
     proc.on('error', (err) => {
-        if (trackedProcesses.get(workspaceId) !== proc)
+        if (shuttingDown || trackedProcesses.get(workspaceId) !== proc || generations.get(workspaceId) !== generation)
             return;
         // A signal failure is also an 'error' event; it does not prove process exit.
         if (!proc.pid)
@@ -373,6 +380,16 @@ function signalAndWait(proc, signal, timeoutMs) {
         }
     });
 }
+async function stopTrackedProcess(workspaceId) {
+    const tracked = trackedProcesses.get(workspaceId);
+    if (!tracked)
+        return;
+    const exited = (await signalAndWait(tracked, 'SIGTERM', 3_000)) || (await signalAndWait(tracked, 'SIGKILL', 1_000));
+    if (!exited)
+        throw new Error('Dev server stop is not confirmed; retry after the process exits');
+    if (trackedProcesses.get(workspaceId) === tracked)
+        trackedProcesses.delete(workspaceId);
+}
 async function stopDevServerOwned(workspaceId) {
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
@@ -383,14 +400,7 @@ async function stopDevServerOwned(workspaceId) {
     const worktreePath = workspace.worktreePath;
     const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : workspace.projectPath;
     // Kill tracked process first (covers Node servers and any spawned process)
-    const tracked = trackedProcesses.get(workspaceId);
-    if (tracked) {
-        const exited = (await signalAndWait(tracked, 'SIGTERM', 3_000)) || (await signalAndWait(tracked, 'SIGKILL', 1_000));
-        if (!exited)
-            throw new Error('Dev server stop is not confirmed; retry after the process exits');
-        if (trackedProcesses.get(workspaceId) === tracked)
-            trackedProcesses.delete(workspaceId);
-    }
+    await stopTrackedProcess(workspaceId);
     const settings = getProjectSettings(workspace.projectPath);
     let stopError;
     let customStopSucceeded = false;
@@ -448,12 +458,30 @@ async function stopDevServerOwned(workspaceId) {
     emitEphemeral(workspaceId, 'devserver:status', status);
     return status;
 }
-/** Stop direct and Docker dev servers for every persisted workspace. */
-export async function stopAllDevServers() {
+/** Shut down local processes; optionally leave independently running Docker services alone. */
+export async function stopAllDevServers(options = {}) {
+    beginDevServerShutdown();
     const workspaceIds = new Set([...listWorkspaces(true).map((workspace) => workspace.id), ...trackedProcesses.keys()]);
     await Promise.all([...workspaceIds].map(async (workspaceId) => {
         try {
-            await stopDevServer(workspaceId);
+            if (!options.preserveDocker) {
+                await stopDevServer(workspaceId);
+            }
+            else {
+                // A stop already requested by the user must still finish.
+                const stopping = stoppingProcesses.get(workspaceId);
+                if (stopping) {
+                    await stopping;
+                    return;
+                }
+                const hadProcess = trackedProcesses.has(workspaceId);
+                await stopTrackedProcess(workspaceId);
+                const workspace = getWorkspace(workspaceId);
+                // Preserve Docker state; getStatus re-inspects Compose after restart.
+                if (hadProcess && workspace && !resolveInstance(workspace.projectPath, workspace.workingBranch)) {
+                    updateDevServerStatus(workspaceId, 'stopped');
+                }
+            }
         }
         catch (err) {
             console.error(`[dev-server] Failed to stop '${workspaceId}' during shutdown:`, err);