@loicngr/kobo 2.1.26 → 2.1.29

package/AGENTS.md

@@ -6,11 +6,13 @@ Guidance for AI coding agents (Claude Code, Cursor, etc.) working on this reposi
 
 **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.
 
-Single-user dev tool, local by default. The server binds `127.0.0.1` unless the opt-in "network access" setting is enabled, which binds all interfaces and gates non-loopback API/WS requests behind a shared token. Behind-a-reverse-proxy mode also requires the token for loopback API/WS requests; `/api/health` stays exempt. Host/Origin checks apply separately. No multi-tenant concerns.
+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.
+
+External `/api/mcp` and global stdio require dedicated hashed credentials with tool/workspace grants, expiry and revocation, even on loopback. Manage them through operator-only `/api/mcp-credentials`; global stdio uses `KOBO_MCP_TOKEN`. Managed workspace stdio uses per-launch `KOBO_MCP_SESSION_TOKEN` through OS-loopback-only `/api/internal-mcp`, never the operator token or direct SQLite writes. The backend enforces Plan/read-only permissions and revokes capabilities when stopping begins. Keep report/progress exceptions narrowly scoped. See [SECURITY.md](./SECURITY.md).
 
 ## 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.
 
@@ -103,7 +105,8 @@ src/
 │       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
 │       └── router/
 ├── mcp-server/                     # standalone MCP server spawned per workspace
-│   ├── kobo-tasks-server.ts        # entrypoint, registers tools
+│   ├── kobo-tasks-server.ts        # stdio bridge; forwards discovery/calls to authenticated backend
+│   ├── managed-mcp-dispatcher.ts   # workspace tool definitions/dispatch, executed in backend
 │   └── kobo-tasks-handlers.ts      # pure handlers (list_tasks, mark_task_done)
 ├── shared/                         # model catalogues, prompts, dialogue contracts, shared utilities
 └── __tests__/                      # backend Vitest suites; client tests live under client/src/__tests__/
