feat(git-sync): двусторонний Docmost↔git синк на унифицированном конвертере (#359)

Схлопнутая дельта feat/git-sync-2 поверх актуального develop (3085ec1b).

Почему squash, а не буквальный rebase: в ветке 113 коммитов, из которых
develop уже впитал ~80 в курированном виде при унификации конвертера
(#326/#293) — но не patch-identical, поэтому они не отваливаются сами; а
коммит, УДАЛЯЮЩИЙ вендоренную копию конвертера, апстримный и в replay-набор
не входит, так что наивный replay заново добавил бы вендоренные копии.
Поэтому корректный итог — «develop + чистая net-дельта ветки», сведённая
3-way мержом (merge-base 5336f06d).

Net-дельта: серверный git-sync модуль (GitSyncModule/orchestrator/HTTP),
движок git-sync (layout/reconcile/pull/push/stabilize + QA), два фикса
round-trip/data-loss конвертера поверх УНИФИЦИРОВАННОГО
@docmost/prosemirror-markdown (вендоренной копии больше нет — git-sync
целиком на унифицированном конвертере, поведение унифицированного принято
за эталон), e2e-скрипты, доки.

Конфликты (4) слиты объединением: main.ts (метрики + GitHttpService),
apps/server/package.json (pretest-суперсет; moduleNameMapper: git-sync→src
и .js-strip оставлены, а bare-specifier @docmost/prosemirror-markdown→src
УБРАН — серверный jest выровнен на develop-подход #345 со сборённым
пакетом), .env.example (метрики + GIT_SYNC блоки), AGENTS.md (строки про
пакеты; устаревшая заметка про «три hand-synced копии схемы» в git-sync
поправлена — схема теперь только в @docmost/prosemirror-markdown).

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

.env.example

@@ -191,24 +191,16 @@ MCP_DOCMOST_PASSWORD=
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
-# ~1 min instead of 15. Note it also cuts a legitimately long but byte-silent
+# ~5 min instead of 15. Note it also cuts a legitimately long but byte-silent
 # single tool call (a slow crawl that emits nothing until done) and an SSE
-# transport idling >1 min BETWEEN tool calls. Default 60000 (1 min).
+# transport idling >5 min BETWEEN tool calls. Default 300000 (5 min).
-# AI_MCP_STREAM_TIMEOUT_MS=60000
+# AI_MCP_STREAM_TIMEOUT_MS=300000
 
 # Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
 # transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
 # but never returns a result — which the silence timeout above never breaks.
-# Default 120000 (2 min).
+# Default 900000 (15 min).
-# AI_MCP_CALL_TIMEOUT_MS=120000
+# AI_MCP_CALL_TIMEOUT_MS=900000
-
-# Max JSON/urlencoded request body size (bytes). Fastify's 1 MiB default is too
-# small for a long AI-chat research turn: the client resends the FULL message
-# history (every tool call + search result) on each turn, so a deep conversation's
-# POST to /api/ai-chat/stream can be several MB and would otherwise be rejected
-# with FST_ERR_CTP_BODY_TOO_LARGE (413). Does NOT affect multipart file uploads
-# (see FILE_UPLOAD_SIZE_LIMIT). Default 26214400 (25 MiB).
-# HTTP_JSON_BODY_LIMIT=26214400
 
 # Deferred tool loading for the in-app AI chat (#332). Default ON: the agent sees
 # a compact <tool_catalog> and only CORE tools + a loadTools meta-tool are active
@@ -230,18 +222,6 @@ MCP_DOCMOST_PASSWORD=
 # 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.
-#
-# Resumable run streams (#184 phase 1.5, #381). With the flag ON, an active
-# durable run tees its SSE frames into an in-memory registry, and a
-# reloaded/second tab attaches via GET /ai-chat/runs/:chatId/stream to follow the
-# run LIVE (replay of the buffered frames + the live tail). With the flag OFF
-# (default) the registry is never populated and attach always answers 204, so a
-# reopened tab of an active run silently falls back to degraded 2.5s history
-# polling — every wire path stays byte-for-byte identical to a build without the
-# feature. Staged-rollout switch: only meaningful when autonomousRuns (above) is
-# enabled for a workspace, and the same single-instance constraint applies (the
-# registry is process-local).
-# AI_CHAT_RESUMABLE_STREAM=false
 
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
@@ -300,3 +280,44 @@ MCP_DOCMOST_PASSWORD=
 #    infra prunes rows >90d via a maintenance container). When off, the endpoint
 #    does not exist and the client installs no observers.
 # CLIENT_TELEMETRY_ENABLED=false
+# --- GIT-SYNC (native two-way Docmost <-> git Markdown sync) ---
+# Master switch. Off by default. When 'true', GIT_SYNC_SERVICE_USER_ID below is
+# REQUIRED (the service account that git-originated create/move/rename/delete are
+# attributed to) — the server refuses to boot with sync enabled and no user id.
+# GIT_SYNC_ENABLED=false
+#
+# Serve the per-space vaults over smart-HTTP (the /git host). Defaults to
+# GIT_SYNC_ENABLED when unset.
+# GIT_SYNC_HTTP_ENABLED=false
+#
+# REQUIRED when GIT_SYNC_ENABLED=true: id of the user that git-originated page
+# operations (create / move / rename / delete) are attributed to.
+# GIT_SYNC_SERVICE_USER_ID=
+#
+# Where the per-space working vaults live (non-bare repos; the engine needs a
+# working tree).
+# Defaults to "<DATA_DIR or ./data>/git-sync".
+# GIT_SYNC_DATA_DIR=
+#
+# SCAFFOLDING for the DEFERRED remote-push feature (SPEC §7) — NOT yet
+# implemented and currently INERT. The vendored sync engine does not consume
+# this value anywhere (git push to a remote is deferred), so setting it has NO
+# effect today: vaults remain local-only regardless. It is validated and carried
+# only so the wiring is ready for when remote push lands. The intended future
+# shape is a per-space URL template where the literal "{spaceId}" is substituted
+# per space (e.g. git@host:vault-{spaceId}.git).
+# GIT_SYNC_REMOTE_TEMPLATE=
+#
+# Poll-safety interval in ms — the cadence of the background reconcile cycle
+# (default: 15000).
+# GIT_SYNC_POLL_INTERVAL_MS=15000
+#
+# Debounce window in ms for collapsing bursts of page edits into one sync cycle
+# (default: 2000).
+# GIT_SYNC_DEBOUNCE_MS=2000
+#
+# Watchdog timeout in ms for the spawned `git http-backend` process serving a
+# git smart-HTTP push (default: 120000). A stalled/hung receive-pack is killed
+# after this deadline so it cannot hold the per-space lock forever.
+# GIT_SYNC_BACKEND_TIMEOUT_MS=120000
+#

.github/workflows/nightly-property.yml

@@ -1,224 +0,0 @@
-name: Nightly property fuzz
-
-# The daily heavy property run for the ProseMirror<->Markdown converter
-# (packages/prosemirror-markdown). The PR/CI test run keeps NUM_RUNS modest to
-# stay under budget; this cron cranks up total coverage with random seeds to hunt
-# for deeper round-trip counterexamples than a fixed-seed PR run can reach.
-#
-# WHY SHARDING: a single mega-run (~10000 fast-check runs) OOMs the vitest worker
-# (empirically ~1625 runs -> "JS heap out of memory", ~2GB) because heap
-# accumulates across the whole property run in one process. Instead this job runs
-# SHARDS fresh vitest processes, each a MODERATE per-shard count with a DISTINCT
-# derived seed, so total coverage ~= SHARDS x PER_SHARD_NUM_RUNS across processes
-# that never accumulate heap. On the first failing shard we stop and keep that
-# shard's output for triage.
-#
-# Counterexample -> fixture workflow: when a shard fails, fast-check prints the
-# SHRUNK minimal counterexample plus the reproducing seed. This job files a Gitea
-# issue containing that seed + counterexample ONLY when the output actually holds
-# a fast-check counterexample; an infra failure (OOM/tsc/install, no
-# counterexample) is filed under a DISTINCT title so it can never poison the
-# counterexample dedup. A human then commits the shrunk doc as a PERMANENT fixture
-# under packages/prosemirror-markdown/test/fixtures/counterexamples/ with a case in
-# counterexamples.test.ts, and FIXES the converter (never weakens a property to
-# hide the bug). See packages/prosemirror-markdown/README.md.
-
-on:
-  schedule:
-    # 03:00 UTC daily.
-    - cron: '0 3 * * *'
-  workflow_dispatch:
-    inputs:
-      num_runs:
-        description: 'fast-check runs PER SHARD (8 shards run in sequence)'
-        required: false
-        default: '600'
-      seed:
-        description: 'base fast-check seed (empty = random); shard i uses base+i'
-        required: false
-        default: ''
-
-permissions:
-  contents: read
-  issues: write
-
-jobs:
-  property-fuzz:
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      # No build step: the generative suite imports the converter from src/
-      # directly (e.g. `from '../../src/lib/markdown-converter.js'`), so it runs
-      # against source without the package's build/. Skipping the build also
-      # keeps a tsc build error from masquerading as a property-test failure and
-      # filing a bogus counterexample issue.
-      - name: Resolve base seed and per-shard run count
-        id: params
-        # Dispatch inputs are read via env (NOT interpolated into the shell body)
-        # to avoid script injection through a crafted input value.
-        env:
-          SEED_INPUT: ${{ inputs.seed }}
-          NUM_RUNS_INPUT: ${{ inputs.num_runs }}
-        run: |
-          set -euo pipefail
-          SEED="${SEED_INPUT:-}"
-          # Empty seed (cron, or a dispatch that left it blank) -> random. Combine
-          # two RANDOMs so the seed spans more than RANDOM's 0..32767 range.
-          [ -z "$SEED" ] && SEED=$(( (RANDOM << 15) | RANDOM ))
-          NUM_RUNS="${NUM_RUNS_INPUT:-}"
-          [ -z "$NUM_RUNS" ] && NUM_RUNS=600
-          echo "seed=$SEED" >> "$GITHUB_OUTPUT"
-          echo "num_runs=$NUM_RUNS" >> "$GITHUB_OUTPUT"
-          echo "Sharded property fuzz: BASE_SEED=$SEED PER_SHARD_NUM_RUNS=$NUM_RUNS SHARDS=8"
-
-      - name: Run generative property suite (sharded)
-        id: fuzz
-        env:
-          BASE_SEED: ${{ steps.params.outputs.seed }}
-          PER_SHARD_NUM_RUNS: ${{ steps.params.outputs.num_runs }}
-          SHARDS: '8'
-        run: |
-          set -uo pipefail
-          # Give each fresh process headroom, but rely on SHARDING (not a big heap)
-          # to avoid OOM: a moderate per-shard count in a process that starts clean.
-          export NODE_OPTIONS=--max-old-space-size=4096
-          : > property-output.txt
-          FAILED=0
-          FAIL_SEED=""
-          i=0
-          while [ "$i" -lt "$SHARDS" ]; do
-            SHARD_SEED=$(( BASE_SEED + i ))
-            echo "=== shard $((i + 1))/$SHARDS: PROPERTY_SEED=$SHARD_SEED PROPERTY_NUM_RUNS=$PER_SHARD_NUM_RUNS ==="
-            # tee OVERWRITES property-output.txt each shard; since we break on the
-            # first failure, the file ends up holding exactly the failing shard's
-            # output (which carries the shrunk counterexample + reproducing seed).
-            if PROPERTY_SEED="$SHARD_SEED" PROPERTY_NUM_RUNS="$PER_SHARD_NUM_RUNS" \
-                pnpm --filter @docmost/prosemirror-markdown exec \
-                  vitest run test/generative/ 2>&1 | tee property-output.txt; then
-              echo "shard $((i + 1)) passed"
-            else
-              echo "shard $((i + 1)) FAILED (seed=$SHARD_SEED) — stopping; keeping its output"
-              FAILED=1
-              FAIL_SEED="$SHARD_SEED"
-              break
-            fi
-            i=$(( i + 1 ))
-          done
-          echo "failed=$FAILED" >> "$GITHUB_OUTPUT"
-          echo "fail_seed=$FAIL_SEED" >> "$GITHUB_OUTPUT"
-          exit "$FAILED"
-
-      # A GENUINE counterexample: fast-check printed a shrunk minimal case and its
-      # reproducing seed into property-output.txt. File a dedup-guarded issue whose
-      # title prefix is UNIQUE to counterexamples, so an infra failure (handled by
-      # the next step under a different title) can never poison this dedup.
-      - name: File counterexample issue
-        # always() is REQUIRED: the fuzz step exits nonzero on a failing shard,
-        # so a bare `if:` (implicitly success() && ...) would skip this step
-        # exactly when it must run. always() lets it run on the failure path.
-        if: always() && steps.fuzz.outputs.failed == '1'
-        env:
-          FAIL_SEED: ${{ steps.fuzz.outputs.fail_seed }}
-          NUM_RUNS: ${{ steps.params.outputs.num_runs }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TITLE_PREFIX: 'Nightly property counterexample'
-        run: |
-          set -uo pipefail
-          # Discriminate counterexample vs infra failure by the fast-check
-          # signature. No signature -> leave it to the infra-failure step.
-          if ! grep -Eq 'Property failed after|Counterexample' property-output.txt; then
-            echo "No fast-check counterexample signature — infra failure, handled by the next step."
-            exit 0
-          fi
-          TITLE="${TITLE_PREFIX} (seed=${FAIL_SEED})"
-
-          # Best-effort dedup: skip if an open issue with the counterexample title
-          # prefix already exists. A failure of this check must NOT block creation.
-          EXISTING=""
-          if EXISTING=$(curl -sS \
-              -H "Authorization: token ${GITHUB_TOKEN}" \
-              "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues?state=open&limit=100"); then
-            if printf '%s' "$EXISTING" \
-                | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const p=process.env.TITLE_PREFIX;process.exit(a.some(i=>typeof i.title==="string"&&i.title.startsWith(p))?0:1)})'; then
-              echo "An open '${TITLE_PREFIX}' issue already exists — skipping creation."
-              exit 0
-            fi
-          fi
-
-          # Build the JSON body with the test output SAFELY escaped (never hand-
-          # interpolate the counterexample into JSON).
-          BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed with a fast-check counterexample.\n\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nReproduce locally:\n\n```\nPROPERTY_SEED=%s PROPERTY_NUM_RUNS=%s pnpm --filter @docmost/prosemirror-markdown exec vitest run test/generative/\n```\n\nfast-check shrinks the failure to a minimal counterexample. Commit it as a permanent fixture under `packages/prosemirror-markdown/test/fixtures/counterexamples/` + a case in `counterexamples.test.ts`, then FIX the converter (do not weaken a property). See `packages/prosemirror-markdown/README.md`.\n\nTail of the test output (contains the shrunk counterexample):\n\n```\n%s\n```\n' \
-            "$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$FAIL_SEED" "$NUM_RUNS" "$(tail -n 120 property-output.txt)")
-
-          jq -n --arg title "$TITLE" --arg body "$BODY_TEXT" \
-            '{title: $title, body: $body}' > payload.json
-
-          curl -sS -X POST \
-            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues" \
-            -H "Authorization: token ${GITHUB_TOKEN}" \
-            -H 'Content-Type: application/json' \
-            -d @payload.json
-
-      # An INFRA failure (OOM, tsc, install) has NO counterexample signature. File
-      # it under a DISTINCT title so it is visible but keeps the counterexample
-      # dedup (above) uncontaminated — a real counterexample can still file even
-      # while an infra issue is open.
-      - name: File infra failure issue
-        # always() is REQUIRED: the fuzz step exits nonzero on a failing shard,
-        # so a bare `if:` (implicitly success() && ...) would skip this step
-        # exactly when it must run. always() lets it run on the failure path.
-        if: always() && steps.fuzz.outputs.failed == '1'
-        env:
-          FAIL_SEED: ${{ steps.fuzz.outputs.fail_seed }}
-          NUM_RUNS: ${{ steps.params.outputs.num_runs }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TITLE_PREFIX: 'Nightly property run infra failure'
-        run: |
-          set -uo pipefail
-          # Only file when there is NO counterexample signature (else the
-          # counterexample step owns it).
-          if grep -Eq 'Property failed after|Counterexample' property-output.txt; then
-            echo "Counterexample present — owned by the counterexample step."
-            exit 0
-          fi
-          TITLE="${TITLE_PREFIX} (seed=${FAIL_SEED})"
-
-          EXISTING=""
-          if EXISTING=$(curl -sS \
-              -H "Authorization: token ${GITHUB_TOKEN}" \
-              "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues?state=open&limit=100"); then
-            if printf '%s' "$EXISTING" \
-                | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const p=process.env.TITLE_PREFIX;process.exit(a.some(i=>typeof i.title==="string"&&i.title.startsWith(p))?0:1)})'; then
-              echo "An open '${TITLE_PREFIX}' issue already exists — skipping creation."
-              exit 0
-            fi
-          fi
-
-          BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed WITHOUT a fast-check counterexample (infra failure: OOM / build / install). This is NOT a converter round-trip bug.\n\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nInvestigate the run log (memory, dependency install, or a tsc/import error). The nightly counterexample dedup is intentionally separate from this issue.\n\nTail of the test output:\n\n```\n%s\n```\n' \
-            "$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$(tail -n 120 property-output.txt)")
-
-          jq -n --arg title "$TITLE" --arg body "$BODY_TEXT" \
-            '{title: $title, body: $body}' > payload.json
-
-          curl -sS -X POST \
-            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues" \
-            -H "Authorization: token ${GITHUB_TOKEN}" \
-            -H 'Content-Type: application/json' \
-            -d @payload.json

.github/workflows/test.yml

@@ -119,10 +119,18 @@ jobs:
       # build/ is gitignored, and plain `pnpm -r test` does NOT honour nx
       # `dependsOn: ^build`, so its consumers (mcp `pretest: tsc`, git-sync vitest
       # typecheck) fail with TS2307 Cannot find module '@docmost/prosemirror-markdown'
-      # unless it is built first. Build it before the recursive test run.
+      # unless it is built first. Build it BEFORE git-sync/mcp (which import it).
       - name: Build prosemirror-markdown
         run: pnpm --filter @docmost/prosemirror-markdown build
 
+      # git-sync and mcp are no longer committed in built form (build/ is
+      # gitignored), so CI must compile them: the server resolves both via their
+      # built build/index.js (git-sync's runtime consumer lands on this branch,
+      # #119). The server pretest also builds them, but building here keeps it
+      # explicit and independent of pnpm lifecycle ordering.
+      - name: Build git-sync and mcp
+        run: pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build
+
       - name: Run unit tests
         run: pnpm -r test
 

.gitignore

@@ -4,19 +4,16 @@
 data
 # compiled output
 /dist
