@loicngr/kobo 2.1.22 → 2.1.24

package/AGENTS.md

@@ -243,7 +243,23 @@ Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `tas
 
 ### External MCP dialogue and update checks
 
-Workspace-bound stdio, global stdio and HTTP expose shared `create_workspace` / `diagnose_workspace_pr` definitions in `src/shared/workspace-creation-tools.ts`. Stdio forwards them to the backend. `workspace-creation-mcp-service.ts` validates inputs and dispatches through the existing workspace and PR routes in process; preserve UI validation, checkout fingerprints, lifecycle guards and rollback. Inputs use snake_case except the existing camelCase PR checkout decisions. Attachments are inline base64, bounded to the shared 10-file/50 MiB decoded limit before checkout mutations. Keep SDK HTTP/stdio limits aligned with the shared creation envelope budget. Only creation envelopes get the larger base64 HTTP body budget; ordinary MCP requests remain 1 MiB. After a known PR creation failure, rollback only a checkout proven newly created, unchanged, clean (including ignored files) and unowned, under the Git repository lock; retain other checkouts and expose recovery details. Do not retry uncertain creation automatically or treat `creation_id` as an idempotency key. Restricted review/handoff launches cannot create workspaces or invoke lifecycle mutations. Shared lifecycle tools (`workspace-lifecycle-tools.ts` / `workspace-lifecycle-mcp-service.ts`) also expose archive, purge, delete, unarchive and restore through the same transports. Reject reserved/bulk/path-like IDs, require explicit purge/delete flags, and preserve warnings. Single-workspace DELETE accepts optional `confirmationBranch`, rechecked under its lifecycle guard before stopping processes; MCP always supplies it. Branch rename/resync share this guard so the confirmed branch and checkout path cannot change during teardown. Recovery uses `restore-worktree` before unarchive and never starts an agent.
+Workspace-bound stdio, global stdio and HTTP expose shared `create_workspace` / `diagnose_workspace_pr` definitions in `src/shared/workspace-creation-tools.ts`. Stdio forwards them to the backend. `workspace-creation-mcp-service.ts` validates inputs and dispatches through the existing workspace and PR routes in process; preserve UI validation, checkout fingerprints, lifecycle guards and rollback. Inputs use snake_case except the existing camelCase PR checkout decisions. Attachments are inline base64, bounded to the shared 10-file/50 MiB decoded limit before checkout mutations. Keep SDK HTTP/stdio limits aligned with the shared creation envelope budget. Creation and send_workspace_message envelopes with attachments get the larger base64 HTTP body budget; ordinary MCP requests remain 1 MiB. After a known PR creation failure, rollback only a checkout proven newly created, unchanged, clean (including ignored files) and unowned, under the Git repository lock; retain other checkouts and expose recovery details. Do not retry uncertain creation automatically or treat `creation_id` as an idempotency key. Restricted review/handoff launches cannot create workspaces or invoke lifecycle mutations. Shared lifecycle tools (`workspace-lifecycle-tools.ts` / `workspace-lifecycle-mcp-service.ts`) also expose archive, purge, delete, unarchive and restore through the same transports. Reject reserved/bulk/path-like IDs, require explicit purge/delete flags, and preserve warnings. Single-workspace DELETE accepts optional `confirmationBranch`, rechecked under its lifecycle guard before stopping processes; MCP always supplies it. Branch rename/resync share this guard so the confirmed branch and checkout path cannot change during teardown. Recovery uses `restore-worktree` before unarchive and never starts an agent.
+
+MCP creation and single-workspace messages share `shared/mcp-attachments.ts`
+validation and inline `{name, mime_type, data_base64}` schemas. Validate before
+writing, reserve keyed-message identity before uploading, and fingerprint the
+original content/session plus attachment names, types and bytes (preserving old
+text-only fingerprints). Delivery saves files under the target worktree using
+the existing attachment service, then passes references to the engine and chat.
+Clean up definitively rejected files; retain them if dispatch is uncertain.
+Never expose raw server filesystem paths as attachment inputs. Group messages
+remain text-only.
+
+The global JSON setting `forceImmediateMessages` (v67, default false) bypasses
+client chat queueing for new messages using confirmed immediate delivery. It
+also bypasses the auto-loop next-iteration UI path; normal backend immediate
+message delivery pauses a ready loop. Do not flush existing queues on toggle,
+remove compaction/permission/handoff guards, or queue rejected forced sends.
 
 `POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind the existing Host/Origin and network-token gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.
 