@@ -292,7 +295,7 @@ 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.
+`POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind Host/Origin, network enablement and dedicated MCP credential 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.
 
 Optional `send_workspace_message.idempotency_key` uses `mcp_message_requests` (migration v43). Reserve before dispatch, preserve fingerprints and terminal outcomes, and never automatically resend an unfinished request after restart. The user event and accepted receipt commit in one SQLite transaction; broadcast follows commit. Dispatch may precede persistence, so interrupted requests are explicitly `delivery_unknown`, not an exactly-once execution promise. The backend alone calls `reconcileMessageRequests` on startup. History retention does not delete the ledger; workspace deletion cascades it.
 

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.29
+
+- chore: upgrade node and dependencies and fix dev server readiness
+
+## 2.1.28
+
+- fix(ci): authenticate packaged mcp smoke tests
+- fix(security): harden authentication and mcp access
+- feat(models): Add Haiku 5.5
+
+## 2.1.27
+
+- fix(security): harden authentication and mcp access
+- feat(models): Add Haiku 5.5
+
 ## 2.1.26
 
 - feat: switch Claude and Codex accounts with ccswap

package/CONFIGURATION.md

@@ -887,11 +887,28 @@ 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.
+Every external MCP client, including loopback and global stdio clients, must use
+a dedicated MCP key. The operator token and browser session cookie are not accepted
+by `/api/mcp`. Send the MCP key as `Authorization: Bearer <key>`. The endpoint retains the same Host/Origin, network-access and
+reverse-proxy policy. No network setting changes automatically.
+
+Keys are independent, stored only as hashes and have explicit tool and workspace
+grants, optional expiration and individual revocation. The default tool grant is
+read-only; writes and destructive tools require an explicit grant. Each key must
+select workspace IDs or deliberately grant all workspaces. An MCP key cannot
+authenticate to operator REST, terminal or credential-management endpoints.
+
+An authenticated operator manages credentials through `/api/mcp-credentials`:
+GET lists metadata and available tools; POST accepts `name`, optional `tools`,
+`workspaceIds` or `allWorkspaces: true`, and optional ISO `expiresAt`; DELETE
+`/api/mcp-credentials/<id>` revokes one key. Creation returns the raw `token` once.
+Do not send that token to logs, commit it, or reuse it as the operator credential.
 
 See [Connect an external LLM](src/mcp-server/README.md#connect-an-external-llm) for connection examples, tool arguments, cursor polling and authentication details.
 
-The **External LLM access (MCP)** panel within global Network access settings provides copyable URLs and HTTP/stdio configurations for this running installation. Previews use token placeholders; copying a configuration with the real token is a separate action. Set a client name to identify its messages and question answers in workspace history.
+The **External LLM access (MCP)** panel within global Network access settings
+provides HTTP/stdio configuration templates. Supply the dedicated MCP key for the
+intended client. Client names are display labels, not permission identities.
 
 External senders can supply `idempotency_key` once per intended message and reuse it on retries. The durable receipt survives backend restarts and event retention. An uncertain delivery is explicitly reported and never automatically sent again; see the MCP guide for response codes and limitations.
 
@@ -1058,8 +1075,9 @@ To disable network access, toggle it off and restart again.
 
 ### The network access token
 
-When network access is enabled, every non-loopback HTTP request and every
-non-loopback WebSocket connection must supply a shared token.
+When network access is enabled, remote API and WebSocket access requires
+operator authentication. The shared operator token opens a browser session;
+external MCP clients use separate scoped credentials.
 
 - **Auto-generated**: Kōbō generates a random token the first time you enable
   the feature. You never have to type one in.
@@ -1075,11 +1093,12 @@ non-loopback WebSocket connection must supply a shared token.
 
 **Option A: QR code (recommended for phones)**
 
-The Settings panel shows a QR code encoding
-`http://<lan-ip>:<port>/?token=<token>`. Scan it with your phone's camera
-while on the same Wi-Fi network; the browser opens directly to a pre-authenticated
-session. The token is stored in the browser's `localStorage` under
-`kobo:network-token` so subsequent visits don't require re-scanning.
+The Settings panel shows a QR code using a URL fragment (`#token=<token>`),
+which browsers do not send in HTTP requests. The client immediately removes the
+fragment and exchanges the token for a 12-hour HttpOnly, SameSite=Strict session
+cookie (Secure for a configured HTTPS proxy). The operator token is not retained in localStorage.
+Previously stored tokens are removed during migration. Use QR links only on
+trusted devices; do not publish or bookmark a credential-bearing link.
 
 **Option B: manual URL**
 
@@ -1087,22 +1106,27 @@ session. The token is stored in the browser's `localStorage` under
    `http://<lan-ip>:<port>/`).
 2. Open it on the remote device.
 3. A login dialog appears: paste the token from the Settings panel and confirm.
-4. The token is stored in `localStorage`; subsequent visits auto-authenticate.
+4. The HttpOnly session cookie authenticates subsequent visits until expiry or revocation.
 
 **Host machine (localhost)**: connect to `http://localhost:<port>` as usual.
 No token is needed unless **Behind a reverse proxy** is enabled.
 
 ### Token transport
 
-| Connection type | How to supply the token |
+| Connection type | Authentication |
 |---|---|
-| HTTP requests | `X-Kobo-Token: <token>` header |
-| MCP HTTP requests (`/api/mcp`) | `X-Kobo-Token` or `Authorization: Bearer <token>` |
-| WebSocket connections | `?token=<token>` query parameter on the upgrade URL |
-
-The Kōbō browser client handles both automatically once the token is stored in
-`localStorage`. Third-party scripts or API consumers must supply the header or
-query param manually.
+| Browser API requests | HttpOnly session cookie after login |
+| Operator scripts / REST | `X-Kobo-Token: <operator-token>` header |
+| External MCP HTTP (`/api/mcp`) | Dedicated MCP key as `Authorization: Bearer <key>` |
+| Browser WebSocket connections | Short-lived, single-use ticket in the upgrade URL, bound to its WS path |
+
+The browser handles session and ticket exchanges automatically. Tickets expire
+after 60 seconds and cannot be replayed, reused for a different terminal, or used
+after their session expires. The permanent operator token is no longer accepted
+in a WebSocket query string. Rotation, disabling network access or changing proxy
+mode invalidates browser sessions, pending tickets and existing main/terminal
+WebSocket connections. Agent processes are not stopped by credential revocation.
+Server restart also expires browser sessions.
 
 The IP address used for the loopback exemption is taken **from the OS socket**,
 never from forwarded headers (`X-Forwarded-For` etc.), so a remote client cannot
