@loicngr/kobo 2.1.28 → 2.1.30

package/AGENTS.md

@@ -4,7 +4,7 @@ Guidance for AI coding agents (Claude Code, Cursor, etc.) working on this reposi
 
 ## What this project is
 
-**Kōbō** (工房, Japanese for "workshop") orchestrates Claude Code and OpenAI Codex agents across isolated git worktrees. Each "workspace" is a self-contained mission with its own worktree, branch, agent sessions, optional dev server, optional Notion/Sentry context, and a dedicated MCP tools server. A Vue 3 UI lets the human track progress, read live agent output, review Git changes, and manage the lifecycle. A workspace can switch engines through a handoff to a fresh session while preserving its worktree and history.
+**Kōbō** (工房, Japanese for "workshop") orchestrates Claude Code, OpenAI Codex and Mistral Vibe agents across isolated git worktrees. Each "workspace" is a self-contained mission with its own worktree, branch, agent sessions, optional dev server, optional Notion/Sentry context, and a dedicated MCP tools server. A Vue 3 UI lets the human track progress, read live agent output, review Git changes, and manage the lifecycle. A workspace can switch engines through a handoff to a fresh session while preserving its worktree and history.
 
 Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled. Operator HTTP access uses the network token or a 12-hour HttpOnly browser session; browsers use 60-second single-use path-bound tickets for WebSocket upgrades, never the operator token in the URL or localStorage. Behind-a-reverse-proxy mode also gates loopback operator requests. Rotation, network disable and proxy-mode changes revoke sessions, tickets and active WebSockets. `/api/health` stays exempt. Host/Origin checks apply separately; public proxy origin must be declared explicitly. No multi-tenant concerns.
 
@@ -12,7 +12,7 @@ External `/api/mcp` and global stdio require dedicated hashed credentials with t
 
 ## Tech stack
 
-**Backend**: Node.js ≥ 24.15, Hono (HTTP), `ws` (WebSocket), better-sqlite3 (WAL mode), nanoid, `@modelcontextprotocol/sdk`. TypeScript throughout, `tsx` for dev, `tsc` for production build.
+**Backend**: Node.js ≥ 26.12.1, Hono (HTTP), `ws` (WebSocket), better-sqlite3 (WAL mode), nanoid, `@modelcontextprotocol/sdk`. TypeScript throughout, `tsx` for dev, `tsc` for production build.
 
 **Frontend**: Vue 3, Quasar 2, Pinia, vue-router, marked + dompurify for markdown rendering. Vite via `@quasar/app-vite`, built and served as a Progressive Web App in production.
 
@@ -70,7 +70,7 @@ src/
 │   │   │   ├── orchestrator.ts     # per-workspace engine map, retry/quota handling, watchdog, public API
 │   │   │   ├── session-controller.ts # lifecycle wrapper around an AgentEngine instance
 │   │   │   ├── event-router.ts     # persists/broadcasts normalized AgentEvent via WebSocket
-│   │   │   └── engines/{claude-code,codex}/ # per-engine adapters implementing the AgentEngine contract
+│   │   │   └── engines/{claude-code,codex,mistral-vibe}/ # per-engine adapters implementing the AgentEngine contract
 │   │   ├── forge/                  # github / gitlab / bitbucket-community / none, registry + auto-resolve
 │   │   ├── change-source-branch-service.ts # re-target a workspace onto a new source branch (built-in cherry-pick or custom bash)
 │   │   ├── git-stats-service.ts    # pure compute of commit/ahead-behind/diff stats + forge availability for a workspace
