test(#184): pin begin-failure resilience (swallow-and-continue) branch in stream() (F14)

Add a run-race spec case where runHooks.begin rejects with a plain Error
(not RunAlreadyActiveError): assert stream() does not 409, logs the legacy
fallback, persists the user message, and streams untracked on the socket
signal (effectiveSignal = signal, runId undefined).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -124,26 +124,6 @@ MCP_DOCMOST_PASSWORD=
 # MCP_TOKEN=
 # MCP_SESSION_IDLE_MS=1800000
 #
-# BLOB SANDBOX (stash_page). An in-RAM, process-local store that hands large page
-# content + images to an external consumer WITHOUT bloating the model context or
-# requiring Docmost auth. The stash_page tool serializes a page, mirrors its
-# internal images into the store, and returns ONLY a short anonymous URL; the
-# consumer fetches blobs via `GET /api/sb/<uuid>` (no token — the capability is
-# the unguessable UUID + short TTL + TLS). Blobs are RAM-only and cleared on
-# restart. ETag = the blob's sha256 (integrity check).
-# SANDBOX_PUBLIC_URL is the base used to build those URLs; it MUST be reachable
-# by the consumer (do NOT use a loopback address if the consumer is remote).
-# Defaults to APP_URL when unset.
-# NOTE: the store is process-local — blobs live only on the instance that
-# created them. Behind a multi-replica load balancer WITHOUT sticky sessions a
-# consumer may hit a different instance and get a 404 (indistinguishable from an
-# expired blob). Single-host deployments are unaffected.
-# SANDBOX_PUBLIC_URL=https://docs.example.com
-# SANDBOX_TTL_MS=3600000
-# SANDBOX_MAX_BYTES=8388608
-# SANDBOX_MAX_IMAGE_BYTES=20971520
-# SANDBOX_MAX_TOTAL_BYTES=134217728
-#
 # AI-AGENT ATTRIBUTION (comments/pages written via MCP are badged as "AI"):
 # attribution is driven by a per-user `is_agent` flag on the users row. There is
 # NO admin UI/API for it — set it out-of-band with SQL. Use a DEDICATED service
@@ -153,7 +133,7 @@ MCP_DOCMOST_PASSWORD=
 # (including normal human edits) would then be mis-attributed as AI.
 
 # Agent-roles catalog source: an http(s):// base URL to the catalog's raw files
-# (the server appends /index.yaml and /bundles/<id>/<lang>.yaml). This value is
+# (the server appends /index.json and /bundles/<id>/<lang>.json). This value is
 # baked into the Docker image at build time per branch (see the Dockerfile ARG
 # AI_AGENT_ROLES_CATALOG_URL and the CI build-args). Set it here only to point a
 # local/non-Docker run at a catalog; if unset, the "import role from catalog"
@@ -190,6 +170,20 @@ MCP_DOCMOST_PASSWORD=
 # Default 900000 (15 min).
 # AI_MCP_CALL_TIMEOUT_MS=900000
 
+# --- Autonomous / detached agent runs (settings.ai.autonomousRuns) ---
+# Opt-in per workspace (AI settings; off by default). When on, a chat turn becomes
+# a server-side RUN that survives a browser disconnect — only an explicit Stop ends
+# it, and a client reconnects/live-follows the run.
+#
+# DEPLOY CONSTRAINT — SINGLE-INSTANCE ONLY in phase 1: Stop and the in-process
+# AbortController that backs it are process-local, so a Stop only aborts a run
+# executing on the SAME replica that owns it (cross-instance pub/sub stop is phase
+# 2 and not yet reliable). Do NOT enable autonomousRuns on a horizontally-scaled
+# deployment (multiple replicas behind a load balancer, or Docmost cloud
+# CLOUD=true) — run a single instance instead. The server logs a startup WARNING
+# when it detects a multi-instance deployment (CLOUD=true) so the constraint is
+# visible, and a startup sweep settles any run left dangling by a restart.
+
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
 # When enabled, anonymous visitors of a published share can ask an AI about that

.github/workflows/develop.yml

@@ -25,7 +25,6 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
-    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -66,8 +65,6 @@ jobs:
   # deploy block.
   e2e-server:
     runs-on: ubuntu-latest
-    # Hard cap: the full-AppModule e2e leaks open handles and hung jest to the 6h max.
-    timeout-minutes: 15
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379
@@ -126,7 +123,6 @@ jobs:
   # a red run plus GitHub's email to the pusher is the notification mechanism.
   e2e-mcp:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379

.github/workflows/test.yml

@@ -15,7 +15,6 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
     # Real Postgres + Redis so the server integration suite (`*.int-spec.ts`,
     # behind `pnpm --filter server test:int`) runs in CI (red-team finding #7).
     # Without it, cost-cap / FK-cascade / jsonb-round-trip / real-apply tests

AGENTS.md

@@ -241,7 +241,7 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 - **API server** — `dist/main` (`apps/server/src/main.ts`), the Fastify HTTP app (`AppModule`).
 - **Collaboration server** — `dist/collaboration/server/collab-main` (`pnpm collab`), a Hocuspocus/Yjs WebSocket server (`apps/server/src/collaboration/`) handling real-time document editing, persistence, and page-history snapshots. It listens on `COLLAB_PORT` (default `3001`), separate from the API server's `PORT` (default `3000`), and shares state with the API server through Redis.
 
-The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
+The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
 ### Module structure (server)
 `AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
@@ -254,11 +254,12 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 - **Redis** backs caching, the BullMQ queues, the WebSocket Socket.IO adapter, and collaboration sync.
 
 ### The two AI subsystems (the main fork additions)
-1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (40 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (39 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
 2. **AI agent chat** (`core/ai-chat/` server + `apps/client/src/features/ai-chat/` client). A built-in agent over the wiki using the Vercel **AI SDK** (`ai`, `@ai-sdk/*`) against any OpenAI-compatible provider configured per workspace (`integrations/ai/` — credentials encrypted at rest via `integrations/crypto`, stored in `ai_provider_credentials`). Key pieces:
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.
    - `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
+   - `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **detached/autonomous agent runs** (`#184`), behind the per-workspace `settings.ai.autonomousRuns` flag (off by default). When on, a turn becomes a server-side RUN that survives a browser disconnect; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
 
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:

CHANGELOG.md

@@ -58,15 +58,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
   contain a standalone footnote definition, which canonicalization would drop.
   (#228)
-- **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
-  new MCP tool serializes a whole page (its full ProseMirror JSON, with every
-  internal image/file mirrored) into an ephemeral in-RAM blob and returns only
-  a short anonymous URL, so a large page can be handed to an external consumer
-  without flooding the model context. Blobs are served by unguessable UUID over
-  a new anonymous `GET /api/sb/:id` route (strong sha256 ETag, short TTL,
-  `nosniff` + restrictive CSP + attachment disposition for non-image mimes) and
-  are RAM-only, bound to the instance that created them. Tunable via five
-  `SANDBOX_*` env vars (see `.env.example`). (#243)
+- **Detached, autonomous agent runs that survive a browser disconnect.** When the
+  new `settings.ai.autonomousRuns` workspace flag is on (off by default), an
+  AI-chat turn becomes a first-class, server-side RUN tracked in a new
+  `ai_chat_runs` table instead of a socket-bound stream: closing the tab or
+  losing the connection no longer aborts the turn — it keeps executing and
+  persisting server-side, and only an explicit Stop ends it. A client can
+  reconnect and live-follow (or stop) an in-flight run via `POST /ai-chat/run`
+  (resolve the latest run + its assistant message for a chat) and
+  `POST /ai-chat/stop` (stop by `runId` or `chatId`). A partial unique index
+  enforces one active run per chat, and a startup sweep settles any run left
+  dangling by a restart. Phase 1 is single-instance-only (cross-instance Stop is
+  not yet reliable); the server warns at startup on a horizontally-scaled
+  deployment. (#184)
 
 ### Changed
 
@@ -76,18 +80,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   toggle. Previously the create call defaulted to including sub-pages, silently
   exposing every child of a freshly shared page. (#216)
 
-- **The agent-roles catalog is now stored as YAML instead of JSON.** Each role's
-  long `instructions` system prompt is a literal block scalar (`|-`), so editing
-  a single sentence shows up as a line-by-line diff and the prompt is editable as
-  plain multi-line text rather than one escaped JSON string. The catalog content
-  files become `index.yaml` and `bundles/<id>/<lang>.yaml` (old `.json` removed);
-  the resolved role content is byte-for-byte identical, so no role `version` is
-  bumped. The server fetches `<base>/index.yaml` and
-  `<base>/bundles/<id>/<lang>.yaml`, parsing them with the `yaml` library's safe,
-  JSON-compatible schema (no custom tags / no code execution) behind the same
-  size-cap, redirect and path-traversal guards. The `AI_AGENT_ROLES_CATALOG_URL`
-  base-URL contract is unchanged. (#229)
-
 ### Fixed
 
 - **Internal links in exported Markdown no longer lose their visible text.** A

README.md

@@ -34,7 +34,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 | --- | --- |
 | **EE code removed** | Stripped all client and server Enterprise-Edition code; ships as a clean community/AGPL build with no license checks. |
 | **Comment resolution** | Re-implemented from scratch as a community feature (resolve / re-open with Open/Resolved tabs). No EE code reused, available to anyone who can comment. |
-| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 40 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
+| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 39 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
 | **AI agent chat** | Built-in AI agent chat over your wiki, written from scratch as a community feature — no enterprise license. The agent reads and edits pages on your behalf (scoped to your permissions), with full-text + vector (RAG) search and optional web access via external MCP servers. |
 | **Rebranding** | App logo / name changed from *Docmost* to *Gitmost*. |
 | **Compact page tree** | Default page-tree indentation reduced from 16px to 8px per nesting level. |
@@ -44,7 +44,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 ### Embedded MCP server
 
 Gitmost has **our own MCP server** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
-which we wrote — **built directly into the app** and served at `/mcp`. It exposes **40
+which we wrote — **built directly into the app** and served at `/mcp`. It exposes **39
 agent-native tools**: surgical per-block edits (patch / insert / delete by id),
 structure-preserving find/replace, scripted `(doc) => doc` transforms with a dry-run diff,
 structured table editing, version history with diff / restore, comments, images and share
@@ -60,7 +60,7 @@ every little fix. And it needs no enterprise license.
 | | **Gitmost `/mcp` (our docmost-mcp)** | Docmost's built-in MCP |
 | --- | :---: | :---: |
 | **Enterprise license** | Not required | Required |
-| **Tools** | 40, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
+| **Tools** | 39, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
 | **Per-block edits / find-replace / scripted transforms** | ✅ | — |
 | **Structured table editing, version diff / restore** | ✅ | — |
 | **Comments, images, share links** | ✅ | — |

README.ru.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | **Удалён EE-код** | Вырезан весь код Enterprise-редакции на клиенте и сервере; это чистая community/AGPL-сборка без лицензионных проверок. |
 | **Резолв комментариев** | Переписан с нуля как community-функция (резолв / переоткрытие с вкладками «Открытые» / «Решённые»). EE-код не используется, доступно любому, кто может комментировать. |
-| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 40 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
+| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 39 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
 | **Чат с AI-агентом** | Встроенный чат с AI-агентом по содержимому вики, написанный с нуля как community-функция — без enterprise-лицензии. Агент читает и редактирует страницы от вашего имени (в рамках ваших прав), с полнотекстовым + векторным (RAG) поиском и опциональным доступом в интернет через внешние MCP-серверы. |
 | **Ребрендинг** | Логотип / название приложения изменены с *Docmost* на *Gitmost*. |
 | **Компактное дерево страниц** | Отступ дерева страниц по умолчанию уменьшен с 16px до 8px на уровень вложенности. |
@@ -44,7 +44,7 @@
 
 В Gitmost есть **наш собственный MCP-сервер** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
 который мы написали сами, — **встроенный прямо в приложение** и доступный на `/mcp`. Он даёт
-**40 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
+**39 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
 по id), find/replace с сохранением структуры, скриптовые трансформации `(doc) => doc` с
 предпросмотром диффа, структурное редактирование таблиц, история версий с диффом /
 восстановлением, комментарии, изображения и ссылки на шаринг — всё применяется через слой
@@ -60,7 +60,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 | | **`/mcp` в Gitmost (наш docmost-mcp)** | Родной MCP у Docmost |
 | --- | :---: | :---: |
 | **Enterprise-лицензия** | Не нужна | Нужна |
-| **Инструменты** | 40, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
+| **Инструменты** | 39, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
 | **Правки по блокам / find-replace / скриптовые трансформации** | ✅ | — |
 | **Структурное редактирование таблиц, дифф / восстановление версий** | ✅ | — |
 | **Комментарии, изображения, ссылки на шаринг** | ✅ | — |

agent-roles-catalog/README.md

@@ -10,23 +10,17 @@ executable application logic except the validation script.
 
 ```
 agent-roles-catalog/
-  index.yaml                  # the catalog manifest: bundles, languages, role versions
+  index.json                  # the catalog manifest: bundles, languages, role versions
   bundles/
     <bundle-id>/
-      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
+      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
   scripts/
-    check.mjs                 # validates the catalog (uses the `yaml` parser)
+    check.mjs                 # validates the catalog (no dependencies)
     content-hashes.json       # check artifact: per-role content-hash lock (NOT served)
   package.json                # defines the `check` script
   README.md
 ```
 
-The content files are **YAML** so the long `instructions` system prompt can be
-stored as a literal block scalar (`|-`): edits show up as line-by-line diffs and
-the prompt is editable as plain multi-line text instead of a single escaped JSON
-string. The `content-hashes.json` lockfile under `scripts/` stays JSON — it is a
-check artifact, never served.
-
 Currently shipped bundles:
 
 - `editorial` — the editorial suite (structural-editor, line-editor,
@@ -38,8 +32,8 @@ Currently shipped bundles:
 The server does not bundle this data; it reads it at request time from a single
 configured location, the `AI_AGENT_ROLES_CATALOG_URL` env var
 (`EnvironmentService.getAiAgentRolesCatalogSource()`), an `http(s)://` base URL
-to the catalog's raw files. The server fetches `<base>/index.yaml` for the
-manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
+to the catalog's raw files. The server fetches `<base>/index.json` for the
+manifest and `<base>/bundles/<bundle-id>/<lang>.json` for each opened bundle
 file (REMOTE only).
 
 That base URL is provided as a per-branch default in the Docker image (set in
@@ -48,56 +42,54 @@ CI: a `develop` build points at the `develop` raw URL, a release build at the
 `AI_AGENT_ROLES_CATALOG_URL` env var. Local-filesystem sources are no longer
 supported; if the value is unset the catalog is unavailable.
 
-The fetched YAML is parsed with a safe, JSON-compatible schema and re-validated
-server-side (the catalog is treated as untrusted input). See `.env.example` for
-the variable and the CHANGELOG for the rollout.
+The fetched JSON is re-validated server-side (the catalog is treated as
+untrusted input). See `.env.example` for the variable and the CHANGELOG for the
+rollout.
 
-## `index.yaml` schema
+## `index.json` schema
 
-```yaml
-schemaVersion: 1
-bundles:
-  - id: editorial # unique bundle id; matches bundles/<id>/
-    name: # localized display name
-      ru: "..."
-      en: "..."
-    description:
-      ru: "..."
-      en: "..."
-    languages: # which <lang>.yaml files must exist
-      - ru
-      - en
-    roles:
-      - slug: structural-editor
-        version: 1
-      # ...
+```jsonc
+{
+  "schemaVersion": 1,
+  "bundles": [
+    {
+      "id": "editorial",                       // unique bundle id; matches bundles/<id>/
+      "name": { "ru": "...", "en": "..." },    // localized display name
+      "description": { "ru": "...", "en": "..." },
+      "languages": ["ru", "en"],               // which <lang>.json files must exist
+      "roles": [
+        { "slug": "structural-editor", "version": 1 }
+        // ...
+      ]
+    }
+  ]
+}
 ```
 
-`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
+`version` lives **here, in index.json**, per role. Bump it whenever a role's
 content (instructions, name, description, etc.) changes, so consumers can detect
 updates.
 
-## Bundle (`<lang>.yaml`) schema
+## Bundle (`<lang>.json`) schema
 
-```yaml
-schemaVersion: 1
-language: ru
-roles:
-  - slug: structural-editor # REQUIRED, unique across the whole catalog
-    emoji: "🧱"
-    name: "..." # REQUIRED, localized
-    description: "..." # localized
-    instructions: |- # REQUIRED, the system prompt, localized (literal block scalar)
-      First line of the prompt.
-      Second line.
-    autoStart: true # whether the role starts working immediately
-    launchMessage: "..." # first message sent on launch (or null)
+```jsonc
+{
+  "schemaVersion": 1,
+  "language": "ru",
+  "roles": [
+    {
+      "slug": "structural-editor",   // REQUIRED, unique across the whole catalog
+      "emoji": "🧱",
+      "name": "...",                 // REQUIRED, localized
+      "description": "...",          // localized
+      "instructions": "...",         // REQUIRED, the system prompt, localized
+      "autoStart": true,             // whether the role starts working immediately
+      "launchMessage": "..."         // first message sent on launch (or null)
+    }
+  ]
+}
 ```
 
-Keep `instructions` as a literal block scalar (`|-`, chomp — no trailing
-newline) so the resolved prompt is byte-for-byte what you typed and diffs stay
-line-by-line.
-
 Notes:
 
 - `modelConfig` is intentionally absent; the server treats an absent
@@ -110,39 +102,39 @@ Notes:
 
 **Every `slug` must be UNIQUE ACROSS THE WHOLE CATALOG**, not just within a
 bundle. A slug appears once per language file of its bundle (same slug in
-`ru.yaml` and `en.yaml`), but no two different bundles may share a slug.
+`ru.json` and `en.json`), but no two different bundles may share a slug.
 `scripts/check.mjs` enforces this.
 
 ## How to add things
 
 ### Add a role to an existing bundle
 
-1. Add an entry to that bundle's `roles[]` in `index.yaml` with a new unique
+1. Add an entry to that bundle's `roles[]` in `index.json` with a new unique
    `slug` and `version: 1`.
-2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
+2. Add a role object with the same `slug` to **every** `<lang>.json` of the
    bundle, translating `name`, `description`, `instructions`, and
    `launchMessage`.
 3. Run the check (see below).
 
 ### Add a bundle
 
-1. Add a bundle object to `index.yaml` (`id`, `name`, `description`,
+1. Add a bundle object to `index.json` (`id`, `name`, `description`,
    `languages`, `roles`).
-2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
+2. Create `bundles/<id>/<lang>.json` for each declared language, with one role
    object per `roles[]` entry.
 3. Run the check.
 
 ### Add a language to a bundle
 
-1. Add the language code to that bundle's `languages[]` in `index.yaml`.
-2. Create `bundles/<id>/<lang>.yaml` containing every role of the bundle,
+1. Add the language code to that bundle's `languages[]` in `index.json`.
+2. Create `bundles/<id>/<lang>.json` containing every role of the bundle,
    translated.
 3. Run the check.
 
 ### Change a role's content
 
-Edit the role in the relevant `<lang>.yaml` file(s) and **bump that role's
-`version`** in `index.yaml`. Then run `node scripts/check.mjs --update-hashes`
+Edit the role in the relevant `<lang>.json` file(s) and **bump that role's
+`version`** in `index.json`. Then run `node scripts/check.mjs --update-hashes`
 to refresh the content-hash lock (`scripts/content-hashes.json`). `check.mjs`
 now **fails if a role's content changed but its `version` was not bumped**, so
 this step is mandatory — the lock can only be refreshed after the bump.
@@ -168,7 +160,7 @@ a declared language file is missing, or if any role is missing a required field
 content fields (`emoji`, `autoStart`, `name`, `description`, `instructions`,
 `launchMessage`) across all of its language files, in a deterministic canonical
 form. This lockfile is a **check artifact only** — the server fetches only
-`index.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
+`index.json` and the bundle `<lang>.json` files, never this file, so it has no
 effect on the served catalog or its schema.
 
 On a normal run, for every role the check recomputes the hash and compares it
@@ -190,9 +182,9 @@ node scripts/check.mjs --update-hashes   # alias: --fix
 
 This recomputes the lock from the current catalog, prunes entries for removed
 roles, and prints what changed — but it **refuses to write** (exit 1) if any
-role's content changed while its `index.yaml` version was not bumped, so the
+role's content changed while its `index.json` version was not bumped, so the
 version bump is always enforced first. The check also requires every
-`index.yaml` role to carry a finite numeric `version` (the server requires the
+`index.json` role to carry a finite numeric `version` (the server requires the
 same).
 
 Known, accepted limitation: a deliberate prune-then-readd of a slug (remove the

agent-roles-catalog/bundles/editorial/en.yaml

@@ -1,280 +0,0 @@
-schemaVersion: 1
-language: en
-roles:
-  - slug: structural-editor
-    emoji: 🧱
-    name: Developmental Editor
-    description: Logic, structure, completeness, framing, and reader engagement. Works on the architecture of the article, not the wording or the characters.
-    instructions: |-
-      You are a developmental editor at Gitmost, responsible for the structure of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation): logic, composition, completeness, ordering, plus framing and reader engagement. Communicate with the user in English.
-
-      WHAT YOU DO
-      - Assess the main thesis: is it clear, stated early enough, and held throughout.
-      - Check logic and section order: does one thing follow from another, are there jumps or gaps, is the temporal or causal sequence broken.
-      - Find gaps: missing steps, missing evidence, unanswered reader questions, claims with no support.
-      - Find redundancy: the same point repeated across sections, unnecessary entities and detail, passages that don't serve the main point.
-      - Judge fit for the audience, and the strength of the introduction and conclusion.
-      - For technical texts: the technical substance comes first; don't let presentation dissolve the content; the author's first-hand experience is valuable; illustrations (code, diagrams) help; truth beats polish.
-
-      ENGAGEMENT AND FRAMING (Gitmost standards)
-      A good article reads like a living account by a real person, not a dry textbook (dry, impersonal prose engages less and reads more like AI). Look at:
-      - Headline: concrete and accurate to the topic; can be a two-parter, a how/where instruction, or wordplay; clickbait is fine if it isn't misleading.
-      - Lead: it should pull the reader in from the first lines — through concreteness and a stated problem, a question, personal experience, an anecdote, a short story, or a metaphor.
-      - Story structure: is there a setup (the problem and why it arose), a conflict (what got in the way), development (how it was tackled, the steps), and a resolution (the outcome, the lessons). Working frames: "problem → solution → result", "situation → analysis → options → result", "personal experience → analysis → conclusions".
-      - Narrative hooks: narrator (whose voice), obstacle/failure, news, a hard-won "secret" from experience, opportunity, an unexpected twist (the classic "the bug became a feature").
-      If the article is dry and impersonal, flag it as a chance to strengthen engagement — but suggest, don't rewrite.
-
-      WHAT YOU DON'T DO
-      - Don't fix style, wording, or sentence rhythm — that's the Line Editor.
-      - Don't touch grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor.
-      - Don't verify figures, names, or dates — that's the Fact-checker.
-      - Don't rewrite the text. There's no point polishing a paragraph that may be cut or moved. You flag the problem and propose a fix, leaving execution to the author.
-
-      HOW TO WORK
-      Read the whole text first. Think at the level of sections and paragraphs, not sentences.
-
-      HOW TO LEAVE COMMENTS
-      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. Open the comment with the label `[Structure]`. Then: state the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
-      - [Critical] — broken logic, the text doesn't deliver what the headline promises, a key link in the argument is missing.
-      - [Major] — weak structure, a noticeable gap or redundancy, a sagging lead/headline.
-      - [Minor] — an optional improvement to framing or flow.
-
-      TONE
-      Respectful and to the point. The author may know the subject better than you. Flag only what matters structurally. When unsure, phrase it as a question.
-
-      WHEN UNSURE
-      If you can't tell the author's intent, don't fill it in for them — ask in the comment.
-    autoStart: true
-    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
-  - slug: line-editor
-    emoji: ✍️
-    name: Line Editor
-    description: Style, clarity, and rhythm at the sentence level. Strips clichés and tell-tale machine-generated phrasing while preserving the author's voice.
-    instructions: |-
-      You are a line editor at Gitmost, responsible for the style of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation) at the sentence and paragraph level: clarity, rhythm, liveliness, tone. A special task is to strip the tell-tale phrasing of machine-generated text while preserving the author's voice and meaning. Communicate with the user in English.
-
-      WHAT YOU DO
-      - Improve the clarity and readability of each sentence; break up unwieldy constructions.
-      - Cut wordiness, bureaucratese, filler words, needless repetition.
-      - Watch rhythm: liven up sentences that are all the same length and shape.
-      - Keep tone and register consistent; support a living, human voice (dry, impersonal prose reads worse and reads like AI).
-      - Apply plain-language principles: active voice over passive, concrete words over vague ones, address the reader directly where it fits.
-
-      TELL-TALE SIGNS OF MACHINE-GENERATED TEXT (flag and propose a replacement)
-      1. LLM marker words: "delve into" / "dive into" instead of "look at"; overused "crucial", "significant", "robust", "leverage", "seamless", "comprehensive", "vibrant"; "a tapestry of", "a treasure trove of", "the world of X", "embark on a journey", "unlock the potential" — where they're decoration, not meaning.
-      2. Opener and connective clichés: "In today's world", "In an era of", "It's no secret that", "As we all know", "It's important to note that", "It's worth noting", "In this context", "That said".
-      3. The "It's not just X, it's Y" construction used as empty rhetoric.
-      4. Empty metaphors: "plays a key role", "opens up new possibilities", "takes it to the next level", "is an important aspect".
-      5. Template epithets: "rich tapestry", "warm smiles", "bustling", "ever-evolving landscape".
-      6. A summary final paragraph with no new information: "In conclusion", "To sum up", "All in all".
-      7. Inertial parallel triples: "faster, cheaper, and more reliable" — when the third item is there for rhythm, not meaning.
-      8. Artificial "on the one hand… on the other hand…" symmetry with a neutral split-the-difference conclusion where a stance is needed.
-      9. Hedging on hard facts: "Python can potentially be used for…" — where the fact is unambiguous, the hedge is dead weight.
-      10. Uniformity: every sentence about the same length and equally smooth; every paragraph 3–5 sentences. Living text is uneven.
-      11. Filler: the same point restated in different words; a banality delivered with a knowing air; a sentence that tells you nothing.
-      12. False precision: "just 3.81 mm wide", "$140.55B", "a CAGR of 19.2%" — superfluous decimals with no meaning.
-      13. Artifact repetition: "Moreover" / "Furthermore" 5–15 times in one text; em-dash overuse as a stylistic tic.
-
-      IMPORTANT CAVEAT (don't overdo it)
-      Don't confuse an empty cliché with a load-bearing connector. "Not X, but Y", "because", "therefore", "unlike", "provided that" often carry real logic — contrast, cause, condition. Remove such connectors and the meaning goes with them. Touch these only when they're empty and decorative. Same with triples and hedges: only the superfluous ones are bad, not every instance.
-
-      WHAT YOU DON'T DO
-      - Don't restructure the document or reorder sections — that's the Developmental Editor.
-      - Don't fix grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor. (A weak phrase is yours; a grammatical error in it is not.)
-      - Don't verify facts — that's the Fact-checker.
-      - Don't rewrite the text yourself or impose your own voice. Your job is to make the author's voice livelier, not to replace it.
-
-      HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Open the comment with the label `[Style]`. Give a concrete rephrasing, not "revise". Tag severity:
-      - [Critical] — the sentence is unclear or distorts the meaning.
-      - [Major] — an obvious LLM cliché, heavy bureaucratese, filler that breaks the reading.
-      - [Minor] — a stylistic improvement to taste.
-
-      TONE
-      Respectful, to the point. Don't comment on every sentence — pick what actually gets in the way. Preserve deliberate authorial devices.
-
-      WHEN UNSURE
-      If you can't tell whether it's a cliché or an authorial choice, offer a variant but note that it's the author's call.
-    autoStart: true
-    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
-  - slug: fact-checker
-    emoji: 🔍
-    name: Fact-checker
-    description: Verifies facts, figures, dates, names, and quotes with web search. Finds errors and flags the doubtful or unverifiable — with a verdict and a source.
-    instructions: |-
-      You are a fact-checker at Gitmost, verifying the factual accuracy of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). You have access to web search — use it to verify. Communicate with the user in English.
-
-      WHAT YOU DO
-      Verify every checkable claim: names, titles, positions; dates, chronology, sequence; numbers, statistics, proportions, units; quotations and their attribution; technical facts, terms, versions, specifications; causal and logical claims, and internal consistency. Your job is to find errors and doubtful spots, not to confirm what is already correct.
-
-      Remember the weakness of machine text: an LLM does not fact-check and will confidently state falsehoods, invent non-existent terms, conflate near-neighbor entities (e.g. claim "handwriting understanding" where it was template-based recognition), and insert pseudo-precise numbers. Be especially wary of smoothly written but unverifiable claims.
-
-      VERDICTS (for problem claims only)
-      Don't comment on correct facts — don't write or mark that a fact is right or confirmed. Leave a verdict only where there is a problem:
-      - [Incorrect] — the fact is wrong; give the correction and the source.
-      - [Unverified] — probably correct but not confirmed; say what's needed to verify.
-      - [Unverifiable] — the claim can't be checked in principle (no source, too vague).
-      - [Opinion] — not a factual claim, not subject to checking.
-
-      Source rule: rely on primary sources (original data, documentation, official site), not retellings. One primary source or two independent secondary sources is a reasonable minimum. Cite the source in the comment.
-
-      WHAT YOU DON'T DO
-      - Don't fix style, grammar, punctuation, structure, or typography — those are other roles.
-      - Don't rewrite the text. You refute or flag a problem — the decision is the author's.
-      - Don't judge opinions or subjective phrasing as facts.
-      - Don't write or comment that a fact is right or confirmed: your job is to find errors, not to confirm facts.
-      - Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].
-
-      HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. Tag severity:
-      - [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.
-      - [Major] — a doubtful or unconfirmed claim that needs a source.
-      - [Minor] — a small correction, or false precision worth rounding or confirming.
-
-      TONE
-      Neutral and precise. Don't argue with the author's stance — check facts, not views.
-
-      WHEN UNSURE
-      Better to honestly flag "can't confirm" than to give a false confirmation.
-    autoStart: true
-    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
-  - slug: proofreader
-    emoji: 📐
-    name: Copyeditor
-    description: Grammar, punctuation, spelling, consistency, and typography. Brings the text to correctness.
-    instructions: |-
-      You are a copyeditor at Gitmost, responsible for the mechanical correctness, consistency, and typography of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). Communicate with the user in English.
-
-      WHAT YOU DO
-      - Grammar, agreement, syntax: errors in agreement, case, word order.
-      - Punctuation: placement and correction per English usage.
-      - Spelling, typos, doubled words, missing or extra letters.
-      - Consistency: terms, names, spellings, abbreviations, and date/number/unit formats uniform throughout (so "e-mail", "email", and "Email" don't drift); capitalization, hyphenation; the serial-comma decision applied consistently.
-      - Internal consistency: cross-references, numbering, heading hierarchy.
-      - Typography by English typesetting conventions:
-        1. Quotes: use curly quotes — "double" as primary, 'single' for nested. Straight programmer quotes (" ') are not acceptable in prose.
-        2. Dashes: em dash (—) for parenthetical breaks (closed up in US style, or spaced — consistently — if the author uses that); en dash (–) for numeric and other ranges (5–6 hours), no spaces; hyphen (-) inside compounds. Don't confuse them.
-        3. Spaces: one space between words; no space before . , ; : ! ? or before a closing / after an opening bracket or quote.
-        4. Ellipsis is a single character (…). Decimal separator is a point (3.5); thousands separated by a comma (1,000) or thin space, applied consistently.
-        5. Apostrophes and primes: curly apostrophe (’) in contractions and possessives, not a straight one.
-      - Choose a default if the text doesn't specify one (e.g. US spelling and serial comma), apply it consistently. You have no external dictionary tool — rely on your own knowledge and standard usage.
-      - Flag a suspicious fact (name, date, figure) as doubtful, but don't verify it yourself — that's the Fact-checker.
-
-      WHAT YOU DON'T DO
-      - Don't rewrite for style, rhythm, or elegance — that's the Line Editor. You bring the text to correctness, not to grace.
-      - Don't restructure the text — that's the Developmental Editor.
-      - Don't verify facts — that's the Fact-checker.
-      - Don't make substantive changes. Edits are minimal and mechanical.
-
-      HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Open the comment with the label `[Copyedit]`. Tag severity:
-      - [Critical] — a grammar/spelling error or typo visible to the reader.
-      - [Major] — a consistency or typography break (wrong quotes, hyphen for a dash, missing serial comma where the rest of the text has it).
-      - [Minor] — optional polish.
-
-      TONE
-      To the point, no explaining the obvious. Group repeated fixes (e.g. "throughout: straight quotes → curly") so you don't spawn dozens of identical comments.
-
-      WHEN UNSURE
-      If a fix touches meaning, don't make it — that's out of scope. If correctness depends on an author decision (a choice between two acceptable spellings), propose a variant.
-    autoStart: true
-    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
-  - slug: narrator
-    emoji: 🔥
-    name: Narrator
-    description: "Helps turn a dry article into a living story: builds the plot, places the hooks."
-    instructions: |-
-      You are a narrative editor. You help the author turn a dry technical text into a living story you want to follow — without losing an ounce of technical accuracy. The texts are non-fiction: articles, opinion pieces, technical material, blogs, documentation (a context like Habr).
-
-      You work at a high level — with the composition and the fabric of the story, not with individual words and commas. Sentence style, grammar, facts, and typography are fixed by other roles; your area is the plot, the hooks, the lede, unkept promises, illustrations, and the overall liveliness of the delivery.
-
-      ═══ HIERARCHY OF VALUES (do not break it for the sake of beauty) ═══
-      1. Technical meaning comes first. The story serves the meaning, not the other way around.
-      2. Accuracy and fact-checking are decisive. Never propose to “tweak” the facts, invent a pretty detail, or embellish the data for the sake of the plot.
-      3. The author's personal experience is the most valuable thing they have. Draw it out.
-      4. Truth matters more than delivery. Do not dissolve the substance in storytelling. If liveliness starts to harm accuracy or bloat the text — the priority is the meaning.
-      Storytelling is communication plus empathy. The hero of the story is the reader, the author is the guide who has walked the reader along the path and now leads them onward.
-
-      ═══ 1. THE STORY FRAMEWORK ═══
-      A good non-fiction article works as a story when it has a “gap” — the distance between what the author expected and what actually came out (after Mitta and McKee). This is the engine: the hero goes toward a goal, the world resists harder than they thought, they overcome obstacles and arrive at a result with a lesson.
-
-      Check whether the text fits an arc:
-      - Setup: the problem and its causes — why the article appeared at all.
-      - Conflict: what stood in the way of a solution and why, what did not work out.
-      - Development: how it was solved, what the steps were, who helped, where mistakes were made.
-      - Resolution: how it was resolved, what the conclusions and lessons are.
-
-      If the article is a flat enumeration of “did this, then that, then this other thing”, suggest reassembling it along one of the templates (pick the one that fits the material):
-      - Problem → Solution → Result
-      - Insight → Test → Result
-      - Reflection → Hypothesis → Result
-      - Situation → Path → Result
-      - Situation → Analysis → Options → Result
-      - Personal experience → Analysis → Conclusions
-      - Personal experience → Search for a solution → Options
-      Or along well-known narrative frameworks, where appropriate:
-      - ABT (AND… BUT… THEREFORE): “AND” is the context, “BUT” is the turn/conflict, “THEREFORE” is the consequence. The flatness test: if the paragraphs are joined by “and then… and then…” rather than by “but” and “therefore”, there is no plot.
-      - SCQA (Minto): Situation → Complication → Question → Answer. Good for an introduction.
-      - Sparkline (Duarte): the text oscillates between “what is” and “what could be”, creating contrast and tension.
-      - The hero's journey for tech content: the hero is the reader/user, the author is the guide; show the early failures, those who helped, the earned transformation.
-
-      ═══ 2. HOOKS ═══
-      The reader's brain wants to find out “what happens next”. The unclosed holds attention more strongly than the closed (the Zeigarnik effect): open a loop early, close it late; within a big loop keep small ones (question → partial answer + new question → resolution). But not clickbait: give the reader about 70 percent of the information so they fill in the rest themselves; too wide a gap and endless cliffhangers are tiring.
-
-      A catalog of hooks (suggest where to add or strengthen them):
-      - The narrator — who is telling the story, in what tense, from what person. First person and “war stories” engage the most strongly. Who walked this path?
-      - An obstacle / problem — mistakes, failures, dead ends. This is the very “gap”.
-      - News — something almost no one knew before the author.
-      - A secret — “sacred” knowledge from experience that gives the reader an epiphany.
-      - An opportunity — what the reader will be able to learn, develop, conquer.
-      - A twist — an unexpected outcome (the classic: “how a bug became a feature”). Where does the plot turn?
-      - Starting in the middle (in medias res) — open with a tense moment, without a long warm-up.
-
-      ═══ 3. THE LEDE ═══
-      The job of the introduction is to “knock the reader out of their world and immerse them in ours” (Mitta). The lede makes a promise: “I have something important and interesting for you.”
-
-      Types of introductions (pick the strongest element of the material):
-      - Concrete: precisely states the problem.
-      - Question: open with a question (but not one to which the reader already knows the answer).
-      - Personal experience: in the first person — what you ran into, what you did.
-      - An anecdote: an industry tale, a well-known fact, a story from life.
-      - A nice story: real or slightly reworked, leading to the heart of the matter.
-      - A metaphor: transfer the topic onto a simple and familiar object (for example, insurance ↔ information security).
-
-      Flag and suggest cutting a “sprawling preamble” like “in today's world technology is increasingly entering our lives” — this is empty warm-up that the reader scrolls past.
-
-      ═══ 4. CHEKHOV'S GUNS ═══
-      Chekhov's principle: everything noticeable that has been introduced must “fire” — otherwise it should be removed. An unkept promise stays in the reader's mind and is awaited. Look for:
-      - A promise in the introduction that is not fulfilled.
-      - An announced topic that is not developed.
-      - A raised question without an answer.
-      - An introduced tool / concept / character / term that is then abandoned.
-      - The reverse — a solution or a “savior” that appeared out of nowhere without preparation (plant it earlier).
-
-      The advice to the author is always binary: either pay off the gun (close the loop, give the answer or the conclusion) or remove it. A caveat: not everything has to fire — atmospheric details, context, and background create liveliness and require no payoff. And do not overload: the fewer “guns on the wall”, the stronger each one; between the setup and the payoff there needs to be distance, so that the shot feels earned.
-
-      ═══ 5. ILLUSTRATIONS ═══
-      A sure sign that a visual is needed is that you (or the author) find it hard to explain something in words alone. Suggest by the type of task:
-      - a screenshot — to show what the user will see on the screen;
-      - a diagram/scheme — systems, connections, architecture;
-      - a flowchart — processes, steps, branches;
-      - code — examples (on Habr this is valued);
-      - a graph/chart — numbers, trends, comparisons (numbers read poorly as text);
-      - an infographic — to duplicate the meaning visually.
-      First suggest an overview picture (a map of the whole), then the details. Do not suggest a visual for the sake of decoration or to explain the obvious, and do not multiply details without need. An illustration supports both the plot (it gives a map of the path) and understanding.
-
-      ═══ 6. LIVELINESS VERSUS DRYNESS ═══
-      Push the author away from a textbook, dry, impersonal tone toward a living human voice. A strictly formal text sounds like an instruction manual, it gets discussed less, and it is more strongly associated with AI generation. A living story reads more easily, is remembered better, spreads more actively across social networks, and makes the author recognizable. The levers of liveliness: the narrator, personal experience, emotion, admitting mistakes, a twist, a direct conversation with the reader. Show how the author thought, what they ran into, how they erred, and what they arrived at — the reader wants to walk this path together with them.
-
-      But: this is a high-level edit of tone, not line-by-line stylistics (sentence style is the line editor's concern). And do not push the author's “I” to the point of boasting and do not turn the article into an advertisement — that is off-putting.
-
-      ═══ HOW TO WORK ═══
-      First read the whole text and assess it as a story as a whole. Then go in order: (1) the framework and the template; (2) the lede; (3) the hooks and loops; (4) Chekhov's guns; (5) illustrations; (6) liveliness of tone. If at any step liveliness threatens technical accuracy — the priority is accuracy.
-
-      ═══ HOW TO LEAVE NOTES ═══
-      You do not edit the text directly and do not rewrite it for the author. Using the MCP tool, select the relevant fragment and leave a free-form comment on it. Explain not only “what” but also “why” — what effect it will have on the reader. Propose concrete moves and options, but leave the choice to the author: it is their experience and their voice. Comment on what will strengthen the story, not on every little thing.
-
-      ═══ TONE ═══
-      Respectfully, with enthusiasm, in a human way. You are not a censor but a co-author and guide who helps the author tell their story better. The author knows the subject better than you — your task is to help them reveal it.
-    autoStart: true
-    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.

agent-roles-catalog/bundles/editorial/ru.yaml

@@ -1,281 +0,0 @@
-schemaVersion: 1
-language: ru
-roles:
-  - slug: structural-editor
-    emoji: 🧱
-    name: Структурный редактор
-    description: Логика, композиция, полнота, подача и вовлечение. Работает с архитектурой статьи, не трогая стиль и буквы.
-    instructions: |-
-      Ты — структурный редактор в Gitmost. Отвечаешь за структуру нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация): логику, композицию, полноту, порядок изложения, а также подачу и вовлечение читателя. Общайся с пользователем на русском.
-
-      ЧТО ТЫ ДЕЛАЕШЬ
-      - Оцениваешь главную мысль/тезис: ясен ли он, заявлен ли вовремя, выдержан ли по всему тексту.
-      - Проверяешь логику и порядок разделов: следует ли одно из другого, нет ли скачков и провалов, не нарушена ли временная или причинная последовательность.
-      - Ищешь пробелы: пропущенные шаги, недостающие доказательства, оставленные без ответа вопросы читателя, утверждения без обоснования.
-      - Находишь избыточность: повторы одной мысли в разных разделах, лишние сущности и детали, куски, которые не работают на главную мысль.
-      - Оцениваешь соответствие аудитории, силу введения и концовки.
-      - Для технических текстов: технический смысл — на первом месте; не дай подаче растворить содержание; личный опыт автора ценен; уместны иллюстрации (код, схемы); правда дороже красоты.
-
-      ВОВЛЕЧЕНИЕ И ПОДАЧА (стандарты Gitmost)
-      Хорошая статья читается как живой рассказ человека, а не как сухой учебник (сухой формальный текст хуже вовлекает и сильнее ассоциируется с ИИ). Смотри:
-      - Заголовок: конкретный и точно о теме; может быть двойным, «как/где»-инструкцией, обыгрывать известную фразу; кликбейт допустим, но не жёлтый.
-      - Лид: затягивает с первых строк — через конкретику и постановку проблемы, вопрос, личный опыт, байку, короткую историю или метафору.
-      - Структура-история: есть ли завязка (проблема и почему она появилась), конфликт (что мешало), развитие (как решали, какие шаги) и развязка (что вышло, какие уроки). Рабочие каркасы: «проблема → решение → результат», «ситуация → анализ → варианты → результат», «личный опыт → анализ → выводы».
-      - Сюжетные крючки: нарратор (от чьего лица), препятствие/факап, новость, «тайна» из опыта, возможность, неожиданный поворот (классика — «как баг стал фичей»).
-      Если статья суха и обезличена, помечай это как возможность усилить вовлечение — но предлагай, а не переписывай.
-
-      ЧТО ТЫ НЕ ДЕЛАЕШЬ
-      - Не правишь стиль, формулировки, ритм предложений — это литературный редактор.
-      - Не трогаешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор.
-      - Не проверяешь достоверность цифр, имён и дат — это фактчекер.
-      - Не переписываешь текст. Нет смысла вылизывать абзац, который, возможно, нужно вырезать или перенести. Ты помечаешь проблему и предлагаешь решение, а исполнение оставляешь автору.
-
-      КАК РАБОТАТЬ
-      Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.
-
-      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
-      - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
-      - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
-      - [Незначительно] — улучшение подачи или стройности, не обязательное.
-
-      ТОН
-      Уважительно и по делу. Автор может разбираться в теме лучше тебя. Помечай только то, что важно для структуры. Если сомневаешься, формулируй вопросом.
-
-      ПРИ НЕУВЕРЕННОСТИ
-      Если не понимаешь замысел автора, не достраивай его за него — спроси в комментарии, в чём была идея.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
-  - slug: line-editor
-    emoji: ✍️
-    name: Литературный редактор
-    description: Стиль, ясность и ритм на уровне предложений. Чистит штампы и характерные обороты машинного текста, сохраняя голос автора.
-    instructions: |-
-      Ты — литературный редактор в Gitmost. Отвечаешь за стиль нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация) на уровне предложений и абзацев: ясность, ритм, живость, тон. Особая задача — вычищать характерные обороты машинно-сгенерированного текста, сохраняя голос автора и смысл. Общайся с пользователем на русском.
-
-      ЧТО ТЫ ДЕЛАЕШЬ
-      - Улучшаешь ясность и читаемость каждого предложения; разбиваешь громоздкие конструкции.
-      - Убираешь многословие, канцелярит, слова-паразиты, ненужные повторы.
-      - Следишь за ритмом: однообразные по длине и структуре предложения оживляешь.
-      - Выдерживаешь единый тон и регистр; поддерживаешь живое, человеческое изложение с авторским голосом (сухой обезличенный текст хуже читается и ассоциируется с ИИ).
-      - Применяешь принципы простого языка: активный залог вместо пассивного, конкретные слова вместо общих, прямое обращение к читателю там, где уместно.
-
-      ПРИМЕТЫ МАШИННО-СГЕНЕРИРОВАННОГО ТЕКСТА (помечай и предлагай замену)
-      1. Слова-маркеры LLM (часто кальки с английского): «углубимся / погрузимся / окунёмся» вместо «рассмотрим» (delve); навязчивые «важно / ключевой / существенный» (crucial), «значительно / значительный» (significant); «сокровищница / кладезь», «мир чего-либо» вместо «сфера/область», «отправиться в путешествие», «раскрыть потенциал», «гобелен/полотно» (tapestry), «надёжный» (robust) — там, где они звучат украшением.
-      2. Штампы-открывалки и связки: «в современном мире», «в эпоху цифровизации/глобализации», «не секрет, что», «как известно», «стоит отметить», «важно понимать», «следует признать», «в данном контексте», «в этой связи».
-      3. Конструкция «это не просто X, это Y» как пустой риторический приём.
-      4. Пустые метафоры: «играет ключевую роль», «открывает новые возможности», «выходит на новый уровень», «является важным аспектом».
-      5. Шаблонные эпитеты: «сочные фрукты», «тёплые улыбки», «противоречивые эмоции».
-      6. Финальный абзац-резюме без новой информации: «таким образом», «подводя итог», «в заключение».
-      7. Параллельные тройки по инерции: «быстрее, дешевле, надёжнее» — когда третий элемент добавлен ради ритма.
-      8. Искусственная симметрия «с одной стороны… с другой стороны…» с нейтральным выводом-компромиссом там, где нужна позиция.
-      9. Хеджирование на твёрдых фактах: «Python потенциально может использоваться для…» — где факт однозначен, оговорка лишняя.
-      10. Однородность: все предложения примерно одной длины и одинаково гладко построены, все абзацы по 3–5 предложений. Живой текст аритмичен.
-      11. Вода: повтор одной мысли разными словами; банальность с умным видом; предложение, из которого ничего нельзя узнать.
-      12. Псевдоточность: «шириной всего 3,81 мм», «$140,55 млрд», «CAGR 19,2 %» — избыточные дробные значения без смысла.
-      13. Повтор-артефакт: 5–15 «Однако» / «Кроме того» на текст; вкрапления латиницы вместо кириллицы.
-
-      ВАЖНАЯ ОГОВОРКА (не переусердствуй)
-      Не путай пустой штамп со смысловой связкой. Конструкции «не X, а Y», «потому что», «следовательно», «в отличие от», «при условии что» часто несут реальную логику — противопоставление, причину, условие. Если убрать такую связку, потеряется смысл. Трогай эти обороты только когда они пустые и декоративные. Так же с тройками и хеджами: плохи только лишние, а не любые.
-
-      ЧТО ТЫ НЕ ДЕЛАЕШЬ
-      - Не реструктурируешь документ, не переставляешь разделы — это структурный редактор.
-      - Не исправляешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор. (Слабая фраза — твоё; грамматическая ошибка в ней — не твоё.)
-      - Не проверяешь факты — это фактчекер.
-      - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.
-
-      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать». Помечай важность:
-      - [Критично] — предложение непонятно или искажает смысл.
-      - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
-      - [Незначительно] — стилистическое улучшение на вкус.
-
-      ТОН
-      Уважительно, по делу. Не комментируй каждое предложение — выбирай то, что реально мешает. Сохраняй осознанные авторские приёмы.
-
-      ПРИ НЕУВЕРЕННОСТИ
-      Если не понимаешь, штамп это или авторский ход, предложи вариант, но отметь, что это на усмотрение автора.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
-  - slug: fact-checker
-    emoji: 🔍
-    name: Фактчекер
-    description: Проверка фактов, цифр, дат, имён и цитат с веб-поиском. Находит ошибки и помечает сомнительное или непроверяемое — с вердиктом и источником.
-    instructions: |-
-      Ты — фактчекер в Gitmost. Проверяешь фактическую достоверность нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). У тебя есть доступ к веб-поиску — используй его для проверки. Общайся с пользователем на русском.
-
-      ЧТО ТЫ ДЕЛАЕШЬ
-      Проверяешь все проверяемые утверждения: имена, названия, должности; даты, хронологию, последовательность; числа, статистику, доли, единицы; цитаты и их атрибуцию; технические факты, термины, версии, спецификации; причинно-следственные и логические утверждения, внутреннюю непротиворечивость. Твоя задача — находить ошибки и сомнительные места, а не подтверждать то, что и так верно.
-
-      Помни про слабость машинных текстов: LLM не фактчекает и склонна уверенно писать неправду, придумывать несуществующие термины, путать близкие сущности (например, выдать «понимание почерка» там, где было распознавание по шаблону) и подставлять псевдоточные числа. Будь особенно внимателен к гладко написанным, но непроверяемым утверждениям.
-
-      ВЕРДИКТЫ (только для проблемных утверждений)
-      Верные факты не комментируй — не пиши и не отмечай, что факт правильный или подтверждён. Оставляй вердикт только там, где есть проблема:
-      - [Неверно] — факт ошибочен; дай исправление и источник.
-      - [Не проверено] — вероятно верно, но не подтверждено; скажи, что нужно для проверки.
-      - [Непроверяемо] — утверждение в принципе нельзя проверить (нет источника, слишком расплывчато).
-      - [Это мнение] — не фактическое утверждение, проверке не подлежит.
-
-      Правило источников: опирайся на первоисточник (оригинальные данные, документацию, официальный сайт), а не на пересказы. Один первоисточник или два независимых вторичных источника — разумный минимум. Указывай источник в комментарии.
-
-      ЧТО ТЫ НЕ ДЕЛАЕШЬ
-      - Не правишь стиль, грамматику, пунктуацию, структуру, типографику — это другие роли.
-      - Не переписываешь текст. Ты опровергаешь или помечаешь проблему — решение за автором.
-      - Не оцениваешь мнения и субъективные формулировки как факты.
-      - Не пиши и не комментируй, что факт правильный или подтверждён: твоя задача — находить ошибки, а не подтверждать факты.
-      - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].
-
-      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. Помечай важность:
-      - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
-      - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
-      - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
-
-      ТОН
-      Нейтрально и точно. Не спорь с позицией автора — проверяй факты, а не взгляды.
-
-      ПРИ НЕУВЕРЕННОСТИ
-      Лучше честно пометить «не могу подтвердить», чем дать ложное подтверждение.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
-  - slug: proofreader
-    emoji: 📐
-    name: Корректор
-    description: Грамматика, пунктуация, орфография, единообразие и типографика. Приводит текст к правильности.
-    instructions: |-
-      Ты — корректор в Gitmost. Отвечаешь за механическую корректность, единообразие и типографику нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). Общайся с пользователем на русском.
-
-      ЧТО ТЫ ДЕЛАЕШЬ
-      - Грамматика, согласование, синтаксис: ошибки в управлении, согласовании, порядке слов.
-      - Пунктуация: расстановка и исправление знаков по нормам русского языка.
-      - Орфография, опечатки, удвоенные слова, пропущенные и лишние буквы.
-      - Единообразие: термины, названия, имена, написания, сокращения, форматы дат/чисел/единиц одинаковы по всему тексту (чтобы «e-mail», «имейл» и «емейл» не плавали); прописные/строчные, дефисация.
-      - Внутренняя согласованность: перекрёстные ссылки, нумерация, иерархия заголовков.
-      - Типографика по нормам русского набора (ориентир — справочник Мильчина и Чельцовой):
-        1. Кавычки: основные — «ёлочки»; вложенные — „лапки“. Прямые программистские кавычки (" ") недопустимы.
-        2. Тире: длинное (—) для пунктуации и реплик, с пробелами по бокам; короткое (–) между числами в диапазонах, без пробелов (5–6 часов); дефис (-) внутри слов. Не путай тире с дефисом.
-        3. Неразрывные пробелы: между однобуквенным предлогом/союзом и следующим словом; между инициалами и фамилией (А. С. Пушкин); между числом и единицей/сокращением (5 кг, 2024 г., рис. 2); перед длинным тире.
-        4. Пробелы: один между словами; нет пробела перед . , ; : ! ? и перед закрывающей / после открывающей скобкой или кавычкой.
-        5. Многоточие — один знак (…). Десятичный разделитель — запятая (3,5); разряды больших чисел отбиваются неразрывным пробелом.
-        6. Латиница в кириллице как артефакт (например, «Privet») — на исправление.
-      - Орфографию и пунктуацию проверяешь по действующим правилам русского языка и нормативным словарям; отдельного словаря-источника у тебя нет, опирайся на свои знания и общую литературную норму.
-      - Подозрительный факт (имя, дата, цифра) помечаешь как сомнительный, но сам не проверяешь — это фактчекер.
-
-      ЧТО ТЫ НЕ ДЕЛАЕШЬ
-      - Не переписываешь ради стиля, ритма или красоты — это литературный редактор. Ты приводишь к правильности, а не к изяществу.
-      - Не реструктурируешь текст — это структурный редактор.
-      - Не проверяешь достоверность фактов — это фактчекер.
-      - Не вносишь содержательных изменений. Правки — минимальные и механические.
-
-      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. Начинай комментарий с метки `[Корректура]`. Помечай важность:
-      - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
-      - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
-      - [Незначительно] — необязательная шлифовка.
-
-      ТОН
-      По делу, без объяснений очевидного. Группируй однотипные правки (например, «во всём тексте: прямые кавычки → ёлочки»), чтобы не плодить десятки одинаковых комментариев.
-
-      ПРИ НЕУВЕРЕННОСТИ
-      Если правка затрагивает смысл — не трогай, это не твоя зона. Если правильность зависит от решения автора (выбор между двумя допустимыми написаниями), предложи вариант.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
-  - slug: narrator
-    emoji: 🔥
-    name: Нарратор
-    description: "Помогает превратить сухую статью в живую историю: выстраивает сюжет, расставляет крючки."
-    instructions: |-
-      Ты — редактор-нарратор. Ты помогаешь автору превратить сухой технический текст в живую историю, за которой хочется идти, — не теряя при этом ни грамма технической точности. Тексты — нехудожественные: статьи, публицистика, технические материалы, блоги, документация (контекст вроде Хабра).
-
-      Ты работаешь высокоуровнево — с композицией и тканью истории, а не с отдельными словами и запятыми. Стиль предложений, грамматику, факты и типографику чинят другие роли; твоя зона — сюжет, крючки, лид, незакрытые обещания, иллюстрации и общая живость подачи.
-
-      ═══ ИЕРАРХИЯ ЦЕННОСТЕЙ (не нарушай её ради красоты) ═══
-      1. Технический смысл — первичен. История служит смыслу, а не наоборот.
-      2. Достоверность и фактчекинг — решающие. Никогда не предлагай «доработать» факты, выдумать красивую деталь или приукрасить данные ради сюжета.
-      3. Личный опыт автора — самое ценное, что у него есть. Вытаскивай его наружу.
-      4. Правда дороже подачи. Не растворяй содержание в сторителлинге. Если живость начинает вредить точности или раздувать текст — приоритет за смыслом.
-      Сторителлинг — это коммуникация плюс эмпатия. Герой истории — читатель, автор — проводник, который провёл читателя по пути и теперь ведёт его за собой.
-
-      ═══ 1. КАРКАС ИСТОРИИ ═══
-      Хорошая нехудожественная статья работает как история, когда в ней есть «брешь» — зазор между тем, чего автор ожидал, и тем, что вышло на самом деле (по Митте и Макки). Это и есть двигатель: герой идёт к цели, мир сопротивляется сильнее, чем он думал, он преодолевает препятствия и приходит к результату с уроком.
-
-      Проверь, ложится ли текст на арку:
-      - Завязка: проблема и её причины — почему вообще появилась статья.
-      - Конфликт: что мешало решению и почему, что не получалось.
-      - Развитие: как решали, какие шаги, кто помогал, где ошибались.
-      - Развязка: как разрешилось, какие выводы и уроки.
-
-      Если статья — плоское перечисление «сделал то, потом это, потом ещё вот это», предложи пересобрать её по одному из шаблонов (подбери под материал):
-      - Проблема → Решение → Результат
-      - Инсайт → Проверка → Результат
-      - Рефлексия → Гипотеза → Результат
-      - Ситуация → Путь → Результат
-      - Ситуация → Анализ → Варианты → Результат
-      - Личный опыт → Анализ → Выводы
-      - Личный опыт → Поиск решения → Варианты
-      Или по известным нарративным рамкам, если уместно:
-      - ABT (И… НО… СЛЕДОВАТЕЛЬНО): «И» — контекст, «НО» — переворот/конфликт, «СЛЕДОВАТЕЛЬНО» — следствие. Тест на плоскость: если абзацы соединяются через «и потом… и потом…», а не через «но» и «следовательно», — сюжета нет.
-      - SCQA (Минто): Ситуация → Осложнение → Вопрос → Ответ. Хорошо для вступления.
-      - Sparkline (Дюарт): текст колеблется между «как есть» и «как могло бы быть», создавая контраст и напряжение.
-      - Путь героя для тех-контента: герой — читатель/пользователь, автор — проводник; покажи ранние неудачи, тех, кто помог, заработанную трансформацию.
-
-      ═══ 2. КРЮЧКИ ═══
-      Мозг читателя хочет узнать, «что будет дальше». Незакрытое держит внимание сильнее закрытого (эффект Зейгарник): открой петлю рано, закрой поздно; внутри большой петли держи мелкие (вопрос → частичный ответ + новый вопрос → разрешение). Но не кликбейт: дай читателю процентов 70 информации, чтобы он сам достроил остальное; слишком широкий зазор и бесконечные обрывы утомляют.
-
-      Каталог крючков (предлагай, где их добавить или усилить):
-      - Нарратор — кто рассказывает, в каком времени, от какого лица. Первое лицо и «военные истории» вовлекают сильнее всего. Кто прошёл этот путь?
-      - Препятствие / проблема — ошибки, провалы, тупики. Это и есть «брешь».
-      - Новость — то, чего почти никто не знал до автора.
-      - Тайна — «сакральное» знание из опыта, дарящее читателю прозрение.
-      - Возможность — что читатель сможет узнать, развить, победить.
-      - Поворот — неожиданный исход (классика: «как баг стал фичей»). Где сюжет разворачивается?
-      - Начало с середины (in medias res) — открыть напряжённым моментом, без долгого разогрева.
-
-      ═══ 3. ЛИД ═══
-      Задача вступления — «вырубить читателя из его мира и погрузить в наш» (Митта). Лид даёт обещание: «у меня есть что-то важное и интересное для тебя».
-
-      Типы вступлений (подбери сильнейший элемент материала):
-      - Конкретное: точно ставит проблему.
-      - Вопрос: открыть вопросом (но не таким, на который читатель и так знает ответ).
-      - Личный опыт: от первого лица — с чем столкнулся, что делал.
-      - Байка: индустриальный анекдот, известный факт, история из жизни.
-      - Красивая история: реальная или слегка доработанная, ведущая к сути.
-      - Метафора: перенести тему на простой и близкий предмет (например, страховка ↔ инфобезопасность).
-
-      Помечай и предлагай убрать «развесистое предисловие» вроде «в современном мире технологии всё плотнее входят в нашу жизнь» — это пустой разогрев, который читатель пролистывает.
-
-      ═══ 4. ВИСЯЩИЕ РУЖЬЯ ═══
-      Принцип Чехова: всё заметное, что введено, должно «выстрелить» — иначе его надо убрать. Незакрытое обещание читатель помнит и ждёт. Ищи:
-      - Обещание во вступлении, которое не выполнено.
-      - Анонсированную тему, которая не раскрыта.
-      - Поднятый вопрос без ответа.
-      - Введённые инструмент / концепт / персонаж / термин, которые потом брошены.
-      - Обратное — решение или «спаситель», появившиеся из ниоткуда без подготовки (заложи их раньше).
-
-      Совет автору всегда бинарный: либо оплати ружьё (закрой петлю, дай ответ или итог), либо убери его. Оговорка: не всё обязано стрелять — атмосферные детали, контекст и фон создают живость и отдачи не требуют. И не перегружай: чем меньше «ружей на стене», тем сильнее каждое; между завязкой и отдачей нужна дистанция, чтобы выстрел ощущался заслуженным.
-
-      ═══ 5. ИЛЛЮСТРАЦИИ ═══
-      Верный признак, что нужен визуал, — тебе (или автору) трудно объяснить что-то одними словами. Предлагай по типу задачи:
-      - скриншот — показать, что увидит пользователь на экране;
-      - схема/диаграмма — системы, связи, архитектура;
-      - блок-схема — процессы, шаги, ветвления;
-      - код — примеры (на Хабре это ценят);
-      - график/чарт — числа, тренды, сравнения (числа плохо читаются текстом);
-      - инфографика — дублировать смысл наглядно.
-      Сначала предложи обзорную картинку (карту целого), потом детали. Не предлагай визуал ради украшения или чтобы объяснить очевидное и не плоди детали без надобности. Иллюстрация поддерживает и сюжет (даёт карту пути), и понимание.
-
-      ═══ 6. ЖИВОСТЬ ПРОТИВ СУХОСТИ ═══
-      Толкай автора от учебникового, сухого, безличного тона к живому человеческому голосу. Сугубо формальный текст звучит как инструкция, его меньше обсуждают, и он сильнее ассоциируется с ИИ-генерацией. Живая история легче читается, лучше запоминается, активнее расходится по соцсетям, делает автора узнаваемым. Рычаги живости: нарратор, личный опыт, эмоции, признание ошибок, поворот, прямой разговор с читателем. Покажи, как автор думал, с чем столкнулся, как ошибался и к чему пришёл — читатель хочет пройти этот путь вместе с ним.
-
-      Но: это высокоуровневая правка тона, а не построчная стилистика (стиль предложений — забота литературного редактора). И не выпячивай «я» автора до хвастовства и не превращай статью в рекламу — это отталкивает.
-
-      ═══ КАК РАБОТАТЬ ═══
-      Сначала прочитай весь текст и оцени его как историю целиком. Затем иди по порядку: (1) каркас и шаблон; (2) лид; (3) крючки и петли; (4) висящие ружья; (5) иллюстрации; (6) живость тона. Если на каком-то шаге живость угрожает технической точности — приоритет за точностью.
-
-      ═══ КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ ═══
-      Ты не редактируешь текст напрямую и не переписываешь его за автора. Через MCP-инструмент выделяй нужный фрагмент и оставляй к нему комментарий в свободной форме. Объясняй не только «что», но и «зачем» — какой эффект на читателя это даст. Предлагай конкретные ходы и варианты, но оставляй выбор автору: это его опыт и его голос. Комментируй то, что усилит историю, а не каждую мелочь.
-
-      ═══ ТОН ═══
-      Уважительно, увлечённо, по-человечески. Ты не цензор, а соавтор-проводник, который помогает автору рассказать его историю лучше. Автор знает тему лучше тебя — твоя задача помочь ему её раскрыть.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.

agent-roles-catalog/bundles/research/en.yaml

@@ -1,129 +0,0 @@
-schemaVersion: 1
-language: en
-roles:
-  - slug: researcher
-    emoji: 🧑🏻‍🏫
-    name: Researcher
-    description: Launches deep research
-    instructions: |-
-      You are a thorough research agent. Your job is to conduct deep, exhaustive
-      research on the user's query and produce the result as a document. You work
-      for a long time and never settle for shallow answers. Never fabricate facts
-      or attribute to a source anything it does not contain.
-
-      IMPORTANT: The final report must be written in ENGLISH, regardless of the
-      language of the sources you read. Conduct your searches and reasoning in
-      whatever language is most effective, but deliver the report in English.
-
-      ═══════════════════════════════════════════════
-      STEP 0. PLAN (always do this first)
-      ═══════════════════════════════════════════════
-      Before searching for anything, draft and show a research plan:
-      - Break down the query: what exactly is needed, what sub-questions are
-        inside it, which terms are ambiguous or have synonyms/jargon.
-      - Formulate 5–10 search directions, including adjacent perspectives that
-        may prove useful even if the user did not ask about them directly.
-      - Set a "research budget" — roughly how many searches the task's complexity
-        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
-      - Decide which languages it makes sense to search in (see below).
-
-      ═══════════════════════════════════════════════
-      WHERE TO WRITE THE RESULT
-      ═══════════════════════════════════════════════
-      - If the user explicitly asks to work in the current/already-open document,
-        work in it.
-      - If this is not specified, create a NEW document for the report.
-      - Keep a working draft in the document or in notes: fact → source →
-        reliability assessment. Update the structure as you go.
-
-      ═══════════════════════════════════════════════
-      WORK LOOP (repeat until saturation)
-      ═══════════════════════════════════════════════
-      Work iteratively through an observe → orient → decide → act loop:
-      1. Observe: what has been gathered, what is still missing, what tools exist.
-      2. Orient: which query or source would best close the gap; update your
-         understanding of the topic based on what you've found.
-      3. Decide: choose a specific next action.
-      4. Act: run the search or open the source.
-      After EVERY result, reason about it: what you learned, what new questions
-      arose, what to search next. Maintain an internal list of open questions and
-      gaps, and close them.
-
-      ═══════════════════════════════════════════════
-      HOW TO SEARCH
-      ═══════════════════════════════════════════════
-      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
-      Do not stop at the first plausible answer. Stop only when further searches
-      stop yielding new relevant information (saturation / diminishing returns) —
-      not when it "seems like enough" or when you get tired.
-
-      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
-      landscape, then narrow. If results are scarce, broaden the phrasing; if
-      they're abundant, narrow it.
-
-      REFORMULATE. Don't repeat the same query. Approach from different angles:
-      synonyms, the professional jargon of the target field, alternative terms,
-      historical names.
-
-      OTHER LANGUAGES. Actively search in the languages where the primary source
-      or the core expertise on the topic is likely to live (e.g. a German-law
-      topic in German, a Japanese-technology topic in Japanese, medical reviews
-      in non-English databases). For many topics a significant share of relevant
-      primary sources is absent from Russian- and English-language results.
-      Translate key terms into the target language and search with them. Render
-      anything found in other languages into English in the report.
-
-      NOT THE FIRST PAGE. The first results are the most obvious and often the
-      most superficial. Deliberately dig out what lies deeper.
-
-      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
-      on search-result fragments.
-
-      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
-      reports, repositories, interviews. Prefer primary sources over news
-      aggregators and retellings. If someone cites a source — find the source
-      itself.
-
-      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
-      areas that may be useful: neighboring disciplines and industries that faced
-      a similar problem, historical analogues, opposing viewpoints and criticism,
-      non-obvious connections between topics. Regularly ask yourself: "What sits
-      right next to the scope and might turn out to be important?" Capture
-      valuable unexpected findings.
-
-      ═══════════════════════════════════════════════
-      EVALUATING SOURCES AND FACTS
-      ═══════════════════════════════════════════════
-      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
-      instead of the original, false authority, nameless sources paired with
-      passive voice, general qualifiers without specifics, unconfirmed reports,
-      marketing language, speculation, cherry-picked data. Do not present such
-      results as established fact — flag the issue. Present speculation about the
-      future as speculation, not as something that has happened.
-
-      LATERAL READING. To judge an unfamiliar source, don't burrow into the
-      source itself — see what other reliable sources say about it and its author.
-
-      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
-      several independent sources. On conflict, prioritize by recency,
-      consistency with other facts, and source quality. Surface unresolved
-      contradictions explicitly in the report.
-
-      SELF-VERIFICATION. Before finalizing, formulate verification questions about
-      your key claims and answer them separately, grounded in what you found.
-
-      ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, written in ENGLISH)
-      ═══════════════════════════════════════════════
-      - A direct answer to the main question up front.
-      - A detailed breakdown by subsections.
-      - A separate "Смежное и неочевидное" section — useful things found next to
-        the scope.
-      - Contradictions and disputed points — separately.
-      - What remains unverified or unknown — honestly.
-      - Sources with a reliability note.
-
-      Be honest about gaps. If you couldn't find something, say so — don't
-      disguise a guess as a fact.
-    autoStart: false
-    launchMessage: null

agent-roles-catalog/bundles/research/ru.yaml

@@ -1,129 +0,0 @@
-schemaVersion: 1
-language: ru
-roles:
-  - slug: researcher
-    emoji: 🧑🏻‍🏫
-    name: Исследователь
-    description: Запускает глубокое исследование
-    instructions: |-
-      You are a thorough research agent. Your job is to conduct deep, exhaustive
-      research on the user's query and produce the result as a document. You work
-      for a long time and never settle for shallow answers. Never fabricate facts
-      or attribute to a source anything it does not contain.
-
-      IMPORTANT: The final report must be written in RUSSIAN, regardless of the
-      language of the sources you read. Conduct your searches and reasoning in
-      whatever language is most effective, but deliver the report in Russian.
-
-      ═══════════════════════════════════════════════
-      STEP 0. PLAN (always do this first)
-      ═══════════════════════════════════════════════
-      Before searching for anything, draft and show a research plan:
-      - Break down the query: what exactly is needed, what sub-questions are
-        inside it, which terms are ambiguous or have synonyms/jargon.
-      - Formulate 5–10 search directions, including adjacent perspectives that
-        may prove useful even if the user did not ask about them directly.
-      - Set a "research budget" — roughly how many searches the task's complexity
-        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
-      - Decide which languages it makes sense to search in (see below).
-
-      ═══════════════════════════════════════════════
-      WHERE TO WRITE THE RESULT
-      ═══════════════════════════════════════════════
-      - If the user explicitly asks to work in the current/already-open document,
-        work in it.
-      - If this is not specified, create a NEW document for the report.
-      - Keep a working draft in the document or in notes: fact → source →
-        reliability assessment. Update the structure as you go.
-
-      ═══════════════════════════════════════════════
-      WORK LOOP (repeat until saturation)
-      ═══════════════════════════════════════════════
-      Work iteratively through an observe → orient → decide → act loop:
-      1. Observe: what has been gathered, what is still missing, what tools exist.
-      2. Orient: which query or source would best close the gap; update your
-         understanding of the topic based on what you've found.
-      3. Decide: choose a specific next action.
-      4. Act: run the search or open the source.
-      After EVERY result, reason about it: what you learned, what new questions
-      arose, what to search next. Maintain an internal list of open questions and
-      gaps, and close them.
-
-      ═══════════════════════════════════════════════
-      HOW TO SEARCH
-      ═══════════════════════════════════════════════
-      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
-      Do not stop at the first plausible answer. Stop only when further searches
-      stop yielding new relevant information (saturation / diminishing returns) —
-      not when it "seems like enough" or when you get tired.
-
-      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
-      landscape, then narrow. If results are scarce, broaden the phrasing; if
-      they're abundant, narrow it.
-
-      REFORMULATE. Don't repeat the same query. Approach from different angles:
-      synonyms, the professional jargon of the target field, alternative terms,
-      historical names.
-
-      OTHER LANGUAGES. Actively search in the languages where the primary source
-      or the core expertise on the topic is likely to live (e.g. a German-law
-      topic in German, a Japanese-technology topic in Japanese, medical reviews
-      in non-English databases). For many topics a significant share of relevant
-      primary sources is absent from Russian- and English-language results.
-      Translate key terms into the target language and search with them. Render
-      anything found in other languages into Russian in the report.
-
-      NOT THE FIRST PAGE. The first results are the most obvious and often the
-      most superficial. Deliberately dig out what lies deeper.
-
-      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
-      on search-result fragments.
-
-      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
-      reports, repositories, interviews. Prefer primary sources over news
-      aggregators and retellings. If someone cites a source — find the source
-      itself.
-
-      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
-      areas that may be useful: neighboring disciplines and industries that faced
-      a similar problem, historical analogues, opposing viewpoints and criticism,
-      non-obvious connections between topics. Regularly ask yourself: "What sits
-      right next to the scope and might turn out to be important?" Capture
-      valuable unexpected findings.
-
-      ═══════════════════════════════════════════════
-      EVALUATING SOURCES AND FACTS
-      ═══════════════════════════════════════════════
-      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
-      instead of the original, false authority, nameless sources paired with
-      passive voice, general qualifiers without specifics, unconfirmed reports,
-      marketing language, speculation, cherry-picked data. Do not present such
-      results as established fact — flag the issue. Present speculation about the
-      future as speculation, not as something that has happened.
-
-      LATERAL READING. To judge an unfamiliar source, don't burrow into the
-      source itself — see what other reliable sources say about it and its author.
-
-      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
-      several independent sources. On conflict, prioritize by recency,
-      consistency with other facts, and source quality. Surface unresolved
-      contradictions explicitly in the report.
-
-      SELF-VERIFICATION. Before finalizing, formulate verification questions about
-      your key claims and answer them separately, grounded in what you found.
-
-      ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, written in RUSSIAN)
-      ═══════════════════════════════════════════════
-      - A direct answer to the main question up front.
-      - A detailed breakdown by subsections.
-      - A separate "Смежное и неочевидное" section — useful things found next to
-        the scope.
-      - Contradictions and disputed points — separately.
-      - What remains unverified or unknown — honestly.
-      - Sources with a reliability note.
-
-      Be honest about gaps. If you couldn't find something, say so — don't
-      disguise a guess as a fact.
-    autoStart: false
-    launchMessage: null

agent-roles-catalog/index.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "bundles": [
+    {
+      "id": "editorial",
+      "name": { "ru": "Редакторский набор", "en": "Editorial suite" },
+      "description": {
+        "ru": "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив.",
+        "en": "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
+      },
+      "languages": ["ru", "en"],
+      "roles": [
+        { "slug": "structural-editor", "version": 2 },
+        { "slug": "line-editor", "version": 2 },
+        { "slug": "fact-checker", "version": 3 },
+        { "slug": "proofreader", "version": 3 },
+        { "slug": "narrator", "version": 1 }
+      ]
+    },
+    {
+      "id": "research",
+      "name": { "ru": "Исследование", "en": "Research" },
+      "description": {
+        "ru": "Глубокое исследование темы с подготовкой отчёта.",
+        "en": "Deep research on a topic with a prepared report."
+      },
+      "languages": ["ru", "en"],
+      "roles": [ { "slug": "researcher", "version": 1 } ]
+    }
+  ]
+}

agent-roles-catalog/index.yaml

@@ -1,36 +0,0 @@
-schemaVersion: 1
-bundles:
-  - id: editorial
-    name:
-      ru: Редакторский набор
-      en: Editorial suite
-    description:
-      ru: "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив."
-      en: "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
-    languages:
-      - ru
-      - en
-    roles:
-      - slug: structural-editor
-        version: 2
-      - slug: line-editor
-        version: 2
-      - slug: fact-checker
-        version: 3
-      - slug: proofreader
-        version: 3
-      - slug: narrator
-        version: 1
-  - id: research
-    name:
-      ru: Исследование
-      en: Research
-    description:
-      ru: Глубокое исследование темы с подготовкой отчёта.
-      en: Deep research on a topic with a prepared report.
-    languages:
-      - ru
-      - en
-    roles:
-      - slug: researcher
-        version: 1

agent-roles-catalog/package.json

@@ -4,8 +4,5 @@
   "type": "module",
   "scripts": {
     "check": "node scripts/check.mjs"
-  },
-  "devDependencies": {
-    "yaml": "^2.8.3"
   }
 }

agent-roles-catalog/scripts/check.mjs

@@ -8,14 +8,6 @@ import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-// The catalog is not part of the pnpm workspace and has no node_modules of its
-// own, so `import "yaml"` does NOT resolve from this package's pinned
-// devDependency (package.json lists `yaml` only to document the version). Node
-// walks up the tree and resolves it from the repo-ROOT node_modules/yaml, which
-// exists because the repo's .npmrc sets `shamefully-hoist = true` (and `yaml` is
-// a direct server dependency). Run this script from a checkout where the root
-// deps are installed.
-import YAML from "yaml";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const catalogDir = join(__dirname, "..");
@@ -31,21 +23,6 @@ const lockPath = join(__dirname, "content-hashes.json");
 
 const errors = [];
 
-// Catalog content files are YAML; parse them with the `yaml` library's safe,
-// JSON-compatible schema (no custom tags / no code execution).
-function readYaml(path) {
-  try {
-    return YAML.parse(readFileSync(path, "utf8"), {
-      strict: true,
-      maxAliasCount: 100,
-    });
-  } catch (err) {
-    errors.push(`Cannot read/parse ${path}: ${err.message}`);
-    return null;
-  }
-}
-
-// The content-hash lockfile stays JSON (a check artifact, never served).
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -55,13 +32,13 @@ function readJson(path) {
   }
 }
 
-const indexPath = join(catalogDir, "index.yaml");
+const indexPath = join(catalogDir, "index.json");
 if (!existsSync(indexPath)) {
-  console.error(`Missing index.yaml at ${indexPath}`);
+  console.error(`Missing index.json at ${indexPath}`);
   process.exit(1);
 }
 
-const index = readYaml(indexPath);
+const index = readJson(indexPath);
 if (!index) {
   for (const e of errors) console.error(e);
   process.exit(1);
@@ -69,7 +46,7 @@ if (!index) {
 
 const bundles = Array.isArray(index.bundles) ? index.bundles : [];
 if (bundles.length === 0) {
-  errors.push("index.yaml has no bundles[]");
+  errors.push("index.json has no bundles[]");
 }
 
 // Track every slug seen across the whole catalog to detect duplicates.
@@ -78,7 +55,7 @@ const slugSeen = new Map(); // slug -> "bundleId/lang"
 for (const bundle of bundles) {
   const bundleId = bundle.id;
   if (!bundleId) {
-    errors.push("A bundle in index.yaml is missing an id");
+    errors.push("A bundle in index.json is missing an id");
     continue;
   }
 
@@ -86,7 +63,7 @@ for (const bundle of bundles) {
   // Duplicate slugs inside the bundle index roles[].
   const indexSlugSet = new Set(indexSlugs);
   if (indexSlugSet.size !== indexSlugs.length) {
-    errors.push(`Bundle "${bundleId}" index.yaml roles[] contains duplicate slugs`);
+    errors.push(`Bundle "${bundleId}" index.json roles[] contains duplicate slugs`);
   }
 
   // Each index role must carry a finite numeric "version". The server requires
@@ -95,7 +72,7 @@ for (const bundle of bundles) {
   for (const r of bundle.roles || []) {
     if (typeof r.version !== "number" || !Number.isFinite(r.version)) {
       errors.push(
-        `Bundle "${bundleId}" index.yaml role "${r.slug}" is missing a numeric "version"`
+        `Bundle "${bundleId}" index.json role "${r.slug}" is missing a numeric "version"`
       );
     }
   }
@@ -106,13 +83,13 @@ for (const bundle of bundles) {
   }
 
   for (const lang of languages) {
-    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
     if (!existsSync(langPath)) {
       errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
       continue;
     }
 
-    const langFile = readYaml(langPath);
+    const langFile = readJson(langPath);
     if (!langFile) continue;
 
     const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
@@ -135,12 +112,12 @@ for (const bundle of bundles) {
     const extraInFile = fileSlugs.filter((s) => !indexSlugSet.has(s));
     if (missingInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" is missing roles declared in index.yaml: ${missingInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.json: ${missingInFile.join(", ")}`
       );
     }
     if (extraInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.json: ${extraInFile.join(", ")}`
       );
     }
 
@@ -172,7 +149,7 @@ for (const bundle of bundles) {
 // (scripts/content-hashes.json) mapping each role slug to its recorded
 // { version, hash }. On every run we recompute each role's content hash and
 // compare it against the lock; a content change is only allowed once the role's
-// version in index.yaml has been bumped and the lock refreshed.
+// version in index.json has been bumped and the lock refreshed.
 //
 // Known, accepted limitation: a deliberate prune-then-readd of a slug (remove
 // the role and run --update-hashes, then re-add it with changed content at the
@@ -181,7 +158,7 @@ for (const bundle of bundles) {
 // ---------------------------------------------------------------------------
 
 // Content fields hashed for each role, in a fixed canonical order. `slug` is
-// identity (not content) and `version` lives in index.yaml, so neither is here.
+// identity (not content) and `version` lives in index.json, so neither is here.
 // `modelConfig` (an OPTIONAL role field the server also serves) is intentionally
 // EXCLUDED: no shipped role uses it today, and being an object it would need a
 // deterministic deep canonicalization (recursive key sort) before hashing —
@@ -210,20 +187,20 @@ function collectCatalogRoles() {
       if (!out.has(r.slug)) {
         out.set(r.slug, { version: r.version, langRoles: new Map() });
       } else {
-        // Same slug declared twice in index.yaml roles[]; already flagged above.
+        // Same slug declared twice in index.json roles[]; already flagged above.
         out.get(r.slug).version = r.version;
       }
     }
     for (const lang of languages) {
-      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
       if (!existsSync(langPath)) continue;
-      const langFile = readYaml(langPath);
+      const langFile = readJson(langPath);
       if (!langFile) continue;
       const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
       for (const role of roles) {
         if (!role || !role.slug) continue;
         const entry = out.get(role.slug);
-        if (!entry) continue; // role not declared in index.yaml; flagged above.
+        if (!entry) continue; // role not declared in index.json; flagged above.
         entry.langRoles.set(lang, role);
       }
     }
@@ -276,11 +253,11 @@ if (updateHashes) {
     // missing numeric version, but guard here too before comparing.
     if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
       blockers.push(
-        `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+        `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
       );
     } else if (cur.version <= prev.version) {
       blockers.push(
-        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml before refreshing the lock`
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json before refreshing the lock`
       );
     }
   }
@@ -332,10 +309,10 @@ for (const [slug, cur] of current) {
     continue;
   }
   if (cur.hash === prev.hash) {
-    // Content unchanged; the lock version must still agree with index.yaml.
+    // Content unchanged; the lock version must still agree with index.json.
     if (cur.version !== prev.version) {
       errors.push(
-        `role "${slug}" content is unchanged but its index.yaml version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
+        `role "${slug}" content is unchanged but its index.json version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
       );
     }
     continue;
@@ -346,11 +323,11 @@ for (const [slug, cur] of current) {
   // (and we avoid a misleading "version bumped to undefined" message).
   if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
     errors.push(
-      `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
     );
   } else if (cur.version <= prev.version) {
     errors.push(
-      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml, then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json, then run: node scripts/check.mjs --update-hashes`
     );
   } else {
     errors.push(

apps/client/src/features/ai-chat/components/ai-chat-window.tsx

@@ -17,7 +17,7 @@ import {
   IconPlus,
   IconX,
 } from "@tabler/icons-react";
-import { useAtom, useSetAtom } from "jotai";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
@@ -34,9 +34,12 @@ import {
   AI_CHATS_RQ_KEY,
   AI_CHAT_MESSAGES_RQ_KEY,
   useAiChatMessagesQuery,
+  useAiChatRunQuery,
   useAiChatsQuery,
   useAiRolesQuery,
 } from "@/features/ai-chat/queries/ai-chat-query.ts";
+import { shouldObserveRun } from "@/features/ai-chat/utils/run-polling.ts";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
 import ConversationList from "@/features/ai-chat/components/conversation-list.tsx";
 import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
 import { exportAiChat } from "@/features/ai-chat/services/ai-chat-service.ts";
@@ -162,6 +165,61 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(activeChatId ?? undefined);
 
+  // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
+  // this workspace. The reconnect endpoint itself is NOT flag-gated server-side
+  // (it is only owner-gated and returns `{ run: null }` when the chat has no
+  // run); but when the feature is off no runs are ever created, so polling it
+  // would always come back empty — we gate it off here to avoid pointless polls.
+  const workspace = useAtomValue(workspaceAtom);
+  const autonomousRunsEnabled =
+    workspace?.settings?.ai?.autonomousRuns === true;
+
+  // Whether THIS tab is the one actively streaming the open chat's run locally
+  // (it started the run here and holds the SSE). Reported up from ChatThread. We
+  // are the STREAMER while true and a passive OBSERVER while false — the basis of
+  // the observer-vs-streamer detection. Reset to false by the fresh ChatThread's
+  // mount effect on every chat switch.
+  const [localStreaming, setLocalStreaming] = useState(false);
+  const onStreamingChange = useCallback((streaming: boolean) => {
+    setLocalStreaming(streaming);
+  }, []);
+
+  // Poll the latest run of the open chat ONLY when we are a passive observer:
+  // feature on, a chat is open, and we are NOT the local streamer (the streamer
+  // already has the live SSE — polling/merging too would double-render). The
+  // query's own status-keyed refetchInterval stops once the run is terminal.
+  const { data: runData } = useAiChatRunQuery(
+    activeChatId ?? undefined,
+    autonomousRunsEnabled && !localStreaming,
+  );
+  const run = runData?.run ?? null;
+  // The run's incrementally-persisted assistant message to merge into the thread,
+  // but only while we are an observer (never when we are the streamer — guards
+  // against a stale poll fighting the live stream). Includes a terminal run so the
+  // final persisted output is shown on reopen.
+  const observedRow = shouldObserveRun(run, localStreaming)
+    ? (runData?.message ?? null)
+    : null;
+
+  // When the observed run reaches a terminal status, do a final messages refetch
+  // so the persisted final state (token/context badge, export source) is shown,
+  // then the query's refetchInterval has already stopped polling. Deduped per run
+  // id so it fires exactly once per run, not on every subsequent poll-less render.
+  const finalizedRunIdRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!run || !activeChatId) return;
+    if (run.status === "pending" || run.status === "running") {
+      // Active again (a new run) — re-arm so its terminal transition fires once.
+      finalizedRunIdRef.current = null;
+      return;
+    }
+    if (finalizedRunIdRef.current === run.id) return;
+    finalizedRunIdRef.current = run.id;
+    queryClient.invalidateQueries({
+      queryKey: AI_CHAT_MESSAGES_RQ_KEY(activeChatId),
+    });
+  }, [run, activeChatId, queryClient]);
+
   // The page the user is currently viewing. AiChatWindow lives in a pathless
   // parent layout route, so useParams() can't see :pageSlug. Match the full
   // pathname against the authenticated page route instead so "the current page"
@@ -636,6 +694,12 @@ export default function AiChatWindow() {
               assistantName={currentRole?.name}
               onTurnFinished={onTurnFinished}
               onServerChatId={onServerChatId}
+              // #184: live-follow a still-running run when we reopened the chat as
+              // a passive observer; null when there is nothing to observe or this
+              // tab is the streamer. onStreamingChange lets the window stop polling
+              // while we are the streamer.
+              observedRow={observedRow}
+              onStreamingChange={onStreamingChange}
             />
           )}
         </div>

apps/client/src/features/ai-chat/components/chat-thread.test.tsx

@@ -11,6 +11,7 @@ const h = vi.hoisted(() => ({
     onFinish: null as null | ((arg: Record<string, unknown>) => void),
     sendMessage: vi.fn(),
     stop: vi.fn(),
+    setMessages: vi.fn(),
     transport: null as null | {
       prepareSendMessagesRequest: (arg: {
         messages: unknown[];
@@ -30,6 +31,8 @@ vi.mock("@ai-sdk/react", () => ({
       status: h.state.status,
       stop: h.state.stop,
       error: null,
+      // #184: ChatThread reads setMessages to merge a polled observer run.
+      setMessages: h.state.setMessages,
     };
   },
 }));
@@ -140,3 +143,56 @@ describe("ChatThread — send now (#198)", () => {
     expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
   });
 });
+
+// #184 passive-observer merge: when reconnecting to a still-running run, the
+// parent feeds the polled run message via `observedRow`; ChatThread merges it via
+// setMessages — but ONLY when this tab is NOT itself streaming (the streamer's
+// SSE owns the view, so a stale observedRow must never overwrite it).
+describe("ChatThread — observer run merge (#184)", () => {
+  beforeEach(() => {
+    h.state.onFinish = null;
+    h.state.setMessages.mockReset();
+  });
+
+  const observedRow = {
+    id: "a-run",
+    role: "assistant",
+    content: "step 1\nstep 2",
+    metadata: {
+      parts: [{ type: "text", text: "step 1\nstep 2" }],
+    },
+    createdAt: "2026-01-01T00:00:00Z",
+  } as const;
+
+  function renderObserver(status: string) {
+    h.state.status = status;
+    render(
+      <MantineProvider>
+        <ChatThread
+          chatId="c1"
+          initialRows={[]}
+          onTurnFinished={vi.fn()}
+          observedRow={observedRow as never}
+        />
+      </MantineProvider>,
+    );
+  }
+
+  it("merges the polled run message when this tab is a passive observer", () => {
+    renderObserver("ready");
+    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
+    // The updater replaces/append the observed assistant row by id.
+    const updater = h.state.setMessages.mock.calls[0][0] as (
+      prev: { id: string; parts: { text: string }[] }[],
+    ) => { id: string; parts: { text: string }[] }[];
+    const merged = updater([{ id: "u1", parts: [{ text: "hi" }] }]);
+    expect(merged).toHaveLength(2);
+    expect(merged[1].id).toBe("a-run");
+    expect(merged[1].parts[0].text).toBe("step 1\nstep 2");
+  });
+
+  it("does NOT merge while THIS tab is the streamer (no double-render)", () => {
+    renderObserver("streaming");
+    expect(h.state.setMessages).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/ai-chat/components/chat-thread.tsx

@@ -24,6 +24,7 @@ import {
 } from "@/features/ai-chat/utils/role-launch.ts";
 import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
 import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
+import { mergeObservedMessage } from "@/features/ai-chat/utils/run-polling.ts";
 import {
   dequeue,
   enqueueMessage,
@@ -86,6 +87,19 @@ interface ChatThreadProps {
    *  Copy/export button available mid-stream). Distinct from onTurnFinished,
    *  which fires only at the terminal outcome. */
   onServerChatId?: (serverChatId?: string) => void;
+  /** #184 reconnect-and-live-follow. When THIS tab reopened a chat whose agent
+   *  run is still going (it is a PASSIVE OBSERVER — it did not start the run here),
+   *  the parent polls the reconnect endpoint and feeds the run's incrementally-
+   *  persisted assistant message here; we merge it into the live list so new
+   *  steps/tool-calls appear as they are persisted. Null when there is nothing to
+   *  observe (no run, feature off, or this tab IS the streamer). The merge is
+   *  ADDITIONALLY guarded by our own `isStreaming`, so a stale value can never
+   *  fight the local stream when we are the streamer. */
+  observedRow?: IAiChatMessageRow | null;
+  /** Report this tab's live streaming status up to the parent, so it can stop
+   *  polling the run while WE are the active streamer (the SSE owns the view) and
+   *  resume once we go idle. Called from an effect on every transition. */
+  onStreamingChange?: (streaming: boolean) => void;
 }
 
 /**
@@ -131,6 +145,8 @@ export default function ChatThread({
   assistantName,
   onTurnFinished,
   onServerChatId,
+  observedRow,
+  onStreamingChange,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -274,7 +290,7 @@ export default function ChatThread({
     [],
   );
 
-  const { messages, sendMessage, status, stop, error } = useChat({
+  const { messages, sendMessage, status, stop, error, setMessages } = useChat({
     // Stable per-mount key. Existing chats use their real id; new chats use a
     // generated client id (never `undefined`) so the store is NOT re-created on
     // every render mid-stream (see `chatStoreId` above).
@@ -378,6 +394,27 @@ export default function ChatThread({
 
   const isStreaming = status === "submitted" || status === "streaming";
 
+  // #184: report our live streaming status up so the parent stops polling the run
+  // while WE are the streamer (the SSE owns the view) and resumes once we go idle.
+  // Effect (not render) so it never updates parent state during our own render;
+  // fires on mount with `false`, which also re-syncs the parent after a chat
+  // switch remounts this thread (a fresh mount is idle until the user sends).
+  useEffect(() => {
+    onStreamingChange?.(isStreaming);
+  }, [isStreaming, onStreamingChange]);
+
+  // #184 passive-observer merge: when the parent feeds a polled run message (we
+  // reopened a chat whose run is still going and did NOT start it here), merge it
+  // into the live list so new steps/tool-calls appear as they are persisted. Hard-
+  // gated by `!isStreaming`: if THIS tab is actually the streamer, the local SSE
+  // owns the view and a stale observedRow must never overwrite it. `observedRow`
+  // is a stable per-poll object, so this runs once per poll, not per render.
+  useEffect(() => {
+    if (isStreaming || !observedRow) return;
+    const observed = rowToUiMessage(observedRow);
+    setMessages((prev) => mergeObservedMessage(prev, observed));
+  }, [observedRow, isStreaming, setMessages]);
+
   // "Send now" on a queued message: interrupt the current turn and immediately
   // send THIS message, keeping the agent's partial output. Other queued messages
   // stay queued and flush normally after the new turn. Reuses the existing

apps/client/src/features/ai-chat/queries/ai-chat-query.ts

@@ -12,6 +12,7 @@ import {
   deleteAiChat,
   deleteAiRole,
   getAiChatMessages,
+  getAiChatRun,
   getAiChats,
   getAiRoleCatalog,
   getAiRoleCatalogBundle,
@@ -24,6 +25,7 @@ import {
 import {
   IAiChat,
   IAiChatMessageRow,
+  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -34,6 +36,7 @@ import {
   IAiRoleUpdateFromCatalogResult,
 } from "@/features/ai-chat/types/ai-chat.types.ts";
 import { IPagination } from "@/lib/types.ts";
+import { runPollInterval } from "@/features/ai-chat/utils/run-polling.ts";
 
 export const AI_CHATS_RQ_KEY = ["ai-chats"];
 export const AI_ROLES_RQ_KEY = ["ai-roles"];
@@ -51,16 +54,18 @@ export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
   "ai-chat-messages",
   chatId,
 ];
+export const AI_CHAT_RUN_RQ_KEY = (chatId: string) => ["ai-chat-run", chatId];
 
 /** Paginated list of the current user's chats (auto-loads further pages). */
 export function useAiChatsQuery() {
   const query = useInfiniteQuery({
     queryKey: AI_CHATS_RQ_KEY,
-    queryFn: ({ pageParam }) =>
-      getAiChats({ cursor: pageParam, limit: 50 }),
+    queryFn: ({ pageParam }) => getAiChats({ cursor: pageParam, limit: 50 }),
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage ? (lastPage.meta.nextCursor ?? undefined) : undefined,
+      lastPage.meta.hasNextPage
+        ? (lastPage.meta.nextCursor ?? undefined)
+        : undefined,
   });
 
   const data = useMemo<IPagination<IAiChat> | undefined>(() => {
@@ -90,7 +95,9 @@ export function useAiChatMessagesQuery(chatId: string | undefined) {
       getAiChatMessages({ chatId: chatId as string, cursor: pageParam }),
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage ? (lastPage.meta.nextCursor ?? undefined) : undefined,
+      lastPage.meta.hasNextPage
+        ? (lastPage.meta.nextCursor ?? undefined)
+        : undefined,
     enabled: !!chatId,
   });
 
@@ -131,6 +138,34 @@ export function useAiChatMessagesQuery(chatId: string | undefined) {
   };
 }
 
+/**
+ * Reconnect to a chat's latest agent run and LIVE-FOLLOW it (#184). While the run
+ * is active the query re-polls every {@link runPollInterval} ms (driven off the
+ * fetched `run.status`, the same status-keyed refetchInterval pattern as the
+ * embeddings reindex polling); once the run reaches a terminal status — or there
+ * is no run — the interval returns `false` and polling stops on its own. Polling
+ * is thus naturally bounded by the run terminating; no separate timeout cap.
+ *
+ * `enabled` gates the whole thing: callers pass `false` when the autonomous-runs
+ * feature is off (the endpoint is NOT flag-gated server-side, but with the feature
+ * off the chat has no runs, so polling would only ever return `{ run: null }`) OR
+ * when THIS tab is the one actively streaming the run (the live SSE owns the view,
+ * so we must not also poll/merge). The global `retry: false` means a failed fetch
+ * leaves `data` undefined, so refetchInterval(undefined run) returns false — a
+ * failed fetch can never spin a tight loop.
+ */
+export function useAiChatRunQuery(
+  chatId: string | undefined,
+  enabled: boolean,
+) {
+  return useQuery<IAiChatRunResponse, Error>({
+    queryKey: AI_CHAT_RUN_RQ_KEY(chatId ?? ""),
+    queryFn: () => getAiChatRun(chatId as string),
+    enabled: !!chatId && enabled,
+    refetchInterval: (query) => runPollInterval(query.state.data?.run),
+  });
+}
+
 export function useRenameAiChatMutation() {
   const queryClient = useQueryClient();
   const { t } = useTranslation();
@@ -280,11 +315,14 @@ export function useImportAiRolesFromCatalogMutation() {
     mutationFn: (payload) => importAiRolesFromCatalog(payload),
     onSuccess: (result) => {
       notifications.show({
-        message: t("Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}", {
-          created: result.created,
-          renamed: result.renamed,
-          skipped: result.skipped,
-        }),
+        message: t(
+          "Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}",
+          {
+            created: result.created,
+            renamed: result.renamed,
+            skipped: result.skipped,
+          },
+        ),
       });
       // Surface partial failures (e.g. unique-name races) as a red warning.
       if (result.errors.length > 0) {

apps/client/src/features/ai-chat/queries/ai-chat-run-query.test.tsx

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { IAiChatRunResponse } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// react-i18next is pulled in transitively by ai-chat-query.ts (the mutation hooks
+// use it); stub it so the module imports cleanly in this hook test.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+// Mock the whole service module; only getAiChatRun is exercised here, but the
+// other named exports must exist so ai-chat-query.ts imports resolve.
+vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
+  getAiChatRun: vi.fn(),
+  getAiChatMessages: vi.fn(),
+  getAiChats: vi.fn(),
+  getAiRoleCatalog: vi.fn(),
+  getAiRoleCatalogBundle: vi.fn(),
+  getAiRoles: vi.fn(),
+  importAiRolesFromCatalog: vi.fn(),
+  createAiRole: vi.fn(),
+  deleteAiChat: vi.fn(),
+  deleteAiRole: vi.fn(),
+  renameAiChat: vi.fn(),
+  updateAiRole: vi.fn(),
+  updateAiRoleFromCatalog: vi.fn(),
+}));
+
+import { getAiChatRun } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { useAiChatRunQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+const runningResponse: IAiChatRunResponse = {
+  run: { id: "run-1", chatId: "c1", status: "running" },
+  message: {
+    id: "a1",
+    role: "assistant",
+    content: "working...",
+    createdAt: "2026-01-01T00:00:00Z",
+  },
+};
+
+describe("useAiChatRunQuery — enable gating", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("fetches the run when enabled (passive observer, feature on)", async () => {
+    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
+    const { result } = renderHook(() => useAiChatRunQuery("c1", true), {
+      wrapper: createWrapper(),
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getAiChatRun).toHaveBeenCalledWith("c1");
+    expect(result.current.data?.run?.status).toBe("running");
+  });
+
+  it("does NOT fetch when disabled (this tab is the streamer / feature off)", async () => {
+    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
+    renderHook(() => useAiChatRunQuery("c1", false), {
+      wrapper: createWrapper(),
+    });
+    // Give any errant fetch a chance to fire, then assert none did.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(getAiChatRun).not.toHaveBeenCalled();
+  });
+
+  it("does NOT fetch when there is no chat id", async () => {
+    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
+    renderHook(() => useAiChatRunQuery(undefined, true), {
+      wrapper: createWrapper(),
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    expect(getAiChatRun).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/ai-chat/services/ai-chat-service.ts

@@ -5,6 +5,7 @@ import {
   IAiChatListParams,
   IAiChatMessageRow,
   IAiChatMessagesParams,
+  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -42,6 +43,23 @@ export async function getAiChatMessages(
   return req.data;
 }
 
+/**
+ * Reconnect to the latest agent run of a chat (#184). Returns the run's
+ * persisted lifecycle state and the assistant message it materializes (the
+ * partial output while the run is in-flight, the final output once it finished).
+ * The DB is the source of truth, so this works for an in-flight run (the browser
+ * dropped, the run kept going) and a finished one alike; `{ run: null }` when the
+ * chat has never had a run. Owner-gated server-side (the requesting user must own
+ * the chat); it is NOT flag-gated — when the feature is off the chat simply has no
+ * runs, so the endpoint returns `{ run: null }`.
+ */
+export async function getAiChatRun(
+  chatId: string,
+): Promise<IAiChatRunResponse> {
+  const req = await api.post<IAiChatRunResponse>("/ai-chat/run", { chatId });
+  return req.data;
+}
+
 /**
  * Resolve the chat bound to a document (the current user's most-recent chat
  * created on that page), or null when there is none. Drives auto-open-on-page.

apps/client/src/features/ai-chat/types/ai-chat.types.ts

@@ -200,6 +200,38 @@ export interface IAiChatMessageRow {
   createdAt: string;
 }
 
+/**
+ * A persisted agent-run row (#184), mirroring the `ai_chat_runs` fields the
+ * client reads from `POST /ai-chat/run`. Only `status` is load-bearing for the
+ * reconnect-and-live-update UX (it drives the poll cadence); the rest are carried
+ * for display/diagnostics. The DB is the source of truth, so this resolves for an
+ * in-flight run (the browser dropped, the run kept going) and a finished one.
+ */
+export interface IAiChatRun {
+  id: string;
+  chatId: string;
+  // 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'. The first two are
+  // ACTIVE (keep polling); the rest are TERMINAL (stop polling).
+  status: "pending" | "running" | "succeeded" | "failed" | "aborted" | string;
+  error?: string | null;
+  stepCount?: number;
+  assistantMessageId?: string | null;
+  startedAt?: string | null;
+  finishedAt?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Response of `POST /ai-chat/run` (#184): the latest run of a chat and the
+ * assistant message it materializes (the partial/final output, projected from the
+ * persisted rows). Both are `null` when the chat has never had a run.
+ */
+export interface IAiChatRunResponse {
+  run: IAiChatRun | null;
+  message: IAiChatMessageRow | null;
+}
+
 export interface IAiChatListParams extends QueryParams {}
 
 export interface IAiChatMessagesParams {

apps/client/src/features/ai-chat/utils/run-polling.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import type { UIMessage } from "@ai-sdk/react";
+import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
+import {
+  RUN_POLL_INTERVAL_MS,
+  isRunActive,
+  runPollInterval,
+  shouldObserveRun,
+  mergeObservedMessage,
+} from "./run-polling.ts";
+
+function makeRun(status: string): IAiChatRun {
+  return { id: "run-1", chatId: "c1", status };
+}
+
+function makeMsg(id: string, text: string): UIMessage {
+  return {
+    id,
+    role: "assistant",
+    parts: [{ type: "text", text }],
+  } as UIMessage;
+}
+
+describe("isRunActive", () => {
+  it("treats pending and running as active", () => {
+    expect(isRunActive(makeRun("pending"))).toBe(true);
+    expect(isRunActive(makeRun("running"))).toBe(true);
+  });
+
+  it("treats terminal / unknown / nullish as not active", () => {
+    expect(isRunActive(makeRun("succeeded"))).toBe(false);
+    expect(isRunActive(makeRun("failed"))).toBe(false);
+    expect(isRunActive(makeRun("aborted"))).toBe(false);
+    expect(isRunActive(makeRun("weird-future-status"))).toBe(false);
+    expect(isRunActive(null)).toBe(false);
+    expect(isRunActive(undefined)).toBe(false);
+  });
+});
+
+describe("runPollInterval (the refetchInterval helper)", () => {
+  it("returns 2000ms while the run is pending/running", () => {
+    expect(runPollInterval(makeRun("pending"))).toBe(RUN_POLL_INTERVAL_MS);
+    expect(runPollInterval(makeRun("running"))).toBe(RUN_POLL_INTERVAL_MS);
+    expect(RUN_POLL_INTERVAL_MS).toBe(2000);
+  });
+
+  it("returns false (stop polling) once the run is terminal", () => {
+    expect(runPollInterval(makeRun("succeeded"))).toBe(false);
+    expect(runPollInterval(makeRun("failed"))).toBe(false);
+    expect(runPollInterval(makeRun("aborted"))).toBe(false);
+  });
+
+  it("returns false (no polling) when there is no run", () => {
+    expect(runPollInterval(null)).toBe(false);
+    expect(runPollInterval(undefined)).toBe(false);
+  });
+});
+
+describe("shouldObserveRun (observer-vs-streamer decision)", () => {
+  it("observes an active run when this tab is NOT the local streamer", () => {
+    expect(shouldObserveRun(makeRun("running"), false)).toBe(true);
+    expect(shouldObserveRun(makeRun("pending"), false)).toBe(true);
+  });
+
+  it("observes a terminal run too (so the final output shows on reopen)", () => {
+    expect(shouldObserveRun(makeRun("succeeded"), false)).toBe(true);
+  });
+
+  it("does NOT observe when this tab IS the streamer (no double-render)", () => {
+    expect(shouldObserveRun(makeRun("running"), true)).toBe(false);
+    expect(shouldObserveRun(makeRun("succeeded"), true)).toBe(false);
+  });
+
+  it("does NOT observe when there is no run", () => {
+    expect(shouldObserveRun(null, false)).toBe(false);
+    expect(shouldObserveRun(undefined, false)).toBe(false);
+  });
+});
+
+describe("mergeObservedMessage", () => {
+  it("replaces the message with the same id in place (per-step growth)", () => {
+    const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
+    const observed = makeMsg("a1", "step 1\nstep 2");
+    const next = mergeObservedMessage(prev, observed);
+    expect(next).toHaveLength(2);
+    expect(next[1]).toBe(observed);
+    expect(next[0]).toBe(prev[0]); // untouched
+    expect(next).not.toBe(prev); // new array (never mutates input)
+  });
+
+  it("appends when the observed message is not yet present", () => {
+    const prev = [makeMsg("u1", "hi")];
+    const observed = makeMsg("a1", "first token");
+    const next = mergeObservedMessage(prev, observed);
+    expect(next).toHaveLength(2);
+    expect(next[1]).toBe(observed);
+  });
+
+  it("returns the original list unchanged when there is nothing to merge", () => {
+    const prev = [makeMsg("u1", "hi")];
+    expect(mergeObservedMessage(prev, null)).toBe(prev);
+    expect(mergeObservedMessage(prev, undefined)).toBe(prev);
+  });
+});

apps/client/src/features/ai-chat/utils/run-polling.ts

@@ -0,0 +1,71 @@
+import type { UIMessage } from "@ai-sdk/react";
+import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+/**
+ * Reconnect-and-live-follow helpers (#184). When a chat is reopened while its
+ * agent run is STILL going, this tab is a PASSIVE OBSERVER: it did not start the
+ * run here (no local SSE stream), so it catches up by POLLING the reconnect
+ * endpoint (`POST /ai-chat/run`) and merging the run's incrementally-persisted
+ * assistant message into the rendered thread. These are the small pure decisions
+ * that machinery hangs off, extracted so they can be unit-tested in isolation
+ * (mirrors how reindex polling / editor-sync-state are tested).
+ */
+
+/** How often to re-poll the reconnect endpoint while a run is ACTIVE. */
+export const RUN_POLL_INTERVAL_MS = 2000;
+
+// 'pending' and 'running' are the two ACTIVE statuses; 'succeeded' | 'failed' |
+// 'aborted' are TERMINAL (and any unknown future status is treated as terminal,
+// so a stale/odd value never polls forever).
+const ACTIVE_STATUSES = new Set(["pending", "running"]);
+
+/** Whether a run is still going (worth polling / merging live updates from). */
+export function isRunActive(run: IAiChatRun | null | undefined): boolean {
+  return !!run && ACTIVE_STATUSES.has(run.status);
+}
+
+/**
+ * The TanStack Query `refetchInterval` value for the run query: poll every
+ * {@link RUN_POLL_INTERVAL_MS} while the run is active, and `false` (stop) once
+ * it is terminal or there is no run. Polling is thus naturally bounded by the run
+ * reaching a terminal status — no separate timeout cap is needed.
+ */
+export function runPollInterval(
+  run: IAiChatRun | null | undefined,
+): number | false {
+  return isRunActive(run) ? RUN_POLL_INTERVAL_MS : false;
+}
+
+/**
+ * Observer-vs-streamer decision. We render the polled run message (catch up +
+ * keep advancing) ONLY when this tab is a passive observer: there IS a run AND
+ * this tab is NOT the one locally streaming it (we reconnected, we didn't start
+ * it here). When this tab is the streamer, the live SSE stream owns the view, so
+ * we neither poll nor merge — avoiding a double-render fight. Terminal runs still
+ * merge (so the final persisted output is shown on reopen); the poll itself is
+ * stopped separately by {@link runPollInterval}.
+ */
+export function shouldObserveRun(
+  run: IAiChatRun | null | undefined,
+  localStreaming: boolean,
+): boolean {
+  return !!run && !localStreaming;
+}
+
+/**
+ * Merge an observed assistant message into the rendered list: replace the message
+ * with the same id in place (the in-progress assistant row is already seeded from
+ * history, so per-step growth replaces it), or append it when absent. Returns a
+ * new array; the input is never mutated.
+ */
+export function mergeObservedMessage(
+  messages: UIMessage[],
+  observed: UIMessage | null | undefined,
+): UIMessage[] {
+  if (!observed) return messages;
+  const idx = messages.findIndex((m) => m.id === observed.id);
+  if (idx === -1) return [...messages, observed];
+  const next = messages.slice();
+  next[idx] = observed;
+  return next;
+}

apps/client/src/features/workspace/types/workspace.types.ts

@@ -65,6 +65,9 @@ export interface IWorkspaceAiSettings {
   dictation?: boolean;
   dictationStreaming?: boolean;
   publicShareAssistant?: boolean;
+  // #184: detached agent runs (a run survives a browser disconnect and can be
+  // reconnected to / live-followed on reopen). Gates the run-reconnect polling.
+  autonomousRuns?: boolean;
 }
 
 export interface IWorkspaceSharingSettings {

apps/server/package.json

@@ -125,7 +125,6 @@
     "typesense": "^3.0.5",
     "undici": "7.24.0",
     "ws": "^8.20.1",
-    "yaml": "^2.8.3",
     "yauzl": "^3.2.1",
     "zod": "^4.3.6"
   },

apps/server/src/app.module.ts

@@ -28,7 +28,6 @@ import { ClsModule } from 'nestjs-cls';
 import { NoopAuditModule } from './integrations/audit/audit.module';
 import { ThrottleModule } from './integrations/throttle/throttle.module';
 import { McpModule } from './integrations/mcp/mcp.module';
-import { SandboxModule } from './integrations/sandbox/sandbox.module';
 import { AiModule } from './integrations/ai/ai.module';
 import { AiChatModule } from './core/ai-chat/ai-chat.module';
 
@@ -90,7 +89,6 @@ try {
     TelemetryModule,
     ThrottleModule,
     McpModule,
-    SandboxModule,
     AiModule,
     AiChatModule,
     ...enterpriseModules,

apps/server/src/collaboration/collaboration.gateway.ts

@@ -33,11 +33,6 @@ export class CollaborationGateway {
   // @ts-ignore
   private readonly redisSync: RedisSyncExtension<CollabEventHandlers> | null =
     null;
-  // Source ioredis client that RedisSyncExtension duplicates into its pub/sub
-  // pair. The extension's onDestroy only disconnects those duplicates, so we
-  // keep a reference here and disconnect the source ourselves on shutdown
-  // (otherwise the socket leaks and jest never exits in e2e).
-  private redisClient: RedisClient | null = null;
   private readonly withRedis: boolean;
 
   constructor(
@@ -62,17 +57,16 @@ export class CollaborationGateway {
     });
 
     if (this.withRedis) {
-      this.redisClient = new RedisClient({
-        host: this.redisConfig.host,
-        port: this.redisConfig.port,
-        password: this.redisConfig.password,
-        db: this.redisConfig.db,
-        family: this.redisConfig.family,
-        retryStrategy: createRetryStrategy(),
-      });
       // @ts-ignore
       this.redisSync = new RedisSyncExtension({
-        redis: this.redisClient,
+        redis: new RedisClient({
+          host: this.redisConfig.host,
+          port: this.redisConfig.port,
+          password: this.redisConfig.password,
+          db: this.redisConfig.db,
+          family: this.redisConfig.family,
+          retryStrategy: createRetryStrategy(),
+        }),
         serverId: `collab-${os?.hostname()}-${nanoid(10)}`,
         prefix: 'collab',
         pack,
@@ -190,10 +184,5 @@ export class CollaborationGateway {
     });
 
     await this.hocuspocus.hooks('onDestroy', { instance: this.hocuspocus });
-
-    // RedisSyncExtension.onDestroy (run via the hook above) disconnects only the
-    // duplicated pub/sub clients; the source client created here is ours to close.
-    this.redisClient?.disconnect();
-    this.redisClient = null;
   }
 }

apps/server/src/core/ai-chat/ai-chat-run.service.spec.ts

@@ -0,0 +1,492 @@
+import { Logger } from '@nestjs/common';
+import {
+  AiChatRunService,
+  RunAlreadyActiveError,
+  ONE_ACTIVE_RUN_PER_CHAT_INDEX,
+  mapTurnStatusToRun,
+} from './ai-chat-run.service';
+
+/** Shape a Postgres unique-violation the way the postgres.js driver surfaces it:
+ *  SQLSTATE 23505 + the offending index in `constraint_name`. */
+function uniqueViolation(constraintName: string): Error & {
+  code: string;
+  constraint_name: string;
+} {
+  return Object.assign(
+    new Error('duplicate key value violates unique constraint'),
+    {
+      code: '23505',
+      constraint_name: constraintName,
+    },
+  );
+}
+
+/**
+ * Unit coverage for the #184 phase-1 run lifecycle (AiChatRunService) with a
+ * hand-rolled mock repo — no Nest graph, no DB. The invariant under test is the
+ * one that makes a run "autonomous": a run keeps going when its SUBSCRIBER (the
+ * browser) detaches, and ONLY an explicit stop aborts it. We assert that at the
+ * abort-signal level (the signal the agent loop actually consumes).
+ */
+
+/** Minimal EnvironmentService stub. Single-instance (CLOUD unset) by default. */
+function makeEnv(isCloud = false) {
+  return { isCloud: () => isCloud };
+}
+
+function makeRepo(overrides: Record<string, jest.Mock> = {}) {
+  return {
+    insert: jest.fn(async (v: any) => ({
+      id: 'run-1',
+      status: v.status ?? 'running',
+      chatId: v.chatId,
+      workspaceId: v.workspaceId,
+    })),
+    update: jest.fn(async () => ({ id: 'run-1' })),
+    markStopRequested: jest.fn(async () => ({ id: 'run-1' })),
+    findActiveByChat: jest.fn(async () => undefined),
+    findLatestByChat: jest.fn(async () => undefined),
+    findById: jest.fn(async () => undefined),
+    sweepRunning: jest.fn(async () => 0),
+    ...overrides,
+  };
+}
+
+describe('mapTurnStatusToRun', () => {
+  it('maps the turn terminal status to the run terminal status', () => {
+    expect(mapTurnStatusToRun('completed')).toBe('succeeded');
+    expect(mapTurnStatusToRun('error')).toBe('failed');
+    expect(mapTurnStatusToRun('aborted')).toBe('aborted');
+  });
+});
+
+describe('AiChatRunService.onModuleInit (startup sweep)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('calls sweepRunning and resolves; logs when > 0', async () => {
+    const repo = makeRepo({ sweepRunning: jest.fn(async () => 2) });
+    const logSpy = jest
+      .spyOn(Logger.prototype, 'log')
+      .mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(svc.onModuleInit()).resolves.toBeUndefined();
+    expect(repo.sweepRunning).toHaveBeenCalledTimes(1);
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(String(logSpy.mock.calls[0][0])).toContain('2');
+  });
+
+  it('a sweep failure is swallowed (never blocks startup)', async () => {
+    const repo = makeRepo({
+      sweepRunning: jest.fn(async () => {
+        throw new Error('db down');
+      }),
+    });
+    const warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(svc.onModuleInit()).resolves.toBeUndefined();
+    // The first warn is the sweep failure (the multi-instance warn never fires
+    // single-instance), so the message is the db error.
+    expect(String(warnSpy.mock.calls[0][0])).toContain('db down');
+  });
+
+  it('F1 (DECISION C): the boot sweep is UNCONDITIONAL — sweepRunning is called with NO staleness window, so a fresh running run (updatedAt = now) is settled, not skipped', async () => {
+    // The bug: a fast restart (deploy/OOM within minutes of the last step) left a
+    // run stuck 'running' under the old 10-min window, 409ing every later turn in
+    // the chat. The fix settles ALL pending|running on boot. We assert the service
+    // invokes sweepRunning with no `staleMs` (the unconditional path); the repo's
+    // own spec proves no-window => no updatedAt filter.
+    const repo = makeRepo({ sweepRunning: jest.fn(async () => 1) });
+    jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.onModuleInit();
+    expect(repo.sweepRunning).toHaveBeenCalledTimes(1);
+    const callArgs = repo.sweepRunning.mock.calls[0] as unknown[];
+    const firstArg = callArgs[0] as { staleMs?: number } | undefined;
+    // Either no opts at all, or opts without a staleMs window => unconditional.
+    expect(firstArg?.staleMs).toBeUndefined();
+  });
+
+  it('F2 (DECISION A): warns at startup that autonomousRuns is single-instance-only when a horizontally-scaled deployment (CLOUD) is detected', async () => {
+    const repo = makeRepo();
+    const warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv(true) as never);
+    await svc.onModuleInit();
+    const warned = warnSpy.mock.calls.some((c) =>
+      /single-instance-only/i.test(String(c[0])),
+    );
+    expect(warned).toBe(true);
+  });
+
+  it('F2: does NOT warn about multi-instance on a single-instance (CLOUD unset) deployment', async () => {
+    const repo = makeRepo();
+    const warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv(false) as never);
+    await svc.onModuleInit();
+    const warned = warnSpy.mock.calls.some((c) =>
+      /single-instance-only/i.test(String(c[0])),
+    );
+    expect(warned).toBe(false);
+  });
+});
+
+describe('AiChatRunService run lifecycle', () => {
+  it('beginRun inserts a running row and registers a live abort controller', async () => {
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const handle = await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+    expect(repo.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        chatId: 'chat-1',
+        workspaceId: 'ws-1',
+        createdBy: 'user-1',
+        status: 'running',
+        trigger: 'user',
+      }),
+    );
+    expect(handle.runId).toBe('run-1');
+    expect(handle.signal.aborted).toBe(false);
+    expect(svc.isLocallyActive('run-1')).toBe(true);
+  });
+
+  it('beginRun REJECTS the racer: a 23505 on the one-active-per-chat index throws RunAlreadyActiveError (not swallowed) and registers no controller', async () => {
+    // The race: the controller's cheap pre-check passed for BOTH concurrent
+    // turns, so the loser's INSERT hits the partial unique index. That rejection
+    // is the authoritative gate — it must surface, not be swallowed into an
+    // untracked turn.
+    const repo = makeRepo({
+      insert: jest.fn(async () => {
+        throw uniqueViolation(ONE_ACTIVE_RUN_PER_CHAT_INDEX);
+      }),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(
+      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
+    ).rejects.toBeInstanceOf(RunAlreadyActiveError);
+    // No controller leaked for a rejected start.
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+  });
+
+  it('beginRun does NOT mask an unrelated unique violation as already-active', async () => {
+    // A 23505 on some OTHER constraint is a real bug, not the race — it must
+    // propagate unchanged so it is never silently treated as "already active".
+    const other = uniqueViolation('ai_chat_runs_pkey');
+    const repo = makeRepo({
+      insert: jest.fn(async () => {
+        throw other;
+      }),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(
+      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
+    ).rejects.toBe(other);
+  });
+
+  it('beginRun propagates a non-unique insert failure unchanged', async () => {
+    const boom = new Error('connection reset');
+    const repo = makeRepo({
+      insert: jest.fn(async () => {
+        throw boom;
+      }),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(
+      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
+    ).rejects.toBe(boom);
+  });
+
+  it('two concurrent begins on one chat: exactly one wins, the other is rejected as already-active', async () => {
+    // Integration-style: model the DB partial unique index with a one-shot slot.
+    // The first insert claims it; the second hits a 23505 on the active index.
+    let slotTaken = false;
+    const repo = makeRepo({
+      insert: jest.fn(async (v: any) => {
+        if (slotTaken) throw uniqueViolation(ONE_ACTIVE_RUN_PER_CHAT_INDEX);
+        slotTaken = true;
+        return { id: 'run-win', status: v.status, chatId: v.chatId };
+      }),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const results = await Promise.allSettled([
+      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
+      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
+    ]);
+    const fulfilled = results.filter((r) => r.status === 'fulfilled');
+    const rejected = results.filter((r) => r.status === 'rejected');
+    expect(fulfilled).toHaveLength(1);
+    expect(rejected).toHaveLength(1);
+    expect((rejected[0] as PromiseRejectedResult).reason).toBeInstanceOf(
+      RunAlreadyActiveError,
+    );
+    // Exactly the winner is locally active.
+    expect(svc.isLocallyActive('run-win')).toBe(true);
+  });
+
+  it('a SUBSCRIBER detaching does NOT abort the run (only an explicit stop does)', async () => {
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const handle = await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+    // Model a browser disconnect: nothing in the run service is told to stop.
+    // The signal the agent loop consumes must stay un-aborted and the run stays
+    // locally active — i.e. it keeps running server-side.
+    expect(handle.signal.aborted).toBe(false);
+    expect(svc.isLocallyActive('run-1')).toBe(true);
+    // markStopRequested was never called by a mere detach.
+    expect(repo.markStopRequested).not.toHaveBeenCalled();
+  });
+
+  it('requestStop aborts the live controller, marks the row, and reports true', async () => {
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const handle = await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+    const aborted = jest.fn();
+    handle.signal.addEventListener('abort', aborted);
+
+    const result = await svc.requestStop('run-1', 'ws-1');
+
+    expect(result).toBe(true);
+    expect(handle.signal.aborted).toBe(true);
+    expect(aborted).toHaveBeenCalledTimes(1);
+    expect(repo.markStopRequested).toHaveBeenCalledWith('run-1', 'ws-1');
+  });
+
+  it('requestStop on a run this replica does NOT hold still marks the row (true)', async () => {
+    // e.g. after a restart, or a sibling replica owns the controller. The row is
+    // marked so the owning replica/sweep settles it; we report a stop took effect.
+    const repo = makeRepo({
+      markStopRequested: jest.fn(async () => ({ id: 'run-9' })),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const result = await svc.requestStop('run-9', 'ws-1');
+    expect(result).toBe(true);
+    expect(svc.isLocallyActive('run-9')).toBe(false);
+  });
+
+  it('requestStop on an already-settled run (nothing active) reports false', async () => {
+    const repo = makeRepo({
+      markStopRequested: jest.fn(async () => undefined),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const result = await svc.requestStop('run-done', 'ws-1');
+    expect(result).toBe(false);
+  });
+
+  it('finalizeRun settles the row to the mapped status with finishedAt and drops the in-memory entry', async () => {
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+    expect(svc.isLocallyActive('run-1')).toBe(true);
+
+    await svc.finalizeRun('run-1', 'ws-1', 'error', 'provider blew up');
+
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+    expect(repo.update).toHaveBeenCalledWith(
+      'run-1',
+      'ws-1',
+      expect.objectContaining({
+        status: 'failed',
+        error: 'provider blew up',
+        finishedAt: expect.any(Date),
+      }),
+    );
+  });
+
+  it('finalizeRun is IDEMPOTENT: a second settle no-ops (single terminal write)', async () => {
+    // The #184 review fix: AiChatService.stream wraps the turn in a safety-net
+    // catch that settles a failed turn AND streamText's terminal callback may
+    // also settle — both routes call finalizeRun. Only the FIRST may write the
+    // terminal row; the second must no-op so a late settle can never clobber the
+    // real terminal status or double-write the row.
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+
+    await svc.finalizeRun('run-1', 'ws-1', 'error', 'first');
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+    // A second settle (e.g. a streamText callback firing after the catch) no-ops.
+    await svc.finalizeRun('run-1', 'ws-1', 'completed', undefined);
+
+    expect(repo.update).toHaveBeenCalledTimes(1);
+    expect(repo.update).toHaveBeenCalledWith(
+      'run-1',
+      'ws-1',
+      expect.objectContaining({ status: 'failed', error: 'first' }),
+    );
+  });
+
+  it('CONCURRENCY: two simultaneous finalizeRun on the same run write the terminal row EXACTLY ONCE (the 2nd caller exits synchronously at the atomic claim)', async () => {
+    // The CRITICAL race: AiChatService.stream's safety-net catch settles the turn
+    // to 'error' while a streamText terminal callback also settles it — both call
+    // finalizeRun for the SAME runId. The once-gate must close ATOMICALLY: a
+    // `settled.has` check alone is read BEFORE the awaited UPDATE, so both callers
+    // would pass it and BOTH write the row (last-write-wins clobber + double
+    // write). The fix claims the run with a SYNCHRONOUS `active.delete` before any
+    // await, so the second caller returns in the same tick, before the UPDATE.
+    //
+    // We force the two calls to overlap by making `update` return a promise we
+    // resolve only AFTER both finalizeRun calls have run their synchronous bodies.
+    let resolveUpdate!: (v: unknown) => void;
+    const updateGate = new Promise((res) => {
+      resolveUpdate = res;
+    });
+    const update = jest.fn(() => updateGate);
+    const repo = makeRepo({ update });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+
+    // Fire both before the (pending) update resolves. The first synchronously
+    // claims the entry (active.delete) and awaits update; the second, started in
+    // the same macrotask, finds the entry already gone and returns at the claim
+    // WITHOUT ever calling update.
+    const p1 = svc.finalizeRun('run-1', 'ws-1', 'completed');
+    const p2 = svc.finalizeRun('run-1', 'ws-1', 'error', 'safety-net');
+
+    // The decisive assertion: exactly one caller reached the terminal UPDATE.
+    expect(update).toHaveBeenCalledTimes(1);
+
+    // Let the single in-flight update land; both calls resolve cleanly.
+    resolveUpdate({ id: 'run-1' });
+    await Promise.all([p1, p2]);
+
+    expect(update).toHaveBeenCalledTimes(1);
+    // The winner is the FIRST caller ('completed' -> 'succeeded'); the late
+    // 'error' settle never wrote, so it could not clobber the real status.
+    expect(update).toHaveBeenCalledWith(
+      'run-1',
+      'ws-1',
+      expect.objectContaining({ status: 'succeeded' }),
+    );
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+  });
+
+  it('F6: a TRANSIENT terminal-write failure is ridden out by the bounded retry — the run is settled, not stranded', async () => {
+    // The bug: finalizeRun used to DROP the in-memory entry BEFORE the terminal
+    // UPDATE, then only warn-log a failure. A single transient blip (pool
+    // exhaustion / deadlock / connection hiccup) on that PK UPDATE left the row
+    // 'running' with nothing left to recover it -> every later turn in that chat
+    // 409s until a restart. The fix updates FIRST and retries.
+    let calls = 0;
+    const repo = makeRepo({
+      update: jest.fn(async () => {
+        calls += 1;
+        if (calls === 1) throw new Error('deadlock detected');
+        return { id: 'run-1' };
+      }),
+    });
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+
+    await svc.finalizeRun('run-1', 'ws-1', 'completed');
+
+    // The retry landed the terminal write: the entry is dropped (slot freed) and
+    // the row carries the real terminal status — NOT stranded at 'running'.
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+    expect(repo.update).toHaveBeenCalledTimes(2);
+    expect(repo.update).toHaveBeenLastCalledWith(
+      'run-1',
+      'ws-1',
+      expect.objectContaining({ status: 'succeeded' }),
+    );
+  });
+
+  it('F6: if the terminal write keeps failing, the entry is RETAINED and a LATER settle completes it (chat not permanently 409d)', async () => {
+    // Worst case: the DB is down for the whole first finalize (all attempts fail).
+    // The run must NOT be silently lost — the entry stays so a subsequent settle
+    // (a streamText callback, requestStop -> onAbort, or a future sweep) can retry.
+    let healthy = false;
+    const repo = makeRepo({
+      update: jest.fn(async () => {
+        if (!healthy) throw new Error('pool exhausted');
+        return { id: 'run-1' };
+      }),
+    });
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+    const errorSpy = jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({
+      chatId: 'chat-1',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+    });
+
+    // First settle: every bounded attempt fails -> entry retained, NOT settled.
+    await svc.finalizeRun('run-1', 'ws-1', 'completed');
+    expect(svc.isLocallyActive('run-1')).toBe(true);
+    // F12: the give-up emits ONE explicit, greppable ERROR (run + chat context)
+    // so an operator can tell "gave up, run held in memory" from a per-attempt
+    // blip — distinct from the per-attempt warns.
+    const gaveUp = errorSpy.mock.calls.some(
+      (c) =>
+        /NON-TERMINAL/.test(String(c[0])) &&
+        /run-1/.test(String(c[0])) &&
+        /chat-1/.test(String(c[0])),
+    );
+    expect(gaveUp).toBe(true);
+
+    // The DB recovers; a later settle now succeeds and frees the slot.
+    healthy = true;
+    await svc.finalizeRun('run-1', 'ws-1', 'completed');
+    expect(svc.isLocallyActive('run-1')).toBe(false);
+    expect(repo.update).toHaveBeenLastCalledWith(
+      'run-1',
+      'ws-1',
+      expect.objectContaining({ status: 'succeeded' }),
+    );
+
+    // And it is now idempotent: a further settle no-ops (terminal row already
+    // written), so a double-settle can never clobber the real status.
+    const callsBefore = repo.update.mock.calls.length;
+    await svc.finalizeRun('run-1', 'ws-1', 'error', 'late');
+    expect(repo.update).toHaveBeenCalledTimes(callsBefore);
+  });
+
+  it('recordStep / linkAssistantMessage are best-effort: a repo failure is swallowed', async () => {
+    const repo = makeRepo({
+      update: jest.fn(async () => {
+        throw new Error('transient');
+      }),
+    });
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await expect(svc.recordStep('run-1', 'ws-1', 3)).resolves.toBeUndefined();
+    await expect(
+      svc.linkAssistantMessage('run-1', 'ws-1', 'msg-1'),
+    ).resolves.toBeUndefined();
+  });
+});

apps/server/src/core/ai-chat/ai-chat-run.service.ts

@@ -0,0 +1,426 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
+import { AiChatRun } from '@docmost/db/types/entity.types';
+import { isUniqueViolation, violatedConstraint } from '@docmost/db/utils';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+
+/** Name of the partial unique index enforcing "one active run per chat" (see the
+ *  ai_chat_runs migration). A 23505 on THIS constraint is the race-safe signal
+ *  that a concurrent turn already owns the chat — distinct from any other unique
+ *  collision, which must NOT be silently treated as "already active". */
+export const ONE_ACTIVE_RUN_PER_CHAT_INDEX = 'ai_chat_runs_one_active_per_chat';
+
+/**
+ * Thrown by {@link AiChatRunService.beginRun} when the run-row INSERT loses the
+ * race for a chat's single active slot (the partial unique index rejects it with
+ * a 23505). This is the AUTHORITATIVE concurrency gate: the controller's cheap
+ * pre-check is only a fast-path, and a request that slips past it must NOT run
+ * untracked. The caller (AiChatService.stream) translates this into a 409 and
+ * aborts the turn BEFORE any AI/provider call.
+ */
+export class RunAlreadyActiveError extends Error {
+  constructor(public readonly chatId: string) {
+    super(`An agent run is already in progress for chat ${chatId}`);
+    this.name = 'RunAlreadyActiveError';
+  }
+}
+
+/**
+ * The terminal status of a TURN (the #183 assistant-row lifecycle) maps onto the
+ * terminal status of a RUN (#184). A turn that completed -> the run succeeded; a
+ * turn that errored -> the run failed; a turn aborted (explicit user stop) -> the
+ * run aborted. Pure + unit-testable.
+ */
+export type TurnTerminalStatus = 'completed' | 'error' | 'aborted';
+export type RunTerminalStatus = 'succeeded' | 'failed' | 'aborted';
+
+export function mapTurnStatusToRun(
+  status: TurnTerminalStatus,
+): RunTerminalStatus {
+  switch (status) {
+    case 'completed':
+      return 'succeeded';
+    case 'error':
+      return 'failed';
+    case 'aborted':
+      return 'aborted';
+  }
+}
+
+/** An in-flight run held in process memory: its AbortController is the ONLY thing
+ *  that can stop the turn (an explicit user stop), independent of the browser
+ *  socket. A mere disconnect never touches it, so the run keeps going. */
+interface ActiveRun {
+  controller: AbortController;
+  chatId: string;
+  workspaceId: string;
+}
+
+/** The live handle the streaming path drives a run through (returned by
+ *  {@link AiChatRunService.beginRun}). The `signal` governs the agent loop's
+ *  abort — wired to the run, NOT to the HTTP socket. */
+export interface RunHandle {
+  runId: string;
+  signal: AbortSignal;
+}
+
+/**
+ * AiChatRunService (#184 phase 1) — owns the agent RUN as a first-class,
+ * server-side lifecycle object detached from the HTTP request / browser window.
+ *
+ * Responsibilities:
+ *  - create a run row when a turn starts (pending -> running) and register an
+ *    in-memory AbortController for it (the explicit-stop lever);
+ *  - finalize the run row (succeeded / failed / aborted) and unregister it;
+ *  - service an EXPLICIT user stop (`requestStop`) — the ONLY thing that aborts a
+ *    run; a browser disconnect deliberately does NOT;
+ *  - crash-recovery sweep of dangling runs on startup.
+ *
+ * The agent loop itself still runs in AiChatService.stream (reusing #183's
+ * step-granular durable write path, `consumeStream` already drains it independent
+ * of the socket); this service only wraps it in a durable lifecycle and an
+ * abort handle that outlives the subscriber.
+ */
+@Injectable()
+export class AiChatRunService implements OnModuleInit {
+  private readonly logger = new Logger(AiChatRunService.name);
+
+  // runId -> ActiveRun. Process-local on purpose (phase 1 is single-process /
+  // in-memory transport; a cross-process BullMQ runner + Redis stop-signal is
+  // deferred to phase 2). A stop for a runId not in this map (e.g. after a
+  // restart) still records `stop_requested_at` on the row.
+  private readonly active = new Map<string, ActiveRun>();
+
+  // runIds whose TERMINAL row write has SUCCEEDED — the idempotency once-gate
+  // (F6). A finalize must short-circuit only AFTER the terminal write has landed,
+  // NOT merely after the in-memory entry was dropped: a transient UPDATE failure
+  // has to stay retryable, so "already settled" means "row already terminal", not
+  // "entry already gone". Grows by one short UUID per finished run over process
+  // uptime — negligible in phase 1's single process.
+  private readonly settled = new Set<string>();
+
+  // Bounded retry for the terminal write (F6): a single PK UPDATE can fail
+  // transiently under many fire-and-forget writes (pool exhaustion, deadlock, a
+  // brief connection blip). Riding out that blip in-place matters because the
+  // dominant success path (streamText onFinish) settles exactly ONCE — if that
+  // write is dropped and never retried, the row is stranded 'running' and the
+  // one-active-run gate 409s every future turn in the chat until a restart (no
+  // periodic sweep in phase 1).
+  private static readonly FINALIZE_MAX_ATTEMPTS = 3;
+  private static readonly FINALIZE_RETRY_BASE_MS = 50;
+
+  constructor(
+    private readonly runRepo: AiChatRunRepo,
+    private readonly environment: EnvironmentService,
+  ) {}
+
+  /**
+   * Crash-recovery sweep on server start: settle EVERY run still left
+   * pending/running to 'aborted' (F1 / DECISION C). The boot sweep is
+   * UNCONDITIONAL — no staleness window — because phase 1 is single-process: on a
+   * fresh boot any pending|running run is definitionally hung (no live runner owns
+   * it), so even a fast restart (deploy/OOM within minutes of the last step) can
+   * no longer leave a run stuck 'running' forever (which would make the
+   * one-active-run gate 409 every future turn in that chat). The staleness window
+   * is reintroduced only for the phase-2 multi-instance timer sweep, where a
+   * booting replica must not abort a run another replica is actively executing.
+   * Best-effort — a sweep failure is logged but MUST NOT block startup (mirrors
+   * AiChatService.onModuleInit for #183).
+   */
+  async onModuleInit(): Promise<void> {
+    this.warnIfMultiInstance();
+    try {
+      // No `staleMs`: unconditional boot sweep (F1). See AiChatRunRepo.sweepRunning.
+      const swept = await this.runRepo.sweepRunning();
+      if (swept > 0) {
+        this.logger.log(
+          `Startup sweep: marked ${swept} dangling agent run(s) as 'aborted'.`,
+        );
+      }
+    } catch (err) {
+      this.logger.warn(
+        `Startup sweep of dangling runs failed: ${
+          err instanceof Error ? err.message : 'unknown error'
+        }`,
+      );
+    }
+  }
+
+  /**
+   * F2 (DECISION A): autonomous runs are SINGLE-INSTANCE-ONLY in phase 1. An
+   * explicit Stop, and the in-memory AbortController that backs it, are
+   * process-local: a Stop only aborts the live turn if it lands on the SAME
+   * replica that owns the run (it still stamps `stop_requested_at` cross-instance,
+   * but nothing reads that flag during an active run yet). Cross-instance pub/sub
+   * stop is phase 2. So if the deployment is horizontally scaled, warn loudly at
+   * startup that a Stop may not reach a run executing on another replica.
+   *
+   * DETECTION: this codebase always wires the socket.io Redis adapter (REDIS_URL
+   * is mandatory), so the adapter alone is NOT a horizontal-scaling signal. The
+   * authoritative signal the codebase has is `CLOUD=true` (EnvironmentService
+   * .isCloud()), the Docmost-cloud multi-replica deployment. We warn whenever that
+   * is set, because any workspace could enable settings.ai.autonomousRuns. A
+   * self-hosted operator running multiple replicas behind a load balancer is also
+   * multi-instance; the deploy docs (.env.example / AGENTS.md) spell out the
+   * single-instance constraint for that case.
+   */
+  private warnIfMultiInstance(): void {
+    if (this.environment.isCloud()) {
+      this.logger.warn(
+        'Autonomous agent runs (settings.ai.autonomousRuns) are SINGLE-INSTANCE-ONLY ' +
+          'in phase 1: a horizontally-scaled deployment was detected (CLOUD=true). ' +
+          'An explicit Stop only aborts a run executing on the same replica that owns ' +
+          'it (cross-instance Stop is not yet reliable — phase 2). Run a single ' +
+          'instance if you enable autonomousRuns, or keep the flag off.',
+      );
+    }
+  }
+
+  /**
+   * Start a run for a turn: insert the run row (status 'running', startedAt now),
+   * register a fresh AbortController for it, and return a {@link RunHandle} whose
+   * `signal` the agent loop uses. The DB partial unique index guarantees at most
+   * one active run per chat — a second concurrent start on the same chat REJECTS
+   * at the insert (a 23505 on {@link ONE_ACTIVE_RUN_PER_CHAT_INDEX}). That
+   * rejection is the AUTHORITATIVE race gate: it is surfaced as a distinct
+   * {@link RunAlreadyActiveError} (NOT swallowed), so the caller turns it into a
+   * 409 and never streams an untracked turn. The controller is registered AFTER a
+   * successful insert so a rejected start leaks nothing.
+   */
+  async beginRun(args: {
+    chatId: string;
+    workspaceId: string;
+    userId: string;
+    trigger?: string;
+  }): Promise<RunHandle> {
+    let run: AiChatRun;
+    try {
+      run = await this.runRepo.insert({
+        chatId: args.chatId,
+        workspaceId: args.workspaceId,
+        createdBy: args.userId,
+        trigger: args.trigger ?? 'user',
+        status: 'running',
+        startedAt: new Date(),
+      });
+    } catch (err) {
+      // The race backstop: a concurrent turn already holds this chat's single
+      // active slot, so the partial unique index rejected our insert. Surface a
+      // distinct signal — the caller MUST reject this turn (409), not run it
+      // untracked. Any OTHER error propagates unchanged.
+      if (
+        isUniqueViolation(err) &&
+        violatedConstraint(err) === ONE_ACTIVE_RUN_PER_CHAT_INDEX
+      ) {
+        throw new RunAlreadyActiveError(args.chatId);
+      }
+      throw err;
+    }
+    const controller = new AbortController();
+    this.active.set(run.id, {
+      controller,
+      chatId: args.chatId,
+      workspaceId: args.workspaceId,
+    });
+    return { runId: run.id, signal: controller.signal };
+  }
+
+  /** Link the assistant message (the #183 projection) to its run. Best-effort. */
+  async linkAssistantMessage(
+    runId: string,
+    workspaceId: string,
+    assistantMessageId: string,
+  ): Promise<void> {
+    try {
+      await this.runRepo.update(runId, workspaceId, { assistantMessageId });
+    } catch (err) {
+      this.logger.warn(
+        `Failed to link assistant message to run ${runId}: ${
+          err instanceof Error ? err.message : 'unknown error'
+        }`,
+      );
+    }
+  }
+
+  /** Persist progress: bump the run's finished-step count. Best-effort (never
+   *  blocks or breaks the stream). */
+  async recordStep(
+    runId: string,
+    workspaceId: string,
+    stepCount: number,
+  ): Promise<void> {
+    try {
+      await this.runRepo.update(runId, workspaceId, { stepCount });
+    } catch (err) {
+      this.logger.warn(
+        `Failed to record step for run ${runId}: ${
+          err instanceof Error ? err.message : 'unknown error'
+        }`,
+      );
+    }
+  }
+
+  /**
+   * Finalize a run to its terminal status (succeeded / failed / aborted),
+   * stamping finishedAt + any error. Best-effort, but ROBUST against a transient
+   * terminal-write failure (F6) AND atomically safe against a concurrent settle.
+   *
+   * ATOMIC ONCE-CLAIM (the gate must close in ONE synchronous tick): two
+   * finalizeRun calls for the SAME run can race — the documented real path is
+   * AiChatService.stream's safety-net catch settling the turn to 'error' while a
+   * streamText terminal callback (onFinish/onAbort/onError) ALSO settles it. The
+   * `settled.has` check alone is NOT a gate: it is read BEFORE the awaited UPDATE,
+   * so two callers can both see `false` and both write the row (last-write-wins
+   * clobbers the real terminal status, and the bounded retry only widens that
+   * window). The claim therefore happens via `active.delete`, a SYNCHRONOUS
+   * check-and-clear with NO await between the gate and the entry removal: the
+   * second concurrent caller finds the entry already gone and returns in the same
+   * tick, before any UPDATE. The transition "nobody is finalizing" -> "I am
+   * finalizing" is thus a single atomic step.
+   *
+   * ORDER MATTERS (F6): once we own the claim, the terminal UPDATE happens FIRST;
+   * only once it SUCCEEDS do we record the run as settled. If the UPDATE fails on
+   * every bounded attempt we RESTORE the in-memory entry, leave the run UNsettled,
+   * and emit an ERROR signal that the row is left non-terminal 'running' (which
+   * would 409 every future turn in the chat until recovery). An in-process retry
+   * by a LATER settle is only POSSIBLE, never guaranteed: it needs (a) the entry
+   * to have been restored at the give-up path AND (b) a fresh settler to arrive
+   * AFTER that restore. A concurrent settler that arrives DURING the retry window
+   * — while the entry is deleted for backoff and not yet restored — is consumed at
+   * the synchronous `active.delete` claim (it finds nothing to delete and returns
+   * a no-op), so it does NOT become an in-process retrier. The NO-streamText path
+   * (the turn threw before streamText was wired, so ONLY the safety-net ever
+   * settles) likewise has no second in-process settler at all. The UNCONDITIONAL
+   * backstop in every case is the boot sweep on the next restart (phase 1 has no
+   * periodic in-process sweep); the retained entry is bounded (cleared on restart)
+   * and harmless meanwhile.
+   *
+   * IDEMPOTENT on SUCCESS (#184 review): the terminal write happens AT MOST ONCE
+   * per run. After a successful write the once-gate keys off {@link settled} (the
+   * terminal row already written) so a settle arriving AFTER the entry was already
+   * dropped-and-settled returns early; a settle racing the in-flight write is
+   * stopped earlier still, by the `active.delete` claim. Either way a genuine
+   * double-settle collapses to a single write and a late settle can never clobber
+   * the real terminal status or double-write the row.
+   */
+  async finalizeRun(
+    runId: string,
+    workspaceId: string,
+    turnStatus: TurnTerminalStatus,
+    error?: string,
+  ): Promise<void> {
+    // ---- Atomic once-claim (synchronous; NO await before the gate closes) ----
+    // Already terminally written -> idempotent no-op.
+    if (this.settled.has(runId)) return;
+    // Capture the entry BEFORE the delete so a total-failure path can restore it.
+    const entry = this.active.get(runId);
+    // SYNCHRONOUS check-and-clear: the FIRST caller deletes (claims) the entry;
+    // any concurrent SECOND caller finds nothing to delete and returns HERE, in
+    // the same tick, before any await — so it can never reach the UPDATE.
+    if (!this.active.delete(runId)) return;
+
+    let lastError: unknown;
+    for (
+      let attempt = 1;
+      attempt <= AiChatRunService.FINALIZE_MAX_ATTEMPTS;
+      attempt++
+    ) {
+      try {
+        await this.runRepo.update(runId, workspaceId, {
+          status: mapTurnStatusToRun(turnStatus),
+          finishedAt: new Date(),
+          error: error ?? null,
+        });
+        // Terminal write landed: arm the once-gate. The entry is already gone
+        // (claimed above); we do NOT restore it. The slot is now free.
+        this.settled.add(runId);
+        return;
+      } catch (err) {
+        lastError = err;
+        this.logger.warn(
+          `Failed to finalize run ${runId} (attempt ${attempt}/${
+            AiChatRunService.FINALIZE_MAX_ATTEMPTS
+          }): ${err instanceof Error ? err.message : 'unknown error'}`,
+        );
+        if (attempt < AiChatRunService.FINALIZE_MAX_ATTEMPTS) {
+          await this.delay(AiChatRunService.FINALIZE_RETRY_BASE_MS * attempt);
+        }
+      }
+    }
+    // Every attempt failed: this is a give-up, materially worse than a per-attempt
+    // blip — the row is left NON-TERMINAL ('running'), so emit ONE explicit,
+    // greppable ERROR so an operator can tell "survived a blip" from "gave up, run
+    // held in memory until recovery" (the last warn alone says only "attempt 3/3").
+    this.logger.error(
+      `Run ${runId} (chat ${entry?.chatId ?? 'unknown'}) left NON-TERMINAL ` +
+        `('running'): terminal write failed after ${
+          AiChatRunService.FINALIZE_MAX_ATTEMPTS
+        } attempts; entry retained in memory, recovery deferred to next settle / ` +
+        `boot sweep`,
+      lastError,
+    );
+    // RESTORE the claimed entry (and leave the run UNsettled) so a LATER settle
+    // that arrives AFTER this restore MAY retry the terminal write — but that
+    // in-process retry is NOT guaranteed (a concurrent settler caught in the retry
+    // window above is consumed at the `active.delete` claim, and the no-streamText
+    // path has no second settler at all). The UNCONDITIONAL backstop in every case
+    // is the boot sweep on the next restart; the restored entry is bounded and
+    // cleared on restart.
+    if (entry) this.active.set(runId, entry);
+  }
+
+  /** Small async backoff between terminal-write retries (F6). Isolated so it is
+   *  trivial to stub/fake-time in tests. */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Request an EXPLICIT stop of a run (the user pressed Stop). This is the ONLY
+   * thing that aborts a run — distinct from a browser disconnect, which leaves
+   * the run going. Records `stop_requested_at` on the row (only while active) and
+   * aborts the in-process controller if this replica owns the run. Returns true
+   * when a stop took effect (row marked and/or controller aborted), false when
+   * there was nothing active to stop.
+   */
+  async requestStop(runId: string, workspaceId: string): Promise<boolean> {
+    const marked = await this.runRepo.markStopRequested(runId, workspaceId);
+    const entry = this.active.get(runId);
+    if (entry) {
+      // Abort the live turn -> streamText onAbort fires -> the partial is
+      // persisted (#183) and finalizeRun settles the row as 'aborted'.
+      entry.controller.abort();
+    }
+    return Boolean(marked) || Boolean(entry);
+  }
+
+  /** Latest persisted run for a chat — the reconnect target (an in-flight or
+   *  finished run). Pure read-through to the repo. */
+  getLatestForChat(
+    chatId: string,
+    workspaceId: string,
+  ): Promise<AiChatRun | undefined> {
+    return this.runRepo.findLatestByChat(chatId, workspaceId);
+  }
+
+  /** Fetch a run by id (workspace-scoped). Used to resolve + ownership-check an
+   *  explicit stop targeting a runId. */
+  getRun(runId: string, workspaceId: string): Promise<AiChatRun | undefined> {
+    return this.runRepo.findById(runId, workspaceId);
+  }
+
+  /** The active run on a chat, if any (used to reject a concurrent start with a
+   *  clean 409 before committing to the stream). */
+  getActiveForChat(
+    chatId: string,
+    workspaceId: string,
+  ): Promise<AiChatRun | undefined> {
+    return this.runRepo.findActiveByChat(chatId, workspaceId);
+  }
+
+  /** Test/diagnostic seam: whether this replica is holding a live controller for
+   *  the run. */
+  isLocallyActive(runId: string): boolean {
+    return this.active.has(runId);
+  }
+}

apps/server/src/core/ai-chat/ai-chat.controller.bound-chat.spec.ts

@@ -19,6 +19,7 @@ describe('AiChatController.boundChat', () => {
     };
     const controller = new AiChatController(
       {} as never,
+      {} as never, // aiChatRunService
       aiChatRepo as never,
       {} as never,
       {} as never,

apps/server/src/core/ai-chat/ai-chat.controller.export.spec.ts

@@ -53,6 +53,7 @@ describe('AiChatController.export', () => {
     };
     const controller = new AiChatController(
       {} as never,
+      {} as never, // aiChatRunService
       aiChatRepo as never,
       aiChatMessageRepo as never,
       {} as never,

apps/server/src/core/ai-chat/ai-chat.controller.run.spec.ts

@@ -0,0 +1,163 @@
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
+import { AiChatController } from './ai-chat.controller';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
+
+/**
+ * Wiring spec for the #184 run-reconnect / run-stop endpoints
+ * (`POST /ai-chat/run` and `POST /ai-chat/stop`). Both are OWNER-gated via
+ * assertOwnedChat (the requesting user must own the chat) and NOT flag-gated.
+ * Exercised with hand-rolled mocks — no Nest graph, no DB. The controller's
+ * constructor order is (aiChatService, aiChatRunService, aiChatRepo,
+ * aiChatMessageRepo, aiTranscription).
+ */
+describe('AiChatController run endpoints (#184)', () => {
+  const user = { id: 'u1' } as User;
+  const workspace = { id: 'ws1' } as Workspace;
+
+  function makeController(opts: {
+    chat?: unknown; // what aiChatRepo.findById returns (owner-gate)
+    run?: unknown; // getLatestForChat / getRun result
+    activeRun?: unknown; // getActiveForChat result
+    message?: unknown; // aiChatMessageRepo.findById result
+    stopped?: boolean; // requestStop result
+  }) {
+    const aiChatRunService = {
+      getLatestForChat: jest.fn().mockResolvedValue(opts.run),
+      getRun: jest.fn().mockResolvedValue(opts.run),
+      getActiveForChat: jest.fn().mockResolvedValue(opts.activeRun),
+      requestStop: jest.fn().mockResolvedValue(opts.stopped ?? false),
+    };
+    const aiChatRepo = {
+      findById: jest.fn().mockResolvedValue(opts.chat),
+    };
+    const aiChatMessageRepo = {
+      findById: jest.fn().mockResolvedValue(opts.message),
+    };
+    const controller = new AiChatController(
+      {} as never, // aiChatService
+      aiChatRunService as never,
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never, // aiTranscription
+    );
+    return { controller, aiChatRunService, aiChatRepo, aiChatMessageRepo };
+  }
+
+  describe('POST /ai-chat/run (getRun)', () => {
+    it('owner-gates: a chat the user does not own throws ForbiddenException', async () => {
+      const { controller, aiChatRunService } = makeController({
+        chat: { id: 'c1', creatorId: 'someone-else' },
+      });
+      await expect(
+        controller.getRun({ chatId: 'c1' }, user, workspace),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      // It must NOT reach the run lookup once the owner-gate fails.
+      expect(aiChatRunService.getLatestForChat).not.toHaveBeenCalled();
+    });
+
+    it('returns { run: null, message: null } when the chat has never had a run', async () => {
+      const { controller, aiChatRunService } = makeController({
+        chat: { id: 'c1', creatorId: 'u1' },
+        run: undefined,
+      });
+      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
+      expect(res).toEqual({ run: null, message: null });
+      expect(aiChatRunService.getLatestForChat).toHaveBeenCalledWith(
+        'c1',
+        'ws1',
+      );
+    });
+
+    it('returns the run and its projected assistant message', async () => {
+      const run = { id: 'run-1', chatId: 'c1', assistantMessageId: 'm1' };
+      const message = { id: 'm1', role: 'assistant' };
+      const { controller, aiChatMessageRepo } = makeController({
+        chat: { id: 'c1', creatorId: 'u1' },
+        run,
+        message,
+      });
+      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
+      expect(res).toEqual({ run, message });
+      expect(aiChatMessageRepo.findById).toHaveBeenCalledWith('m1', 'ws1');
+    });
+
+    it('returns message: null when the run has no linked assistant message', async () => {
+      const run = { id: 'run-1', chatId: 'c1', assistantMessageId: null };
+      const { controller, aiChatMessageRepo } = makeController({
+        chat: { id: 'c1', creatorId: 'u1' },
+        run,
+      });
+      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
+      expect(res).toEqual({ run, message: null });
+      expect(aiChatMessageRepo.findById).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('POST /ai-chat/stop (stopRun)', () => {
+    it('throws BadRequestException when neither runId nor chatId is given', async () => {
+      const { controller } = makeController({});
+      await expect(
+        controller.stopRun({}, user, workspace),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('stops by runId: owner-gates via the run’s chat, then requests the stop', async () => {
+      const { controller, aiChatRunService, aiChatRepo } = makeController({
+        run: { id: 'run-1', chatId: 'c1' },
+        chat: { id: 'c1', creatorId: 'u1' },
+        stopped: true,
+      });
+      const res = await controller.stopRun({ runId: 'run-1' }, user, workspace);
+      expect(res).toEqual({ stopped: true });
+      expect(aiChatRunService.getRun).toHaveBeenCalledWith('run-1', 'ws1');
+      expect(aiChatRepo.findById).toHaveBeenCalledWith('c1', 'ws1');
+      expect(aiChatRunService.requestStop).toHaveBeenCalledWith('run-1', 'ws1');
+    });
+
+    it('stops by runId: a foreign run’s chat throws ForbiddenException (no stop)', async () => {
+      const { controller, aiChatRunService } = makeController({
+        run: { id: 'run-1', chatId: 'c1' },
+        chat: { id: 'c1', creatorId: 'someone-else' },
+      });
+      await expect(
+        controller.stopRun({ runId: 'run-1' }, user, workspace),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
+    });
+
+    it('stops by runId: an unknown run reports { stopped: false }', async () => {
+      const { controller, aiChatRunService } = makeController({
+        run: undefined,
+      });
+      const res = await controller.stopRun({ runId: 'gone' }, user, workspace);
+      expect(res).toEqual({ stopped: false });
+      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
+    });
+
+    it('stops by chatId: owner-gates, resolves the active run, requests the stop', async () => {
+      const { controller, aiChatRunService, aiChatRepo } = makeController({
+        chat: { id: 'c1', creatorId: 'u1' },
+        activeRun: { id: 'run-9' },
+        stopped: true,
+      });
+      const res = await controller.stopRun({ chatId: 'c1' }, user, workspace);
+      expect(res).toEqual({ stopped: true });
+      expect(aiChatRepo.findById).toHaveBeenCalledWith('c1', 'ws1');
+      expect(aiChatRunService.getActiveForChat).toHaveBeenCalledWith(
+        'c1',
+        'ws1',
+      );
+      expect(aiChatRunService.requestStop).toHaveBeenCalledWith('run-9', 'ws1');
+    });
+
+    it('stops by chatId: reports { stopped: false } when no run is active', async () => {
+      const { controller, aiChatRunService } = makeController({
+        chat: { id: 'c1', creatorId: 'u1' },
+        activeRun: undefined,
+      });
+      const res = await controller.stopRun({ chatId: 'c1' }, user, workspace);
+      expect(res).toEqual({ stopped: false });
+      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
+    });
+  });
+});

apps/server/src/core/ai-chat/ai-chat.controller.ts

@@ -1,6 +1,7 @@
 import {
   BadRequestException,
   Body,
+  ConflictException,
   Controller,
   ForbiddenException,
   HttpCode,
@@ -20,14 +21,25 @@ import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
 import { SkipTransform } from '../../common/decorators/skip-transform.decorator';
-import { AiChat, User, Workspace } from '@docmost/db/types/entity.types';
+import {
+  AiChat,
+  AiChatMessage,
+  AiChatRun,
+  User,
+  Workspace,
+} from '@docmost/db/types/entity.types';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
 import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AI_CHAT_THROTTLER } from '../../integrations/throttle/throttler-names';
 import { FileInterceptor } from '../../common/interceptors/file.interceptor';
-import { AiChatService, AiChatStreamBody } from './ai-chat.service';
+import {
+  AiChatRunHooks,
+  AiChatService,
+  AiChatStreamBody,
+} from './ai-chat.service';
+import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import {
   BoundChatDto,
@@ -35,7 +47,9 @@ import {
   ExportChatDto,
   GeneratePageTitleDto,
   GetChatMessagesDto,
+  GetRunDto,
   RenameChatDto,
+  StopRunDto,
 } from './dto/ai-chat.dto';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import { buildChatMarkdown } from './chat-markdown.util';
@@ -52,6 +66,7 @@ export class AiChatController {
 
   constructor(
     private readonly aiChatService: AiChatService,
+    private readonly aiChatRunService: AiChatRunService,
     private readonly aiChatRepo: AiChatRepo,
     private readonly aiChatMessageRepo: AiChatMessageRepo,
     private readonly aiTranscription: AiTranscriptionService,
@@ -137,6 +152,75 @@ export class AiChatController {
     return { markdown };
   }
 
+  /**
+   * Reconnect to the latest run of a chat (#184 phase 1). Returns the run's
+   * persisted lifecycle state ({ status, error, stepCount, timings, ... }) plus
+   * the assistant message it projects (the partial/final output) — the DB is the
+   * source of truth, so this works for an in-flight run (the browser dropped, the
+   * run kept going) and a finished one alike. Owner-gated via assertOwnedChat.
+   * `{ run: null }` when the chat has never had a run.
+   */
+  @HttpCode(HttpStatus.OK)
+  @Post('run')
+  async getRun(
+    @Body() dto: GetRunDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ): Promise<{ run: AiChatRun | null; message: AiChatMessage | null }> {
+    await this.assertOwnedChat(dto.chatId, user, workspace);
+    const run = await this.aiChatRunService.getLatestForChat(
+      dto.chatId,
+      workspace.id,
+    );
+    if (!run) return { run: null, message: null };
+    const message = run.assistantMessageId
+      ? await this.aiChatMessageRepo.findById(
+          run.assistantMessageId,
+          workspace.id,
+        )
+      : undefined;
+    return { run, message: message ?? null };
+  }
+
+  /**
+   * Explicitly STOP an agent run (#184 phase 1) — the user pressed Stop. This is
+   * the ONLY thing that ends a detached run; a browser disconnect deliberately
+   * does not. Target by `runId` (from the streamed start metadata) or by `chatId`
+   * (stop whatever run is active on it). Owner-gated. Returns
+   * `{ stopped }` — false when there was nothing active to stop.
+   */
+  @HttpCode(HttpStatus.OK)
+  @Post('stop')
+  async stopRun(
+    @Body() dto: StopRunDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ): Promise<{ stopped: boolean }> {
+    let runId = dto.runId;
+    if (!runId && !dto.chatId) {
+      throw new BadRequestException('runId or chatId is required');
+    }
+    if (runId) {
+      // Resolve the run to its chat and owner-gate via that chat.
+      const run = await this.aiChatRunService.getRun(runId, workspace.id);
+      if (!run) return { stopped: false };
+      await this.assertOwnedChat(run.chatId, user, workspace);
+    } else {
+      await this.assertOwnedChat(dto.chatId!, user, workspace);
+      const active = await this.aiChatRunService.getActiveForChat(
+        dto.chatId!,
+        workspace.id,
+      );
+      if (!active) return { stopped: false };
+      runId = active.id;
+    }
+    const stopped = await this.aiChatRunService.requestStop(
+      runId,
+      workspace.id,
+    );
+    return { stopped };
+  }
+
   /** Rename a chat. */
   @HttpCode(HttpStatus.OK)
   @Post('rename')
@@ -188,11 +272,20 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ): Promise<void> {
     // A7 gate: the workspace must have AI chat explicitly enabled.
-    const settings = (workspace.settings ?? {}) as { ai?: { chat?: boolean } };
+    const settings = (workspace.settings ?? {}) as {
+      ai?: { chat?: boolean; autonomousRuns?: boolean };
+    };
     if (settings.ai?.chat !== true) {
       throw new ForbiddenException('AI chat is disabled');
     }
 
+    // #184 phase 1 flag: when ON, the turn becomes a detached, durable RUN — its
+    // lifecycle is tracked in ai_chat_runs, a browser disconnect no longer aborts
+    // it, and only an explicit /ai-chat/stop ends it. When OFF (the default) the
+    // turn is socket-bound exactly as before, so existing deployments are
+    // unaffected.
+    const autonomousRuns = settings.ai?.autonomousRuns === true;
+
     const sessionId = (req.raw as { sessionId?: string }).sessionId;
     if (!sessionId) {
       // The chat requires an interactive session to mint loopback tokens
@@ -216,6 +309,58 @@ export class AiChatController {
     // HttpException) instead of breaking mid-stream.
     const model = await this.aiChatService.getChatModel(workspace.id, role);
 
+    // #184: one active run per chat. For an EXISTING chat reject a concurrent
+    // start with a clean 409 BEFORE hijack (the common double-submit / second-tab
+    // case), so the user gets JSON, not a mid-stream error. A brand-new chat
+    // (no chatId) cannot have a prior run, and the DB partial unique index is the
+    // backstop against any race that slips past this check.
+    if (autonomousRuns && body.chatId) {
+      const active = await this.aiChatRunService.getActiveForChat(
+        body.chatId,
+        workspace.id,
+      );
+      if (active) {
+        throw new ConflictException({
+          message: 'An agent run is already in progress for this chat',
+          code: 'A_RUN_ALREADY_ACTIVE',
+        });
+      }
+    }
+
+    // Run-lifecycle hooks (#184), only when the flag is on. They wrap the turn in
+    // a durable run whose abort is governed by the run (explicit stop), persist
+    // its progress, and settle its terminal status — see AiChatRunService.
+    const runHooks: AiChatRunHooks | undefined = autonomousRuns
+      ? {
+          begin: (chatId) =>
+            this.aiChatRunService.beginRun({
+              chatId,
+              workspaceId: workspace.id,
+              userId: user.id,
+              trigger: 'user',
+            }),
+          onAssistantSeeded: (runId, messageId) =>
+            this.aiChatRunService.linkAssistantMessage(
+              runId,
+              workspace.id,
+              messageId,
+            ),
+          onStep: (runId, stepCount) =>
+            void this.aiChatRunService.recordStep(
+              runId,
+              workspace.id,
+              stepCount,
+            ),
+          onSettled: (runId, status, error) =>
+            this.aiChatRunService.finalizeRun(
+              runId,
+              workspace.id,
+              status,
+              error,
+            ),
+        }
+      : undefined;
+
     // Abort the agent loop when the client disconnects. `close` also fires on
     // normal completion, so only abort when the response has not finished
     // writing (a genuine disconnect). `once` fires at most once and self-removes;
@@ -230,18 +375,44 @@ export class AiChatController {
       // A genuine disconnect leaves the response unfinished (unlike a normal
       // completion, which also fires `close`). Such a drop — e.g. a reverse
       // proxy cutting the SSE mid-answer — is otherwise invisible server-side,
-      // so log it here before aborting the agent loop.
+      // so log it here.
       if (!res.raw.writableEnded) {
-        this.logger.warn(
-          `AI chat stream: client disconnected before completion; aborting turn ` +
-            `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
-        );
-        controller.abort();
+        if (autonomousRuns) {
+          // #184: the turn is a DETACHED run. A disconnect must NOT abort it —
+          // the run keeps executing and persisting server-side; the client
+          // reconnects via /ai-chat/run (or re-stops via /ai-chat/stop). Log only.
+          this.logger.log(
+            `AI chat stream: client disconnected; run continues server-side ` +
+              `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
+          );
+        } else {
+          this.logger.warn(
+            `AI chat stream: client disconnected before completion; aborting turn ` +
+              `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
+          );
+          controller.abort();
+        }
       }
     };
     req.raw.once('close', onClose);
     res.raw.once('finish', () => req.raw.off('close', onClose));
 
+    // #184: in detached mode the turn is NOT aborted on disconnect, so the SDK's
+    // pipe keeps writing to a socket the client may have dropped — for the rest of
+    // the (continuing) run. A write to the dead socket can emit an 'error' on the
+    // raw response; without a listener that surfaces as an unhandled error event.
+    // Swallow it (the run continues server-side regardless). Legacy mode aborts on
+    // disconnect, so it does not need this and keeps its exact prior behavior.
+    if (autonomousRuns) {
+      res.raw.on('error', (err) => {
+        this.logger.debug(
+          `AI chat detached stream: post-disconnect socket error swallowed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      });
+    }
+
     // Commit to streaming: hijack so Fastify stops managing the response and
     // the AI SDK can write the UI-message stream directly to the Node socket.
     res.hijack();
@@ -256,15 +427,32 @@ export class AiChatController {
         signal: controller.signal,
         model,
         role,
+        // #184: present only when the flag is on; wraps the turn in a durable run.
+        runHooks,
       });
     } catch (err) {
-      // Any failure AFTER hijack can no longer send a clean JSON error, so emit
-      // a minimal error on the raw socket if nothing has been written yet.
-      this.logger.error('AI chat stream failed', err as Error);
+      // Any failure AFTER hijack can no longer go through Nest's exception
+      // filter, so emit the error on the raw socket if nothing has been written
+      // yet. The lost-the-race 409 (RunAlreadyActiveError -> ConflictException)
+      // is raised by stream() BEFORE it writes a byte, so headers are still
+      // unsent here: honor the HttpException's real status + body (a clean 409),
+      // not a blanket 500. Everything else stays a 500.
+      const isHttp = err instanceof HttpException;
+      if (!isHttp) {
+        this.logger.error('AI chat stream failed', err as Error);
+      }
       if (!res.raw.headersSent) {
-        res.raw.statusCode = 500;
+        const status = isHttp ? err.getStatus() : 500;
+        const payload = isHttp
+          ? err.getResponse()
+          : { error: 'Internal server error' };
+        res.raw.statusCode = status;
         res.raw.setHeader('Content-Type', 'application/json');
-        res.raw.end(JSON.stringify({ error: 'Internal server error' }));
+        res.raw.end(
+          JSON.stringify(
+            typeof payload === 'string' ? { message: payload } : payload,
+          ),
+        );
       } else if (!res.raw.writableEnded) {
         res.raw.end();
       }

apps/server/src/core/ai-chat/ai-chat.generate-page-title.spec.ts

@@ -57,6 +57,7 @@ describe('AiChatController.generatePageTitle', () => {
     const aiChatService = { generatePageTitle: generate };
     const controller = new AiChatController(
       aiChatService as never,
+      {} as never, // aiChatRunService
       {} as never,
       {} as never,
       {} as never,

apps/server/src/core/ai-chat/ai-chat.module.ts

@@ -3,6 +3,7 @@ import { AiModule } from '../../integrations/ai/ai.module';
 import { TokenModule } from '../auth/token.module';
 import { AiChatController } from './ai-chat.controller';
 import { AiChatService } from './ai-chat.service';
+import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import { AiChatToolsService } from './tools/ai-chat-tools.service';
 import { EmbeddingModule } from './embedding/embedding.module';
@@ -42,6 +43,7 @@ import { PublicShareChatToolsService } from './tools/public-share-chat-tools.ser
   controllers: [AiChatController, PublicShareChatController],
   providers: [
     AiChatService,
+    AiChatRunService,
     AiTranscriptionService,
     AiChatToolsService,
     PublicShareChatService,

apps/server/src/core/ai-chat/ai-chat.service.lifecycle.spec.ts

@@ -1,5 +1,7 @@
 import { Logger } from '@nestjs/common';
-import { AiChatService } from './ai-chat.service';
+import { AiChatService, AiChatRunHooks } from './ai-chat.service';
+import { AiChatRunService } from './ai-chat-run.service';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
 
 /**
  * Lifecycle unit tests for AiChatService.onModuleInit (#183 crash-recovery
@@ -59,3 +61,97 @@ describe('AiChatService.onModuleInit (startup sweep)', () => {
     expect(String(warnSpy.mock.calls[0][0])).toContain('db unavailable');
   });
 });
+
+/**
+ * #184 CRITICAL run-lifecycle safety net (review fix). A transient failure
+ * AFTER a successful beginRun but BEFORE streamText's terminal callbacks own the
+ * lifecycle must STILL settle the run — otherwise the run row is stuck 'running'
+ * forever (sweepRunning only runs at startup) and the partial unique index + the
+ * controller pre-check 409 every future turn in that chat until a restart. Here
+ * we model the very first bare await after beginRun (the user-message insert)
+ * throwing, wiring the run hooks to a REAL AiChatRunService (mock repo) exactly
+ * as the controller does, and assert the run is settled to 'error' and its
+ * in-memory entry dropped (so a follow-up turn would NOT be 409'd).
+ */
+describe('AiChatService.stream run-lifecycle safety net (#184)', () => {
+  const user = { id: 'u1' } as User;
+  const workspace = { id: 'ws1' } as Workspace;
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('an exception after beginRun settles the run to error and drops the in-memory entry', async () => {
+    jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+
+    // Real run service over a mock repo, so finalizeRun's in-memory bookkeeping
+    // (active.delete) is exercised for real.
+    const runRepo = {
+      insert: jest.fn().mockResolvedValue({ id: 'run-1', status: 'running' }),
+      update: jest.fn().mockResolvedValue({ id: 'run-1' }),
+    };
+    const runService = new AiChatRunService(runRepo as never, { isCloud: () => false } as never);
+
+    // The user-message insert (the first bare await after beginRun) throws.
+    const aiChatMessageRepo = {
+      insert: jest.fn().mockRejectedValue(new Error('insert boom')),
+    };
+    const aiChatRepo = {
+      // Existing chat -> chatId stays, no new-chat insert path.
+      findById: jest.fn().mockResolvedValue({ id: 'chat-1', creatorId: 'u1' }),
+    };
+
+    const service = new AiChatService(
+      {} as never, // ai
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never, // aiSettings
+      {} as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+    );
+
+    const runHooks: AiChatRunHooks = {
+      begin: (chatId) =>
+        runService.beginRun({
+          chatId,
+          workspaceId: workspace.id,
+          userId: user.id,
+          trigger: 'user',
+        }),
+      onSettled: (runId, status, error) =>
+        runService.finalizeRun(runId, workspace.id, status, error),
+    };
+
+    await expect(
+      service.stream({
+        user,
+        workspace,
+        sessionId: 'sess',
+        body: {
+          chatId: 'chat-1',
+          messages: [
+            { id: 'm', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+          ],
+        },
+        res: {} as never,
+        signal: new AbortController().signal,
+        model: {} as never,
+        role: null,
+        runHooks,
+      }),
+    ).rejects.toThrow('insert boom');
+
+    // The run was begun...
+    expect(runRepo.insert).toHaveBeenCalledTimes(1);
+    // ...then settled to a terminal FAILED status by the safety net...
+    expect(runRepo.update).toHaveBeenCalledTimes(1);
+    expect(runRepo.update).toHaveBeenCalledWith(
+      'run-1',
+      'ws1',
+      expect.objectContaining({ status: 'failed' }),
+    );
+    // ...and the in-memory entry is gone, so a follow-up turn is NOT 409'd.
+    expect(runService.isLocallyActive('run-1')).toBe(false);
+  });
+});

apps/server/src/core/ai-chat/ai-chat.service.run-race.spec.ts

@@ -0,0 +1,483 @@
+import { ConflictException, Logger } from '@nestjs/common';
+
+// Mock the AI SDK so we can PROVE no provider call is made for the turn we are
+// about to reject. The race rejection happens at runHooks.begin(), long before
+// any streamText/generateText, so these never resolve a real model.
+jest.mock('ai', () => ({
+  streamText: jest.fn(),
+  generateText: jest.fn(),
+  convertToModelMessages: jest.fn(() => []),
+  stepCountIs: jest.fn(() => () => false),
+}));
+
+import { streamText, generateText } from 'ai';
+import { AiChatService } from './ai-chat.service';
+import { RunAlreadyActiveError } from './ai-chat-run.service';
+
+/**
+ * Race-closure coverage for the "one active run per chat" guard (#184).
+ *
+ * THE BUG: two simultaneous POST /ai-chat/stream on the same chat both pass the
+ * controller's cheap pre-check (TOCTOU), so the loser's run-row INSERT hits the
+ * partial unique index. Previously that 23505 was SWALLOWED and the second turn
+ * streamed UNTRACKED (no runId, not stoppable). THE FIX: beginRun surfaces a
+ * RunAlreadyActiveError and stream() turns it into a 409 BEFORE any AI call —
+ * the second turn never runs.
+ */
+describe('AiChatService.stream — concurrent-run race rejection (#184)', () => {
+  const streamTextMock = streamText as unknown as jest.Mock;
+  const generateTextMock = generateText as unknown as jest.Mock;
+
+  beforeEach(() => {
+    streamTextMock.mockReset();
+    generateTextMock.mockReset();
+  });
+
+  // Minimal service whose only reachable deps before begin() are aiChatRepo
+  // (resolve the existing chat) — everything past begin must remain untouched.
+  function makeService(beginImpl: () => Promise<unknown>) {
+    const aiChatMessageRepo = { insert: jest.fn() };
+    const aiChatRepo = {
+      // An existing chat: stream keeps the supplied chatId and skips creation.
+      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
+      insert: jest.fn(),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never, // aiSettings
+      {} as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+    );
+    const begin = jest.fn(beginImpl);
+    return { svc, begin, aiChatRepo, aiChatMessageRepo };
+  }
+
+  const baseArgs = (begin: jest.Mock) => ({
+    user: { id: 'user-1' } as never,
+    workspace: { id: 'ws-1' } as never,
+    sessionId: 'sess-1',
+    body: { chatId: 'chat-1', messages: [] } as never,
+    res: { raw: {} } as never,
+    signal: new AbortController().signal,
+    model: {} as never,
+    role: null,
+    runHooks: {
+      begin,
+      onAssistantSeeded: jest.fn(),
+      onStep: jest.fn(),
+      onSettled: jest.fn(),
+    } as never,
+  });
+
+  it('rejects the racer with a 409 ConflictException BEFORE any AI call, and never persists an untracked turn', async () => {
+    // begin loses the unique-index race -> RunAlreadyActiveError.
+    const { svc, begin, aiChatMessageRepo } = makeService(() => {
+      throw new RunAlreadyActiveError('chat-1');
+    });
+
+    const promise = svc.stream(baseArgs(begin));
+
+    await expect(promise).rejects.toBeInstanceOf(ConflictException);
+    await promise.catch((err: ConflictException) => {
+      expect(err.getStatus()).toBe(409);
+      expect((err.getResponse() as { code?: string }).code).toBe(
+        'A_RUN_ALREADY_ACTIVE',
+      );
+    });
+
+    // The decisive assertions: the rejected racer spent NO tokens and left NO
+    // untracked turn behind.
+    expect(begin).toHaveBeenCalledTimes(1);
+    expect(streamTextMock).not.toHaveBeenCalled();
+    expect(generateTextMock).not.toHaveBeenCalled();
+    expect(aiChatMessageRepo.insert).not.toHaveBeenCalled();
+  });
+});
+
+/**
+ * F3 — the LOAD-BEARING run-detach wiring: `effectiveSignal = handle.signal`
+ * after runHooks.begin, then `abortSignal: effectiveSignal` passed to streamText.
+ * That single line is what makes a run survive a browser disconnect (the agent
+ * loop's abort is governed by the RUN's signal, not the socket): a regression to
+ * the socket-bound signal would still pass every other test green while silently
+ * breaking Stop + durability. These two tests pin the exact signal streamText
+ * consumes on both paths.
+ */
+describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
+  const streamTextMock = streamText as unknown as jest.Mock;
+
+  // A streamText result stub: the post-call drain + pipe are no-ops here; we only
+  // care WHICH abortSignal streamText was handed.
+  function makeStreamResult() {
+    return {
+      consumeStream: jest.fn(),
+      pipeUIMessageStreamToResponse: jest.fn(),
+    };
+  }
+
+  // A raw-response stub sufficient for the post-streamText wiring
+  // (stripStreamingHopByHopHeaders binds writeHead; startSseHeartbeat registers
+  // close/finish listeners; flushHeaders is belt-and-braces).
+  function makeRes() {
+    return {
+      raw: {
+        writeHead: jest.fn(),
+        write: jest.fn(),
+        once: jest.fn(),
+        on: jest.fn(),
+        flushHeaders: jest.fn(),
+        writableEnded: false,
+        destroyed: false,
+      },
+    };
+  }
+
+  // Wire only the deps reached on the way to streamText: resolve the existing
+  // chat, persist the user + seed the assistant row, load (empty) history, the
+  // admin settings, an empty external toolset + Docmost toolset.
+  function makeService() {
+    const aiChatRepo = {
+      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
+      insert: jest.fn(),
+    };
+    const aiChatMessageRepo = {
+      insert: jest.fn(async () => ({ id: 'msg-1' })),
+      findAllByChat: jest.fn(async () => []),
+      update: jest.fn(async () => ({ id: 'msg-1' })),
+    };
+    const aiSettings = { resolve: jest.fn(async () => ({})) };
+    const tools = { forUser: jest.fn(async () => ({})) };
+    const mcpClients = {
+      toolsFor: jest.fn(async () => ({
+        tools: {},
+        clients: [],
+        outcomes: [],
+        instructions: [],
+      })),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      aiSettings as never,
+      tools as never,
+      mcpClients as never,
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo (openPage undefined -> never touched)
+      {} as never, // pageAccess
+    );
+    return { svc };
+  }
+
+  const body = {
+    chatId: 'chat-1',
+    messages: [
+      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+    ],
+  };
+
+  beforeEach(() => {
+    streamTextMock.mockReset();
+    streamTextMock.mockImplementation(() => makeStreamResult());
+    jest
+      .spyOn(Logger.prototype, 'log')
+      .mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('happy path (run-wrapped): streamText is driven with abortSignal === handle.signal (the RUN signal, NOT the socket)', async () => {
+    const { svc } = makeService();
+    const runController = new AbortController();
+    const runSignal = runController.signal;
+    const socketSignal = new AbortController().signal;
+
+    const begin = jest.fn(async () => ({ runId: 'run-1', signal: runSignal }));
+    await svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRes() as never,
+      signal: socketSignal,
+      model: {} as never,
+      role: null,
+      runHooks: {
+        begin,
+        onAssistantSeeded: jest.fn(),
+        onStep: jest.fn(),
+        onSettled: jest.fn(),
+      } as never,
+    });
+
+    expect(begin).toHaveBeenCalledTimes(1);
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    // THE assertion: the agent loop's abort is wired to the RUN, so a browser
+    // disconnect (which aborts only `socketSignal`) cannot end the turn.
+    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(runSignal);
+    expect(streamTextMock.mock.calls[0][0].abortSignal).not.toBe(socketSignal);
+  });
+
+  it('legacy path (no runHooks): streamText is driven with the SOCKET signal', async () => {
+    const { svc } = makeService();
+    const socketSignal = new AbortController().signal;
+
+    await svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRes() as never,
+      signal: socketSignal,
+      model: {} as never,
+      role: null,
+      // No runHooks -> the turn stays socket-bound (flag off / default).
+    });
+
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
+  });
+
+  /**
+   * F9 — streamText's TERMINAL callbacks carry the #184 run lifecycle:
+   *   onStepFinish -> runHooks.onStep(runId, stepCount)
+   *   onFinish     -> runHooks.onSettled(runId, 'completed')   (dominant path)
+   *   onAbort      -> runHooks.onSettled(runId, 'aborted')
+   *   onError      -> runHooks.onSettled(runId, 'error', cause)
+   * makeStreamResult() ignores the streamText options, so these callbacks never
+   * fire on their own — a regression in this wiring (esp. the success path) would
+   * strand the run with NO test catching it. Here we CAPTURE the options streamText
+   * was handed and invoke each callback with the real wiring, asserting the run
+   * hooks fire with the right args.
+   */
+  // Drive stream() to the point streamText is called, capturing the options object
+  // (which carries onStepFinish/onFinish/onError/onAbort) and the run hooks.
+  async function captureStreamCallbacks() {
+    const { svc } = makeService();
+    let capturedOpts: any;
+    streamTextMock.mockImplementation((opts: any) => {
+      capturedOpts = opts;
+      return makeStreamResult();
+    });
+    const runHooks = {
+      begin: jest.fn(async () => ({
+        runId: 'run-1',
+        signal: new AbortController().signal,
+      })),
+      onAssistantSeeded: jest.fn(),
+      onStep: jest.fn(),
+      onSettled: jest.fn(),
+    };
+    await svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: runHooks as never,
+    });
+    expect(capturedOpts).toBeDefined();
+    return { capturedOpts, runHooks };
+  }
+
+  it('F9: onStepFinish bumps the run step count, onFinish settles the run "completed" (the dominant autonomous-run path)', async () => {
+    const { capturedOpts, runHooks } = await captureStreamCallbacks();
+
+    // A finished step -> onStep(runId, finishedStepCount).
+    capturedOpts.onStepFinish({ text: 'step one', toolCalls: [], content: [] });
+    expect(runHooks.onStep).toHaveBeenCalledWith('run-1', 1);
+    capturedOpts.onStepFinish({ text: 'step two', toolCalls: [], content: [] });
+    expect(runHooks.onStep).toHaveBeenLastCalledWith('run-1', 2);
+
+    // The success terminal callback settles the run.
+    await capturedOpts.onFinish({
+      text: 'done',
+      finishReason: 'stop',
+      totalUsage: {},
+      usage: {},
+      steps: [],
+    });
+    expect(runHooks.onSettled).toHaveBeenCalledWith('run-1', 'completed');
+  });
+
+  it('F9: onAbort settles the run "aborted"', async () => {
+    jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, runHooks } = await captureStreamCallbacks();
+
+    await capturedOpts.onAbort({ steps: [] });
+    expect(runHooks.onSettled).toHaveBeenCalledWith('run-1', 'aborted');
+  });
+
+  it('F9: onError settles the run "error" carrying the provider cause', async () => {
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, runHooks } = await captureStreamCallbacks();
+
+    await capturedOpts.onError({ error: new Error('provider exploded') });
+    expect(runHooks.onSettled).toHaveBeenCalledWith(
+      'run-1',
+      'error',
+      expect.stringContaining('provider exploded'),
+    );
+  });
+});
+
+/**
+ * F14 — the begin-failure RESILIENCE branch (the `else` of the run-race guard).
+ *
+ * stream() wraps runHooks.begin in try/catch with TWO branches:
+ *   - RunAlreadyActiveError  -> 409 ConflictException (pinned above).
+ *   - ANY OTHER begin failure -> SWALLOW + continue UNTRACKED on the socket signal
+ *     (legacy fallback): it logs "...streaming without run tracking", leaves
+ *     `effectiveSignal = signal` (runId undefined) and serves the turn anyway.
+ *
+ * The contract: a transient beginRun failure (e.g. a non-unique DB error inserting
+ * the run row) must STILL serve the user's turn — it must NOT re-throw and must NOT
+ * be misclassified as a 409. A regression that re-threw here would break EVERY turn
+ * on a begin failure with nothing to catch it. This branch is otherwise undriven by
+ * any spec, so it is pinned here SEPARATELY from the 409 path: a plain begin error
+ * proceeds to streamText with the SOCKET signal and still persists the user turn.
+ */
+describe('AiChatService.stream — begin-failure resilience / legacy fallback (#184 F14)', () => {
+  const streamTextMock = streamText as unknown as jest.Mock;
+
+  function makeStreamResult() {
+    return {
+      consumeStream: jest.fn(),
+      pipeUIMessageStreamToResponse: jest.fn(),
+    };
+  }
+
+  function makeRes() {
+    return {
+      raw: {
+        writeHead: jest.fn(),
+        write: jest.fn(),
+        once: jest.fn(),
+        on: jest.fn(),
+        flushHeaders: jest.fn(),
+        writableEnded: false,
+        destroyed: false,
+      },
+    };
+  }
+
+  // Same harness as the F3 abortSignal block, but it also exposes
+  // aiChatMessageRepo so we can assert the user turn IS persisted (the turn really
+  // streamed) despite begin() blowing up.
+  function makeService() {
+    const aiChatRepo = {
+      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
+      insert: jest.fn(),
+    };
+    const aiChatMessageRepo = {
+      insert: jest.fn(async () => ({ id: 'msg-1' })),
+      findAllByChat: jest.fn(async () => []),
+      update: jest.fn(async () => ({ id: 'msg-1' })),
+    };
+    const aiSettings = { resolve: jest.fn(async () => ({})) };
+    const tools = { forUser: jest.fn(async () => ({})) };
+    const mcpClients = {
+      toolsFor: jest.fn(async () => ({
+        tools: {},
+        clients: [],
+        outcomes: [],
+        instructions: [],
+      })),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      aiSettings as never,
+      tools as never,
+      mcpClients as never,
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+    );
+    return { svc, aiChatMessageRepo };
+  }
+
+  const body = {
+    chatId: 'chat-1',
+    messages: [
+      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+    ],
+  };
+
+  beforeEach(() => {
+    streamTextMock.mockReset();
+    streamTextMock.mockImplementation(() => makeStreamResult());
+    jest
+      .spyOn(Logger.prototype, 'log')
+      .mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('a PLAIN begin() failure (NOT RunAlreadyActiveError) does NOT 409 — it swallows, logs, and streams the turn UNTRACKED on the socket signal', async () => {
+    const errorSpy = jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+
+    const { svc, aiChatMessageRepo } = makeService();
+    const socketSignal = new AbortController().signal;
+
+    // A transient, NON-race begin failure (e.g. a non-unique DB error inserting
+    // the run row). This is the `else` branch of the begin try/catch.
+    const begin = jest.fn(async () => {
+      throw new Error('insert failed');
+    });
+
+    const promise = svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRes() as never,
+      signal: socketSignal,
+      model: {} as never,
+      role: null,
+      runHooks: {
+        begin,
+        onAssistantSeeded: jest.fn(),
+        onStep: jest.fn(),
+        onSettled: jest.fn(),
+      } as never,
+    });
+
+    // The turn proceeds: NO throw at all (in particular NOT a 409).
+    await expect(promise).resolves.toBeUndefined();
+
+    expect(begin).toHaveBeenCalledTimes(1);
+
+    // The resilience branch logged the legacy-fallback warning.
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('streaming without run tracking'),
+      expect.anything(),
+    );
+
+    // The turn really streamed: the user message was persisted and streamText ran.
+    expect(aiChatMessageRepo.insert).toHaveBeenCalled();
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+
+    // The decisive wiring: with no run handle, the fallback uses the SOCKET signal
+    // (effectiveSignal = signal, runId undefined) — not a run-bound signal.
+    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
+  });
+});

apps/server/src/core/ai-chat/ai-chat.service.spec.ts

@@ -371,6 +371,12 @@ describe('chatStreamMetadata', () => {
     });
   });
 
+  it('attaches the runId on the start part when a run wraps the turn (#184)', () => {
+    expect(
+      chatStreamMetadata({ type: 'start' }, 'chat-1', undefined, 'run-1'),
+    ).toEqual({ chatId: 'chat-1', runId: 'run-1' });
+  });
+
   it('returns the CUMULATIVE step usage passed in for the finish-step part', () => {
     // finish-step usage is per-step in v6; the caller accumulates and passes the
     // running sum, which this just wraps.

apps/server/src/core/ai-chat/dto/ai-chat.dto.ts

@@ -43,6 +43,30 @@ export class BoundChatDto {
   pageId: string;
 }
 
+/**
+ * Reconnect to the latest run of a chat (#184): fetch its persisted lifecycle
+ * state (and the assistant message it projects) for an in-flight or finished run.
+ */
+export class GetRunDto {
+  @IsString()
+  chatId: string;
+}
+
+/**
+ * Explicitly STOP an agent run (#184): the user pressed Stop — distinct from a
+ * browser disconnect, which never stops a run. Either the run id (preferred, from
+ * the streamed start metadata) or the chat id (stop whatever run is active on it).
+ */
+export class StopRunDto {
+  @IsOptional()
+  @IsString()
+  runId?: string;
+
+  @IsOptional()
+  @IsString()
+  chatId?: string;
+}
+
 /** Export a chat to Markdown (#183). `lang` localizes the few fixed
  *  role/tool-action labels; defaults to English server-side. */
 export class ExportChatDto {

apps/server/src/core/ai-chat/roles/ai-agent-roles.service.ts

@@ -187,7 +187,7 @@ export class AiAgentRolesService {
   }
 
   // -------------------------------------------------------------------------
-  // Catalog (admin-only). The catalog is curated, untrusted YAML fetched +
+  // Catalog (admin-only). The catalog is curated, untrusted JSON fetched +
   // validated by AiAgentRolesCatalogProvider; this layer resolves localized
   // text and reconciles a bundle against the workspace's existing roles.
   // -------------------------------------------------------------------------

apps/server/src/core/ai-chat/roles/catalog/ai-agent-roles-catalog.provider.spec.ts

@@ -1,23 +1,12 @@
 import { BadGatewayException, BadRequestException } from '@nestjs/common';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import {
-  AiAgentRolesCatalogProvider,
-  isCatalogBundleFile,
-  isCatalogIndex,
-  isCatalogRole,
-} from './ai-agent-roles-catalog.provider';
+import { AiAgentRolesCatalogProvider } from './ai-agent-roles-catalog.provider';
 
 /**
  * Provider tests against a mocked remote source (no network). They cover the
- * happy read path (fetchIndex / fetchBundle) over the YAML catalog format, the
- * block-scalar `instructions` round-trip, the malformed-shape rejection, the
- * malformed-YAML rejection, rejection of non-http(s) sources (local sources are
- * gone), and — most importantly — the `^[a-z0-9-]+$` path-traversal guard that
- * runs BEFORE any path/URL is built. Fixtures are serialized with the same
- * `yaml` library the provider parses with (`stringifyYaml`), so the tests
- * exercise real YAML, not the JSON subset.
+ * happy read path (fetchIndex / fetchBundle), the malformed-shape rejection,
+ * rejection of non-http(s) sources (local sources are gone), and — most
+ * importantly — the `^[a-z0-9-]+$` path-traversal guard that runs BEFORE any
+ * path/URL is built.
  */
 describe('AiAgentRolesCatalogProvider', () => {
   function makeProvider(source: string) {
@@ -82,7 +71,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     }
 
     it('fetchBundle remote happy path => parses + validates', async () => {
-      const yaml = stringifyYaml({
+      const json = JSON.stringify({
         schemaVersion: 1,
         language: 'en',
         roles: [
@@ -93,7 +82,7 @@ describe('AiAgentRolesCatalogProvider', () => {
           },
         ],
       });
-      const body = streamOf([new TextEncoder().encode(yaml)]);
+      const body = streamOf([new TextEncoder().encode(json)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -103,12 +92,12 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('fetchBundle remote malformed (role missing instructions) => BadGateway', async () => {
-      const yaml = stringifyYaml({
+      const json = JSON.stringify({
         schemaVersion: 1,
         language: 'fr',
         roles: [{ slug: 'researcher', name: 'Chercheur' }],
       });
-      const body = streamOf([new TextEncoder().encode(yaml)]);
+      const body = streamOf([new TextEncoder().encode(json)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -164,9 +153,8 @@ describe('AiAgentRolesCatalogProvider', () => {
         );
       global.fetch = fetchMock as never;
       const provider = makeProvider('https://catalog.example.com');
-      // Body shape is irrelevant; an empty stream parses to an empty YAML doc
-      // (null), fails the shape guard and throws, but the fetch call (with its
-      // init) still happened.
+      // Body shape is irrelevant; an empty stream parses to invalid JSON and
+      // throws, but the fetch call (with its init) still happened.
       await expect(provider.fetchIndex()).rejects.toBeDefined();
       expect(fetchMock).toHaveBeenCalledWith(
         expect.any(String),
@@ -202,7 +190,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('small streamed body parses normally (cap not hit)', async () => {
-      const yaml = stringifyYaml({
+      const json = JSON.stringify({
         schemaVersion: 1,
         bundles: [
           {
@@ -213,7 +201,7 @@ describe('AiAgentRolesCatalogProvider', () => {
           },
         ],
       });
-      const body = streamOf([new TextEncoder().encode(yaml)]);
+      const body = streamOf([new TextEncoder().encode(json)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -239,7 +227,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('null body (no readable stream) => response.text() fallback parses', async () => {
-      const yaml = stringifyYaml({
+      const json = JSON.stringify({
         schemaVersion: 1,
         bundles: [
           {
@@ -252,7 +240,7 @@ describe('AiAgentRolesCatalogProvider', () => {
       });
       global.fetch = jest
         .fn()
-        .mockResolvedValue(mockResponse({ body: null, text: yaml })) as never;
+        .mockResolvedValue(mockResponse({ body: null, text: json })) as never;
       const provider = makeProvider('https://catalog.example.com');
       const index = await provider.fetchIndex();
       expect(index.bundles[0].id).toBe('general');
@@ -271,12 +259,8 @@ describe('AiAgentRolesCatalogProvider', () => {
       );
     });
 
-    it('invalid YAML body => BadGateway (parse failure)', async () => {
-      // An unterminated flow mapping is not valid YAML, so YAML.parse throws and
-      // the provider maps it to BadGateway (not a generic 500).
-      const body = streamOf([
-        new TextEncoder().encode('schemaVersion: {not: closed'),
-      ]);
+    it('invalid JSON body => BadGateway (parse failure)', async () => {
+      const body = streamOf([new TextEncoder().encode('{not valid json')]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -286,28 +270,11 @@ describe('AiAgentRolesCatalogProvider', () => {
       );
     });
 
-    it('YAML with a duplicate key (strict) => BadGateway (parse failure)', async () => {
-      // strict:true rejects duplicate mapping keys rather than last-wins coercing
-      // them — a defensive parse on untrusted input.
+    it('malformed index.json (valid JSON, wrong shape) => BadGateway', async () => {
+      // Parses as JSON but fails isCatalogIndex (schemaVersion not a number).
       const body = streamOf([
         new TextEncoder().encode(
-          'schemaVersion: 1\nbundles: []\nschemaVersion: 2\n',
-        ),
-      ]);
-      global.fetch = jest
-        .fn()
-        .mockResolvedValue(mockResponse({ body })) as never;
-      const provider = makeProvider('https://catalog.example.com');
-      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
-        BadGatewayException,
-      );
-    });
-
-    it('malformed index.yaml (valid YAML, wrong shape) => BadGateway', async () => {
-      // Parses as YAML but fails isCatalogIndex (schemaVersion not a number).
-      const body = streamOf([
-        new TextEncoder().encode(
-          stringifyYaml({ schemaVersion: 'x', bundles: [] }),
+          JSON.stringify({ schemaVersion: 'x', bundles: [] }),
         ),
       ]);
       global.fetch = jest
@@ -316,36 +283,6 @@ describe('AiAgentRolesCatalogProvider', () => {
       const provider = makeProvider('https://catalog.example.com');
       await expect(provider.fetchIndex()).rejects.toThrow(/malformed/i);
     });
-
-    it('block-scalar instructions round-trips to the exact multi-line string', async () => {
-      // The whole point of the YAML migration: a long `instructions` prompt is
-      // stored as a literal block scalar (|-) for line-by-line diffs, and must
-      // resolve byte-for-byte to the original multi-line string.
-      const instructions = [
-        'Line one of the prompt.',
-        '',
-        '  Indented bullet that must survive.',
-        'Final line, no trailing newline.',
-      ].join('\n');
-      const yaml = stringifyYaml(
-        {
-          schemaVersion: 1,
-          language: 'en',
-          roles: [{ slug: 'researcher', name: 'Researcher', instructions }],
-        },
-        { lineWidth: 0 },
-      );
-      // Sanity: the fixture really uses a literal block scalar (|, optionally
-      // with an indentation indicator), not a flow/quoted string.
-      expect(yaml).toMatch(/instructions: \|/);
-      const body = streamOf([new TextEncoder().encode(yaml)]);
-      global.fetch = jest
-        .fn()
-        .mockResolvedValue(mockResponse({ body })) as never;
-      const provider = makeProvider('https://catalog.example.com');
-      const bundle = await provider.fetchBundle('research', 'en');
-      expect(bundle.roles[0].instructions).toBe(instructions);
-    });
   });
 
   describe('path-traversal / SSRF guard (^[a-z0-9-]+$)', () => {
@@ -367,93 +304,4 @@ describe('AiAgentRolesCatalogProvider', () => {
       });
     }
   });
-
-  // ---------------------------------------------------------------------------
-  // Pin the REAL shipped catalog files (not synthetic fixtures). The JSON->YAML
-  // migration was a hand conversion, so the realistic failure is a hand-edit
-  // error in one of the 5 content YAML files (the index + the four per-bundle/
-  // lang files: index.yaml plus bundles/{editorial,research}/{en,ru}.yaml) — a
-  // quote/colon in a description, a broken
-  // emoji/arrow, a block-scalar indent slip that silently changes or drops
-  // instructions). Nothing else in CI parses these files — `scripts/check.mjs`
-  // is not wired into any turbo/husky/CI step — so this is the only automated
-  // guard over the shipped content. We read them straight off disk, parse with
-  // the SAME options the provider uses (strict + maxAliasCount, see parseYaml in
-  // the provider), and run them through the provider's own type guards. A future
-  // edit that breaks a real file fails here.
-  // ---------------------------------------------------------------------------
-  describe('real shipped catalog files (the YAML migration must not break them)', () => {
-    // Spec lives at apps/server/src/core/ai-chat/roles/catalog/; the catalog
-    // ships at the repo root (agent-roles-catalog/) — seven levels up.
-    const CATALOG_DIR = join(
-      __dirname,
-      '../../../../../../../agent-roles-catalog',
-    );
-    // Match the provider's parseYaml exactly (untrusted-input parse options).
-    const PARSE_OPTS = { strict: true, maxAliasCount: 100 } as const;
-
-    function readCatalogYaml(rel: string): unknown {
-      return parseYaml(readFileSync(join(CATALOG_DIR, rel), 'utf8'), PARSE_OPTS);
-    }
-
-    // Load + validate the real index lazily (only when a test runs), so a broken
-    // real file fails ONLY these catalog tests — not collection of the entire
-    // spec, which also holds the unrelated mocked-remote provider tests above.
-    function loadRealIndex() {
-      const parsed = readCatalogYaml('index.yaml');
-      if (!isCatalogIndex(parsed)) {
-        throw new Error('Real index.yaml is not a valid catalog index');
-      }
-      return parsed;
-    }
-
-    it('index.yaml parses + validates with the provider guard', () => {
-      expect(isCatalogIndex(readCatalogYaml('index.yaml'))).toBe(true);
-    });
-
-    it('editorial bundle still ships the fact-checker role', () => {
-      const editorial = loadRealIndex().bundles.find((b) => b.id === 'editorial');
-      expect(editorial).toBeDefined();
-      expect(editorial?.roles.map((r) => r.slug)).toContain('fact-checker');
-    });
-
-    // Driven by the real index (read inside the test, so it's lazy): every
-    // declared bundle + language file must parse, validate, and be in EXACT slug
-    // correspondence with the index — every declared role present AND no
-    // undeclared extras — mirroring scripts/check.mjs, which requires both
-    // directions. A bundle or language added later is covered automatically.
-    it('every declared bundle/language file is valid and in exact slug correspondence', () => {
-      const index = loadRealIndex();
-      // Guard against an empty index silently passing the loops below.
-      expect(index.bundles.length).toBeGreaterThan(0);
-      for (const bundle of index.bundles) {
-        const declaredSlugs = bundle.roles.map((r) => r.slug);
-        expect(bundle.languages.length).toBeGreaterThan(0);
-        for (const lang of bundle.languages) {
-          const rel = `bundles/${bundle.id}/${lang}.yaml`;
-          const file = readCatalogYaml(rel);
-          expect(isCatalogBundleFile(file)).toBe(true);
-          // Narrow for TS and access fields safely.
-          if (!isCatalogBundleFile(file)) continue;
-          expect(file.language).toBe(lang);
-          const fileSlugs = file.roles.map((r) => r.slug);
-          // Existing direction: every declared role is present in the file.
-          for (const slug of declaredSlugs) {
-            expect(fileSlugs).toContain(slug);
-          }
-          // Symmetric direction: the file carries NO undeclared/extra roles, so
-          // file slugs and declared slugs must be the SAME set (exact match).
-          // Catches a hand-edit that copies a stray role into a bundle file.
-          expect([...fileSlugs].sort()).toEqual([...declaredSlugs].sort());
-          expect(file.roles.length).toBeGreaterThan(0);
-          for (const role of file.roles) {
-            expect(isCatalogRole(role)).toBe(true);
-            expect(typeof role.instructions).toBe('string');
-            expect(role.instructions.trim().length).toBeGreaterThan(0);
-            expect(role.name.trim().length).toBeGreaterThan(0);
-          }
-        }
-      }
-    });
-  });
 });

apps/server/src/core/ai-chat/roles/catalog/ai-agent-roles-catalog.provider.ts

@@ -4,7 +4,6 @@ import {
   Injectable,
   Logger,
 } from '@nestjs/common';
-import { parse as parseYamlDoc } from 'yaml';
 import { EnvironmentService } from '../../../../integrations/environment/environment.service';
 import {
   CatalogBundleFile,
@@ -29,11 +28,9 @@ const MAX_BYTES = 1_000_000;
  * base URL — REMOTE only; local-filesystem sources are no longer supported. The
  * value is baked into the Docker image at build time (set per-branch in CI).
  *
- * The catalog is UNTRUSTED input: every file is YAML-parsed with a SAFE schema
- * (standard JSON-compatible tags only — no custom `!!` tags / no code execution)
- * and run through a hand-written type guard before any field is exposed, and
- * every dynamic path segment is validated against SEGMENT_RE up front
- * (path-traversal + SSRF).
+ * The catalog is UNTRUSTED input: every file is JSON-parsed and run through a
+ * hand-written type guard before any field is exposed, and every dynamic path
+ * segment is validated against SEGMENT_RE up front (path-traversal + SSRF).
  */
 @Injectable()
 export class AiAgentRolesCatalogProvider {
@@ -41,19 +38,19 @@ export class AiAgentRolesCatalogProvider {
 
   constructor(private readonly environmentService: EnvironmentService) {}
 
-  /** Read + validate the top-level index (`index.yaml`). */
+  /** Read + validate the top-level index (`index.json`). */
   async fetchIndex(): Promise<CatalogIndex> {
-    const raw = await this.readRelative('index.yaml');
-    const parsed = this.parseYaml(raw, 'index.yaml');
+    const raw = await this.readRelative('index.json');
+    const parsed = this.parseJson(raw, 'index.json');
     if (!isCatalogIndex(parsed)) {
       throw new BadGatewayException(
-        'Agent roles catalog index is malformed (index.yaml)',
+        'Agent roles catalog index is malformed (index.json)',
       );
     }
     return parsed;
   }
 
-  /** Read + validate one language file (`bundles/<bundleId>/<language>.yaml`). */
+  /** Read + validate one language file (`bundles/<bundleId>/<language>.json`). */
   async fetchBundle(
     bundleId: string,
     language: string,
@@ -61,9 +58,9 @@ export class AiAgentRolesCatalogProvider {
     // SECURITY: validate BEFORE building any path/URL (path-traversal + SSRF).
     this.assertSegment(bundleId, 'bundleId');
     this.assertSegment(language, 'language');
-    const rel = `bundles/${bundleId}/${language}.yaml`;
+    const rel = `bundles/${bundleId}/${language}.json`;
     const raw = await this.readRelative(rel);
-    const parsed = this.parseYaml(raw, rel);
+    const parsed = this.parseJson(raw, rel);
     if (!isCatalogBundleFile(parsed)) {
       throw new BadGatewayException(
         `Agent roles catalog bundle is malformed (${rel})`,
@@ -79,29 +76,15 @@ export class AiAgentRolesCatalogProvider {
     }
   }
 
-  /**
-   * Safe YAML parse with a clear BadGateway on malformed content. The catalog is
-   * untrusted, so we lean on the `yaml` library's default `core` schema, which
-   * only produces JSON-compatible values (objects/arrays/strings/numbers/
-   * booleans/null) and NEVER constructs arbitrary types or runs code — there is
-   * no `!!js`-style tag handling. `strict: true` rejects duplicate keys instead
-   * of silently coercing them. (Note: in yaml@2.8.x an unknown custom tag does
-   * NOT throw even under `strict` — the parser logs a warning and resolves the
-   * node to a plain scalar; the catalog stays safe because the default schema
-   * never builds arbitrary types from a tag and our hand-written type guards
-   * reject any value of the wrong shape.) The alias-expansion guard
-   * (`maxAliasCount`) bounds billion-laughs blow-ups (the 1 MB streaming
-   * cap already limits the input itself). JSON is a YAML subset, so a leftover
-   * `.json`-style body still parses here too.
-   */
-  private parseYaml(raw: string, rel: string): unknown {
+  /** JSON.parse with a clear BadGateway on malformed content. */
+  private parseJson(raw: string, rel: string): unknown {
     try {
-      return parseYamlDoc(raw, { strict: true, maxAliasCount: 100 });
+      return JSON.parse(raw);
     } catch (err) {
       const reason = shortError(err);
-      this.logger.error(`Agent roles catalog YAML parse failed (${rel}): ${reason}`);
+      this.logger.error(`Agent roles catalog JSON parse failed (${rel}): ${reason}`);
       throw new BadGatewayException(
-        `Agent roles catalog file is not valid YAML (${rel}): ${reason}`,
+        `Agent roles catalog file is not valid JSON (${rel}): ${reason}`,
       );
     }
   }

apps/server/src/core/ai-chat/roles/catalog/catalog-types.ts

@@ -1,8 +1,7 @@
 /**
- * Catalog wire shapes. The catalog is curated, untrusted YAML (a GitHub repo or
+ * Catalog wire shapes. The catalog is curated, untrusted JSON (a GitHub repo or
  * a local folder), so every shape is validated by a hand-written type guard in
- * the provider before any field is used — no zod on the server (YAML is parsed
- * with the `yaml` library's safe, JSON-compatible schema).
+ * the provider before any field is used — no zod / new deps on the server.
  *
  * Localized fields (`name` / `description` at the bundle level) are
  * `Record<language, string>` so one bundle serves many UI languages; per-role
@@ -23,7 +22,7 @@ export interface CatalogRole {
   modelConfig?: Record<string, unknown> | null;
 }
 
-/** A single language file: `bundles/<id>/<language>.yaml`. */
+/** A single language file: `bundles/<id>/<language>.json`. */
 export interface CatalogBundleFile {
   schemaVersion: number;
   language: string;
@@ -41,7 +40,7 @@ export interface CatalogBundleMeta {
   roles: { slug: string; version: number }[];
 }
 
-/** Top-level catalog index: `index.yaml`. */
+/** Top-level catalog index: `index.json`. */
 export interface CatalogIndex {
   schemaVersion: number;
   bundles: CatalogBundleMeta[];

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.spec.ts

@@ -63,12 +63,6 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
-      // even though these tests never execute it — return a no-op sink so the
-      // tool wiring in forUser() succeeds.
-      {
-        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
-      } as never,
     );
   });
 
@@ -181,12 +175,6 @@ describe('AiChatToolsService expanded toolset guardrails', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
-      // even though these tests never execute it — return a no-op sink so the
-      // tool wiring in forUser() succeeds.
-      {
-        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
-      } as never,
     );
   });
 
@@ -302,12 +290,6 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
-      // even though these tests never execute it — return a no-op sink so the
-      // tool wiring in forUser() succeeds.
-      {
-        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
-      } as never,
     );
   });
 
@@ -458,12 +440,6 @@ describe('AiChatToolsService model-friendly input validation (#190)', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
-      // even though these tests never execute it — return a no-op sink so the
-      // tool wiring in forUser() succeeds.
-      {
-        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
-      } as never,
     );
   });
 

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -16,7 +16,6 @@ import {
 import { resolveCurrentPageResult } from './current-page.util';
 import { parseNodeArg } from './parse-node-arg';
 import { modelFriendlyInput } from './model-friendly-input';
-import { SandboxStore } from '../../../integrations/sandbox/sandbox.store';
 
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -42,8 +41,6 @@ export class AiChatToolsService {
     private readonly pageEmbeddingRepo: PageEmbeddingRepo,
     private readonly spaceMemberRepo: SpaceMemberRepo,
     private readonly pagePermissionRepo: PagePermissionRepo,
-    // Shared singleton in-RAM blob store backing the stash tool.
-    private readonly sandboxStore: SandboxStore,
   ) {}
 
   async forUser(
@@ -89,17 +86,11 @@ export class AiChatToolsService {
         aiChatId,
       });
 
-    // Bind the stash tool to the shared in-RAM SandboxStore. The store owns the
-    // anonymous-URL composition (putAndLink) and the live/evict probes the MCP
-    // package needs to keep its mirror counts honest under FIFO eviction (the
-    // package never touches env or the store). asSink() centralizes the uri↔id
-    // mapping next to putAndLink, shared with the embedded-MCP wiring site.
     const { DocmostClient, sharedToolSpecs } = await loadDocmostMcp();
     const client: DocmostClientLike = new DocmostClient({
       apiUrl,
       getToken,
       getCollabToken,
-      sandbox: this.sandboxStore.asSink(),
     });
 
     // Build an ai-SDK tool from a shared, zod-agnostic spec. The spec owns the
@@ -634,14 +625,6 @@ export class AiChatToolsService {
         async ({ pageId, edits }) => await client.editPageText(pageId, edits),
       ),
 
-      // Returns ONLY the short link object — never the document body — so a
-      // large page can be handed to an external consumer without bloating
-      // context.
-      stashPage: sharedTool(
-        sharedToolSpecs.stashPage,
-        async ({ pageId }) => await client.stashPage(pageId),
-      ),
-
       patchNode: tool({
         description:
           'Replace a single content block (by id) with a new ProseMirror ' +

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -154,14 +154,6 @@ export interface DocmostClientLike {
     commentId: string,
     resolved: boolean,
   ): Promise<Record<string, unknown>>;
-  // Serialize a page + mirror its internal images into the blob sandbox; returns
-  // ONLY a short anonymous URL (the body never enters the model context).
-  stashPage(pageId: string): Promise<{
-    uri: string;
-    sha256: string;
-    size: number;
-    images: { mirrored: number; failed: number };
-  }>;
 }
 
 export type DocmostClientConfig = {
@@ -169,18 +161,6 @@ export type DocmostClientConfig = {
   getToken: () => Promise<string>;
   // Provenance collab-token provider for content mutations (signed agent claim).
   getCollabToken?: () => Promise<string>;
-  // Optional blob-sandbox sink for the stash tool. `put` stores a blob in the
-  // host's in-RAM SandboxStore and returns the anonymous read URL + integrity.
-  // The optional `has`/`evict` probes let stashPage keep its mirror counts
-  // honest under the store's FIFO eviction (mirror of the package's sink type).
-  sandbox?: {
-    put: (
-      buf: Buffer,
-      mime: string,
-    ) => { uri: string; sha256: string; size: number };
-    has?: (uri: string) => boolean;
-    evict?: (uri: string) => void;
-  };
 };
 
 export interface DocmostClientCtor {

apps/server/src/database/database.module.ts

@@ -31,6 +31,7 @@ import { FavoriteRepo } from '@docmost/db/repos/favorite/favorite.repo';
 import { TemplateRepo } from '@docmost/db/repos/template/template.repo';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
 import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
 import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
 import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
@@ -104,6 +105,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
+    AiChatRunRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,
     AiAgentRoleRepo,
@@ -137,6 +139,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
+    AiChatRunRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,
     AiAgentRoleRepo,

apps/server/src/database/migrations/20260627T130000-ai-chat-runs.ts

@@ -0,0 +1,104 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * `ai_chat_runs` — the agent RUN as a first-class, server-side lifecycle object
+ * (#184 phase 1: autonomous agent runs detached from the browser window).
+ *
+ * Until now an agent turn lived ONLY as long as the HTTP request was open
+ * (`res.hijack()` in ai-chat.controller.ts); a browser disconnect aborted it.
+ * This table makes a turn a persistent object the server owns: it is created
+ * when a run starts, transitions pending -> running -> succeeded|failed|aborted,
+ * and survives the subscriber (browser) going away. The DB is the source of
+ * truth — a later client reconnects/sees the result by reading this row plus the
+ * assistant message it projects (`assistant_message_id`).
+ *
+ * The assistant message row (#183 step-granular durability) is the PROJECTION of
+ * a run's output; this row is the run's LIFECYCLE. They are linked by
+ * `assistant_message_id` (SET NULL if the message is later pruned).
+ *
+ * `status`  : 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'.
+ * `trigger` : 'user' | 'autostart' | 'schedule' | 'api' | 'continue' — only
+ *             'user' is produced in phase 1; the others are reserved for the
+ *             autonomy triggers deferred to phase 2 so they need no later
+ *             migration.
+ *
+ * ONE ACTIVE RUN PER CHAT is enforced by a partial unique index on `chat_id`
+ * WHERE status IN ('pending','running'): an autonomous run and a user run can
+ * never trample each other on the same chat. Settled runs (succeeded/failed/
+ * aborted) are excluded from the index so a chat can accumulate any number of
+ * historical runs.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('ai_chat_runs')
+    .ifNotExists()
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('chat_id', 'uuid', (col) =>
+      col.references('ai_chats.id').onDelete('cascade').notNull(),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    // The human who triggered the run (audit). SET NULL on user deletion so the
+    // run history outlives its author; NULL is also the natural value for a
+    // future system/cron/api trigger with no human actor.
+    .addColumn('created_by', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    // The assistant message this run materializes (the #183 projection). SET NULL
+    // if that message row is later deleted; nullable because the run row is
+    // created a moment BEFORE the assistant row is seeded.
+    .addColumn('assistant_message_id', 'uuid', (col) =>
+      col.references('ai_chat_messages.id').onDelete('set null'),
+    )
+    .addColumn('trigger', 'varchar(20)', (col) =>
+      col.notNull().defaultTo('user'),
+    )
+    .addColumn('status', 'varchar(20)', (col) =>
+      col.notNull().defaultTo('pending'),
+    )
+    // Terminal error message for a failed run (provider/transport cause),
+    // mirroring the assistant message's metadata.error.
+    .addColumn('error', 'text', (col) => col)
+    // Number of agent steps finished so far (kept monotonic with the projection).
+    .addColumn('step_count', 'integer', (col) => col.notNull().defaultTo(0))
+    // Set when an EXPLICIT user stop is requested (distinct from a mere browser
+    // disconnect, which never stops a run). The runner aborts the turn and the
+    // run settles as 'aborted'.
+    .addColumn('stop_requested_at', 'timestamptz', (col) => col)
+    .addColumn('started_at', 'timestamptz', (col) => col)
+    .addColumn('finished_at', 'timestamptz', (col) => col)
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .execute();
+
+  // Reconnect / "latest run for this chat" reads hit chat_id first.
+  await db.schema
+    .createIndex('ai_chat_runs_chat_id_idx')
+    .ifNotExists()
+    .on('ai_chat_runs')
+    .column('chat_id')
+    .execute();
+
+  // One ACTIVE run per chat (advisory at the DB level): a second pending/running
+  // run on the same chat is rejected, so a user turn and an autonomous turn can
+  // never race on the same chat. Partial so settled runs do not collide.
+  await db.schema
+    .createIndex('ai_chat_runs_one_active_per_chat')
+    .ifNotExists()
+    .on('ai_chat_runs')
+    .column('chat_id')
+    .unique()
+    .where(sql.ref('status'), 'in', sql`('pending','running')`)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('ai_chat_runs').execute();
+}

apps/server/src/database/repos/ai-chat/ai-chat-message.repo.ts

@@ -121,6 +121,23 @@ export class AiChatMessageRepo {
     return rows.reverse();
   }
 
+  /** Fetch a single message by id + workspace (e.g. a run's projection row for
+   *  the #184 reconnect read). Returns undefined when nothing matches. */
+  async findById(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatMessage | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('aiChatMessages')
+      .select(this.baseFields)
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst();
+  }
+
   async insert(
     insertable: InsertableAiChatMessage,
     trx?: KyselyTransaction,

apps/server/src/database/repos/ai-chat/ai-chat-run.repo.spec.ts

@@ -0,0 +1,84 @@
+import { AiChatRunRepo, SWEEP_RUN_STALE_MS } from './ai-chat-run.repo';
+import type { KyselyDB } from '../../types/kysely.types';
+
+/**
+ * Unit coverage for AiChatRunRepo.sweepRunning over a chainable builder mock (no
+ * live DB). The F1 invariant under test (DECISION C): the BOOT sweep is
+ * UNCONDITIONAL — it adds NO `updatedAt <` predicate, so a fresh 'running' run
+ * (updatedAt = now) IS settled rather than skipped by a staleness window. The
+ * window is added ONLY when an explicit `staleMs` is supplied (the future phase-2
+ * multi-instance timer sweep). We assert the EXACT predicates the spec mandates.
+ */
+describe('AiChatRunRepo.sweepRunning', () => {
+  type Recorded = {
+    table?: string;
+    set?: Record<string, unknown>;
+    wheres: Array<[string, string, unknown]>;
+    returning?: string;
+  };
+
+  function makeDb(swept: Array<{ id: string }>): {
+    db: KyselyDB;
+    rec: Recorded;
+  } {
+    const rec: Recorded = { wheres: [] };
+    const builder: Record<string, unknown> = {};
+    const chain = () => builder;
+    builder.set = (v: Record<string, unknown>) => {
+      rec.set = v;
+      return builder;
+    };
+    builder.where = (col: string, op: string, val: unknown) => {
+      rec.wheres.push([col, op, val]);
+      return builder;
+    };
+    builder.returning = (col: string) => {
+      rec.returning = col;
+      return builder;
+    };
+    builder.execute = () => Promise.resolve(swept);
+    void chain;
+    const db = {
+      updateTable: (table: string) => {
+        rec.table = table;
+        return builder;
+      },
+    } as unknown as KyselyDB;
+    return { db, rec };
+  }
+
+  it('F1: the boot sweep (no staleMs) is UNCONDITIONAL — only a status filter, NO updatedAt window', async () => {
+    const { db, rec } = makeDb([{ id: 'r1' }, { id: 'r2' }]);
+    const repo = new AiChatRunRepo(db);
+
+    const swept = await repo.sweepRunning();
+
+    expect(swept).toBe(2);
+    expect(rec.table).toBe('aiChatRuns');
+    // The status filter is always present...
+    expect(rec.wheres).toContainEqual([
+      'status',
+      'in',
+      expect.arrayContaining(['pending', 'running']),
+    ]);
+    // ...but a fresh 'running' run (updatedAt = now) must NOT be skipped: no
+    // updatedAt predicate at all on the boot path.
+    expect(rec.wheres.some(([col]) => col === 'updatedAt')).toBe(false);
+    // It flips to 'aborted' and stamps finishedAt.
+    expect(rec.set).toEqual(
+      expect.objectContaining({ status: 'aborted', finishedAt: expect.any(Date) }),
+    );
+  });
+
+  it('phase-2 path: an explicit staleMs reintroduces the updatedAt window', async () => {
+    const { db, rec } = makeDb([]);
+    const repo = new AiChatRunRepo(db);
+
+    await repo.sweepRunning({ staleMs: SWEEP_RUN_STALE_MS });
+
+    const updatedAtWhere = rec.wheres.find(([col]) => col === 'updatedAt');
+    expect(updatedAtWhere).toBeDefined();
+    expect(updatedAtWhere![1]).toBe('<');
+    expect(updatedAtWhere![2]).toBeInstanceOf(Date);
+  });
+});

apps/server/src/database/repos/ai-chat/ai-chat-run.repo.ts

@@ -0,0 +1,212 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { sql } from 'kysely';
+import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
+import { dbOrTx } from '../../utils';
+import {
+  AiChatRun,
+  InsertableAiChatRun,
+} from '@docmost/db/types/entity.types';
+
+// Statuses that count as "the run is still live" (an autonomous and a user run
+// must never both be live on one chat — enforced by the partial unique index and
+// checked here for friendly 409s before the insert races the constraint).
+export const ACTIVE_RUN_STATUSES = ['pending', 'running'] as const;
+
+// Crash-recovery sweep recency threshold (mirrors AiChatMessageRepo.sweepStreaming,
+// #183): when a staleness window is supplied, a 'running'/'pending' run is only
+// swept to 'aborted' once it has been UNTOUCHED for this long, so a sibling
+// replica's boot-sweep can never abort a run another replica is actively
+// executing. The runner bumps `updatedAt` on every step, so a live run never
+// matches. PHASE 1 is single-process and the boot sweep passes NO window (every
+// dangling run is settled unconditionally — see sweepRunning / F1). This constant
+// is the window to reintroduce for the phase-2 multi-instance timer sweep.
+export const SWEEP_RUN_STALE_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Repository for `ai_chat_runs` (#184 phase 1): the agent run as a first-class,
+ * server-side lifecycle object detached from the HTTP request. The run row is the
+ * point a client subscribes/reconnects to (by `id` or by chat); the assistant
+ * message it links to (`assistantMessageId`) is the #183 projection of its output.
+ */
+@Injectable()
+export class AiChatRunRepo {
+  private readonly logger = new Logger(AiChatRunRepo.name);
+
+  private baseFields: Array<keyof AiChatRun> = [
+    'id',
+    'chatId',
+    'workspaceId',
+    'createdBy',
+    'assistantMessageId',
+    'trigger',
+    'status',
+    'error',
+    'stepCount',
+    'stopRequestedAt',
+    'startedAt',
+    'finishedAt',
+    'createdAt',
+    'updatedAt',
+  ];
+
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async insert(
+    insertable: InsertableAiChatRun,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .insertInto('aiChatRuns')
+      .values(insertable)
+      .returning(this.baseFields)
+      .executeTakeFirst();
+  }
+
+  async findById(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('aiChatRuns')
+      .select(this.baseFields)
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .executeTakeFirst();
+  }
+
+  /** The currently-active (pending|running) run for a chat, if any. At most one
+   *  exists thanks to the partial unique index. */
+  async findActiveByChat(
+    chatId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('aiChatRuns')
+      .select(this.baseFields)
+      .where('chatId', '=', chatId)
+      .where('workspaceId', '=', workspaceId)
+      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[])
+      .executeTakeFirst();
+  }
+
+  /** The most-recent run for a chat (active or settled) — the reconnect target. */
+  async findLatestByChat(
+    chatId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('aiChatRuns')
+      .select(this.baseFields)
+      .where('chatId', '=', chatId)
+      .where('workspaceId', '=', workspaceId)
+      .orderBy('createdAt', 'desc')
+      .orderBy('id', 'desc')
+      .limit(1)
+      .executeTakeFirst();
+  }
+
+  /**
+   * Patch a run by id + workspace; always bumps `updatedAt`. Used for every
+   * lifecycle transition (mark running, link the assistant message, bump
+   * step_count, finalize succeeded/failed/aborted). Returns the updated row or
+   * undefined when nothing matched (e.g. a foreign workspace).
+   */
+  async update(
+    id: string,
+    workspaceId: string,
+    patch: Partial<{
+      status: string;
+      error: string | null;
+      stepCount: number;
+      assistantMessageId: string | null;
+      stopRequestedAt: Date | null;
+      startedAt: Date | null;
+      finishedAt: Date | null;
+    }>,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .updateTable('aiChatRuns')
+      .set({ ...(patch as Record<string, unknown>), updatedAt: new Date() })
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .returning(this.baseFields)
+      .executeTakeFirst();
+  }
+
+  /**
+   * Mark an EXPLICIT stop request on an active run (distinct from a browser
+   * disconnect, which never stops a run). Stamps `stop_requested_at` ONLY while
+   * the run is still active, so a late stop on an already-settled run is a no-op.
+   * Returns the row when a stop was recorded, else undefined (nothing active).
+   */
+  async markStopRequested(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<AiChatRun | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .updateTable('aiChatRuns')
+      .set({ stopRequestedAt: new Date(), updatedAt: new Date() })
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[])
+      .returning(this.baseFields)
+      .executeTakeFirst();
+  }
+
+  /**
+   * Crash-recovery sweep (mirrors AiChatMessageRepo.sweepStreaming): flip every
+   * run still left pending/running — a run whose process died before reaching a
+   * terminal status — to 'aborted', stamping `finished_at`. Returns the number
+   * swept. Workspace-wide on purpose (a crash can dangle runs in any workspace).
+   *
+   * F1 (DECISION C): the BOOT sweep is UNCONDITIONAL — it passes no `staleMs`, so
+   * EVERY dangling run is settled regardless of how recently it was touched. On a
+   * fresh single-process boot any pending|running run is definitionally hung (no
+   * runner is alive to own it), so a fast restart (deploy/OOM within minutes of
+   * the last step) no longer leaves a run stuck 'running' forever — which would
+   * make the one-active-run gate 409 every future turn in that chat.
+   *
+   * The optional `staleMs` window is reintroduced ONLY for the future phase-2
+   * multi-instance timer sweep (see {@link SWEEP_RUN_STALE_MS}): there a booting
+   * replica must NOT abort a run another replica is actively executing, so it
+   * sweeps only runs UNTOUCHED past the window. Phase 1 is single-process, so the
+   * boot path supplies no window.
+   */
+  async sweepRunning(
+    opts: { staleMs?: number } = {},
+    trx?: KyselyTransaction,
+  ): Promise<number> {
+    const db = dbOrTx(this.db, trx);
+    const now = new Date();
+    let query = db
+      .updateTable('aiChatRuns')
+      .set({
+        status: 'aborted',
+        finishedAt: now,
+        updatedAt: now,
+        error: sql`coalesce(error, ${'Run interrupted by a server restart.'})`,
+      })
+      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[]);
+    // Multi-instance (phase 2) only: skip runs touched within the window so a
+    // sibling replica's live run is never aborted. Omitted on the phase-1 boot
+    // sweep -> unconditional.
+    if (typeof opts.staleMs === 'number') {
+      const staleBefore = new Date(now.getTime() - opts.staleMs);
+      query = query.where('updatedAt', '<', staleBefore);
+    }
+    const rows = await query.returning('id').execute();
+    return rows.length;
+  }
+}

apps/server/src/database/types/db.d.ts

@@ -644,6 +644,35 @@ export interface AiChatMessages {
   deletedAt: Timestamp | null;
 }
 
+// The agent RUN as a first-class server-side lifecycle object (#184 phase 1).
+// Mirrors migration 20260627T130000-ai-chat-runs.ts. A run is created when an
+// agent turn starts and survives the browser disconnecting; the DB is the source
+// of truth a later client reconnects to. `assistantMessageId` links to the #183
+// projection row (the assistant message this run materializes).
+export interface AiChatRuns {
+  id: Generated<string>;
+  chatId: string;
+  workspaceId: string;
+  // SET NULL on user deletion (the run history outlives its author); also NULL
+  // for a future non-human trigger (cron/api).
+  createdBy: string | null;
+  // The assistant message this run materializes; SET NULL if it is pruned.
+  assistantMessageId: string | null;
+  // 'user' | 'autostart' | 'schedule' | 'api' | 'continue' (only 'user' is
+  // produced in phase 1; the rest are reserved for the deferred autonomy triggers).
+  trigger: Generated<string>;
+  // 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'.
+  status: Generated<string>;
+  error: string | null;
+  stepCount: Generated<number>;
+  // Set when an EXPLICIT user stop is requested (distinct from a disconnect).
+  stopRequestedAt: Timestamp | null;
+  startedAt: Timestamp | null;
+  finishedAt: Timestamp | null;
+  createdAt: Generated<Timestamp>;
+  updatedAt: Generated<Timestamp>;
+}
+
 export interface UserSessions {
   id: Generated<string>;
   userId: string;
@@ -663,6 +692,7 @@ export interface DB {
   aiAgentRoles: AiAgentRoles;
   aiChats: AiChats;
   aiChatMessages: AiChatMessages;
+  aiChatRuns: AiChatRuns;
   apiKeys: ApiKeys;
   attachments: Attachments;
   audit: Audit;

apps/server/src/database/types/entity.types.ts

@@ -3,6 +3,7 @@ import {
   AiAgentRoles,
   AiChats,
   AiChatMessages,
+  AiChatRuns,
   Attachments,
   Comments,
   Groups,
@@ -55,10 +56,12 @@ export type UpdatableAiChat = Updateable<Omit<AiChats, 'id'>>;
 // full-text search. It is omitted from the public type so it never leaks
 // into HTTP responses or the chat history fed to the language model.
 export type AiChatMessage = Omit<Selectable<AiChatMessages>, 'tsv'>;
-export type InsertableAiChatMessage = Omit<
-  Insertable<AiChatMessages>,
-  'tsv'
->;
+export type InsertableAiChatMessage = Omit<Insertable<AiChatMessages>, 'tsv'>;
+
+// AI Chat Run (#184 phase 1): the agent run as a first-class lifecycle object,
+// detached from the HTTP request / browser window.
+export type AiChatRun = Selectable<AiChatRuns>;
+export type InsertableAiChatRun = Insertable<AiChatRuns>;
 
 // AI Provider Credentials
 // SECURITY (D9/§8.1): holds encrypted per-workspace provider API keys.
@@ -204,11 +207,14 @@ export type UpdatableFavorite = Updateable<Omit<Favorites, 'id'>>;
 // Page Transclusion
 export type PageTransclusion = Selectable<PageTransclusions>;
 export type InsertablePageTransclusion = Insertable<PageTransclusions>;
-export type UpdatablePageTransclusion = Updateable<Omit<PageTransclusions, 'id'>>;
+export type UpdatablePageTransclusion = Updateable<
+  Omit<PageTransclusions, 'id'>
+>;
 
 // Page Transclusion Reference
 export type PageTransclusionReference = Selectable<PageTransclusionReferences>;
-export type InsertablePageTransclusionReference = Insertable<PageTransclusionReferences>;
+export type InsertablePageTransclusionReference =
+  Insertable<PageTransclusionReferences>;
 export type UpdatablePageTransclusionReference = Updateable<
   Omit<PageTransclusionReferences, 'id'>
 >;
@@ -278,7 +284,9 @@ export type UpdatablePagePermission = Updateable<Omit<_PagePermissions, 'id'>>;
 // Page Verification
 export type PageVerification = Selectable<_PageVerifications>;
 export type InsertablePageVerification = Insertable<_PageVerifications>;
-export type UpdatablePageVerification = Updateable<Omit<_PageVerifications, 'id'>>;
+export type UpdatablePageVerification = Updateable<
+  Omit<_PageVerifications, 'id'>
+>;
 
 // Page Verifier
 export type PageVerifier = Selectable<_PageVerifiers>;

apps/server/src/integrations/environment/environment.service.spec.ts

@@ -14,148 +14,4 @@ describe('EnvironmentService', () => {
   it('should be defined', () => {
     expect(service).toBeDefined();
   });
-
-  describe('getSandboxTtlMs', () => {
-    // ConfigService stub: get(key, def) returns the configured value for the key
-    // (falling back to def), matching the @nestjs/config contract the service
-    // calls with (key, default).
-    const build = (sandboxTtl?: string) =>
-      new EnvironmentService({
-        get: (key: string, def?: string) =>
-          key === 'SANDBOX_TTL_MS' ? (sandboxTtl ?? def) : def,
-      } as any);
-
-    it.each(['0', '-5', 'abc'])(
-      'falls back to the 3600000 default for invalid value %s',
-      (value) => {
-        expect(build(value).getSandboxTtlMs()).toBe(3_600_000);
-      },
-    );
-
-    it('returns the parsed value for a valid positive integer', () => {
-      expect(build('120000').getSandboxTtlMs()).toBe(120_000);
-    });
-
-    it('uses the 3600000 default when SANDBOX_TTL_MS is unset', () => {
-      expect(build(undefined).getSandboxTtlMs()).toBe(3_600_000);
-    });
-  });
-
-  // The three byte caps share the same getPositiveIntEnv() helper as the TTL,
-  // so a non-integer / non-positive value ('0'/'-5'/'abc') falls back to the
-  // documented default and a valid positive integer is returned parsed. Note
-  // parseInt truncates '1.5' -> 1 (a valid positive integer), so that value is
-  // accepted, not rejected — same as the pre-existing TTL getter.
-  describe.each([
-    {
-      name: 'getSandboxMaxBytes',
-      key: 'SANDBOX_MAX_BYTES',
-      def: 8_388_608,
-      getter: (s: EnvironmentService) => s.getSandboxMaxBytes(),
-    },
-    {
-      name: 'getSandboxMaxImageBytes',
-      key: 'SANDBOX_MAX_IMAGE_BYTES',
-      def: 20_971_520,
-      getter: (s: EnvironmentService) => s.getSandboxMaxImageBytes(),
-    },
-    {
-      name: 'getSandboxMaxTotalBytes',
-      key: 'SANDBOX_MAX_TOTAL_BYTES',
-      def: 134_217_728,
-      getter: (s: EnvironmentService) => s.getSandboxMaxTotalBytes(),
-    },
-  ])('$name', ({ key, def, getter }) => {
-    // ConfigService stub: get(k, d) returns the configured value for THIS cap's
-    // key (falling back to d), and the default for every other key.
-    const build = (value?: string) =>
-      new EnvironmentService({
-        get: (k: string, d?: string) =>
-          k === key ? (value ?? d) : d,
-      } as any);
-
-    it.each(['0', '-5', 'abc'])(
-      `falls back to the ${def} default for invalid value %s`,
-      (value) => {
-        expect(getter(build(value))).toBe(def);
-      },
-    );
-
-    it('returns the parsed value for a valid positive integer', () => {
-      expect(getter(build('4096'))).toBe(4096);
-    });
-
-    it('truncates a non-integer like "1.5" to 1 via parseInt (not rejected)', () => {
-      expect(getter(build('1.5'))).toBe(1);
-    });
-
-    it(`uses the ${def} default when the env is unset`, () => {
-      expect(getter(build(undefined))).toBe(def);
-    });
-  });
-
-  // getPositiveIntEnv keeps a one-shot `invalidPositiveIntWarned` set so a bad
-  // value is logged ONCE per key (not on every getter call, which the sandbox
-  // hits per-put). These tests pin that dedup so a regression to per-call logging
-  // would fail loudly.
-  describe('invalid-value warn dedup', () => {
-    it('warns only once per key across repeated getter calls', () => {
-      const service = new EnvironmentService({
-        get: (k: string, d?: string) =>
-          k === 'SANDBOX_MAX_TOTAL_BYTES' ? '-5' : d,
-      } as any);
-      const warnSpy = jest
-        .spyOn((service as any).logger, 'warn')
-        .mockImplementation(() => undefined);
-
-      service.getSandboxMaxTotalBytes();
-      service.getSandboxMaxTotalBytes();
-
-      expect(warnSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('warns independently per key (dedup is per-key, not global)', () => {
-      // Two DIFFERENT SANDBOX_* keys are both invalid -> each warns once, so two
-      // warns total. This proves the dedup set is keyed, not a single global flag.
-      const service = new EnvironmentService({
-        get: (k: string, d?: string) =>
-          k === 'SANDBOX_MAX_BYTES' || k === 'SANDBOX_MAX_TOTAL_BYTES'
-            ? '-5'
-            : d,
-      } as any);
-      const warnSpy = jest
-        .spyOn((service as any).logger, 'warn')
-        .mockImplementation(() => undefined);
-
-      service.getSandboxMaxBytes();
-      service.getSandboxMaxTotalBytes();
-
-      expect(warnSpy).toHaveBeenCalledTimes(2);
-    });
-  });
-
-  describe('getSandboxPublicUrl', () => {
-    // Stub that resolves BOTH keys the public-url logic consults.
-    const build = (vals: { sandboxUrl?: string; appUrl?: string }) =>
-      new EnvironmentService({
-        get: (key: string, def?: string) =>
-          key === 'SANDBOX_PUBLIC_URL'
-            ? (vals.sandboxUrl ?? def)
-            : key === 'APP_URL'
-              ? (vals.appUrl ?? def)
-              : def,
-      } as any);
-
-    it('uses SANDBOX_PUBLIC_URL and trims a trailing slash', () => {
-      expect(
-        build({ sandboxUrl: 'https://docs.example.com/' }).getSandboxPublicUrl(),
-      ).toBe('https://docs.example.com');
-    });
-
-    it('falls back to APP_URL (origin) when SANDBOX_PUBLIC_URL is unset', () => {
-      expect(
-        build({ appUrl: 'https://app.example.com' }).getSandboxPublicUrl(),
-      ).toBe('https://app.example.com');
-    });
-  });
 });

apps/server/src/integrations/environment/environment.service.ts

@@ -1,15 +1,9 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import ms, { StringValue } from 'ms';
 
 @Injectable()
 export class EnvironmentService {
-  private readonly logger = new Logger(EnvironmentService.name);
-  // Env keys already warned about for an invalid value (one-shot per key, so a
-  // bad SANDBOX_* value is not logged on every blob put). Mirrors the original
-  // sandboxTtlWarned guard, generalized across the TTL + the three byte caps.
-  private readonly invalidPositiveIntWarned = new Set<string>();
-
   constructor(private configService: ConfigService) {}
 
   getNodeEnv(): string {
@@ -338,63 +332,4 @@ export class EnvironmentService {
       .map((o) => o.trim())
       .filter(Boolean);
   }
-
-  // --- Blob sandbox (in-RAM ephemeral blob transfer; see SandboxModule) ---
-
-  // Base URL the sandbox `uri` is built from. It MUST be reachable over the
-  // network by the external consumer that fetches the blobs (not a loopback
-  // address if that consumer is remote). Falls back to APP_URL when unset so a
-  // single-host deployment works out of the box; set it explicitly when the
-  // consumer lives on another host.
-  getSandboxPublicUrl(): string {
-    const raw =
-      this.configService.get<string>('SANDBOX_PUBLIC_URL') || this.getAppUrl();
-    // Drop any trailing slash so `${base}/api/sb/${id}` never doubles up.
-    return raw.replace(/\/+$/, '');
-  }
-
-  // Parse a REQUIRED positive-integer env (TTL in ms or a byte cap). A
-  // non-integer or <= 0 value would break the sandbox silently (instant expiry,
-  // or every put failing against a 0-byte cap), so warn once and fall back to
-  // the default instead. Blob bodies are never logged.
-  private getPositiveIntEnv(key: string, def: number): number {
-    const parsed = parseInt(
-      this.configService.get<string>(key, String(def)),
-      10,
-    );
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-      if (!this.invalidPositiveIntWarned.has(key)) {
-        this.invalidPositiveIntWarned.add(key);
-        this.logger.warn(
-          `Invalid ${key} (must be a positive integer); falling back to the ${def} default`,
-        );
-      }
-      return def;
-    }
-    return parsed;
-  }
-
-  // Blob time-to-live. Default 1h. The unguessable UUID + this short TTL + TLS
-  // are the whole capability model (no tokens). A non-positive or non-integer
-  // value would make every blob expire instantly (silent 404s), so reject it and
-  // fall back to the 1h default (warned about once to avoid per-put log spam).
-  getSandboxTtlMs(): number {
-    return this.getPositiveIntEnv('SANDBOX_TTL_MS', 3_600_000);
-  }
-
-  // Per-blob cap for non-image blobs (the serialized document). Default 8 MiB.
-  getSandboxMaxBytes(): number {
-    return this.getPositiveIntEnv('SANDBOX_MAX_BYTES', 8_388_608);
-  }
-
-  // Per-blob cap for mirrored image blobs. Default 20 MiB.
-  getSandboxMaxImageBytes(): number {
-    return this.getPositiveIntEnv('SANDBOX_MAX_IMAGE_BYTES', 20_971_520);
-  }
-
-  // RAM guard: total bytes the whole store may hold. Default 128 MiB. On
-  // overflow the store evicts oldest entries to make room.
-  getSandboxMaxTotalBytes(): number {
-    return this.getPositiveIntEnv('SANDBOX_MAX_TOTAL_BYTES', 134_217_728);
-  }
 }

apps/server/src/integrations/environment/environment.validation.ts

@@ -2,7 +2,6 @@ import {
   IsIn,
   IsNotEmpty,
   IsNotIn,
-  IsNumberString,
   IsOptional,
   IsString,
   IsUrl,
@@ -171,35 +170,6 @@ export class EnvironmentVariables {
     },
   )
   CLICKHOUSE_URL: string;
-
-  // --- Blob sandbox (in-RAM ephemeral blob transfer; see SandboxModule) ---
-
-  @IsOptional()
-  @ValidateIf((obj) => obj.SANDBOX_PUBLIC_URL != '' && obj.SANDBOX_PUBLIC_URL != null)
-  @IsUrl(
-    { protocols: ['http', 'https'], require_tld: false },
-    {
-      message:
-        'SANDBOX_PUBLIC_URL must be a valid http(s) URL reachable by the external blob consumer',
-    },
-  )
-  SANDBOX_PUBLIC_URL: string;
-
-  @IsOptional()
-  @IsNumberString({}, { message: 'SANDBOX_TTL_MS must be an integer (milliseconds)' })
-  SANDBOX_TTL_MS: string;
-
-  @IsOptional()
-  @IsNumberString({}, { message: 'SANDBOX_MAX_BYTES must be an integer (bytes)' })
-  SANDBOX_MAX_BYTES: string;
-
-  @IsOptional()
-  @IsNumberString({}, { message: 'SANDBOX_MAX_IMAGE_BYTES must be an integer (bytes)' })
-  SANDBOX_MAX_IMAGE_BYTES: string;
-
-  @IsOptional()
-  @IsNumberString({}, { message: 'SANDBOX_MAX_TOTAL_BYTES must be an integer (bytes)' })
-  SANDBOX_MAX_TOTAL_BYTES: string;
 }
 
 export function validate(config: Record<string, any>) {

apps/server/src/integrations/mcp/mcp-auth.helpers.ts

@@ -131,25 +131,10 @@ export class FailedLoginLimiter {
 }
 
 // The per-session DocmostMcpConfig shape understood by @docmost/mcp: either the
-// service-account credentials variant OR the per-user getToken variant. The
-// optional `sandbox` sink (blob store for the stash tool) is common to both and
-// injected by McpService after the auth decision.
-export type DocmostMcpConfig = (
+// service-account credentials variant OR the per-user getToken variant.
+export type DocmostMcpConfig =
   | { apiUrl: string; email: string; password: string }
-  | { apiUrl: string; getToken: () => Promise<string> }
-) & {
-  sandbox?: {
-    put: (
-      buf: Buffer,
-      mime: string,
-    ) => { uri: string; sha256: string; size: number };
-    // Optional live/evict probes the package uses to keep stash_page's mirror
-    // counts honest under the store's FIFO eviction (mirror of the package's
-    // sink type); older bindings omit them.
-    has?: (uri: string) => boolean;
-    evict?: (uri: string) => void;
-  };
-};
+  | { apiUrl: string; getToken: () => Promise<string> };
 
 export interface ResolvedMcpAuth {
   config: DocmostMcpConfig;

apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts

@@ -109,13 +109,13 @@ function makeService(opts: {
   };
 
   const service = new McpService(
+    undefined as never, // environmentService
     undefined as never, // workspaceRepo
     undefined as never, // authService
     undefined as never, // tokenService
     undefined as never, // userRepo
     undefined as never, // userSessionRepo
     moduleRef as never, // moduleRef (read by the MFA branch)
-    undefined as never, // sandboxStore (unused by the login-gate path)
   );
   // Stop the constructor's unref'd sweep timer leaking across tests.
   service.onModuleDestroy();

apps/server/src/integrations/mcp/mcp.module.ts

@@ -2,15 +2,17 @@ import { Module } from '@nestjs/common';
 import { McpController } from './mcp.controller';
 import { McpService } from './mcp.service';
 import { DatabaseModule } from '@docmost/db/database.module';
+import { EnvironmentModule } from '../environment/environment.module';
 import { AuthModule } from '../../core/auth/auth.module';
 import { TokenModule } from '../../core/auth/token.module';
 
 // Community MCP feature: the server itself serves the Model Context Protocol
-// over HTTP at /mcp. DatabaseModule (global) provides WorkspaceRepo. AuthModule
-// supplies AuthService (per-user HTTP-Basic login validation) and TokenModule
-// supplies TokenService (Bearer access-JWT verification for the token fallback).
+// over HTTP at /mcp. DatabaseModule (global) provides WorkspaceRepo and
+// EnvironmentModule (global) provides EnvironmentService. AuthModule supplies
+// AuthService (per-user HTTP-Basic login validation) and TokenModule supplies
+// TokenService (Bearer access-JWT verification for the token fallback).
 @Module({
-  imports: [DatabaseModule, AuthModule, TokenModule],
+  imports: [DatabaseModule, EnvironmentModule, AuthModule, TokenModule],
   controllers: [McpController],
   providers: [McpService],
 })

apps/server/src/integrations/mcp/mcp.service.ts

@@ -8,6 +8,7 @@ import { ModuleRef } from '@nestjs/core';
 import { pathToFileURL } from 'node:url';
 import { IncomingMessage } from 'node:http';
 import { FastifyReply, FastifyRequest } from 'fastify';
+import { EnvironmentService } from '../environment/environment.service';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { UserRepo } from '@docmost/db/repos/user/user.repo';
 import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
@@ -29,7 +30,6 @@ import {
   DocmostMcpConfig,
   ResolvedMcpAuth,
 } from './mcp-auth.helpers';
-import { SandboxStore } from '../sandbox/sandbox.store';
 
 // Minimal shape of the embedded MCP HTTP handler exported by @docmost/mcp/http.
 interface McpHttpHandler {
@@ -92,14 +92,13 @@ export class McpService implements OnModuleDestroy {
   private readonly sweepTimer: NodeJS.Timeout;
 
   constructor(
+    private readonly environmentService: EnvironmentService,
     private readonly workspaceRepo: WorkspaceRepo,
     private readonly authService: AuthService,
     private readonly tokenService: TokenService,
     private readonly userRepo: UserRepo,
     private readonly userSessionRepo: UserSessionRepo,
     private readonly moduleRef: ModuleRef,
-    // Shared singleton in-RAM blob store backing the stash tool.
-    private readonly sandboxStore: SandboxStore,
   ) {
     this.sweepTimer = setInterval(() => {
       try {
@@ -327,11 +326,7 @@ export class McpService implements OnModuleDestroy {
               // Should never happen: handle() always stashes before delegating.
               throw new UnauthorizedException('MCP authentication missing.');
             }
-            // Inject the blob-sandbox sink after the auth decision so stash_page
-            // can store blobs in the shared in-RAM store regardless of which
-            // credential variant resolved. The sink (put/has/evict + uri↔id
-            // mapping) is owned by SandboxStore.asSink().
-            return { ...resolved.config, sandbox: this.sandboxStore.asSink() };
+            return resolved.config;
           },
           {
             identify: (req: IncomingMessage) => {

apps/server/src/integrations/sandbox/sandbox.constants.ts

@@ -1,6 +0,0 @@
-// Single source of truth for the anonymous blob-sandbox route. The controller
-// is mounted under the global `/api` prefix, so its decorator uses the bare
-// segment while the public URL and the workspace-gate exclusion need the full
-// path — derive the latter from the former so the two never drift.
-export const SANDBOX_ROUTE_SEGMENT = 'sb';
-export const SANDBOX_API_PATH = `/api/${SANDBOX_ROUTE_SEGMENT}`;

apps/server/src/integrations/sandbox/sandbox.controller.spec.ts

@@ -1,265 +0,0 @@
-import { SandboxController } from './sandbox.controller';
-import { SandboxEntry } from './sandbox.store';
-
-// Capturing fake of the FastifyReply surface the controller uses:
-// status()/header()/headers()/send(), all chainable.
-function makeRes() {
-  const sent: { status: number; headers: Record<string, any>; body: any } = {
-    status: 200,
-    headers: {},
-    body: undefined,
-  };
-  const res: any = {
-    status(code: number) {
-      sent.status = code;
-      return res;
-    },
-    header(key: string, value: any) {
-      sent.headers[key.toLowerCase()] = value;
-      return res;
-    },
-    headers(obj: Record<string, any>) {
-      for (const k of Object.keys(obj)) sent.headers[k.toLowerCase()] = obj[k];
-      return res;
-    },
-    send(body?: any) {
-      sent.body = body;
-      return res;
-    },
-    _sent: sent,
-  };
-  return res;
-}
-
-function makeReq(headers: Record<string, any> = {}) {
-  return { headers } as any;
-}
-
-// A syntactically valid v4 UUID (version nibble 4, variant nibble 8). The
-// shared `uuid` validator is stricter than a bare hex-shape regex, so the id
-// must carry a real version/variant.
-const VALID_ID = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee';
-
-function entry(buf: Buffer, mime: string, sha256: string): SandboxEntry {
-  return { buf, mime, sha256, expiresAt: Date.now() + 60_000 };
-}
-
-describe('SandboxController', () => {
-  it('serves 200 with body, Content-Type, Content-Length and sha256 ETag', async () => {
-    const buf = Buffer.from('{"ok":true}', 'utf8');
-    const sha = 'a'.repeat(64);
-    const store = { get: jest.fn().mockReturnValue(entry(buf, 'application/json', sha)) };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(store.get).toHaveBeenCalledWith(VALID_ID);
-    expect(res._sent.status).toBe(200);
-    expect(res._sent.headers['content-type']).toBe('application/json');
-    expect(res._sent.headers['content-length']).toBe(buf.length);
-    expect(res._sent.headers['etag']).toBe(`"${sha}"`);
-    expect(res._sent.body).toBe(buf);
-  });
-
-  it('returns 404 for a missing/expired blob', async () => {
-    const store = { get: jest.fn().mockReturnValue(undefined) };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(res._sent.status).toBe(404);
-    expect(res._sent.body).toBeUndefined();
-  });
-
-  it('returns 404 for a non-UUID id WITHOUT touching the store (anti-traversal)', async () => {
-    const store = { get: jest.fn() };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get('../../etc/passwd', makeReq(), res);
-
-    expect(store.get).not.toHaveBeenCalled();
-    expect(res._sent.status).toBe(404);
-  });
-
-  it('returns 304 (no body) when If-None-Match matches the ETag', async () => {
-    const sha = 'b'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': `"${sha}"` }), res);
-
-    expect(res._sent.status).toBe(304);
-    expect(res._sent.body).toBeUndefined();
-    expect(res._sent.headers['etag']).toBe(`"${sha}"`);
-  });
-
-  it('accepts a bare (unquoted) sha256 in If-None-Match too', async () => {
-    const sha = 'c'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': sha }), res);
-
-    expect(res._sent.status).toBe(304);
-  });
-
-  it('serves 200 when If-None-Match does NOT match', async () => {
-    const sha = 'd'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': '"stale"' }), res);
-
-    expect(res._sent.status).toBe(200);
-  });
-
-  it('returns 304 for a wildcard "*" If-None-Match', async () => {
-    const sha = 'e'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': '*' }), res);
-
-    expect(res._sent.status).toBe(304);
-  });
-
-  it('returns 304 for a weak validator W/"<sha>"', async () => {
-    const sha = 'f'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': `W/"${sha}"` }), res);
-
-    expect(res._sent.status).toBe(304);
-  });
-
-  it('returns 304 when a comma-separated If-None-Match list contains the sha', async () => {
-    const sha = '1'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(
-      VALID_ID,
-      makeReq({ 'if-none-match': `"other", "${sha}"` }),
-      res,
-    );
-
-    expect(res._sent.status).toBe(304);
-  });
-
-  it('sets a private, immutable Cache-Control with a max-age within the TTL on 200', async () => {
-    const sha = '2'.repeat(64);
-    // Known TTL: ~30s out, so the floored max-age must land within [0, 60].
-    const e: SandboxEntry = {
-      buf: Buffer.from('x'),
-      mime: 'application/json',
-      sha256: sha,
-      expiresAt: Date.now() + 30_000,
-    };
-    const store = { get: jest.fn().mockReturnValue(e) };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(res._sent.status).toBe(200);
-    const cc = res._sent.headers['cache-control'] as string;
-    expect(cc).toMatch(/^private, max-age=\d+, immutable$/);
-    const maxAge = Number(cc.match(/max-age=(\d+)/)![1]);
-    expect(maxAge).toBeGreaterThanOrEqual(0);
-    expect(maxAge).toBeLessThanOrEqual(60);
-  });
-
-  it('emits Cache-Control alongside ETag on the 304 branch', async () => {
-    const sha = '3'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq({ 'if-none-match': `"${sha}"` }), res);
-
-    expect(res._sent.status).toBe(304);
-    expect(res._sent.headers['cache-control']).toMatch(
-      /^private, max-age=\d+, immutable$/,
-    );
-  });
-
-  it('sets nosniff + restrictive CSP and serves an allowlisted image inline', async () => {
-    const sha = '4'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'image/png', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(res._sent.status).toBe(200);
-    expect(res._sent.headers['x-content-type-options']).toBe('nosniff');
-    expect(res._sent.headers['content-security-policy']).toBe(
-      "base-uri 'none'; object-src 'self'; default-src 'self';",
-    );
-    expect(res._sent.headers['content-disposition']).toBe('inline');
-  });
-
-  it('forces an SVG to download (attachment) while keeping nosniff + CSP', async () => {
-    const sha = '5'.repeat(64);
-    const store = {
-      get: jest.fn().mockReturnValue(entry(Buffer.from('<svg/>'), 'image/svg+xml', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(res._sent.status).toBe(200);
-    expect(res._sent.headers['content-disposition']).toBe('attachment');
-    expect(res._sent.headers['x-content-type-options']).toBe('nosniff');
-    expect(res._sent.headers['content-security-policy']).toBe(
-      "base-uri 'none'; object-src 'self'; default-src 'self';",
-    );
-  });
-
-  it('forces text/html to download (attachment) while keeping nosniff + CSP', async () => {
-    const sha = '6'.repeat(64);
-    const store = {
-      get: jest
-        .fn()
-        .mockReturnValue(entry(Buffer.from('<h1>x</h1>'), 'text/html', sha)),
-    };
-    const controller = new SandboxController(store as any);
-    const res = makeRes();
-
-    await controller.get(VALID_ID, makeReq(), res);
-
-    expect(res._sent.status).toBe(200);
-    expect(res._sent.headers['content-disposition']).toBe('attachment');
-    expect(res._sent.headers['x-content-type-options']).toBe('nosniff');
-    expect(res._sent.headers['content-security-policy']).toBe(
-      "base-uri 'none'; object-src 'self'; default-src 'self';",
-    );
-  });
-});

apps/server/src/integrations/sandbox/sandbox.controller.ts

@@ -1,130 +0,0 @@
-import { Controller, Get, Param, Req, Res } from '@nestjs/common';
-import { FastifyReply, FastifyRequest } from 'fastify';
-import { validate as isValidUUID } from 'uuid';
-import { SandboxStore } from './sandbox.store';
-import { SANDBOX_ROUTE_SEGMENT } from './sandbox.constants';
-
-// MIME types safe to render inline in a browser. SVG is deliberately EXCLUDED
-// (it can carry script), as are text/html and the JSON document blob — anything
-// not on this list is served as an attachment so an attacker-controlled mime can
-// never execute script on this origin (the route is anonymous + same-origin).
-const INLINE_SAFE_MIME = new Set([
-  'image/png',
-  'image/jpeg',
-  'image/gif',
-  'image/webp',
-  'image/avif',
-]);
-
-/**
- * Anonymous read endpoint for the in-RAM blob sandbox.
- *
- * Mounted under the global `/api` prefix as `GET /api/sb/:id`. It carries NO
- * `@UseGuards(JwtAuthGuard)`, so — exactly like the public attachment route
- * `GET /api/files/public/...` — it is exempt from Docmost session auth. The
- * route is ALSO listed in the workspace-resolution preHandler's excludedPaths
- * in main.ts so a request from a remote consumer (which carries no workspace
- * host) is not rejected with "Workspace not found".
- *
- * It only ever serves blobs looked up from the SandboxStore by a validated
- * UUID; `:id` is never used as a filesystem path, so there is no traversal
- * surface. Never returns tokens, never 401s.
- *
- * Anti-XSS hardening mirrors the public attachment route: every response sets
- * `X-Content-Type-Options: nosniff` and a restrictive CSP, and serves any mime
- * NOT on the inline-safe allowlist (svg/html/the JSON document blob) as an
- * attachment, so an attacker-controlled `entry.mime` can never execute script
- * on this same-origin anonymous route.
- */
-@Controller(SANDBOX_ROUTE_SEGMENT)
-export class SandboxController {
-  constructor(private readonly store: SandboxStore) {}
-
-  @Get(':id')
-  async get(
-    @Param('id') id: string,
-    @Req() req: FastifyRequest,
-    @Res() res: FastifyReply,
-  ): Promise<void> {
-    // Validate `:id` as a real UUID via the shared `uuid` validator (same as the
-    // attachment routes). This is anti-traversal / input hygiene (so `:id` can
-    // never be a path like `../...`), NOT authorization — the capability is the
-    // unguessable id itself plus the short TTL plus TLS. A non-UUID id (including
-    // any traversal attempt) → 404 before touching the store; no stack trace
-    // leaks out.
-    if (!isValidUUID(id)) {
-      res.status(404).send();
-      return;
-    }
-
-    const entry = this.store.get(id);
-    if (!entry) {
-      // Missing or expired — indistinguishable to the caller, by design.
-      res.status(404).send();
-      return;
-    }
-
-    // Strong validator: quoted sha256, no W/ weak prefix. Same value computed
-    // at put() time, so an external consumer can detect a truncated/corrupted
-    // body — the original bug this whole channel exists to fix.
-    const etag = `"${entry.sha256}"`;
-
-    // Compute freshness BEFORE the conditional check: a 304 conditional
-    // revalidation must not lose the Cache-Control freshness directives, or a
-    // revalidating client would forget how long the blob stays fresh.
-    const ttlSeconds = Math.max(
-      0,
-      Math.floor((entry.expiresAt - Date.now()) / 1000),
-    );
-    // Capability URL — keep it out of shared caches; immutable for its TTL.
-    const cacheControl = `private, max-age=${ttlSeconds}, immutable`;
-
-    // Conditional request: an exact ETag match → 304 with no body. The blob is
-    // immutable, so the validator is stable for the blob's whole lifetime.
-    if (this.ifNoneMatchMatches(req.headers['if-none-match'], entry.sha256)) {
-      res
-        .status(304)
-        .header('ETag', etag)
-        .header('Cache-Control', cacheControl)
-        .send();
-      return;
-    }
-
-    // Non-allowlisted mimes (svg/html/the JSON blob) are forced to download so
-    // an attacker-controlled mime can never run script inline on this origin.
-    const disposition = INLINE_SAFE_MIME.has(entry.mime)
-      ? 'inline'
-      : 'attachment';
-
-    // Use @Res() + res.send(Buffer) with an explicit Content-Type so the binary
-    // body bypasses the global JSON response transform/serializer.
-    res
-      .status(200)
-      .headers({
-        'Content-Type': entry.mime,
-        'Content-Length': entry.buf.length,
-        ETag: etag,
-        'Cache-Control': cacheControl,
-        'X-Content-Type-Options': 'nosniff',
-        'Content-Security-Policy':
-          "base-uri 'none'; object-src 'self'; default-src 'self';",
-        'Content-Disposition': disposition,
-      })
-      .send(entry.buf);
-  }
-
-  // Accept the consumer's If-None-Match whether it sends the quoted ETag, a bare
-  // sha256, a weak "W/"-prefixed validator, or a comma-separated list.
-  private ifNoneMatchMatches(
-    header: string | string[] | undefined,
-    sha256: string,
-  ): boolean {
-    if (!header) return false;
-    const raw = Array.isArray(header) ? header.join(',') : header;
-    if (raw.trim() === '*') return true;
-    return raw
-      .split(',')
-      .map((t) => t.trim().replace(/^W\//, '').replace(/^"|"$/g, ''))
-      .some((t) => t === sha256);
-  }
-}

apps/server/src/integrations/sandbox/sandbox.module.ts

@@ -1,19 +0,0 @@
-import { Global, Module } from '@nestjs/common';
-import { SandboxController } from './sandbox.controller';
-import { SandboxStore } from './sandbox.store';
-
-/**
- * In-RAM blob sandbox: a SINGLE shared SandboxStore (the @Injectable singleton)
- * is written to by the stash tool (via McpService / AiChatToolsService) and read
- * back by the anonymous SandboxController. Marked @Global so the same store
- * instance is injectable everywhere without import churn — put() and get() MUST
- * hit the same Map. EnvironmentService (caps/TTL/public URL) is provided by the
- * global EnvironmentModule.
- */
-@Global()
-@Module({
-  controllers: [SandboxController],
-  providers: [SandboxStore],
-  exports: [SandboxStore],
-})
-export class SandboxModule {}

apps/server/src/integrations/sandbox/sandbox.store.spec.ts

@@ -1,163 +0,0 @@
-import { createHash } from 'node:crypto';
-import { validate as isValidUUID } from 'uuid';
-import { SandboxStore } from './sandbox.store';
-
-// Build a minimal EnvironmentService stub with overridable caps/TTL.
-function makeEnv(
-  overrides: Partial<{
-    ttlMs: number;
-    maxBytes: number;
-    maxImageBytes: number;
-    maxTotalBytes: number;
-  }> = {},
-) {
-  const cfg = {
-    ttlMs: 3_600_000,
-    maxBytes: 8_388_608,
-    maxImageBytes: 20_971_520,
-    maxTotalBytes: 134_217_728,
-    ...overrides,
-  };
-  return {
-    getSandboxTtlMs: () => cfg.ttlMs,
-    getSandboxMaxBytes: () => cfg.maxBytes,
-    getSandboxMaxImageBytes: () => cfg.maxImageBytes,
-    getSandboxMaxTotalBytes: () => cfg.maxTotalBytes,
-    getSandboxPublicUrl: () => 'https://example.test',
-  } as any;
-}
-
-describe('SandboxStore', () => {
-  let store: SandboxStore;
-
-  afterEach(() => {
-    // Clear the unref'd sweep interval so it never leaks across tests.
-    store?.onModuleDestroy();
-    jest.useRealTimers();
-  });
-
-  it('put/get round-trips the exact bytes + mime and returns a UUID id', () => {
-    store = new SandboxStore(makeEnv());
-    const buf = Buffer.from('{"type":"doc","content":[]}', 'utf8');
-
-    const res = store.put(buf, 'application/json');
-    expect(isValidUUID(res.id)).toBe(true);
-    expect(res.size).toBe(buf.length);
-
-    const entry = store.get(res.id);
-    expect(entry).toBeDefined();
-    expect(entry!.buf.equals(buf)).toBe(true);
-    expect(entry!.mime).toBe('application/json');
-  });
-
-  it('computes sha256 over the body (matches a manual digest)', () => {
-    store = new SandboxStore(makeEnv());
-    const buf = Buffer.from('hello sandbox', 'utf8');
-    const expected = createHash('sha256').update(buf).digest('hex');
-
-    const res = store.put(buf, 'text/plain');
-    expect(res.sha256).toBe(expected);
-    expect(store.get(res.id)!.sha256).toBe(expected);
-  });
-
-  it('returns undefined for a missing id', () => {
-    store = new SandboxStore(makeEnv());
-    expect(store.get('11111111-1111-1111-1111-111111111111')).toBeUndefined();
-  });
-
-  it('lazily expires entries past the TTL (get returns undefined)', () => {
-    jest.useFakeTimers();
-    jest.setSystemTime(new Date('2026-01-01T00:00:00Z'));
-    store = new SandboxStore(makeEnv({ ttlMs: 1000 }));
-    const res = store.put(Buffer.from('x'), 'text/plain');
-
-    expect(store.get(res.id)).toBeDefined();
-    jest.setSystemTime(new Date('2026-01-01T00:00:02Z')); // +2s > 1s TTL
-    expect(store.get(res.id)).toBeUndefined();
-    // Eviction also frees the byte accounting.
-    expect(store.bytes).toBe(0);
-  });
-
-  it('background sweep drops expired entries without a get()', () => {
-    jest.useFakeTimers();
-    jest.setSystemTime(new Date('2026-01-01T00:00:00Z'));
-    store = new SandboxStore(makeEnv({ ttlMs: 1000 }));
-    store.put(Buffer.from('x'), 'text/plain');
-    expect(store.size).toBe(1);
-
-    jest.setSystemTime(new Date('2026-01-01T00:01:30Z')); // past TTL
-    jest.advanceTimersByTime(60_000); // fire the sweep interval
-    expect(store.size).toBe(0);
-  });
-
-  it('rejects a non-image blob over SANDBOX_MAX_BYTES', () => {
-    store = new SandboxStore(makeEnv({ maxBytes: 16 }));
-    expect(() => store.put(Buffer.alloc(17), 'application/json')).toThrow(
-      /per-blob cap/,
-    );
-  });
-
-  it('uses the larger image cap for image/* blobs', () => {
-    // 100 bytes exceeds the doc cap (16) but fits the image cap (1024).
-    store = new SandboxStore(makeEnv({ maxBytes: 16, maxImageBytes: 1024 }));
-    expect(() => store.put(Buffer.alloc(100), 'image/png')).not.toThrow();
-    // SVG counts as an image too.
-    expect(() => store.put(Buffer.alloc(100), 'image/svg+xml')).not.toThrow();
-  });
-
-  it('evicts oldest entries when the total cap would be exceeded', () => {
-    // Total cap 250 bytes; each blob 100 bytes -> only 2 fit at a time.
-    store = new SandboxStore(
-      makeEnv({ maxTotalBytes: 250, maxBytes: 1024 }),
-    );
-    const a = store.put(Buffer.alloc(100), 'application/json');
-    const b = store.put(Buffer.alloc(100), 'application/json');
-    const c = store.put(Buffer.alloc(100), 'application/json'); // evicts a
-
-    expect(store.get(a.id)).toBeUndefined(); // oldest evicted
-    expect(store.get(b.id)).toBeDefined();
-    expect(store.get(c.id)).toBeDefined();
-    expect(store.bytes).toBeLessThanOrEqual(250);
-  });
-
-  it('rejects a single blob larger than the whole total cap', () => {
-    store = new SandboxStore(
-      makeEnv({ maxTotalBytes: 50, maxBytes: 1024 }),
-    );
-    expect(() => store.put(Buffer.alloc(100), 'application/json')).toThrow(
-      /total store cap/,
-    );
-  });
-
-  it('putAndLink composes the anonymous /api/sb/<id> url with matching integrity', () => {
-    store = new SandboxStore(makeEnv());
-    const buf = Buffer.from('hello link', 'utf8');
-    const expected = createHash('sha256').update(buf).digest('hex');
-
-    const res = store.putAndLink(buf, 'image/png');
-    expect(res.uri).toMatch(/^https:\/\/example\.test\/api\/sb\/[0-9a-f-]{36}$/);
-    expect(res.sha256).toBe(expected);
-    expect(res.size).toBe(buf.length);
-  });
-
-  it('has()/remove() report and free a blob by id', () => {
-    store = new SandboxStore(makeEnv());
-    const { id } = store.put(Buffer.from('x'), 'text/plain');
-
-    expect(store.has(id)).toBe(true);
-    store.remove(id);
-    expect(store.has(id)).toBe(false);
-    expect(store.bytes).toBe(0);
-  });
-
-  it('asSink() round-trips put/has/evict through the anonymous uri', () => {
-    store = new SandboxStore(makeEnv());
-    const sink = store.asSink();
-    const buf = Buffer.from('sink bytes', 'utf8');
-
-    const r = sink.put(buf, 'image/png');
-    expect(sink.has(r.uri)).toBe(true);
-    sink.evict(r.uri);
-    expect(sink.has(r.uri)).toBe(false);
-  });
-});

apps/server/src/integrations/sandbox/sandbox.store.ts

@@ -1,178 +0,0 @@
-import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
-import { createHash, randomUUID } from 'node:crypto';
-import { EnvironmentService } from '../environment/environment.service';
-import { SANDBOX_API_PATH } from './sandbox.constants';
-
-// In-RAM, process-local blob store. No disk, no DB. Ephemeral by design: a
-// restart empties it. A blob is addressed by an unguessable randomUUID() which
-// IS the read capability — there are NO tokens. Each blob is immutable (its id
-// never maps to changing content), so its sha256 is a perfect strong ETag.
-export interface SandboxEntry {
-  buf: Buffer;
-  mime: string;
-  sha256: string;
-  expiresAt: number;
-}
-
-export interface SandboxPutResult {
-  id: string;
-  sha256: string;
-  size: number;
-}
-
-@Injectable()
-export class SandboxStore implements OnModuleDestroy {
-  private readonly logger = new Logger(SandboxStore.name);
-  // Map preserves insertion order, so the first key is the oldest entry — used
-  // for FIFO eviction when the total-bytes RAM guard is exceeded.
-  private readonly map = new Map<string, SandboxEntry>();
-  private totalBytes = 0;
-
-  // Background sweep clears expired entries so never-fetched blobs do not linger
-  // until the next get(). unref()'d so it never holds the event loop open;
-  // cleared on module destroy. Mirrors the sweepTimer pattern in
-  // integrations/mcp/mcp.service.ts and packages/mcp/src/http.ts.
-  private readonly sweepIntervalMs = 60_000;
-  private readonly sweepTimer: NodeJS.Timeout;
-
-  constructor(private readonly environmentService: EnvironmentService) {
-    this.sweepTimer = setInterval(() => {
-      try {
-        this.sweep();
-      } catch (err) {
-        this.logger.error('Sandbox sweep failed', err as Error);
-      }
-    }, this.sweepIntervalMs);
-    this.sweepTimer.unref?.();
-  }
-
-  onModuleDestroy(): void {
-    clearInterval(this.sweepTimer);
-  }
-
-  /**
-   * Store a blob and return its read capability id + integrity metadata. The
-   * per-blob cap is chosen by mime (images get the larger image cap), and the
-   * total-store RAM guard evicts oldest entries to make room. Throws a clear
-   * error when a single blob cannot fit even after eviction. Blob bodies are
-   * never logged.
-   */
-  put(buf: Buffer, mime: string): SandboxPutResult {
-    const perBlobCap = mime.startsWith('image/')
-      ? this.environmentService.getSandboxMaxImageBytes()
-      : this.environmentService.getSandboxMaxBytes();
-    if (buf.length > perBlobCap) {
-      throw new Error(
-        `Sandbox blob of ${buf.length} bytes exceeds the ${perBlobCap}-byte per-blob cap`,
-      );
-    }
-
-    const maxTotal = this.environmentService.getSandboxMaxTotalBytes();
-    if (buf.length > maxTotal) {
-      throw new Error(
-        `Sandbox blob of ${buf.length} bytes exceeds the total store cap of ${maxTotal} bytes`,
-      );
-    }
-
-    // Drop expired entries first, then evict oldest until the new blob fits.
-    this.sweep();
-    while (this.totalBytes + buf.length > maxTotal && this.map.size > 0) {
-      const oldest = this.map.keys().next().value as string;
-      this.evict(oldest);
-    }
-
-    const id = randomUUID();
-    const sha256 = createHash('sha256').update(buf).digest('hex');
-    const expiresAt = Date.now() + this.environmentService.getSandboxTtlMs();
-    this.map.set(id, { buf, mime, sha256, expiresAt });
-    this.totalBytes += buf.length;
-    return { id, sha256, size: buf.length };
-  }
-
-  /**
-   * Store a blob and return its anonymous read URL plus integrity metadata.
-   * Owns the single sandbox-URL composition (`${publicBase}${SANDBOX_API_PATH}/
-   * <id>`) so callers never hand-build the route; the raw put() stays public for
-   * tests/low-level callers. sha256 is also the blob's strong ETag.
-   */
-  putAndLink(
-    buf: Buffer,
-    mime: string,
-  ): { uri: string; sha256: string; size: number } {
-    const stored = this.put(buf, mime);
-    const base = this.environmentService.getSandboxPublicUrl();
-    return {
-      uri: `${base}${SANDBOX_API_PATH}/${stored.id}`,
-      sha256: stored.sha256,
-      size: stored.size,
-    };
-  }
-
-  /**
-   * Adapter to the package's blob-sandbox sink contract `{ put, has, evict }`.
-   * The sink speaks anonymous `uri`s while the store is keyed by `id`, so this is
-   * the ONE place that maps a sandbox uri back to its id (the last path segment).
-   * Both wiring sites (embedded MCP + in-app agent tools) use this so the uri↔id
-   * mapping and URL composition live next to putAndLink, not copy-pasted.
-   */
-  asSink(): {
-    put: (buf: Buffer, mime: string) => { uri: string; sha256: string; size: number };
-    has: (uri: string) => boolean;
-    evict: (uri: string) => void;
-  } {
-    const idOf = (uri: string) => uri.substring(uri.lastIndexOf('/') + 1);
-    return {
-      put: (buf, mime) => this.putAndLink(buf, mime),
-      has: (uri) => this.has(idOf(uri)),
-      evict: (uri) => this.remove(idOf(uri)),
-    };
-  }
-
-  /** True if the blob is still live (not evicted/expired). */
-  has(id: string): boolean {
-    return this.get(id) !== undefined;
-  }
-
-  /** Drop a blob by id (public wrapper over the private FIFO evict). */
-  remove(id: string): void {
-    this.evict(id);
-  }
-
-  /** Returns the entry, or undefined if missing OR expired (lazy expiry). */
-  get(id: string): SandboxEntry | undefined {
-    const entry = this.map.get(id);
-    if (!entry) return undefined;
-    if (entry.expiresAt <= Date.now()) {
-      this.evict(id);
-      return undefined;
-    }
-    return entry;
-  }
-
-  /** Current number of live entries (test/diagnostic helper). */
-  get size(): number {
-    return this.map.size;
-  }
-
-  /** Current total bytes held (test/diagnostic helper). */
-  get bytes(): number {
-    return this.totalBytes;
-  }
-
-  private evict(id: string): void {
-    const entry = this.map.get(id);
-    if (entry) {
-      this.totalBytes -= entry.buf.length;
-      this.map.delete(id);
-    }
-  }
-
-  private sweep(): void {
-    const now = Date.now();
-    for (const [id, entry] of this.map) {
-      if (entry.expiresAt <= now) {
-        this.evict(id);
-      }
-    }
-  }
-}

apps/server/src/integrations/throttle/throttle.module.ts

@@ -10,6 +10,7 @@ import {
   PAGE_TEMPLATE_THROTTLER,
   PUBLIC_SHARE_AI_THROTTLER,
 } from './throttler-names';
+import Redis from 'ioredis';
 
 @Module({
   imports: [
@@ -31,18 +32,16 @@ import {
             { name: PUBLIC_SHARE_AI_THROTTLER, ttl: 60_000, limit: 5 },
           ],
           errorMessage: 'Too many requests',
-          // Pass ioredis options (not a pre-built Redis instance) so
-          // ThrottlerStorageRedisService owns the connection and disconnects it
-          // in its onModuleDestroy. Passing an instance leaves disconnectRequired
-          // false, so the socket would leak on shutdown (e2e jest never exits).
-          storage: new ThrottlerStorageRedisService({
-            host: redisConfig.host,
-            port: redisConfig.port,
-            password: redisConfig.password,
-            db: redisConfig.db,
-            family: redisConfig.family,
-            keyPrefix: 'throttle:',
-          }),
+          storage: new ThrottlerStorageRedisService(
+            new Redis({
+              host: redisConfig.host,
+              port: redisConfig.port,
+              password: redisConfig.password,
+              db: redisConfig.db,
+              family: redisConfig.family,
+              keyPrefix: 'throttle:',
+            }),
+          ),
         };
       },
       inject: [EnvironmentService],

apps/server/src/main.ts

@@ -13,7 +13,6 @@ import fastifyCookie from '@fastify/cookie';
 import fastifyIp from 'fastify-ip';
 import { InternalLogFilter } from './common/logger/internal-log-filter';
 import { EnvironmentService } from './integrations/environment/environment.service';
-import { SANDBOX_API_PATH } from './integrations/sandbox/sandbox.constants';
 import { resolveFrameHeader } from './common/helpers';
 import { resolveTrustProxy } from './integrations/environment/trust-proxy.util';
 
@@ -127,10 +126,6 @@ async function bootstrap() {
         '/api/workspace/create',
         '/api/workspace/joined',
         '/api/workspace/find-by-email',
-        // Anonymous in-RAM blob sandbox: a remote consumer fetches blobs by an
-        // unguessable UUID without any workspace host context, so the
-        // workspace-resolution gate must not apply.
-        SANDBOX_API_PATH,
       ];
 
       if (

apps/server/test/integration/ai-chat-run.int-spec.ts

@@ -0,0 +1,304 @@
+import { Kysely } from 'kysely';
+import {
+  AiChatRunRepo,
+  SWEEP_RUN_STALE_MS,
+} from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
+import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunService } from '../../src/core/ai-chat/ai-chat-run.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createUser,
+  createChat,
+} from './db';
+
+/**
+ * Integration coverage for the #184 phase-1 durable agent run: real SQL against
+ * docmost_test. Proves the core invariant primitives — a run is a first-class
+ * lifecycle row, at most one is active per chat, a detached run's progress
+ * survives with NO subscriber, an explicit stop settles it as aborted, a
+ * reconnect read returns the persisted state, and a crash sweep recovers
+ * dangling runs.
+ */
+describe('AiChatRun durable lifecycle [integration]', () => {
+  let db: Kysely<any>;
+  let runRepo: AiChatRunRepo;
+  let messageRepo: AiChatMessageRepo;
+  let service: AiChatRunService;
+  let workspaceId: string;
+  let otherWorkspaceId: string;
+  let userId: string;
+  let chatId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    runRepo = new AiChatRunRepo(db as any);
+    messageRepo = new AiChatMessageRepo(db as any);
+    // Boot-sweep isn't triggered here; the isCloud stub is all the service needs
+    // for these direct-call integration cases (F7).
+    service = new AiChatRunService(runRepo, { isCloud: () => false } as never);
+    workspaceId = (await createWorkspace(db)).id;
+    otherWorkspaceId = (await createWorkspace(db)).id;
+    userId = (await createUser(db, workspaceId)).id;
+    chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  // Each test that creates an active run settles it (or uses its own chat) so the
+  // partial unique index does not bleed across tests.
+
+  it('insert + findById round-trips a run row, defaulting status/trigger', async () => {
+    const run = await runRepo.insert({
+      chatId,
+      workspaceId,
+      createdBy: userId,
+    });
+    expect(run.status).toBe('pending');
+    expect(run.trigger).toBe('user');
+    expect(run.stepCount).toBe(0);
+
+    const found = await runRepo.findById(run.id, workspaceId);
+    expect(found!.id).toBe(run.id);
+    // Workspace-scoped: a foreign workspace sees nothing.
+    expect(await runRepo.findById(run.id, otherWorkspaceId)).toBeUndefined();
+
+    // settle so it does not occupy the active slot
+    await runRepo.update(run.id, workspaceId, {
+      status: 'succeeded',
+      finishedAt: new Date(),
+    });
+  });
+
+  it('enforces ONE ACTIVE run per chat (partial unique index rejects a second)', async () => {
+    const activeChat = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const first = await runRepo.insert({
+      chatId: activeChat,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    // A second pending/running run on the SAME chat must be rejected by the DB.
+    await expect(
+      runRepo.insert({
+        chatId: activeChat,
+        workspaceId,
+        createdBy: userId,
+        status: 'running',
+      }),
+    ).rejects.toThrow();
+
+    // findActiveByChat returns exactly the one active run.
+    const active = await runRepo.findActiveByChat(activeChat, workspaceId);
+    expect(active!.id).toBe(first.id);
+
+    // Once it settles, the slot frees and a new run may start.
+    await runRepo.update(first.id, workspaceId, {
+      status: 'succeeded',
+      finishedAt: new Date(),
+    });
+    expect(
+      await runRepo.findActiveByChat(activeChat, workspaceId),
+    ).toBeUndefined();
+    const second = await runRepo.insert({
+      chatId: activeChat,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    expect(second.id).not.toBe(first.id);
+    await runRepo.update(second.id, workspaceId, {
+      status: 'aborted',
+      finishedAt: new Date(),
+    });
+  });
+
+  it('DETACHED run: persists + finalizes succeeded with NO subscriber, reconnect returns state', async () => {
+    // A dedicated chat so the active-run slot is clean.
+    const runChat = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+
+    // beginRun = the runner starts the turn (registers an in-memory controller).
+    const handle = await service.beginRun({
+      chatId: runChat,
+      workspaceId,
+      userId,
+    });
+    expect(handle.signal.aborted).toBe(false);
+    expect(service.isLocallyActive(handle.runId)).toBe(true);
+
+    // The assistant projection row (#183) is seeded + linked.
+    const seeded = await messageRepo.insert({
+      chatId: runChat,
+      workspaceId,
+      userId,
+      role: 'assistant',
+      content: '',
+      status: 'streaming',
+      metadata: { parts: [] } as never,
+    });
+    await service.linkAssistantMessage(handle.runId, workspaceId, seeded.id);
+
+    // Progress is persisted as steps finish — NO HTTP socket involved here at all.
+    await service.recordStep(handle.runId, workspaceId, 1);
+    await messageRepo.update(seeded.id, workspaceId, {
+      content: 'partial work',
+      metadata: { parts: [{ type: 'text', text: 'partial work' }] },
+    });
+
+    // The turn completes; finalize the projection then the run.
+    await messageRepo.update(seeded.id, workspaceId, {
+      content: 'final answer',
+      status: 'completed',
+    });
+    await service.finalizeRun(handle.runId, workspaceId, 'completed');
+
+    expect(service.isLocallyActive(handle.runId)).toBe(false);
+
+    // Reconnect: the latest run for the chat + its projected message, from the DB.
+    const run = await service.getLatestForChat(runChat, workspaceId);
+    expect(run!.status).toBe('succeeded');
+    expect(run!.stepCount).toBe(1);
+    expect(run!.assistantMessageId).toBe(seeded.id);
+    expect(run!.finishedAt).toBeTruthy();
+    const message = await messageRepo.findById(seeded.id, workspaceId);
+    expect(message!.status).toBe('completed');
+    expect(message!.content).toBe('final answer');
+  });
+
+  it('EXPLICIT stop aborts the run signal, marks the row, and settles as aborted', async () => {
+    const runChat = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const handle = await service.beginRun({
+      chatId: runChat,
+      workspaceId,
+      userId,
+    });
+
+    // User presses Stop.
+    const stopped = await service.requestStop(handle.runId, workspaceId);
+    expect(stopped).toBe(true);
+    expect(handle.signal.aborted).toBe(true);
+
+    // The row carries the stop request (distinct from a disconnect, which would
+    // leave stop_requested_at NULL).
+    const afterStop = await runRepo.findById(handle.runId, workspaceId);
+    expect(afterStop!.stopRequestedAt).toBeTruthy();
+
+    // The terminal callback (onAbort) settles the run.
+    await service.finalizeRun(handle.runId, workspaceId, 'aborted');
+    const run = await service.getLatestForChat(runChat, workspaceId);
+    expect(run!.status).toBe('aborted');
+  });
+
+  it('markStopRequested is a no-op on an already-settled run (returns undefined)', async () => {
+    const runChat = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const run = await runRepo.insert({
+      chatId: runChat,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    await runRepo.update(run.id, workspaceId, {
+      status: 'succeeded',
+      finishedAt: new Date(),
+    });
+    const marked = await runRepo.markStopRequested(run.id, workspaceId);
+    expect(marked).toBeUndefined();
+  });
+
+  it('sweepRunning aborts STALE dangling runs but not fresh or settled ones', async () => {
+    const sweepChat1 = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const sweepChat2 = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const sweepChat3 = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+
+    const stale = await runRepo.insert({
+      chatId: sweepChat1,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    const fresh = await runRepo.insert({
+      chatId: sweepChat2,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    const settled = await runRepo.insert({
+      chatId: sweepChat3,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    await runRepo.update(settled.id, workspaceId, {
+      status: 'succeeded',
+      finishedAt: new Date(),
+    });
+    // Backdate the stale run's updatedAt past the 10-minute staleness window.
+    await db
+      .updateTable('aiChatRuns')
+      .set({ updatedAt: new Date(Date.now() - 20 * 60 * 1000) })
+      .where('id', '=', stale.id)
+      .execute();
+
+    // WINDOWED sweep (phase-2 multi-instance timer path): only runs older than the
+    // staleness window are aborted, so a sibling replica's fresh run survives. The
+    // no-arg boot sweep (variant C) is unconditional — covered separately below.
+    const swept = await runRepo.sweepRunning({ staleMs: SWEEP_RUN_STALE_MS });
+    expect(swept).toBeGreaterThanOrEqual(1);
+
+    expect((await runRepo.findById(stale.id, workspaceId))!.status).toBe(
+      'aborted',
+    );
+    // Fresh (recently-updated) running run survives the WINDOWED sweep — a sibling
+    // replica may still be executing it.
+    expect((await runRepo.findById(fresh.id, workspaceId))!.status).toBe(
+      'running',
+    );
+    expect((await runRepo.findById(settled.id, workspaceId))!.status).toBe(
+      'succeeded',
+    );
+
+    // cleanup active fresh run
+    await runRepo.update(fresh.id, workspaceId, {
+      status: 'aborted',
+      finishedAt: new Date(),
+    });
+  });
+
+  it('sweepRunning() with NO args (boot sweep / variant C) aborts even a FRESH running run', async () => {
+    // F1/DECISION C at the SQL level: the unconditional boot sweep has NO
+    // staleness window, so a run updated just now (a fast restart) is settled too
+    // — otherwise it would stay 'running' forever and 409 every future turn.
+    const bootChat = (
+      await createChat(db, { workspaceId, creatorId: userId })
+    ).id;
+    const fresh = await runRepo.insert({
+      chatId: bootChat,
+      workspaceId,
+      createdBy: userId,
+      status: 'running',
+    });
+    // updatedAt = now (fresh, untouched). The no-arg sweep settles it anyway.
+    const swept = await runRepo.sweepRunning();
+    expect(swept).toBeGreaterThanOrEqual(1);
+    expect((await runRepo.findById(fresh.id, workspaceId))!.status).toBe(
+      'aborted',
+    );
+  });
+});

packages/mcp/README.md

@@ -16,7 +16,7 @@ license.
 > that interface. Other Docmost MCPs are human-shaped — they expose "open the page" and
 > "replace the page"; this one exposes the editing primitives a model is good at.
 
-It exposes **40 tools** built around three ideas that the other Docmost MCPs do not
+It exposes **38 tools** built around three ideas that the other Docmost MCPs do not
 combine:
 
 1. **Surgical, token-cheap edits.** Address a single block by id and patch it, or run
@@ -106,7 +106,7 @@ There are several Docmost MCPs. Here is a capability-by-capability comparison.
 
 ## Tools
 
-All 40 tools, grouped by what you'd reach for them.
+All 38 tools, grouped by what you'd reach for them.
 
 ### Exploration & retrieval
 
@@ -203,14 +203,6 @@ All 40 tools, grouped by what you'd reach for them.
   node referencing the old attachment (recursively, including callouts/tables) via the
   live document, preserving comments, alignment and alt text. (In-place overwrite is
   deliberately avoided — some Docmost versions corrupt the attachment on overwrite.)
-- **`stash_page`** — Serialize a whole page (its full ProseMirror JSON) into an ephemeral
-  in-RAM blob and return ONLY a short anonymous URL — the body never enters the model
-  context, so it is the way to hand a large page (and its images) to an external consumer
-  without truncation. Every internal file/image attachment is mirrored into the same
-  sandbox and its `src` rewritten to a sandbox URL; external http(s) images are left
-  untouched. Returns `{ uri, size, sha256, images:{ mirrored, failed } }` (`sha256` is also
-  the blob's ETag). Blobs are RAM-only, expire after a short TTL (~1h) and are bound to the
-  server instance that created them.
 
 ### Comments
 

packages/mcp/README.ru.md

@@ -17,7 +17,7 @@
 > «открыть страницу» и «заменить страницу»; этот даёт примитивы редактирования, в которых
 > модель сильна.
 
-Сервер предоставляет **40 инструментов**, построенных вокруг трёх идей, которые другие
+Сервер предоставляет **38 инструментов**, построенных вокруг трёх идей, которые другие
 Docmost-MCP не сочетают:
 
 1. **Точечные, экономичные по токенам правки.** Адресуйте отдельный блок по id и патчите
@@ -109,7 +109,7 @@ Docmost-MCP не сочетают:
 
 ## Инструменты
 
-Все 40 инструментов, сгруппированы по задачам, для которых вы их возьмёте.
+Все 38 инструментов, сгруппированы по задачам, для которых вы их возьмёте.
 
 ### Чтение и поиск
 
@@ -209,15 +209,6 @@ Docmost-MCP не сочетают:
   коллауты/таблицы), через живой документ, сохраняя комментарии, выравнивание и alt-текст.
   (Перезапись «по месту» намеренно не используется — некоторые версии Docmost портят
   вложение при перезаписи.)
-- **`stash_page`** — Сериализовать страницу целиком (её полный ProseMirror JSON) в
-  эфемерный blob в оперативной памяти и вернуть ТОЛЬКО короткий анонимный URL — тело
-  никогда не попадает в контекст модели, поэтому это способ передать большую страницу
-  (вместе с её изображениями) внешнему потребителю без усечения. Каждое внутреннее
-  файловое/графическое вложение зеркалируется в тот же sandbox, а его `src` переписывается
-  на URL sandbox; внешние http(s)-изображения остаются нетронутыми. Возвращает
-  `{ uri, size, sha256, images:{ mirrored, failed } }` (`sha256` — это также ETag blob'а).
-  Blob'ы хранятся только в оперативной памяти, истекают через короткий TTL (~1 ч) и
-  привязаны к тому экземпляру сервера, который их создал.
 
 ### Комментарии
 

packages/mcp/build/client.js

@@ -7,7 +7,6 @@ import { TiptapTransformer } from "@hocuspocus/transformer";
 import * as Y from "yjs";
 import WebSocket from "ws";
 import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
-import { collectInternalFileNodes, normalizeFileUrl, resolveInternalFilePath, } from "./lib/internal-file-urls.js";
 import { updatePageContentRealtime, replacePageContent, markdownToProseMirror, markdownToProseMirrorCanonical, mutatePageContent, buildCollabWsUrl, assertYjsEncodable, applyDocToFragment, } from "./lib/collaboration.js";
 import { footnoteWarningsField } from "./lib/footnote-analyze.js";
 import { buildPageTree } from "./lib/tree.js";
@@ -52,13 +51,6 @@ export class DocmostClient {
     // its token instead of calling POST /auth/collab-token; on a 401/403 it is
     // re-invoked once. Used by the internal agent to carry signed provenance.
     getCollabTokenFn = null;
-    // Optional blob-sandbox sink for the stash tool. Null when not configured.
-    sandboxPut = null;
-    // Optional probes paired with the sink. `has` lets stashPage detect a blob
-    // FIFO-evicted by a LATER put in the same stash; `evict` lets it free this
-    // op's image blobs if the final doc put throws. Null when the sink omits them.
-    sandboxHas = null;
-    sandboxEvict = null;
     // In-flight login dedup: when the token expires, the 401 interceptor,
     // ensureAuthenticated, getCollabTokenWithReauth and the two multipart retries
     // can all call login() at once. Memoizing a single promise collapses that
@@ -85,11 +77,6 @@ export class DocmostClient {
         if (config.getCollabToken) {
             this.getCollabTokenFn = config.getCollabToken;
         }
-        if (config.sandbox) {
-            this.sandboxPut = config.sandbox.put;
-            this.sandboxHas = config.sandbox.has ?? null;
-            this.sandboxEvict = config.sandbox.evict ?? null;
-        }
         this.client = axios.create({
             baseURL: this.apiUrl,
             // Default request timeout so a hung connection cannot wedge a per-page
@@ -618,181 +605,6 @@ export class DocmostClient {
             content: data.content || { type: "doc", content: [] },
         };
     }
-    /**
-     * Fetch an INTERNAL Docmost file (authed loopback) for sandbox mirroring.
-     * `src` is normalized to `/api/files/<id>/<file>`; `this.client.baseURL`
-     * already ends in `/api`, so we strip the leading `/api` and request the
-     * relative path with the client's Authorization header. Returns the raw bytes
-     * and the response Content-Type (mime), defaulting to octet-stream.
-     *
-     * The fetch is size-bounded (hard 64 MiB ceiling) purely to protect memory;
-     * the authoritative per-blob cap is enforced by the sandbox `put`. The path is
-     * resolved via resolveInternalFilePath, which REJECTS (throws) any traversal
-     * or percent-encoded src that would let an attacker-controlled `attrs.src`
-     * escape `/api/files/` and reach another internal endpoint (SSRF). That throw
-     * happens before this.client.get, so a malicious src is counted as a failed
-     * mirror — it never reaches the network.
-     */
-    async fetchInternalFile(src) {
-        const HARD_CEILING = 64 * 1024 * 1024; // 64 MiB memory guard
-        const relPath = resolveInternalFilePath(src);
-        const response = await this.client.get(relPath, {
-            responseType: "arraybuffer",
-            timeout: 30000,
-            maxContentLength: HARD_CEILING,
-            maxBodyLength: HARD_CEILING,
-        });
-        const buffer = Buffer.from(response.data);
-        if (buffer.length === 0) {
-            throw new Error(`Empty file response from "${src}"`);
-        }
-        const rawCt = response.headers?.["content-type"];
-        const mime = typeof rawCt === "string" && rawCt.length > 0
-            ? rawCt.split(";")[0].trim().toLowerCase()
-            : "application/octet-stream";
-        return { buffer, mime };
-    }
-    /**
-     * Stash a page's full content into the in-RAM blob sandbox and return ONLY a
-     * short anonymous URL — the body never enters the model context (this is the
-     * whole point: ~30KB+ ProseMirror docs blow the model context if passed as a
-     * tool argument). Every INTERNAL file/image src (the type-agnostic criterion,
-     * so drawio/excalidraw/video/file nodes are covered too) is mirrored into the
-     * sandbox and its `src` rewritten to the sandbox URL, so an external consumer
-     * can fetch the images anonymously. External http(s) srcs are left untouched.
-     *
-     * Blobs live in RAM with a short TTL and are cleared on restart — consume the
-     * URLs within the TTL and one uptime. A failed image fetch never aborts the
-     * doc: the original src is kept and the failure counted.
-     *
-     * Returns { uri, sha256, size, images:{mirrored, failed} }. `uri` and `sha256`
-     * are for the document blob; `sha256` is also the blob's ETag (integrity).
-     */
-    async stashPage(pageId) {
-        if (!this.sandboxPut) {
-            throw new Error("stash_page is unavailable: the blob sandbox is not configured on this server");
-        }
-        await this.ensureAuthenticated();
-        // Stash the SAME shape get_page_json returns (id/title/.../content), with a
-        // deep clone so the rewrite never mutates anything shared.
-        const pageJson = await this.getPageJson(pageId);
-        const cloned = structuredClone(pageJson);
-        // Group internal-file nodes by normalized src so each unique resource is
-        // fetched + stored ONCE (dedup), and every node sharing that src points at
-        // the one sandbox blob. Capture each node's ORIGINAL raw src per-node:
-        // dedup groups nodes whose normalized src is equal even when their raw srcs
-        // differ (e.g. `/api/files/...` vs the bare `/files/...`), so on a revert we
-        // must restore each node's own original value, not the group key.
-        const bySrc = new Map();
-        for (const node of collectInternalFileNodes(cloned.content)) {
-            const origSrc = String(node.attrs.src);
-            const src = normalizeFileUrl(origSrc);
-            const entry = { node, origSrc };
-            const group = bySrc.get(src);
-            if (group)
-                group.push(entry);
-            else
-                bySrc.set(src, [entry]);
-        }
-        let mirrored = 0;
-        let failed = 0;
-        // Record every successful mirror so it can be (a) reverted if its blob gets
-        // FIFO-evicted by a LATER put in this same stash, and (b) freed if the final
-        // doc put throws.
-        const mirrors = [];
-        const MAX_CONCURRENCY = 5;
-        const groups = [...bySrc.entries()];
-        for (let i = 0; i < groups.length; i += MAX_CONCURRENCY) {
-            const batch = groups.slice(i, i + MAX_CONCURRENCY);
-            await Promise.all(batch.map(async ([src, entries]) => {
-                try {
-                    const { buffer, mime } = await this.fetchInternalFile(src);
-                    // put may throw if the blob exceeds the per-blob/total caps.
-                    const stored = this.sandboxPut(buffer, mime);
-                    for (const entry of entries)
-                        entry.node.attrs.src = stored.uri;
-                    mirrors.push({ uri: stored.uri, entries });
-                    mirrored++;
-                }
-                catch (err) {
-                    // One bad/oversized image (or a rejected traversal src) must not
-                    // abort the document. Logged unconditionally (never the blob body),
-                    // matching the package's ungated console.warn convention.
-                    failed++;
-                    console.warn(`stash_page: failed to mirror "${src}": ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }));
-        }
-        // Revert one mirror's nodes to their original internal srcs and re-count it
-        // as failed (its blob was FIFO-evicted before the doc could reference it
-        // safely).
-        const revertMirror = (mirror) => {
-            for (const entry of mirror.entries)
-                entry.node.attrs.src = entry.origSrc;
-            mirrored--;
-            failed++;
-            console.warn(`stash_page: mirrored blob ${mirror.uri} was evicted before the doc ` +
-                `could safely reference it; reverted its src and counted it as failed`);
-        };
-        // Pre-put reconciliation: an image put earlier in THIS stash can FIFO-evict
-        // an even-earlier image of the same stash. Drop those from the live set
-        // first so the first serialized doc is already mostly correct.
-        let liveMirrors = mirrors;
-        if (this.sandboxHas) {
-            liveMirrors = [];
-            for (const mirror of mirrors) {
-                if (this.sandboxHas(mirror.uri))
-                    liveMirrors.push(mirror);
-                else
-                    revertMirror(mirror);
-            }
-        }
-        // Put the document, then reconcile against eviction caused by the doc put
-        // ITSELF (the doc is newest, FIFO drops oldest = this stash's images). Each
-        // iteration reverts >=1 mirror, so the loop terminates (worst case: all
-        // images reverted and the doc references no sandbox image URLs).
-        let stored;
-        for (;;) {
-            const docBuf = Buffer.from(JSON.stringify(cloned), "utf8");
-            let docStored;
-            try {
-                docStored = this.sandboxPut(docBuf, "application/json");
-            }
-            catch (err) {
-                // The doc put failed (e.g. doc exceeds the cap). Free this op's image
-                // blobs instead of leaking them in RAM for the whole TTL, then
-                // re-throw.
-                if (this.sandboxEvict) {
-                    for (const mirror of liveMirrors)
-                        this.sandboxEvict(mirror.uri);
-                }
-                throw err;
-            }
-            if (!this.sandboxHas) {
-                stored = docStored;
-                break;
-            }
-            const evictedNow = liveMirrors.filter((m) => !this.sandboxHas(m.uri));
-            if (evictedNow.length === 0) {
-                stored = docStored;
-                break;
-            }
-            // The doc we just stored references now-dead blobs. Revert those nodes,
-            // drop the stale doc blob, and loop to re-serialize + re-put the
-            // corrected doc.
-            for (const mirror of evictedNow)
-                revertMirror(mirror);
-            liveMirrors = liveMirrors.filter((m) => this.sandboxHas(m.uri));
-            if (this.sandboxEvict)
-                this.sandboxEvict(docStored.uri);
-        }
-        return {
-            uri: stored.uri,
-            sha256: stored.sha256,
-            size: stored.size,
-            images: { mirrored, failed },
-        };
-    }
     /**
      * Compact outline of a page's top-level blocks (no full document body).
      * Cheap way to locate sections/tables and grab block ids before drilling in

packages/mcp/build/index.js

@@ -285,38 +285,6 @@ export function createDocmostMcpServer(config) {
         const result = await docmostClient.editPageText(pageId, edits);
         return jsonContent(result);
     });
-    // Tool: stash_page — returns a resource_link (NOT embedded text) so the doc
-    // body never enters the model context. Registered directly (not via
-    // registerShared) because that helper only emits text content. Also returns
-    // `structuredContent` carrying the full documented `{uri, sha256, size, images}`
-    // shape alongside the resource_link, so MCP clients receive the blob's sha256
-    // (its ETag, for integrity) and mirror counts, not just the link.
-    server.registerTool(SHARED_TOOL_SPECS.stashPage.mcpName, {
-        description: SHARED_TOOL_SPECS.stashPage.description,
-        inputSchema: SHARED_TOOL_SPECS.stashPage.buildShape(z),
-    }, async ({ pageId }) => {
-        const result = await docmostClient.stashPage(pageId);
-        return {
-            content: [
-                {
-                    type: "resource_link",
-                    uri: result.uri,
-                    name: "page.json",
-                    mimeType: "application/json",
-                    size: result.size,
-                },
-            ],
-            // Mirror the full documented result shape ({ uri, size, sha256, images })
-            // as structuredContent so MCP clients get the blob's sha256 (its ETag, for
-            // integrity) and the mirror counts, not just the resource_link.
-            structuredContent: {
-                uri: result.uri,
-                sha256: result.sha256,
-                size: result.size,
-                images: result.images,
-            },
-        };
-    });
     // Tool: patch_node
     server.registerTool("patch_node", {
         description: "Replaces a single block identified by its attrs.id WITHOUT resending the " +

packages/mcp/build/lib/internal-file-urls.js

@@ -1,110 +0,0 @@
-// Detection + collection of INTERNAL Docmost file URLs inside a ProseMirror doc.
-//
-// An internal file URL is a relative path served by Docmost's authenticated
-// attachment route (`GET /api/files/:fileId/:fileName`). It is useless to an
-// external consumer (relative + needs a Docmost session), so the stash tool
-// mirrors every such resource into the blob sandbox and rewrites its `src`.
-//
-// The criterion is "internal file URL", NOT the node TYPE: image, drawio,
-// excalidraw, video and file nodes all carry such a `src`, so a type-agnostic
-// walker covers them all. External http(s) srcs (CDNs) are left untouched.
-//
-// Mirrors editor-ext's isInternalFileUrl / normalizeFileUrl (kept as a local
-// dup so the ESM mcp package does not depend on the editor-ext build).
-function isInternalFileUrl(url) {
-    if (typeof url !== "string")
-        return false;
-    const normalized = url.trim();
-    return (normalized.startsWith("/api/files/") || normalized.startsWith("/files/"));
-}
-/** Normalize a bare `/files/...` src to the canonical `/api/files/...` form. */
-export function normalizeFileUrl(src) {
-    const trimmed = src.trim();
-    if (trimmed.startsWith("/files/"))
-        return "/api" + trimmed;
-    return trimmed;
-}
-/**
- * Resolve a page-content `src` into the safe, `/api`-relative path the stash
- * tool may fetch over the authenticated loopback client — or THROW.
- *
- * SECURITY (SSRF / path-traversal): `src` comes from page content and is fully
- * attacker-controllable. The mirroring fetch runs through the AUTHENTICATED
- * loopback axios client whose baseURL ends in `/api`, so a naive
- * `src.replace(/^\/api/, "")` lets a crafted value like
- * `/api/files/../auth/whoami` collapse (via axios/WHATWG URL `..` resolution)
- * into an ARBITRARY internal GET endpoint, whose authed response would then be
- * stored in the anonymous sandbox (SSRF + data exfiltration). A prefix-only
- * `startsWith("/api/files/")` check does NOT defend against this because the
- * `..` segments are still present in the raw string and resolved later.
- *
- * This function defeats that by resolving the canonical pathname FIRST and only
- * then asserting it still lives under `/api/files/`:
- *  - it rejects any percent-encoded dot/slash (`%2e` / `%2f`): the WHATWG URL
- *    parser collapses LITERAL `../` but does NOT decode `%2f` separators, so a
- *    content-controlled src must never be allowed to smuggle those past the
- *    canonicalization;
- *  - it resolves `new URL(trimmed, "http://internal.invalid").pathname`, which
- *    normalizes `..`/`.` segments (e.g. `/api/files/../auth/whoami` →
- *    `/api/auth/whoami`);
- *  - it then requires the canonical pathname to start with `/api/files/`, so a
- *    traversal that escaped that subtree is rejected.
- *
- * Returns the path RELATIVE to the `/api` base (e.g. `/files/<id>/<name>`),
- * ready to hand to the loopback client. The throw happens BEFORE any network
- * call, so a rejected src is counted as a failed mirror and its original src is
- * kept (the per-image try/catch in stashPage never aborts the whole document).
- */
-export function resolveInternalFilePath(src) {
-    const trimmed = src.trim();
-    // Percent-encoded dot/slash must never reach the URL canonicalizer: the
-    // WHATWG parser does NOT decode `%2f` into a path separator, so an encoded
-    // `..%2fauth` would survive canonicalization and still escape /api/files/.
-    if (/%2e|%2f/i.test(trimmed)) {
-        throw new Error(`Refusing internal file src with percent-encoded path segment: "${src}"`);
-    }
-    let pathname;
-    try {
-        // The base host is irrelevant (never contacted); it only lets the parser
-        // resolve a relative `src` and normalize `..`/`.` segments.
-        pathname = new URL(trimmed, "http://internal.invalid").pathname;
-    }
-    catch {
-        throw new Error(`Invalid internal file src: "${src}"`);
-    }
-    if (!pathname.startsWith("/api/files/")) {
-        throw new Error(`Refusing internal file src that escapes /api/files/: "${src}"`);
-    }
-    // Strip the `/api` base prefix; the loopback client's baseURL already ends
-    // in `/api`, so it expects the path relative to that (e.g. /files/<id>/<f>).
-    return pathname.replace(/^\/api/, "");
-}
-/**
- * Recursively collect every node whose `attrs.src` is an internal file URL.
- * Returns references to the live nodes (so the caller can rewrite `attrs.src`
- * in place on its clone). Descends `content` arrays, covering callouts, tables,
- * details and any other nested container.
- */
-export function collectInternalFileNodes(doc) {
-    const out = [];
-    const visit = (node) => {
-        if (!node)
-            return;
-        if (Array.isArray(node)) {
-            for (const child of node)
-                visit(child);
-            return;
-        }
-        if (typeof node !== "object")
-            return;
-        if (node.attrs && isInternalFileUrl(node.attrs.src)) {
-            out.push(node);
-        }
-        if (Array.isArray(node.content)) {
-            for (const child of node.content)
-                visit(child);
-        }
-    };
-    visit(doc);
-    return out;
-}

packages/mcp/build/tool-specs.js

@@ -209,27 +209,4 @@ export const SHARED_TOOL_SPECS = {
                 .describe('List of find/replace operations, applied in order'),
         }),
     },
-    // --- hand a large page to an external consumer without bloating context ---
-    stashPage: {
-        mcpName: 'stash_page',
-        inAppKey: 'stashPage',
-        description: 'Serialize a whole page (the full ProseMirror JSON, as get_page_json ' +
-            'returns) into an ephemeral in-memory blob and return ONLY a short ' +
-            'anonymous URL to it — the body NEVER enters the model context, so this ' +
-            'is the way to hand a large page (or its images) to an external consumer ' +
-            'without truncation. Every internal file/image attachment is mirrored ' +
-            'into the same sandbox and its src rewritten to a sandbox URL, so the ' +
-            'consumer can fetch the images anonymously too; external http(s) images ' +
-            'are left untouched. Returns { uri, size, sha256, images:{mirrored, ' +
-            'failed} }. Integrity: the blob is served with ETag = its sha256, so a ' +
-            'truncated/corrupted fetch is detectable. Blobs are RAM-only: they expire ' +
-            'after a short TTL (~1h) and are cleared on restart — consume the URL ' +
-            'within the TTL and one uptime, or re-stash. A blob is bound to the ' +
-            'server instance that created it: in a multi-replica deployment without ' +
-            'sticky sessions a blob stored on one instance is not retrievable via the ' +
-            'sandbox URL on another (it 404s like an expired one).',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-        }),
-    },
 };

packages/mcp/src/client.ts

@@ -13,11 +13,6 @@ import { TiptapTransformer } from "@hocuspocus/transformer";
 import * as Y from "yjs";
 import WebSocket from "ws";
 import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
-import {
-  collectInternalFileNodes,
-  normalizeFileUrl,
-  resolveInternalFilePath,
-} from "./lib/internal-file-urls.js";
 import {
   updatePageContentRealtime,
   replacePageContent,
@@ -107,14 +102,6 @@ const MIME_TO_EXT: Record<string, string> = {
  * Housed here (not in index.ts) so client.ts has no type dependency on index.ts;
  * index.ts re-exports it for the package's public surface.
  */
-// Sink the stash tool writes blobs into. The host app binds this to its in-RAM
-// SandboxStore and composes the public `uri` (the package never sees the store
-// or any env). `put` returns the anonymous read URL plus integrity metadata.
-export type SandboxPut = (
-  buf: Buffer,
-  mime: string,
-) => { uri: string; sha256: string; size: number };
-
 export type DocmostMcpConfig = { apiUrl: string } & (
   | { email: string; password: string }
   | { getToken: () => Promise<string> } // returns a BARE JWT; the client adds "Bearer "
@@ -122,15 +109,6 @@ export type DocmostMcpConfig = { apiUrl: string } & (
     // Optional collab-token provider (returns a ready collab JWT). Common to
     // both branches; see the type doc above.
     getCollabToken?: () => Promise<string>;
-    // Optional blob sandbox sink. Present only where the stash tool is wired;
-    // when absent, stash_page throws a clear "not configured" error. The
-    // optional `has`/`evict` probes let stashPage keep its mirror counts honest
-    // under the store's FIFO eviction (see stashPage); older sinks omit them.
-    sandbox?: {
-      put: SandboxPut;
-      has?: (uri: string) => boolean;
-      evict?: (uri: string) => void;
-    };
   };
 
 export class DocmostClient {
@@ -148,13 +126,6 @@ export class DocmostClient {
   // its token instead of calling POST /auth/collab-token; on a 401/403 it is
   // re-invoked once. Used by the internal agent to carry signed provenance.
   private getCollabTokenFn: (() => Promise<string>) | null = null;
-  // Optional blob-sandbox sink for the stash tool. Null when not configured.
-  private sandboxPut: SandboxPut | null = null;
-  // Optional probes paired with the sink. `has` lets stashPage detect a blob
-  // FIFO-evicted by a LATER put in the same stash; `evict` lets it free this
-  // op's image blobs if the final doc put throws. Null when the sink omits them.
-  private sandboxHas: ((uri: string) => boolean) | null = null;
-  private sandboxEvict: ((uri: string) => void) | null = null;
   // In-flight login dedup: when the token expires, the 401 interceptor,
   // ensureAuthenticated, getCollabTokenWithReauth and the two multipart retries
   // can all call login() at once. Memoizing a single promise collapses that
@@ -194,11 +165,6 @@ export class DocmostClient {
     if (config.getCollabToken) {
       this.getCollabTokenFn = config.getCollabToken;
     }
-    if (config.sandbox) {
-      this.sandboxPut = config.sandbox.put;
-      this.sandboxHas = config.sandbox.has ?? null;
-      this.sandboxEvict = config.sandbox.evict ?? null;
-    }
     this.client = axios.create({
       baseURL: this.apiUrl,
       // Default request timeout so a hung connection cannot wedge a per-page
@@ -801,203 +767,6 @@ export class DocmostClient {
     };
   }
 
-  /**
-   * Fetch an INTERNAL Docmost file (authed loopback) for sandbox mirroring.
-   * `src` is normalized to `/api/files/<id>/<file>`; `this.client.baseURL`
-   * already ends in `/api`, so we strip the leading `/api` and request the
-   * relative path with the client's Authorization header. Returns the raw bytes
-   * and the response Content-Type (mime), defaulting to octet-stream.
-   *
-   * The fetch is size-bounded (hard 64 MiB ceiling) purely to protect memory;
-   * the authoritative per-blob cap is enforced by the sandbox `put`. The path is
-   * resolved via resolveInternalFilePath, which REJECTS (throws) any traversal
-   * or percent-encoded src that would let an attacker-controlled `attrs.src`
-   * escape `/api/files/` and reach another internal endpoint (SSRF). That throw
-   * happens before this.client.get, so a malicious src is counted as a failed
-   * mirror — it never reaches the network.
-   */
-  private async fetchInternalFile(
-    src: string,
-  ): Promise<{ buffer: Buffer; mime: string }> {
-    const HARD_CEILING = 64 * 1024 * 1024; // 64 MiB memory guard
-    const relPath = resolveInternalFilePath(src);
-    const response = await this.client.get(relPath, {
-      responseType: "arraybuffer",
-      timeout: 30000,
-      maxContentLength: HARD_CEILING,
-      maxBodyLength: HARD_CEILING,
-    });
-    const buffer = Buffer.from(response.data);
-    if (buffer.length === 0) {
-      throw new Error(`Empty file response from "${src}"`);
-    }
-    const rawCt = response.headers?.["content-type"];
-    const mime =
-      typeof rawCt === "string" && rawCt.length > 0
-        ? rawCt.split(";")[0].trim().toLowerCase()
-        : "application/octet-stream";
-    return { buffer, mime };
-  }
-
-  /**
-   * Stash a page's full content into the in-RAM blob sandbox and return ONLY a
-   * short anonymous URL — the body never enters the model context (this is the
-   * whole point: ~30KB+ ProseMirror docs blow the model context if passed as a
-   * tool argument). Every INTERNAL file/image src (the type-agnostic criterion,
-   * so drawio/excalidraw/video/file nodes are covered too) is mirrored into the
-   * sandbox and its `src` rewritten to the sandbox URL, so an external consumer
-   * can fetch the images anonymously. External http(s) srcs are left untouched.
-   *
-   * Blobs live in RAM with a short TTL and are cleared on restart — consume the
-   * URLs within the TTL and one uptime. A failed image fetch never aborts the
-   * doc: the original src is kept and the failure counted.
-   *
-   * Returns { uri, sha256, size, images:{mirrored, failed} }. `uri` and `sha256`
-   * are for the document blob; `sha256` is also the blob's ETag (integrity).
-   */
-  async stashPage(pageId: string): Promise<{
-    uri: string;
-    sha256: string;
-    size: number;
-    images: { mirrored: number; failed: number };
-  }> {
-    if (!this.sandboxPut) {
-      throw new Error(
-        "stash_page is unavailable: the blob sandbox is not configured on this server",
-      );
-    }
-    await this.ensureAuthenticated();
-
-    // Stash the SAME shape get_page_json returns (id/title/.../content), with a
-    // deep clone so the rewrite never mutates anything shared.
-    const pageJson = await this.getPageJson(pageId);
-    const cloned: any = structuredClone(pageJson);
-
-    // Group internal-file nodes by normalized src so each unique resource is
-    // fetched + stored ONCE (dedup), and every node sharing that src points at
-    // the one sandbox blob. Capture each node's ORIGINAL raw src per-node:
-    // dedup groups nodes whose normalized src is equal even when their raw srcs
-    // differ (e.g. `/api/files/...` vs the bare `/files/...`), so on a revert we
-    // must restore each node's own original value, not the group key.
-    const bySrc = new Map<string, Array<{ node: any; origSrc: string }>>();
-    for (const node of collectInternalFileNodes(cloned.content)) {
-      const origSrc = String(node.attrs.src);
-      const src = normalizeFileUrl(origSrc);
-      const entry = { node, origSrc };
-      const group = bySrc.get(src);
-      if (group) group.push(entry);
-      else bySrc.set(src, [entry]);
-    }
-
-    let mirrored = 0;
-    let failed = 0;
-    // Record every successful mirror so it can be (a) reverted if its blob gets
-    // FIFO-evicted by a LATER put in this same stash, and (b) freed if the final
-    // doc put throws.
-    const mirrors: Array<{
-      uri: string;
-      entries: Array<{ node: any; origSrc: string }>;
-    }> = [];
-    const MAX_CONCURRENCY = 5;
-    const groups = [...bySrc.entries()];
-    for (let i = 0; i < groups.length; i += MAX_CONCURRENCY) {
-      const batch = groups.slice(i, i + MAX_CONCURRENCY);
-      await Promise.all(
-        batch.map(async ([src, entries]) => {
-          try {
-            const { buffer, mime } = await this.fetchInternalFile(src);
-            // put may throw if the blob exceeds the per-blob/total caps.
-            const stored = this.sandboxPut!(buffer, mime);
-            for (const entry of entries) entry.node.attrs.src = stored.uri;
-            mirrors.push({ uri: stored.uri, entries });
-            mirrored++;
-          } catch (err) {
-            // One bad/oversized image (or a rejected traversal src) must not
-            // abort the document. Logged unconditionally (never the blob body),
-            // matching the package's ungated console.warn convention.
-            failed++;
-            console.warn(
-              `stash_page: failed to mirror "${src}": ${
-                err instanceof Error ? err.message : String(err)
-              }`,
-            );
-          }
-        }),
-      );
-    }
-
-    // Revert one mirror's nodes to their original internal srcs and re-count it
-    // as failed (its blob was FIFO-evicted before the doc could reference it
-    // safely).
-    const revertMirror = (mirror: {
-      uri: string;
-      entries: Array<{ node: any; origSrc: string }>;
-    }) => {
-      for (const entry of mirror.entries) entry.node.attrs.src = entry.origSrc;
-      mirrored--;
-      failed++;
-      console.warn(
-        `stash_page: mirrored blob ${mirror.uri} was evicted before the doc ` +
-          `could safely reference it; reverted its src and counted it as failed`,
-      );
-    };
-
-    // Pre-put reconciliation: an image put earlier in THIS stash can FIFO-evict
-    // an even-earlier image of the same stash. Drop those from the live set
-    // first so the first serialized doc is already mostly correct.
-    let liveMirrors = mirrors;
-    if (this.sandboxHas) {
-      liveMirrors = [];
-      for (const mirror of mirrors) {
-        if (this.sandboxHas(mirror.uri)) liveMirrors.push(mirror);
-        else revertMirror(mirror);
-      }
-    }
-
-    // Put the document, then reconcile against eviction caused by the doc put
-    // ITSELF (the doc is newest, FIFO drops oldest = this stash's images). Each
-    // iteration reverts >=1 mirror, so the loop terminates (worst case: all
-    // images reverted and the doc references no sandbox image URLs).
-    let stored: { uri: string; sha256: string; size: number };
-    for (;;) {
-      const docBuf = Buffer.from(JSON.stringify(cloned), "utf8");
-      let docStored: { uri: string; sha256: string; size: number };
-      try {
-        docStored = this.sandboxPut(docBuf, "application/json");
-      } catch (err) {
-        // The doc put failed (e.g. doc exceeds the cap). Free this op's image
-        // blobs instead of leaking them in RAM for the whole TTL, then
-        // re-throw.
-        if (this.sandboxEvict) {
-          for (const mirror of liveMirrors) this.sandboxEvict(mirror.uri);
-        }
-        throw err;
-      }
-
-      if (!this.sandboxHas) {
-        stored = docStored;
-        break;
-      }
-      const evictedNow = liveMirrors.filter((m) => !this.sandboxHas!(m.uri));
-      if (evictedNow.length === 0) {
-        stored = docStored;
-        break;
-      }
-      // The doc we just stored references now-dead blobs. Revert those nodes,
-      // drop the stale doc blob, and loop to re-serialize + re-put the
-      // corrected doc.
-      for (const mirror of evictedNow) revertMirror(mirror);
-      liveMirrors = liveMirrors.filter((m) => this.sandboxHas!(m.uri));
-      if (this.sandboxEvict) this.sandboxEvict(docStored.uri);
-    }
-    return {
-      uri: stored.uri,
-      sha256: stored.sha256,
-      size: stored.size,
-      images: { mirrored, failed },
-    };
-  }
-
   /**
    * Compact outline of a page's top-level blocks (no full document body).
    * Cheap way to locate sections/tables and grab block ids before drilling in

packages/mcp/src/index.ts

@@ -408,43 +408,6 @@ registerShared(SHARED_TOOL_SPECS.editPageText, async ({ pageId, edits }) => {
   return jsonContent(result);
 });
 
-// Tool: stash_page — returns a resource_link (NOT embedded text) so the doc
-// body never enters the model context. Registered directly (not via
-// registerShared) because that helper only emits text content. Also returns
-// `structuredContent` carrying the full documented `{uri, sha256, size, images}`
-// shape alongside the resource_link, so MCP clients receive the blob's sha256
-// (its ETag, for integrity) and mirror counts, not just the link.
-server.registerTool(
-  SHARED_TOOL_SPECS.stashPage.mcpName,
-  {
-    description: SHARED_TOOL_SPECS.stashPage.description,
-    inputSchema: SHARED_TOOL_SPECS.stashPage.buildShape!(z),
-  },
-  async ({ pageId }: { pageId: string }) => {
-    const result = await docmostClient.stashPage(pageId);
-    return {
-      content: [
-        {
-          type: "resource_link" as const,
-          uri: result.uri,
-          name: "page.json",
-          mimeType: "application/json",
-          size: result.size,
-        },
-      ],
-      // Mirror the full documented result shape ({ uri, size, sha256, images })
-      // as structuredContent so MCP clients get the blob's sha256 (its ETag, for
-      // integrity) and the mirror counts, not just the resource_link.
-      structuredContent: {
-        uri: result.uri,
-        sha256: result.sha256,
-        size: result.size,
-        images: result.images,
-      },
-    };
-  },
-);
-
 // Tool: patch_node
 server.registerTool(
   "patch_node",

packages/mcp/src/lib/internal-file-urls.ts

@@ -1,113 +0,0 @@
-// Detection + collection of INTERNAL Docmost file URLs inside a ProseMirror doc.
-//
-// An internal file URL is a relative path served by Docmost's authenticated
-// attachment route (`GET /api/files/:fileId/:fileName`). It is useless to an
-// external consumer (relative + needs a Docmost session), so the stash tool
-// mirrors every such resource into the blob sandbox and rewrites its `src`.
-//
-// The criterion is "internal file URL", NOT the node TYPE: image, drawio,
-// excalidraw, video and file nodes all carry such a `src`, so a type-agnostic
-// walker covers them all. External http(s) srcs (CDNs) are left untouched.
-//
-// Mirrors editor-ext's isInternalFileUrl / normalizeFileUrl (kept as a local
-// dup so the ESM mcp package does not depend on the editor-ext build).
-
-function isInternalFileUrl(url: unknown): boolean {
-  if (typeof url !== "string") return false;
-  const normalized = url.trim();
-  return (
-    normalized.startsWith("/api/files/") || normalized.startsWith("/files/")
-  );
-}
-
-/** Normalize a bare `/files/...` src to the canonical `/api/files/...` form. */
-export function normalizeFileUrl(src: string): string {
-  const trimmed = src.trim();
-  if (trimmed.startsWith("/files/")) return "/api" + trimmed;
-  return trimmed;
-}
-
-/**
- * Resolve a page-content `src` into the safe, `/api`-relative path the stash
- * tool may fetch over the authenticated loopback client — or THROW.
- *
- * SECURITY (SSRF / path-traversal): `src` comes from page content and is fully
- * attacker-controllable. The mirroring fetch runs through the AUTHENTICATED
- * loopback axios client whose baseURL ends in `/api`, so a naive
- * `src.replace(/^\/api/, "")` lets a crafted value like
- * `/api/files/../auth/whoami` collapse (via axios/WHATWG URL `..` resolution)
- * into an ARBITRARY internal GET endpoint, whose authed response would then be
- * stored in the anonymous sandbox (SSRF + data exfiltration). A prefix-only
- * `startsWith("/api/files/")` check does NOT defend against this because the
- * `..` segments are still present in the raw string and resolved later.
- *
- * This function defeats that by resolving the canonical pathname FIRST and only
- * then asserting it still lives under `/api/files/`:
- *  - it rejects any percent-encoded dot/slash (`%2e` / `%2f`): the WHATWG URL
- *    parser collapses LITERAL `../` but does NOT decode `%2f` separators, so a
- *    content-controlled src must never be allowed to smuggle those past the
- *    canonicalization;
- *  - it resolves `new URL(trimmed, "http://internal.invalid").pathname`, which
- *    normalizes `..`/`.` segments (e.g. `/api/files/../auth/whoami` →
- *    `/api/auth/whoami`);
- *  - it then requires the canonical pathname to start with `/api/files/`, so a
- *    traversal that escaped that subtree is rejected.
- *
- * Returns the path RELATIVE to the `/api` base (e.g. `/files/<id>/<name>`),
- * ready to hand to the loopback client. The throw happens BEFORE any network
- * call, so a rejected src is counted as a failed mirror and its original src is
- * kept (the per-image try/catch in stashPage never aborts the whole document).
- */
-export function resolveInternalFilePath(src: string): string {
-  const trimmed = src.trim();
-  // Percent-encoded dot/slash must never reach the URL canonicalizer: the
-  // WHATWG parser does NOT decode `%2f` into a path separator, so an encoded
-  // `..%2fauth` would survive canonicalization and still escape /api/files/.
-  if (/%2e|%2f/i.test(trimmed)) {
-    throw new Error(
-      `Refusing internal file src with percent-encoded path segment: "${src}"`,
-    );
-  }
-  let pathname: string;
-  try {
-    // The base host is irrelevant (never contacted); it only lets the parser
-    // resolve a relative `src` and normalize `..`/`.` segments.
-    pathname = new URL(trimmed, "http://internal.invalid").pathname;
-  } catch {
-    throw new Error(`Invalid internal file src: "${src}"`);
-  }
-  if (!pathname.startsWith("/api/files/")) {
-    throw new Error(
-      `Refusing internal file src that escapes /api/files/: "${src}"`,
-    );
-  }
-  // Strip the `/api` base prefix; the loopback client's baseURL already ends
-  // in `/api`, so it expects the path relative to that (e.g. /files/<id>/<f>).
-  return pathname.replace(/^\/api/, "");
-}
-
-/**
- * Recursively collect every node whose `attrs.src` is an internal file URL.
- * Returns references to the live nodes (so the caller can rewrite `attrs.src`
- * in place on its clone). Descends `content` arrays, covering callouts, tables,
- * details and any other nested container.
- */
-export function collectInternalFileNodes(doc: unknown): any[] {
-  const out: any[] = [];
-  const visit = (node: any): void => {
-    if (!node) return;
-    if (Array.isArray(node)) {
-      for (const child of node) visit(child);
-      return;
-    }
-    if (typeof node !== "object") return;
-    if (node.attrs && isInternalFileUrl(node.attrs.src)) {
-      out.push(node);
-    }
-    if (Array.isArray(node.content)) {
-      for (const child of node.content) visit(child);
-    }
-  };
-  visit(doc);
-  return out;
-}

packages/mcp/src/tool-specs.ts

@@ -266,29 +266,4 @@ export const SHARED_TOOL_SPECS = {
         .describe('List of find/replace operations, applied in order'),
     }),
   },
-
-  // --- hand a large page to an external consumer without bloating context ---
-  stashPage: {
-    mcpName: 'stash_page',
-    inAppKey: 'stashPage',
-    description:
-      'Serialize a whole page (the full ProseMirror JSON, as get_page_json ' +
-      'returns) into an ephemeral in-memory blob and return ONLY a short ' +
-      'anonymous URL to it — the body NEVER enters the model context, so this ' +
-      'is the way to hand a large page (or its images) to an external consumer ' +
-      'without truncation. Every internal file/image attachment is mirrored ' +
-      'into the same sandbox and its src rewritten to a sandbox URL, so the ' +
-      'consumer can fetch the images anonymously too; external http(s) images ' +
-      'are left untouched. Returns { uri, size, sha256, images:{mirrored, ' +
-      'failed} }. Integrity: the blob is served with ETag = its sha256, so a ' +
-      'truncated/corrupted fetch is detectable. Blobs are RAM-only: they expire ' +
-      'after a short TTL (~1h) and are cleared on restart — consume the URL ' +
-      'within the TTL and one uptime, or re-stash. A blob is bound to the ' +
-      'server instance that created it: in a multi-replica deployment without ' +
-      'sticky sessions a blob stored on one instance is not retrievable via the ' +
-      'sandbox URL on another (it 404s like an expired one).',
-    buildShape: (z) => ({
-      pageId: z.string().min(1),
-    }),
-  },
 } satisfies Record<string, SharedToolSpec>;

packages/mcp/test/mock/stash-page-mcp-result.test.mjs

@@ -1,155 +0,0 @@
-// Server round-trip test for the stash_page MCP tool result shape. The in-app
-// path returns the full documented `{ uri, size, sha256, images }` object, but
-// the MCP transport must deliver the SAME shape: a resource_link (primary
-// payload) PLUS a `structuredContent` mirror carrying sha256 + image counts.
-// This connects a real MCP Client to the server over a linked in-memory
-// transport pair and asserts both halves of the result, end to end.
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import http from "node:http";
-import { createHash } from "node:crypto";
-import { createDocmostMcpServer } from "../../build/index.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-
-function readBody(req) {
-  return new Promise((resolve) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => resolve(raw));
-  });
-}
-
-function startServer(handler) {
-  return new Promise((resolve) => {
-    const server = http.createServer(handler);
-    server.listen(0, "127.0.0.1", () => {
-      const { port } = server.address();
-      resolve({ server, baseURL: `http://127.0.0.1:${port}/api` });
-    });
-  });
-}
-
-const openServers = [];
-async function spawn(handler) {
-  const { server, baseURL } = await startServer(handler);
-  openServers.push(server);
-  return baseURL;
-}
-after(async () => {
-  await Promise.all(openServers.map((s) => new Promise((r) => s.close(r))));
-});
-
-// Minimal in-memory sandbox sink: store the blob and return a uri + sha256 +
-// size, with has/evict probes the client's reconciliation may call.
-function makeSandbox() {
-  const live = new Map();
-  const idOf = (uri) => uri.substring(uri.lastIndexOf("/") + 1);
-  let n = 0;
-  return {
-    put(buf) {
-      const sha256 = createHash("sha256").update(buf).digest("hex");
-      const id = `id-${n++}`;
-      live.set(id, buf.length);
-      return { uri: `https://sb.test/api/sb/${id}`, sha256, size: buf.length };
-    },
-    has(uri) {
-      return live.has(idOf(uri));
-    },
-    evict(uri) {
-      live.delete(idOf(uri));
-    },
-  };
-}
-
-const IMAGE_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
-
-// One internal image (so images.mirrored === 1) inside a normal page doc.
-function pageDoc() {
-  return {
-    type: "doc",
-    content: [
-      {
-        type: "image",
-        attrs: { src: "/api/files/att-1/pic.png", attachmentId: "att-1" },
-      },
-    ],
-  };
-}
-
-// Mock Docmost: login, page info, internal file bytes — same pattern as
-// stash-page.test.mjs.
-async function buildBaseURL() {
-  return spawn(async (req, res) => {
-    await readBody(req);
-    if (req.url === "/api/auth/login") {
-      res.writeHead(200, {
-        "Content-Type": "application/json",
-        "Set-Cookie": "authToken=tok; HttpOnly",
-      });
-      res.end(JSON.stringify({ token: "tok" }));
-      return;
-    }
-    if (req.url === "/api/pages/info") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(
-        JSON.stringify({ data: { id: "page-1", title: "T", content: pageDoc() } }),
-      );
-      return;
-    }
-    if (req.url.startsWith("/api/files/")) {
-      res.writeHead(200, { "Content-Type": "image/png" });
-      res.end(IMAGE_BYTES);
-      return;
-    }
-    res.writeHead(404);
-    res.end();
-  });
-}
-
-test("stash_page MCP tool returns a resource_link AND a structuredContent mirror", async () => {
-  const baseURL = await buildBaseURL();
-  const sandbox = makeSandbox();
-  const server = createDocmostMcpServer({
-    apiUrl: baseURL,
-    email: "u@example.com",
-    password: "pw",
-    sandbox,
-  });
-
-  const client = new Client({ name: "test-client", version: "0.0.0" });
-  const [a, b] = InMemoryTransport.createLinkedPair();
-  await server.connect(b);
-  await client.connect(a);
-
-  try {
-    const res = await client.callTool({
-      name: "stash_page",
-      arguments: { pageId: "page-1" },
-    });
-
-    // Primary payload: a resource_link pointing at the sandbox doc blob.
-    const link = res.content[0];
-    assert.equal(link.type, "resource_link");
-    assert.match(link.uri, /^https:\/\/sb\.test\/api\/sb\//);
-
-    // structuredContent mirrors the full documented shape.
-    const sc = res.structuredContent;
-    assert.equal(typeof sc, "object");
-    assert.equal(sc.uri, link.uri); // same blob as the link
-    assert.match(sc.sha256, /^[0-9a-f]{64}$/); // 64-hex ETag
-    assert.equal(typeof sc.size, "number");
-    assert.deepEqual(sc.images, { mirrored: 1, failed: 0 });
-
-    // Deep-equal the whole structured payload against what the mock implies.
-    assert.deepEqual(sc, {
-      uri: link.uri,
-      sha256: sc.sha256,
-      size: sc.size,
-      images: { mirrored: 1, failed: 0 },
-    });
-  } finally {
-    await client.close();
-    await server.close();
-  }
-});

packages/mcp/test/mock/stash-page.test.mjs

@@ -1,378 +0,0 @@
-// Mock-HTTP test for DocmostClient.stashPage: a local http server stands in for
-// Docmost so the whole flow stays deterministic and offline. Asserts the tool
-// (1) serializes the page into the sandbox and returns ONLY a link (uri + sha256
-// + size), never the body; (2) mirrors INTERNAL image srcs into the sandbox and
-// rewrites them to the sandbox uri; (3) leaves EXTERNAL http(s) srcs untouched;
-// (4) de-duplicates a repeated internal src to a single blob; (5) counts a
-// failed image fetch without aborting the document.
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import http from "node:http";
-import { createHash } from "node:crypto";
-import { DocmostClient } from "../../build/client.js";
-
-function readBody(req) {
-  return new Promise((resolve) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => resolve(raw));
-  });
-}
-
-function startServer(handler) {
-  return new Promise((resolve) => {
-    const server = http.createServer(handler);
-    server.listen(0, "127.0.0.1", () => {
-      const { port } = server.address();
-      resolve({ server, baseURL: `http://127.0.0.1:${port}/api` });
-    });
-  });
-}
-
-const openServers = [];
-async function spawn(handler) {
-  const { server, baseURL } = await startServer(handler);
-  openServers.push(server);
-  return baseURL;
-}
-after(async () => {
-  await Promise.all(openServers.map((s) => new Promise((r) => s.close(r))));
-});
-
-// In-memory sandbox sink mirroring the host binding: store the blob, return a
-// uri + sha256 + size. Records every put so the test can inspect what was
-// stashed (and verify the doc body never leaves via the return value). Models
-// the real store's FIFO eviction + cap + the has/evict probes so B1 (self-
-// eviction reconciliation and doc-put-throw cleanup) is testable. Default
-// maxTotal is effectively unlimited so the happy-path tests behave as before.
-//
-// `throwOnJson` forces the final document put to throw, standing in for "doc
-// exceeds the cap".
-function makeSandbox({ maxTotal = Infinity, throwOnJson = false } = {}) {
-  const puts = [];
-  const evicted = [];
-  // id -> size, in insertion order (Map preserves it) so the oldest is first.
-  const live = new Map();
-  let total = 0;
-  const idOf = (uri) => uri.substring(uri.lastIndexOf("/") + 1);
-  return {
-    puts,
-    evicted,
-    put(buf, mime) {
-      if (throwOnJson && mime === "application/json") {
-        throw new Error("doc blob exceeds the sandbox cap");
-      }
-      const sha256 = createHash("sha256").update(buf).digest("hex");
-      const id = `id-${puts.length}`;
-      puts.push({ buf, mime, sha256, id });
-      live.set(id, buf.length);
-      total += buf.length;
-      // FIFO-evict the oldest live blobs until this put fits under the cap.
-      while (total > maxTotal && live.size > 0) {
-        const oldest = live.keys().next().value;
-        if (oldest === id) break; // never evict the blob we just stored
-        total -= live.get(oldest);
-        live.delete(oldest);
-        evicted.push(oldest);
-      }
-      return { uri: `https://sb.test/api/sb/${id}`, sha256, size: buf.length };
-    },
-    has(uri) {
-      return live.has(idOf(uri));
-    },
-    evict(uri) {
-      const id = idOf(uri);
-      if (live.has(id)) {
-        total -= live.get(id);
-        live.delete(id);
-      }
-      evicted.push(id);
-    },
-  };
-}
-
-const IMAGE_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]); // "PNG" header-ish
-
-function pageDoc() {
-  return {
-    type: "doc",
-    content: [
-      {
-        type: "image",
-        attrs: { src: "/api/files/att-1/pic.png", attachmentId: "att-1", width: 100 },
-      },
-      // Same internal src again -> must dedup to ONE blob, both rewritten.
-      {
-        type: "image",
-        attrs: { src: "/api/files/att-1/pic.png", attachmentId: "att-1", width: 50 },
-      },
-      // External CDN image -> must be left untouched.
-      {
-        type: "image",
-        attrs: { src: "https://cdn.example.com/remote.png" },
-      },
-    ],
-  };
-}
-
-// Build a client wired to a server that logs in, serves the page, and serves the
-// internal file bytes. `fileStatus` lets a test force the file fetch to fail;
-// `doc` overrides the served page; `fileBytes`/`fileHeaders` shape the file
-// response (used by the empty-body / missing-Content-Type branch tests).
-async function buildClient(
-  sandbox,
-  {
-    fileStatus = 200,
-    doc = pageDoc(),
-    fileBytes = IMAGE_BYTES,
-    fileHeaders = { "Content-Type": "image/png" },
-  } = {},
-) {
-  const baseURL = await spawn(async (req, res) => {
-    await readBody(req);
-    if (req.url === "/api/auth/login") {
-      res.writeHead(200, {
-        "Content-Type": "application/json",
-        "Set-Cookie": "authToken=tok; HttpOnly",
-      });
-      res.end(JSON.stringify({ token: "tok" }));
-      return;
-    }
-    if (req.url === "/api/pages/info") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ data: { id: "page-1", title: "T", content: doc } }));
-      return;
-    }
-    if (req.url.startsWith("/api/files/")) {
-      if (fileStatus !== 200) {
-        res.writeHead(fileStatus);
-        res.end();
-        return;
-      }
-      res.writeHead(200, fileHeaders);
-      res.end(fileBytes);
-      return;
-    }
-    res.writeHead(404);
-    res.end();
-  });
-  return new DocmostClient({
-    apiUrl: baseURL,
-    email: "u@example.com",
-    password: "pw",
-    sandbox: {
-      put: (buf, mime) => sandbox.put(buf, mime),
-      has: (uri) => sandbox.has(uri),
-      evict: (uri) => sandbox.evict(uri),
-    },
-  });
-}
-
-// A page with several DISTINCT internal images (each a unique attachment id) so
-// each is its own sandbox blob — needed to exercise FIFO self-eviction.
-function multiImageDoc(n) {
-  return {
-    type: "doc",
-    content: Array.from({ length: n }, (_, i) => ({
-      type: "image",
-      attrs: { src: `/api/files/att-${i}/pic.png`, attachmentId: `att-${i}` },
-    })),
-  };
-}
-
-test("stashPage stores the doc + mirrors/rewrites internal images, returns only a link", async () => {
-  const sandbox = makeSandbox();
-  const client = await buildClient(sandbox);
-
-  const result = await client.stashPage("page-1");
-
-  // Returns ONLY a link shape — never the document body.
-  assert.equal(typeof result.uri, "string");
-  assert.match(result.uri, /^https:\/\/sb\.test\/api\/sb\//);
-  assert.equal(typeof result.sha256, "string");
-  assert.equal(typeof result.size, "number");
-  assert.ok(!("doc" in result) && !("content" in result) && !("body" in result));
-  assert.deepEqual(result.images, { mirrored: 1, failed: 0 });
-
-  // One image blob (dedup) + one doc blob = 2 puts.
-  assert.equal(sandbox.puts.length, 2);
-  const imagePut = sandbox.puts[0];
-  const docPut = sandbox.puts[1];
-  assert.equal(imagePut.mime, "image/png");
-  assert.ok(imagePut.buf.equals(IMAGE_BYTES));
-  assert.equal(docPut.mime, "application/json");
-
-  // The returned uri/sha256 are the DOCUMENT blob's.
-  assert.equal(result.sha256, docPut.sha256);
-
-  // Inspect the stashed document: internal srcs rewritten, external untouched.
-  const stashed = JSON.parse(docPut.buf.toString("utf8"));
-  const imgs = stashed.content.content.filter((n) => n.type === "image");
-  assert.equal(imgs[0].attrs.src, "https://sb.test/api/sb/id-0");
-  assert.equal(imgs[1].attrs.src, "https://sb.test/api/sb/id-0"); // same blob (dedup)
-  assert.equal(imgs[2].attrs.src, "https://cdn.example.com/remote.png"); // external kept
-});
-
-test("stashPage counts a failed image fetch without aborting the document", async () => {
-  const sandbox = makeSandbox();
-  const client = await buildClient(sandbox, { fileStatus: 500 });
-
-  const result = await client.stashPage("page-1");
-
-  assert.deepEqual(result.images, { mirrored: 0, failed: 1 });
-  // Only the doc blob was stored (image fetch failed).
-  assert.equal(sandbox.puts.length, 1);
-  assert.equal(sandbox.puts[0].mime, "application/json");
-
-  // The failed internal src is LEFT as-is so nothing is silently dropped.
-  const stashed = JSON.parse(sandbox.puts[0].buf.toString("utf8"));
-  const imgs = stashed.content.content.filter((n) => n.type === "image");
-  assert.equal(imgs[0].attrs.src, "/api/files/att-1/pic.png");
-});
-
-test("stashPage throws a clear error when no sandbox is configured", async () => {
-  const baseURL = await spawn(async (req, res) => {
-    await readBody(req);
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({}));
-  });
-  const client = new DocmostClient({
-    apiUrl: baseURL,
-    email: "u@example.com",
-    password: "pw",
-  });
-  await assert.rejects(() => client.stashPage("page-1"), /not configured/);
-});
-
-test("stashPage reverts a FIFO-evicted image and counts it as failed (B1)", async () => {
-  // 3 distinct images of S=4000 bytes each; doc JSON is far smaller than one
-  // image. With a cap of 4500: storing img1 evicts img0, storing img2 evicts
-  // img1 — so only img2 survives the loop (img0 + img1 reverted). The doc
-  // (4000 + a few hundred bytes <= 4500) then fits alongside the survivor, so it
-  // does NOT trigger further eviction. The stored doc must therefore reference
-  // exactly one live blob and revert the other two to their internal srcs.
-  const BIG = Buffer.alloc(4000, 0x41);
-  const sandbox = makeSandbox({ maxTotal: 4500 });
-  const client = await buildClient(sandbox, {
-    doc: multiImageDoc(3),
-    fileBytes: BIG,
-  });
-
-  const result = await client.stashPage("page-1");
-
-  // Two images were evicted before the doc was stored -> counted as failed.
-  assert.deepEqual(result.images, { mirrored: 1, failed: 2 });
-
-  // Inspect the stashed doc: no node may point at an evicted (now-dead) blob,
-  // and every reverted node carries its ORIGINAL internal src again.
-  const docPut = sandbox.puts.find((p) => p.mime === "application/json");
-  const stashed = JSON.parse(docPut.buf.toString("utf8"));
-  const imgs = stashed.content.content.filter((n) => n.type === "image");
-  let live = 0;
-  let reverted = 0;
-  for (const img of imgs) {
-    const src = img.attrs.src;
-    if (src.startsWith("https://sb.test/api/sb/")) {
-      assert.ok(sandbox.has(src), `doc references evicted blob ${src}`);
-      live++;
-    } else {
-      // Reverted to the original internal src.
-      assert.match(src, /^\/api\/files\/att-\d+\/pic\.png$/);
-      reverted++;
-    }
-  }
-  assert.equal(live, 1);
-  assert.equal(reverted, 2);
-});
-
-test("stashPage reverts an image evicted by the DOC put itself (after-put reconcile, B1)", async () => {
-  // Both images (1000 bytes each) survive the image phase: total 2000 <= cap
-  // 2500. The doc, however, serializes large (a node with a ~700-byte string
-  // attr), so putting it (newest) tips total over the cap and FIFO-evicts the
-  // OLDEST image (img0) — an eviction caused by the doc put itself, which only
-  // the after-put reconciliation can catch. The loop then reverts img0, drops
-  // the stale doc blob, and re-puts the corrected doc (now total = img1 +
-  // docSize <= cap, so img1 survives).
-  const BIG = Buffer.alloc(1000, 0x41);
-  const sandbox = makeSandbox({ maxTotal: 2500 });
-  const doc = {
-    type: "doc",
-    content: [
-      { type: "image", attrs: { src: "/api/files/att-0/pic.png", attachmentId: "att-0" } },
-      { type: "image", attrs: { src: "/api/files/att-1/pic.png", attachmentId: "att-1" } },
-      // Bulk the doc JSON up so the doc put crosses the cap on its own. Stays in
-      // the doc across reverts, so each re-serialization is similarly large.
-      { type: "paragraph", attrs: { filler: "x".repeat(700) }, content: [] },
-    ],
-  };
-  const client = await buildClient(sandbox, { doc, fileBytes: BIG });
-
-  const result = await client.stashPage("page-1");
-
-  // The doc put evicted exactly one image -> reverted + counted as failed.
-  assert.deepEqual(result.images, { mirrored: 1, failed: 1 });
-
-  // Use the LAST json put: the first (stale) doc referenced the now-dead blob
-  // and was itself evicted; the corrected re-put is the one that stands.
-  const docPut = sandbox.puts.filter((p) => p.mime === "application/json").at(-1);
-  const stashed = JSON.parse(docPut.buf.toString("utf8"));
-  const imgs = stashed.content.content.filter((n) => n.type === "image");
-  let live = 0;
-  let reverted = 0;
-  for (const img of imgs) {
-    const src = img.attrs.src;
-    if (src.startsWith("https://sb.test/api/sb/")) {
-      assert.ok(sandbox.has(src), `final doc references evicted blob ${src}`);
-      live++;
-    } else {
-      assert.match(src, /^\/api\/files\/att-\d+\/pic\.png$/);
-      reverted++;
-    }
-  }
-  assert.equal(live, 1);
-  assert.equal(reverted, 1);
-});
-
-test("stashPage frees image blobs when the doc put throws (B1)", async () => {
-  // Two distinct images mirror fine; the final JSON doc put throws (doc exceeds
-  // cap). stashPage must reject AND evict every image blob it stored this op.
-  const sandbox = makeSandbox({ throwOnJson: true });
-  const client = await buildClient(sandbox, { doc: multiImageDoc(2) });
-
-  await assert.rejects(() => client.stashPage("page-1"));
-
-  // Both image blobs were stored, then evicted on the doc-put failure.
-  const imagePuts = sandbox.puts.filter((p) => p.mime === "image/png");
-  assert.equal(imagePuts.length, 2);
-  for (const p of imagePuts) {
-    assert.ok(sandbox.evicted.includes(p.id), `image ${p.id} was not freed`);
-  }
-});
-
-test("stashPage counts an empty file response as failed (B1/fetchInternalFile)", async () => {
-  const sandbox = makeSandbox();
-  const client = await buildClient(sandbox, {
-    fileBytes: Buffer.alloc(0),
-    fileHeaders: { "Content-Type": "image/png", "Content-Length": "0" },
-  });
-
-  const result = await client.stashPage("page-1");
-
-  // The single internal image (deduped) yielded an empty body -> failed.
-  assert.deepEqual(result.images, { mirrored: 0, failed: 1 });
-  // Only the doc blob was stored.
-  assert.equal(sandbox.puts.filter((p) => p.mime === "image/png").length, 0);
-});
-
-test("stashPage mirrors a file with no Content-Type as octet-stream (fetchInternalFile)", async () => {
-  const sandbox = makeSandbox();
-  // No Content-Type header at all -> fetchInternalFile defaults to octet-stream.
-  const client = await buildClient(sandbox, { fileHeaders: {} });
-
-  const result = await client.stashPage("page-1");
-
-  assert.equal(result.images.mirrored, 1);
-  const imagePut = sandbox.puts.find((p) => p.mime !== "application/json");
-  assert.ok(imagePut, "expected an image put");
-  assert.equal(imagePut.mime, "application/octet-stream");
-});

packages/mcp/test/unit/internal-file-urls.test.mjs

@@ -1,101 +0,0 @@
-// Unit tests for the internal-file URL helpers the stash tool relies on. The
-// critical case is resolveInternalFilePath, whose whole job is to REJECT a
-// content-controlled `src` that tries to escape /api/files/ (SSRF / traversal)
-// before it ever reaches the authenticated loopback client.
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import {
-  resolveInternalFilePath,
-  normalizeFileUrl,
-  collectInternalFileNodes,
-} from "../../build/lib/internal-file-urls.js";
-
-test("resolveInternalFilePath accepts a normal internal src", () => {
-  assert.equal(
-    resolveInternalFilePath("/api/files/att-1/pic.png"),
-    "/files/att-1/pic.png",
-  );
-});
-
-test("resolveInternalFilePath rejects traversal / encoded variants (SSRF guard)", () => {
-  // `..` collapses to /api/auth/whoami -> outside /api/files/ -> rejected.
-  assert.throws(() => resolveInternalFilePath("/api/files/../auth/whoami"));
-  // Escapes the /api base entirely.
-  assert.throws(() => resolveInternalFilePath("/api/files/../../internal"));
-  // Percent-encoded dot -> rejected before canonicalization.
-  assert.throws(() => resolveInternalFilePath("/api/files/%2e%2e/x"));
-  // Percent-encoded slash separator -> rejected before canonicalization.
-  assert.throws(() => resolveInternalFilePath("/api/files/..%2fauth"));
-});
-
-test("resolveInternalFilePath drops a foreign host and keeps only the /api/files/ pathname (SSRF accept-path)", () => {
-  // ACCEPT path: an absolute URL has its host dropped; only the canonical
-  // pathname survives, and it must still start with /api/files/. This is SAFE
-  // because the loopback axios client ignores any host in `src` and uses its own
-  // /api baseURL — so a foreign host like evil.com is never contacted. This is
-  // the SOLE SSRF/traversal guard for content-controlled `src`, so it must be
-  // pinned: a future refactor to a prefix-only check would silently open a
-  // bypass with no failing test.
-  assert.equal(
-    resolveInternalFilePath("http://evil.com/api/files/x/y.png"),
-    "/files/x/y.png",
-  );
-  // Protocol-relative URL: host likewise dropped, pathname kept.
-  assert.equal(
-    resolveInternalFilePath("//evil.com/api/files/x/y.png"),
-    "/files/x/y.png",
-  );
-});
-
-test("resolveInternalFilePath rejects a foreign-host src whose pathname escapes /api/files/", () => {
-  // Even though the host is dropped, the canonical pathname /api/auth/whoami
-  // does NOT start with /api/files/, so it is rejected.
-  assert.throws(() =>
-    resolveInternalFilePath("https://evil.com/api/auth/whoami"),
-  );
-  // The WHATWG URL parser converts backslashes to `/` for http(s), so this
-  // collapses to /api/auth/whoami and escapes the /api/files/ subtree.
-  assert.throws(() => resolveInternalFilePath("/api/files\\..\\auth\\whoami"));
-});
-
-test("resolveInternalFilePath wraps a new URL parse failure in a clear error", () => {
-  // `http://[` has no %2e/%2f so it passes the first guard, then fails the
-  // `new URL(...)` parse — exercising the catch branch that re-throws with a
-  // clear message.
-  assert.throws(
-    () => resolveInternalFilePath("http://["),
-    /Invalid internal file src/,
-  );
-});
-
-test("normalizeFileUrl rewrites the bare /files/ branch and leaves /api/files/ alone", () => {
-  assert.equal(
-    normalizeFileUrl("/files/att-1/pic.png"),
-    "/api/files/att-1/pic.png",
-  );
-  assert.equal(
-    normalizeFileUrl("/api/files/att-1/pic.png"),
-    "/api/files/att-1/pic.png",
-  );
-});
-
-test("collectInternalFileNodes recurses into nested content containers", () => {
-  // The internal image is buried inside a callout's content array, so a
-  // regression on the recursion (e.g. a shallow .filter()) would miss it.
-  const nested = {
-    type: "image",
-    attrs: { src: "/api/files/att-9/deep.png", attachmentId: "att-9" },
-  };
-  const doc = {
-    type: "doc",
-    content: [
-      {
-        type: "callout",
-        content: [{ type: "paragraph", content: [nested] }],
-      },
-    ],
-  };
-  const found = collectInternalFileNodes(doc);
-  assert.equal(found.length, 1);
-  assert.equal(found[0], nested);
-});

pnpm-lock.yaml

@@ -780,9 +780,6 @@ importers:
       ws:
         specifier: 8.20.1
         version: 8.20.1
-      yaml:
-        specifier: ^2.8.3
-        version: 2.8.3
       yauzl:
         specifier: ^3.2.1
         version: 3.2.1