@@ -1154,19 +1178,15 @@ Practical consequences:
   count as the real interface. In development the Quasar dev server is the one
   exception, since it proxies to the backend and so never matches the `Host`;
   the `dev` npm script declares it through `KOBO_DEV_CLIENT_ORIGIN`.
-- **Behind-a-reverse-proxy mode accepts any host by default**, because only the
-  operator knows the expected domain. Declare it with
-  `KOBO_NETWORK_ACCESS_PROXY_HOST` (see below) to close that; the bundled
-  `docker-compose.example.yml` and `docker-compose.local-traefik.yml` do. That
-  mode also disables the loopback exemption, so every `/api/*` request has to
-  carry the token — but the SPA itself is served outside `/api/*` and behind no
-  token, so without a declared hostname a rebinding page can be served the real
-  interface and ask the user to paste their token into it.
+- **Behind-a-reverse-proxy mode requires a declared public hostname.** Set
+  `KOBO_NETWORK_ACCESS_PROXY_HOST`; missing or invalid configuration rejects
+  public requests. Internal loopback clients remain reachable but still require
+  authentication. The bundled proxy Compose files configure this explicitly.
 
 #### `KOBO_NETWORK_ACCESS_PROXY_HOST`
 
-Set it to the domain your proxy serves Kōbō under, and the host check is
-enforced in behind-a-reverse-proxy mode instead of being skipped:
+Set it to the public origin your proxy serves Kōbō under. This is required in
+behind-a-reverse-proxy mode:
 
 ```yaml
 environment:
@@ -1175,9 +1195,33 @@ environment:
   - KOBO_NETWORK_ACCESS_PROXY_HOST=kobo.example.com
 ```
 
-A scheme and a port are accepted and ignored (`https://kobo.example.com:8443`
-reads as `kobo.example.com`). Loopback stays reachable so a local healthcheck
-keeps working. Leaving it unset preserves the previous behaviour.
+A bare hostname means HTTPS. For a nonstandard port, set the complete origin,
+e.g. `https://kobo.example.com:8443`. Browser Origin checks compare the scheme,
+hostname and port exactly. Local HTTP proxy staging must explicitly declare
+`http://kobo.localhost`. Paths, credentials, query strings and fragments are
+invalid. Loopback healthchecks and authenticated internal calls remain reachable.
+Leaving this variable unset rejects public proxy traffic.
+
+### Browser response protections
+
+The server sends `Content-Security-Policy: frame-ancestors 'self'` and
+`X-Frame-Options: SAMEORIGIN`, preserving Kōbō's split panes while blocking
+embedding by another site. It also sends `X-Content-Type-Options: nosniff`,
+`Referrer-Policy: no-referrer` and `Cache-Control: no-store` for API responses.
+The public HTTPS Compose examples add one-year HSTS at Traefik, without applying
+it to subdomains or HTTP-only local staging. Kōbō does not trust forwarded headers
+to decide whether a connection is HTTPS. A broader script/style CSP is not enabled;
+it needs separate compatibility testing with Quasar and Monaco.
+
+Application limits apply per OS peer address (forwarded addresses are not trusted):
+3,000 API requests per minute and 20 login attempts per minute. Requests exceeding
+these limits receive HTTP 429. MCP permits 32 concurrent requests, with at most
+four bodies larger than 1 MiB or of unknown/chunked length; ordinary attachment
+uploads also have four slots. Authentication runs before body buffering. Main
+WebSocket messages are capped at 1 MiB, terminal messages at 128 KiB; sockets
+have per-peer and global caps and inbound message-rate limits. Behind a proxy,
+clients share the proxy peer's bucket, so configure client-IP limits at the proxy
+for deployments with many simultaneous clients.
 
 ### Security caveats
 