@@ -178,7 +178,7 @@ and [VPS setup](./docs/vps-projects-and-skills.md#switch-engine-accounts-inside-
 
 ## Persistent memory
 
-Kōbō memory is independent of provider chat history/native memory and shared by Claude Code and Codex. `memoryMode` is a global setting defaulting to `hybrid`: Manual permits reads only; Hybrid applies workspace writes and proposes project/global writes; Automatic applies writes to the explicitly targeted scope. Mode is checked per operation, so a setting change affects existing agent sessions; pending/rejected proposals are never automatically approved or revived. Plan/review/report-only capabilities cannot write.
+Kōbō memory is independent of provider chat history/native memory and shared by Claude Code, Codex and Mistral Vibe. `memoryMode` is a global setting defaulting to `hybrid`: Manual permits reads only; Hybrid applies workspace writes and proposes project/global writes; Automatic applies writes to the explicitly targeted scope. Mode is checked per operation, so a setting change affects existing agent sessions; pending/rejected proposals are never automatically approved or revived. Plan/review/report-only capabilities cannot write.
 
 `memory_scopes` identify global, normalized configured project path, or durable workspace id. Project identity is not a display name, branch, or worktree path. Clear is transactional: it deletes entries and pending proposals only from the exact scope, increments generation, and writes content-free journal metadata. Every delayed writer supplies its expected generation. Workspace archive/purge preserves memory; workspace deletion cascades its own scope and launch records while leaving global/project scopes intact. Provenance FKs become null when the source session/workspace is deleted; saved memory remains in its scope until explicitly erased.
 
@@ -444,7 +444,7 @@ See the "Notion integration" section of the README for the end-user setup guide.
 ### Launch instructions
 
 `src/shared/launch-instructions.ts` composes application-owned MCP discovery,
-permissions, progress reporting and continuation rules for both engines on every
+permissions, progress reporting and continuation rules for all three engines on every
 fresh/resumed launch. Prefer discovering the available tool schemas to embedding
 a duplicate catalogue. Keep Plan conversation-only; template approval cannot
 expand tool permissions. Initial writable auto-loop launches seed tasks and end;
@@ -493,11 +493,58 @@ through `ExitPlanMode`; a permission change requires a new launch.
 
 ### Agent engines
 
-Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:
+**Mistral Vibe** (`mistral-vibe/`, engine id `mistral-vibe`) uses ACP v1 through
+SDK 2.0.1 and the server user's PATH-resolved `vibe-acp`. Native setup/authentication
+belongs to that same user/environment, including Docker; Kōbō stores no Vibe key.
+Model/thinking choices come from validated native ACP `configOptions`, including
+model-specific thinking levels. `auto` omits setters; explicit launch selections
+use public ACP setters and may persist native Vibe preferences. Discovery uses
+child-only native environment overrides and session/new without prompts, setters,
+provider requests or Kōbō MCP grants. Resolve workspace/project context server-side;
+cache/coalesce only after confirmed native closure and retain failed shutdown slots.
+Preflight explicit choices before mutations, then confirm mode → model → thinking
+again on the actual new/load session before prompting. Static Auto catalogues are
+fallbacks, never complete membership validators. Configured Auto must not acquire
+an observed session-model override during resume or review return; explicit source
+configuration may restore the observed source/brainstorm alias. Native review
+return thinking comes from the pinned saved session, never the workspace iteration
+effort. Auto-model resumes with explicit thinking defer catalogue membership to
+the loaded native session because session/new defaults may use another model.
+Fresh Vibe workspaces default to `interactive`;
+`interactive`/`strict`/`bypass` select advertised native `ask`/`accept-edits`/
+`auto-approve`. Native profiles/admin policy remain authoritative. Reject Plan,
+readOnly and restricted handoff-summary launches before spawn or workspace mutations.
+Manual Vibe reviews always use a fresh controlled launch, Interactive by default;
+automatic final reviews are fixed Interactive. Native permissions do not enforce
+filesystem read-only access: prompts forbid every modification and approvals may
+pause the review. Kōbō MCP/memory grants and bootstrap remain read-only even in
+Automatic memory mode. Returning/final reviewers derive this role from durable
+state; no-return reviews use the private KOBO_REVIEW_ONLY launch marker.
+Explicit native Plan requests still fail; only explicitly starting a native review
+chooses its independent Interactive default. Ordinary saved Plan is never promoted.
+
+No live steering, account/quota panel, managed skills or sub-agent cards/individual
+stop. Queue messages until confirmed native closure, then resume; immediate sends
+fail while busy. Normal task/memory/progress MCP and manual handoff destinations
+remain supported. Shared memory migration v55 preserves existing facts and adds
+Mistral provenance. Setup requests have 20-second initialize/30-second session
+limits; prompts have no absolute deadline. Opt-in liveness uses 120 seconds
+foreground silence or 30 minutes unresolved tools, paused for human input.
+
+Native shutdown drains stdout, ends stdin and awaits actual exit and an empty
+owned process group; a close ACK is insufficient. Allow 15 seconds for native EOF
+cleanup before bounded signal fallback. Unconfirmed/abnormal exit retains ownership.
+Do not claim arbitrary unmanaged descendant containment. Vibe 3.0.1 has passed the
+real-adapter offline provider/MCP smoke on Linux; paid-provider compatibility is
+still unverified. Health version detection proves executable availability only,
+never authentication. See [setup](CONFIGURATION.md#mistral-vibe) and
+[compatibility evidence](src/__tests__/fixtures/mistral-acp/README.md).
+
+Three engines live under `src/server/services/agent/engines/`, implementing the `AgentEngine` contract in `types.ts`:
 
 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
+on every launch/resume for all three 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.
@@ -536,7 +583,7 @@ Background: the engine was migrated from `@openai/codex-sdk` (one-shot `codex ex
 - **Permission mode vs collaboration mode are independent.** Sandbox + approvalPolicy control *what the agent may do at OS level* (read-only / workspace-write, never / on-request / unless-trusted). `collaborationMode` is a separate session-level flag that gates internal Codex behaviour (notably interactive Q&A). Kōbō hides both behind a single "permission mode" selector and maps them together.
 - **Sub-agents map to `collabAgentToolCall`.** Codex's analogue of Claude's Task tool is `collabAgentToolCall` (`spawnAgent` / `sendInput` / `resumeAgent` / `wait` / `closeAgent`). The mapper emits **both** a `tool:call` named `Task` (chat card) and a `subagent:progress` event (right-hand panel) per call, the same dual-emission Claude does. See `event-mapper.ts` `handleItemStarted` / `handleItemCompleted` for the `collabAgentToolCall` branch.
 - **`fileChange` items carry a unified-diff blob.** The protocol shape is `{ path, kind: PatchChangeKind, diff: string }` per change; `kind` is a discriminated union, not a string. The mapper flattens the first change into a Claude-style Edit input (`{ file_path, diff, change_kind, move_path? }`) so the existing `ToolCallItem` renderer picks it up. The client parses the unified diff into `DiffLine[]` via `parseUnifiedDiff` in `inline-diff.ts`.
-- **Streaming bursts trip auto-scroll.** Both engines can emit token deltas; Claude enables SDK partial messages as well. The naive `eventCount` watcher in `ActivityFeed.vue` triggered an animated `scrollToBottom(180)` per event, causing stacked animations and visible jank. Scroll requests are coalesced through `requestAnimationFrame`; preserve burst handling when changing the feed.
+- **Streaming bursts trip auto-scroll.** All three engines can emit token deltas; Claude enables SDK partial messages as well. The naive `eventCount` watcher in `ActivityFeed.vue` triggered an animated `scrollToBottom(180)` per event, causing stacked animations and visible jank. Scroll requests are coalesced through `requestAnimationFrame`; preserve burst handling when changing the feed.
 - **`MCP tools` need `default_tools_approval_mode: 'auto'` in `config.mcp_servers`.** Without it Codex flags every MCP tool call as needing user approval ("user cancelled MCP tool call"). Kōbō trusts every tool it spawns, so the options-builder pre-approves the namespace.
 
 ## Workspace operations
@@ -616,8 +663,10 @@ never automatically resend a possibly delivered summary. Explicit user stop canc
 the continuation. Errors retain recoverable intent and restore original settings.
 
 `auto_loop_final_reviews` (migration v52) adds an optional final gate configured
-before execution. Each pass starts a separate Plan review session with its own
-engine/model/effort/instructions. Only the active reviewer capability may submit
+before execution. Each pass starts a separate review session with its own
+engine/model/effort/instructions: Plan for Claude Code/Codex, native Interactive
+for Vibe. Kōbō grants allow only reads and scoped reports; native Vibe permissions
+do not guarantee filesystem read-only access and may require human approval. Only the active reviewer capability may submit
 the structured `kobo__submit_final_review` verdict. Findings become work tasks,
 invalidate finalization, and return to the exact original working session for
 automatic corrections under its original permissions. Repeat verification and a
@@ -716,7 +765,7 @@ global and project settings; keep this help and CONFIGURATION.md in sync.
 
 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.
 
-One task, two engines, two sibling worktrees. `POST /api/workspaces` accepts a `comparisonId`; the client posts twice with the same one (sequentially — parallel creations contend on the git index lock), suffixing the name with the engine's display name and the branch with the engine id and giving the non-configured engine the model picked for it on the form and its own effort / permission defaults. `workspaces.comparison_id` (migration v40) groups them; `listComparisonMembers` reads them back, treating an empty id as no group rather than as a match against the NULL majority. `GET /api/workspaces/:id/comparison` returns each member with its cached git stats (`null`, never zeros, when nothing has been measured). `ComparisonPanel.vue` renders the table at the top of the Git tab, only for workspaces that belong to a comparison. See [CONFIGURATION.md → Comparing two engines on one task](CONFIGURATION.md#comparing-two-engines-on-one-task).
+One task, Claude Code versus Codex, two sibling worktrees. Mistral Vibe is excluded from comparisons. `POST /api/workspaces` accepts a `comparisonId`; the client posts twice with the same one (sequentially — parallel creations contend on the git index lock), suffixing the name with the engine's display name and the branch with the engine id and giving the non-configured engine the model picked for it on the form and its own effort / permission defaults. `workspaces.comparison_id` (migration v40) groups them; `listComparisonMembers` reads them back, treating an empty id as no group rather than as a match against the NULL majority. `GET /api/workspaces/:id/comparison` returns each member with its cached git stats (`null`, never zeros, when nothing has been measured). `ComparisonPanel.vue` renders the table at the top of the Git tab, only for workspaces that belong to a comparison. See [CONFIGURATION.md → Comparing two engines on one task](CONFIGURATION.md#comparing-two-engines-on-one-task).
 
 ### Unanswered question reminder
 

package/CHANGELOG.md

@@ -2,7 +2,26 @@
 
 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.
+section — the in-app "What's new" dialog reads released version sections.
+
+## 2.1.30
+
+- fix(workspaces): preserve pr merge transitions and mobile focus
+- feat(agents): integrate mistral vibe through acp
+
+## Unreleased
+
+- Add Mistral Vibe through the official ACP SDK alongside Claude Code and Codex,
+  with native model/thinking discovery, permissions, resume, managed MCP and reviews.
+  Vibe is installed separately and does not support Plan mode.
+- Expose automatic-agent concurrency in Settings and group agent defaults by provider.
+- Preserve PR merge hooks and archiving across UI refreshes, show mergeability
+  recalculation explicitly, and keep branch deletion usable after worktree cleanup.
+- Avoid automatically opening the phone keyboard when switching workspaces.
+
+## 2.1.29
+
+- chore: upgrade node and dependencies and fix dev server readiness
 
 ## 2.1.28
 

package/CONFIGURATION.md

@@ -41,6 +41,7 @@ Reference for Kōbō configuration and external integrations. The tables cover t
 - [Agent runtimes](#agent-runtimes)
   - [Claude Code](#claude-code)
   - [OpenAI Codex](#openai-codex)
+  - [Mistral Vibe](#mistral-vibe)
   - [Permission modes](#permission-modes)
 - [Dev server](#dev-server)
 - [Forge integration](#forge-integration)
@@ -137,7 +138,7 @@ settings exports.
 | Key | Type | Purpose |
 |---|---|---|
 | `defaultModel` | `string` | Fallback model when no engine-specific default is set. |
-| `defaultModelByEngine` | `Record<engine, string>` | Per-engine default model (`claude-code` / `codex`). Fresh installs use Sonnet 5.5 (`claude-sonnet-5-5`) for Claude Code and `auto` for Codex. Historical migrations and existing user choices are preserved. The actual model is reported by the engine when the session starts; an Auto configuration label is not a model name. |
+| `defaultModelByEngine` | `Record<engine, string>` | Per-engine default model (`claude-code` / `codex` / `mistral-vibe`). Fresh installs use Sonnet 5.5 (`claude-sonnet-5-5`) for Claude Code and `auto` for Codex and Mistral Vibe. Historical migrations and existing user choices are preserved. The actual model is reported by the engine when the session starts; an Auto configuration label is not a model name. |
 | `workflowPolicy` | `{ commit, push, publish }` | Independent `manual` / `automatic` preferences, snapshotted at workspace creation. Fresh defaults are manual. See [Git preferences](#first-run-defaults-and-git-workflow-preferences). |
 | `skillSuite` | `string` | Standard, an external suite/combination, or custom instructions. Fresh default `standard`; see [Skill suites](#skill-suites). |
 | `defaultPermissionModeByEngine` | `Record<engine, mode>` | Default permission mode per engine. See [Permission modes](#permission-modes). |
@@ -653,11 +654,14 @@ above.
 
 ## Choosing an LLM for code review
 
-The workspace's **Start review** dialog offers engine (Claude Code or Codex),
+The workspace's **Start review** dialog offers engine (Claude Code, Codex or Mistral Vibe),
 model, reasoning effort and permission mode using the same catalogues as workspace
 creation. The current workspace settings are selected initially. Changing any of
 these settings automatically enables and locks **New session**; with unchanged
-settings you can continue the current session or start a fresh one explicitly.
+settings Claude Code/Codex can continue the current session or start a fresh one explicitly.
+Mistral Vibe reviews always use a fresh session and default to native **Interactive**
+permissions. Their prompts forbid modifications, but they cannot guarantee filesystem
+read-only access; Kōbō-managed tools remain restricted. See [Mistral Vibe](#mistral-vibe).
 
 Enable **Return to the current session after the review** to resume the original
 conversation with its original LLM settings and the reviewer's final summary.
@@ -681,8 +685,10 @@ also keeps a recoverable return instead of silently losing it.
 Enable **Final review** in the creation form or the workspace's Auto-loop panel.
 Configure the reviewer engine, model, reasoning effort and additional instructions
 in advance. Workspace templates and remembered creation preferences retain these
-settings. Each review uses a separate session in Plan mode and returns to the exact
-working session with its original LLM settings and permissions.
+settings. Each review uses a separate session: Plan for Claude Code/Codex, native
+Interactive for Vibe. Kōbō grants allow only reads and scoped reports; Vibe does not
+guarantee filesystem read-only access and may pause for human approval. The review
+returns to the exact working session with its original LLM settings and permissions.
 
 After all work and final checks pass, Kōbō launches the reviewer. Its structured
 findings become tasks for the original agent to correct automatically. The agent
@@ -870,7 +876,15 @@ capacity release and lifecycle-guard release reconsider waiting workspaces.
 It emits `autoloop:waiting-for-slot` so the
 interface can say so rather than looking stalled.
 
-The setting lives in `settings.json` under `global` and has no UI control yet:
+Change the limit in **Settings → Agents**. Saving applies immediately: increasing
+it, or changing a finite limit to `0`, immediately reconsiders waiting auto-loop
+iterations and review returns through the normal admission checks. Cron, wakeup
+and quota retries retain their existing timers and deadlines; their next admission
+check reads the new limit. Reducing it never interrupts active sessions; new
+automatic sessions wait until capacity becomes available. Progress and retry state
+are preserved.
+
+The setting also lives in `settings.json` under `global`:
 
 ```json
 { "global": { "maxConcurrentAgents": 3 } }
@@ -985,7 +999,7 @@ arguments, ordering, retry behavior and update limits.
 
 ## Persistent memory
 
-Kōbō stores deliberate, concise facts in SQLite, independently of Claude Code's native memory and provider chat history. Claude Code and Codex read the same Kōbō scopes, so a fact saved in one engine can be available to the other. There is no background transcript extractor or extra LLM call: agents must deliberately use the memory tools to save useful knowledge.
+Kōbō stores deliberate, concise facts in SQLite, independently of Claude Code's native memory and provider chat history. Claude Code, Codex and Mistral Vibe read the same Kōbō scopes, so facts can follow a mission across engines. The incremental v55 migration preserves existing entries/proposals while extending engine provenance. There is no background transcript extractor or extra LLM call: agents must deliberately use the memory tools to save useful knowledge.
 
 Choose the global behavior in **Settings → Memory**. New and upgraded installations default to **Hybrid**:
 
@@ -1293,7 +1307,7 @@ and [project/skills operations guide](./docs/vps-projects-and-skills.md).
 
 ### The image
 
-Multi-stage `Dockerfile`, `node:24.19.0-slim` base:
+Multi-stage `Dockerfile`, `node:26.12.1-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, 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.
@@ -1336,7 +1350,7 @@ retrieved once — see [Token / login flow](#token--login-flow).
 
 | Mount | RO/RW | Purpose |
 |---|---|---|
-| `kobo-home:/root` (`vps.yml`, named volume) | RW | Independent Kōbō, Claude/Codex, Git and forge state. Authenticate inside the container; no PC credential files are required. |
+| `kobo-home:/root` (`vps.yml`, named volume) | RW | Independent Kōbō, Claude/Codex, optional Vibe native state, Git and forge state. Authenticate inside the container; no PC credential files are required. |
 | `<name>-data:/root/.config/kobo` (named volume) | RW | Kōbō's own state — SQLite DB, `settings.json`, etc. Named (not bind-mounted) so it survives `docker compose down` without `-v`, and so it can be deliberately **shared** across compose files by reusing the same volume name (see the two local files, both `kobo-test-data`). |
 | `${KOBO_PROJECTS_DIR:-./kobo-projects}:/projects` | RW | Your project repositories. Ensure the configured worktree directory is also persistent. For project Docker bind mounts, use the VPS example’s identical host/container paths; see the [path setup](./docs/deployment-vps.md#optional-project-docker-environments). |
 | `${HOME}/.ssh:/root/.ssh` | RO | Git SSH auth — needed to push/pull over SSH remotes. |
@@ -1509,7 +1523,7 @@ An old image alone is not a complete rollback after database migrations.
 
 ## Agent runtimes
 
-Engines are selected per workspace at creation time. Both share the same UI surface (chat feed, task panel, permission modes, sub-agent panel, quota footer, auto-loop).
+Engines are selected per workspace at creation time. All three share chat, task tracking, memory and auto-loop; available permissions and optional controls depend on each engine's capabilities.
 
 ### Claude Code
 
@@ -1544,7 +1558,7 @@ its dedicated auto-loop API.
 
 **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
+both new and existing installations. Each engine 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.
 
@@ -1597,6 +1611,92 @@ When a Codex session is already working, **Send now** sends a queued chat messag
 
 The selector reads [`src/shared/codex-models.ts`](./src/shared/codex-models.ts). This checkout lists GPT-6 Astra, GPT-5.6 Sol/Terra/Luna, GPT-5.5 and older variants; availability depends on your account and authentication. Kōbō exposes effort values `auto`, `none`, `low`, `medium`, `high`, `xhigh`, and `max`, as declared in the engine's capabilities. The runtime must support the selected model/effort combination. Both selectors switch when you change the engine.
 
+### Mistral Vibe
+
+> Experimental. Target version: **Vibe 3.0.1**, ACP v1 with SDK 2.0.1.
+
+Follow the official [native Vibe setup](https://docs.mistral.ai/vibe/code/cli/install-setup)
+and [Vibe 3.0.1 ACP instructions](https://github.com/mistralai/mistral-vibe/blob/v3.0.1/docs/acp-setup.md).
+Install Vibe separately; run `vibe` for its native authentication wizard (`vibe --setup`
+to repeat it). Run these as the **same OS user and in the same environment as the
+Kōbō server**. `vibe-acp` must be on that user's PATH. Kōbō inherits native provider
+configuration/authentication and does not store a Mistral key. Explicit native
+model/thinking selections can persist Vibe preferences as described below. In Docker, host installation/login is insufficient: install and
+configure Vibe inside the container and persist its native state; see
+[VPS setup](./docs/vps-projects-and-skills.md#use-mistral-vibe-inside-the-container).
+
+The health diagnostic checks `vibe-acp --version` without contacting a provider.
+A detected executable/version is **not an authentication check**. If a launch
+reports authentication required, complete native setup in the server environment;
+check PATH/permissions for executable errors. Kōbō does not launch browser login,
+install or update Vibe for you.
+
+Model and thinking **Auto** retain native selection and send no override. Native
+model aliases, display names and model-specific thinking levels are discovered
+from Vibe for the selected project/workspace and permission mode. Settings without
+a project use the server user's home. Discovery creates and closes a native session
+without sending a prompt, contacting a provider or changing configuration. It uses
+short-lived child environment overrides, never model/thinking setters. Discovery
+results are cached for 30 seconds; failed discovery leaves Auto available and keeps
+explicit saved choices visible. Use Retry to request the options again.
+
+**Explicit model or thinking selections may persist in native Vibe preferences**
+through Vibe's public ACP setters, including preferences used outside Kōbō. At each
+actual launch, Kōbō confirms native mode, model and thinking in that order before
+sending the prompt. Native profiles/admin policy remain authoritative; unavailable
+or overridden selections fail explicitly instead of falling back to Auto. Project
+preflight cannot guarantee a future worktree or resumed session has identical
+options, so launch validation remains mandatory. Thinking values are native values
+(e.g. `off`, `low`, `medium`, `high`, `max` when advertised); `none` and `xhigh` are
+not translated. Brainstorming has independent model/thinking choices. On return
+from a review, native saved-session thinking is retained separately from the
+workspace iteration settings. An Auto-model resume validates explicit thinking
+against the loaded session, not a new session using potentially different defaults.
+
+New Vibe workspaces visibly default to **Interactive**. Only these native execution
+modes are offered:
+
+| Kōbō mode | Native Vibe mode |
+|---|---|
+| `interactive` | `ask` |
+| `strict` | `accept-edits` |
+| `bypass` | `auto-approve` |
+
+These are native approval modes, not a Kōbō sandbox. Native profiles and admin
+policy may change effective permissions. Plan/read-only launches are rejected before spawning or changing the workspace. Existing Plan
+choices require an explicit supported mode; they are never promoted automatically.
+The comparison feature remains **Claude Code versus Codex**.
+
+Native tools, approval/question panels, managed tasks/memory/progress MCP, resume
+and whole-session Stop are supported. Messages wait in the normal queue until
+the native process closes, then resume the conversation. Live steering and
+**Send now** are unavailable while Vibe is busy, including forced immediate
+messages and external MCP sends; rejected sends are not silently queued.
+Account/quota controls, managed skills and sub-agent cards/individual stop are
+excluded. Native tools/skills remain Vibe's own configuration.
+
+A manual handoff can target Vibe with a supported execution mode. For a Vibe
+source, disable **Generate a handoff with the current agent** and use the existing
+mission/history handoff: Vibe cannot run the restricted read-only summary launch.
+Vibe is available for manual and automatic final reviews. Manual reviews always
+start a fresh session, defaulting to Interactive independently of source permissions;
+Accept edits and Bypass remain explicit manual choices. Automatic final reviews
+always use Interactive and may pause for human approval. Review instructions forbid
+all modifications, but native permissions provide no guaranteed filesystem read-only
+enforcement. Kōbō memory and managed MCP remain read/report-only, including under
+Automatic memory mode; final-verdict and progress grants stay scoped. Explicit
+review model/thinking choices use the same native catalogue and persistence rules.
+Other supported engines can also review Vibe's work. Stop/transfer waits for actual
+native exit; an ACP close acknowledgement alone does not release the worktree.
+
+On **2026-10-23, Linux x64, Node 26.12.1**, the installed 3.0.1 passed the real
+Kōbō adapter smoke using an isolated loopback provider and synthetic stdio MCP:
+permissions, question, all three modes with MCP, native resume without duplicated
+history, renewed MCP environment and managed-job cleanup after confirmed exit.
+This made no paid call. **Real-provider end-to-end compatibility remains unverified**;
+its separately opt-in scenario has not been run. Commands and exact limits are in
+[the compatibility record](./src/__tests__/fixtures/mistral-acp/README.md).
+
 ### Switch Claude Code and Codex accounts with ccswap
 
 The usage popover in the chat footer can show the current **managed account**
@@ -1658,7 +1758,7 @@ credential-directory environment. See [VPS account setup](./docs/vps-projects-an
 
 ### Permission modes
 
-Claude Code uses SDK permission modes; Codex uses sandbox and approval flags. These controls differ by engine. A Git worktree itself is not a security boundary.
+Claude Code uses SDK permission modes; Codex uses sandbox and approval flags; [Mistral Vibe](#mistral-vibe) uses native execution modes and excludes Plan. These controls differ by engine. A Git worktree itself is not a security boundary.
 
 **Claude Code** (controlled via SDK options):
 
@@ -1702,15 +1802,17 @@ Kōbō treats the dev server in two independent layers:
 | Layer | Driven by | Works for any project? |
 |---|---|---|
 | **Start / Stop** | The shell commands you configure | ✅ Yes, any shell-startable process |
-| **Status badge, URL, container count, logs** | The `.container/instances/*.env` convention + Docker | ❌ No, requires the convention below |
-
-Configured processes can be started and stopped. Docker status, a URL and logs
-require a matching instance file and running containers. Without an instance,
-runtime detection returns `unknown`; the HTTP route may show the saved process
-status instead, but has no URL or container logs. Without a start command, the
-route returns `not_configured`.
-
-> **Known limitation: Docker-coupled, for now.** Status detection, the URL, the container count, and the logs viewer are currently hard-wired to Docker and to the `.container/instances/*.env` convention described below. This is a deliberate, temporary state: it works today for Docker-instance projects, and the convention is documented here so you can adopt it. An **evolution is planned** to abstract this layer, making the URL/port configurable and the running-detection engine-agnostic (e.g. a TCP probe) so the panel works for any project, Docker or not, without imposing this file layout. Until that lands, follow the contract below.
+| **Status badge, URL** | A tracked process's local readiness announcement, or the Docker convention below | Quasar (`App URL...`) and Vite/Next (`Local:`), or matching Docker containers |
+| **Container count, logs viewer** | The `.container/instances/*.env` convention + Docker | ❌ No, requires the convention below |
+
+Configured processes can be started and stopped. A tracked direct process reports
+`starting` until it announces a local HTTP(S) URL in a recognized readiness line
+on stdout or stderr, then reports `running` with that URL and port. Colored output
+and lines split across chunks are supported. This observes the CLI announcement;
+it does not probe application health. Docker container status and logs require a
+matching instance file and running containers. Without a tracked process or an
+instance, runtime detection returns `unknown`; the HTTP route may show the saved
+status instead. Without a start command, the route returns `not_configured`.
 
 ### 1. Configure start / stop commands
 
@@ -1729,9 +1831,9 @@ How Kōbō runs them:
   - `DEV_DOCKER_NO_FOLLOW=1`: a hint that a Docker setup script should exit after starting its containers instead of following logs. A tracked start process reports `starting` when an instance file exists but no matching container is running yet; once containers appear, Docker status takes precedence.
 - `stopCommand` runs with `INSTANCE` and `PROJECT_NAME` in the environment. After it, Kōbō also unconditionally runs `docker compose -p <PROJECT_NAME> down` if a `PROJECT_NAME` was resolved, so a Docker project does not strictly need a `stopCommand` at all.
 
-### 2. Make the status panel light up — the `.container/instances` contract
+### 2. Docker status — the `.container/instances` contract
 
-For the **Running** badge, the URL, the container count, and the logs button to appear, your **start command must create an instance file**:
+For Docker detection, the URL, the container count, and the logs button to appear, your **start command must create an instance file**:
 
 ```
 <project-root>/.container/instances/<any-name>.env
@@ -1753,13 +1855,12 @@ The simplest correct start script therefore: read `$INSTANCE`, start your contai
 
 ### 3. Running detection and logs
 
-- **Status**: `running` if at least one container has the exact Compose project label; `starting` if an instance file exists and the start process remains tracked but no container is running; `stopped` otherwise; `unknown` if no instance file matched.
+- **Status**: a tracked process with a recognized local readiness URL reports `running`. Otherwise, `running` if at least one container has the exact Compose project label; `starting` while the start process remains tracked; `stopped` when an instance exists but no container or process remains; `unknown` if neither a tracked process nor an instance matched.
 - **Logs**: the logs button runs `docker logs` on those same matched containers.
 
-Both are **Docker-only**. A plain Node process (`npm run dev`) does not produce a
-running Docker status or container logs. Writing an instance file alone is not
-enough to expose a URL: status responses only include the URL when matching
-containers are running. Direct processes can still be started and stopped.
+The logs viewer and container count remain **Docker-only**. Writing an instance
+file alone is not enough to expose a URL: matching containers must be running,
+or a tracked direct process must have announced its local URL.
 
 ### Minimal setups
 
@@ -1767,11 +1868,15 @@ containers are running. Direct processes can still be started and stopped.
 
 **Non-Docker project (e.g. Vite/Node)**: configure a foreground command such as
 `npm run dev`. Kōbō tracks its process group for shutdown, including children that
-outlive the shell. Open the project's URL yourself; the Docker status, URL and
-logs contract does not provide general process health monitoring.
+outlive the shell. Quasar's `App URL... http://localhost:9000/` and Vite/Next's
+`Local: http://localhost:5173/` announcements populate the status and URL without
+an instance file. Other output formats remain `starting`; there is no general
+process health monitoring or direct-process log viewer. Readiness URLs are kept
+only for the current launch and cleared when it stops.
 
-**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.
+**No instance file at all**: Start/Stop run your commands; a tracked process uses
+the direct-process detection above. Otherwise the panel uses the saved status
+when available, or `unknown`, with no URL or Docker logs.
 
 ### Kōbō shutdown
 
@@ -2256,7 +2361,7 @@ Lets you bypass the bundled prompts entirely and write your own. The five `custo
 
 ## gbrain (companion MCP)
 
-[`gbrain`](https://github.com/garrytan/gbrain) is a separate companion tool: a per-project knowledge graph and semantic search index, with an MCP server interface. It's **not** a Kōbō skill suite (it doesn't change the auto-generated prompts) but it plugs into Kōbō workspaces transparently via the standard Claude Code MCP config: Claude Code sessions can inherit MCP servers registered in `~/.claude.json`. Codex uses its own native MCP configuration; Kōbō does not copy arbitrary Claude MCP entries into Codex. The managed Notion/Sentry connections described above are supplied explicitly to both engines.
+[`gbrain`](https://github.com/garrytan/gbrain) is a separate companion tool: a per-project knowledge graph and semantic search index, with an MCP server interface. It's **not** a Kōbō skill suite (it doesn't change the auto-generated prompts) but it plugs into Kōbō workspaces transparently via the standard Claude Code MCP config: Claude Code sessions can inherit MCP servers registered in `~/.claude.json`. Codex uses its own native MCP configuration; Kōbō does not copy arbitrary Claude MCP entries into Codex. The managed Notion/Sentry connections described above are supplied explicitly to all three engines.
 
 When gbrain is configured, the agent gets access to tools like:
 
@@ -2481,7 +2586,7 @@ as failures, with safe diagnostics; authentication/permission errors never justi
 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.
+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. Returning Claude Code/Codex reviewers and handoff reports remain in read-only Plan mode. Vibe reviewers use native permissions (Interactive by default, fixed Interactive for automatic final reviews), which may require human approval and do not guarantee filesystem read-only access. These restricted review/report launches restrict Kōbō grants to reads, scoped reports and operational progress; review instructions forbid modifications. 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.
 
@@ -2509,7 +2614,7 @@ the complete backend environment is not serialized into the agent configuration.
 Saving settings does not replace connections in an already-running engine. Stop
 that engine and resume, or start a fresh session, to apply changes. Disabling an
 integration removes its Kōbō-managed connection from subsequent launches; it does
-not remove independent MCP servers configured in Claude or Codex. Integration
+not remove independent MCP servers configured in Claude Code, Codex or Mistral Vibe. Integration
 credentials do not authorize the agent to modify remote data.
 
 

package/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for considering a contribution. This guide covers the from-source setup,
 
 ## Prerequisites
 
-Node.js ≥ 24.15. The repository's `.nvmrc` pins the tested version; run
+Node.js ≥ 26.12.1. The repository's `.nvmrc` pins the tested version; run
 `nvm use` when using nvm.
 
 ## Setup
@@ -52,7 +52,7 @@ Run a single test file with `npx vitest run src/__tests__/<file>.test.ts`, filte
 
 TDD for backend changes: write the failing test, confirm it fails for the right reason, implement minimally, then confirm it passes. Frontend tests cover stores, utilities, composables, and selected Vue components using Vue Test Utils and `happy-dom`. Type-checking and browser smoke tests complement this coverage. See [`AGENTS.md`](./AGENTS.md#testing-discipline) for route mocking and cleanup conventions.
 
-Backend tests pin `KOBO_HOME` to a temporary directory; never point tests at your production data. Live MCP tests are a separate, explicit command (`npm run test:mcp:live`) requiring `KOBO_LIVE_ENGINE`, `KOBO_LIVE_MODEL`, and real provider credentials. They stay outside normal CI; see the [MCP guide](./src/mcp-server/README.md#live-engine-validation).
+Backend tests pin `KOBO_HOME` to a temporary directory; never point tests at your production data. Live MCP tests are a separate, explicit command (`npm run test:mcp:live`) requiring `KOBO_LIVE_ENGINE`, `KOBO_LIVE_MODEL`, and real provider credentials. They stay outside normal CI; see the [MCP guide](./src/mcp-server/README.md#live-engine-validation). Mistral Vibe also has native ACP fixtures and an offline adapter smoke; see its [compatibility record](./src/__tests__/fixtures/mistral-acp/README.md) for the exact commands, prerequisites and the separate opt-in provider test.
 
 Schema changes must append a migration and update the fresh-install schema, with upgrade tests proving data preservation. See [Database migrations](./AGENTS.md#database-migrations). UI changes must follow [`DESIGN.md`](./DESIGN.md) and update all five translation files for user-visible text.
 

package/DESIGN.md

@@ -2,7 +2,7 @@
 
 ## Product Context
 
-- **What this is:** Kōbō — a Claude Code and Codex multi-agent orchestrator. Each "workspace" is a
+- **What this is:** Kōbō — a Claude Code, Codex and Mistral Vibe multi-agent orchestrator. Each "workspace" is a
   self-contained mission with its own git worktree, branch, agent session, optional dev
   server, optional Notion source-of-truth, and a dedicated MCP tools server.
 - **Who it's for:** Developers using their own local instance, from a first mission to advanced parallel workflows,