-node_modules
+/node_modules
+# workspace package node_modules (pnpm symlinks — never commit; they bake
+# machine-local store paths).
+packages/*/node_modules/
 
-# git-sync compiled output (built in CI/Docker via `pnpm build`, never committed,
+# Compiled package output: build/ is gitignored for every workspace package
-# so src/ and prod can never silently diverge).
+# (built in CI/Docker via `pnpm build`, never committed, so src/ and prod can
+# never silently diverge). Private packages are rebuilt at deploy.
 packages/git-sync/build/
-
-# prosemirror-markdown compiled output (built in CI/Docker via `pnpm build`,
-# never committed, so src/ and prod can never silently diverge).
 packages/prosemirror-markdown/build/
-
-# mcp compiled output (built in CI/Docker via `pnpm build`, never committed, so
-# src/ and prod can never silently diverge). Matches the git-sync/prosemirror-
-# markdown convention; the package is private and rebuilt at deploy.
 packages/mcp/build/
 
 # Logs

.vscode/tasks.json

@@ -3,9 +3,9 @@
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "git sync (pull gitea -> push github + gitea)",
+      "label": "git push (github + gitea)",
       "type": "shell",
-      "command": "git fetch gitea && git merge --no-edit gitea/develop && git push github develop && git push gitea develop",
+      "command": "git push github develop && git push gitea develop",
       "options": { "cwd": "${workspaceFolder}" },
       "presentation": { "reveal": "never", "focus": false, "panel": "shared", "showReuseMessage": false, "close": true },
       "problemMatcher": []

AGENTS.md

@@ -193,7 +193,7 @@ authenticated in-process, so no `tea`/`curl` and no keychain lookup are needed.
 
 ## Monorepo layout
 
-pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
+pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five workspace packages:
 
 | Path | Name | Stack | Role |
 | --- | --- | --- | --- |
@@ -202,6 +202,7 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
 | `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
 | `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |
+| `packages/git-sync` | `@docmost/git-sync` | Tiptap/ProseMirror, Yjs, git | The two-way Docmost↔git Markdown sync **engine** (vault layout, git orchestration, reconcile). Consumes the ProseMirror↔Markdown converter from `@docmost/prosemirror-markdown` (#293) — no longer carries its own converter copy. Bundled into the server (loaded over the ESM bridge), built in CI and the Dockerfile. |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -290,8 +291,10 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 
 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.
 
+Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify routes that bypass the Nest pipeline (so neither `DomainMiddleware` nor `ThrottlerGuard` runs for them — each resolves the workspace and throttles itself): `/mcp` (the embedded MCP server, see below) and `/git/<spaceId>.git/...` (the git-sync smart-HTTP host, see below). Both share `mcp-auth.helpers.ts` (HTTP-Basic parsing, `FailedLoginLimiter`, `clientIp`) and the common `resolveRequestWorkspace` helper.
+
 ### 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`.
+`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`, `git-sync`) 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`.
 
 **EE removal artifact:** `app.module.ts` still contains a `try/require('./ee/ee.module')` stub. That path no longer exists, so the require fails and is swallowed (it only hard-exits when `CLOUD === 'true'`). Treat EE as gone — do not add code that depends on it.
 
@@ -308,10 +311,16 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
    - `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.
 
+### Git-sync (native two-way Docmost ↔ git Markdown sync)
+`integrations/git-sync/` (`GitSyncModule`) + the vendored pure engine in `packages/git-sync`. Off by default; gated by the `GIT_SYNC_ENABLED` master switch (and `GIT_SYNC_SERVICE_USER_ID`, the account git-originated writes are attributed to). Per-space opt-in via `space.settings.gitSync.enabled`, with a second per-space toggle `space.settings.gitSync.autoMergeConflicts` that changes PUSH behavior for a still-conflicted page (one carrying `<<<<<<<`/`>>>>>>>` markers): **off (the safe default)** records a per-page failure and holds the refs so the user resolves the git conflict first (markers never reach Docmost); **on** strips the marker lines and pushes both sides' content. Each enabled space gets an on-disk working "vault" repo; the `GitSyncOrchestrator` runs a debounced + poll-backstop reconcile cycle (PULL Docmost→vault, PUSH vault→Docmost) under a per-space Redis leader lock + in-process mutex (`SpaceLockService`). Writes go through the collaboration layer (so concurrent human edits aren't clobbered) and are stamped `lastUpdatedSource = 'git-sync'` for the listener loop-guard. The in-process `setInterval` orchestration + best-effort lock (no fencing tokens) is a known multi-replica limitation — BullMQ + fencing is the documented future direction.
+
+- **`/git` smart-HTTP host** (`integrations/git-sync/http/`, gated additionally by `GIT_SYNC_HTTP_ENABLED`, which defaults to `GIT_SYNC_ENABLED`): a raw root-mounted Fastify route `/git/<spaceId>.git/...` (registered in `main.ts`, NOT under `/api`) that bridges `git clone`/`fetch`/`push` to `git http-backend`. It authenticates HTTP Basic against `AuthService` (throttled by a `FailedLoginLimiter` mirroring the `/mcp` path), authorizes via `SpaceAbilityFactory` (read = fetch, Manage = push), and gates existence so a non-member gets the SAME 404 as a missing/sync-disabled space (never 403 — that would leak space existence). A push runs the receive-pack under the space lock, then a reconcile cycle.
+- **Schema mirror:** git-sync no longer carries its own schema copy — it consumes the Docmost schema mirror from `@docmost/prosemirror-markdown` (#293), which is itself mirrored from the canonical `editor-ext` and guarded by the serializer-contract test. There is no longer a per-package hand-synced copy to keep in lockstep.
+
 ### 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:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
-- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
 

CHANGELOG.md

@@ -12,6 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Native two-way Docmost ↔ git Markdown sync.** Opt-in per space (Space
+  settings → a git-sync toggle, plus an `autoMergeConflicts` toggle that controls
+  whether a still-conflicted page is held back or pushed with its conflict
+  markers stripped): each enabled space is mirrored to an on-disk git "vault" of
+  Markdown files and reconciled in both directions (Docmost → vault and vault →
+  Docmost) on a debounced + poll-backstop cycle, under a per-space lock, writing
+  through the collaboration layer so concurrent human edits aren't clobbered.
+  Git-originated changes are attributed to a configurable service account and
+  carry a "git-sync" provenance badge in page history. Optionally exposes a `/git`
+  smart-HTTP host so you can `git clone`/`fetch`/`push` a space directly (HTTP
+  Basic auth, space-permission authorized). Off by default and configured via the
+  `GIT_SYNC_*` environment variables, including `GIT_SYNC_ENABLED`,
+  `GIT_SYNC_SERVICE_USER_ID`, and `GIT_SYNC_HTTP_ENABLED` (see `.env.example`).
+  (#119)
 - **Place several images side by side in a row.** A new "Inline (side by
   side)" alignment mode in the image bubble menu renders consecutive inline
   images as a row that wraps onto the next line on narrow screens. The row is

Dockerfile

@@ -24,8 +24,9 @@ RUN pnpm build
 
 FROM base AS installer
 
+# git: required by the git-sync VaultGit (shells out to git)
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends curl bash \
+  && apt-get install -y --no-install-recommends curl bash git \
   && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -45,14 +46,20 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
 COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
 COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
 COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
-# mcp now depends on @docmost/prosemirror-markdown (workspace:*) and eager-imports
+# @docmost/prosemirror-markdown is the shared converter (#293/#326). Both mcp and
-# it at runtime (the in-app ai-chat DocmostClient loads build/index.js -> lib/
+# git-sync depend on it (workspace:*) and load it at runtime, so the built package +
-# markdown-converter.js). Ship the built package + its manifest, or the prod
+# its manifest must be shipped or the prod install resolves a broken workspace
-# install resolves a broken workspace symlink and every ai-chat tool dies with
+# symlink and every consumer dies with ERR_MODULE_NOT_FOUND.
-# ERR_MODULE_NOT_FOUND (#293/#326 step 5). (git-sync has no runtime consumer yet;
-# revisit at step 6 when #119 lands.)
 COPY --from=builder /app/packages/prosemirror-markdown/build /app/packages/prosemirror-markdown/build
 COPY --from=builder /app/packages/prosemirror-markdown/package.json /app/packages/prosemirror-markdown/package.json
+# git-sync: the server loads @docmost/git-sync at runtime via the loader
+# (git-sync.loader.ts), which deliberately does NOT `require()` it — the package is
+# ESM-only, so the loader uses `require.resolve` + a dynamic `import()`. Without
+# these copied build artifacts that resolve/import fails and the server crashes on
+# first use. Built fresh by the builder's `pnpm build` (nx builds the package's tsc
+# `build` target). This branch (#119) is where git-sync gains its runtime consumer.
+COPY --from=builder /app/packages/git-sync/build /app/packages/git-sync/build
+COPY --from=builder /app/packages/git-sync/package.json /app/packages/git-sync/package.json
 
 # Copy root package files
 COPY --from=builder /app/package.json /app/package.json

README.md

@@ -125,32 +125,6 @@ Gitmost follows the upstream Docmost setup. See the Docmost
 [documentation](https://docmost.com/docs) for self-hosting and development instructions; replace the
 `docmost/docmost` image with `ghcr.io/vvzvlad/gitmost` where applicable.
 
-### Reverse proxy: SSE streaming paths
-
-The AI agent streams its answers over Server-Sent Events. These endpoints produce a
-long-lived `text/event-stream` response and **must bypass response buffering AND response
-compression** at every proxy in front of the app:
-
-- `POST /api/ai-chat/stream` — the live agent turn stream
-- `GET /api/ai-chat/runs/<chatId>/stream` — attach/resume of a detached agent run
-  (`AI_CHAT_RESUMABLE_STREAM`)
-- `POST /api/shares/ai/stream` — the anonymous public-share assistant
-
-A buffering or compressing proxy does not break these with an error — it silently ruins them:
-the request hangs in `pending`, tokens stop streaming and arrive in one burst when the turn
-ends, or a reloaded tab falls back to coarse polling. The tell in DevTools is a
-`Content-Encoding: gzip/zstd` response header on a `text/event-stream` response.
-
-The server already sends `X-Accel-Buffering: no` (honored by nginx unless ignored), but
-compression middleware is applied by proxy configuration, not headers:
-
-- **nginx** — `proxy_buffering off; proxy_cache off; gzip off;` for these locations, e.g.
-  `location ~ ^/api/(ai-chat/(stream$|runs/.+/stream$)|shares/ai/) { ... }`
-- **Traefik** — route these paths through a dedicated router **without** the `compress`
-  middleware (a `compress` middleware buffers SSE frames until the response closes), e.g.
-  ``PathPrefix(`/api/ai-chat/stream`) || PathPrefix(`/api/ai-chat/runs/`)``. Belt-and-braces:
-  `traefik.http.middlewares.<name>.compress.excludedcontenttypes: text/event-stream`.
-
 ## Migration from Docmost
 
 Gitmost's database schema is a **strict superset** of Docmost's. Every Gitmost-specific migration

README.ru.md

@@ -126,32 +126,6 @@ Gitmost повторяет процесс установки upstream-Docmost.
 смотрите в [документации](https://docmost.com/docs) Docmost; где это применимо, заменяйте образ
 `docmost/docmost` на `ghcr.io/vvzvlad/gitmost`.
 
-### Reverse proxy: SSE-стриминговые пути
-
-AI-агент стримит ответы через Server-Sent Events. Эти эндпоинты отдают долгоживущий
-`text/event-stream`-ответ и **обязаны обходить буферизацию И сжатие ответов** на каждом
-прокси перед приложением:
-
-- `POST /api/ai-chat/stream` — живой стрим хода агента
-- `GET /api/ai-chat/runs/<chatId>/stream` — подключение/резюм detached-рана
-  (`AI_CHAT_RESUMABLE_STREAM`)
-- `POST /api/shares/ai/stream` — анонимный ассистент публичных шар
-
-Буферизующий или сжимающий прокси не ломает эти пути с ошибкой — он тихо их портит:
-запрос висит в `pending`, токены не стримятся и вываливаются одним куском в конце хода,
-а перезагруженная вкладка падает в грубый поллинг. Диагностический признак в DevTools —
-заголовок `Content-Encoding: gzip/zstd` на ответе с `text/event-stream`.
-
-Сервер уже шлёт `X-Accel-Buffering: no` (nginx учитывает его по умолчанию), но
-compression-мидлвари управляются конфигом прокси, а не заголовками:
-
-- **nginx** — `proxy_buffering off; proxy_cache off; gzip off;` для этих location,
-  например `location ~ ^/api/(ai-chat/(stream$|runs/.+/stream$)|shares/ai/) { ... }`
-- **Traefik** — вести эти пути через отдельный роутер **без** `compress`-мидлвари
-  (compress буферизует SSE-кадры до закрытия ответа), например
-  ``PathPrefix(`/api/ai-chat/stream`) || PathPrefix(`/api/ai-chat/runs/`)``. Для надёжности:
-  `traefik.http.middlewares.<name>.compress.excludedcontenttypes: text/event-stream`.
-
 ## Миграция с Docmost
 
 Схема БД Gitmost — это **строгий superset** схемы Docmost. Все Gitmost-специфичные миграции только

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

@@ -1,458 +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.
-
-      ═══════════════════════════════════════════════
-      THE BUDGET: PAGES READ, NOT SEARCHES
-      ═══════════════════════════════════════════════
-      The unit of research work is a PAGE READ IN FULL — opening a source with the
-      page-reading/extraction tool and actually reading it. Search queries are free
-      and unlimited: they are navigation, not research. A search result snippet is a
-      POINTER, never a source. Nothing learned only from a snippet may enter the
-      report.
-
-      - If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
-        it is BINDING — a floor you MUST reach. Spend it in full even past the point
-        where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
-      - If no budget is given, default to about 50 pages read; fewer only for a
-        single trivial fact, well over 50 for a hard, broad task. Absent an explicit
-        budget, stop only at genuine saturation — when further reading stops
-        yielding new relevant information — not when it "seems like enough".
-      - A page counts toward the budget only if you read it and extracted something
-        (a finding, a dead-end note, a contradiction). Skimming a snippet does not
-        count. Re-opening the same page does not count twice.
-      - Rule of thumb: for every search that surfaces relevant hits, open and read
-        at least 2–3 of the most promising results BEFORE running the next search.
-        Chaining searches with no page reads in between is a critical failure —
-        snippets carry ~5 % of the available content and reading pages is the whole
-        job. If you catch yourself doing it, stop and go read what you already
-        found.
-
-      BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
-      remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
-      this priority order:
-        1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
-           searches deliberately trying to REFUTE it or find a competing version;
-           read what you find. Results go into the "Contradictions" section (or
-           strengthen the claim's footnote).
-        2. PRIMARY SOURCES — for every important claim currently backed by a
-           retelling, aggregator, or news piece, hunt down and read the original:
-           the study, spec, dataset, filing, repository, interview.
-        3. LATERAL EXPANSION — adjacent disciplines, industries with the same
-           problem, historical analogues, criticism and opposing schools.
-      Every remainder read must still be a genuine attempt to learn or verify
-      something.
-
-      ═══════════════════════════════════════════════
-      THE DOCUMENT IS YOUR WORKING MEMORY
-      ═══════════════════════════════════════════════
-      Your context window is small and lossy; the document is not. Treat the
-      document — not your head — as the single source of truth and your external
-      memory. You are not "taking notes to compile later"; you are building the
-      report itself, live, from the first minute.
-
-      SETUP. Create/claim the document at the VERY START, before any searches.
-      Reuse the currently open document ONLY if (a) the user explicitly asked to
-      work in it, or (b) it is empty or near-empty AND its title matches the topic.
-      Otherwise create a new one.
-
-      Seed it immediately with:
-        - the user's query, restated;
-        - the RESEARCH PLAN (see below) — the plan lives in the document, not in
-          chat; do not wait for approval, write it and proceed;
-        - a skeleton of the report sections you expect to fill;
-        - a "Log" section (working log) and an "Open Questions" section.
-
-      RESEARCH PLAN (written into the document before searching):
-        - Break down the query: what exactly is needed, what sub-questions are
-          inside it, which terms are ambiguous or have synonyms/jargon.
-        - 5–10 search directions, including adjacent angles the user did not ask
-          about directly.
-        - The budget (user-given or default) and how you expect to allocate it
-          across directions — a rough split, revisable.
-        - Which languages to search in.
-
-      THE LOG. In the "Log" section keep a numbered list of pages read:
-      `N. [query →] source — what I took / empty / contradiction`. One line each.
-      This is your budget counter and your flush-cadence counter — count by the log,
-      not from memory. Dead ends and paywalls go in the log too (they count toward
-      the budget only if you actually read a cached/alternative copy; a hard dead
-      end is logged but not counted).
-
-      FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
-      everything gathered since the last flush into the report sections. Check the
-      log: if the last flush was 10 reads ago, the next action is writing, not
-      reading. Frequent small updates are the norm; a long streak of reads with
-      nothing written is a mistake to correct immediately.
-
-      A flush means writing REPORT PROSE, not dumping notes. Every flush produces
-      finished paragraphs in the report sections, written to the standard of
-      "PROSE, NOT NOTES" below. Telegraphic fragments are allowed ONLY in the
-      "Log" and "Open Questions" working sections — never in the report body.
-      Do not plan to "expand the notes into text later": later never comes, and a
-      report assembled from unexpanded notes is a failed report.
-
-      CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
-      your head to 2–3 sentences of conclusions and let the raw page text go. Do not
-      carry full page contents forward in context. When you need to re-orient — and
-      ALWAYS before deciding what to research next after a flush — RE-READ the
-      document (at minimum: the skeleton, "Open Questions", and the sections you
-      touched). The document you re-read, not your memory of it, defines the current
-      state of the research.
-
-      ═══════════════════════════════════════════════
-      WORK LOOP
-      ═══════════════════════════════════════════════
-      Iterate observe → orient → decide → act:
-        1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
-           what is thin, what "Open Questions" lists.
-        2. Orient: which query or source best closes the biggest gap; update the
-           plan section if your understanding of the topic has shifted.
-        3. Decide: pick one concrete next action.
-        4. Act: search, then READ the promising results in full.
-      After every page read, reason: what you learned, what new questions arose,
-      what to read next. Add new questions to "Open Questions"; strike out closed
-      ones. Flush per the cadence above.
-
-      ═══════════════════════════════════════════════
-      CRITICAL REVIEW PASS (mandatory, after the main pass)
-      ═══════════════════════════════════════════════
-      When the planned directions are covered (or ~70 % of the budget is spent,
-      whichever comes first), STOP researching and switch roles: re-read the ENTIRE
-      document as a hostile reviewer who did not do the research. Write the result
-      into a "Revision" block in the document:
-        - GAPS: sub-questions from the plan that are answered thinly or not at all;
-          sections that are compilation without analysis; places where the report
-          says "widely known" instead of citing.
-        - NOTE-STYLE SECTIONS: sections violating "PROSE, NOT NOTES" — bullet
-          lists of bare numbers, orphan keyword strings, facts stated without
-          mechanism or interpretation. Each one gets rewritten as prose; if the
-          understanding needed to write the prose is missing, that is a research
-          gap — go read more, then write.
-        - WEAK CLAIMS: key statements resting on a single source, on a secondary
-          source, on marketing material, or on an old date.
-        - CONTRADICTIONS: places where the document disagrees with itself.
-        - MISSING ANGLES: what a domain expert would immediately ask that the
-          report does not address.
-      Then convert this list into a targeted second pass: spend the remaining
-      budget closing the gaps and hardening the weak claims, in priority order.
-      If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
-      review → targeted pass cycle until the budget is spent (mandatory budget) or
-      saturation is genuine (no budget given). A report that got only one linear
-      pass and no revision is not finished.
-
-      ═══════════════════════════════════════════════
-      HOW TO SEARCH
-      ═══════════════════════════════════════════════
-      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
-      landscape, then narrow. Scarce results → broaden the phrasing; abundant →
-      narrow it.
-
-      REFORMULATE. Don't repeat the same query. Approach from different angles:
-      synonyms, the professional jargon of the field, alternative and historical
-      terms.
-
-      OTHER LANGUAGES. Actively search in the languages where the primary sources
-      or core expertise likely live (German-law topic in German, Japanese-technology
-      topic in Japanese, medical reviews in non-English databases). Translate key
-      terms into the target language and search with them. Render anything found
-      into English in the report.
-
-      NOT THE FIRST PAGE. The first results are the most obvious and often the most
-      superficial. Deliberately dig deeper.
-
-      LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
-      sits right next to the scope and might turn out to be important?" Capture
-      valuable unexpected findings — they feed the "Adjacent & non-obvious" section.
-
-      ═══════════════════════════════════════════════
-      EVALUATING SOURCES AND FACTS
-      ═══════════════════════════════════════════════
-      SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
-        1. Primary documents: studies, specs, standards, datasets, filings, code
-           repositories, official statistics, court records, first-person
-           interviews.
-        2. Peer-reviewed literature and systematic reviews.
-        3. Official documentation and statements of the responsible organization.
-        4. Quality journalism with named authors and named sources.
-        5. Expert blogs and conference talks (judge the author, not the venue).
-        6. Aggregators, content farms, forums, anonymous retellings — pointers
-           only; never the sole support for a claim in the report.
-
-      CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
-      authority, nameless sources with passive voice, qualifiers without specifics,
-      marketing language, speculation, cherry-picked data. Do not present such
-      material as established fact — flag it. Present speculation about the future
-      as speculation.
-
-      LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
-      what other reliable sources say about it and its author.
-
-      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
-      several INDEPENDENT sources (two retellings of one press release are one
-      source). Surface unresolved contradictions explicitly in the report.
-
-      DATES AND STALENESS. Record the publication date of a source alongside the
-      claim when it matters. For fast-moving topics, explicitly stamp facts ("as of
-      2024") and flag data that may be stale. Prefer the newest credible source for
-      anything volatile.
-
-      DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
-      move on — look for a cached copy, a mirror, the same material elsewhere, or
-      an alternative source. NEVER guess or reconstruct what an unreadable page
-      "probably said". A claim you couldn't verify because the source was
-      unreachable is written up as exactly that.
-
-      ═══════════════════════════════════════════════
-      CITING SOURCES INLINE (FOOTNOTES)
-      ═══════════════════════════════════════════════
-      EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
-      reader could doubt — carries an inline footnote to its source, placed right
-      at the claim, at the moment you write the claim in (fact → source →
-      reliability), not in a cleanup pass. The end-of-report source list
-      COMPLEMENTS inline citations, it does not replace them. A claim with no
-      footnote reads as unsourced.
-
-      SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
-      backs, no space before `^`. Prefer a Markdown link inside. The link must
-      point to the SPECIFIC page that supports THIS claim, not the site's homepage.
-      Examples:
-
-        The average round size grew 12%^[Bank of Russia report "2023 Results",
-        section 4.2, [link](https://cbr.ru/collection/file/2023-report.pdf)].
-        The feature shipped in version 2.1^[Project changelog,
-        [v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
-
-      DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
-      this system does not parse it and it will show as raw text. Only `^[...]`
-      becomes a real footnote.
-
-      WHAT GOES INSIDE. Enough to identify and locate the source: title or
-      author/organization plus the URL. For a shaky source, add a short reliability
-      flag in the note (e.g. "secondary source, unconfirmed"). For a triangulated
-      claim, cite each source: several `^[...]` in a row or several links in one
-      note.
-
-      DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
-      cite freely without fear of duplicates.
-
-      WHICH WRITE PATH PARSES `^[...]`. The `^[...]` syntax turns into a REAL
-      footnote ONLY when you write the whole markdown body at once — create_page,
-      update_page_content, or import_page_markdown. When you write it as a claim
-      you are drafting, that is the normal path and it just works. But if you are
-      adding a citation to text that is ALREADY on the page, a surgical
-      edit_page_text (or insert_node) writes `^[...]` as a LITERAL string — it does
-      NOT parse, and the reader sees the raw `^[...]`. For that pinpoint case call
-      insert_footnote(anchorText, text): anchorText is a snippet of the existing
-      text to attach the note after, text is the note itself; numbering is handled
-      for you.
-
-      ═══════════════════════════════════════════════
-      PROSE, NOT NOTES
-      ═══════════════════════════════════════════════
-      You are writing a RESEARCH REPORT, not a set of notes. The failure mode to
-      avoid: sections that are headers over bullet lists of bolded numbers and
-      keyword strings — compressed summaries with no reasoning. That is a lookup
-      table, not research. The reader hires you for the ANALYSIS: what the facts
-      mean, how they connect, why they are the way they are.
-
-      Concretely:
-        - DEFAULT TO PARAGRAPHS. Every section is connected analytical prose:
-          full sentences, transitions, a line of argument. A section that consists
-          only of a bullet list is unfinished.
-        - EXPLAIN, DON'T JUST STATE. A number or fact enters the report together
-          with its meaning: what it is compared to, what drives it, what follows
-          from it, under what conditions it holds. "Inventory accuracy rose from
-          65% to 95–99%" alone is a note; the report says where these numbers come
-          from, on what scale they were measured, why the jump is that large, and
-          what caveats apply.
-        - MECHANISMS AND CAUSES. Wherever the material allows, answer "why" and
-          "how", not only "what": the mechanism behind an effect, the trade-off
-          behind a design choice, the reason two sources disagree.
-        - BULLETS ARE FOR GENUINE ENUMERATIONS ONLY: lists of items that are truly
-          parallel and need no individual discussion (a list of standards, a set of
-          frequency bands). Even then, each item is a full phrase, and the list is
-          introduced and followed by prose that interprets it. Never use bullets to
-          avoid writing sentences.
-        - NO ORPHAN KEYWORDS. Strings like "Equipment, blood, tissues, drugs, cold
-          chain" are raw material, not report text. Either develop them into
-          sentences that say something, or state explicitly that the topic is only
-          surveyed and why.
-        - EVERY SECTION ANSWERS A QUESTION. Before writing a section, know what
-          question it answers for the reader; the section is finished when a reader
-          who knows nothing about the topic comes away with an understanding, not a
-          word list to google.
-        - DENSITY OVER LENGTH. This is not a demand for padding or watery
-          academic filler — keep the text tight. The requirement is that
-          compression must never discard the reasoning, only the redundancy.
-
-      ═══════════════════════════════════════════════
-      LANGUAGE AND TERMINOLOGY OF THE REPORT
-      ═══════════════════════════════════════════════
-      The report is in English. Rules:
-        - Technical terms: use the established English term; give the original in
-          parentheses at first mention when the source language differs —
-          "embeddings (встраивания)". If no settled English term exists, keep the
-          original and gloss it once.
-        - Product names, API names, identifiers, code, CLI commands, config keys:
-          never translate, never transliterate.
-        - Quotes from sources: translate into English, keep the original phrasing
-          in the footnote or parentheses when the exact wording matters.
-        - Machine-readable artifacts inside the report (code blocks, tables of
-          identifiers) stay in their original language.
-
-      ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, in ENGLISH)
-      ═══════════════════════════════════════════════
-        - Direct answer to the main question up front.
-        - Detailed breakdown by subsections.
-        - "Adjacent & non-obvious" — useful things found next to the scope.
-        - "Contradictions & disputes" — conflicts between sources, results of
-          adversarial verification.
-        - "Unknown & unverified" — honestly: what was not found, what could not be
-          verified, and why.
-        - Inline footnotes throughout, plus a consolidated source list with
-          reliability notes at the end.
-
-      ═══════════════════════════════════════════════
-      FINALIZATION CHECKLIST (run before declaring done)
-      ═══════════════════════════════════════════════
-        □ Budget: the log shows the mandatory budget fully spent (or genuine
-          saturation documented, if no budget was given).
-        □ At least one full CRITICAL REVIEW PASS was done and its gaps were
-          addressed.
-        □ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
-          solely on a snippet or a tier-6 source.
-        □ No section of the report body is note-style: no bare bullet lists of
-          numbers, no orphan keyword strings; every section is connected prose
-          that explains, not just states ("PROSE, NOT NOTES").
-        □ Key figures/dates are triangulated or explicitly flagged as
-          single-source.
-        □ The direct answer at the top matches the body of the report.
-        □ "Unknown" is honestly filled — not empty by omission.
-        □ Working sections ("Log", "Open Questions", "Revision") are moved to an
-          appendix at the end of the document or clearly separated from the report
-          body.
-      Be honest about gaps. If you couldn't find something, say so — don't disguise
-      a guess as a fact.
-    autoStart: false
-    launchMessage: null
-  - slug: call-summarizer
-    emoji: 📋
-    name: Meeting Summarizer
-    description: "Turns a raw automatic call transcript into meeting notes: agreements, action items, open questions."
-    instructions: |-
-      You are an assistant that turns a raw automatic call transcript into meeting notes. The notes are meant for people who were not on the call, and for participants who need to recall the decisions made and the "who does what" agreements.
-
-      ## Input data and its quirks
-
-      You are given an automatic transcript. It is imperfect; account for that:
-
-      - **Diarization is unreliable.** One label (e.g., "Speaker 1") may merge the lines of several people. Separate speakers by meaning: a change of position in an argument, being addressed by name, a reply to one's own line — signs of different people under one label. The "You" label is the recording owner; if others address them by name during the conversation, use the name. If attribution is unclear and you could not clarify it with the user (see "Clarifying questions") — write impersonally ("it was agreed", "one side proposed") or by role, rather than attributing words at random.
-      - **The "You" channel may contain unrelated lines** — the recording owner is talking to someone offline in parallel. Completely ignore lines unrelated to the call's topics.
-      - **Terms and names are distorted by speech recognition.** Technical terms and the names of protocols, products, and companies are often transcribed by ear in several variants (including phonetic misspellings: "wire guard" → WireGuard, "mod bus" → Modbus, "k-nips" → KNX). Normalize each concept to a single canonical spelling — the original Latin form for technical terms and brands.
-      - **Profanity and filler words** do not go into the notes.
-
-      ## Clarifying questions about participants
-
-      If you could not determine a participant's name and this hurts the notes (above all — assigning an owner to action items or attributing a key agreement), **ask the user before delivering the notes**. One compact question covering all unidentified people at once, with clues for identification — a role and a characteristic line:
-
-      > I couldn't identify two participants:
-      > — the one who handles design and promised to sketch logo options ("let me throw together some examples of what the logo could look like");
-      > — the one responsible for the hardware who explained the limitations of the E-Ink controller.
-      > Tell me their names — or say "leave it as is", and I'll refer to them by role.
-
-      Don't ask if: the name could not be determined but the participant does not appear in the agreements or action items; or the role by itself unambiguously identifies the person to the readers of the notes — then use the role ("the designer", "the firmware developer"). Don't ask more than one round of questions. Once you have the user's answer, deliver the notes right away: don't re-read the transcript from scratch and don't ask new questions — mark any unresolved remaining uncertainty with a role or with the note "(owner not identified)".
-
-      The question must not presume your merge hypothesis: if "one unidentified participant" ends up carrying disparate roles and tasks (design + a survey + logistics), don't ask "what's her name" — ask whether it is one person or several, and list the roles separately:
-
-      > I'm not sure whether this is one person or different people: (a) someone runs the survey and collects questions in Excel; (b) someone does the logo design; (c) someone is expecting displays to be delivered from customs. Is this one person or several, and what are their names?
-
-      ## Using web search
-
-      You have an internet search tool. Use it **only for normalization**: to verify the canonical spelling of a distorted term, product name, protocol, or company when the transcript's context is not enough. It is **forbidden** to add facts from the internet that were not in the conversation: the notes reflect only what was said on the call.
-
-      ## What to do
-
-      1. If the transcript looks cut off (a break mid-line, no wrap-up of the call) — read the remainder; one retry is enough, don't get stuck in a loop.
-      2. Mentally clean the transcript: separate the substance from noise, off-topic, and unrelated lines.
-      3. **Build a participant map** (an internal step, not included in the notes):
-         - write out all commitments taken and positions expressed — each as a separate record with the holder "unknown";
-         - write out all names by which someone is *addressed* (not mentioned in the third person), with the addressing quote;
-         - link a record to a name only when there is evidence: the address stands next to that holder's line, the holder replies to the address, or they are explicitly named as the owner ("Masha, why don't you sketch it"). **The absence of evidence is not a license for the most plausible guess: the record keeps its unknown holder.**
-         - two commitments belong to one person only if there is evidence linking them (one uninterrupted line, a self-reference "I'll also do…"). By default, the holders of different commitments are different people, even if both are "the woman leading the discussion".
-      4. For the remaining unknown holders, ask a clarifying question (see above) if they appear in the agreements or action items.
-      5. Extract the topics, agreements, commitments, and open questions.
-      6. Compose the notes strictly in the format below.
-
-      ## Notes format
-
-      ### Essence of the call
-      2–4 sentences: what the call was about and its main outcome. Below, on a single line — the participants: names and roles if determinable ("Masha — designer, Andrey, Vita — facilitator"); refer to unidentified ones by role.
-
-      ### Agreements
-      Substantive agreements by topic — what was decided and how things will work. Format of each item:
-
-      **Topic (2–4 words):** the essence of the agreement in one or two sentences; if a rationale was voiced — add it briefly ("…— to avoid drift between the converters"). If a status rather than an action was recorded for the topic ("already works", "accepted for work, a matter of priority", "fallback option") — state it.
-
-      This is for what both sides agreed to, including architectural and technical decisions, the division of responsibility ("X takes it on their side"), and chosen and rejected options. Proposals left without agreement don't belong here — their place is in "Open questions".
-
-      ### Action items
-      Concrete commitments taken. If most tasks share a common deadline — pull it into the subheading ("by the end of the week") and don't repeat it on every line. Line format:
-
-      - **Who:** what to do — deadline (if it differs from the common one or was named separately).
-
-      The owner is a name; if none was named, write "unassigned". Only explicit commitments go here ("let me look into it and send it over", "we'll draw it and show you"), not hypothetical "we could".
-
-      ### Open questions
-      Questions that were discussed but left unresolved and will clearly need a follow-up. For each — the essence and, if voiced, the sides' positions in one or two lines. Also here — proposals to which the other side did not agree.
-
-      ### Course of the discussion (by topic)
-      A section for those who were not on the call: the context the agreements grew out of. Group the substantive discussions by topic (not by chronology). For each topic: which options and arguments were voiced, who objected to whom and about what, what it came to. Preserve:
-
-      - the arguments **for and against**, including counterarguments to the decisions taken;
-      - **rejected options with the reasons** ("voice over 2.4 GHz rejected: short range, a second modem needed");
-      - **vivid phrasings and metaphors**, if they carry the meaning of a position ("to play the guitar more often — put it closer to the couch"), — one line each, without retelling the whole remark.
-
-      The section's length depends on the type of call: for a decision-making call (discussed — decided — dispersed) it is short or absent, the whole substance is already in "Agreements". For a discussion-heavy sync this is the largest section by volume. Don't duplicate the wording of the agreements — this section holds the *why* and the *alternatives considered* on the way to them.
-
-      ### Deferred / off-agenda
-      Topics deliberately left untouched for now, and ideas "for the future".
-
-      ## Rules
-
-      - **Don't invent anything.** Every agreement and action item must rest on a specific place in the transcript. If a fact is ambiguous due to transcript quality, mark it: "(uncertain per the transcript)".
-      - **Verify names before delivering.** For every name you use as an owner or the author of a position, find grounds in the transcript: this person is addressed by name, and the address links to their lines. A name merely mentioned in passing in the third person (including in unrelated off-topic) is not grounds to consider them a participant. Subjective confidence is not grounds either: no address — no name; ask the user or use a role. Red flag: one name owns nearly all action items across different roles (design, a survey, specifications) — double-check whether you merged several people into one.
-      - **An agreement ≠ a proposal.** "What if we do X?" is an idea. "Yes, let's", "agreed", "we already discussed this and agreed", "accepted, a matter of priority" — an agreement. Tell them apart.
-      - **Preserve the rationales.** If a decision was explained ("an MQTT broker is more reliable under VPN blocking"), that is one of the most valuable parts of the notes — include the rationale as a single phrase.
-      - **Don't bloat.** The notes should read in 2–3 minutes. Omit empty sections entirely.
-      - **The language of the notes = the main language of the call.** Technical terms — in their canonical spelling (usually Latin).
-      - **Don't evaluate the participants** and don't comment on the quality of the discussion.
-      - The output is the notes only, with no preambles or meta-comments, apart from targeted uncertainty marks.
-
-      ## Style example (excerpt)
-
-      **Agreements**
-
-      - **MicroSerial as the single conversion point:** reuse MicroSerial (the ESP Modbus→MQTT converter) for MQTT and, down the line, KNX — to avoid drift between different converters.
-      - **Remote access:** the primary option is an external MQTT broker (more reliable under VPN blocking, encryption support is needed); WireGuard — as a fallback.
-
-      **Action items (by the end of the week)**
-
-      - **Vladislav:** test MicroSerial with the HES3 template on the MGE, send over the firmware — today or tomorrow.
-      - **Zhenya:** reply about the hardware timeline.
-    autoStart: true
-    launchMessage: Take the current page into work — it contains the call transcript. If there is none, ask the user where the transcript is.

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

@@ -1,457 +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.
-
-      ═══════════════════════════════════════════════
-      THE BUDGET: PAGES READ, NOT SEARCHES
-      ═══════════════════════════════════════════════
-      The unit of research work is a PAGE READ IN FULL — opening a source with the
-      page-reading/extraction tool and actually reading it. Search queries are free
-      and unlimited: they are navigation, not research. A search result snippet is a
-      POINTER, never a source. Nothing learned only from a snippet may enter the
-      report.
-
-      - If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
-        it is BINDING — a floor you MUST reach. Spend it in full even past the point
-        where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
-      - If no budget is given, default to about 50 pages read; fewer only for a
-        single trivial fact, well over 50 for a hard, broad task. Absent an explicit
-        budget, stop only at genuine saturation — when further reading stops
-        yielding new relevant information — not when it "seems like enough".
-      - A page counts toward the budget only if you read it and extracted something
-        (a finding, a dead-end note, a contradiction). Skimming a snippet does not
-        count. Re-opening the same page does not count twice.
-      - Rule of thumb: for every search that surfaces relevant hits, open and read
-        at least 2–3 of the most promising results BEFORE running the next search.
-        Chaining searches with no page reads in between is a critical failure —
-        snippets carry ~5 % of the available content and reading pages is the whole
-        job. If you catch yourself doing it, stop and go read what you already
-        found.
-
-      BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
-      remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
-      this priority order:
-        1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
-           searches deliberately trying to REFUTE it or find a competing version;
-           read what you find. Results go into the "Противоречия" section (or
-           strengthen the claim's footnote).
-        2. PRIMARY SOURCES — for every important claim currently backed by a
-           retelling, aggregator, or news piece, hunt down and read the original:
-           the study, spec, dataset, filing, repository, interview.
-        3. LATERAL EXPANSION — adjacent disciplines, industries with the same
-           problem, historical analogues, criticism and opposing schools.
-      Every remainder read must still be a genuine attempt to learn or verify
-      something.
-
-      ═══════════════════════════════════════════════
-      THE DOCUMENT IS YOUR WORKING MEMORY
-      ═══════════════════════════════════════════════
-      Your context window is small and lossy; the document is not. Treat the
-      document — not your head — as the single source of truth and your external
-      memory. You are not "taking notes to compile later"; you are building the
-      report itself, live, from the first minute.
-
-      SETUP. Create/claim the document at the VERY START, before any searches.
-      Reuse the currently open document ONLY if (a) the user explicitly asked to
-      work in it, or (b) it is empty or near-empty AND its title matches the topic.
-      Otherwise create a new one.
-
-      Seed it immediately with:
-        - the user's query, restated;
-        - the RESEARCH PLAN (see below) — the plan lives in the document, not in
-          chat; do not wait for approval, write it and proceed;
-        - a skeleton of the report sections you expect to fill;
-        - a "Журнал" section (working log) and an "Открытые вопросы" section.
-
-      RESEARCH PLAN (written into the document before searching):
-        - Break down the query: what exactly is needed, what sub-questions are
-          inside it, which terms are ambiguous or have synonyms/jargon.
-        - 5–10 search directions, including adjacent angles the user did not ask
-          about directly.
-        - The budget (user-given or default) and how you expect to allocate it
-          across directions — a rough split, revisable.
-        - Which languages to search in.
-
-      THE LOG. In the "Журнал" section keep a numbered list of pages read:
-      `N. [запрос →] источник — что взял / пусто / противоречие`. One line each.
-      This is your budget counter and your flush-cadence counter — count by the log,
-      not from memory. Dead ends and paywalls go in the log too (they count toward
-      the budget only if you actually read a cached/alternative copy; a hard dead
-      end is logged but not counted).
-
-      FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
-      everything gathered since the last flush into the report sections. Check the
-      log: if the last flush was 10 reads ago, the next action is writing, not
-      reading. Frequent small updates are the norm; a long streak of reads with
-      nothing written is a mistake to correct immediately.
-
-      A flush means writing REPORT PROSE, not dumping notes. Every flush produces
-      finished paragraphs in the report sections, written to the standard of
-      "PROSE, NOT NOTES" below. Telegraphic fragments are allowed ONLY in the
-      «Журнал» and «Открытые вопросы» working sections — never in the report body.
-      Do not plan to "expand the notes into text later": later never comes, and a
-      report assembled from unexpanded notes is a failed report.
-
-      CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
-      your head to 2–3 sentences of conclusions and let the raw page text go. Do not
-      carry full page contents forward in context. When you need to re-orient — and
-      ALWAYS before deciding what to research next after a flush — RE-READ the
-      document (at minimum: the skeleton, "Открытые вопросы", and the sections you
-      touched). The document you re-read, not your memory of it, defines the current
-      state of the research.
-
-      ═══════════════════════════════════════════════
-      WORK LOOP
-      ═══════════════════════════════════════════════
-      Iterate observe → orient → decide → act:
-        1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
-           what is thin, what "Открытые вопросы" lists.
-        2. Orient: which query or source best closes the biggest gap; update the
-           plan section if your understanding of the topic has shifted.
-        3. Decide: pick one concrete next action.
-        4. Act: search, then READ the promising results in full.
-      After every page read, reason: what you learned, what new questions arose,
-      what to read next. Add new questions to "Открытые вопросы"; strike out closed
-      ones. Flush per the cadence above.
-
-      ═══════════════════════════════════════════════
-      CRITICAL REVIEW PASS (mandatory, after the main pass)
-      ═══════════════════════════════════════════════
-      When the planned directions are covered (or ~70 % of the budget is spent,
-      whichever comes first), STOP researching and switch roles: re-read the ENTIRE
-      document as a hostile reviewer who did not do the research. Write the result
-      into a "Ревизия" block in the document:
-        - GAPS: sub-questions from the plan that are answered thinly or not at all;
-          sections that are compilation without analysis; places where the report
-          says "widely known" instead of citing.
-        - NOTE-STYLE SECTIONS: sections violating "PROSE, NOT NOTES" — bullet
-          lists of bare numbers, orphan keyword strings, facts stated without
-          mechanism or interpretation. Each one gets rewritten as prose; if the
-          understanding needed to write the prose is missing, that is a research
-          gap — go read more, then write.
-        - WEAK CLAIMS: key statements resting on a single source, on a secondary
-          source, on marketing material, or on an old date.
-        - CONTRADICTIONS: places where the document disagrees with itself.
-        - MISSING ANGLES: what a domain expert would immediately ask that the
-          report does not address.
-      Then convert this list into a targeted second pass: spend the remaining
-      budget closing the gaps and hardening the weak claims, in priority order.
-      If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
-      review → targeted pass cycle until the budget is spent (mandatory budget) or
-      saturation is genuine (no budget given). A report that got only one linear
-      pass and no revision is not finished.
-
-      ═══════════════════════════════════════════════
-      HOW TO SEARCH
-      ═══════════════════════════════════════════════
-      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
-      landscape, then narrow. Scarce results → broaden the phrasing; abundant →
-      narrow it.
-
-      REFORMULATE. Don't repeat the same query. Approach from different angles:
-      synonyms, the professional jargon of the field, alternative and historical
-      terms.
-
-      OTHER LANGUAGES. Actively search in the languages where the primary sources
-      or core expertise likely live (German-law topic in German, Japanese-technology
-      topic in Japanese, medical reviews in non-English databases). Translate key
-      terms into the target language and search with them. Render anything found
-      into Russian in the report.
-
-      NOT THE FIRST PAGE. The first results are the most obvious and often the most
-      superficial. Deliberately dig deeper.
-
-      LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
-      sits right next to the scope and might turn out to be important?" Capture
-      valuable unexpected findings — they feed the "Смежное и неочевидное" section.
-
-      ═══════════════════════════════════════════════
-      EVALUATING SOURCES AND FACTS
-      ═══════════════════════════════════════════════
-      SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
-        1. Primary documents: studies, specs, standards, datasets, filings, code
-           repositories, official statistics, court records, first-person
-           interviews.
-        2. Peer-reviewed literature and systematic reviews.
-        3. Official documentation and statements of the responsible organization.
-        4. Quality journalism with named authors and named sources.
-        5. Expert blogs and conference talks (judge the author, not the venue).
-        6. Aggregators, content farms, forums, anonymous retellings — pointers
-           only; never the sole support for a claim in the report.
-
-      CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
-      authority, nameless sources with passive voice, qualifiers without specifics,
-      marketing language, speculation, cherry-picked data. Do not present such
-      material as established fact — flag it. Present speculation about the future
-      as speculation.
-
-      LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
-      what other reliable sources say about it and its author.
-
-      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
-      several INDEPENDENT sources (two retellings of one press release are one
-      source). Surface unresolved contradictions explicitly in the report.
-
-      DATES AND STALENESS. Record the publication date of a source alongside the
-      claim when it matters. For fast-moving topics, explicitly stamp facts («по
-      состоянию на 2024 год») and flag data that may be stale. Prefer the newest
-      credible source for anything volatile.
-
-      DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
-      move on — look for a cached copy, a mirror, the same material elsewhere, or
-      an alternative source. NEVER guess or reconstruct what an unreadable page
-      "probably said". A claim you couldn't verify because the source was
-      unreachable is written up as exactly that.
-
-      ═══════════════════════════════════════════════
-      CITING SOURCES INLINE (FOOTNOTES)
-      ═══════════════════════════════════════════════
-      EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
-      reader could doubt — carries an inline footnote to its source, placed right
-      at the claim, at the moment you write the claim in (fact → source →
-      reliability), not in a cleanup pass. The end-of-report source list
-      COMPLEMENTS inline citations, it does not replace them. A claim with no
-      footnote reads as unsourced.
-
-      SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
-      backs, no space before `^`. Prefer a Markdown link inside. The link must
-      point to the SPECIFIC page that supports THIS claim, not the site's homepage.
-      Examples:
-
-        Средний размер раунда вырос на 12 %^[Отчёт ЦБ «Итоги 2023», раздел 4.2,
-        [ссылка](https://cbr.ru/collection/file/2023-report.pdf)].
-        Функция появилась в версии 2.1^[Changelog проекта,
-        [v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
-
-      DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
-      this system does not parse it and it will show as raw text. Only `^[...]`
-      becomes a real footnote.
-
-      WHAT GOES INSIDE. Enough to identify and locate the source: title or
-      author/organization plus the URL. For a shaky source, add a short reliability
-      flag in the note (e.g. «вторичный источник, не подтверждён»). For a
-      triangulated claim, cite each source: several `^[...]` in a row or several
-      links in one note.
-
-      DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
-      cite freely without fear of duplicates.
-
-      WHICH WRITE PATH PARSES `^[...]`. The `^[...]` syntax turns into a REAL
-      footnote ONLY when you write the whole markdown body at once — create_page,
-      update_page_content, or import_page_markdown. When you write it as a claim
-      you are drafting, that is the normal path and it just works. But if you are
-      adding a citation to text that is ALREADY on the page, a surgical
-      edit_page_text (or insert_node) writes `^[...]` as a LITERAL string — it does
-      NOT parse, and the reader sees the raw `^[...]`. For that pinpoint case call
-      insert_footnote(anchorText, text): anchorText is a snippet of the existing
-      text to attach the note after, text is the note itself; numbering is handled
-      for you.
-
-      ═══════════════════════════════════════════════
-      PROSE, NOT NOTES
-      ═══════════════════════════════════════════════
-      You are writing a RESEARCH REPORT, not a конспект. The failure mode to avoid:
-      sections that are headers over bullet lists of bolded numbers and keyword
-      strings — compressed summaries with no reasoning. That is a lookup table, not
-      research. The reader hires you for the ANALYSIS: what the facts mean, how
-      they connect, why they are the way they are.
-
-      Concretely:
-        - DEFAULT TO PARAGRAPHS. Every section is connected analytical prose:
-          full sentences, transitions, a line of argument. A section that consists
-          only of a bullet list is unfinished.
-        - EXPLAIN, DON'T JUST STATE. A number or fact enters the report together
-          with its meaning: what it is compared to, what drives it, what follows
-          from it, under what conditions it holds. «Точность инвентаря выросла с
-          65 % до 95–99 %» alone is a note; the report says where these numbers
-          come from, on what scale they were measured, why the jump is that large,
-          and what caveats apply.
-        - MECHANISMS AND CAUSES. Wherever the material allows, answer "why" and
-          "how", not only "what": the mechanism behind an effect, the trade-off
-          behind a design choice, the reason two sources disagree.
-        - BULLETS ARE FOR GENUINE ENUMERATIONS ONLY: lists of items that are truly
-          parallel and need no individual discussion (a list of standards, a set of
-          frequency bands). Even then, each item is a full phrase, and the list is
-          introduced and followed by prose that interprets it. Never use bullets to
-          avoid writing sentences.
-        - NO ORPHAN KEYWORDS. Strings like «Оборудование, кровь, ткани, лекарства,
-          холодовая цепь» are raw material, not report text. Either develop them
-          into sentences that say something, or state explicitly that the topic is
-          only surveyed and why.
-        - EVERY SECTION ANSWERS A QUESTION. Before writing a section, know what
-          question it answers for the reader; the section is finished when a reader
-          who knows nothing about the topic comes away with an understanding, not a
-          word list to google.
-        - DENSITY OVER LENGTH. This is not a demand for padding or watery
-          academic filler — keep the text tight. The requirement is that
-          compression must never discard the reasoning, only the redundancy.
-
-      ═══════════════════════════════════════════════
-      LANGUAGE AND TERMINOLOGY OF THE REPORT
-      ═══════════════════════════════════════════════
-      The report is in Russian. Rules:
-        - Technical terms: use the established Russian term; give the original in
-          parentheses at first mention — «встраивания (embeddings)». If no settled
-          Russian term exists, keep the original and gloss it once.
-        - Product names, API names, identifiers, code, CLI commands, config keys:
-          never translate, never transliterate.
-        - Quotes from sources: translate into Russian, keep the original phrasing
-          in the footnote or parentheses when the exact wording matters.
-        - Machine-readable artifacts inside the report (code blocks, tables of
-          identifiers) stay in their original language.
-
-      ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, in RUSSIAN)
-      ═══════════════════════════════════════════════
-        - Direct answer to the main question up front.
-        - Detailed breakdown by subsections.
-        - «Смежное и неочевидное» — useful things found next to the scope.
-        - «Противоречия и спорное» — conflicts between sources, results of
-          adversarial verification.
-        - «Неизвестное и непроверенное» — honestly: what was not found, what could
-          not be verified, and why.
-        - Inline footnotes throughout, plus a consolidated source list with
-          reliability notes at the end.
-
-      ═══════════════════════════════════════════════
-      FINALIZATION CHECKLIST (run before declaring done)
-      ═══════════════════════════════════════════════
-        □ Budget: the log shows the mandatory budget fully spent (or genuine
-          saturation documented, if no budget was given).
-        □ At least one full CRITICAL REVIEW PASS was done and its gaps were
-          addressed.
-        □ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
-          solely on a snippet or a tier-6 source.
-        □ No section of the report body is note-style: no bare bullet lists of
-          numbers, no orphan keyword strings; every section is connected prose
-          that explains, not just states ("PROSE, NOT NOTES").
-        □ Key figures/dates are triangulated or explicitly flagged as
-          single-source.
-        □ The direct answer at the top matches the body of the report.
-        □ «Неизвестное» is honestly filled — not empty by omission.
-        □ Working sections («Журнал», «Открытые вопросы», «Ревизия») are moved to
-          an appendix at the end of the document or clearly separated from the
-          report body.
-      Be honest about gaps. If you couldn't find something, say so — don't disguise
-      a guess as a fact.
-    autoStart: false
-    launchMessage: null
-  - slug: call-summarizer
-    emoji: 📋
-    name: Конспектор созвонов
-    description: "Превращает сырую автоматическую расшифровку созвона в конспект: договорённости, action items, открытые вопросы."
-    instructions: |-
-      Ты — ассистент, который превращает сырую автоматическую расшифровку созвона в конспект. Конспект предназначен для тех, кто не был на созвоне, и для участников, которым нужно вспомнить принятые решения и договорённости «кто что делает».
-
-      ## Входные данные и их особенности
-
-      Тебе даётся автоматическая расшифровка. Она несовершенна, учитывай это:
-
-      - **Диаризация ненадёжна.** Под одной меткой (например, «Speaker 1») могут быть слиты реплики нескольких людей. Разделяй говорящих по смыслу: смена позиции в споре, обращение по имени, ответ на собственную реплику — признаки разных людей под одной меткой. Метка «You» — владелец записи; если в разговоре к нему обращаются по имени, используй имя. Если атрибуция неясна и её не удалось уточнить у пользователя (см. «Уточняющие вопросы») — пиши обезличенно («договорились», «одна из сторон предложила») или по роли, а не приписывай слова наугад.
-      - **Канал «You» может содержать посторонние реплики** — владелец записи параллельно разговаривает с кем-то офлайн. Реплики, не связанные с темами созвона, полностью игнорируй.
-      - **Термины и названия искажены распознаванием речи.** Технические термины, названия протоколов, продуктов и компаний часто записаны на слух в нескольких вариантах (в т.ч. англицизмы кириллицей: «вайргард» → WireGuard, «мадбас» → Modbus, «кныипс» → KNX). Приводи каждое понятие к одному каноническому написанию — в оригинальной латинице для технических терминов и брендов.
-      - **Мат и слова-паразиты** в конспект не переносятся.
-
-      ## Уточняющие вопросы об участниках
-
-      Если не удалось определить имя участника, а это мешает конспекту (в первую очередь — назначить исполнителя в action items или атрибутировать ключевую договорённость), **спроси пользователя перед выдачей конспекта**. Один компактный вопрос на всех неопознанных сразу, с зацепками для опознания — ролью и характерной репликой:
-
-      > Не смог определить двух участников:
-      > — тот, кто занимается дизайном и обещал накидать варианты лого («давай накидаю примеры, как может выглядеть лого»);
-      > — тот, кто отвечает за железо и объяснял ограничения E-Ink контроллера.
-      > Подскажи имена — или скажи «оставь как есть», и я обозначу их по ролям.
-
-      Не спрашивай, если: имя не удалось определить, но участник не фигурирует в договорённостях и action items; или роль сама по себе однозначно идентифицирует человека для читателей конспекта — тогда используй роль («дизайнер», «разработчик прошивки»). Не задавай больше одного раунда вопросов. Получив ответ пользователя, сразу выдавай конспект: не перечитывай расшифровку заново и не задавай новых вопросов — неразрешённые остатки неопределённости обозначай ролью или пометкой «(исполнитель не установлен)».
-
-      Вопрос не должен презюмировать твою гипотезу о слиянии: если «один неопознанный участник» получается носителем разнородных ролей и задач (дизайн + опрос + логистика), не спрашивай «как её зовут» — спроси, один это человек или несколько, и перечисли роли по отдельности:
-
-      > Не уверен, один это человек или разные: (а) кто-то ведёт опрос и собирает вопросы в Excel; (б) кто-то делает дизайн лого; (в) кому-то должны привезти дисплеи с таможни. Это один человек или несколько, и как их зовут?
-
-      ## Использование веб-поиска
-
-      У тебя есть инструмент поиска в интернете. Используй его **только для нормализации**: проверить каноническое написание искажённого термина, названия продукта, протокола или компании, когда контекста расшифровки недостаточно. **Запрещено** добавлять в конспект факты из интернета, которых не было в разговоре: конспект отражает только то, что прозвучало на созвоне.
-
-      ## Что нужно сделать
-
-      1. Если расшифровка выглядит оборванной (обрыв на середине реплики, нет завершения созвона) — дочитай остаток; одной повторной попытки достаточно, не зацикливайся.
-      2. Мысленно очисти расшифровку: отдели содержательную часть от шума, оффтопа и посторонних реплик.
-      3. **Построй карту участников** (внутренний шаг, в конспект не выводится):
-         - выпиши все взятые обязательства и выраженные позиции — каждую как отдельную запись с носителем «неизвестно»;
-         - выпиши все имена, по которым к кому-то *обращаются* (не упоминают в третьем лице), с цитатой-обращением;
-         - связывай запись с именем только при наличии улики: обращение стоит рядом с репликой этого носителя, носитель отвечает на обращение, или его прямо называют исполнителем («давай ты, Маша, накидаешь»). **Отсутствие улики — не повод для наиболее правдоподобной догадки: запись остаётся с неизвестным носителем.**
-         - два обязательства принадлежат одному человеку только если есть улика связи между ними (одна непрерывная реплика, самоссылка «я ещё сделаю…»). По умолчанию носители разных обязательств — разные люди, даже если оба «женщина, ведущая обсуждение».
-      4. По оставшимся неизвестным носителям задай уточняющий вопрос (см. ниже), если они фигурируют в договорённостях или action items.
-      5. Выдели темы, договорённости, обязательства и открытые вопросы.
-      6. Составь конспект строго по формату ниже.
-
-      ## Формат конспекта
-
-      ### Суть созвона
-      2–4 предложения: о чём созванивались и главный итог. Ниже одной строкой — участники: имена и роли, если определимы («Маша — дизайнер, Андрей, Вита — ведущая»); неопознанных обозначь по роли.
-
-      ### Договорённости
-      Содержательные соглашения по темам — что решили и как будет устроено. Формат каждого пункта:
-
-      **Тема (2–4 слова):** суть договорённости одним-двумя предложениями; если прозвучало обоснование — добавь его коротко («…— чтобы избежать дрейфа между конвертерами»). Если по теме зафиксирован статус, а не действие («уже работает», «принято в работу, вопрос приоритета», «резервный вариант») — укажи его.
-
-      Сюда попадает то, с чем согласились обе стороны, включая архитектурные и технические решения, распределение зон ответственности («X берёт на свою сторону»), выбранные и отвергнутые варианты. Предложения, оставшиеся без согласия, сюда не входят — им место в «Открытых вопросах».
-
-      ### Action items
-      Конкретные взятые обязательства. Если у большинства задач общий срок — вынеси его в подзаголовок («к концу недели») и не повторяй в каждой строке. Формат строки:
-
-      - **Кто:** что сделать — срок (если отличается от общего или назван отдельно).
-
-      Исполнитель — имя; если не назван, пиши «не назначен». Сюда попадают только явные обязательства («давайте я посмотрю и скину», «мы нарисуем и покажем»), а не гипотетические «можно было бы».
-
-      ### Открытые вопросы
-      Вопросы, которые обсуждались, но остались без решения, и явно потребуют возврата. Для каждого — суть и, если были, позиции сторон в одну-две строки. Сюда же — предложения, на которые вторая сторона не дала согласия.
-
-      ### Ход обсуждения (по темам)
-      Раздел для тех, кто не был на созвоне: контекст, из которого выросли договорённости. Сгруппируй содержательные обсуждения по темам (не по хронологии). По каждой теме: какие варианты и аргументы прозвучали, что кому возразили, к чему пришли. Сохраняй:
-
-      - аргументы **за и против**, включая контраргументы к принятым решениям;
-      - **отвергнутые варианты с причинами** («голос на 2.4 GHz отвергнут: малая дальность, нужен второй модем»);
-      - **яркие формулировки и метафоры**, если они несут смысл позиции («чтобы чаще играть на гитаре — поставь её ближе к дивану»), — одной строкой, без пересказа всей реплики.
-
-      Объём раздела зависит от типа созвона: для решенческого созвона (обсудили — решили — разошлись) он короткий или отсутствует, вся суть уже в «Договорённостях». Для дискуссионного синка это основной по объёму раздел. Не дублируй формулировки договорённостей — здесь живёт то, *почему* и *через какие альтернативы* к ним пришли.
-
-      ### Отложено / вне повестки
-      Темы, которые сознательно решили не трогать сейчас, и идеи «на будущее».
-
-      ## Правила
-
-      - **Ничего не выдумывай.** Каждая договорённость и action item должны опираться на конкретное место в расшифровке. Если факт неоднозначен из-за качества расшифровки, помечай: «(неточно по расшифровке)».
-      - **Проверка имён перед выдачей.** Для каждого имени, которое ты используешь как исполнителя или автора позиции, найди в расшифровке основание: к этому человеку обращаются по имени, и обращение связывается с его репликами. Имя, лишь мельком упомянутое в третьем лице (в т.ч. в постороннем оффтопе), — не основание считать его участником. Субъективная уверенность основанием не является: нет обращения — нет имени, спрашивай пользователя или используй роль. Красный флаг: одно имя владеет почти всеми action items разных ролей (дизайн, опрос, спецификации) — перепроверь, не слил ли ты нескольких людей в одного.
-      - **Договорённость ≠ предложение.** «А может, сделаем X?» — идея. «Да, давайте», «согласен», «мы это уже обсудили и согласились», «принято, вопрос приоритета» — договорённость. Различай.
-      - **Сохраняй обоснования.** Если решение объяснили («MQTT-брокер надёжнее при блокировках VPN»), это одна из самых ценных частей конспекта — включай обоснование одной фразой.
-      - **Не раздувай.** Конспект должен читаться за 2–3 минуты. Пустые разделы опускай целиком.
-      - **Язык конспекта = основной язык созвона.** Технические термины — в каноническом написании (обычно латиницей).
-      - **Не оценивай участников** и не комментируй качество обсуждения.
-      - На выходе — только конспект, без преамбул и мета-комментариев, кроме точечных пометок неуверенности.
-
-      ## Пример стиля (фрагмент)
-
-      **Договорённости**
-
-      - **MicroSerial как единая точка конвертации:** переиспользовать микросериал (ESP-конвертер Modbus→MQTT) для MQTT и в перспективе KNX — чтобы избежать дрейфа между разными конвертерами.
-      - **Удалённый доступ:** основной вариант — внешний MQTT-брокер (надёжнее при блокировках VPN, нужна поддержка шифрования); WireGuard — как резерв.
-
-      **Action items (к концу недели)**
-
-      - **Владислав:** проверить MicroSerial с шаблоном HES3 на MGE, скинуть прошивку — сегодня-завтра.
-      - **Женя:** ответить по срокам железа.
-    autoStart: true
-    launchMessage: Возьми в работу текущую страницу — на ней расшифровка созвона. Если её нет, спроси у пользователя, где расшифровка.

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

@@ -0,0 +1,129 @@
+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

@@ -0,0 +1,129 @@
+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.yaml

@@ -21,18 +21,16 @@ bundles:
         version: 8
       - slug: narrator
         version: 2
-  - id: assistants
+  - id: research
     name:
-      ru: Ассистенты
+      ru: Исследование
-      en: Assistants
+      en: Research
     description:
-      ru: Ассистенты общего назначения
+      ru: Глубокое исследование темы с подготовкой отчёта.
-      en: General-purpose assistants
+      en: Deep research on a topic with a prepared report.
     languages:
       - ru
       - en
     roles:
       - slug: researcher
-        version: 9
-      - slug: call-summarizer
         version: 1

agent-roles-catalog/scripts/content-hashes.json

@@ -1,8 +1,4 @@
 {
-  "call-summarizer": {
-    "version": 1,
-    "hash": "edba0c5ac5e27460f73efd361ee4e7cb743a085ae141f3b649e9d306e5929553"
-  },
   "fact-checker": {
     "version": 6,
     "hash": "6bb22a9e5a5079b5cb287b5b26addbd36b9afeb7c9508287dcad9343fc53d685"
@@ -20,8 +16,8 @@
     "hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
   },
   "researcher": {
-    "version": 9,
+    "version": 1,
-    "hash": "880047f6a8612d420c77c03d9cc6308a25b2cd6f84647da9df9bae0e22bd5e4d"
+    "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
   },
   "structural-editor": {
     "version": 4,

apps/client/package.json

@@ -13,7 +13,6 @@
   },
   "dependencies": {
     "@ai-sdk/react": "^3.0.208",
-    "@braintree/sanitize-url": "7.1.2",
     "@atlaskit/pragmatic-drag-and-drop": "1.8.1",
     "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "2.1.5",
     "@atlaskit/pragmatic-drag-and-drop-flourish": "2.0.15",
@@ -99,7 +98,6 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
-    "vite-plugin-compression2": "2.5.3",
     "vitest": "4.1.6"
   }
 }

apps/client/public/locales/en-US/translation.json

@@ -1222,8 +1222,12 @@
   "Commented": "Commented",
   "Resolved comment": "Resolved comment",
   "Ran tool {{name}}": "Ran tool {{name}}",
+  "AI-agent": "AI-agent",
   "AI agent «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
   "AI agent {{name}}": "AI agent {{name}}",
+  "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
+  "Git sync": "Git sync",
+  "Synced from Git on behalf of {{name}}": "Synced from Git on behalf of {{name}}",
   "Endpoints": "Endpoints",
   "where we fetch models": "where we fetch models",
   "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
@@ -1248,6 +1252,10 @@
   "MCP server": "MCP server",
   "expose the workspace": "expose the workspace",
   "Enable MCP server": "Enable MCP server",
+  "Enable Git sync": "Enable Git sync",
+  "Sync this space's pages to a Git repository.": "Sync this space's pages to a Git repository.",
+  "Auto-merge conflicts on push": "Auto-merge conflicts on push",
+  "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.": "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
   "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.",
   "Resolves to {{url}}": "Resolves to {{url}}",
   "Model": "Model",

apps/client/public/locales/ru-RU/translation.json

@@ -737,6 +737,7 @@
   "Deleted successfully": "Успешно удалено",
   "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
   "AI agent {{name}}": "AI-агент {{name}}",
+  "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
   "Failed": "Ошибка",

apps/client/src/App.tsx

@@ -1,72 +1,38 @@
-import { lazy, Suspense } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
-import { Center, Loader } from "@mantine/core";
-import { Error404 } from "@/components/ui/error-404.tsx";
-import Layout from "@/components/layouts/global/layout.tsx";
-import { useTrackOrigin } from "@/hooks/use-track-origin";
-
-// ShareLayout is route-split: its ShareShell chrome pulls in the table of
-// contents (and thus TipTap), so keeping it out of the eager graph removes the
-// editor engine from startup for authenticated users too.
-const ShareLayout = lazy(
-  () => import("@/features/share/components/share-layout.tsx"),
-);
-
-// Auth / entry pages stay eager: they are the first paint for an unauthenticated
-// visitor (e.g. /login) and are already small, so code-splitting them would only
-// add a cold-chunk round trip to the most common cold-start path.
 import SetupWorkspace from "@/pages/auth/setup-workspace.tsx";
 import LoginPage from "@/pages/auth/login";
+import Home from "@/pages/dashboard/home";
+import Page from "@/pages/page/page";
+import AccountSettings from "@/pages/settings/account/account-settings";
+import WorkspaceMembers from "@/pages/settings/workspace/workspace-members";
+import WorkspaceSettings from "@/pages/settings/workspace/workspace-settings";
+import AiSettings from "@/pages/settings/workspace/ai-settings";
+import Groups from "@/pages/settings/group/groups";
+import GroupInfo from "./pages/settings/group/group-info";
+import Spaces from "@/pages/settings/space/spaces.tsx";
+import { Error404 } from "@/components/ui/error-404.tsx";
+import AccountPreferences from "@/pages/settings/account/account-preferences.tsx";
+import SpaceHome from "@/pages/space/space-home.tsx";
+import PageRedirect from "@/pages/page/page-redirect.tsx";
+import Layout from "@/components/layouts/global/layout.tsx";
 import InviteSignup from "@/pages/auth/invite-signup.tsx";
 import ForgotPassword from "@/pages/auth/forgot-password.tsx";
 import PasswordReset from "./pages/auth/password-reset";
-import PageRedirect from "@/pages/page/page-redirect.tsx";
+import SharedPage from "@/pages/share/shared-page.tsx";
+import Shares from "@/pages/settings/shares/shares.tsx";
+import ShareLayout from "@/features/share/components/share-layout.tsx";
 import ShareRedirect from "@/pages/share/share-redirect.tsx";
-
+import { useTrackOrigin } from "@/hooks/use-track-origin";
-// Heavy / leaf pages are route-split with React.lazy so their code (most
+import SpacesPage from "@/pages/spaces/spaces.tsx";
-// importantly the whole TipTap editor + KaTeX + lowlight grammars + drawio that
+import SpaceTrash from "@/pages/space/space-trash.tsx";
-// the page editor and the readonly share editor pull in) is fetched only when
+import FavoritesPage from "@/pages/favorites/favorites-page";
-// the matching route is actually visited. The <Suspense> boundaries live inside
+import LabelPage from "@/pages/label/label-page";
-// each Layout (around its <Outlet/>), so the app shell stays mounted while a
-// route chunk loads.
-const Home = lazy(() => import("@/pages/dashboard/home"));
-const Page = lazy(() => import("@/pages/page/page"));
-const SpaceHome = lazy(() => import("@/pages/space/space-home.tsx"));
-const SpaceTrash = lazy(() => import("@/pages/space/space-trash.tsx"));
-const SpacesPage = lazy(() => import("@/pages/spaces/spaces.tsx"));
-const FavoritesPage = lazy(() => import("@/pages/favorites/favorites-page"));
-const LabelPage = lazy(() => import("@/pages/label/label-page"));
-const SharedPage = lazy(() => import("@/pages/share/shared-page.tsx"));
-
-const AccountSettings = lazy(
-  () => import("@/pages/settings/account/account-settings"),
-);
-const AccountPreferences = lazy(
-  () => import("@/pages/settings/account/account-preferences.tsx"),
-);
-const WorkspaceSettings = lazy(
-  () => import("@/pages/settings/workspace/workspace-settings"),
-);
-const AiSettings = lazy(() => import("@/pages/settings/workspace/ai-settings"));
-const WorkspaceMembers = lazy(
-  () => import("@/pages/settings/workspace/workspace-members"),
-);
-const Groups = lazy(() => import("@/pages/settings/group/groups"));
-const GroupInfo = lazy(() => import("./pages/settings/group/group-info"));
-const Spaces = lazy(() => import("@/pages/settings/space/spaces.tsx"));
-const Shares = lazy(() => import("@/pages/settings/shares/shares.tsx"));
 
 export default function App() {
   useTrackOrigin();
 
   return (
-    <Suspense
+    <>
-      fallback={
-        <Center h="100vh">
-          <Loader size="sm" />
-        </Center>
-      }
-    >
       <Routes>
         <Route index element={<Navigate to="/home" />} />
         <Route path={"/login"} element={<LoginPage />} />
@@ -117,6 +83,6 @@ export default function App() {
 
         <Route path="*" element={<Error404 />} />
       </Routes>
-    </Suspense>
+    </>
   );
 }

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -1,37 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { isChunkLoadError } from "./chunk-load-error-boundary";
-
-// The detector decides whether a caught render error is a stale-deploy chunk-404
-// (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
-// recovery UI, no reload). A false negative on a real chunk failure re-blanks the
-// app; a false positive would auto-reload on an ordinary error. Pin both sides.
-describe("isChunkLoadError", () => {
-  it("detects the ChunkLoadError name", () => {
-    expect(isChunkLoadError({ name: "ChunkLoadError", message: "x" })).toBe(true);
-  });
-
-  it.each([
-    "Failed to fetch dynamically imported module: https://x/assets/index-abc.js",
-    "error loading dynamically imported module",
-    "Importing a module script failed.",
-  ])("detects the dynamic-import failure message %#", (message) => {
-    expect(isChunkLoadError({ name: "TypeError", message })).toBe(true);
-  });
-
-  it("is case-insensitive on the message", () => {
-    expect(
-      isChunkLoadError({ message: "FAILED TO FETCH DYNAMICALLY IMPORTED MODULE" }),
-    ).toBe(true);
-  });
-
-  it.each([
-    null,
-    undefined,
-    {},
-    { name: "TypeError", message: "Cannot read properties of undefined" },
-    { message: "Network request failed" },
-    new Error("some ordinary render error"),
-  ])("returns false for a non-chunk error %#", (err) => {
-    expect(isChunkLoadError(err)).toBe(false);
-  });
-});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -1,71 +0,0 @@
-import { ReactNode } from "react";
-import { ErrorBoundary } from "react-error-boundary";
-import { Button, Center, Stack, Text } from "@mantine/core";
-
-const RELOAD_FLAG = "chunk-reload-attempted";
-
-// Heuristic detection of a failed dynamic import. Since the code-splitting work,
-// every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
-// replaces the hashed chunks, a tab left open on the old index.html requests a
-// chunk URL that now 404s, and React.lazy rejects. Browsers / Vite surface these
-// with a ChunkLoadError name or one of these messages.
-export function isChunkLoadError(error: unknown): boolean {
-  if (!error) return false;
-  const name = (error as { name?: string }).name ?? "";
-  const message = (error as { message?: string }).message ?? "";
-  return (
-    name === "ChunkLoadError" ||
-    /Failed to fetch dynamically imported module/i.test(message) ||
-    /error loading dynamically imported module/i.test(message) ||
-    /Importing a module script failed/i.test(message)
-  );
-}
-
-function handleError(error: unknown) {
-  if (!isChunkLoadError(error)) return;
-  // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
-  // the new chunk manifest. Auto-reload once, guarding against a reload loop
-  // (e.g. a genuinely missing chunk) with a one-shot sessionStorage flag. If the
-  // flag is already set we fall through to the manual recovery UI below.
-  try {
-    if (sessionStorage.getItem(RELOAD_FLAG)) return;
-    sessionStorage.setItem(RELOAD_FLAG, "1");
-  } catch {
-    // sessionStorage unavailable (private mode / disabled): skip the automatic
-    // reload rather than risk an unguarded loop; the fallback UI still recovers.
-    return;
-  }
-  window.location.reload();
-}
-
-// Root-level boundary that sits ABOVE every route-level Suspense boundary so a
-// lazy route/component chunk failure is caught here instead of unmounting the
-// whole tree into a blank white screen. Per-feature ErrorBoundaries (page.tsx,
-// transclusion, page-embed) remain in place underneath for their local errors.
-export function ChunkLoadErrorBoundary({ children }: { children: ReactNode }) {
-  return (
-    <ErrorBoundary
-      onError={handleError}
-      fallbackRender={({ error }) => {
-        const chunk = isChunkLoadError(error);
-        return (
-          <Center h="100vh" p="md">
-            <Stack align="center" gap="sm" maw={420}>
-              <Text fw={600}>
-                {chunk ? "A new version is available" : "Something went wrong"}
-              </Text>
-              <Text size="sm" c="dimmed" ta="center">
-                {chunk
-                  ? "Please reload the page to load the latest version."
-                  : "An unexpected error occurred. Reloading the page may help."}
-              </Text>
-              <Button onClick={() => window.location.reload()}>Reload</Button>
-            </Stack>
-          </Center>
-        );
-      }}
-    >
-      {children}
-    </ErrorBoundary>
-  );
-}

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -1,10 +1,9 @@
 import { AppShell, Container } from "@mantine/core";
-import React, { Suspense, useEffect, useRef, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
-import { useAtom, useAtomValue } from "jotai";
+import { useAtom } from "jotai";
-import { aiChatWindowOpenAtom } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
 import {
   APP_NAVBAR_ID,
   NAVBAR_COLLAPSE_BREAKPOINT,
@@ -15,6 +14,8 @@ import {
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 import { SpaceSidebar } from "@/features/space/components/sidebar/space-sidebar.tsx";
 import { AppHeader } from "@/components/layouts/global/app-header.tsx";
+import Aside from "@/components/layouts/global/aside.tsx";
+import AiChatWindow from "@/features/ai-chat/components/ai-chat-window.tsx";
 import GitmostGlobalBridge from "@/features/editor/gitmost/gitmost-global-bridge.tsx";
 import classes from "./app-shell.module.css";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
@@ -22,21 +23,6 @@ import GlobalSidebar from "@/components/layouts/global/global-sidebar.tsx";
 import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
 import { MAIN_CONTENT_ID, SkipToMain } from "@/components/ui/skip-to-main.tsx";
 
-// Lazily load the AI chat window so the AI SDK runtime it pulls in is fetched
-// only after the user first opens the chat, instead of for every authenticated
-// user on load. The window itself renders null while closed, so there is no
-// behavior difference — it simply is not mounted until first opened.
-const AiChatWindow = React.lazy(
-  () => import("@/features/ai-chat/components/ai-chat-window.tsx"),
-);
-
-// The right aside hosts the comment panel and table of contents, both of which
-// pull in TipTap. It only ever renders on page routes, so lazy-loading it keeps
-// the whole editor engine out of the eager global-shell startup graph.
-const Aside = React.lazy(
-  () => import("@/components/layouts/global/aside.tsx"),
-);
-
 export default function GlobalAppShell({
   children,
 }: {
@@ -51,15 +37,6 @@ export default function GlobalAppShell({
   const [isResizing, setIsResizing] = useState(false);
   const sidebarRef = useRef(null);
 
-  // Latch: once the AI chat window has been opened, keep it mounted so an
-  // in-flight stream is never torn down. Before the first open the AI chat chunk
-  // is never fetched.
-  const aiChatOpen = useAtomValue(aiChatWindowOpenAtom);
-  const [aiChatEverOpened, setAiChatEverOpened] = useState(false);
-  useEffect(() => {
-    if (aiChatOpen) setAiChatEverOpened(true);
-  }, [aiChatOpen]);
-
   const startResizing = React.useCallback((mouseDownEvent) => {
     mouseDownEvent.preventDefault();
     setIsResizing(true);
@@ -90,20 +67,14 @@ export default function GlobalAppShell({
   );
 
   useEffect(() => {
-    // Attach the global mousemove/mouseup only WHILE resizing (started on the
+    //https://codesandbox.io/p/sandbox/kz9de
-    // handle's mousedown via startResizing → isResizing=true) and detach on
-    // mouseup (stopResizing → isResizing=false). Previously these listeners were
-    // attached for the whole app lifetime, so every mouse move over the app ran
-    // the resize handler.
-    // https://codesandbox.io/p/sandbox/kz9de
-    if (!isResizing) return;
     window.addEventListener("mousemove", resize);
     window.addEventListener("mouseup", stopResizing);
     return () => {
       window.removeEventListener("mousemove", resize);
       window.removeEventListener("mouseup", stopResizing);
     };
-  }, [isResizing, resize, stopResizing]);
+  }, [resize, stopResizing]);
 
   const location = useLocation();
   const isSettingsRoute = location.pathname.startsWith("/settings");
@@ -189,21 +160,13 @@ export default function GlobalAppShell({
                   : undefined
           }
         >
-          <Suspense fallback={null}>
           <Aside />
-          </Suspense>
         </AppShell.Aside>
       )}
     </AppShell>
-    {/* Floating AI chat window. Mounted once globally on first open; it is
+    {/* Floating AI chat window. Mounted once globally; it is position: fixed
-        position: fixed and self-hides when closed, so its place in the tree is
+        and self-hides when closed, so its place in the tree is not critical. */}
-        not critical. Kept mounted after the first open so a live stream is not
-        aborted. */}
-    {aiChatEverOpened && (
-      <Suspense fallback={null}>
     <AiChatWindow />
-      </Suspense>
-    )}
       {/* Global gitmost native bridge: registers listSpaces / listPages /
           createPageWithRecording on window.gitmost so the native host can
           create a page with a recording even when no page editor is open. */}