@@ -1249,7 +1293,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.
@@ -1300,7 +1344,7 @@ retrieved once — see [Token / login flow](#token--login-flow).
 | `${HOME}/.claude.json:/root/.claude.json` | RW | Claude Code auth + MCP server registrations. **Must already exist as a file on the host** (run `claude /login` locally first if it doesn't) — Docker silently creates an empty *directory* instead of erroring on a missing bind-mount source, which breaks auth in a confusing way. |
 | `${HOME}/.claude:/root/.claude` | RW | Claude Code's full state directory (skills/plugins cache, session transcripts, memory) — Claude Code writes into this tree during normal operation. |
 | `${HOME}/.codex:/root/.codex` | RW | Codex's full state directory (`auth.json`, `config.toml`). Harmless to mount even if you only use Claude Code. |
-| `/var/run/docker.sock:/var/run/docker.sock` | RW, enabled in `example.yml`, opt-in in `vps.yml` | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Remove this line if you don't need the dev-server panel. |
+| `/var/run/docker.sock:/var/run/docker.sock` | RW, opt-in in both `example.yml` and `vps.yml` | Lets the dev-server panel start/stop/tail logs for your projects' own `docker compose` stacks. **DANGER**: grants the container root-equivalent control over the host — anyone who can run a command inside `kobo` can spawn a privileged container that mounts the host filesystem. Leave this mount commented out unless required. |
 
 ### Ports
 
@@ -1316,25 +1360,32 @@ reachable, matching the real production posture.
 
 ### Token / login flow
 
-All four files pre-enable network access via env vars, so there's no interactive Settings-UI step.
-Retrieve the auto-generated token from the container's boot log, then bookmark the token-bearing URL:
+All four files pre-enable network access via environment variables. Startup logs
+never contain the token. Retrieve it deliberately from a trusted local terminal:
 
 ```bash
-docker compose -f <compose-file> logs kobo | grep Token
+docker compose -f <compose-file> exec kobo node -e 'const fs = require("node:fs"); console.log(JSON.parse(fs.readFileSync(process.env.KOBO_HOME + "/settings.json", "utf8")).global.networkAccessToken)'
 ```
 
-Open `http://<host>/?token=<token>` (exact host depends on the file — see the walkthroughs below).
-The token is stored in the browser's `localStorage`, so you only paste it once per browser.
+Open the plain application URL and paste the token into its login dialog. Do not
+put the token in a URL, command argument, log collector or shared transcript.
+For an npm installation, read `networkAccessToken` from your private
+`$KOBO_HOME/settings.json` (default `~/.config/kobo/settings.json`).
+Kōbō restricts its home to mode `0700` and settings, temporary settings and
+settings backups to `0600`, including existing files on startup or the next disk read.
+
+Existing logs from older releases may still contain a valid token. After upgrading,
+rotate it from Settings and apply your log-retention policy to retained copies.
+Kōbō does not delete historical logs automatically.
 
 ### Quick local test — `docker-compose.local.yml`
 
 ```bash
 docker build -t kobo:local .                          # once
 docker compose -f docker-compose.local.yml up -d
-docker compose -f docker-compose.local.yml logs kobo | grep Token
 ```
 
-Open `http://localhost:3000/?token=<token from above>`.
+Open `http://localhost:3000/`; retrieve the token using [Token / login flow](#token--login-flow) if prompted.
 
 By default the file bind-mounts `./kobo-projects` (next to it) at `/projects` — put a real git repo
 in there (or set `KOBO_PROJECTS_DIR` to point elsewhere) before creating a workspace. When you get
@@ -1353,10 +1404,9 @@ and lose all Kōbō state).
 ```bash
 docker build -t kobo:local .                          # once, if not already built
 docker compose -f docker-compose.local-traefik.yml up -d
-docker compose -f docker-compose.local-traefik.yml logs kobo | grep Token
 ```
 
-Open `http://kobo.localhost/?token=<token from above>` — `.localhost` resolves to `127.0.0.1` on
+Open `http://kobo.localhost/` and sign in using [Token / login flow](#token--login-flow) — `.localhost` resolves to `127.0.0.1` on
 most OSes without touching `/etc/hosts`. This exercises the exact routing/auth/mount setup used by
 `docker-compose.example.yml`, minus a real domain and TLS certificate.
 
@@ -1386,17 +1436,16 @@ Before using it:
 2. Replace `kobo.example.com` with your real domain, and `you@example.com` with a real email (Let's Encrypt account).
 3. Populate a `.env` file next to the compose file with `GH_TOKEN` / `GITLAB_TOKEN` if you use the forge integration.
 4. Point every bind mount (`~/.ssh`, `~/.gitconfig`, `~/.claude.json`, `~/.claude`, `~/.codex`) at real paths on the host — see [Volumes](#volumes) for what each one is for, in particular the "`~/.claude.json` must already exist as a file" gotcha.
-5. Decide whether you need the Docker-socket passthrough (dev-server panel). If not, delete that volume line — see the DANGER note in [Volumes](#volumes).
+5. Leave the Docker socket unmounted unless your project workflows require it; opting in grants host-level control. See [Volumes](#volumes).
 6. Network access + behind-a-reverse-proxy are already pre-enabled via the `KOBO_NETWORK_ACCESS_*` env vars in the file — no manual bootstrap step.
 
-Bring it up, grab the token, bookmark the URL:
+Start it, then retrieve the token using the login flow above:
 
 ```bash
 docker compose -f docker-compose.example.yml up -d
-docker compose -f docker-compose.example.yml logs kobo | grep Token
 ```
 
-Open `https://kobo.example.com/?token=<token>`. SSH access: `ssh -p 2222 root@<host>` (key-based
+Open `https://kobo.example.com/` and sign in using [Token / login flow](#token--login-flow). SSH access: `ssh -p 2222 root@<host>` (key-based
 only). See [Ports](#ports) and [Volumes](#volumes) above for the full rationale on the Docker socket
 and SSH tradeoffs before deploying this to a real machine.
 
@@ -1455,9 +1504,8 @@ An old image alone is not a complete rollback after database migrations.
   — check `docker inspect <container> --format '{{json .State.Health}}'`. This should not happen on
   a current image (`/api/health` is exempt from the token gate, see [The image](#the-image)); if you
   see a 401 in the health log on a custom-built image, you're missing that exemption.
-- **`docker compose logs kobo | grep Token` returns nothing** — network access wasn't enabled at
-  boot. Confirm `KOBO_NETWORK_ACCESS_ENABLED=true` is actually set in the `environment:` block for
-  the `kobo` service.
+- **The token is absent from startup logs** — this is intentional. Use the local
+  [token retrieval command](#token--login-flow), then the browser login dialog.
 
 ## Agent runtimes
 
@@ -1473,7 +1521,7 @@ claude /login
 
 Kōbō talks to the embedded [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript), which reuses the same login. The `claude` CLI is **not** required at runtime; you only need it for `/login`, `mcp add`, and other one-off setup commands. As a fallback you can export `ANTHROPIC_API_KEY` instead.
 
-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.
+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.1/5, Opus 5.5, Sonnet 5.5, Haiku 5.5 (`claude-haiku-5-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
 
@@ -1654,15 +1702,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
 
@@ -1681,9 +1731,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
@@ -1705,13 +1755,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
 
@@ -1719,11 +1768,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.
-
-**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.
+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; 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
 

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

package/README.md

@@ -28,7 +28,7 @@ Use [group messages](CONFIGURATION.md#group-workspace-messages) to send one inst
 
 ## Quick start
 
-Requires Node.js ≥ 24.15, Git, Bash and your own Claude Code **or** Codex authentication. No skill plugin or ticket integration is required. Kōbō is a local, single-user tool; each user installs their own instance.
+Requires Node.js ≥ 26.12.1, Git, Bash and your own Claude Code **or** Codex authentication. No skill plugin or ticket integration is required. Kōbō is a local, single-user tool; each user installs their own instance.
 
 ```bash
 npx @loicngr/kobo@latest

package/SECURITY.md

@@ -17,11 +17,37 @@ the account running Kōbō and the selected engine's permission mode. A Git work
 isolates a checkout, not processes, credentials or the filesystem. Only open
 projects and configure executable hooks/integrations you trust.
 
-The default listener is loopback. LAN access uses one shared token; it is not
-per-user authorization. Behind a reverse proxy, enable the corresponding setting
-so loopback API/WebSocket requests also require that token. Health checks are
-exempt. Host and Origin validation remain separate protections. Use HTTPS or a
-trusted private network; do not offer this installation as a shared public service.
+The default listener is loopback. Network access uses an operator token; it is not
+per-user authorization. Browsers exchange it for a 12-hour HttpOnly, SameSite=Strict
+cookie (Secure behind HTTPS proxies), never persist it in localStorage, and obtain
+60-second single-use tickets for each WebSocket path. Rotation, disabling network
+access, or changing proxy mode revokes sessions, pending tickets and active sockets,
+including terminals. Restarting Kōbō also expires sessions. A settings change may
+establish a new session for the browser that performed it using the returned token.
+
+Behind a reverse proxy, enable the corresponding setting and declare the exact
+public origin with `KOBO_NETWORK_ACCESS_PROXY_HOST` (bare domains default to HTTPS).
+Health checks are exempt. Host and Origin validation remain separate protections.
+Use HTTPS or a trusted private network; do not offer this installation as a shared
+public service. Configure HSTS at the HTTPS terminator. The supplied public Compose
+examples include it. Socket and request size/rate/concurrency limits are bounded
+in-process; proxy limits should complement them. Client IPs come from OS sockets,
+so callers behind the same proxy share limits.
+
+External MCP requires a separately issued Bearer credential, including on loopback.
+Each key has explicit tool and workspace grants, optional expiry, and independent
+revocation; only its hash is stored. The UI defaults to read-only tools, selected
+workspaces and 30-day expiry. Operator cookies/tokens cannot authenticate `/api/mcp`,
+and an MCP key cannot authenticate operator APIs or terminal upgrades. Global stdio
+forwards to that endpoint using `KOBO_MCP_TOKEN`; it does not read the database offline.
+
+Managed workspace stdio uses a per-launch `KOBO_MCP_SESSION_TOKEN` through the local
+`/api/internal-mcp` dispatcher. The backend owns authorization and database writes;
+Plan and read-only review launches cannot invoke mutating managed tools even if the
+provider approves a tool. Launch capabilities are revoked when stopping begins.
+Operational progress and narrowly scoped review/handoff reports retain their own
+capabilities. This tool boundary does not sandbox arbitrary code executed by an
+agent or other integrations running as the same OS account.
 
 Git workflow preferences express which automatic actions are wanted. They are not
 a sandbox for arbitrary shell commands or external MCP tools. Claude and Codex
@@ -33,7 +59,8 @@ network token.
 
 KOBO_HOME stores conversations, workspaces, backups and settings. Direct integration
 commands and credentials live in `integrations.json`, written atomically with mode
-0600 on Unix. They are plaintext local secrets: protect the host account and backups.
+0600 on Unix. Settings and their temporary files/backups are also private (0600),
+and new Kōbō home directories use 0700. They are plaintext local secrets: protect the host account and backups.
 They are excluded from settings exports and are never returned by the connection
 status API. A replacement connection must be entered in full. MCP error text and
 stderr are withheld because third-party processes may echo secrets.