@@ -279,6 +295,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
@@ -381,6 +417,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ō
@@ -607,6 +670,14 @@ reuse outside PR import still forces setup off. Worktree ownership is unchanged.
 
 Each event maps to one effective-settings key (`sessionEndedScript` / `prMergedScript` / `autoLoopDisabledScript`, settings migration v55), cascading project-over-global with empty meaning inherit. Execution reuses `runScript` with `eventPrefix: 'hook:<event>'`; `runScript` gained an `extraEnv` option, merged **under** the identity variables so a hook payload can never claim a different `WORKSPACE_ID`. `runLifecycleHook` never rejects and returns `null` when there is nothing to run (no script, unknown workspace, worktree gone). The pr-watcher awaits the `pr-merged` hook before auto-purge so a deploy script does not lose its worktree mid-run. See [CONFIGURATION.md → Lifecycle hooks](CONFIGURATION.md#lifecycle-hooks).
 
+The shared `utils/script-runner.ts` supplies `INSTANCE` and `PROJECT_NAME` to
+setup, cleanup, archive and every lifecycle hook, including shutdown. Resolve
+these at execution time through `utils/dev-server-instance.ts`, shared with the
+dev-server service. Never inherit ambient Docker identity or invent a Compose
+project name: `PROJECT_NAME` is empty when no matching instance metadata exists.
+`ScriptVariablesHelp.vue` documents common and event-specific variables in both
+global and project settings; keep this help and CONFIGURATION.md in sync.
+
 ### Engine comparison
 
 Successful paired creation opens the existing `split` route with `left` and `right` workspace ids in creation order. A single successful creation keeps the normal workspace route, including when the second creation fails.

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.24
+
+- feat: add MCP attachments and immediate chat delivery
+
+## 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

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. |
@@ -395,14 +397,43 @@ silently.
 
 ### Hook environment variables
 
-Every hook gets the standard set: `WORKSPACE_ID`, `WORKSPACE_NAME`,
-`BRANCH_NAME`, `SOURCE_BRANCH`, `PROJECT_PATH`, plus `KOBO_HOOK_EVENT` naming
-the event. On top of that:
+Settings → Scripts and each project's script fields include expandable
+**Available variables** help. Setup, cleanup, archive and lifecycle scripts all
+run in the workspace worktree (`PWD`) and receive:
+
+| Variable | Value |
+|---|---|
+| `WORKSPACE_ID`, `WORKSPACE_NAME` | Workspace identifier and display name |
+| `BRANCH_NAME`, `SOURCE_BRANCH` | Working branch and source branch |
+| `PROJECT_PATH` | Main repository path, not the worktree |
+| `INSTANCE` | Matching Docker instance name, or the lowercased branch with `/` and `_` replaced by `-` |
+| `PROJECT_NAME` | Exact Compose project name from the matching `PROJECT_PATH/.container/instances/*.env` file; empty without a known matching instance |
+
+Docker identity is resolved at each script execution using the same instance
+metadata as the dev-server panel. It never inherits a Docker project from the
+server's environment or guesses one from a folder name. In particular, setup
+before the first dev-server launch usually has an empty `PROJECT_NAME`.
+Keep the metadata file if later archive/PR hooks need that identity. These
+variables are specific to the shared workspace script runner; dev start/stop
+and change-source-branch commands have their own contracts documented below.
+
+Quote variables and guard destructive Docker commands against a missing project:
+
+```bash
+# Archive or PR merged — stop this stack, preserving volumes and images.
+docker compose -p "${PROJECT_NAME:?Missing Docker project}" down --remove-orphans
+```
+
+Add `--volumes --rmi local` only to also remove its Compose-managed volumes and
+images without custom tags. This does not remove every image on the Docker host.
+
+Lifecycle hooks also receive `KOBO_HOOK_EVENT` naming the event. On top of that:
 
 | Hook | Extra variables |
 |---|---|
 | Session ended | `KOBO_SESSION_ID`, `KOBO_SESSION_END_REASON` (`completed` / `error` / `killed` / `watchdog`), `KOBO_SESSION_EXIT_CODE` (empty when the engine reports none), `KOBO_SESSION_STOP_CAUSE` (`user`, `replacement`, `setup`, `archive`, or `shutdown`; empty for a natural end; superseded sessions and delete/purge stops skip the hook), `KOBO_AUTOLOOP_ACTIVE` (`1` when auto-loop is enabled, so a test run may overlap with the next agent's edits) |
 | PR merged | `KOBO_PR_NUMBER`, `KOBO_PR_URL` |
+| Kōbō shutdown | `KOBO_SHUTDOWN_SIGNAL` |
 | Auto-loop stopped | `KOBO_AUTOLOOP_REASON` (`completed` / `user-action`; blocked missions retain their intent and do not fire this hook), `KOBO_TASKS_PENDING` |
 
 Only `KOBO_`-prefixed variables are passed through from the event; a hook
@@ -849,6 +880,13 @@ The setting lives in `settings.json` under `global` and has no UI control yet:
 
 An external MCP client can connect to `http://127.0.0.1:3000/api/mcp` using Streamable HTTP (use your backend's configured port). It can create workspaces with the same options as the form, diagnose and check out existing PRs, discover workspaces, read their conversations, send messages and answer pending questions. Workspace-bound stdio, global stdio and HTTP share the creation contract, including brainstorm settings, final auto-loop review, workflow policy, imports, existing worktrees, comparison grouping and inline attachments. All three transports also expose archive, disk-space purge, permanent deletion with explicit branch confirmation, unarchive and recovery of purged worktrees. See the [creation and PR guide](src/mcp-server/README.md#create_workspace) for fields, explicit checkout decisions and timeout/retry behavior.
 
+Both `create_workspace` and `send_workspace_message` accept inline `attachments`
+with `{name, mime_type, data_base64}`: 10 files, 50 MiB decoded total, same formats
+as the interface. Messages may contain only attachments. Kōbō saves them in the
+destination worktree and sends file/image references to the agent and chat.
+Keyed retries include attachment identity and never upload or send twice. See
+[Sending files and images](src/mcp-server/README.md#sending-files-and-images).
+
 Remote HTTP clients follow the [network access](#network-access) settings and supply the Kōbō token as `Authorization: Bearer <token>` or `X-Kobo-Token`. The endpoint uses the same Host/Origin and reverse-proxy policy as the rest of the backend. No network setting is changed automatically.
 
 See [Connect an external LLM](src/mcp-server/README.md#connect-an-external-llm) for connection examples, tool arguments, cursor polling and authentication details.
@@ -1423,6 +1461,23 @@ Kōbō talks to the embedded [`@anthropic-ai/claude-agent-sdk`](https://github.c
 
 The model selector is populated from [`src/shared/models.ts`](./src/shared/models.ts), also used by backend validation. This checkout includes Fable 5.1, Mythos 5, Opus 5, Opus 4.8, Sonnet 5 and older variants. Pick the default in **Settings → Agents**. Catalogue entries describe what Kōbō offers; provider access still depends on your account. `auto` leaves model selection to the runtime.
 
+#### Immediate chat messages
+
+**Settings → Agents → Force immediate message delivery** controls
+`forceImmediateMessages`, **false by default**, including existing installations.
+When enabled, new chat messages reach a busy Claude/Codex agent directly, like
+**Ctrl+Enter**, instead of waiting in Kōbō's message queue. Messages sent during
+an auto-loop go through immediate delivery and pause the active, ready loop.
+Previously queued instructions stay queued; changing the setting never sends
+old drafts automatically. The setting affects subsequent sends without restarting
+the server or agent.
+
+Compaction, pending questions/permissions, archive and session handoff guards
+still apply. Failed or rejected sends restore the draft; they do not silently
+queue it. MCP messages already use direct delivery and do not depend on this
+interface setting. Explicit next-iteration scheduling remains available through
+its dedicated auto-loop API.
+
 #### Session watchdogs
 
 **Settings → Agents → Enable agent inactivity watchdogs**, at the top of the tab,
@@ -1597,6 +1652,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:
@@ -2184,6 +2281,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

@@ -3,9 +3,10 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getDb } from '../server/db/index.js';
+import { MAX_MCP_ATTACHMENT_REQUEST_BYTES } from '../shared/mcp-attachments.js';
 import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName, MEMORY_TOOL_DEFINITIONS } from '../shared/memory-tools.js';
 import { INTERNAL_PROGRESS_BAR_TOOLS, isProgressBarTool, PROGRESS_BAR_TOOLS } from '../shared/progress-bar-tools.js';
-import { isWorkspaceCreationTool, MAX_MCP_CREATION_REQUEST_BYTES, WORKSPACE_CREATION_TOOLS, } from '../shared/workspace-creation-tools.js';
+import { isWorkspaceCreationTool, WORKSPACE_CREATION_TOOLS } from '../shared/workspace-creation-tools.js';
 import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
 import { isWorkspaceGroupMessageTool, WORKSPACE_GROUP_MESSAGE_TOOLS } from '../shared/workspace-group-message-tools.js';
 import { isWorkspaceLifecycleTool, WORKSPACE_LIFECYCLE_TOOLS } from '../shared/workspace-lifecycle-tools.js';
@@ -408,25 +409,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: {
@@ -1023,7 +1024,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 const transport = new StdioServerTransport(process.stdin, process.stdout, {
     // Include the JSON-lines delimiter in addition to the HTTP envelope budget.
-    maxBufferSize: MAX_MCP_CREATION_REQUEST_BYTES + 1,
+    maxBufferSize: MAX_MCP_ATTACHMENT_REQUEST_BYTES + 1,
 });
 server.connect(transport).catch((err) => {
     console.error('[kobo-tasks-server] Fatal:', err);

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/routes/mcp.js

@@ -3,9 +3,10 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Hono } from 'hono';
 import { bodyLimit } from 'hono/body-limit';
+import { MAX_MCP_ATTACHMENT_REQUEST_BYTES } from '../../shared/mcp-attachments.js';
 import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName } from '../../shared/memory-tools.js';
 import { isProgressBarTool, PROGRESS_BAR_TOOLS } from '../../shared/progress-bar-tools.js';
-import { isWorkspaceCreationTool, MAX_MCP_CREATION_REQUEST_BYTES, WORKSPACE_CREATION_TOOLS, } from '../../shared/workspace-creation-tools.js';
+import { isWorkspaceCreationTool, WORKSPACE_CREATION_TOOLS } from '../../shared/workspace-creation-tools.js';
 import { EXTERNAL_MCP_TOOLS } from '../../shared/workspace-dialogue-tools.js';
 import { isWorkspaceGroupMessageTool, WORKSPACE_GROUP_MESSAGE_TOOLS, } from '../../shared/workspace-group-message-tools.js';
 import { isWorkspaceLifecycleTool, WORKSPACE_LIFECYCLE_TOOLS } from '../../shared/workspace-lifecycle-tools.js';
@@ -19,22 +20,27 @@ import { executeWorkspaceGroupMessageTool, WorkspaceGroupMessageMcpError, } from
 import { executeWorkspaceLifecycleTool, WorkspaceLifecycleMcpError, } from '../services/workspace-lifecycle-mcp-service.js';
 import { prepareMemoryToolEnvelope } from '../utils/memory-token-budget.js';
 const app = new Hono();
-// Only creation envelopes may carry the larger, base64 attachment payload.
+// Only creation and message envelopes may carry the larger, base64 attachment payload.
 // Other tools retain their existing 1 MiB limit, including malformed envelopes.
-app.use('*', bodyLimit({ maxSize: MAX_MCP_CREATION_REQUEST_BYTES }));
+app.use('*', bodyLimit({ maxSize: MAX_MCP_ATTACHMENT_REQUEST_BYTES }));
 app.use('*', async (c, next) => {
     if (c.req.raw.body) {
         const body = await c.req.raw.clone().arrayBuffer();
         if (body.byteLength > 1024 * 1024) {
-            let creation = false;
+            let attachmentTool = false;
             try {
                 const envelope = JSON.parse(new TextDecoder().decode(body));
-                creation = envelope?.method === 'tools/call' && envelope?.params?.name === 'create_workspace';
+                attachmentTool =
+                    envelope?.method === 'tools/call' &&
+                        (envelope?.params?.name === 'create_workspace' ||
+                            (envelope?.params?.name === 'send_workspace_message' &&
+                                Array.isArray(envelope?.params?.arguments?.attachments) &&
+                                envelope.params.arguments.attachments.length > 0));
             }
             catch {
                 /* Preserve the normal body-size rejection for malformed input. */
             }
-            if (!creation)
+            if (!attachmentTool)
                 return c.json({ error: 'MCP request is too large' }, 413);
         }
     }
@@ -64,7 +70,7 @@ app.all('/', async (c) => {
     const transport = new WebStandardStreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
         enableJsonResponse: true,
-        maxRequestBodySize: MAX_MCP_CREATION_REQUEST_BYTES,
+        maxRequestBodySize: MAX_MCP_ATTACHMENT_REQUEST_BYTES,
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [

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

@@ -486,6 +486,7 @@ function readEffectiveSettingsSafe(projectPath) {
             archiveScript: '',
             changeSourceBranchScript: '',
             sessionEndedScript: '',
+            shutdownScript: '',
             prMergedScript: '',
             autoLoopDisabledScript: '',
             notionStatusProperty: '',