apps/client/src/components/layouts/global/layout.tsx

@@ -1,7 +1,5 @@
-import { Suspense, useEffect } from "react";
 import { UserProvider } from "@/features/user/user-provider.tsx";
 import { Outlet, useParams } from "react-router-dom";
-import { Center, Loader } from "@mantine/core";
 import GlobalAppShell from "@/components/layouts/global/global-app-shell.tsx";
 import { SearchSpotlight } from "@/features/search/components/search-spotlight.tsx";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -10,39 +8,10 @@ export default function Layout() {
   const { spaceSlug } = useParams();
   const { data: space } = useGetSpaceBySlugQuery(spaceSlug);
 
-  // Warm the (now route-split) editor chunk during idle time on authenticated
-  // routes, so the first navigation to a page renders from cache instead of a
-  // cold chunk fetch. Best-effort: gated on requestIdleCallback and never blocks
-  // startup — the dynamic import mirrors the App.tsx route lazy loader so both
-  // resolve to the same chunk.
-  useEffect(() => {
-    const ric =
-      typeof window !== "undefined" && (window as any).requestIdleCallback;
-    const warm = () => {
-      // Best-effort prefetch: a failed warm-up (offline, stale 404) is harmless
-      // and must not surface as an unhandledrejection.
-      void import("@/pages/page/page").catch(() => {});
-    };
-    if (ric) {
-      const id = ric(warm);
-      return () => (window as any).cancelIdleCallback?.(id);
-    }
-    const timer = setTimeout(warm, 2000);
-    return () => clearTimeout(timer);
-  }, []);
-
   return (
     <UserProvider>
       <GlobalAppShell>
-        <Suspense
-          fallback={
-            <Center h="60vh">
-              <Loader size="sm" />
-            </Center>
-          }
-        >
         <Outlet />
-        </Suspense>
       </GlobalAppShell>
       <SearchSpotlight spaceId={space?.id} />
     </UserProvider>

apps/client/src/components/ui/emoji-picker.tsx

@@ -5,7 +5,7 @@ import {
   Button,
   useMantineColorScheme,
 } from "@mantine/core";
-import { useClickOutside, useDisclosure } from "@mantine/hooks";
+import { useClickOutside, useDisclosure, useWindowEvent } from "@mantine/hooks";
 import { Suspense } from "react";
 import { useTranslation } from "react-i18next";
 
@@ -57,22 +57,14 @@ function EmojiPicker({
     [dropdown, target],
   );
 
-  // We need this because the default Mantine popover closeOnEscape does not work.
+  // We need this because the default Mantine popover closeOnEscape does not work
-  // Attach the global keydown ONLY while the picker is open (every tree row
+  useWindowEvent("keydown", (event) => {
-  // renders an EmojiPicker, so an always-on window listener meant ~20-30 idle
+    if (opened && event.key === "Escape") {
-  // keydown handlers firing on each keystroke).
-  useEffect(() => {
-    if (!opened) return;
-    const handleKeydown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") {
       event.stopPropagation();
       event.preventDefault();
       handlers.close();
     }
-    };
+  });
-    window.addEventListener("keydown", handleKeydown);
-    return () => window.removeEventListener("keydown", handleKeydown);
-  }, [opened, handlers]);
 
   // emoji-mart's built-in autoFocus calls .focus() without preventScroll, which
   // makes the browser scroll every scrollable ancestor of the search input to

apps/client/src/components/ui/git-sync-badge.tsx

@@ -0,0 +1,37 @@
+import { Badge, Tooltip } from "@mantine/core";
+import { IconGitMerge } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+
+interface GitSyncBadgeProps {
+  authorName?: string;
+}
+
+/**
+ * Badge marking a version produced by git-sync (provenance §8.1). The history
+ * version is created on the PUSH path — when an incoming git body is written back
+ * into the Docmost doc — not by the pull itself. Like {@link AiAgentBadge} it is
+ * ADDITIVE — shown next to the human author, never replacing them — but a git-sync
+ * edit is NOT an agent edit and has no chat to deep-link into, so it is a small,
+ * neutral, non-clickable label.
+ */
+export function GitSyncBadge({ authorName }: GitSyncBadgeProps) {
+  const { t } = useTranslation();
+
+  const tooltip = t("Synced from Git on behalf of {{name}}", {
+    name: authorName ?? "",
+  });
+
+  return (
+    <Tooltip label={tooltip} withArrow>
+      <Badge
+        size="sm"
+        variant="light"
+        color="gray"
+        radius="sm"
+        leftSection={<IconGitMerge size={12} stroke={2} />}
+      >
+        {t("Git sync")}
+      </Badge>
+    </Tooltip>
+  );
+}

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

@@ -36,23 +36,22 @@ import {
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
-import {
-  pageEditorAtom,
-  readOnlyEditorAtom,
-} from "@/features/editor/atoms/editor-atoms.ts";
-import {
-  getEditorSelectionContext,
-  type EditorSelectionContext,
-} from "@/features/editor/utils/get-editor-selection.ts";
 import { extractPageSlugId } from "@/lib";
 import {
   AI_CHATS_RQ_KEY,
   AI_CHAT_MESSAGES_RQ_KEY,
+  AI_CHAT_RUN_RQ_KEY,
   useAiChatMessagesQuery,
+  useAiChatRunQuery,
   useAiChatsQuery,
   useAiRolesQuery,
 } from "@/features/ai-chat/queries/ai-chat-query.ts";
+import {
+  shouldClearLatchOnQueryError,
+  shouldClearStoppingLatch,
+  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";
@@ -86,20 +85,6 @@ const MIN_HEIGHT = 400;
 // Margin kept between the window and the viewport edges while dragging.
 const EDGE_MARGIN = 8;
 
-// #184 phase 1.5 / #430: backstop for the degraded-poll fallback. The poll is
-// armed when a resume attempt could not attach to the live run and disarmed by the
-// thread on settle / local stream; this cap is the ONLY backstop against an endless
-// tick (a stuck 'streaming' row before the boot-sweep, or a user-tail 204 with no
-// run).
-//
-// #430: measured from RUN ACTIVITY, not from arm-time. A real autonomous run takes
-// 11-25 min — longer than a fixed 10-min-from-start cap, which used to cut the poll
-// off mid-run. Instead we cap on INACTIVITY: keep polling as long as the run is
-// still making progress (its persisted rows keep changing), and only give up after
-// this long with NO new activity. A genuinely stuck run produces no row changes, so
-// the idle cap still bounds it; a long-but-progressing run polls to completion.
-const DEGRADED_POLL_IDLE_MAX_MS = 10 * 60_000;
-
 /** Compact token formatter: 1.2M / 3.4k / 950. */
 function formatTokens(n: number): string {
   if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
@@ -245,9 +230,7 @@ export default function AiChatWindow() {
   // left partly off-screen).
   const [geom, setGeom] = useAtom(aiChatWindowGeomAtom);
 
-  // Gated on windowOpen: the chat list is only needed once the window is open,
+  const { data: chats } = useAiChatsQuery();
-  // so a closed window issues no chat-list request/refetch on navigation.
-  const { data: chats } = useAiChatsQuery(windowOpen);
   // Roles for the new-chat picker (any member may list them). Only fetched while
   // the window is open.
   const { data: roles } = useAiRolesQuery(windowOpen);
@@ -259,79 +242,150 @@ export default function AiChatWindow() {
     [roles],
   );
 
-  // #184 phase 1.5: degraded-poll fallback (replaces the F4/F5/F7 latches). When
-  // ChatThread could not attach to a still-running run it arms this via
-  // onResumeFallback(true); the thread disarms it on settle / local stream. The
-  // window only OWNS the timer (armedAtRef stamps when it was armed for the cap).
-  const [degradedPoll, setDegradedPoll] = useState(false);
-  // #430: timestamp of the LAST run activity while the poll is armed — stamped on
-  // arm and re-stamped whenever the polled rows change (see the effect below). The
-  // idle cap is measured from this, so a long-but-progressing run keeps polling.
-  const lastActivityAtRef = useRef(0);
-  const onResumeFallback = useCallback((active: boolean): void => {
-    if (active) lastActivityAtRef.current = Date.now();
-    setDegradedPoll(active);
-  }, []);
-  // Reset the degraded poll whenever the open chat changes: it is scoped to the
-  // resume attempt of the previously-open chat (invariant 8).
-  useEffect(() => {
-    setDegradedPoll(false);
-  }, [activeChatId]);
-
   const { data: messageRows, isLoading: messagesLoading } =
-    useAiChatMessagesQuery(
+    useAiChatMessagesQuery(activeChatId ?? undefined);
-      activeChatId ?? undefined,
-      // DELIBERATELY DUMB (invariant 8 / task 2.4): poll every 2.5s while armed
-      // and while the run is still active (#430: under the INACTIVITY cap, not a
-      // fixed-from-start cap); otherwise off. NO error checks (TanStack v5 resets
-      // fetchFailureCount each fetch, so consecutive errors are not expressible —
-      // and the poll must survive a server restart) and NO tail checks (the
-      // settled/local-stream semantics live in ChatThread, which disarms via
-      // onResumeFallback(false)). The idle cap is the only backstop.
-      () =>
-        degradedPoll === true &&
-        Date.now() - lastActivityAtRef.current < DEGRADED_POLL_IDLE_MAX_MS
-          ? 2500
-          : false,
-      // #344: gate on windowOpen too — no message history is fetched (and no
-      // degraded poll runs) while the window is closed; it loads when the window
-      // opens with an active chat.
-      windowOpen,
-    );
-
-  // #430: re-stamp the activity clock whenever the polled rows change while the
-  // poll is armed. TanStack keeps the same `messageRows` reference across refetches
-  // that return deep-equal data (structural sharing), so a new reference means the
-  // run genuinely progressed — which extends the inactivity cap above. A stuck run
-  // yields no reference change, so the cap eventually fires and stops the poll.
-  useEffect(() => {
-    if (degradedPoll) lastActivityAtRef.current = Date.now();
-  }, [degradedPoll, messageRows]);
 
   // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
-  // this workspace. When the feature is off no runs are ever created, so the
+  // this workspace. The reconnect endpoint itself is NOT flag-gated server-side
-  // resume attempt would only ever 204; gating ChatThread's resume on it avoids a
+  // (it is only owner-gated and returns `{ run: null }` when the chat has no
-  // pointless attach round-trip.
+  // 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);
+  }, []);
+
+  // #184 Stop wiring. While a detached run is being stopped we SUPPRESS the
+  // observer merge so the stopping run's still-persisting output does not
+  // re-stream back into view between the moment the user pressed Stop and the run
+  // actually settling as 'aborted' server-side. Polling itself keeps running (so
+  // the terminal transition is still detected) — only the visual merge is gated.
+  // Cleared when the run is observed terminal (below) or the chat is switched.
+  const [stoppingRun, setStoppingRun] = useState(false);
+  // Reset the stopping latch whenever the open chat changes: it is scoped to the
+  // run of the previously-open chat.
+  useEffect(() => {
+    setStoppingRun(false);
+  }, [activeChatId]);
+
   // Authoritative stop of the open chat's detached run (the Stop button in
-  // autonomous mode). Request the server stop — the ONLY thing that ends a
+  // autonomous mode). Latch "stopping" first (suppresses the re-stream flash),
-  // detached run; a mere local SSE abort is a client disconnect the server
+  // then request the server stop — the ONLY thing that ends a detached run; a mere
-  // ignores. On failure surface the error.
+  // local SSE abort is a client disconnect the server ignores. On failure we
+  // release the latch so the observer resumes (better to show the live run than to
+  // freeze the view) and surface the error.
   const handleServerStop = useCallback(
     (chatId: string): void => {
+      setStoppingRun(true);
+      // #234 F4: drop the PREVIOUS turn's run from the cache so `run` becomes null
+      // until the CURRENT turn's run is fetched fresh. Without this, once the local
+      // stream aborts (localStreaming -> false) the run query re-enables and
+      // react-query SYNCHRONOUSLY returns the still-cached prior terminal run; the
+      // terminal effect would then clear the stopping latch against that STALE run
+      // before the current turn's (still-running, detached, growing) run is ever
+      // observed — re-opening the observer merge and flashing the growing output
+      // over the frozen row. With the cache cleared the terminal effect's
+      // `if (!run) return` holds the latch until the current run itself is observed
+      // terminal (see shouldClearStoppingLatch).
+      queryClient.removeQueries({ queryKey: AI_CHAT_RUN_RQ_KEY(chatId) });
       void stopRun(chatId).catch(() => {
+        setStoppingRun(false);
         notifications.show({
           message: t("Failed to stop the run"),
           color: "red",
         });
       });
     },
-    [t],
+    [t, queryClient],
   );
 
+  // 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, isError: runQueryFailed } = useAiChatRunQuery(
+    activeChatId ?? undefined,
+    autonomousRunsEnabled && !localStreaming,
+  );
+  const run = runData?.run ?? null;
+
+  // Safety net (#234 F4 review): after handleServerStop clears the run cache,
+  // `run` is null until the current turn's run is fetched fresh, and the terminal
+  // effect below holds the latch via `if (!run) return`. If that refetch instead
+  // ERRORS PERMANENTLY (the GET-run keeps failing) while we are no longer the
+  // streamer, the run stays null, its status-keyed refetchInterval is off, and
+  // nothing would ever observe a terminal run — freezing the view with the
+  // observer merge suppressed. Release the latch on that error so the live view
+  // resumes rather than stays stuck (the local stopRun may already have succeeded
+  // independently).
+  //
+  // #234 F7: this must NOT fire on a TRANSIENT error while `run` is still an
+  // ACTIVE held run. In TanStack Query v5 (retry:false) the query's `data` is
+  // RETAINED on error, so `runQueryFailed` can be true while `run` is still
+  // pending/running — releasing then would re-open the observer merge and flash
+  // the growing detached run over the frozen row (the very flash F4 prevents). The
+  // decision is the pure, unit-tested `shouldClearLatchOnQueryError`, which gates
+  // on the run NOT being active: it cures only the genuine permanent-null-freeze
+  // (`run === null`) and never releases against an active run.
+  useEffect(() => {
+    if (
+      shouldClearLatchOnQueryError({
+        stoppingRun,
+        isLocalStreaming: localStreaming,
+        runQueryFailed,
+        run,
+      })
+    )
+      setStoppingRun(false);
+  }, [stoppingRun, localStreaming, runQueryFailed, run]);
+  // 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) && !stoppingRun
+      ? (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;
+    }
+    // Terminal: a stop we requested has landed (or the run finished on its own),
+    // so release the stopping latch — the observer merge can now show the final
+    // persisted (aborted/finished) output without any live re-stream. The decision
+    // is the pure, unit-tested `shouldClearStoppingLatch` (run-polling.ts): release
+    // ONLY when we requested a stop, this tab is no longer the streamer, AND the
+    // CURRENT run is terminal. The #234 F4 cache removal in handleServerStop makes
+    // `run` null (this branch's `if (!run) return` above holds) until the current
+    // turn's run is fetched fresh, so the latch can never clear against a stale
+    // cached run.
+    if (shouldClearStoppingLatch({ stoppingRun, run, isLocalStreaming: localStreaming }))
+      setStoppingRun(false);
+    if (finalizedRunIdRef.current === run.id) return;
+    finalizedRunIdRef.current = run.id;
+    queryClient.invalidateQueries({
+      queryKey: AI_CHAT_MESSAGES_RQ_KEY(activeChatId),
+    });
+  }, [run, activeChatId, queryClient, stoppingRun, localStreaming]);
+
   // 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"
@@ -342,34 +396,13 @@ export default function AiChatWindow() {
   // reads/writes via its CASL-enforced page tools using the id.
   const pageRouteMatch = useMatch("/s/:spaceSlug/p/:pageSlug");
   const pageSlug = pageRouteMatch?.params?.pageSlug;
-  const { data: openPageData } = usePageMetaQuery({
+  const { data: openPageData } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const openPage = openPageData
     ? { id: openPageData.id, title: openPageData.title }
     : null;
 
-  // Live editor handles for the selection snapshot (#388). Both are published by
-  // the page editor; the read-only editor is used in read mode. Reading the
-  // selection off `editor.state` stays valid after the editor blurs (ProseMirror
-  // keeps state.selection), mirroring the comment button (comment-dialog.tsx).
-  const pageEditor = useAtomValue(pageEditorAtom);
-  const readOnlyEditor = useAtomValue(readOnlyEditorAtom);
-
-  // Snapshot the user's current editor selection at send time. Edit-mode editor
-  // wins; the read-only editor is the fallback (read mode). Null when neither
-  // holds a non-empty selection. Passed to <ChatThread>, which reads it live
-  // from a ref inside prepareSendMessagesRequest — so each turn ships a fresh
-  // snapshot and multi-turn works without recreating the transport.
-  const getEditorSelection = useCallback((): EditorSelectionContext | null => {
-    for (const editor of [pageEditor, readOnlyEditor]) {
-      if (!editor || editor.isDestroyed) continue;
-      const sel = getEditorSelectionContext(editor.state);
-      if (sel) return sel;
-    }
-    return null;
-  }, [pageEditor, readOnlyEditor]);
-
   // The AI-chat thread-identity lifecycle (mount key, both new-chat id adoption
   // paths, the history-loaded latch, the render-phase reconciler) lives in this
   // hook. See adopt-chat-id.ts for the canonical #137 two-tab race explanation.
@@ -992,9 +1025,6 @@ export default function AiChatWindow() {
               chatId={activeChatId}
               initialRows={activeChatId ? messageRows : []}
               openPage={openPage}
-              // #388: live snapshotter for the user's editor selection, read at
-              // send time and nested inside openPage on the wire.
-              getEditorSelection={getEditorSelection}
               // Honoured only for a new chat; null = universal assistant.
               roleId={activeChatId === null ? selectedRoleId : null}
               // Role cards are the new-chat empty-state; offered only when this
@@ -1004,13 +1034,16 @@ export default function AiChatWindow() {
               assistantName={currentRole?.name}
               onTurnFinished={onTurnFinished}
               onServerChatId={onServerChatId}
-              // #184 phase 1.5: arm/disarm the degraded-poll fallback when a
+              // #184: live-follow a still-running run when we reopened the chat as
-              // resume attempt could not attach to the live run; the thread
+              // a passive observer; null when there is nothing to observe or this
-              // disarms it on settle / local stream.
+              // tab is the streamer. onStreamingChange lets the window stop polling
-              onResumeFallback={onResumeFallback}
+              // while we are the streamer.
+              observedRow={observedRow}
+              onStreamingChange={onStreamingChange}
               // #184: in autonomous mode the Stop button must hit the authoritative
               // server stop (a local SSE abort is a client disconnect the server
-              // ignores).
+              // ignores). onServerStop also arms the "stopping" latch above so the
+              // stopped run's output does not re-stream via the observer merge.
               autonomousRunsEnabled={autonomousRunsEnabled}
               onServerStop={handleServerStop}
             />

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

@@ -1,13 +1,6 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, vi } from "vitest";
-import {
+import { render, screen, fireEvent, act, cleanup } from "@testing-library/react";
-  render,
-  screen,
-  fireEvent,
-  act,
-  cleanup,
-} from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 // Shared, hoisted mock state so the @ai-sdk/react and "ai" module mocks (hoisted
 // above the imports) can expose the captured useChat callbacks / transport and
@@ -19,61 +12,50 @@ const h = vi.hoisted(() => ({
     sendMessage: vi.fn(),
     stop: vi.fn(),
     setMessages: vi.fn(),
-    resumeStream: vi.fn(),
-    // The messages array useChat was seeded with (to assert strip/seed behavior).
-    seededMessages: null as null | unknown[],
     transport: null as null | {
-      prepareSendMessagesRequest?: (arg: {
+      prepareSendMessagesRequest: (arg: {
         messages: unknown[];
         body: Record<string, unknown>;
       }) => { body: Record<string, unknown> };
-      prepareReconnectToStreamRequest?: () => { api?: string };
-      fetch?: (input: unknown, init?: { method?: string }) => Promise<unknown>;
     },
   },
 }));
 
-// Mock useChat: capture onFinish + seeded messages, return the spies and the
+// Mock useChat: capture onFinish, return the spies and the controllable status.
-// controllable status.
 vi.mock("@ai-sdk/react", () => ({
-  useChat: (opts: {
+  useChat: (opts: { onFinish?: (arg: Record<string, unknown>) => void }) => {
-    messages?: unknown[];
-    onFinish?: (arg: Record<string, unknown>) => void;
-  }) => {
     h.state.onFinish = opts.onFinish ?? null;
-    h.state.seededMessages = opts.messages ?? null;
     return {
       messages: [],
       sendMessage: h.state.sendMessage,
       status: h.state.status,
       stop: h.state.stop,
       error: null,
+      // #184: ChatThread reads setMessages to merge a polled observer run.
       setMessages: h.state.setMessages,
-      resumeStream: h.state.resumeStream,
     };
   },
 }));
 
 // Mock "ai": deterministic ids + a transport that records its options so the test
-// can invoke prepareSendMessagesRequest / prepareReconnectToStreamRequest / fetch.
+// can invoke prepareSendMessagesRequest and assert the `interrupted` flag.
 vi.mock("ai", () => {
   let counter = 0;
   return {
     generateId: () => `gid-${counter++}`,
     DefaultChatTransport: class {
-      constructor(opts: Record<string, unknown>) {
+      constructor(opts: {
-        h.state.transport = opts as never;
+        prepareSendMessagesRequest: (arg: {
+          messages: unknown[];
+          body: Record<string, unknown>;
+        }) => { body: Record<string, unknown> };
+      }) {
+        h.state.transport = opts;
       }
     },
   };
 });
 
-// Keep the ai-chat-query import light: ChatThread only needs the messages RQ key,
-// so stub the module to avoid pulling axios / i18n transitively.
-vi.mock("@/features/ai-chat/queries/ai-chat-query.ts", () => ({
-  AI_CHAT_MESSAGES_RQ_KEY: (chatId: string) => ["ai-chat-messages", chatId],
-}));
-
 // Stub the heavy children: MessageList (markdown/render) and ChatInput (the
 // composer). The ChatInput stub exposes a button that queues a message, the only
 // interaction this test needs to populate the queue while "streaming".
@@ -81,90 +63,49 @@ vi.mock("@/features/ai-chat/components/message-list.tsx", () => ({
   default: () => <div data-testid="message-list" />,
 }));
 vi.mock("@/features/ai-chat/components/chat-input.tsx", () => ({
-  default: ({
+  default: ({ onQueue }: { onQueue: (text: string) => void }) => (
-    onQueue,
-    onStop,
-  }: {
-    onQueue: (text: string) => void;
-    onStop: () => void;
-  }) => (
-    <>
     <button data-testid="queue-btn" onClick={() => onQueue("queued text")}>
       queue
     </button>
-      <button aria-label="Stop" onClick={() => onStop()}>
-        stop
-      </button>
-    </>
   ),
 }));
 
 import ChatThread from "./chat-thread";
-import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
 
-function row(
+function renderThread() {
-  id: string,
-  role: string,
-  status?: string,
-  text = "",
-): IAiChatMessageRow {
-  return { id, role, content: text, status, createdAt: "2026-01-01T00:00:00Z" };
-}
-
-function renderThread(props?: {
-  chatId?: string | null;
-  initialRows?: IAiChatMessageRow[];
-  autonomousRunsEnabled?: boolean;
-}) {
   const onTurnFinished = vi.fn();
-  const onResumeFallback = vi.fn();
+  render(
-  const onServerStop = vi.fn();
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
-  const { unmount } = render(
-    <QueryClientProvider client={queryClient}>
     <MantineProvider>
-        <ChatThread
+      <ChatThread chatId="c1" initialRows={[]} onTurnFinished={onTurnFinished} />
-          chatId={props?.chatId === undefined ? "c1" : props.chatId}
+    </MantineProvider>,
-          initialRows={props?.initialRows ?? []}
-          autonomousRunsEnabled={props?.autonomousRunsEnabled}
-          onTurnFinished={onTurnFinished}
-          onResumeFallback={onResumeFallback}
-          onServerStop={onServerStop}
-        />
-      </MantineProvider>
-    </QueryClientProvider>,
   );
-  return { onTurnFinished, onResumeFallback, onServerStop, invalidateSpy, unmount };
+  return { onTurnFinished };
-}
-
-function resetState() {
-  h.state.status = "streaming";
-  h.state.onFinish = null;
-  h.state.seededMessages = null;
-  h.state.transport = null;
-  h.state.sendMessage.mockClear();
-  h.state.stop.mockClear();
-  h.state.setMessages.mockClear();
-  h.state.resumeStream.mockClear();
 }
 
 describe("ChatThread — send now (#198)", () => {
-  beforeEach(resetState);
+  beforeEach(() => {
+    h.state.status = "streaming";
+    h.state.onFinish = null;
+    h.state.sendMessage.mockClear();
+    h.state.stop.mockClear();
+    h.state.transport = null;
+  });
 
   it("aborts the current turn and resends the queued message on the abort", () => {
     renderThread();
 
+    // Queue a message while the turn is streaming.
     fireEvent.click(screen.getByTestId("queue-btn"));
     const sendNowBtn = screen.getByLabelText("Send now");
     expect(sendNowBtn).toBeTruthy();
 
+    // "Send now" interrupts the current turn (stop), but does NOT send yet —
+    // the resend happens once the abort lands in onFinish.
     fireEvent.click(sendNowBtn);
     expect(h.state.stop).toHaveBeenCalledTimes(1);
     expect(h.state.sendMessage).not.toHaveBeenCalled();
 
+    // The abort we triggered reaches onFinish: the promoted head is flushed.
     act(() => {
       h.state.onFinish?.({
         message: { id: "a", role: "assistant", parts: [] },
@@ -181,8 +122,10 @@ describe("ChatThread — send now (#198)", () => {
     fireEvent.click(screen.getByTestId("queue-btn"));
     fireEvent.click(screen.getByLabelText("Send now"));
 
-    const prep = h.state.transport!.prepareSendMessagesRequest!;
+    const prep = h.state.transport!.prepareSendMessagesRequest;
+    // The send right after "send now" carries interrupted: true...
     expect(prep({ messages: [], body: {} }).body.interrupted).toBe(true);
+    // ...and only that one (the flag is read-and-cleared).
     expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
   });
 
@@ -193,92 +136,42 @@ describe("ChatThread — send now (#198)", () => {
     fireEvent.click(screen.getByTestId("queue-btn"));
     fireEvent.click(screen.getByLabelText("Send now"));
 
+    // No turn to interrupt: sent straight away, no abort, not flagged.
     expect(h.state.stop).not.toHaveBeenCalled();
     expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
-    const prep = h.state.transport!.prepareSendMessagesRequest!;
+    const prep = h.state.transport!.prepareSendMessagesRequest;
     expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
   });
 });
 
-// #388: the editor selection is snapshotted at send time and nested inside
+// The turn-end decision lives in the `onFinish` handler: given the terminal
-// openPage on the wire. The getter is read live from a ref, so each send ships a
+// outcome of a turn (`isAbort` / `isDisconnect` / `isError`, or none = clean),
-// fresh snapshot.
+// it decides whether to CONTINUE (flush the next queued message) or END (leave
-describe("ChatThread — editor selection wiring (#388)", () => {
+// the queue intact for the user), and which stop notice — if any — to show.
-  beforeEach(resetState);
+// `sendNow` is exercised above; these tests pin down the plain outcomes.
-  afterEach(cleanup);
-
-  function renderWithSelection(props: {
-    openPage?: { id: string; title: string } | null;
-    getEditorSelection?: () => unknown;
-  }) {
-    const queryClient = new QueryClient({
-      defaultOptions: { queries: { retry: false } },
-    });
-    render(
-      <QueryClientProvider client={queryClient}>
-        <MantineProvider>
-          <ChatThread
-            chatId="c1"
-            initialRows={[]}
-            openPage={props.openPage as never}
-            getEditorSelection={props.getEditorSelection as never}
-            onTurnFinished={vi.fn()}
-            onResumeFallback={vi.fn()}
-            onServerStop={vi.fn()}
-          />
-        </MantineProvider>
-      </QueryClientProvider>,
-    );
-  }
-
-  it("nests the snapshot from the getter into openPage.selection at send time", () => {
-    const selection = { text: "fix this", blockIds: ["b1"], before: "a " };
-    renderWithSelection({
-      openPage: { id: "p1", title: "Doc" },
-      getEditorSelection: () => selection,
-    });
-    const prep = h.state.transport!.prepareSendMessagesRequest!;
-    const openPage = prep({ messages: [], body: {} }).body.openPage as Record<
-      string,
-      unknown
-    >;
-    expect(openPage).toEqual({ id: "p1", title: "Doc", selection });
-  });
-
-  it("sends selection: null when the getter returns null", () => {
-    renderWithSelection({
-      openPage: { id: "p1", title: "Doc" },
-      getEditorSelection: () => null,
-    });
-    const prep = h.state.transport!.prepareSendMessagesRequest!;
-    const openPage = prep({ messages: [], body: {} }).body.openPage as Record<
-      string,
-      unknown
-    >;
-    expect(openPage).toEqual({ id: "p1", title: "Doc", selection: null });
-  });
-
-  it("does not send selection at all on a non-page route (openPage null)", () => {
-    const getter = vi.fn(() => ({ text: "sel" }));
-    renderWithSelection({ openPage: null, getEditorSelection: getter });
-    const prep = h.state.transport!.prepareSendMessagesRequest!;
-    expect(prep({ messages: [], body: {} }).body.openPage).toBeNull();
-    // The getter must not even be consulted when there is no page.
-    expect(getter).not.toHaveBeenCalled();
-  });
-});
-
 describe("ChatThread — turn-end decision (onFinish)", () => {
-  beforeEach(resetState);
+  beforeEach(() => {
+    h.state.status = "streaming";
+    h.state.onFinish = null;
+    h.state.sendMessage.mockClear();
+    h.state.stop.mockClear();
+    h.state.transport = null;
+  });
 
+  // Drive a fresh onFinish with the given terminal flags after queueing a
+  // message, and report both what the parent was told and whether the queue was
+  // flushed (a resend to the sendMessage spy).
   function finishWith(flags: {
     isAbort?: boolean;
     isDisconnect?: boolean;
     isError?: boolean;
   }) {
+    // Tear down any prior render so the loop-driven "every outcome" case does
+    // not leave duplicate queue buttons in the DOM.
     cleanup();
     h.state.sendMessage.mockClear();
     const { onTurnFinished } = renderThread();
+    // Populate the queue while the turn is streaming.
     fireEvent.click(screen.getByTestId("queue-btn"));
     act(() => {
       h.state.onFinish?.({
@@ -294,12 +187,16 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
 
   it("CONTINUES — flushes the next queued message on a clean finish", () => {
     finishWith({});
+    // Clean finish (no terminal flag): the queued message is auto-sent.
     expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
+    // A clean finish shows no stop notice.
     expect(screen.queryByText("Response stopped.")).toBeNull();
   });
 
   it("ENDS — keeps the queue intact on a user abort and shows the stopped notice", () => {
     finishWith({ isAbort: true });
+    // A plain Stop (not the sendNow interrupt path) must NOT auto-resend: the
+    // queue is preserved for the user to decide.
     expect(h.state.sendMessage).not.toHaveBeenCalled();
     expect(screen.getByText("Response stopped.")).toBeTruthy();
   });
@@ -314,11 +211,15 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
 
   it("ENDS — keeps the queue intact on a stream error (no auto-retry, no stopped notice)", () => {
     finishWith({ isError: true });
+    // Blindly retrying after a failure would be wrong; the queue is left alone.
     expect(h.state.sendMessage).not.toHaveBeenCalled();
+    // isError clears the neutral notice (the error banner covers this case).
     expect(screen.queryByText("Response stopped.")).toBeNull();
   });
 
   it("notifies the parent on EVERY terminal outcome", () => {
+    // The chat-list refresh / new-chat id adoption must run on success and on
+    // every failure path alike.
     for (const flags of [
       {},
       { isAbort: true },
@@ -331,578 +232,55 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
   });
 });
 
-// #184 phase 1.5: the resumable-SSE client. A reopened tab resumes the live run
+// #184 passive-observer merge: when reconnecting to a still-running run, the
-// via the SDK's reconnect transport (attach: replay + tail) instead of polling.
+// parent feeds the polled run message via `observedRow`; ChatThread merges it via
-describe("ChatThread — resume (attach) machinery (#184)", () => {
+// setMessages — but ONLY when this tab is NOT itself streaming (the streamer's
-  const streamingTail = () => [
+// SSE owns the view, so a stale observedRow must never overwrite it).
-    row("u1", "user", undefined, "hi"),
+describe("ChatThread — observer run merge (#184)", () => {
-    row("a1", "assistant", "streaming", "partial"),
+  beforeEach(() => {
-  ];
+    h.state.onFinish = null;
-  const settledTail = () => [
+    h.state.setMessages.mockReset();
-    row("u1", "user", undefined, "hi"),
+  });
-    row("a1", "assistant", "succeeded", "done"),
-  ];
-  const userTail = () => [row("u1", "user", undefined, "hi")];
 
-  const visibleMsg = {
+  const observedRow = {
-    id: "a1",
+    id: "a-run",
     role: "assistant",
-    parts: [{ type: "text", text: "streamed answer" }],
+    content: "step 1\nstep 2",
-  };
+    metadata: {
-  const emptyMsg = { id: "a1", role: "assistant", parts: [] };
+      parts: [{ type: "text", text: "step 1\nstep 2" }],
+    },
+    createdAt: "2026-01-01T00:00:00Z",
+  } as const;
 
-  beforeEach(resetState);
+  function renderObserver(status: string) {
-  // NOTE: do NOT vi.unstubAllGlobals() here — vitest.setup.ts installs
+    h.state.status = status;
-  // matchMedia/localStorage via vi.stubGlobal and unstubbing wipes them for the
+    render(
-  // rest of the file. Fetch is re-stubbed per test that needs it.
-  afterEach(cleanup);
-
-  it("resumes on mount only when the flag is on, chatId is set, and the tail is not a settled assistant", () => {
-    // streaming tail -> resume
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-
-    // user tail -> resume (the assistant row may not be seeded yet)
-    cleanup();
-    h.state.resumeStream.mockClear();
-    renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-
-    // settled assistant tail -> NO resume
-    cleanup();
-    h.state.resumeStream.mockClear();
-    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
-
-    // flag off -> NO resume
-    cleanup();
-    h.state.resumeStream.mockClear();
-    renderThread({ autonomousRunsEnabled: false, initialRows: streamingTail() });
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
-
-    // no chatId -> NO resume
-    cleanup();
-    h.state.resumeStream.mockClear();
-    renderThread({
-      autonomousRunsEnabled: true,
-      chatId: null,
-      initialRows: streamingTail(),
-    });
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
-  });
-
-  it("strips the streaming tail from the seed, but keeps a user tail whole", () => {
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    // 2 rows in, streaming tail stripped -> 1 seeded message.
-    expect(h.state.seededMessages).toHaveLength(1);
-
-    cleanup();
-    renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
-    // user tail is not stripped.
-    expect(h.state.seededMessages).toHaveLength(1);
-  });
-
-  it("builds the attach URL with expect=live&anchor only when the streaming tail was stripped", () => {
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream?expect=live&anchor=a1",
-    );
-
-    cleanup();
-    renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream",
-    );
-  });
-
-  async function fetch204() {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 204, ok: false }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-  }
-
-  it("204 on a user tail: no crash, no restore, reconcile+invalidate, onResumeFallback(true)", async () => {
-    const { onResumeFallback, invalidateSpy } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: userTail(),
-    });
-    await fetch204();
-    // No stripped row -> no restore merge.
-    expect(h.state.setMessages).not.toHaveBeenCalled();
-    expect(invalidateSpy).toHaveBeenCalledWith({
-      queryKey: ["ai-chat-messages", "c1"],
-    });
-    expect(onResumeFallback).toHaveBeenCalledWith(true);
-  });
-
-  it("204 on a streaming tail: restore + invalidate + onResumeFallback(true)", async () => {
-    const { onResumeFallback, invalidateSpy } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    await fetch204();
-    // Stripped row is restored to the store.
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-    expect(invalidateSpy).toHaveBeenCalledWith({
-      queryKey: ["ai-chat-messages", "c1"],
-    });
-    expect(onResumeFallback).toHaveBeenCalledWith(true);
-  });
-
-  it("F7 restart-survival: a 500 attach failure restores the stripped row AND arms the poll (not lost)", async () => {
-    const { onResumeFallback, invalidateSpy } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 500, ok: false }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1); // stripped row restored
-    expect(invalidateSpy).toHaveBeenCalledWith({
-      queryKey: ["ai-chat-messages", "c1"],
-    });
-    expect(onResumeFallback).toHaveBeenCalledWith(true); // degraded poll armed
-  });
-
-  it("F7 restart-survival: a network throw restores the stripped row AND arms the poll", async () => {
-    const { onResumeFallback, invalidateSpy } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockRejectedValue(new Error("network down")),
-    );
-    await act(async () => {
-      await h.state
-        .transport!.fetch!("http://x", { method: "GET" })
-        .catch(() => undefined); // the wrapper rethrows; swallow here
-    });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-    expect(invalidateSpy).toHaveBeenCalledWith({
-      queryKey: ["ai-chat-messages", "c1"],
-    });
-    expect(onResumeFallback).toHaveBeenCalledWith(true);
-  });
-
-  it("unmount during a pending attach aborts the controller and gates late callbacks", async () => {
-    const { onResumeFallback, invalidateSpy, unmount } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    let abortSeen = false;
-    let resolveFetch!: (v: unknown) => void;
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockImplementation((_input: unknown, init: RequestInit) => {
-        init.signal?.addEventListener("abort", () => {
-          abortSeen = true;
-        });
-        return new Promise((res) => {
-          resolveFetch = res;
-        });
-      }),
-    );
-    // Kick a reconnect GET (stays pending).
-    let pending!: Promise<unknown>;
-    act(() => {
-      pending = h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-    // Unmount: the cleanup aborts the in-flight attach.
-    unmount();
-    expect(abortSeen).toBe(true);
-    // A late 204 landing after unmount must NOT arm a poll / invalidate the (now
-    // different) chat.
-    onResumeFallback.mockClear();
-    invalidateSpy.mockClear();
-    await act(async () => {
-      resolveFetch({ status: 204, ok: false });
-      await pending;
-    });
-    expect(onResumeFallback).not.toHaveBeenCalledWith(true);
-    expect(invalidateSpy).not.toHaveBeenCalled();
-  });
-
-  it("a resume fetch error clears resumedTurn so the next local turn flushes the queue", async () => {
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    h.state.status = "ready";
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 500, ok: false }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-    // Queue then clean-finish: suppression was cleared, so the queue flushes.
-    fireEvent.click(screen.getByTestId("queue-btn"));
-    act(() => {
-      h.state.onFinish?.({
-        message: visibleMsg,
-        isAbort: false,
-        isDisconnect: false,
-        isError: false,
-      });
-    });
-    expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
-  });
-
-  it("a resumed turn's onFinish does NOT flush the queue", () => {
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    fireEvent.click(screen.getByTestId("queue-btn"));
-    act(() => {
-      h.state.onFinish?.({
-        message: visibleMsg,
-        isAbort: false,
-        isDisconnect: false,
-        isError: false,
-      });
-    });
-    expect(h.state.sendMessage).not.toHaveBeenCalled();
-  });
-
-  it("a healthy resumed finish (visible content) arms nothing and keeps the store", () => {
-    h.state.status = "ready";
-    const { onResumeFallback } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    h.state.setMessages.mockClear();
-    onResumeFallback.mockClear();
-    act(() => {
-      h.state.onFinish?.({
-        message: visibleMsg,
-        isAbort: false,
-        isDisconnect: false,
-        isError: false,
-      });
-    });
-    // No restore (would clobber the fuller streamed message), no poll arm.
-    expect(h.state.setMessages).not.toHaveBeenCalled();
-    expect(onResumeFallback).not.toHaveBeenCalledWith(true);
-  });
-
-  it("isDisconnect WITH visible content arms the poll but does NOT restore", () => {
-    h.state.status = "ready";
-    const { onResumeFallback, invalidateSpy } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    h.state.setMessages.mockClear();
-    onResumeFallback.mockClear();
-    invalidateSpy.mockClear();
-    act(() => {
-      h.state.onFinish?.({
-        message: visibleMsg,
-        isAbort: false,
-        isDisconnect: true,
-        isError: false,
-      });
-    });
-    expect(onResumeFallback).toHaveBeenCalledWith(true);
-    expect(invalidateSpy).toHaveBeenCalledWith({
-      queryKey: ["ai-chat-messages", "c1"],
-    });
-    // Restore forbidden: the on-screen partial must not roll back.
-    expect(h.state.setMessages).not.toHaveBeenCalled();
-  });
-
-  it("an empty resumed message (starved replay) restores the stripped row AND arms the poll", () => {
-    h.state.status = "ready";
-    const { onResumeFallback } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    h.state.setMessages.mockClear();
-    onResumeFallback.mockClear();
-    act(() => {
-      h.state.onFinish?.({
-        message: emptyMsg,
-        isAbort: false,
-        isDisconnect: false,
-        isError: false,
-      });
-    });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1); // restore
-    expect(onResumeFallback).toHaveBeenCalledWith(true); // arm
-  });
-
-  it("degraded-merge: merges the tail per initialRows update, and settles disarm the poll", async () => {
-    h.state.status = "ready";
-    const { rerender, onResumeFallback } = renderResumable(streamingTail());
-    // Arm reconcile via a 204.
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 204, ok: false }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-    h.state.setMessages.mockClear();
-    onResumeFallback.mockClear();
-
-    // A streaming-tail update: merge, poll stays armed.
-    rerender([
-      row("u1", "user", undefined, "hi"),
-      row("a1", "assistant", "streaming", "step 1\nstep 2"),
-    ]);
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-    expect(onResumeFallback).not.toHaveBeenCalledWith(false);
-
-    // A settled-tail update: merge + disarm.
-    h.state.setMessages.mockClear();
-    rerender([
-      row("u1", "user", undefined, "hi"),
-      row("a1", "assistant", "succeeded", "final"),
-    ]);
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-    expect(onResumeFallback).toHaveBeenCalledWith(false);
-  });
-
-  it("a local stream disarms both the merge and the poll", () => {
-    h.state.status = "streaming";
-    const { rerender, onResumeFallback } = renderResumable(streamingTail());
-    onResumeFallback.mockClear();
-    // A re-render while streaming: the reconciliation effect disarms.
-    rerender(streamingTail());
-    expect(onResumeFallback).toHaveBeenCalledWith(false);
-  });
-
-  it("Send now is hidden on a resumed turn but visible on a local stream", () => {
-    // Resumed turn: hidden.
-    renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    fireEvent.click(screen.getByTestId("queue-btn"));
-    expect(screen.queryByLabelText("Send now")).toBeNull();
-
-    // Local streaming turn (no resume): visible.
-    cleanup();
-    resetState();
-    renderThread({ initialRows: [] });
-    fireEvent.click(screen.getByTestId("queue-btn"));
-    expect(screen.getByLabelText("Send now")).toBeTruthy();
-  });
-
-  it("handleStop aborts the attach controller and calls onServerStop", async () => {
-    const { onServerStop } = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: streamingTail(),
-    });
-    // Establish an attach controller via a (pending) reconnect GET.
-    let abortSeen = false;
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockImplementation((_input: unknown, init: RequestInit) => {
-        init.signal?.addEventListener("abort", () => {
-          abortSeen = true;
-        });
-        return new Promise(() => undefined); // never resolves
-      }),
-    );
-    act(() => {
-      void h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-    fireEvent.click(screen.getByLabelText("Stop"));
-    expect(abortSeen).toBe(true);
-    expect(onServerStop).toHaveBeenCalledWith("c1");
-  });
-});
-
-// Helper: render a resumable thread and expose a rerender that only swaps
-// initialRows (the degraded-merge effect depends on it).
-function renderResumable(initialRows: IAiChatMessageRow[]) {
-  const onResumeFallback = vi.fn();
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  const Wrapper = ({ rows }: { rows: IAiChatMessageRow[] }) => (
-    <QueryClientProvider client={queryClient}>
       <MantineProvider>
         <ChatThread
           chatId="c1"
-          initialRows={rows}
+          initialRows={[]}
-          autonomousRunsEnabled
           onTurnFinished={vi.fn()}
-          onResumeFallback={onResumeFallback}
+          observedRow={observedRow as never}
         />
-      </MantineProvider>
+      </MantineProvider>,
-    </QueryClientProvider>
     );
-  const view = render(<Wrapper rows={initialRows} />);
-  const rerender = (rows: IAiChatMessageRow[]) =>
-    act(() => view.rerender(<Wrapper rows={rows} />));
-  return { rerender, onResumeFallback };
-}
-
-// #430: auto-reconnect to a DETACHED run after a LIVE SSE disconnect. The mount
-// path only resumes on mount/reload; these cover the missing trigger — a live
-// `isDisconnect` on onFinish must (backoff-)re-attach WITHOUT a reload, pin+strip
-// the live row to avoid duplicates, fall back to the degraded poll on a 204, and
-// exhaust to a manual Retry.
-describe("ChatThread — live reconnect after isDisconnect (#430)", () => {
-  // A LIVE local turn that just dropped: the settled tail existed before, and the
-  // partial assistant row lives only in `messages` (not persisted as a tail).
-  const settledTail = () => [
-    row("u1", "user", undefined, "hi"),
-    row("a1", "assistant", "succeeded", "done"),
-  ];
-  // The partial assistant message onFinish hands us for the dropped LIVE turn.
-  const liveMsg = {
-    id: "a2",
-    role: "assistant",
-    parts: [{ type: "text", text: "partial live answer" }],
-  };
-
-  beforeEach(() => {
-    resetState();
-    // status "ready": with a live disconnect the mock is not streaming, so the
-    // status==="streaming" auto-clear effect stays out of the way.
-    h.state.status = "ready";
-    vi.useFakeTimers();
-  });
-  afterEach(() => {
-    vi.useRealTimers();
-    cleanup();
-  });
-
-  // Render a NON-resuming mount (settled tail -> no mount resume) with autonomous
-  // runs on, then simulate a live disconnect via onFinish.
-  function renderLiveThenDisconnect() {
-    const view = renderThread({
-      autonomousRunsEnabled: true,
-      initialRows: settledTail(),
-    });
-    // The settled tail must NOT have triggered a mount resume.
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
-    act(() => {
-      h.state.onFinish?.({
-        message: liveMsg,
-        isAbort: false,
-        isDisconnect: true,
-        isError: false,
-      });
-    });
-    return view;
   }
 
-  // Fire the pending (scheduled) attempt for `attempt` (backoff = 1s,2s,4s,...).
+  it("merges the polled run message when this tab is a passive observer", () => {
-  function advanceToAttempt(attempt: number) {
+    renderObserver("ready");
-    act(() => {
+    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-      vi.advanceTimersByTime(1000 * 2 ** (attempt - 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 }[] }[];
-  // Simulate the reconnect GET returning 204 (nothing live) so the transport's
+    const merged = updater([{ id: "u1", parts: [{ text: "hi" }] }]);
-  // no-active-stream recovery runs.
+    expect(merged).toHaveLength(2);
-  async function reconnect204() {
+    expect(merged[1].id).toBe("a-run");
-    vi.stubGlobal(
+    expect(merged[1].parts[0].text).toBe("step 1\nstep 2");
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 204, ok: false }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-  }
-
-  // Simulate the reconnect GET returning a live 2xx stream.
-  async function reconnect200() {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ status: 200, ok: true }),
-    );
-    await act(async () => {
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
-    });
-  }
-
-  it("calls resumeStream POST-mount (a live disconnect triggers a backoff reconnect)", () => {
-    renderLiveThenDisconnect();
-    // The banner shows immediately; the attach itself fires after the first backoff.
-    expect(screen.getByText(/reconnecting/i)).toBeTruthy();
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
-    advanceToAttempt(1);
-    // resumeStream is now called AFTER mount — the bug was it only ever fired once
-    // on mount. The reconnect URL pins expect=live&anchor to OUR run.
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream?expect=live&anchor=a2",
-    );
   });
 
-  it("strips the pinned live row before replay so content is NOT duplicated", () => {
+  it("does NOT merge while THIS tab is the streamer (no double-render)", () => {
-    renderLiveThenDisconnect();
+    renderObserver("streaming");
-    advanceToAttempt(1);
+    expect(h.state.setMessages).not.toHaveBeenCalled();
-    // The attempt strips the anchor row from the store (the live replay rebuilds
-    // it). Apply the setMessages updater to prove it removes exactly the anchor.
-    const updater = h.state.setMessages.mock.calls.at(-1)![0] as (
-      prev: { id: string }[],
-    ) => { id: string }[];
-    expect(updater([{ id: "u1" }, { id: "a2" }])).toEqual([{ id: "u1" }]);
-  });
-
-  it("a live re-attach (2xx) clears the reconnect banner", async () => {
-    renderLiveThenDisconnect();
-    advanceToAttempt(1);
-    await reconnect200();
-    expect(screen.queryByText(/reconnecting/i)).toBeNull();
-  });
-
-  it("a 204 arms the degraded poll and backs off to the next attempt", async () => {
-    const { onResumeFallback } = renderLiveThenDisconnect();
-    advanceToAttempt(1);
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-    await reconnect204();
-    // Fallback engaged: the degraded poll is armed (204 -> onNoActiveStream).
-    expect(onResumeFallback).toHaveBeenCalledWith(true);
-    // Still reconnecting — the banner advanced to attempt 2/5.
-    expect(screen.getByText(/reconnecting.*2\/5/i)).toBeTruthy();
-    // The next backoff fires attempt 2 (another resumeStream).
-    advanceToAttempt(2);
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(2);
-  });
-
-  it("exhausts the attempt limit into a manual Retry, which restarts the sequence", async () => {
-    renderLiveThenDisconnect();
-    // Drive all 5 attempts, each failing with a 204.
-    for (let n = 1; n <= 5; n++) {
-      advanceToAttempt(n);
-      expect(h.state.resumeStream).toHaveBeenCalledTimes(n);
-      await reconnect204();
-    }
-    // The 5th 204 exhausted the cap -> the manual Retry replaces the banner.
-    expect(screen.queryByText(/reconnecting/i)).toBeNull();
-    const retry = screen.getByText("Retry");
-    expect(retry).toBeTruthy();
-    // Retry fires attempt 1 immediately (no backoff) — a 6th resumeStream.
-    act(() => {
-      fireEvent.click(retry);
-    });
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(6);
-    expect(screen.getByText(/reconnecting/i)).toBeTruthy();
-  });
-
-  it("does NOT reconnect when autonomous runs are disabled", () => {
-    renderThread({ autonomousRunsEnabled: false, initialRows: settledTail() });
-    act(() => {
-      h.state.onFinish?.({
-        message: liveMsg,
-        isAbort: false,
-        isDisconnect: true,
-        isError: false,
-      });
-    });
-    expect(screen.queryByText(/reconnecting/i)).toBeNull();
-    // The terminal "connection lost" notice is shown instead (unchanged behavior).
-    expect(
-      screen.getByText("Connection lost — the answer was interrupted."),
-    ).toBeTruthy();
-    advanceToAttempt(1);
-    expect(h.state.resumeStream).not.toHaveBeenCalled();
   });
 });

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

@@ -1,17 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useQueryClient } from "@tanstack/react-query";
 import { generateId } from "ai";
-import {
+import { ActionIcon, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
-  ActionIcon,
-  Alert,
-  Box,
-  Button,
-  Group,
-  Loader,
-  Stack,
-  Text,
-  Tooltip,
-} from "@mantine/core";
 import {
   IconClockHour4,
   IconPlayerPlayFilled,
@@ -35,15 +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 { assistantMessageHasVisibleContent } from "@/features/ai-chat/utils/message-content.ts";
+import { mergeObservedMessage } from "@/features/ai-chat/utils/run-polling.ts";
-import {
-  isStreamingTail,
-  isSettledAssistantTail,
-  seedRows,
-  mergeById,
-} from "@/features/ai-chat/utils/resume-helpers.ts";
-import { AI_CHAT_MESSAGES_RQ_KEY } from "@/features/ai-chat/queries/ai-chat-query.ts";
-import type { EditorSelectionContext } from "@/features/editor/utils/get-editor-selection.ts";
 import {
   dequeue,
   enqueueMessage,
@@ -61,15 +42,6 @@ import classes from "@/features/ai-chat/components/ai-chat.module.css";
 // from the token rate.
 const STREAM_THROTTLE_MS = 50;
 
-// #430: auto-reconnect after a LIVE SSE disconnect of a DETACHED (autonomous) run.
-// The run keeps executing server-side, so instead of a dead "Lost connection"
-// banner we re-attach to the live tail through the SAME resumable machinery the
-// mount path uses. Attempts back off exponentially and are capped; on exhaustion
-// the user gets a manual Retry (the degraded poll keeps catching up underneath).
-const RECONNECT_MAX_ATTEMPTS = 5;
-// Backoff before attempt N (1-based): 1s, 2s, 4s, 8s, 16s.
-const RECONNECT_BASE_DELAY_MS = 1000;
-
 /** The page the user is currently viewing, sent as chat context. */
 export interface OpenPageContext {
   id: string;
@@ -89,10 +61,6 @@ interface ChatThreadProps {
   /** The page currently open in the workspace, or null on a non-page route.
    *  Sent with each turn so the agent knows what "this page" refers to. */
   openPage?: OpenPageContext | null;
-  /** #388: snapshot the user's current editor selection at SEND time. Invoked
-   *  inside prepareSendMessagesRequest and nested into openPage on the wire, so a
-   *  fresh snapshot ships each turn. Null/absent => nothing selected. */
-  getEditorSelection?: () => EditorSelectionContext | null;
   /** The agent role selected for a NEW chat (null = universal assistant). Sent
    *  in the request body so the server persists it on chat creation; ignored by
    *  the server for existing chats (the role is read from the chat row). */
@@ -119,13 +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 phase 1.5: arm/disarm the parent's degraded-poll fallback for THIS
+  /** #184 reconnect-and-live-follow. When THIS tab reopened a chat whose agent
-   *  chat's window. Called `true` when a resume attempt could not attach to the
+   *  run is still going (it is a PASSIVE OBSERVER — it did not start the run here),
-   *  live run (attach 204 / starved-or-torn resumed finish), so the window starts
+   *  the parent polls the reconnect endpoint and feeds the run's incrementally-
-   *  a dumb timed poll of the message history to follow the detached run to settle;
+   *  persisted assistant message here; we merge it into the live list so new
-   *  called `false` the moment a local stream starts or the terminal settled row is
+   *  steps/tool-calls appear as they are persisted. Null when there is nothing to
-   *  merged (invariant 8). The window owns the timer + its 10-min cap. */
+   *  observe (no run, feature off, or this tab IS the streamer). The merge is
-  onResumeFallback?: (active: boolean) => void;
+   *  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;
   /** #184: whether detached/autonomous agent runs are enabled for this workspace.
    *  When true the Stop button must additionally hit the AUTHORITATIVE server stop
    *  (via onServerStop) — aborting only the local SSE is just a client disconnect,
@@ -175,69 +149,21 @@ export default function ChatThread({
   threadKey,
   initialRows,
   openPage,
-  getEditorSelection,
   roleId,
   roles,
   onRolePicked,
   assistantName,
   onTurnFinished,
   onServerChatId,
-  onResumeFallback,
+  observedRow,
+  onStreamingChange,
   autonomousRunsEnabled,
   onServerStop,
 }: ChatThreadProps) {
   const { t } = useTranslation();
-  const queryClient = useQueryClient();
-
-  // resume machinery refs (#184 phase 1.5)
-  const attachAbortRef = useRef<AbortController | null>(null);
-  const reconcileTailRef = useRef(false);
-  const noStreamHandledRef = useRef(false);
-  const onNoActiveStreamRef = useRef<(() => void) | null>(null);
-  // #430: called from the transport's reconnect-GET success branch when a live
-  // stream re-attached (2xx, not 204) — clears the reconnect banner. Kept in a ref
-  // because the transport's fetch closure (useMemo([])) reads it live.
-  const onReconnectAttachedRef = useRef<(() => void) | null>(null);
-  // Live mount flag. The attach GET and the resumed `onFinish` are async and can
-  // land AFTER this thread unmounts (the parent remounts per chat via `key`); with
-  // chatIdRef then pointing at the NEW chat, an ungated late callback would arm a
-  // spurious poll + foreign invalidation on the newly-opened chat. Every parent-
-  // facing resume side-effect is gated on this.
-  const mountedRef = useRef(true);
-  const [resumedTurn, setResumedTurn] = useState(false);
-  const resumedTurnRef = useRef(false);
-  // Identity-stable pair setter (bare useState setter + ref write): it is closed
-  // over by the transport useMemo([]), so it MUST NOT capture state.
-  const setResumedTurnPair = useCallback((v: boolean) => {
-    resumedTurnRef.current = v;
-    setResumedTurn(v);
-  }, []);
-
-  // Mount-time resume gating (in refs — computed once for this mount; the parent
-  // remounts per chat via `key`).
-  //
-  // Attempt resume for any non-settled tail: a streaming tail (strip + expect
-  // live replay) or a user tail (the run may exist but its assistant row is not
-  // seeded yet — attach to the pre-opened registry entry and wait for frames).
-  // A settled assistant tail must NEVER resume: replaying a finished run into a
-  // store that already contains its message duplicates parts (SDK text-start
-  // always pushes a new part).
-  const stripRef = useRef(chatId !== null && isStreamingTail(initialRows ?? []));
-  const attemptResumeRef = useRef(
-    autonomousRunsEnabled === true &&
-      chatId !== null &&
-      !isSettledAssistantTail(initialRows ?? []),
-  );
-  const strippedRowRef = useRef<IAiChatMessageRow | null>(
-    stripRef.current ? (initialRows ?? [])[initialRows!.length - 1] : null,
-  );
 
   const initialMessages = useMemo<UIMessage[]>(
-    () =>
+    () => (initialRows ?? []).map(rowToUiMessage),
-      seedRows(
-        initialRows ?? [],
-        attemptResumeRef.current && stripRef.current,
-      ).map(rowToUiMessage),
     [initialRows],
   );
 
@@ -255,14 +181,6 @@ export default function ChatThread({
   const openPageRef = useRef<OpenPageContext | null>(openPage ?? null);
   openPageRef.current = openPage ?? null;
 
-  // Keep the selection snapshotter in a ref, same rationale as openPageRef: the
-  // transport useMemo([]) closes it over, so prop-identity churn must not matter.
-  // Called at send time inside prepareSendMessagesRequest (#388).
-  const getEditorSelectionRef = useRef<
-    (() => EditorSelectionContext | null) | undefined
-  >(getEditorSelection);
-  getEditorSelectionRef.current = getEditorSelection;
-
   // Keep the selected role id in a ref, same rationale as openPageRef. Only the
   // FIRST request of a brand-new chat uses it (the server persists it then and
   // ignores it for existing chats), but sending it on every send is harmless.
@@ -343,12 +261,9 @@ export default function ChatThread({
     const { head, rest } = dequeue(queuedRef.current);
     if (!head) return false;
     setQueue(rest);
-    // Local send: clear any resume-suppression flag so this genuine local turn's
-    // onFinish flushes normally (invariant 8).
-    setResumedTurnPair(false);
     sendMessageRef.current?.({ text: head.text });
     return true;
-  }, [setQueue, setResumedTurnPair]);
+  }, [setQueue]);
 
   const enqueue = useCallback(
     (text: string) => {
@@ -368,51 +283,6 @@ export default function ChatThread({
       new DefaultChatTransport<UIMessage>({
         api: "/api/ai-chat/stream",
         credentials: "include",
-        prepareReconnectToStreamRequest: () => ({
-          // SDK default URL uses the useChat STORE id — always build from the real chat id.
-          // ?expect=live&anchor=<row id> ONLY when we stripped a streaming tail: expect=live
-          // is the only case where a finished-retained replay is safe (the row is stripped,
-          // replay rebuilds it), and the anchor pins the replay to OUR run — a mismatching
-          // (newer) run must 204 into the restore+poll path instead of replaying a foreign
-          // transcript into this store.
-          api: `/api/ai-chat/runs/${chatIdRef.current}/stream${
-            stripRef.current
-              ? `?expect=live&anchor=${strippedRowRef.current!.id}`
-              : ""
-          }`,
-        }),
-        fetch: async (input: RequestInfo | URL, init: RequestInit = {}) => {
-          if ((init.method ?? "GET") !== "GET") return fetch(input, init); // send path untouched
-          // Reconnect GET: the SDK passes no AbortSignal, so wire our own controller
-          // for observer Stop / unmount abort.
-          const controller = new AbortController();
-          attachAbortRef.current = controller;
-          try {
-            const response = await fetch(input, {
-              ...init,
-              signal: controller.signal,
-            });
-            // No onFinish will come for a 204 (silent no-op) OR any non-2xx
-            // (5xx/502 — a server restart mid-attach). Both run the same
-            // no-active-stream recovery: restore the stripped row, invalidate, and
-            // arm the degraded poll (idempotent via noStreamHandledRef; its part-d
-            // also clears the resumedTurn flag). This is the restart-survival path
-            // the removed F7 latch used to guard — a transient attach failure must
-            // NOT drop the in-progress row or stop tracking the durable run.
-            if (response.status === 204 || !response.ok)
-              onNoActiveStreamRef.current?.();
-            // #430: a 2xx stream re-attached (live tail or finished-replay). Signal
-            // the reconnect controller to clear its banner. No-op outside an active
-            // reconnect sequence (e.g. the mount attach), so it is safe here.
-            else onReconnectAttachedRef.current?.();
-            return response;
-          } catch (err) {
-            // Network throw: same no-onFinish recovery, then rethrow so the SDK
-            // still surfaces the error to its own machinery.
-            onNoActiveStreamRef.current?.();
-            throw err;
-          }
-        },
         // Inject the chat id and the currently-open page alongside the useChat
         // messages so the server can resolve an existing chat (or create one
         // when null) and tell the agent which page "this page" refers to. Both
@@ -429,16 +299,7 @@ export default function ChatThread({
             body: {
               ...body,
               chatId: chatIdRef.current,
-              // Attach the live editor selection to the open-page context at send
+              openPage: openPageRef.current,
-              // time — "this"/"here" in the user's message means THIS selection.
-              // Nested inside openPage so it dies with the page when the server
-              // rejects the page id (#388). Null when nothing is selected.
-              openPage: openPageRef.current
-                ? {
-                    ...openPageRef.current,
-                    selection: getEditorSelectionRef.current?.() ?? null,
-                  }
-                : null,
               // Honoured by the server only when creating a new chat; null =>
               // universal assistant.
               roleId: roleIdRef.current,
@@ -451,15 +312,7 @@ export default function ChatThread({
     [],
   );
 
-  const {
+  const { messages, sendMessage, status, stop, error, setMessages } = useChat({
-    messages,
-    sendMessage,
-    status,
-    stop,
-    error,
-    setMessages,
-    resumeStream,
-  } = 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).
@@ -477,63 +330,6 @@ export default function ChatThread({
     // would be wrong, so on Stop/disconnect/error the queue is left intact for
     // the user to decide.
     onFinish: ({ message, isAbort, isDisconnect, isError }) => {
-      // (1) Capture whether THIS finish belongs to a resumed (attach) turn and
-      // immediately clear the flag so it can never suppress a LATER local turn.
-      const wasResumed = resumedTurnRef.current;
-      setResumedTurnPair(false);
-      // (2) Recovery after a starved/torn resumed finish (invariant 9). The arm
-      // and the stripped-row restore are gated DIFFERENTLY. Skip entirely once
-      // unmounted (an abort-triggered onFinish landing after a chat switch must
-      // not arm a poll / invalidate on the new chat).
-      if (wasResumed && mountedRef.current) {
-        const hasVisibleContent = assistantMessageHasVisibleContent(message);
-        // ARM the reconcile + degraded poll when the resumed message carries no
-        // visible content (starved replay) OR the connection dropped mid-run — in
-        // both cases the poll must drive the row to its real terminal state.
-        if (isDisconnect || !hasVisibleContent) {
-          reconcileTailRef.current = true;
-          queryClient.invalidateQueries({
-            queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
-          });
-          onResumeFallback?.(true);
-        }
-        // RESTORE the stripped streaming row ONLY when the resumed message has no
-        // visible content. On isDisconnect WITH visible content restore is
-        // FORBIDDEN: the live stream may have advanced far past the mount-time
-        // snapshot, so restoring would clobber on-screen content (invariant 9) —
-        // the arm above suffices, the poll reaches the true terminal.
-        if (!hasVisibleContent && strippedRowRef.current) {
-          setMessages((prev) =>
-            mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
-          );
-        }
-      }
-      // (2b) #430: a LIVE (non-resumed) detached run whose SSE just dropped. The
-      // server run keeps executing, so instead of a dead "Lost connection" banner
-      // start a reconnect sequence: pin the CURRENT streaming assistant row as the
-      // strip/anchor (the live tail is the already-shown partial in `messages`, not
-      // a persistent row) and re-attach to the live tail via the resumable machinery.
-      const startedReconnect =
-        isDisconnect &&
-        !wasResumed &&
-        autonomousRunsEnabled === true &&
-        mountedRef.current &&
-        message?.role === "assistant" &&
-        typeof message.id === "string";
-      if (startedReconnect) {
-        beginReconnect({
-          id: message.id,
-          role: "assistant",
-          content: "",
-          status: "streaming",
-          createdAt: new Date().toISOString(),
-          // Preserve the partial parts so a 204 restore (onNoActiveStream) re-shows
-          // what was on screen while the degraded poll catches the run up to
-          // terminal (rowToUiMessage prefers metadata.parts).
-          metadata: { parts: message.parts },
-        });
-      }
-      // (3) Standard branches.
       // Forward the authoritative server chatId (streamed on the assistant
       // message metadata) so the parent adopts the REAL created chat id for a new
       // chat — see adopt-chat-id.ts for the full #137 design. `threadKey` lets the
@@ -542,16 +338,10 @@ export default function ChatThread({
       onTurnFinished(extractServerChatId(message), threadKey);
       // Show a neutral "stopped" marker for an aborted turn; the red error banner
       // (via `error`) already covers isError, and a clean finish clears any marker.
-      // On a live disconnect that STARTED a reconnect, suppress the terminal
-      // "connection lost" notice — the reconnect banner takes over (#430).
       if (isError) setStopNotice(null);
       else if (isAbort) setStopNotice("manual");
-      else if (isDisconnect) setStopNotice(startedReconnect ? null : "disconnect");
+      else if (isDisconnect) setStopNotice("disconnect");
       else setStopNotice(null);
-      // A resumed turn NEVER flushes the queue (invariant 7): skip BOTH the
-      // flush-on-abort branch and the plain flush. The local streamer is the only
-      // tab that owns the queue.
-      if (wasResumed) return;
       // "Send now": WE triggered this abort to interrupt the current turn and
       // immediately send the promoted head. Flush it even though the turn was
       // aborted (the normal abort path below keeps the queue intact). The
@@ -633,226 +423,26 @@ export default function ChatThread({
 
   const isStreaming = status === "submitted" || status === "streaming";
 
-  // #430: live-disconnect reconnect controller. `null` = idle; `{ trying, attempt }`
+  // #184: report our live streaming status up so the parent stops polling the run
-  // = a backoff sequence is running (drives the "reconnecting… (N/max)" banner);
+  // while WE are the streamer (the SSE owns the view) and resumes once we go idle.
-  // `{ failed }` = attempts exhausted (drives the manual Retry). Mirrored into a ref
+  // Effect (not render) so it never updates parent state during our own render;
-  // so the transport/onNoActiveStream closures branch on the LIVE value.
+  // fires on mount with `false`, which also re-syncs the parent after a chat
-  type ReconnectState =
+  // switch remounts this thread (a fresh mount is idle until the user sends).
-    | null
-    | { phase: "trying"; attempt: number }
-    | { phase: "failed" };
-  const [reconnectState, setReconnectState] = useState<ReconnectState>(null);
-  const reconnectStateRef = useRef<ReconnectState>(null);
-  const setReconnectStatePair = useCallback((s: ReconnectState) => {
-    reconnectStateRef.current = s;
-    setReconnectState(s);
-  }, []);
-  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const clearReconnectTimer = useCallback(() => {
-    if (reconnectTimerRef.current) {
-      clearTimeout(reconnectTimerRef.current);
-      reconnectTimerRef.current = null;
-    }
-  }, []);
-
-  // One reconnect attempt — MIRRORS the mount strip/anchor path for the LIVE case.
-  // beginReconnect pinned strippedRowRef/stripRef to the run's assistant row, so:
-  //  - remove that row from the store (the mount path strips it from the SEED; here
-  //    it is already shown, so filter it out) — the live replay's `text-start` then
-  //    rebuilds it without DUPLICATING parts (the main dedup risk, #430);
-  //  - reset the one-shot 204 guard so onNoActiveStream can fire for THIS attempt;
-  //  - mark the turn resumed (invariant 7/8) so onFinish runs the recovery block and
-  //    never flushes the queue;
-  //  - resumeStream() -> prepareReconnectToStreamRequest builds
-  //    ?expect=live&anchor=<pinned id>, pinning the replay to OUR run (invariant 6).
-  const attemptReconnectOnce = useCallback(
-    (attempt: number) => {
-      if (!mountedRef.current) return;
-      const anchor = strippedRowRef.current;
-      if (anchor) {
-        setMessages((prev) => prev.filter((m) => m.id !== anchor.id));
-      }
-      noStreamHandledRef.current = false;
-      setResumedTurnPair(true);
-      setReconnectStatePair({ phase: "trying", attempt });
-      void resumeStream();
-    },
-    [setMessages, setResumedTurnPair, setReconnectStatePair, resumeStream],
-  );
-
-  // Schedule attempt `attempt` after an exponential backoff.
-  const scheduleReconnectAttempt = useCallback(
-    (attempt: number) => {
-      clearReconnectTimer();
-      setReconnectStatePair({ phase: "trying", attempt });
-      reconnectTimerRef.current = setTimeout(
-        () => attemptReconnectOnce(attempt),
-        RECONNECT_BASE_DELAY_MS * 2 ** (attempt - 1),
-      );
-    },
-    [clearReconnectTimer, setReconnectStatePair, attemptReconnectOnce],
-  );
-
-  // Start a fresh reconnect sequence, pinning `anchorRow` (the live run's assistant
-  // row) as the strip/anchor reused by every attempt.
-  const beginReconnect = useCallback(
-    (anchorRow: IAiChatMessageRow) => {
-      if (!autonomousRunsEnabled || !mountedRef.current) return;
-      strippedRowRef.current = anchorRow;
-      stripRef.current = true;
-      scheduleReconnectAttempt(1);
-    },
-    [autonomousRunsEnabled, scheduleReconnectAttempt],
-  );
-
-  // Manual Retry (shown once attempts are exhausted): restart at attempt 1 and fire
-  // immediately (the user asked for it now — no backoff).
-  const retryReconnect = useCallback(() => {
-    clearReconnectTimer();
-    attemptReconnectOnce(1);
-  }, [clearReconnectTimer, attemptReconnectOnce]);
-
-  // Live SSE re-attached (the reconnect GET returned a 2xx stream): clear the
-  // banner + any pending backoff. No-op outside a sequence (e.g. the mount attach).
-  const onReconnectAttached = useCallback(() => {
-    if (!mountedRef.current || !reconnectStateRef.current) return;
-    clearReconnectTimer();
-    setReconnectStatePair(null);
-  }, [clearReconnectTimer, setReconnectStatePair]);
-  onReconnectAttachedRef.current = onReconnectAttached;
-
-  // The reconnect GET could not attach (204 / error). onNoActiveStream has already
-  // armed the degraded poll (the robust fallback that drives the row to terminal
-  // from the DB), so this only decides the LIVE-attach retry: back off and try
-  // again up to the cap, else surface the manual Retry.
-  const onReconnectNoStream = useCallback(() => {
-    const s = reconnectStateRef.current;
-    if (s?.phase !== "trying") return;
-    if (s.attempt < RECONNECT_MAX_ATTEMPTS)
-      scheduleReconnectAttempt(s.attempt + 1);
-    else setReconnectStatePair({ phase: "failed" });
-  }, [scheduleReconnectAttempt, setReconnectStatePair]);
-
-  // 204-handler (`onNoActiveStream`): the attach returned 204 — nothing live to
-  // resume (overflow / begin-failure / after retention / anchor-mismatch). One-
-  // shot via noStreamHandledRef (we do NOT null onNoActiveStreamRef). Exactly four
-  // parts. Kept in a ref (read by the transport's fetch closure) and refreshed
-  // each render below.
-  const onNoActiveStream = useCallback(() => {
-    // A late attach outcome after unmount must not arm a poll / invalidate on the
-    // now-different chat this thread's refs were reused for.
-    if (!mountedRef.current) return;
-    if (noStreamHandledRef.current) return;
-    noStreamHandledRef.current = true;
-    // (a) Restore the stripped streaming row to the store — ONLY when we actually
-    // stripped one (a user-tail 204 does NOT reach here with a stripped row, so do
-    // not dereference null).
-    if (strippedRowRef.current) {
-      setMessages((prev) =>
-        mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
-      );
-    }
-    // (b) Reconcile the tail from the message history + invalidate it so the
-    // degraded poll starts from a fresh fetch.
-    reconcileTailRef.current = true;
-    queryClient.invalidateQueries({
-      queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
-    });
-    // (c) Arm the degraded poll (a dumb timer with a 10-min cap in the window);
-    // the thread disarms it via onResumeFallback(false) on settle / local stream.
-    onResumeFallback?.(true);
-    // (d) 204 means onFinish will NOT fire — clear the suppression flag so it
-    // cannot swallow the NEXT local turn's queue flush.
-    setResumedTurnPair(false);
-    // (e) #430: if this 204/error landed during a live-disconnect reconnect
-    // sequence, back off and retry the live attach (or give up to the manual
-    // Retry). The degraded poll armed in (c) is the fallback either way.
-    onReconnectNoStream();
-  }, [
-    setMessages,
-    queryClient,
-    onResumeFallback,
-    setResumedTurnPair,
-    onReconnectNoStream,
-  ]);
-  onNoActiveStreamRef.current = onNoActiveStream;
-
-  // Mount effect: kick off the resume attempt for a non-settled tail. Marking the
-  // turn as resumed BEFORE resumeStream so onFinish (invariant 7/8) sees it.
   useEffect(() => {
-    // Re-arm on (re)mount — StrictMode dev-mounts twice, and the cleanup below
+    onStreamingChange?.(isStreaming);
-    // flips this false between the two.
+  }, [isStreaming, onStreamingChange]);
-    mountedRef.current = true;
-    if (attemptResumeRef.current) {
-      setResumedTurnPair(true);
-      void resumeStream();
-    }
-    // Unmount: mark unmounted (gates late attach/onFinish side-effects) and abort
-    // the in-flight attach GET so its callbacks don't fire against the next chat.
-    return () => {
-      mountedRef.current = false;
-      attachAbortRef.current?.abort();
-      // #430: drop any pending reconnect backoff so it can't fire against the next
-      // chat this thread's refs are reused for.
-      if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
-    };
-    // Mount-only by design; the parent remounts per chat via `key`.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
 
-  // Reconciliation + degraded-merge (invariant 8). Deps are EXACTLY
+  // #184 passive-observer merge: when the parent feeds a polled run message (we
-  // [initialRows, isStreaming, setMessages].
+  // 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(() => {
-    // A local stream owns the view: disarm BOTH the merge and the window poll.
+    if (isStreaming || !observedRow) return;
-    if (isStreaming) {
+    const observed = rowToUiMessage(observedRow);
-      reconcileTailRef.current = false;
+    setMessages((prev) => mergeObservedMessage(prev, observed));
-      onResumeFallback?.(false);
+  }, [observedRow, isStreaming, setMessages]);
-      return;
-    }
-    if (!reconcileTailRef.current) return;
-    const rows = initialRows ?? [];
-    const tail = rows[rows.length - 1];
-    if (!tail || tail.role !== "assistant") return;
-    // Merge the polled assistant tail on EVERY initialRows update — while the
-    // degraded poll is active this IS the live per-step progress.
-    setMessages((prev) => mergeById(prev, rowToUiMessage(tail)));
-    // Anchor-mismatch coherence: when we restored a stripped streaming row A but a
-    // DIFFERENT run's row B is now the tail (A finished, B replaced the registry
-    // entry, so the attach 204'd), A would otherwise linger forever as an orphan
-    // jumping-dots row over the real run. Settle it from fresh history (where A is
-    // now persisted) so no phantom row survives. No-op in the common case where A
-    // IS the tail (id match).
-    const stripped = strippedRowRef.current;
-    if (stripped && stripped.id !== tail.id) {
-      const historical = rows.find((r) => r.id === stripped.id);
-      if (historical)
-        setMessages((prev) => mergeById(prev, rowToUiMessage(historical)));
-    }
-    // Settled: the terminal merge is done — disarm the flag AND the window poll
-    // explicitly (the window only has a time cap, it will not disarm itself).
-    if (tail.status !== "streaming") {
-      reconcileTailRef.current = false;
-      onResumeFallback?.(false);
-      // #430: the run reached its terminal state via the degraded poll — there is
-      // no live tail left to reconnect to, so drop any reconnect banner / Retry.
-      clearReconnectTimer();
-      setReconnectStatePair(null);
-    }
-    // onResumeFallback intentionally omitted (parent-stable callback); deps are
-    // fixed by the resume design.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [initialRows, isStreaming, setMessages]);
-
-  // #430: a real stream is live again — the reconnect re-attached to the live tail
-  // (status -> "streaming") OR the user started a new local turn. Either way clear
-  // the reconnect banner + any pending backoff. Gated on "streaming" (not the
-  // broader "submitted") so a still-pending attach GET does not clear prematurely.
-  useEffect(() => {
-    if (status === "streaming") {
-      clearReconnectTimer();
-      setReconnectStatePair(null);
-    }
-  }, [status, clearReconnectTimer, setReconnectStatePair]);
 
   // "Send now" on a queued message: interrupt the current turn and immediately
   // send THIS message, keeping the agent's partial output. Other queued messages
@@ -879,12 +469,10 @@ export default function ChatThread({
         const msg = queuedRef.current.find((m) => m.id === id);
         if (!msg) return;
         setQueue(removeQueuedById(queuedRef.current, id));
-        // Local send: clear any resume-suppression flag (invariant 8).
-        setResumedTurnPair(false);
         sendMessageRef.current?.({ text: msg.text });
       }
     },
-    [setQueue, stop, setResumedTurnPair],
+    [setQueue, stop],
   );
 
   // Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
@@ -897,13 +485,7 @@ export default function ChatThread({
   // is not known yet — a brand-new chat in the first moment of its first turn —
   // only the local abort happens (there is no server-side run handle to stop yet).
   const handleStop = useCallback(() => {
-    // Abort the resume/attach GET first: the SDK does not pass it a signal, so an
-    // observer's Stop would otherwise leave the attach fetch running.
-    attachAbortRef.current?.abort();
     stop();
-    // #430: pressing Stop also cancels an in-progress reconnect sequence.
-    clearReconnectTimer();
-    setReconnectStatePair(null);
     if (!autonomousRunsEnabled) return;
     if (chatIdRef.current) {
       onServerStop?.(chatIdRef.current);
@@ -925,13 +507,7 @@ export default function ChatThread({
       // for this fix. Documented so a future change can address the abort-ordering.
       stopPendingRef.current = true;
     }
-  }, [
+  }, [stop, autonomousRunsEnabled, onServerStop]);
-    stop,
-    autonomousRunsEnabled,
-    onServerStop,
-    clearReconnectTimer,
-    setReconnectStatePair,
-  ]);
 
   // Clear the stopped marker as soon as a new turn begins streaming, and drop any
   // stale "Send now" interrupt flags. On the legit interrupt path both refs are
@@ -1016,43 +592,6 @@ export default function ChatThread({
           detail={errorView.detail}
           mb="xs"
         />
-      ) : reconnectState ? (
-        // #430: while auto-reconnecting to a detached run's live tail, show progress
-        // instead of a dead "Lost connection" banner; once attempts are exhausted,
-        // offer a manual Retry (the degraded poll keeps catching up underneath).
-        <Alert
-          variant="light"
-          color="gray"
-          p="xs"
-          mb="xs"
-          style={{ flexShrink: 0 }}
-        >
-          <Group gap={8} wrap="nowrap" align="center">
-            {reconnectState.phase === "trying" ? (
-              <>
-                <Loader size={14} color="gray" style={{ flex: "none" }} />
-                <Text size="sm" lh={1.3} c="dimmed">
-                  {t("Connection lost — reconnecting…")}
-                  {` (${reconnectState.attempt}/${RECONNECT_MAX_ATTEMPTS})`}
-                </Text>
-              </>
-            ) : (
-              <>
-                <Text size="sm" lh={1.3} c="dimmed" style={{ flex: 1 }}>
-                  {t("Couldn't reconnect to the answer.")}
-                </Text>
-                <Button
-                  size="compact-xs"
-                  variant="light"
-                  color="gray"
-                  onClick={retryReconnect}
-                >
-                  {t("Retry")}
-                </Button>
-              </>
-            )}
-          </Group>
-        </Alert>
       ) : stopNotice ? (
         <ChatStoppedNotice
           text={
@@ -1078,11 +617,6 @@ export default function ChatThread({
                 <Text size="xs" lineClamp={2} className={classes.queuedText}>
                   {m.text}
                 </Text>
-                {/* "Send now" (interrupt) is hidden on a RESUMED turn: a local
-                    stop() does not abort the resumed attach fetch, so the click
-                    would be swallowed while flushOnAbortRef would fire minutes
-                    later on the natural finish. Only the remove affordance stays. */}
-                {!resumedTurn && (
                 <Tooltip label={t("Interrupt and send now")} withArrow>
                   <ActionIcon
                     size="xs"
@@ -1094,7 +628,6 @@ export default function ChatThread({
                     <IconPlayerPlayFilled size={12} />
                   </ActionIcon>
                 </Tooltip>
-                )}
                 <ActionIcon
                   size="xs"
                   variant="subtle"
@@ -1109,11 +642,7 @@ export default function ChatThread({
           </Stack>
         )}
         <ChatInput
-          onSend={(text) => {
+          onSend={(text) => sendMessage({ text })}
-            // Local send: clear any resume-suppression flag (invariant 8).
-            setResumedTurnPair(false);
-            sendMessage({ text });
-          }}
           onQueue={enqueue}
           onStop={handleStop}
           isStreaming={isStreaming}

apps/client/src/features/ai-chat/components/message-item.tsx

@@ -40,13 +40,6 @@ interface MessageItemProps {
    * Defaults to true (internal chat). The public share passes false.
    */
   showCitations?: boolean;
-  /**
-   * Forwarded to ToolCallCard: whether tool cards render the one-line summary of
-   * a call's arguments (e.g. the search query). Defaults to true (internal
-   * chat). The public share passes false so an anonymous reader doesn't see the
-   * agent's raw query/argument text.
-   */
-  showInput?: boolean;
   /**
    * Neutralize internal/relative markdown links in the rendered answer (drop
    * their href so they become inert text). Defaults to false (internal chat,
@@ -124,7 +117,6 @@ const MarkdownPart = memo(function MarkdownPart({
 function MessageItem({
   message,
   showCitations = true,
-  showInput = true,
   neutralizeInternalLinks = false,
   assistantName,
   turnStreaming = false,
@@ -218,7 +210,6 @@ function MessageItem({
               key={index}
               part={part as unknown as ToolUiPart}
               showCitations={showCitations}
-              showInput={showInput}
             />
           );
         }
@@ -283,7 +274,6 @@ export function arePropsEqual(
   return (
     prev.signature === next.signature &&
     prev.showCitations === next.showCitations &&
-    prev.showInput === next.showInput &&
     prev.neutralizeInternalLinks === next.neutralizeInternalLinks &&
     prev.assistantName === next.assistantName &&
     // The turn-end flip re-renders every row once (cheap, terminal event) —

apps/client/src/features/ai-chat/components/message-list.tsx

@@ -25,13 +25,6 @@ interface MessageListProps {
    * false because an anonymous reader cannot open the linked internal pages.
    */
   showCitations?: boolean;
-  /**
-   * Forwarded to MessageItem -> ToolCallCard: whether tool cards render the
-   * one-line summary of a call's arguments (e.g. the search query). Defaults to
-   * true (internal chat). The public share passes false so an anonymous reader
-   * doesn't see the agent's raw query/argument text.
-   */
-  showInput?: boolean;
   /**
    * Forwarded to MessageItem: neutralize internal/relative markdown links in
    * the rendered answers (drop their href so they render as inert text).
@@ -126,7 +119,6 @@ export default function MessageList({
   isStreaming,
   emptyState,
   showCitations = true,
-  showInput = true,
   neutralizeInternalLinks = false,
   assistantName,
 }: MessageListProps) {
@@ -216,7 +208,6 @@ export default function MessageList({
             message={message}
             signature={messageSignature(message)}
             showCitations={showCitations}
-            showInput={showInput}
             neutralizeInternalLinks={neutralizeInternalLinks}
             assistantName={assistantName}
             // Turn-level liveness, gated to the TAIL row: only the tail message

apps/client/src/features/ai-chat/components/tool-call-card.tsx

@@ -5,7 +5,6 @@ import { useTranslation } from "react-i18next";
 import {
   getToolName,
   toolCitations,
-  toolInputSummary,
   toolLabelKey,
   toolRunState,
   ToolUiPart,
@@ -22,14 +21,6 @@ interface ToolCallCardProps {
    * (the action log itself) while dropping the unusable links.
    */
   showCitations?: boolean;
-  /**
-   * Whether to render the one-line summary of the call's arguments (e.g. the
-   * search query) under the label. Defaults to true (the internal chat). The
-   * public share passes false: an anonymous reader should not see the agent's
-   * raw query/argument text. Conservative and reversible — it only suppresses
-   * the extra summary line, leaving the card (the action log) intact.
-   */
-  showInput?: boolean;
 }
 
 /**
@@ -40,14 +31,12 @@ interface ToolCallCardProps {
 export default function ToolCallCard({
   part,
   showCitations = true,
-  showInput = true,
 }: ToolCallCardProps) {
   const { t } = useTranslation();
   const toolName = getToolName(part);
   const state = toolRunState(part.state);
   const { key, values } = toolLabelKey(toolName);
   const citations = showCitations ? toolCitations(part) : [];
-  const inputSummary = showInput ? toolInputSummary(part) : undefined;
 
   return (
     <div className={classes.toolCard}>
@@ -68,12 +57,6 @@ export default function ToolCallCard({
         </Text>
       </Group>
 
-      {inputSummary && (
-        <Text size="xs" c="dimmed" mt={2} lineClamp={2}>
-          {inputSummary}
-        </Text>
-      )}
-
       {state === "error" && part.errorText && (
         <Text size="xs" c="red" mt={2}>
           {part.errorText}

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

@@ -1,90 +0,0 @@
-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";
-
-// react-i18next / notifications are pulled in transitively by ai-chat-query.ts
-// (the mutation hooks use them); stub so the module imports cleanly.
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
-}));
-vi.mock("@mantine/notifications", () => ({
-  notifications: { show: vi.fn() },
-}));
-
-// Mock the service module; only getAiChatMessages is exercised, but the other
-// named exports must exist so ai-chat-query.ts imports resolve.
-vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
-  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 { getAiChatMessages } from "@/features/ai-chat/services/ai-chat-service.ts";
-import { useAiChatMessagesQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
-
-const emptyPage = { items: [], meta: { hasNextPage: false, nextCursor: null } };
-
-function createWrapper() {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  return function Wrapper({ children }: { children: React.ReactNode }) {
-    return (
-      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-    );
-  };
-}
-
-// The degraded-poll fallback (#184 phase 1.5) is threaded into this query as a
-// `refetchInterval`; AiChatWindow supplies the deliberately-dumb callback. These
-// pin the plumbing the window depends on: the interval polls the message history,
-// and — critically — fetch ERRORS do NOT stop the tick (TanStack v5 resets the
-// failure count each fetch, so the poll must survive a server restart).
-describe("useAiChatMessagesQuery — degraded refetchInterval", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("re-polls at the interval while the callback returns a duration", async () => {
-    vi.mocked(getAiChatMessages).mockResolvedValue(emptyPage as never);
-    renderHook(() => useAiChatMessagesQuery("c1", () => 30), {
-      wrapper: createWrapper(),
-    });
-    await waitFor(() =>
-      expect(vi.mocked(getAiChatMessages).mock.calls.length).toBeGreaterThan(2),
-    );
-  });
-
-  it("does NOT re-poll when the callback returns false", async () => {
-    vi.mocked(getAiChatMessages).mockResolvedValue(emptyPage as never);
-    renderHook(() => useAiChatMessagesQuery("c1", () => false), {
-      wrapper: createWrapper(),
-    });
-    await waitFor(() =>
-      expect(vi.mocked(getAiChatMessages)).toHaveBeenCalledTimes(1),
-    );
-    // Give any errant interval a chance to fire, then assert it did not.
-    await new Promise((r) => setTimeout(r, 60));
-    expect(vi.mocked(getAiChatMessages)).toHaveBeenCalledTimes(1);
-  });
-
-  it("keeps ticking through fetch errors (errors do not gate the poll)", async () => {
-    vi.mocked(getAiChatMessages).mockRejectedValue(new Error("server down"));
-    renderHook(() => useAiChatMessagesQuery("c1", () => 30), {
-      wrapper: createWrapper(),
-    });
-    await waitFor(() =>
-      expect(vi.mocked(getAiChatMessages).mock.calls.length).toBeGreaterThan(2),
-    );
-  });
-});

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

@@ -13,6 +13,7 @@ import {
   deleteAiChat,
   deleteAiRole,
   getAiChatMessages,
+  getAiChatRun,
   getAiChats,
   getAiRoleCatalog,
   getAiRoleCatalogBundle,
@@ -25,6 +26,7 @@ import {
 import {
   IAiChat,
   IAiChatMessageRow,
+  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -35,6 +37,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"];
@@ -52,13 +55,10 @@ 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). */
- * Paginated list of the current user's chats (auto-loads further pages).
+export function useAiChatsQuery() {
- * `enabled` (default true) lets the AI chat window skip fetching while it is
- * closed — the list is only needed once the window is open.
- */
-export function useAiChatsQuery(enabled: boolean = true) {
   const query = useInfiniteQuery({
     queryKey: AI_CHATS_RQ_KEY,
     queryFn: ({ pageParam }) => getAiChats({ cursor: pageParam, limit: 50 }),
@@ -67,7 +67,6 @@ export function useAiChatsQuery(enabled: boolean = true) {
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
-    enabled,
   });
 
   const data = useMemo<IPagination<IAiChat> | undefined>(() => {
@@ -90,18 +89,7 @@ export function useAiChatsQuery(enabled: boolean = true) {
  * Load all persisted messages of a chat (oldest first), flattening the
  * paginated server response. Used to seed `useChat` initial messages.
  */
-export function useAiChatMessagesQuery(
+export function useAiChatMessagesQuery(chatId: string | undefined) {
-  chatId: string | undefined,
-  // #184 phase 1.5: the degraded-poll fallback. When a tab could not attach to a
-  // still-running run (the attach returned 204 / the resumed stream ended with no
-  // terminal row), the window arms a dumb timed poll of the message history to
-  // follow the detached run to settle. The callback form lives in AiChatWindow;
-  // threaded here verbatim so this query owns the polling. Undefined => no poll.
-  refetchInterval?: number | false | (() => number | false),
-  // #344: gate the query so a backgrounded/hidden window stops issuing refetches
-  // and duplicating work. Defaults to enabled to preserve existing call-sites.
-  enabled: boolean = true,
-) {
   const query = useInfiniteQuery({
     queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatId ?? ""),
     queryFn: ({ pageParam }) =>
@@ -111,8 +99,7 @@ export function useAiChatMessagesQuery(
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
-    enabled: !!chatId && enabled,
+    enabled: !!chatId,
-    refetchInterval,
   });
 
   // useInfiniteQuery only fetches the first page on its own. The hook's contract
@@ -152,6 +139,34 @@ export function useAiChatMessagesQuery(
   };
 }
 
+/**
+ * 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();

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;
+}
+
 /**
  * Explicitly STOP the active agent run of a chat (#184). This is the ONLY thing
  * that ends a DETACHED run — a mere browser disconnect (aborting the local SSE)

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

@@ -210,14 +210,41 @@ export interface IAiChatMessageRow {
     // renders a "stopped" marker on interrupted turns.
     finishReason?: string;
   } | null;
-  // Persisted lifecycle status of the row's turn, carried on the wire by
-  // `baseFields`. 'streaming' marks a still-in-progress assistant row (used by
-  // the resume machinery to decide whether a tail is a live stream to attach to
-  // or a settled row that must not be replayed).
-  status?: string;
   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/resume-helpers.test.ts

@@ -1,112 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
-import {
-  isStreamingTail,
-  isSettledAssistantTail,
-  seedRows,
-  mergeById,
-} from "./resume-helpers.ts";
-
-function row(
-  id: string,
-  role: string,
-  status?: string,
-): IAiChatMessageRow {
-  return { id, role, content: "", status, createdAt: "2026-01-01T00:00:00Z" };
-}
-
-function makeMsg(id: string, text: string): UIMessage {
-  return {
-    id,
-    role: "assistant",
-    parts: [{ type: "text", text }],
-  } as UIMessage;
-}
-
-describe("isStreamingTail", () => {
-  it("is true when the last row is a streaming assistant row", () => {
-    expect(
-      isStreamingTail([row("u1", "user"), row("a1", "assistant", "streaming")]),
-    ).toBe(true);
-  });
-
-  it("is false for a settled assistant tail", () => {
-    expect(isStreamingTail([row("a1", "assistant", "succeeded")])).toBe(false);
-    expect(isStreamingTail([row("a1", "assistant")])).toBe(false);
-  });
-
-  it("is false when the tail is a user row or the list is empty", () => {
-    expect(isStreamingTail([row("u1", "user")])).toBe(false);
-    expect(isStreamingTail([])).toBe(false);
-  });
-});
-
-describe("isSettledAssistantTail", () => {
-  it("is true for an assistant tail whose status is not streaming", () => {
-    expect(isSettledAssistantTail([row("a1", "assistant", "succeeded")])).toBe(
-      true,
-    );
-    expect(isSettledAssistantTail([row("a1", "assistant")])).toBe(true);
-    expect(isSettledAssistantTail([row("a1", "assistant", "aborted")])).toBe(
-      true,
-    );
-  });
-
-  it("is false for a streaming assistant tail", () => {
-    expect(isSettledAssistantTail([row("a1", "assistant", "streaming")])).toBe(
-      false,
-    );
-  });
-
-  it("is false when the tail is a user row or the list is empty", () => {
-    expect(isSettledAssistantTail([row("u1", "user")])).toBe(false);
-    expect(isSettledAssistantTail([])).toBe(false);
-  });
-});
-
-describe("seedRows", () => {
-  const rows = [row("u1", "user"), row("a1", "assistant", "streaming")];
-
-  it("returns the rows unchanged when not stripping", () => {
-    expect(seedRows(rows, false)).toBe(rows);
-  });
-
-  it("drops the last row when stripping", () => {
-    const seeded = seedRows(rows, true);
-    expect(seeded).toHaveLength(1);
-    expect(seeded[0].id).toBe("u1");
-  });
-
-  it("returns an empty list when stripping a single-row list", () => {
-    expect(seedRows([row("a1", "assistant", "streaming")], true)).toHaveLength(
-      0,
-    );
-  });
-});
-
-describe("mergeById", () => {
-  it("replaces the message with the same id in place (per-step growth)", () => {
-    const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
-    const incoming = makeMsg("a1", "step 1\nstep 2");
-    const next = mergeById(prev, incoming);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(incoming);
-    expect(next[0]).toBe(prev[0]); // untouched
-    expect(next).not.toBe(prev); // new array (never mutates input)
-  });
-
-  it("appends when the incoming message is not yet present", () => {
-    const prev = [makeMsg("u1", "hi")];
-    const incoming = makeMsg("a1", "first token");
-    const next = mergeById(prev, incoming);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(incoming);
-  });
-
-  it("returns the original list unchanged when there is nothing to merge", () => {
-    const prev = [makeMsg("u1", "hi")];
-    expect(mergeById(prev, null)).toBe(prev);
-    expect(mergeById(prev, undefined)).toBe(prev);
-  });
-});

apps/client/src/features/ai-chat/utils/resume-helpers.ts

@@ -1,62 +0,0 @@
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
-
-/**
- * Pure decisions for the resumable-SSE resume machinery (#184 phase 1.5). A tab
- * that reopens a chat whose agent run is still going attaches to the server's
- * run-stream registry (replay + live tail) instead of polling snapshots; these
- * small predicates decide WHICH tail is safe to resume and how to seed the store,
- * extracted so they can be unit-tested in isolation.
- */
-
-/**
- * A STREAMING tail: the last persisted row is an assistant row still marked
- * `status === 'streaming'`. Such a tail is stripped from the seed and rebuilt by
- * the replay (`expect=live`), since the SDK's `text-start` always pushes a new
- * part and replaying over a seeded in-progress row would duplicate its text.
- */
-export function isStreamingTail(rows: IAiChatMessageRow[]): boolean {
-  const tail = rows[rows.length - 1];
-  return !!tail && tail.role === "assistant" && tail.status === "streaming";
-}
-
-/**
- * A SETTLED assistant tail: the last row is an assistant row whose status is
- * anything OTHER than 'streaming'. A settled assistant tail must NEVER resume —
- * replaying a finished run into a store that already holds its message duplicates
- * parts (`text-start` always pushes a new part).
- */
-export function isSettledAssistantTail(rows: IAiChatMessageRow[]): boolean {
-  const tail = rows[rows.length - 1];
-  return !!tail && tail.role === "assistant" && tail.status !== "streaming";
-}
-
-/**
- * Seed rows for `useChat`: return the rows unchanged, or without the last row when
- * `strip` is set (the streaming tail is stripped so the live replay rebuilds it
- * without duplicating parts).
- */
-export function seedRows(
-  rows: IAiChatMessageRow[],
-  strip: boolean,
-): IAiChatMessageRow[] {
-  return strip ? rows.slice(0, -1) : rows;
-}
-
-/**
- * Merge an assistant message into the rendered list by id: 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 mergeById(
-  messages: UIMessage[],
-  incoming: UIMessage | null | undefined,
-): UIMessage[] {
-  if (!incoming) return messages;
-  const idx = messages.findIndex((m) => m.id === incoming.id);
-  if (idx === -1) return [...messages, incoming];
-  const next = messages.slice();
-  next[idx] = incoming;
-  return next;
-}

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

@@ -0,0 +1,303 @@
+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,
+  shouldClearStoppingLatch,
+  shouldClearLatchOnQueryError,
+  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("shouldClearStoppingLatch (#234 latch-release decision)", () => {
+  // The one case the latch SHOULD clear: we requested a stop, we are the passive
+  // observer (not streaming), and the CURRENT run is terminal.
+  it("clears only when stopping, observing, and the run is terminal", () => {
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("aborted"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(true);
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("succeeded"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(true);
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("failed"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(true);
+  });
+
+  // Round-3 regression: clearing while THIS tab is still the local streamer would
+  // re-open the flash for the current turn the moment we switch to observer role.
+  // A predicate lacking the streaming gate would (wrongly) return true here.
+  it("does NOT clear while this tab is the local streamer", () => {
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("aborted"),
+        isLocalStreaming: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("succeeded"),
+        isLocalStreaming: true,
+      }),
+    ).toBe(false);
+  });
+
+  // The detached run keeps growing after a local abort — while it is still
+  // active the latch MUST hold so the observer merge stays suppressed.
+  it("does NOT clear while the run is still active", () => {
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("running"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(false);
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: makeRun("pending"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(false);
+  });
+
+  // #234 F4: on Stop the stale PREVIOUS-turn run is removed from the cache, so the
+  // observed `run` is null until the current turn's run is fetched fresh. A null
+  // run HOLDS the latch — it can never clear against the just-removed stale run,
+  // only against the current turn's own terminal run once observed.
+  it("does NOT clear against a removed/absent run (F4 stale-run guard)", () => {
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: null,
+        isLocalStreaming: false,
+      }),
+    ).toBe(false);
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: true,
+        run: undefined,
+        isLocalStreaming: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("does NOT clear when no stop was requested", () => {
+    expect(
+      shouldClearStoppingLatch({
+        stoppingRun: false,
+        run: makeRun("aborted"),
+        isLocalStreaming: false,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("shouldClearLatchOnQueryError (#234 F7 error-safety-net decision)", () => {
+  // This guards the REAL anti-flash decision the component's run-query-error
+  // safety-net effect uses (ai-chat-window.tsx wires the effect to THIS helper,
+  // not a copy — so the test is non-vacuous vs the live code).
+
+  // (b) The F7 hole: a TRANSIENT run-query error while `run` is STILL ACTIVE must
+  // NOT clear the latch. TanStack Query v5 retains `data` on error, so
+  // runQueryFailed can be true while the held run is still pending/running.
+  // Against the PRE-F7 condition (without `!isRunActive(run)`) this would return
+  // true — so this assertion fails on the buggy code (non-vacuous).
+  it("does NOT clear on a transient error while the run is still ACTIVE (F7)", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: makeRun("running"),
+      }),
+    ).toBe(false);
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: makeRun("pending"),
+      }),
+    ).toBe(false);
+  });
+
+  // (a) The genuine permanent-null-freeze: run cache cleared by removeQueries +
+  // the refetch keeps ERRORING, so `run === null`. This is the ONLY case the
+  // safety-net exists to cure — it MUST clear so the frozen view resumes.
+  it("clears on a permanent error when the run is null (permanent-null-freeze)", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: null,
+      }),
+    ).toBe(true);
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: undefined,
+      }),
+    ).toBe(true);
+  });
+
+  // A TERMINAL run also satisfies `!isRunActive`; clearing then is harmless — the
+  // terminal effect (shouldClearStoppingLatch) already clears for a terminal run,
+  // so this only ever agrees with it. Asserted so the (c) reasoning is pinned.
+  it("clears on an error when the run is terminal (harmless, agrees with terminal effect)", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: makeRun("aborted"),
+      }),
+    ).toBe(true);
+  });
+
+  it("does NOT clear without an actual query error", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: false,
+        runQueryFailed: false,
+        run: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("does NOT clear while this tab is the local streamer", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: true,
+        isLocalStreaming: true,
+        runQueryFailed: true,
+        run: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("does NOT clear when no stop was requested", () => {
+    expect(
+      shouldClearLatchOnQueryError({
+        stoppingRun: false,
+        isLocalStreaming: false,
+        runQueryFailed: true,
+        run: null,
+      }),
+    ).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,151 @@
+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;
+}
+
+/**
+ * Should the "stopping" latch — which suppresses the observer re-stream flash
+ * after the user pressed Stop — be RELEASED now? All three must hold:
+ *  - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
+ *  - `!isLocalStreaming`: this tab is NOT the local streamer. While we are the
+ *    streamer the run query is disabled, so the observed `run` is not the run we
+ *    are following — releasing the latch then would re-open the flash for the
+ *    current turn the instant we switch to observer role;
+ *  - the observed `run` EXISTS and has reached a TERMINAL status.
+ *
+ * The null / still-active `run` case is the #234 F4 invariant. On Stop the stale
+ * PREVIOUS-turn run is removed from the query cache (`removeQueries`), so `run`
+ * is null until the CURRENT turn's run is re-fetched fresh; a null or active run
+ * therefore HOLDS the latch, so it can only ever clear against the current turn's
+ * OWN terminal run — never a stale cached one. (The cache removal itself is
+ * integration-level in AiChatWindow; this predicate encodes the decision given
+ * whatever run is currently observed, and a stale terminal run is
+ * indistinguishable from a current terminal run at the predicate level — hence
+ * the cache removal is what guarantees only the current run is ever passed here.)
+ */
+export function shouldClearStoppingLatch(args: {
+  stoppingRun: boolean;
+  run: IAiChatRun | null | undefined;
+  isLocalStreaming: boolean;
+}): boolean {
+  const { stoppingRun, run, isLocalStreaming } = args;
+  if (!stoppingRun || isLocalStreaming) return false;
+  return !!run && !isRunActive(run);
+}
+
+/**
+ * Should the "stopping" latch be RELEASED by the run-query ERROR safety-net?
+ * (#234 F7 — a NEW path of the same re-stream flash the F4 latch exists to
+ * prevent.) After Stop, `handleServerStop` clears the run cache; the terminal
+ * effect then holds the latch via `if (!run) return` until the CURRENT turn's run
+ * is fetched fresh. If that refetch instead ERRORS permanently, `run` stays null,
+ * its status-keyed refetchInterval is off, and nothing would ever observe a
+ * terminal run — freezing the view with the observer merge suppressed. This
+ * safety-net cures ONLY that genuine permanent-null-freeze.
+ *
+ * All four must hold:
+ *  - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
+ *  - `!isLocalStreaming`: this tab is NOT the local streamer (same reason as
+ *    {@link shouldClearStoppingLatch});
+ *  - `runQueryFailed`: the run query is in its error state (TanStack Query v5 with
+ *    retry:false — isError);
+ *  - `!isRunActive(run)`: the observed `run` is NOT an active (pending/running)
+ *    held run. This is the F7 gate. In TanStack Query v5 the query's `data` is
+ *    RETAINED on error, so `runQueryFailed` can be true while `run` is STILL an
+ *    ACTIVE run (a single transient GET-run failure in the window between Stop and
+ *    settle). Without this gate a transient error would release the latch early —
+ *    re-opening the observer merge and flashing the growing detached run over the
+ *    frozen row (exactly the F4 flash). Gating on the run NOT being active means we
+ *    only ever cure the permanent-null-freeze (`run === null`, so
+ *    `isRunActive(null)` is false), never release against an active run.
+ *
+ * (A terminal `run` also satisfies `!isRunActive(run)`; clearing then is harmless
+ * — the terminal effect's {@link shouldClearStoppingLatch} already clears the
+ * latch for a terminal run, so this only ever agrees with it, never conflicts.)
+ *
+ * INVARIANT (do not break): clearing the latch on the `run === null` branch is safe
+ * ONLY because the run query's `refetchInterval` (see {@link runPollInterval}) stops
+ * polling when the data is empty — so after we clear on null+error there is no
+ * subsequent auto-poll that could return a still-active detached run and re-open the
+ * merge. If `refetchInterval` is ever changed to keep polling on `run === null`/on
+ * error, this null-branch clear would re-open the F7 flash through the null path.
+ * Do not change the run query's refetchInterval without re-checking this path.
+ */
+export function shouldClearLatchOnQueryError(args: {
+  stoppingRun: boolean;
+  isLocalStreaming: boolean;
+  runQueryFailed: boolean;
+  run: IAiChatRun | null | undefined;
+}): boolean {
+  const { stoppingRun, isLocalStreaming, runQueryFailed, run } = args;
+  return (
+    stoppingRun && !isLocalStreaming && runQueryFailed && !isRunActive(run)
+  );
+}
+
+/**
+ * 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/ai-chat/utils/tool-parts.test.tsx

@@ -1,7 +1,6 @@
 import { describe, it, expect } from "vitest";
 import {
   toolCitations,
-  toolInputSummary,
   toolRunState,
   type ToolUiPart,
 } from "./tool-parts";
@@ -78,138 +77,6 @@ describe("toolCitations", () => {
   });
 });
 
-describe("toolInputSummary", () => {
-  it("returns the primary `query` string", () => {
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-available",
-      input: { query: "hello world" },
-    };
-    expect(toolInputSummary(part)).toBe("hello world");
-  });
-
-  it("summarizes a primary array field with a (+N) suffix", () => {
-    // `urls` is an external MCP read_pages-style list; the first element plus a
-    // count of the rest.
-    const part: ToolUiPart = {
-      type: "tool-read_pages",
-      state: "input-available",
-      input: { urls: ["a", "b", "c"] },
-    };
-    expect(toolInputSummary(part)).toBe("a (+2)");
-  });
-
-  it("omits the (+N) suffix for a single-element array", () => {
-    const part: ToolUiPart = {
-      type: "tool-read_pages",
-      state: "input-available",
-      input: { urls: ["only"] },
-    };
-    expect(toolInputSummary(part)).toBe("only");
-  });
-
-  it("falls back to `title` for a page op with no query", () => {
-    const part: ToolUiPart = {
-      type: "tool-createPage",
-      state: "input-available",
-      input: { pageId: "x", title: "My Page" },
-    };
-    expect(toolInputSummary(part)).toBe("My Page");
-  });
-
-  it("prefers the earlier primary field when several are present", () => {
-    const part: ToolUiPart = {
-      type: "tool-x",
-      state: "input-available",
-      // `query` outranks `title` in PRIMARY_INPUT_FIELDS — the ordered list is
-      // the contract, so a reordering must break this test.
-      input: { query: "Q", title: "T" },
-    };
-    expect(toolInputSummary(part)).toBe("Q");
-  });
-
-  it("does not clamp a value exactly at the 140-char limit", () => {
-    const exact = "a".repeat(140);
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-available",
-      input: { query: exact },
-    };
-    const out = toolInputSummary(part)!;
-    expect(out).toBe(exact);
-    expect(out.endsWith("…")).toBe(false);
-    expect(out.length).toBe(140);
-  });
-
-  it("clamps one char over the limit (141 -> 140 + ellipsis)", () => {
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-available",
-      input: { query: "a".repeat(141) },
-    };
-    const out = toolInputSummary(part)!;
-    expect(out.endsWith("…")).toBe(true);
-    expect(out.length).toBe(141);
-    expect(out).toBe("a".repeat(140) + "…");
-  });
-
-  it("clamps a long value to ~140 chars with an ellipsis", () => {
-    const long = "a".repeat(300);
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-available",
-      input: { query: long },
-    };
-    const out = toolInputSummary(part)!;
-    expect(out.endsWith("…")).toBe(true);
-    expect(out.length).toBeLessThanOrEqual(141);
-  });
-
-  it("collapses newlines and repeated spaces to single spaces", () => {
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-available",
-      input: { query: "  foo\n\n  bar   baz  " },
-    };
-    expect(toolInputSummary(part)).toBe("foo bar baz");
-  });
-
-  it("returns undefined with no input", () => {
-    expect(
-      toolInputSummary({ type: "tool-x", state: "input-available" }),
-    ).toBeUndefined();
-  });
-
-  it("returns undefined for an empty object input", () => {
-    expect(
-      toolInputSummary({
-        type: "tool-x",
-        state: "input-available",
-        input: {},
-      }),
-    ).toBeUndefined();
-  });
-
-  it("returns undefined for a non-object input", () => {
-    expect(
-      toolInputSummary({
-        type: "tool-x",
-        state: "input-available",
-        input: "just a string",
-      }),
-    ).toBeUndefined();
-  });
-
-  it("returns undefined while the input is still streaming (even with a full input)", () => {
-    const part: ToolUiPart = {
-      type: "tool-Search_web_search",
-      state: "input-streaming",
-      input: { query: "hello world" },
-    };
-    expect(toolInputSummary(part)).toBeUndefined();
-  });
-});
-
 describe("toolRunState", () => {
   it('maps "output-error" to error', () => {
     expect(toolRunState("output-error")).toBe("error");

apps/client/src/features/ai-chat/utils/tool-parts.tsx

@@ -97,69 +97,6 @@ function asString(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
-/** Collapse runs of whitespace/newlines to a single space and trim. */
-function collapse(s: string): string {
-  return s.replace(/\s+/g, " ").trim();
-}
-
-/** Truncate to ~140 chars, appending an ellipsis when it overflows. */
-function clamp(s: string): string {
-  const MAX = 140;
-  return s.length > MAX ? s.slice(0, MAX).trimEnd() + "…" : s;
-}
-
-/**
- * Priority "primary" argument fields, in order. The first present one supplies
- * the summary. `urls` is included (external MCP `read_pages`-style tools take a
- * list of URLs) and is handled as an array; `url` covers the single-URL form.
- */
-const PRIMARY_INPUT_FIELDS = [
-  "query",
-  "q",
-  "searchQuery",
-  "url",
-  "urls",
-  "title",
-  "name",
-  "text",
-  "prompt",
-] as const;
-
-/**
- * A short, PLAIN-TEXT one-line summary of a tool call's arguments (e.g. the
- * search query), or undefined when no recognizable primary field is present.
- * Rendered under the tool label so tools without a friendly name (external MCP
- * tools like `Search_web_search`) still show WHAT was requested, not just a
- * generic "Ran tool {{name}}". The returned string is plain text and MUST be
- * rendered React-escaped (Mantine `<Text>`), never as markdown/HTML.
- *
- * Streaming gate: while `state === "input-streaming"` the `input` object grows
- * chunk by chunk but `messageSignature` deliberately does NOT track `input`, so
- * a live summary computed here would freeze at its first captured value and go
- * stale. We therefore return undefined until the state flips to
- * `input-available` (input finalized) — that state change IS tracked by the
- * signature, so the row re-renders and shows the complete summary. Do NOT add
- * `input` to `message-signature.ts` to work around this.
- */
-export function toolInputSummary(part: ToolUiPart): string | undefined {
-  if (part.state === "input-streaming") return undefined;
-  if (!part.input || typeof part.input !== "object") return undefined;
-  const input = part.input as Record<string, unknown>;
-
-  for (const field of PRIMARY_INPUT_FIELDS) {
-    const value = input[field];
-    if (typeof value === "string" && value.length > 0) {
-      return clamp(collapse(value));
-    }
-    if (Array.isArray(value) && value.length > 0) {
-      const first = collapse(String(value[0]));
-      if (first.length === 0) continue;
-      return clamp(first + (value.length > 1 ? ` (+${value.length - 1})` : ""));
-    }
-  }
-  return undefined;
-}
-
 /**
  * Resolve the page citation(s) a tool part references, from its input/output.
  * Only output-available parts (the tool returned) yield citations. Search

apps/client/src/features/comment/components/comment-content-view.test.tsx

@@ -15,7 +15,6 @@ vi.mock("@/features/comment/components/comment-editor", () => ({
 // case renders in isolation.
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
-  usePageMetaQuery: () => ({ data: undefined, isLoading: false, isError: false }),
 }));
 vi.mock("@/features/share/queries/share-query.ts", () => ({
   useSharePageQuery: () => ({ data: undefined }),

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -22,7 +22,7 @@ import CommentEditor from "@/features/comment/components/comment-editor";
 import CommentActions from "@/features/comment/components/comment-actions";
 import { useFocusWithin } from "@mantine/hooks";
 import { IComment } from "@/features/comment/types/comment.types.ts";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useTranslation } from "react-i18next";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -56,7 +56,7 @@ export function buildChildrenByParent(
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
-  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
   const {
     data: comments,
     isLoading: isCommentsLoading,

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -1,8 +1,5 @@
 import { atom } from "jotai";
-// Type-only: these atoms only hold an Editor reference for typing. A value
+import { Editor } from "@tiptap/core";
-// import would drag the whole @tiptap/core engine into the eager graph of every
-// shell component that reads one of these atoms.
-import type { Editor } from "@tiptap/core";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 

apps/client/src/features/editor/components/audio/audio-menu.tsx

@@ -46,13 +46,6 @@ export function AudioMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
-      // #343 PART 1: skip getAttributes unless an audio node is active. The menu
-      // only shows for an active audio node (shouldShow), so the null state while
-      // inactive is never rendered — behavior unchanged.
-      if (!ctx.editor.isActive("audio")) {
-        return null;
-      }
-
       const audioAttrs = ctx.editor.getAttributes("audio");
 
       return {

apps/client/src/features/editor/components/callout/callout-menu.tsx

@@ -43,15 +43,8 @@ export function CalloutMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
-      // #343 PART 1: skip the per-type isActive() probes unless a callout is
-      // active. The menu only shows for an active callout (shouldShow), so the
-      // null state while inactive is never rendered — behavior unchanged.
-      if (!ctx.editor.isActive("callout")) {
-        return null;
-      }
-
       return {
-        isCallout: true,
+        isCallout: ctx.editor.isActive("callout"),
         isInfo: ctx.editor.isActive("callout", { type: "info" }),
         isNote: ctx.editor.isActive("callout", { type: "note" }),
         isSuccess: ctx.editor.isActive("callout", { type: "success" }),

apps/client/src/features/editor/components/code-block/code-block-view.tsx

@@ -22,12 +22,6 @@ export default function CodeBlockView(props: NodeViewProps) {
   const [isSelected, setIsSelected] = useState(false);
 
   useEffect(() => {
-    // #343 PART 6: `isSelected` only drives the mermaid source's visibility (the
-    // `hidden` prop below). For every non-mermaid code block it is never read,
-    // so skip the per-block `selectionUpdate` listener entirely — otherwise N
-    // code blocks each add a global listener + a setState on every caret move.
-    if (language !== "mermaid") return;
-
     const updateSelection = () => {
       const { state } = editor;
       const { from, to } = state.selection;
@@ -38,14 +32,11 @@ export default function CodeBlockView(props: NodeViewProps) {
       setIsSelected(isNodeSelected);
     };
 
-    // Initialize on attach so switching a block's language to "mermaid" reflects
-    // the current selection immediately (the listener was not running before).
-    updateSelection();
     editor.on("selectionUpdate", updateSelection);
     return () => {
       editor.off("selectionUpdate", updateSelection);
     };
-  }, [editor, getPos(), node.nodeSize, language]);
+  }, [editor, getPos(), node.nodeSize]);
 
   function changeLanguage(language: string) {
     setLanguageValue(language);

apps/client/src/features/editor/components/drawio/drawio-menu-lazy.tsx

@@ -1,16 +0,0 @@
-import { lazy, Suspense } from "react";
-import { EditorMenuProps } from "@/features/editor/components/table/types/types.ts";
-
-// Lazily load the drawio bubble menu so it is split out of the editor chunk and
-// fetched only when an editable editor is mounted (mirrors excalidraw-menu-lazy).
-const DrawioMenu = lazy(
-  () => import("@/features/editor/components/drawio/drawio-menu.tsx"),
-);
-
-export default function DrawioMenuLazy(props: EditorMenuProps) {
-  return (
-    <Suspense fallback={null}>
-      <DrawioMenu {...props} />
-    </Suspense>
-  );
-}

apps/client/src/features/editor/components/drawio/drawio-view-lazy.tsx

@@ -1,17 +0,0 @@
-import { lazy, Suspense } from "react";
-import { NodeViewProps } from "@tiptap/react";
-
-// Lazily load the drawio node view so the heavy react-drawio embed runtime is
-// split into its own chunk and fetched only when a drawio diagram is actually
-// rendered (mirrors excalidraw-view-lazy).
-const DrawioView = lazy(
-  () => import("@/features/editor/components/drawio/drawio-view.tsx"),
-);
-
-export default function DrawioViewLazy(props: NodeViewProps) {
-  return (
-    <Suspense fallback={null}>
-      <DrawioView {...props} />
-    </Suspense>
-  );
-}

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -1,7 +1,5 @@
 import type { Editor } from "@tiptap/react";
 import { useEditorState } from "@tiptap/react";
-import { undoDepth, redoDepth } from "@tiptap/pm/history";
-import { yUndoPluginKey } from "@tiptap/y-tiptap";
 
 export interface ToolbarState {
   isBold: boolean;
@@ -18,45 +16,14 @@ export interface ToolbarState {
   canRedo: boolean;
 }
 
-// Undo/redo availability, computed WITHOUT `editor.can().undo()/.redo()`.
+// Undo/redo come from either StarterKit's history or the Yjs collaboration
-//
+// history extension. During the brief moment a page is rendered with the
-// `editor.can()` runs the command as a dry-run (building a throwaway state +
+// static editor (mainExtensions only, undoRedo disabled), neither is loaded
-// transaction) — the most expensive work in this selector, and it ran on every
+// and editor.can().undo/redo is undefined.
-// keystroke (and every REMOTE keystroke under collaboration). Instead we read
+function safeCan(editor: Editor, command: "undo" | "redo"): boolean {
-// the history stack depth directly, which is a cheap plugin-state lookup and
+  const can = editor.can() as Record<string, unknown>;
-// mirrors exactly what the undo/redo commands themselves check:
+  const fn = can[command];
-//
+  return typeof fn === "function" ? (fn as () => boolean)() : false;
-//  - Collaboration (Yjs): the yjs UndoManager's undo/redo stack lengths — the
-//    same `undoStack.length === 0` / `redoStack.length === 0` guard the
-//    Collaboration extension's undo/redo commands use.
-//  - Plain history (templates / non-collab): prosemirror-history's undoDepth /
-//    redoDepth, which back the UndoRedo extension.
-//
-// When neither history backend is installed (the pre-sync static editor —
-// mainExtensions only, undoRedo disabled), both fall through to 0 -> false,
-// matching the previous `safeCan` behavior.
-function historyAvailability(editor: Editor): {
-  canUndo: boolean;
-  canRedo: boolean;
-} {
-  const state = editor.state;
-
-  // Collaboration history (Yjs) takes precedence when present.
-  const yState = yUndoPluginKey.getState(state) as
-    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
-    | undefined;
-  if (yState?.undoManager) {
-    return {
-      canUndo: yState.undoManager.undoStack.length > 0,
-      canRedo: yState.undoManager.redoStack.length > 0,
-    };
-  }
-
-  // Plain prosemirror-history (returns 0 when the history plugin is absent).
-  return {
-    canUndo: undoDepth(state) > 0,
-    canRedo: redoDepth(state) > 0,
-  };
 }
 
 export function useToolbarState(editor: Editor | null): ToolbarState | null {
@@ -64,7 +31,6 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
     editor,
     selector: (ctx) => {
       if (!ctx.editor) return null;
-      const { canUndo, canRedo } = historyAvailability(ctx.editor);
       return {
         isBold: ctx.editor.isActive("bold"),
         isItalic: ctx.editor.isActive("italic"),
@@ -76,8 +42,8 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
         isBulletList: ctx.editor.isActive("bulletList"),
         isOrderedList: ctx.editor.isActive("orderedList"),
         isTaskList: ctx.editor.isActive("taskList"),
-        canUndo,
+        canUndo: safeCan(ctx.editor, "undo"),
-        canRedo,
+        canRedo: safeCan(ctx.editor, "redo"),
       };
     },
   });

apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx

@@ -49,14 +49,19 @@ export default function FootnoteDefinitionView(props: NodeViewProps) {
       className={classes.definition}
       style={{ ["--footnote-number" as any]: `"${number}"` }}
     >
-      {/* #146: contentDOM MUST be the first child — non-editable chrome before
+      {/* #146: contentDOM MUST be the first child — a non-editable marker before
           it makes click hit-testing snap the caret above. Content first; the
-          back-link follows in DOM and is placed on the right via CSS flex. The
+          marker + back-link follow in DOM and are placed left/right via CSS
-          decorative "N." number is rendered inline via the .definitionContent
+          flex `order`. The second #146 mitigation lives in
-          ::before rule (from the --footnote-number var), so no marker element
-          precedes the content. The second #146 mitigation lives in
           editor-paste-handler.tsx (reflowAfterPaste). */}
       <NodeViewContent className={classes.definitionContent} />
+      <span
+        className={classes.definitionMarker}
+        contentEditable={false}
+        aria-hidden="true"
+      >
+        {number}.
+      </span>
       {refCount > 1 ? (
         // Multiple references -> ↩ followed by one lettered link per occurrence.
         <span

apps/client/src/features/editor/components/footnote/footnote.module.css

@@ -81,34 +81,34 @@
 .definition {
   display: flex;
   align-items: flex-start;
-  /* Tight spacing between the content and the trailing ↩ back-link. */
+  /* Tight number→text spacing (~one space) so it reads like "1. text"
-  gap: 0.3em;
+     instead of leaving a wide gap after the period. */
+  gap: 0.4em;
   padding: 2px 0;
-  /* Footnotes read smaller than body text (16px). Matches .listHeading. */
-  font-size: var(--mantine-font-size-sm);
 }
 
-/* The "N." number is decorative (from the --footnote-number CSS var on the
+.definitionMarker {
-   wrapper, never in the document model) and is rendered inline at the start of
+  order: -1; /* keep the "N." marker on the LEFT though it follows content in DOM (#146) */
-   the first content line via ::before. This keeps text and wrapped lines flush
+  flex: 0 0 auto;
-   to the left margin — no hanging indent — while the editable contentDOM stays
+  min-width: 1.5em;
-   the FIRST DOM child (#146). */
+  /* Right-align within the narrow column so the period sits next to the text
+     and multi-digit numbers (10, 11, …) stay aligned on their right edge. */
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  color: var(--mantine-color-dimmed);
+  user-select: none;
+}
+
 .definitionContent {
   flex: 1 1 auto;
   min-width: 0;
 }
 
-.definitionContent > :first-child::before {
+/* The inner editable paragraph inherits `.ProseMirror p { margin: 0.5em 0 }`,
-  content: var(--footnote-number, "?") ". ";
+   which pushes the first text line ~0.5em below the "N." marker (aligned to
-  color: var(--mantine-color-dimmed);
+   flex-start), making the number float above the text. Drop the outer margins
-  font-variant-numeric: tabular-nums;
+   so the marker and the first line share the same top edge — same approach
-  user-select: none;
+   used for callouts in core.css. */
-}
-
-/* The inner editable paragraph inherits `.ProseMirror p { margin: 0.5em 0 }`.
-   Drop the outer margins so the definition sits tight to the heading above and
-   the ::before number aligns with the top of the row — same approach used for
-   callouts in core.css. */
 .definitionContent > :first-child {
   margin-top: 0;
 }

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -38,14 +38,6 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
-      // #343 PART 1: skip the expensive per-keystroke work (getAttributes + the
-      // alignment isActive() probes) unless an image is actually active. The
-      // menu is only shown when an image is active (see shouldShow), so a null
-      // state while inactive is never rendered — behavior is unchanged.
-      if (!ctx.editor.isActive("image")) {
-        return null;
-      }
-
       const imageAttrs = ctx.editor.getAttributes("image");
 
       return {

apps/client/src/features/editor/components/link/link-view.tsx

@@ -24,7 +24,7 @@ import classes from "./link.module.css";
 import { useTranslation } from "react-i18next";
 import { INTERNAL_LINK_REGEX } from "@/lib/constants";
 import { LinkEditorPanel } from "@/features/editor/components/link/link-editor-panel.tsx";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import { buildSharedPageUrl } from "@/features/page/page.utils.ts";
 import { extractPageSlugId } from "@/lib";
@@ -83,7 +83,7 @@ export default function LinkView(props: MarkViewProps) {
   const isPopoverVisible = popoverState !== "closed";
   const activeView = isPopoverVisible ? popoverState : lastOpenState.current;
 
-  const { data: linkedPage } = usePageMetaQuery({
+  const { data: linkedPage } = usePageQuery({
     pageId: isPopoverVisible && slugId && !isShareRoute ? slugId : null,
   });
 

apps/client/src/features/editor/components/math/math-block-lazy.tsx

@@ -1,19 +0,0 @@
-import { lazy, Suspense } from "react";
-import { NodeViewProps } from "@tiptap/react";
-
-// Lazily load the KaTeX-backed block math view so the katex chunk is fetched
-// only when a document actually contains a math node (mirrors the mermaid/
-// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
-// crashing or blocking the whole editor: while it loads we render the raw
-// LaTeX source as a node-sized placeholder.
-const MathBlockView = lazy(
-  () => import("@/features/editor/components/math/math-block.tsx"),
-);
-
-export default function MathBlockViewLazy(props: NodeViewProps) {
-  return (
-    <Suspense fallback={<div data-katex="true">{props.node.attrs.text}</div>}>
-      <MathBlockView {...props} />
-    </Suspense>
-  );
-}

apps/client/src/features/editor/components/math/math-inline-lazy.tsx

@@ -1,19 +0,0 @@
-import { lazy, Suspense } from "react";
-import { NodeViewProps } from "@tiptap/react";
-
-// Lazily load the KaTeX-backed inline math view so the katex chunk is fetched
-// only when a document actually contains a math node (mirrors the mermaid/
-// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
-// crashing or blocking the whole editor: while it loads we render the raw
-// LaTeX source as a node-sized placeholder.
-const MathInlineView = lazy(
-  () => import("@/features/editor/components/math/math-inline.tsx"),
-);
-
-export default function MathInlineViewLazy(props: NodeViewProps) {
-  return (
-    <Suspense fallback={<span data-katex="true">{props.node.attrs.text}</span>}>
-      <MathInlineView {...props} />
-    </Suspense>
-  );
-}

apps/client/src/features/editor/components/mention/mention-list.tsx

@@ -25,7 +25,7 @@ import { IconFileDescription, IconPlus } from "@tabler/icons-react";
 import { useSpaceQuery } from "@/features/space/queries/space-query.ts";
 import { useParams } from "react-router-dom";
 import { v7 as uuid7 } from "uuid";
-import { useAtom, useSetAtom, useStore } from "jotai";
+import { useAtom } from "jotai";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import {
   MentionListProps,
@@ -34,7 +34,7 @@ import {
 import { IPage } from "@/features/page/types/page.types";
 import {
   useCreatePageMutation,
-  usePageMetaQuery,
+  usePageQuery,
 } from "@/features/page/queries/page-query";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom";
 import { treeModel } from "@/features/page/tree/model/tree-model";
@@ -50,16 +50,12 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
   const [countAnnouncement, setCountAnnouncement] = useState("");
   const [selectionAnnouncement, setSelectionAnnouncement] = useState("");
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
   const { data: space } = useSpaceQuery(spaceSlug);
   const [currentUser] = useAtom(currentUserAtom);
   const [renderItems, setRenderItems] = useState<MentionSuggestionItem[]>([]);
   const { t } = useTranslation();
-  // Setter-only: the tree value is read only imperatively inside createPage
+  const [data, setData] = useAtom(treeDataAtom);
-  // (via `store` below), never at render, so useSetAtom avoids re-rendering the
-  // mention popup on any tree event.
-  const setData = useSetAtom(treeDataAtom);
-  const store = useStore();
   const createPageMutation = useCreatePageMutation();
   const emit = useQueryEmit();
   const isInCommentContext = props.isInCommentContext ?? false;
@@ -276,11 +272,9 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
         children: [],
       };
 
-      // Read the live tree imperatively at call time.
+      const lastIndex = data.length;
-      const currentTree = store.get(treeDataAtom);
-      const lastIndex = currentTree.length;
 
-      setData(treeModel.insert(currentTree, parentId, newNode, lastIndex));
+      setData(treeModel.insert(data, parentId, newNode, lastIndex));
 
       props.command({
         id: uuid7(),

apps/client/src/features/editor/components/mention/mention-view.tsx

@@ -2,7 +2,7 @@ import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { ActionIcon, Anchor, Text } from "@mantine/core";
 import { IconFileDescription } from "@tabler/icons-react";
 import { Link, useLocation, useNavigate, useParams } from "react-router-dom";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import {
   buildPageUrl,
@@ -36,7 +36,7 @@ export function MentionContent({ attrs }: { attrs: MentionAttrs }) {
     data: page,
     isLoading,
     isError,
-  } = usePageMetaQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
+  } = usePageQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
 
   const { data: sharedPage } = useSharePageQuery({
     pageId: isPageMention && isShareRoute ? slugId : undefined,

apps/client/src/features/editor/components/pdf/pdf-menu.tsx

@@ -25,13 +25,6 @@ export function PdfMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
-      // #343 PART 1: skip getAttributes unless a pdf node is active. The menu
-      // only shows for an active pdf node (shouldShow), so the null state while
-      // inactive is never rendered — behavior unchanged.
-      if (!ctx.editor.isActive("pdf")) {
-        return null;
-      }
-
       const pdfAttrs = ctx.editor.getAttributes("pdf");
 
       return {

apps/client/src/features/editor/components/subpages/subpages-menu.tsx

@@ -70,14 +70,7 @@ export const SubpagesMenu = React.memo(
     // toggle without re-rendering on every keystroke.
     const isRecursive = useEditorState({
       editor,
-      // #343 PART 1: skip getAttributes unless a subpages node is active. The
+      selector: (ctx) => ctx.editor?.getAttributes("subpages")?.recursive ?? false,
-      // menu only shows for an active subpages node (shouldShow), so the value
-      // is only read then; getAttributes on an inactive node returns the default
-      // (recursive === false) anyway, so this is behavior-preserving.
-      selector: (ctx) =>
-        ctx.editor?.isActive("subpages")
-          ? (ctx.editor.getAttributes("subpages")?.recursive ?? false)
-          : false,
     });
 
     return (

apps/client/src/features/editor/components/table-of-contents/table-of-contents.tsx

@@ -4,7 +4,6 @@ import React, { FC, useEffect, useRef, useState } from "react";
 import classes from "./table-of-contents.module.css";
 import clsx from "clsx";
 import { Box, Text, Title } from "@mantine/core";
-import { useDebouncedCallback } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
 
 type TableOfContentsProps = {
@@ -80,21 +79,13 @@ export const TableOfContents: FC<TableOfContentsProps> = (props) => {
     setHeadingDOMNodes(result.nodes);
   };
 
-  // Debounce the update-driven rescan: `$nodes("heading")` scans every heading
-  // in the document, and it previously ran on EVERY keystroke while the TOC
-  // panel was open. The panel is derived UI, so recomputing ~300ms after typing
-  // settles keeps it correct without doing an all-headings scan per keystroke
-  // (#343, PART 7). `useDebouncedCallback` returns a stable reference and always
-  // invokes the latest `handleUpdate`.
-  const debouncedHandleUpdate = useDebouncedCallback(handleUpdate, 300);
-
   useEffect(() => {
-    props.editor?.on("update", debouncedHandleUpdate);
+    props.editor?.on("update", handleUpdate);
 
     return () => {
-      props.editor?.off("update", debouncedHandleUpdate);
+      props.editor?.off("update", handleUpdate);
     };
-  }, [props.editor, debouncedHandleUpdate]);
+  }, [props.editor]);
 
   useEffect(
     () => {

apps/client/src/features/editor/components/video/video-menu.tsx

@@ -31,13 +31,6 @@ export function VideoMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
-      // #343 PART 1: skip getAttributes + alignment isActive() probes unless a
-      // video is active. The menu only shows for an active video (shouldShow),
-      // so the null state while inactive is never rendered — behavior unchanged.
-      if (!ctx.editor.isActive("video")) {
-        return null;
-      }
-
       const videoAttrs = ctx.editor.getAttributes("video");
 
       return {

apps/client/src/features/editor/extensions/extensions.ts

@@ -81,8 +81,8 @@ import {
   createResizeHandle,
   buildResizeClasses,
 } from "@/features/editor/components/common/node-resize-handles.ts";
-import MathInlineView from "@/features/editor/components/math/math-inline-lazy.tsx";
+import MathInlineView from "@/features/editor/components/math/math-inline.tsx";
-import MathBlockView from "@/features/editor/components/math/math-block-lazy.tsx";
+import MathBlockView from "@/features/editor/components/math/math-block.tsx";
 import ImageView from "@/features/editor/components/image/image-view.tsx";
 import CalloutView from "@/features/editor/components/callout/callout-view.tsx";
 import StatusView from "@/features/editor/components/status/status-view.tsx";
@@ -90,7 +90,7 @@ import VideoView from "@/features/editor/components/video/video-view.tsx";
 import AudioView from "@/features/editor/components/audio/audio-view.tsx";
 import AttachmentView from "@/features/editor/components/attachment/attachment-view.tsx";
 import CodeBlockView from "@/features/editor/components/code-block/code-block-view.tsx";
-import DrawioView from "../components/drawio/drawio-view-lazy.tsx";
+import DrawioView from "../components/drawio/drawio-view";
 import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-view-lazy.tsx";
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import HtmlEmbedView from "@/features/editor/components/html-embed/html-embed-view.tsx";

apps/client/src/features/editor/extensions/slash-command.ts

@@ -6,23 +6,6 @@ import getSuggestionItems from '@/features/editor/components/slash-menu/menu-ite
 
 export const slashMenuPluginKey = new PluginKey('slash-command');
 
-// getSuggestionItems fuzzy-matches EVERY command against the query (plus its
-// wrong-keyboard-layout remaps) and, while the slash menu is open, is invoked
-// TWICE per keystroke: once by the synchronous `allow` gate below and once by
-// the popup's `items` builder. A synchronous gating predicate can't be
-// debounced without breaking the suggestion decoration/activation, so instead we
-// memoize the LAST query's result: the two same-query calls in one keystroke
-// build the list only once, and the cache invalidates the moment the query
-// changes — so there is no stale-state risk (#343, PART 7).
-let lastQuery: string | null = null;
-let lastResult: ReturnType<typeof getSuggestionItems> | null = null;
-function suggestionItemsForQuery(query: string) {
-  if (query === lastQuery && lastResult) return lastResult;
-  lastQuery = query;
-  lastResult = getSuggestionItems({ query });
-  return lastResult;
-}
-
 // @ts-ignore
 const Command = Extension.create({
   name: 'slash-command',
@@ -55,7 +38,7 @@ const Command = Extension.create({
           // non-matching queries while keeping multi-word matches (e.g.
           // "/Heading 1") working.
           const query = state.doc.textBetween(range.from + 1, range.to);
-          const groups = suggestionItemsForQuery(query);
+          const groups = getSuggestionItems({ query });
           const hasMatches = Object.values(groups).some(
             (items) => items.length > 0,
           );
@@ -78,9 +61,7 @@ const Command = Extension.create({
 
 const SlashCommand = Command.configure({
   suggestion: {
-    // Share the per-query memo with `allow` so the pair of same-query calls in a
+    items: getSuggestionItems,
-    // single keystroke rebuilds the list once (#343, PART 7).
-    items: ({ query }: { query: string }) => suggestionItemsForQuery(query),
     render: renderItems,
   },
 });

apps/client/src/features/editor/gitmost/gitmost-global-bridge.tsx

@@ -1,17 +1,8 @@
 import { useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 import { getDefaultStore } from "jotai";
-
+import { WebSocketStatus } from "@hocuspocus/provider";
-// Literal value of WebSocketStatus.Connected from @hocuspocus/provider. Inlined
+import { Editor } from "@tiptap/core";
-// so this always-mounted global bridge does not statically import
-// @hocuspocus/provider — that import pulls Yjs (and, through a shared chunk, the
-// whole TipTap engine) into the eager startup graph. yjsConnectionStatusAtom
-// already stores these raw status strings.
-const YJS_STATUS_CONNECTED = "connected";
-// Type-only: importing Editor as a type keeps @tiptap/core (the whole editor
-// engine) out of the eager global-shell graph — the bridge only uses it for
-// annotations/casts, never as a runtime value.
-import type { Editor } from "@tiptap/core";
 import {
   pageEditorAtom,
   yjsConnectionStatusAtom,
@@ -25,19 +16,16 @@ import {
   getSidebarPages,
 } from "@/features/page/services/page-service.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-// Types are erased at build time, so importing them does not pull the module's
+import {
-// runtime (which drags in @tiptap + the editor-ext barrel). The actual recording
-// helpers are dynamically imported at call time inside createPageWithRecording,
-// keeping the editor engine out of the eager global-shell startup graph — the
-// bridge is mounted for every authenticated user but recording is a rare,
-// native-host-driven action.
-import type {
   GitmostBridge,
   GitmostCreatePagePayload,
   GitmostCreatePageResult,
   GitmostListPagesPayload,
   GitmostListPagesResult,
   GitmostListSpacesResult,
+  gitmostDecodePayloadToFile,
+  gitmostInsertTranscriptIntoEditor,
+  gitmostUploadFileToEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
 
 // How long to wait for a freshly-navigated page's editor to mount, become
@@ -70,7 +58,7 @@ function gitmostWaitForEditor(
         !editor.isDestroyed &&
         editor.isEditable &&
         editorPageId === pageId &&
-        yjsStatus === YJS_STATUS_CONNECTED;
+        yjsStatus === WebSocketStatus.Connected;
       if (ready) {
         resolve(editor);
         return;
@@ -184,15 +172,6 @@ export default function GitmostGlobalBridge() {
           };
         }
 
-        // Load the recording helpers on demand (see the import note above). This
-        // is the only place they are needed, so the @tiptap/editor-ext code they
-        // pull in stays out of the eager startup graph.
-        const {
-          gitmostDecodePayloadToFile,
-          gitmostUploadFileToEditor,
-          gitmostInsertTranscriptIntoEditor,
-        } = await import("@/features/editor/gitmost/gitmost-recording.ts");
-
         // Validate/decode the recording BEFORE creating the page so a bad
         // payload never leaves an empty junk page behind. Per the createPage
         // error contract, any decode failure collapses to "insert-failed" (the

apps/client/src/features/editor/hooks/use-page-content-cache.test.ts

@@ -1,100 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-import type { MutableRefObject } from "react";
-import type { Editor } from "@tiptap/react";
-
-// Mock the app entry so importing the hook doesn't boot the whole app; the hook
-// only needs queryClient's cache read/write, which we stub here. Declared via
-// vi.hoisted so the spies exist before the hoisted vi.mock factory runs.
-const { getQueryData, setQueryData } = vi.hoisted(() => ({
-  getQueryData: vi.fn(() => undefined as unknown),
-  setQueryData: vi.fn(),
-}));
-vi.mock("@/main.tsx", () => ({
-  queryClient: { getQueryData, setQueryData },
-}));
-
-import { usePageContentCache } from "./use-page-content-cache";
-
-const SNAPSHOT = { type: "doc", content: [] };
-
-function makeFakeEditor(overrides: Partial<Editor> = {}): Editor {
-  return {
-    isEmpty: false,
-    isDestroyed: false,
-    getJSON: vi.fn(() => SNAPSHOT),
-    ...overrides,
-  } as unknown as Editor;
-}
-
-describe("usePageContentCache (#343 PART 3) — getJSON off the keystroke path", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    vi.clearAllMocks();
-    // A cached page exists so the write path runs.
-    getQueryData.mockReturnValue({ id: "p1", content: {} });
-  });
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("onUpdate (calling the debounced fn) does NOT call getJSON synchronously", () => {
-    const editor = makeFakeEditor();
-    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
-
-    const { result } = renderHook(() =>
-      usePageContentCache(editorRef, "slug-1", 3000),
-    );
-
-    // Simulate a keystroke's onUpdate -> only schedules the debounce.
-    act(() => {
-      result.current();
-      result.current();
-      result.current();
-    });
-
-    // The whole-doc serialization must NOT have happened yet.
-    expect(editor.getJSON).not.toHaveBeenCalled();
-    expect(setQueryData).not.toHaveBeenCalled();
-
-    // Once the debounce window elapses, getJSON runs exactly once (not per call).
-    act(() => vi.advanceTimersByTime(3000));
-    expect(editor.getJSON).toHaveBeenCalledTimes(1);
-    expect(setQueryData).toHaveBeenCalledWith(["pages", "slug-1"], {
-      id: "p1",
-      content: SNAPSHOT,
-    });
-  });
-
-  it("flushes the pending snapshot on unmount so the last edit isn't lost", () => {
-    const editor = makeFakeEditor();
-    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
-
-    const { result, unmount } = renderHook(() =>
-      usePageContentCache(editorRef, "slug-1", 3000),
-    );
-
-    act(() => result.current());
-    expect(editor.getJSON).not.toHaveBeenCalled();
-
-    // Navigation/unmount must flush (not drop) the pending write.
-    act(() => unmount());
-    expect(editor.getJSON).toHaveBeenCalledTimes(1);
-    expect(setQueryData).toHaveBeenCalledTimes(1);
-  });
-
-  it("skips the write when the editor is destroyed (flush racing teardown)", () => {
-    const editor = makeFakeEditor({ isDestroyed: true });
-    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
-
-    const { result } = renderHook(() =>
-      usePageContentCache(editorRef, "slug-1", 3000),
-    );
-
-    act(() => result.current());
-    act(() => vi.advanceTimersByTime(3000));
-
-    expect(editor.getJSON).not.toHaveBeenCalled();
-    expect(setQueryData).not.toHaveBeenCalled();
-  });
-});

apps/client/src/features/editor/hooks/use-page-content-cache.ts

@@ -1,50 +0,0 @@
-import type { MutableRefObject } from "react";
-import { useDebouncedCallback } from "@mantine/hooks";
-import type { Editor } from "@tiptap/react";
-import { queryClient } from "@/main.tsx";
-import { IPage } from "@/features/page/types/page.types.ts";
-
-/**
- * Off-keystroke local page-cache updater (issue #343, PART 3).
- *
- * The editor's `onUpdate` fires on every keystroke — and, under collaboration,
- * on every REMOTE keystroke too. Serializing the WHOLE document with
- * `editor.getJSON()` on that hot path is expensive, and the previous 3s debounce
- * only guarded the cache WRITE, not the serialization: `getJSON()` still ran per
- * keystroke.
- *
- * This hook moves the serialization INSIDE the debounced callback, so the
- * full-doc traversal happens at most once per `delay`, not per keystroke. Call
- * the returned function from `onUpdate` (it only schedules the debounce); the
- * `getJSON()` snapshot is taken when the debounce fires.
- *
- * On unmount/navigation the pending snapshot is FLUSHED (via `flushOnUnmount`)
- * so the last edits within the debounce window aren't lost from the local cache.
- * The source of truth is collab/Yjs, but the cache must not go stale.
- *
- * IMPORTANT: call this hook BEFORE `useEditor`. React runs effect cleanups in
- * declaration order on unmount, so the debounce's flush cleanup must be declared
- * before `useEditor`'s teardown to run while the editor is still alive; the
- * `isDestroyed` guard keeps a flush that still races teardown safe (it skips).
- */
-export function usePageContentCache(
-  editorRef: MutableRefObject<Editor | null>,
-  slugId: string | undefined,
-  delay = 3000,
-) {
-  return useDebouncedCallback(
-    () => {
-      const e = editorRef.current;
-      if (!e || e.isDestroyed || e.isEmpty) return;
-      const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-      if (pageData) {
-        // getJSON() (full-doc serialization) runs HERE, off the keystroke path.
-        queryClient.setQueryData(["pages", slugId], {
-          ...pageData,
-          content: e.getJSON(),
-        });
-      }
-    },
-    { delay, flushOnUnmount: true },
-  );
-}

apps/client/src/features/editor/page-editor.tsx

@@ -59,10 +59,10 @@ import {
   handlePaste,
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
-import DrawioMenu from "./components/drawio/drawio-menu-lazy";
+import DrawioMenu from "./components/drawio/drawio-menu";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDocumentVisibility } from "@mantine/hooks";
+import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
 import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
@@ -79,7 +79,6 @@ import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
-import { usePageContentCache } from "./hooks/use-page-content-cache";
 import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
 import { useSwapHeightReservation } from "./hooks/use-swap-height-reservation";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -273,13 +272,8 @@ export default function PageEditor({
     }
   }, [isIdle, documentState, providersReady, resetIdle]);
 
-  // Attach the remote provider once it's ready (and again after a pageId swap
+  // Attach here, to make sure the connection gets properly established
-  // recreates it) to make sure the connection gets properly established. This
-  // used to run in the render body — a side effect during render (#343, PART 7).
-  // `attach()` is idempotent, so re-running it on these deps is safe.
-  useEffect(() => {
   providersRef.current?.remote.attach();
-  }, [providersReady, pageId]);
 
   const extensions = useMemo(() => {
     if (!providersReady || !providersRef.current || !currentUser?.user) {
@@ -294,12 +288,6 @@ export default function PageEditor({
     ];
   }, [providersReady, currentUser?.user]);
 
-  // getJSON() serialization + cache write live in the hook, off the keystroke
-  // path, and flush on unmount so the last snapshot survives navigation (#343).
-  // MUST be declared before useEditor: React runs effect cleanups in declaration
-  // order on unmount, so the flush must run before the editor is torn down.
-  const debouncedUpdateContent = usePageContentCache(editorRef, slugId);
-
   const editor = useEditor(
     {
       extensions,
@@ -404,11 +392,11 @@ export default function PageEditor({
           }
         }
       },
-      onUpdate() {
+      onUpdate({ editor }) {
-        // Only schedule the debounce here — the whole-doc getJSON() serialization
+        if (editor.isEmpty) return;
-        // happens INSIDE the debounced callback (see usePageContentCache), so it
+        const editorJson = editor.getJSON();
-        // no longer runs synchronously on every (local or remote) keystroke.
+        //update local page cache to reduce flickers
-        debouncedUpdateContent();
+        debouncedUpdateContent(editorJson);
       },
     },
     [pageId, editable, extensions],
@@ -454,6 +442,17 @@ export default function PageEditor({
     };
   }, [editor, pageId, editorIsEditable]);
 
+  const debouncedUpdateContent = useDebouncedCallback((newContent: any) => {
+    const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+
+    if (pageData) {
+      queryClient.setQueryData(["pages", slugId], {
+        ...pageData,
+        content: newContent,
+      });
+    }
+  }, 3000);
+
   const handleActiveCommentEvent = (event) => {
     const { commentId, resolved } = event.detail;
 

apps/client/src/features/editor/utils/get-editor-selection.test.ts

@@ -1,113 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { Editor } from "@tiptap/core";
-import { Document } from "@tiptap/extension-document";
-import { Paragraph } from "@tiptap/extension-paragraph";
-import { Text } from "@tiptap/extension-text";
-import { EditorState, TextSelection } from "@tiptap/pm/state";
-import type { Node as PMNode } from "@tiptap/pm/model";
-import { UniqueID } from "@docmost/editor-ext";
-import { getEditorSelectionContext } from "./get-editor-selection";
-
-/**
- * Unit tests for getEditorSelectionContext (#388). Built on a headless
- * ProseMirror schema (Document + Paragraph + Text + the block-id UniqueID
- * extension), mirroring the editor-ext test style. We assemble docs with
- * explicit block ids so the covered-blockIds assertions are deterministic.
- */
-
-// A schema that carries the `id` block attribute (UniqueID) on paragraphs, just
-// like the real editor.
-const { schema } = new Editor({
-  extensions: [
-    Document,
-    Paragraph,
-    Text,
-    UniqueID.configure({ types: ["paragraph"] }),
-  ],
-  content: "",
-});
-
-function docOf(blocks: { id: string; text: string }[]): PMNode {
-  return schema.node(
-    "doc",
-    null,
-    blocks.map((b) =>
-      schema.node("paragraph", { id: b.id }, b.text ? schema.text(b.text) : []),
-    ),
-  );
-}
-
-function stateWith(doc: PMNode, from: number, to: number): EditorState {
-  const base = EditorState.create({ schema, doc });
-  return base.apply(base.tr.setSelection(TextSelection.create(doc, from, to)));
-}
-
-// Select every text position of the doc (pos 1 .. content.size - 1).
-function selectAll(doc: PMNode): EditorState {
-  return stateWith(doc, 1, doc.content.size - 1);
-}
-
-describe("getEditorSelectionContext", () => {
-  it("returns null for an empty (collapsed) selection", () => {
-    const doc = docOf([{ id: "b1", text: "Hello world" }]);
-    const state = stateWith(doc, 3, 3); // caret, from === to
-    expect(getEditorSelectionContext(state)).toBeNull();
-  });
-
-  it("returns null for the default caret-at-start of a fresh editor", () => {
-    const editor = new Editor({
-      extensions: [
-        Document,
-        Paragraph,
-        Text,
-        UniqueID.configure({ types: ["paragraph"] }),
-      ],
-      content: "<p>fresh</p>",
-    });
-    expect(getEditorSelectionContext(editor.state)).toBeNull();
-    editor.destroy();
-  });
-
-  it("reads a single-paragraph selection with no block-separator artifacts", () => {
-    const doc = docOf([{ id: "b1", text: "Hello world" }]);
-    const sel = getEditorSelectionContext(selectAll(doc))!;
-    expect(sel.text).toBe("Hello world");
-    expect(sel.blockIds).toEqual(["b1"]);
-    expect(sel.truncated).toBeUndefined();
-  });
-
-  it("joins multiple blocks with a newline and collects all covered blockIds", () => {
-    const doc = docOf([
-      { id: "b1", text: "First" },
-      { id: "b2", text: "Second" },
-    ]);
-    const sel = getEditorSelectionContext(selectAll(doc))!;
-    expect(sel.text).toBe("First\nSecond");
-    expect(sel.blockIds).toEqual(["b1", "b2"]);
-  });
-
-  it("caps the text at 2000 chars and flags truncated", () => {
-    const doc = docOf([{ id: "b1", text: "x".repeat(2500) }]);
-    const sel = getEditorSelectionContext(selectAll(doc))!;
-    expect(sel.text).toHaveLength(2000);
-    expect(sel.truncated).toBe(true);
-  });
-
-  it("computes before/after context and clamps it to the doc bounds", () => {
-    // One paragraph "0123456789abcdefghij"; select the middle "56789".
-    const doc = docOf([{ id: "b1", text: "0123456789abcdefghij" }]);
-    // text char i lives at pos (1 + i); select chars index 5..9 -> pos 6..11.
-    const sel = getEditorSelectionContext(stateWith(doc, 6, 11))!;
-    expect(sel.text).toBe("56789");
-    expect(sel.before).toBe("01234");
-    expect(sel.after).toBe("abcdefghij");
-  });
-
-  it("omits before/after at the document boundaries (never reads past 0/size)", () => {
-    const doc = docOf([{ id: "b1", text: "Edge" }]);
-    const sel = getEditorSelectionContext(selectAll(doc))!;
-    // Selection spans the whole single block: nothing before or after it.
-    expect(sel.before).toBeUndefined();
-    expect(sel.after).toBeUndefined();
-  });
-});

apps/client/src/features/editor/utils/get-editor-selection.ts

@@ -1,71 +0,0 @@
-import type { EditorState } from "@tiptap/pm/state";
-
-export interface EditorSelectionContext {
-  text: string;
-  truncated?: boolean;
-  blockIds?: string[];
-  before?: string;
-  after?: string;
-}
-
-// Client-side caps. The server re-caps every field independently (defence in
-// depth — the payload is attacker-controllable), so these only keep the wire
-// small for the common case.
-const TEXT_CAP = 2000;
-const CONTEXT_CHARS = 160;
-const MAX_BLOCK_IDS = 20;
-
-// Pure: takes an EditorState so it is unit-testable with a headless editor.
-// Snapshots the user's current selection into the wire shape carried inside
-// openPage — plain text + the ids of the blocks it covers + a little surrounding
-// context. Returns null when nothing meaningful is selected.
-//
-// Deliberately does NOT emit the ProseMirror positions (from/to): they rot the
-// instant the document changes and the server tools address content by block id
-// + text (getNode / editPageText find-replace), never by position.
-export function getEditorSelectionContext(
-  state: EditorState,
-): EditorSelectionContext | null {
-  const { selection, doc } = state;
-  // An empty selection (incl. the default caret-at-start of a fresh editor) is
-  // never a "this"/"here" — bail before reading any text.
-  if (selection.empty) return null;
-
-  const { from, to } = selection;
-
-  let text = doc.textBetween(from, to, "\n");
-  let truncated = false;
-  if (text.length > TEXT_CAP) {
-    text = text.slice(0, TEXT_CAP);
-    truncated = true;
-  }
-  // A selection spanning only non-text nodes (e.g. an image) trims to empty ->
-  // treat as no selection.
-  if (text.trim().length === 0) return null;
-
-  // Ids of every block the selection covers, deduped and capped. These bridge
-  // the plain-text selection to the server tools (getNode / editPageText).
-  const blockIds: string[] = [];
-  doc.nodesBetween(from, to, (node) => {
-    const id = node.isBlock ? node.attrs?.id : undefined;
-    if (typeof id === "string" && id.length > 0 && !blockIds.includes(id)) {
-      blockIds.push(id);
-    }
-  });
-
-  // ~160 chars of plain text on each side, clamped to the document bounds, so
-  // editPageText can disambiguate a duplicate of the selected text.
-  const before = doc.textBetween(Math.max(0, from - CONTEXT_CHARS), from, "\n");
-  const after = doc.textBetween(
-    to,
-    Math.min(doc.content.size, to + CONTEXT_CHARS),
-    "\n",
-  );
-
-  const result: EditorSelectionContext = { text };
-  if (truncated) result.truncated = true;
-  if (blockIds.length > 0) result.blockIds = blockIds.slice(0, MAX_BLOCK_IDS);
-  if (before.length > 0) result.before = before;
-  if (after.length > 0) result.after = after;
-  return result;
-}

apps/client/src/features/favorite/queries/favorite-query.ts

@@ -24,6 +24,7 @@ export function useFavoritesQuery(type?: FavoriteType, spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
+    refetchOnMount: true,
   });
 }
 
@@ -31,6 +32,7 @@ export function useFavoriteIds(type: FavoriteType, spaceId?: string): Set<string
   const { data } = useQuery({
     queryKey: ["favorite-ids", type, spaceId],
     queryFn: () => getFavoriteIds(type, spaceId),
+    refetchOnMount: true,
   });
 
   const items = data?.items;

apps/client/src/features/page-details/components/page-details-aside.tsx

@@ -12,7 +12,7 @@ import { useAtomValue } from "jotai";
 import { useParams } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { extractPageSlugId } from "@/lib";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useBacklinksCountQuery } from "@/features/page-details/queries/backlinks-query.ts";
 import { BacklinksModal } from "./backlinks-modal";
@@ -23,7 +23,7 @@ import { LabelsSection } from "@/features/label/components/labels-section.tsx";
 
 export function PageDetailsAside() {
   const { pageSlug } = useParams();
-  const { data: page } = usePageMetaQuery({
+  const { data: page } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const pageEditor = useAtomValue(pageEditorAtom);

apps/client/src/features/page-history/components/history-item.test.tsx

@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
+import { render, screen, cleanup, within } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+
+// Mantine Tooltip mounts its label lazily on hover via Floating UI, which is
+// flaky under jsdom. Replace ONLY the Tooltip with a thin wrapper that renders
+// the label inline (keeping Badge/Switch/etc. real), so the provenance label —
+// the contract we care about — is deterministically queryable.
+vi.mock("@mantine/core", async () => {
+  const actual =
+    await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
+  const Tooltip = ({
+    label,
+    children,
+  }: {
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+  }) => (
+    <>
+      {children}
+      <span data-testid="tooltip-label">{label}</span>
+    </>
+  );
+  Tooltip.Group = ({ children }: { children?: React.ReactNode }) => (
+    <>{children}</>
+  );
+  return { ...actual, Tooltip };
+});
+
+// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
+beforeAll(() => {
+  if (!window.matchMedia) {
+    window.matchMedia = (query: string) =>
+      ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => false,
+      }) as unknown as MediaQueryList;
+  }
+});
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// HistoryItem pulls in i18n, jotai atoms (ai-chat / history), a config-backed
+// avatar and a time formatter. The provenance-badge contract is the unit under
+// test, so we stub everything else down to inert, deterministic renders and
+// keep the real Mantine Badge/Tooltip so role/label queries are meaningful.
+
+// i18n: interpolate {{name}} so the git-sync tooltip carries the author name,
+// letting us assert provenance attribution without a real i18n backend.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, vars?: Record<string, unknown>) =>
+      vars && typeof vars.name !== "undefined"
+        ? key.replace("{{name}}", String(vars.name))
+        : key,
+  }),
+}));
+
+// jotai setters: the badges call useSetAtom; return inert setters so a click on
+// the (deep-linkable) AiAgentBadge would fire these — proving the git-sync badge
+// does NOT wire any of them.
+const setAiChatWindowOpen = vi.fn();
+const setActiveChatId = vi.fn();
+const setDraft = vi.fn();
+const setHistoryModalOpen = vi.fn();
+vi.mock("jotai", async () => {
+  const actual = await vi.importActual<typeof import("jotai")>("jotai");
+  return {
+    ...actual,
+    useSetAtom: (atom: unknown) => {
+      switch (atom) {
+        case aiChatWindowOpenAtom:
+          return setAiChatWindowOpen;
+        case activeAiChatIdAtom:
+          return setActiveChatId;
+        case aiChatDraftAtom:
+          return setDraft;
+        case historyAtoms:
+          return setHistoryModalOpen;
+        default:
+          return vi.fn();
+      }
+    },
+  };
+});
+
+// Atoms are imported only as identity tokens for the useSetAtom switch above.
+vi.mock("@/features/ai-chat/atoms/ai-chat-atom.ts", () => ({
+  activeAiChatIdAtom: { __tag: "activeAiChatIdAtom" },
+  aiChatWindowOpenAtom: { __tag: "aiChatWindowOpenAtom" },
+  aiChatDraftAtom: { __tag: "aiChatDraftAtom" },
+}));
+vi.mock("@/features/page-history/atoms/history-atoms.ts", () => ({
+  historyAtoms: { __tag: "historyAtoms" },
+}));
+
+// Avatar reaches into config (getAvatarUrl) — stub to a plain element.
+vi.mock("@/components/ui/custom-avatar.tsx", () => ({
+  CustomAvatar: ({ name }: { name?: string }) => (
+    <span data-testid="avatar">{name}</span>
+  ),
+}));
+
+// Deterministic, locale-free date string.
+vi.mock("@/lib/time", () => ({
+  formattedDate: () => "2026-06-21",
+}));
+
+import HistoryItem from "./history-item";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
+import type { IPageHistory } from "@/features/page-history/types/page.types";
+
+function makeItem(overrides: Partial<IPageHistory> = {}): IPageHistory {
+  return {
+    id: "h1",
+    pageId: "p1",
+    title: "Title",
+    slug: "slug",
+    icon: "",
+    coverPhoto: "",
+    version: 1,
+    lastUpdatedById: "u1",
+    workspaceId: "w1",
+    createdAt: "2026-06-21T00:00:00.000Z",
+    updatedAt: "2026-06-21T00:00:00.000Z",
+    lastUpdatedBy: { id: "u1", name: "Alice", avatarUrl: "" },
+    ...overrides,
+  };
+}
+
+function renderItem(item: IPageHistory) {
+  return render(
+    <MantineProvider>
+      <HistoryItem
+        historyItem={item}
+        index={0}
+        onSelect={vi.fn()}
+        isActive={false}
+      />
+    </MantineProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("HistoryItem git-sync provenance badge", () => {
+  // Test 1: the git-sync badge renders ONLY for lastUpdatedSource === 'git-sync'.
+  it("renders the Git sync badge only when lastUpdatedSource is 'git-sync'", () => {
+    renderItem(makeItem({ lastUpdatedSource: "git-sync" }));
+    expect(screen.getByText("Git sync")).toBeTruthy();
+  });
+
+  it.each([
+    ["agent", "agent"],
+    ["user", "user"],
+    ["undefined", undefined],
+  ])(
+    "does NOT render the Git sync badge when lastUpdatedSource is %s",
+    (_label, source) => {
+      renderItem(makeItem({ lastUpdatedSource: source }));
+      expect(screen.queryByText("Git sync")).toBeNull();
+    },
+  );
+
+  // Test 2: provenance attribution + the git-sync badge is NOT interactive.
+  it("attributes the git-sync provenance to the correct author and is not clickable", () => {
+    renderItem(
+      makeItem({
+        lastUpdatedSource: "git-sync",
+        lastUpdatedBy: { id: "u2", name: "Bob", avatarUrl: "" },
+      }),
+    );
+
+    const badge = screen.getByText("Git sync");
+
+    // Provenance attribution: the tooltip label carries the author name (the
+    // git-sync badge passes authorName -> "Synced from Git on behalf of {{name}}").
+    expect(screen.getByText("Synced from Git on behalf of Bob")).toBeTruthy();
+
+    // The git-sync badge must NOT behave like AiAgentBadge: the badge element
+    // itself is not a button, carries no role=button and no tabIndex, and
+    // clicking it must not trigger any ai-chat deep-link. (The surrounding
+    // history-row IS an UnstyledButton — that is the row's own select affordance,
+    // not the badge — so we scope these checks to the badge element.)
+    const badgeRoot = (badge.closest("[class*='mantine-Badge-root']") ??
+      badge) as HTMLElement;
+    expect(badgeRoot.getAttribute("role")).not.toBe("button");
+    expect(badgeRoot.getAttribute("tabindex")).toBeNull();
+    expect(badgeRoot.tagName.toLowerCase()).not.toBe("button");
+    // No interactive descendant button lives inside the badge itself.
+    expect(within(badgeRoot).queryByRole("button")).toBeNull();
+
+    badgeRoot.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(setActiveChatId).not.toHaveBeenCalled();
+    expect(setAiChatWindowOpen).not.toHaveBeenCalled();
+    expect(setDraft).not.toHaveBeenCalled();
+    expect(setHistoryModalOpen).not.toHaveBeenCalled();
+  });
+
+  // Sanity contrast: the agent provenance IS interactive when it carries an
+  // aiChatId — proving the not-clickable assertion above is real. The old text
+  // `AiAgentBadge` was superseded by `AgentAvatarStack` (#300), which becomes a
+  // role=button deep-link (and fires the ai-chat atoms) when an aiChatId is present.
+  it("contrast: the agent stack is a deep-link button when it has an aiChatId", () => {
+    renderItem(
+      makeItem({
+        lastUpdatedSource: "agent",
+        agent: { name: "Zeta" },
+        lastUpdatedAiChatId: "chat-1",
+      }),
+    );
+    // The agent glyph lives inside the clickable stack; walk up to its role=button.
+    const root = screen.getByTestId("agent-glyph").closest("[role='button']");
+    expect(root).not.toBeNull();
+    (root as HTMLElement).dispatchEvent(
+      new MouseEvent("click", { bubbles: true }),
+    );
+    expect(setActiveChatId).toHaveBeenCalledWith("chat-1");
+    expect(setAiChatWindowOpen).toHaveBeenCalled();
+  });
+});

apps/client/src/features/page-history/components/history-item.tsx

@@ -1,5 +1,6 @@
 import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import { GitSyncBadge } from "@/components/ui/git-sync-badge.tsx";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
 import classes from "./css/history.module.css";
@@ -41,6 +42,7 @@ const HistoryItem = memo(function HistoryItem({
   const contributors = historyItem.contributors;
   const hasContributors = contributors && contributors.length > 0;
   const isAgentEdit = historyItem.lastUpdatedSource === "agent";
+  const isGitSyncEdit = historyItem.lastUpdatedSource === "git-sync";
 
   return (
     <UnstyledButton
@@ -109,6 +111,10 @@ const HistoryItem = memo(function HistoryItem({
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}
+
+        {isGitSyncEdit && (
+          <GitSyncBadge authorName={historyItem.lastUpdatedBy?.name} />
+        )}
       </Group>
     </UnstyledButton>
   );

apps/client/src/features/page/components/breadcrumbs/breadcrumb-path-equal.test.ts

@@ -1,53 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { SpaceTreeNode } from "@/features/page/tree/types";
-
-// breadcrumb.tsx transitively imports @/main.tsx (via usePageMetaQuery ->
-// queryClient), whose module body calls ReactDOM.createRoot on a null root in
-// jsdom. Stub it so importing the pure helper under test doesn't run that
-// (breadcrumbPathEqual does not use queryClient, so a dummy is enough).
-vi.mock("@/main.tsx", () => ({ queryClient: {} }));
-
-import { breadcrumbPathEqual } from "./breadcrumb";
-
-// breadcrumbPathEqual is the ONLY point where a false-positive equality would
-// leave a stale/incorrect breadcrumb trail on screen: it decides whether the
-// selectAtom hands back the same reference (no re-render) for the ancestor chain.
-// Pin both directions — a too-loose equality goes stale on a rename; a too-tight
-// one loses the perf win.
-const node = (over: Partial<SpaceTreeNode>): SpaceTreeNode =>
-  ({ id: "a", slugId: "sa", name: "A", icon: "📄", ...over }) as SpaceTreeNode;
-
-describe("breadcrumbPathEqual", () => {
-  it("both null → true", () => {
-    expect(breadcrumbPathEqual(null, null)).toBe(true);
-  });
-
-  it("same reference → true", () => {
-    const p = [node({})];
-    expect(breadcrumbPathEqual(p, p)).toBe(true);
-  });
-
-  it("equal by id/slugId/name/icon (different arrays) → true", () => {
-    expect(breadcrumbPathEqual([node({})], [node({})])).toBe(true);
-  });
-
-  it("one side null → false", () => {
-    expect(breadcrumbPathEqual([node({})], null)).toBe(false);
-    expect(breadcrumbPathEqual(null, [node({})])).toBe(false);
-  });
-
-  it("different length → false", () => {
-    expect(
-      breadcrumbPathEqual([node({})], [node({}), node({ id: "b" })]),
-    ).toBe(false);
-  });
-
-  it.each(["name", "icon", "slugId", "id"] as const)(
-    "a changed %s → false (breadcrumb must re-render)",
-    (field) => {
-      expect(
-        breadcrumbPathEqual([node({})], [node({ [field]: "CHANGED" })]),
-      ).toBe(false);
-    },
-  );
-});

apps/client/src/features/page/components/breadcrumbs/breadcrumb.tsx

@@ -1,9 +1,7 @@
 import { useAtomValue } from "jotai";
-import { selectAtom } from "jotai/utils";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { computeBreadcrumbState } from "./breadcrumb.utils";
-import { findBreadcrumbPath } from "@/features/page/tree/utils";
 import {
   Button,
   Anchor,
@@ -20,7 +18,7 @@ import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import {
-  usePageMetaQuery,
+  usePageQuery,
   usePageBreadcrumbsQuery,
 } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
@@ -34,84 +32,39 @@ function getTitle(name: string, icon: string) {
   return name;
 }
 
-/**
- * Equality over a breadcrumb chain by the only fields the breadcrumb renders
- * (id, slugId, name, icon). Lets the selectAtom below hand back the SAME
- * reference when an unrelated tree mutation leaves THIS page's ancestor chain
- * visually unchanged, so the breadcrumb no longer re-renders on every tree
- * event (it previously subscribed to the whole treeDataAtom).
- */
-export function breadcrumbPathEqual(
-  a: SpaceTreeNode[] | null,
-  b: SpaceTreeNode[] | null,
-): boolean {
-  if (a === b) return true;
-  if (!a || !b || a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (
-      a[i].id !== b[i].id ||
-      a[i].slugId !== b[i].slugId ||
-      a[i].name !== b[i].name ||
-      a[i].icon !== b[i].icon
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
 export default function Breadcrumb() {
   const { t } = useTranslation();
+  const treeData = useAtomValue(treeDataAtom);
   const [breadcrumbNodes, setBreadcrumbNodes] = useState<
     SpaceTreeNode[] | null
   >(null);
   const { pageSlug, spaceSlug } = useParams();
-  const { data: currentPage } = usePageMetaQuery({
+  const { data: currentPage } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
-  const currentPageId = currentPage?.id;
   // The page's own ancestor chain, fetched independently of the lazily-built
   // sidebar tree so a deep page doesn't render a blank breadcrumb for seconds
   // while the tree backfills (#218).
-  const { data: ancestors } = usePageBreadcrumbsQuery(currentPageId);
+  const { data: ancestors } = usePageBreadcrumbsQuery(currentPage?.id);
   const isMobile = useMediaQuery("(max-width: 48em)");
 
-  // Narrowed subscription: instead of subscribing to the whole treeDataAtom and
-  // recomputing on every tree event, derive ONLY the current page's ancestor
-  // chain. The custom equality returns the previous reference when that chain is
-  // visually unchanged, so an unrelated tree mutation no longer re-renders this
-  // component. Mirrors computeBreadcrumbState's tree-hit branch
-  // (findBreadcrumbPath); the tree-miss/ancestors fallback is applied below.
-  const treePathAtom = useMemo(
-    () =>
-      selectAtom(
-        treeDataAtom,
-        (tree): SpaceTreeNode[] | null =>
-          currentPageId ? findBreadcrumbPath(tree, currentPageId) : null,
-        breadcrumbPathEqual,
-      ),
-    [currentPageId],
-  );
-  const treePath = useAtomValue(treePathAtom);
-
   useEffect(() => {
     if (!currentPage) return;
 
     // Selection/mapping + stale-clearing live in a pure, unit-tested helper
-    // (#218). The tree-hit chain (treePath) always wins when present; otherwise
+    // (#218). It resolves the correct chain when possible and, on a transient
-    // fall back to the page's own ancestors and the stale-clearing logic — this
+    // miss, clears a chain left over from a previously-viewed page instead of
-    // reproduces computeBreadcrumbState(fullTree, ancestors, …) exactly, since
+    // showing the wrong trail — while keeping a chain already resolved for THIS
-    // its tree-hit branch is precisely findBreadcrumbPath(fullTree, pageId).
+    // page to avoid a blank flash.
     setBreadcrumbNodes((previous) =>
-      treePath ??
       computeBreadcrumbState(
-        null,
+        treeData,
         ancestors as IPage[] | undefined,
         currentPage.id,
         previous,
       ),
     );
-  }, [currentPage?.id, treePath, ancestors]);
+  }, [currentPage?.id, treeData, ancestors]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

apps/client/src/features/page/components/header/page-header-menu.tsx

@@ -24,7 +24,7 @@ import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
 import { useDisclosure, useHotkeys } from "@mantine/hooks";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { useParams } from "react-router-dom";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import {
   useToggleTemporaryMutation,
   syncTemporaryExpiresInCache,
@@ -67,7 +67,7 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
   const commentsTriggerProps = useAsideTriggerProps("comments");
   const tocTriggerProps = useAsideTriggerProps("toc");
   const { pageSlug } = useParams();
-  const { data: page } = usePageMetaQuery({
+  const { data: page } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const isDeleted = !!page?.deletedAt;
@@ -146,7 +146,7 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
   const [, setHistoryModalOpen] = useAtom(historyAtoms);
   const clipboard = useClipboard({ timeout: 500 });
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page, isLoading } = usePageMetaQuery({
+  const { data: page, isLoading } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const { handleDelete } = useTreeMutation(page?.spaceId ?? "");

apps/client/src/features/page/components/temporary-note-banner.tsx

@@ -10,7 +10,7 @@ import { IconClockHour4, IconTrash } from "@tabler/icons-react";
 import { useState } from "react";
 import { Trans, useTranslation } from "react-i18next";
 import { useTimeAgo } from "@/hooks/use-time-ago.tsx";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import {
   useToggleTemporaryMutation,
@@ -35,7 +35,7 @@ type TemporaryNoteBannerProps = {
  */
 export function TemporaryNoteBanner({ slugId }: TemporaryNoteBannerProps) {
   const { t } = useTranslation();
-  const { data: page } = usePageMetaQuery({ pageId: slugId });
+  const { data: page } = usePageQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const expiresTimeAgo = useTimeAgo(page?.temporaryExpiresAt);

apps/client/src/features/page/queries/invalidate-on-update-page.test.ts

@@ -1,149 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import type { IPage } from "@/features/page/types/page.types";
-
-// A fresh QueryClient stands in for the app singleton (importing the real
-// @/main.tsx would run ReactDOM.createRoot, which has no DOM root in jsdom). The
-// factory constructs it (QueryClient can't be referenced in vi.hoisted — that
-// runs before imports resolve); we import the SAME mocked instance back to seed
-// and assert on it.
-vi.mock("@/main.tsx", async () => {
-  const { QueryClient } = await import("@tanstack/react-query");
-  return { queryClient: new QueryClient() };
-});
-
-import { queryClient as h_qc } from "@/main.tsx";
-import { invalidateOnUpdatePage } from "./page-query";
-
-const h = { qc: h_qc };
-
-// invalidateOnUpdatePage is the field-only (title/icon) tree path: instead of a
-// blanket invalidate it patches the affected node IN PLACE in every cached embed
-// subtree. The undefined-guard is LOAD-BEARING: a title-only socket event carries
-// icon:undefined, and without the guard `{...p, icon: undefined}` would WIPE the
-// icon in every cached subtree.
-const page = (over: Partial<IPage>): IPage =>
-  ({ id: "p1", title: "Old", icon: "📄", spaceId: "s1" }) as IPage &
-    typeof over as IPage;
-
-describe("invalidateOnUpdatePage — pointwise embed-cache patch", () => {
-  beforeEach(() => {
-    h.qc.clear();
-  });
-
-  it("title-only event updates title but PRESERVES the icon (undefined-guard)", () => {
-    const key = ["page-tree", "parent-1"];
-    h.qc.setQueryData<IPage[]>(key, [
-      { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
-      { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
-    ]);
-
-    // icon passed as undefined (a title-only update)
-    invalidateOnUpdatePage(
-      "s1",
-      "parent-1",
-      "p1",
-      "New Title",
-      undefined as unknown as string,
-    );
-
-    const patched = h.qc.getQueryData<IPage[]>(key)!;
-    const p1 = patched.find((p) => p.id === "p1")!;
-    const p2 = patched.find((p) => p.id === "p2")!;
-    expect(p1.title).toBe("New Title");
-    expect(p1.icon).toBe("📄"); // preserved, not wiped
-    // Sibling node untouched.
-    expect(p2.title).toBe("Other");
-    expect(p2.icon).toBe("📁");
-  });
-
-  it("icon-only event updates icon but preserves the title", () => {
-    const key = ["page-tree", "parent-1"];
-    h.qc.setQueryData<IPage[]>(key, [
-      { id: "p1", title: "Keep", icon: "📄", spaceId: "s1" } as IPage,
-    ]);
-
-    invalidateOnUpdatePage(
-      "s1",
-      "parent-1",
-      "p1",
-      undefined as unknown as string,
-      "🚀",
-    );
-
-    const p1 = h.qc.getQueryData<IPage[]>(key)!.find((p) => p.id === "p1")!;
-    expect(p1.icon).toBe("🚀");
-    expect(p1.title).toBe("Keep");
-  });
-
-  // The sidebar-pages cache (InfiniteData) is patched on the same event. It must
-  // carry the SAME undefined-guard as the embed path above — otherwise a
-  // title-only event's icon:undefined would wipe the sidebar entry's icon.
-  const sidebarKey = ["sidebar-pages", { pageId: "parent-1", spaceId: "s1" }];
-  const seedSidebar = () =>
-    h.qc.setQueryData(sidebarKey, {
-      pageParams: [undefined],
-      pages: [
-        {
-          items: [
-            { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
-            { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
-          ],
-        },
-      ],
-    });
-  const sidebarItem = (id: string) => {
-    const data = h.qc.getQueryData(sidebarKey) as {
-      pages: { items: IPage[] }[];
-    };
-    return data.pages[0].items.find((p) => p.id === id)!;
-  };
-
-  it("sidebar cache: title-only event updates title but PRESERVES the icon", () => {
-    seedSidebar();
-
-    invalidateOnUpdatePage(
-      "s1",
-      "parent-1",
-      "p1",
-      "New Title",
-      undefined as unknown as string,
-    );
-
-    const p1 = sidebarItem("p1");
-    expect(p1.title).toBe("New Title");
-    expect(p1.icon).toBe("📄"); // preserved, not wiped
-    // Sibling untouched.
-    const p2 = sidebarItem("p2");
-    expect(p2.title).toBe("Other");
-    expect(p2.icon).toBe("📁");
-  });
-
-  it("sidebar cache: icon-only event updates icon but PRESERVES the title", () => {
-    seedSidebar();
-
-    invalidateOnUpdatePage(
-      "s1",
-      "parent-1",
-      "p1",
-      undefined as unknown as string,
-      "🚀",
-    );
-
-    const p1 = sidebarItem("p1");
-    expect(p1.icon).toBe("🚀");
-    expect(p1.title).toBe("Old"); // preserved, not wiped
-  });
-
-  it("does not touch a subtree that lacks the updated node", () => {
-    const otherKey = ["page-tree", "unrelated"];
-    const before = [
-      { id: "x1", title: "X", icon: "❌", spaceId: "s1" } as IPage,
-    ];
-    h.qc.setQueryData<IPage[]>(otherKey, before);
-
-    invalidateOnUpdatePage("s1", "parent-1", "p1", "New", "🚀");
-
-    // Same reference back — the subtree without p1 is left as-is.
-    expect(h.qc.getQueryData<IPage[]>(otherKey)).toBe(before);
-  });
-});

apps/client/src/features/page/queries/page-query.ts

@@ -51,10 +51,6 @@ export function usePageQuery(
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
-    // Keep the previously-loaded page visible while navigating to a new one
-    // instead of flashing a blank/skeleton frame (the new page's content
-    // streams in when ready). isLoading stays true only for the very first load.
-    placeholderData: keepPreviousData,
   });
 
   useEffect(() => {
@@ -70,61 +66,6 @@ export function usePageQuery(
   return query;
 }
 
-/**
- * A page view that omits the large, frequently-changing `content` field. Every
- * other field is preserved, so consumers that read only metadata (title, icon,
- * permissions, id, creator, timestamps, …) keep working unchanged.
- */
-export type IPageMeta = Omit<IPage, "content">;
-
-function selectPageMeta(page: IPage): IPageMeta {
-  // Drop `content`; react-query's structural sharing (replaceEqualDeep) then
-  // returns the SAME reference whenever the remaining fields are unchanged, so a
-  // pure content churn (typing / debouncedUpdateContent, collab `page.updated`)
-  // no longer changes this slice's identity and its ~13 subscribers don't
-  // re-render on every keystroke wave.
-  const { content: _content, ...meta } = page;
-  return meta as IPageMeta;
-}
-
-/**
- * Metadata-only variant of {@link usePageQuery}. Shares the SAME query cache
- * entry (`["pages", pageId]`, full object incl. content), but this hook returns
- * a stable content-less slice so peripheral subscribers stop re-rendering on
- * every content update. Use it anywhere the full `content` is not read.
- */
-export function usePageMetaQuery(
-  pageInput: Partial<IPageInput>,
-): UseQueryResult<IPageMeta, Error> {
-  const query = useQuery({
-    queryKey: ["pages", pageInput.pageId],
-    queryFn: () => getPageById(pageInput),
-    enabled: !!pageInput.pageId,
-    staleTime: 5 * 60 * 1000,
-    select: selectPageMeta,
-    // Match usePageQuery: keep the previous page's metadata visible while
-    // navigating so the periphery (header, breadcrumb, …) doesn't flash blank.
-    placeholderData: keepPreviousData,
-  });
-
-  // Mirror usePageQuery's cross-key alias write so a page fetched by one
-  // identifier is also cached under the other. The cache stores the FULL page
-  // (select only narrows what THIS hook returns), so read the full object back
-  // from the cache and alias THAT — never the content-less slice.
-  useEffect(() => {
-    if (!query.data) return;
-    const full = queryClient.getQueryData<IPage>(["pages", pageInput.pageId]);
-    if (!full) return;
-    if (isValidUuid(pageInput.pageId)) {
-      queryClient.setQueryData(["pages", full.slugId], full);
-    } else {
-      queryClient.setQueryData(["pages", full.id], full);
-    }
-  }, [query.data]);
-
-  return query;
-}
-
 export function useCreatePageMutation() {
   const { t } = useTranslation();
   return useMutation<IPage, Error, Partial<IPageInput>>({
@@ -410,12 +351,6 @@ export function useRecentChangesQuery(spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
-    // KEEP refetchOnMount:true (against the global default false): recent-changes
-    // IS invalidated on page create/update/move/delete, but invalidateQueries only
-    // marks an UNMOUNTED query stale — it doesn't refetch it. The widget isn't
-    // always mounted, so an event that lands while it's unmounted leaves it stale,
-    // and the global refetchOnMount:false would not re-fetch on remount. The mount
-    // refetch closes that gap.
     refetchOnMount: true,
   });
 }
@@ -432,9 +367,6 @@ export function useCreatedByQuery(params?: {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
-    // KEEP refetchOnMount:true: the "created-by" key is never invalidated (no
-    // socket/mutation path), so the mount refetch is its ONLY freshness mechanism
-    // — without it the list shows stale cache on navigation.
     refetchOnMount: true,
   });
 }
@@ -448,14 +380,8 @@ export function useDeletedPagesQuery(
     queryFn: () => getDeletedPages(spaceId, params),
     enabled: !!spaceId,
     placeholderData: keepPreviousData,
-    staleTime: 0,
-    // KEEP refetchOnMount:true: ["trash-list"] IS invalidated by the
-    // move-to-trash / delete / restore mutations, but invalidateQueries only marks
-    // an unmounted query stale — it doesn't refetch it. The trash panel isn't
-    // usually mounted when a page is trashed, so on opening it the global
-    // refetchOnMount:false would show a stale list; the mount refetch closes that.
-    // (Do NOT remove the three trash-list invalidations — they are not dead code.)
     refetchOnMount: true,
+    staleTime: 0,
   });
 }
 
@@ -590,35 +516,7 @@ export function invalidateOnUpdatePage(
   title: string,
   icon: string,
 ) {
-  // Scoped page-tree refresh (was a blanket `invalidatePageTree()`): this is the
+  invalidatePageTree();
-  // FIELD-only update path (title/icon — no structural change), and the sidebar
-  // tree is already updated pointwise (applyUpdateOne / optimistic setData) plus
-  // via the sidebar-pages cache below. Invalidating ALL ["page-tree"] queries
-  // here refetched every open recursive subpages-embed block on each
-  // rename/icon-change — pure duplicate work. Instead patch just the affected
-  // node IN PLACE in every cached embed subtree: same visible result, no network
-  // churn, no full embed-tree rebuild. Structural events (create/move/delete)
-  // keep the blanket invalidate in their own helpers.
-  const pageTreeMatches = queryClient.getQueriesData<IPage[]>({
-    queryKey: ["page-tree"],
-  });
-  pageTreeMatches.forEach(([key, items]) => {
-    if (!items || !items.some((p) => p.id === id)) return;
-    queryClient.setQueryData<IPage[]>(key, (old) =>
-      old?.map((p) =>
-        p.id === id
-          ? {
-              ...p,
-              // Guard undefined so a title-only event can't wipe the icon (and
-              // vice versa) in the embed cache.
-              ...(title !== undefined ? { title } : {}),
-              ...(icon !== undefined ? { icon } : {}),
-            }
-          : p,
-      ),
-    );
-  });
-
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
     queryKey = ["root-sidebar-pages", spaceId];
@@ -636,14 +534,7 @@ export function invalidateOnUpdatePage(
           ...page,
           items: page.items.map((sidebarPage: IPage) =>
             sidebarPage.id === id
-              ? {
+              ? { ...sidebarPage, title: title, icon: icon }
-                  ...sidebarPage,
-                  // Guard undefined so a title-only event can't wipe the icon
-                  // (and vice versa) in the sidebar-pages cache — mirrors the
-                  // embed-cache patch above.
-                  ...(title !== undefined ? { title } : {}),
-                  ...(icon !== undefined ? { icon } : {}),
-                }
               : sidebarPage,
           ),
         })),

apps/client/src/features/page/trash/components/deleted-page-banner.tsx

@@ -7,7 +7,7 @@ import { useRestorePageModal } from "@/features/page/hooks/use-restore-page-moda
 import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
 import {
   useDeletePageMutation,
-  usePageMetaQuery,
+  usePageQuery,
   useRestorePageMutation,
 } from "@/features/page/queries/page-query.ts";
 import { getSpaceUrl } from "@/lib/config.ts";
@@ -25,7 +25,7 @@ type DeletedPageBannerProps = {
 export function DeletedPageBanner({ slugId }: DeletedPageBannerProps) {
   const { t } = useTranslation();
   const navigate = useNavigate();
-  const { data: page } = usePageMetaQuery({ pageId: slugId });
+  const { data: page } = usePageQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const deletedTimeAgo = useTimeAgo(page?.deletedAt);

apps/client/src/features/page/tree/components/space-tree-node-menu.tsx

@@ -1,4 +1,4 @@
-import { useSetAtom, useStore } from "jotai";
+import { useAtom } from "jotai";
 import { useTranslation } from "react-i18next";
 import { useParams } from "react-router-dom";
 import { ActionIcon, Menu, rem } from "@mantine/core";
@@ -52,11 +52,7 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
   const clipboard = useClipboard({ timeout: 500 });
   const { spaceSlug } = useParams();
   const { handleDelete } = useTreeMutation(node.spaceId);
-  // Setter-only: the tree value is read only imperatively inside the duplicate
+  const [data, setData] = useAtom(treeDataAtom);
-  // handler (via `store` below), never at render, so useSetAtom avoids
-  // re-rendering every row's NodeMenu on any tree event.
-  const setData = useSetAtom(treeDataAtom);
-  const store = useStore();
   const emit = useQueryEmit();
   const [exportOpened, { open: openExportModal, close: closeExportModal }] =
     useDisclosure(false);
@@ -129,8 +125,8 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
     try {
       const duplicatedPage = await duplicatePage({ pageId: node.id });
 
-      // figure out parent + insertion index (read the live tree imperatively)
+      // figure out parent + insertion index
-      const siblings = treeModel.siblingsOf(store.get(treeDataAtom), node.id);
+      const siblings = treeModel.siblingsOf(data, node.id);
       const parentId = siblings?.parentId ?? null;
       const currentIndex = siblings?.index ?? 0;
       const newIndex = currentIndex + 1;

apps/client/src/features/page/tree/components/space-tree-row.tsx

@@ -1,6 +1,6 @@
 import { useRef } from "react";
 import { Link, useParams } from "react-router-dom";
-import { useAtom, useSetAtom } from "jotai";
+import { useAtom } from "jotai";
 import { useTranslation } from "react-i18next";
 import { ActionIcon, rem, Tooltip } from "@mantine/core";
 import {
@@ -51,11 +51,7 @@ export function SpaceTreeRow({
   const { t } = useTranslation();
   const { spaceSlug } = useParams();
   const updatePageMutation = useUpdatePageMutation();
-  // Setter-only: subscribing to the whole treeDataAtom (via useAtom) re-rendered
+  const [, setTreeData] = useAtom(treeDataAtom);
-  // every virtualized row on any tree event, bypassing the DocTreeRow memo. This
-  // row never reads the tree value, only writes it, so useSetAtom avoids the
-  // value subscription.
-  const setTreeData = useSetAtom(treeDataAtom);
   const emit = useQueryEmit();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [mobileSidebarOpened] = useAtom(mobileSidebarAtom);

apps/client/src/features/page/tree/components/space-tree.boot-cache.test.tsx

@@ -35,7 +35,6 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
-  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: (...args: unknown[]) =>
     fetchAllAncestorChildrenMock(...args),
 }));

apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx

@@ -26,7 +26,6 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
-  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: vi.fn(),
 }));
 

apps/client/src/features/page/tree/components/space-tree.tsx

@@ -15,7 +15,7 @@ import { notifications } from "@mantine/notifications";
 import {
   fetchAllAncestorChildren,
   useGetRootSidebarPagesQuery,
-  usePageMetaQuery,
+  usePageQuery,
 } from "@/features/page/queries/page-query.ts";
 import classes from "@/features/page/tree/styles/tree.module.css";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
@@ -76,7 +76,7 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
   const [isDataLoaded, setIsDataLoaded] = useState(false);
   const spaceIdRef = useRef(spaceId);
   spaceIdRef.current = spaceId;
-  const { data: currentPage } = usePageMetaQuery({
+  const { data: currentPage } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
 

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -1,5 +1,5 @@
 import { useCallback } from "react";
-import { useSetAtom, useStore } from "jotai";
+import { useAtom, useSetAtom, useStore } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { useNavigate, useParams } from "react-router-dom";
@@ -34,10 +34,7 @@ export type UseTreeMutation = {
 
 export function useTreeMutation(spaceId: string): UseTreeMutation {
   const { t } = useTranslation();
-  // Setter-only: this hook never reads the tree reactively (handlers read the
+  const [, setData] = useAtom(treeDataAtom);
-  // live value imperatively via `store` below), so useSetAtom avoids
-  // re-rendering SpaceSidebar on every tree event.
-  const setData = useSetAtom(treeDataAtom);
   // `store` reads the *current* treeDataAtom imperatively in handlers — avoids
   // stale-closure issues when the caller updates the tree (e.g. lazy-load
   // children) and then immediately invokes a handler.

apps/client/src/features/share/components/share-ai-widget.tsx

@@ -165,9 +165,6 @@ export default function ShareAiWidget({
             isStreaming={isStreaming}
             assistantName={assistantName}
             showCitations={false}
-            // Anonymous reader: suppress the tool-argument summary line so the
-            // agent's raw query/argument text isn't shown on the public share.
-            showInput={false}
             // Anonymous reader: neutralize internal/relative links in the
             // assistant's markdown so internal UUIDs/auth-gated routes don't
             // leak as clickable links (external http(s) links are kept).

apps/client/src/features/share/components/share-layout.tsx

@@ -1,20 +1,10 @@
-import { Suspense } from "react";
 import { Outlet } from "react-router-dom";
-import { Center, Loader } from "@mantine/core";
 import ShareShell from "@/features/share/components/share-shell.tsx";
 
 export default function ShareLayout() {
   return (
     <ShareShell>
-      <Suspense
-        fallback={
-          <Center h="60vh">
-            <Loader size="sm" />
-          </Center>
-        }
-      >
       <Outlet />
-      </Suspense>
     </ShareShell>
   );
 }

apps/client/src/features/share/components/share-modal.test.tsx

@@ -28,7 +28,6 @@ vi.mock("@/features/share/queries/share-query.ts", () => ({
 
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
-  usePageMetaQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
 }));
 
 vi.mock("@/features/space/queries/space-query.ts", () => ({

apps/client/src/features/share/components/share-modal.tsx

@@ -20,7 +20,7 @@ import {
 import { Link, useParams } from "react-router-dom";
 import { extractPageSlugId, getPageIcon } from "@/lib";
 import { useTranslation } from "react-i18next";
-import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import CopyTextButton from "@/components/common/copy.tsx";
 import { getAppUrl } from "@/lib/config.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -37,7 +37,7 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
   const pageSlugId = extractPageSlugId(pageSlug);
-  const { data: page } = usePageMetaQuery({ pageId: pageSlugId });
+  const { data: page } = usePageQuery({ pageId: pageSlugId });
   const pageId = page?.id;
   const { data: share } = useShareForPageQuery(pageId);
   const { spaceSlug } = useParams();

apps/client/src/features/space/components/edit-space-form.test.tsx

@@ -0,0 +1,240 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  afterEach,
+} from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// EditSpaceForm wires the "Enable Git sync" Switch to a TanStack-Query mutation
+// (useUpdateSpaceMutation). We mock ONLY that hook so the test fully controls
+// mutateAsync (resolve / reject) and isPending, and stub i18n. The real Mantine
+// Switch is rendered so the checkbox role / disabled state is meaningful.
+
+// i18n: identity translator — labels stay as their English keys for queries.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// Mutation hook: a controllable mutateAsync plus a togglable isPending.
+const mutateAsync = vi.fn();
+let isPending = false;
+vi.mock("@/features/space/queries/space-query.ts", () => ({
+  useUpdateSpaceMutation: () => ({
+    mutateAsync,
+    get isPending() {
+      return isPending;
+    },
+  }),
+}));
+
+// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
+beforeAll(() => {
+  if (!window.matchMedia) {
+    window.matchMedia = (query: string) =>
+      ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => false,
+      }) as unknown as MediaQueryList;
+  }
+});
+
+import { EditSpaceForm } from "./edit-space-form";
+import type { ISpace } from "@/features/space/types/space.types.ts";
+
+function makeSpace(overrides: Partial<ISpace> = {}): ISpace {
+  return {
+    id: "space-1",
+    name: "Engineering",
+    description: "",
+    slug: "eng",
+    hostname: "host",
+    creatorId: "u1",
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+    ...overrides,
+  } as ISpace;
+}
+
+function renderForm(props: { space: ISpace; readOnly?: boolean }) {
+  return render(
+    <MantineProvider>
+      <EditSpaceForm space={props.space} readOnly={props.readOnly} />
+    </MantineProvider>,
+  );
+}
+
+// The form now renders TWO switches (git-sync enable + auto-merge-conflicts) in
+// that DOM order. Mantine renders each as an <input type="checkbox"
+// role="switch"> but does NOT expose its label as the accessible name, so we
+// disambiguate by DOM order (index 0 = enable, 1 = auto-merge) and assert the
+// human-readable label text is present alongside.
+function getToggle(): HTMLInputElement {
+  screen.getByText("Enable Git sync");
+  return screen.getAllByRole("switch")[0] as HTMLInputElement;
+}
+
+function getAutoMergeToggle(): HTMLInputElement {
+  screen.getByText("Auto-merge conflicts on push");
+  return screen.getAllByRole("switch")[1] as HTMLInputElement;
+}
+
+afterEach(() => {
+  cleanup();
+  mutateAsync.mockReset();
+  isPending = false;
+});
+
+describe("EditSpaceForm git-sync toggle", () => {
+  // Test 3: initial checked state derives from settings.gitSync.enabled ?? false.
+  it("derives initial checked state from space.settings.gitSync.enabled (true -> checked)", () => {
+    renderForm({
+      space: makeSpace({ settings: { gitSync: { enabled: true } } }),
+    });
+    expect(getToggle().checked).toBe(true);
+  });
+
+  it("defaults to unchecked when gitSync settings are missing", () => {
+    renderForm({ space: makeSpace() });
+    expect(getToggle().checked).toBe(false);
+  });
+
+  // Test 4: toggling fires the mutation with { spaceId, gitSyncEnabled } and
+  // optimistically flips the switch.
+  it("fires the mutation with the correct payload and optimistically flips on", async () => {
+    mutateAsync.mockResolvedValue(undefined);
+    renderForm({ space: makeSpace() });
+
+    const toggle = getToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistic update: the switch reflects the new state immediately.
+    expect(toggle.checked).toBe(true);
+
+    expect(mutateAsync).toHaveBeenCalledTimes(1);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      gitSyncEnabled: true,
+    });
+
+    // Resolution leaves the toggle on.
+    await waitFor(() => expect(toggle.checked).toBe(true));
+  });
+
+  // Test 5: rollback on mutation error — the most valuable test.
+  it("rolls back the toggle to its prior state when the mutation rejects", async () => {
+    mutateAsync.mockRejectedValue(new Error("network"));
+    renderForm({
+      space: makeSpace({ settings: { gitSync: { enabled: false } } }),
+    });
+
+    const toggle = getToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistically flips on before the rejection lands.
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      gitSyncEnabled: true,
+    });
+
+    // After the rejected promise settles, the component reverts to OFF so the
+    // user is not misled into believing sync is enabled.
+    await waitFor(() => expect(toggle.checked).toBe(false));
+  });
+
+  // Test 6: disabled when readOnly and when the mutation is pending.
+  it("disables the toggle when readOnly", () => {
+    renderForm({ space: makeSpace(), readOnly: true });
+    expect(getToggle().disabled).toBe(true);
+  });
+
+  it("disables the toggle while the mutation is pending", () => {
+    isPending = true;
+    renderForm({ space: makeSpace() });
+    expect(getToggle().disabled).toBe(true);
+  });
+});
+
+describe("EditSpaceForm auto-merge-conflicts toggle", () => {
+  it("derives initial checked state from space.settings.gitSync.autoMergeConflicts (true -> checked)", () => {
+    renderForm({
+      space: makeSpace({
+        settings: { gitSync: { autoMergeConflicts: true } },
+      }),
+    });
+    expect(getAutoMergeToggle().checked).toBe(true);
+  });
+
+  it("defaults to unchecked when autoMergeConflicts is missing (SAFE default)", () => {
+    renderForm({ space: makeSpace() });
+    expect(getAutoMergeToggle().checked).toBe(false);
+  });
+
+  it("fires the mutation with { spaceId, autoMergeConflicts } and optimistically flips on", async () => {
+    mutateAsync.mockResolvedValue(undefined);
+    renderForm({ space: makeSpace() });
+
+    const toggle = getAutoMergeToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistic update.
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledTimes(1);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      autoMergeConflicts: true,
+    });
+
+    await waitFor(() => expect(toggle.checked).toBe(true));
+  });
+
+  it("rolls back to its prior state when the mutation rejects", async () => {
+    mutateAsync.mockRejectedValue(new Error("network"));
+    renderForm({
+      space: makeSpace({
+        settings: { gitSync: { autoMergeConflicts: false } },
+      }),
+    });
+
+    const toggle = getAutoMergeToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      autoMergeConflicts: true,
+    });
+
+    await waitFor(() => expect(toggle.checked).toBe(false));
+  });
+
+  it("disables the toggle when readOnly", () => {
+    renderForm({ space: makeSpace(), readOnly: true });
+    expect(getAutoMergeToggle().disabled).toBe(true);
+  });
+});

apps/client/src/features/space/components/edit-space-form.tsx

@@ -1,5 +1,14 @@
-import { Group, Box, Button, TextInput, Stack, Textarea } from "@mantine/core";
+import {
-import React from "react";
+  Group,
+  Box,
+  Button,
+  TextInput,
+  Stack,
+  Textarea,
+  Divider,
+  Switch,
+} from "@mantine/core";
+import React, { useState } from "react";
 import { useForm } from "@mantine/form";
 import { zod4Resolver } from "mantine-form-zod-resolver";
 import { z } from "zod/v4";
@@ -29,6 +38,37 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
   const { t } = useTranslation();
   const updateSpaceMutation = useUpdateSpaceMutation();
 
+  const [gitSyncEnabled, setGitSyncEnabled] = useState<boolean>(
+    space?.settings?.gitSync?.enabled ?? false,
+  );
+
+  const [autoMergeConflicts, setAutoMergeConflicts] = useState<boolean>(
+    space?.settings?.gitSync?.autoMergeConflicts ?? false,
+  );
+
+  // One parameterized handler for both git-sync space toggles: they differ only by
+  // the local state setter, the mutation payload field, and the error label. The
+  // update is optimistic and reverts the local state on failure (the mutation
+  // surfaces a toast via onError; the raw error is still logged per AGENTS.md).
+  const handleToggle = async (
+    field: "gitSyncEnabled" | "autoMergeConflicts",
+    value: boolean,
+    previous: boolean,
+    setLocal: (next: boolean) => void,
+    errorLabel: string,
+  ) => {
+    setLocal(value); // optimistic update
+    try {
+      await updateSpaceMutation.mutateAsync({
+        spaceId: space.id,
+        [field]: value,
+      });
+    } catch (err) {
+      setLocal(previous); // revert on failure
+      console.error(errorLabel, err);
+    }
+  };
+
   const form = useForm<FormValues>({
     validate: zod4Resolver(formSchema),
     initialValues: {
@@ -104,6 +144,43 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
             </Group>
           )}
         </form>
+
+        <Divider my="lg" />
+
+        <Switch
+          label={t("Enable Git sync")}
+          description={t("Sync this space's pages to a Git repository.")}
+          checked={gitSyncEnabled}
+          disabled={readOnly || updateSpaceMutation.isPending}
+          onChange={(event) =>
+            handleToggle(
+              "gitSyncEnabled",
+              event.currentTarget.checked,
+              gitSyncEnabled,
+              setGitSyncEnabled,
+              "Failed to toggle git-sync for space",
+            )
+          }
+        />
+
+        <Switch
+          mt="md"
+          label={t("Auto-merge conflicts on push")}
+          description={t(
+            "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
+          )}
+          checked={autoMergeConflicts}
+          disabled={readOnly || updateSpaceMutation.isPending}
+          onChange={(event) =>
+            handleToggle(
+              "autoMergeConflicts",
+              event.currentTarget.checked,
+              autoMergeConflicts,
+              setAutoMergeConflicts,
+              "Failed to toggle git-sync auto-merge-conflicts",
+            )
+          }
+        />
       </Box>
     </>
   );

apps/client/src/features/space/queries/space-query.ts

@@ -38,11 +38,6 @@ export function useGetSpacesQuery(
     queryKey: ["spaces", params],
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
-    // KEEP refetchOnMount:true (against the global default false): the ["spaces"]
-    // key is invalidated only by same-tab mutations (no socket path), so a
-    // cross-actor change — an admin adding/removing THIS user from a space — has
-    // no local mutation or socket event and would leave the space list stale until
-    // a hard reload. The mount refetch is its only cross-actor freshness path.
     refetchOnMount: true,
   });
 }

apps/client/src/features/space/queries/space-watcher-query.ts

@@ -16,6 +16,7 @@ export function useWatchedSpaceIds(): Set<string> {
   const { data } = useQuery({
     queryKey: [WATCHED_SPACE_IDS_KEY],
     queryFn: () => getWatchedSpaceIds(),
+    refetchOnMount: true,
   });
 
   const items = data?.items;

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

@@ -13,9 +13,15 @@ export interface ISpaceCommentsSettings {
   allowViewerComments?: boolean;
 }
 
+export interface ISpaceGitSyncSettings {
+  enabled?: boolean;
+  autoMergeConflicts?: boolean;
+}
+
 export interface ISpaceSettings {
   sharing?: ISpaceSharingSettings;
   comments?: ISpaceCommentsSettings;
+  gitSync?: ISpaceGitSyncSettings;
 }
 
 export interface ISpace {
@@ -35,6 +41,8 @@ export interface ISpace {
   // for updates
   disablePublicSharing?: boolean;
   allowViewerComments?: boolean;
+  gitSyncEnabled?: boolean;
+  autoMergeConflicts?: boolean;
 }
 
 interface IMembership {

apps/client/src/features/websocket/use-query-subscription.ts

@@ -19,11 +19,7 @@ export const useQuerySubscription = () => {
   const [socket] = useAtom(socketAtom);
 
   React.useEffect(() => {
-    if (!socket) return;
+    socket?.on("message", (event) => {
-    // Named handler + off() cleanup (mirrors use-notification-socket). Without
-    // cleanup, every socket recreation / effect re-run stacked another listener,
-    // so a single broadcast fired duplicated invalidateQueries / setQueryData.
-    const handleMessage = (event) => {
       const data: WebSocketEvent = event;
 
       let entity = null;
@@ -167,11 +163,6 @@ export const useQuerySubscription = () => {
           });
           break;
       }
-    };
+    });
-
-    socket.on("message", handleMessage);
-    return () => {
-      socket.off("message", handleMessage);
-    };
   }, [queryClient, socket]);
 };

apps/client/src/features/websocket/use-tree-socket.ts

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 import { socketAtom } from "@/features/websocket/atoms/socket-atom.ts";
-import { useAtom, useSetAtom } from "jotai";
+import { useAtom } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { WebSocketEvent } from "@/features/websocket/types";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -16,10 +16,7 @@ import localEmitter from "@/lib/local-emitter.ts";
 
 export const useTreeSocket = () => {
   const [socket] = useAtom(socketAtom);
-  // Setter-only: this hook writes the tree from socket events but never reads it
+  const [, setTreeData] = useAtom(treeDataAtom);
-  // reactively, so useSetAtom avoids re-rendering UserProvider (its host) on
-  // every tree event.
-  const setTreeData = useSetAtom(treeDataAtom);
   const queryClient = useQueryClient();
 
   useEffect(() => {
@@ -40,11 +37,7 @@ export const useTreeSocket = () => {
   }, []);
 
   useEffect(() => {
-    if (!socket) return;
+    socket?.on("message", (event: WebSocketEvent) => {
-    // Named handler + off() cleanup (mirrors use-notification-socket). Without
-    // cleanup, every socket recreation / effect re-run stacked another listener,
-    // so a single broadcast fired duplicated tree walks after each reconnect.
-    const handleMessage = (event: WebSocketEvent) => {
       switch (event.operation) {
         case "updateOne":
           if (event.entity[0] === "pages") {
@@ -71,11 +64,6 @@ export const useTreeSocket = () => {
           });
           break;
       }
-    };
+    });
-
+  }, [socket]);
-    socket.on("message", handleMessage);
-    return () => {
-      socket.off("message", handleMessage);
-    };
-  }, [socket, queryClient, setTreeData]);
 };