fix(client): add /l vanity route to SW denylist; name failed offline steps (F2, F3)

F2: navigateFallbackDenylist was missing the server's `l/:alias` vanity
short-link, so a top-nav to /l/<alias> after SW registration got the
index.html app shell (which has no /l route) and dead-ended on Error404
instead of the server's 302 redirect. Add /^\/l(\/|$)/ mirroring main.ts.

F3: the partial-failure branch of "make page available offline" showed a
bare generic toast; include result.failed step labels in the message per
AGENTS.md (errors must be specific), matching the catch-branch below it.

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

.env.example

@@ -92,6 +92,19 @@ IFRAME_EMBED_ALLOWED=false
 # Example: https://intranet.example.com,https://portal.example.com
 IFRAME_ALLOWED_ORIGINS=
 
+# Comma-separated list of additional origins allowed to call the API via CORS.
+# The APP_URL origin and native mobile (Capacitor) origins are always allowed.
+# Leave empty for a same-origin (web-only) deployment.
+CORS_ALLOWED_ORIGINS=
+
+# Expose OpenAPI/Swagger docs at /api/docs (development/debugging aid only).
+SWAGGER_ENABLED=false
+
+# Capacitor (mobile shell): hosted client URL loaded by the iOS shell so the
+# AGPL web client is NOT bundled into the .ipa (see docs/mobile-app-plan.md §9).
+# Leave empty for Android bundled mode / local development.
+CAP_SERVER_URL=
+
 # Enable debug logging in production (default: false)
 DEBUG_MODE=false
 
@@ -191,24 +204,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 +235,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).

.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

@@ -1,13 +1,5 @@
 name: Test
 
-# NO `paths:` filter on purpose (issue #447). The tool-spec REGISTRY is split
-# across two packages that MUST stay in sync: the specs live in `packages/mcp`
-# but the parity/tier guard tests that read them live in the `apps/server` jest
-# suite. A PR touching only `packages/mcp/**` must therefore still run the SERVER
-# suite (and vice-versa), or an in-app wiring break slips through green and only
-# surfaces on develop after merge. The `test` job below runs BOTH suites via
-# `pnpm -r test` on every PR; the dedicated `mcp-server-parity` job makes that
-# cross-package gate explicit and fast. Do not add a `paths:` filter here.
 on:
   pull_request:
   workflow_call:
@@ -140,53 +132,3 @@ jobs:
       # isolated `docmost_test` DB and migrates it to latest.
       - name: Run server integration tests
         run: pnpm --filter server test:int
-
-  # Cross-package tool-spec parity gate (issue #447). The tool-spec registry lives
-  # in `packages/mcp` but its parity/tier guard tests live in the `apps/server`
-  # jest suite, so a PR touching ONLY one of the two packages must still run BOTH
-  # sides — otherwise an in-app wiring break (e.g. PR #434 drawio) passes the mcp
-  # suite green and only surfaces on develop after merge. The `test` job already
-  # runs everything via `pnpm -r test`; this job is a fast, explicitly-named guard
-  # that runs the mcp `node --test` suite AND the server tool-guard jest specs
-  # together, so the coupling is visible and can never be accidentally split by a
-  # path filter. No Postgres/Redis needed: these specs mock the DB/loader.
-  mcp-server-parity:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    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
-
-      # Shared deps first (build/ dirs are gitignored; see test.yml build order).
-      - name: Build editor-ext
-        run: pnpm --filter @docmost/editor-ext build
-
-      - name: Build prosemirror-markdown
-        run: pnpm --filter @docmost/prosemirror-markdown build
-
-      # Build the mcp package so build/ carries a FRESH REGISTRY_STAMP (#447): the
-      # build runs gen-registry-stamp.mjs before tsc, so a build/ vs src/ skew
-      # cannot slip into the tests that exercise the loader's stale-check.
-      - name: Build mcp (regenerates REGISTRY_STAMP)
-        run: pnpm --filter @docmost/mcp build
-
-      # mcp side: the standalone MCP server's own tool-spec / instructions guards.
-      - name: Run mcp tool-spec suite
-        run: pnpm --filter @docmost/mcp test
-
-      # server side: the parity + tier guards that read packages/mcp/src/tool-specs
-      # and assert the in-app AI-chat wiring matches it.
-      - name: Run server tool-spec guard specs
-        run: pnpm --filter server exec jest shared-tool-specs.contract tool-tiers ai-chat-tools.service --runInBand

.gitignore

@@ -19,11 +19,6 @@ packages/prosemirror-markdown/build/
 # markdown convention; the package is private and rebuilt at deploy.
 packages/mcp/build/
 
-# mcp REGISTRY_STAMP codegen output (issue #447). Regenerated into src/ by
-# scripts/gen-registry-stamp.mjs on every `build`/`pretest` (before tsc), so it
-# is a build artifact like build/ — never committed, always fresh.
-packages/mcp/src/registry-stamp.generated.ts
-
 # Logs
 logs
 *.log
@@ -69,3 +64,8 @@ lerna-debug.log*
 
 # Self-hosted VAD / onnxruntime-web assets (copied from node_modules at dev/build time)
 apps/client/public/vad/
+
+# Capacitor native platform projects (generated locally via 'npx cap add ios|android')
+/ios
+/android
+.capacitor

.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

@@ -230,40 +230,6 @@ pnpm build                   # nx run-many -t build (all packages)
 pnpm collab:dev              # run the collaboration server process standalone (see "Two server processes")
 ```
 
-> **Build the shared packages before running a consumer's `tsc`/tests in
-> isolation.** The `build/` dirs of `@docmost/prosemirror-markdown`,
-> `@docmost/git-sync`, and `@docmost/mcp` are **gitignored** (not committed), and
-> a single-package `pnpm --filter <pkg> test` / `tsc` or a bare `pnpm -r test`
-> does **NOT** honour the Nx `dependsOn: ["^build"]` ordering. So a consumer — the
-> server's `tsc`, `git-sync`'s vitest typecheck, `mcp`'s `pretest: tsc` — fails
-> with `error TS2307: Cannot find module '@docmost/…'` until those packages are
-> built first:
-> ```bash
-> pnpm --filter @docmost/prosemirror-markdown build
-> pnpm --filter @docmost/editor-ext build
-> pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build
-> ```
-> `pnpm build` (nx run-many) does this for you; CI does it explicitly in
-> `.github/workflows/test.yml` (prosemirror-markdown → git-sync/mcp → server, in
-> that order). Reach for it whenever you run a consumer package's checks on their
-> own rather than through the full `pnpm build`.
-
-> **Editing an MCP tool spec requires a rebuild (issue #447).** The running
-> server loads the **compiled** `packages/mcp/build/` of `@docmost/mcp` (via the
-> runtime loader in `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts`),
-> but the parity/tier guard tests read `packages/mcp/src/tool-specs.ts`. So if you
-> edit `tool-specs.ts` (any tool name, description, tier, catalog line, or input
-> schema) **without rebuilding**, `build/` and `src/` silently diverge — the tests
-> stay green while the server serves the OLD tools. To close that gap, the build
-> emits a `REGISTRY_STAMP` (a deterministic hash of the tool-specs content, via
-> `scripts/gen-registry-stamp.mjs` before `tsc`); on dev/test startup the loader
-> recomputes it from `src/` and **refuses to start with a "@docmost/mcp build is
-> stale …" error** on a mismatch (a pure no-op in prod, where only `build/` ships).
-> After editing tool specs, rebuild:
-> ```bash
-> pnpm --filter @docmost/mcp build     # or: pnpm --filter @docmost/mcp watch
-> ```
-
 **Lint** (per package — there is no root lint script):
 ```bash
 pnpm --filter server lint    # eslint --fix on server .ts
@@ -327,7 +293,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 ### 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`.
 
@@ -338,7 +304,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`, `ai`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons. The `ai@6.0.134` patch disables the SDK's O(n²) cumulative `partialOutput` accumulation when no output strategy is requested (server heap OOM on long agent runs, #184; tripwire test: `apps/server/src/integrations/ai/ai-sdk-partial-output.patch.spec.ts`) — it MUST be re-created via `pnpm patch` when bumping `ai`.
-- **The MCP tool inventory in `SERVER_INSTRUCTIONS` is GENERATED from the registry** (`packages/mcp/src/server-instructions.ts`: `buildToolInventory()` over `SHARED_TOOL_SPECS`) and spliced into the hand-written routing prose (`ROUTING_PROSE`). So adding/renaming/removing a **shared** spec in `packages/mcp/src/tool-specs.ts` auto-updates the `<tool_inventory>` — no manual `SERVER_INSTRUCTIONS` edit needed. Only an **inline** MCP-only tool (those registered via `server.registerTool(...)` in `index.ts`, not through the registry) needs a one-line entry in `INLINE_MCP_INVENTORY`. Enforced by `packages/mcp/test/unit/tool-inventory.test.mjs`, which fails when a registered tool is missing from the generated inventory (there is no `EXCEPTIONS` opt-out anymore — every tool must appear). Update `ROUTING_PROSE` when a tool's *intent guidance* (when-to-use) changes. `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
 
 ## CI / release
 

CHANGELOG.md

@@ -166,6 +166,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   JSON-compatible schema (no custom tags / no code execution) behind the same
   size-cap, redirect and path-traversal guards. The `AI_AGENT_ROLES_CATALOG_URL`
   base-URL contract is unchanged. (#229)
+- **CORS is now an explicit allowlist** (replaces the previous unconfigured
+  `app.enableCors()`). The same-origin web client is unaffected, but any
+  separately-hosted cross-domain client must now be listed in
+  `CORS_ALLOWED_ORIGINS` (native Capacitor/Ionic/localhost WebView origins are
+  allowed automatically). Requests with no `Origin` header (server-to-server)
+  are still allowed. **Upgrade note:** the old bare `app.enableCors()` reflected
+  *any* origin (with `credentials:false`), so any previously-working cross-domain
+  REST/browser client is now rejected until its origin is added to
+  `CORS_ALLOWED_ORIGINS` (see `.env.example`).
+
+### Added
+
+- **Offline reading support**: opened pages, their sidebar tree, breadcrumb
+  children, and comments are cached in IndexedDB (TanStack Query persister plus
+  `y-indexeddb` for the page's Yjs document), and a PWA service worker
+  (vite-plugin-pwa) serves an app shell so previously opened pages stay readable
+  offline. The two offline stores (the persisted query cache and the Yjs page
+  documents) are cleared on logout AND on sign-in so a previous user's private
+  data does not remain in the browser; the same purge also defensively drops any
+  legacy service-worker `api-get-cache` left by older clients (current builds
+  serve `/api` as NetworkOnly, so there is no active service-worker API cache).
+- **Mobile bootstrap**: a `returnToken` opt-in on login so native/mobile clients
+  can request the access JWT in the response body (`data.authToken`) in addition
+  to the httpOnly cookie (the web client stays cookie-only); an optional
+  OpenAPI/Swagger UI at `/api/docs` gated by `SWAGGER_ENABLED` (off by default);
+  and new env vars `CORS_ALLOWED_ORIGINS`, `SWAGGER_ENABLED`, `CAP_SERVER_URL`.
 
 ### Fixed
 

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/index.html

@@ -10,6 +10,7 @@
     <meta name="theme-color" content="#0E1117" media="(prefers-color-scheme: dark)" />
     <meta name="theme-color" content="#f6f7f9" media="(prefers-color-scheme: light)" />
     <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icons/app-icon-192x192.png" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="apple-touch-fullscreen" content="yes" />
     <meta name="apple-mobile-web-app-title" content="Gitmost" />

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",
@@ -34,7 +33,9 @@
     "@slidoapp/emoji-mart-data": "1.2.4",
     "@slidoapp/emoji-mart-react": "1.1.5",
     "@tabler/icons-react": "3.40.0",
+    "@tanstack/query-async-storage-persister": "5.90.17",
     "@tanstack/react-query": "5.90.17",
+    "@tanstack/react-query-persist-client": "5.90.17",
     "@tanstack/react-virtual": "3.13.24",
     "ai": "6.0.207",
     "alfaaz": "1.1.0",
@@ -47,6 +48,7 @@
     "highlightjs-sap-abap": "0.3.0",
     "i18next": "25.10.1",
     "i18next-http-backend": "3.0.6",
+    "idb-keyval": "6.2.5",
     "jotai": "2.18.1",
     "jotai-optics": "0.4.0",
     "js-cookie": "3.0.7",
@@ -99,7 +101,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
-    "vite-plugin-compression2": "2.5.3",
+    "vite-plugin-pwa": "1.3.0",
     "vitest": "4.1.6"
   }
 }

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

@@ -471,6 +471,18 @@
   "Move page": "Move page",
   "Move page to a different space.": "Move page to a different space.",
   "Real-time editor connection lost. Retrying...": "Real-time editor connection lost. Retrying...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Offline — changes are saved locally and will sync when you reconnect",
+  "Syncing changes…": "Syncing changes…",
+  "All changes synced": "All changes synced",
+  "Update available": "Update available",
+  "Reload": "Reload",
+  "Make available offline": "Make available offline",
+  "Saving page for offline use...": "Saving page for offline use...",
+  "Page is now available offline": "Page is now available offline",
+  "Failed to make page available offline": "Failed to make page available offline",
+  "You're offline": "You're offline",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+  "Retry": "Retry",
   "Table of contents": "Table of contents",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Add headings (H1, H2, H3) to generate a table of contents.",
   "Share": "Share",

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

@@ -487,6 +487,18 @@
   "Move page": "Переместить страницу",
   "Move page to a different space.": "Переместите страницу в другое пространство.",
   "Real-time editor connection lost. Retrying...": "Соединение с редактором в реальном времени потеряно. Повторная попытка...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Нет сети — изменения сохраняются локально и синхронизируются при восстановлении соединения",
+  "Syncing changes…": "Синхронизация изменений…",
+  "All changes synced": "Все изменения синхронизированы",
+  "Update available": "Доступно обновление",
+  "Reload": "Перезагрузить",
+  "Make available offline": "Сделать доступным офлайн",
+  "Saving page for offline use...": "Сохраняем страницу для офлайн-доступа…",
+  "Page is now available offline": "Страница доступна офлайн",
+  "Failed to make page available offline": "Не удалось сделать страницу доступной офлайн",
+  "You're offline": "Вы офлайн",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "Эта страница не была сохранена для офлайн-доступа, поэтому её нельзя загрузить сейчас. Подключитесь к интернету и попробуйте снова.",
+  "Retry": "Повторить",
   "Table of contents": "Оглавление",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Добавьте заголовки (H1, H2, H3), чтобы создать оглавление.",
   "Share": "Поделиться",

apps/client/public/manifest.json

@@ -1,30 +1,19 @@
 {
+  "id": "/",
   "name": "Gitmost",
   "short_name": "Gitmost",
+  "description": "Gitmost - open-source collaborative documentation and knowledge base.",
+  "lang": "en",
   "start_url": "/",
+  "scope": "/",
   "display": "standalone",
+  "orientation": "any",
   "background_color": "#0E1117",
   "theme_color": "#0E1117",
   "icons": [
-    {
+    { "src": "icons/favicon-16x16.png", "type": "image/png", "sizes": "16x16" },
-      "src": "icons/favicon-16x16.png",
+    { "src": "icons/favicon-32x32.png", "type": "image/png", "sizes": "32x32" },
-      "type": "image/png",
+    { "src": "icons/app-icon-192x192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
-      "sizes": "16x16"
+    { "src": "icons/app-icon-512x512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" }
-    },
-    {
-      "src": "icons/favicon-32x32.png",
-      "type": "image/png",
-      "sizes": "32x32"
-    },
-    {
-      "src": "icons/app-icon-192x192.png",
-      "type": "image/png",
-      "sizes": "180x180 192x192"
-    },
-    {
-      "src": "icons/app-icon-512x512.png",
-      "type": "image/png",
-      "sizes": "512x512"
-    }
   ]
 }

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 />
-            <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
+    <AiChatWindow />
-        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
+        <Outlet />
-          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).
+      event.stopPropagation();
-  useEffect(() => {
+      event.preventDefault();
-    if (!opened) return;
+      handlers.close();
-    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/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,
+    <button data-testid="queue-btn" onClick={() => onQueue("queued text")}>
-    onStop,
+      queue
-  }: {
+    </button>
-    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();
+    <MantineProvider>
-  const queryClient = new QueryClient({
+      <ChatThread chatId="c1" initialRows={[]} onTurnFinished={onTurnFinished} />
-    defaultOptions: { queries: { retry: false } },
+    </MantineProvider>,
-  });
-  const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
-  const { unmount } = render(
-    <QueryClientProvider client={queryClient}>
-      <MantineProvider>
-        <ChatThread
-          chatId={props?.chatId === undefined ? "c1" : props.chatId}
-          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,...).
-  function advanceToAttempt(attempt: number) {
-    act(() => {
-      vi.advanceTimersByTime(1000 * 2 ** (attempt - 1));
-    });
-  }
-
-  // Simulate the reconnect GET returning 204 (nothing live) so the transport's
-  // no-active-stream recovery runs.
-  async function reconnect204() {
-    vi.stubGlobal(
-      "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.
+  it("merges the polled run message when this tab is a passive observer", () => {
-  async function reconnect200() {
+    renderObserver("ready");
-    vi.stubGlobal(
+    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-      "fetch",
+    // The updater replaces/append the observed assistant row by id.
-      vi.fn().mockResolvedValue({ status: 200, ok: true }),
+    const updater = h.state.setMessages.mock.calls[0][0] as (
-    );
+      prev: { id: string; parts: { text: string }[] }[],
-    await act(async () => {
+    ) => { id: string; parts: { text: string }[] }[];
-      await h.state.transport!.fetch!("http://x", { method: "GET" });
+    const merged = updater([{ id: "u1", parts: [{ text: "hi" }] }]);
-    });
+    expect(merged).toHaveLength(2);
-  }
+    expect(merged[1].id).toBe("a-run");
-
+    expect(merged[1].parts[0].text).toBe("step 1\nstep 2");
-  it("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,23 +617,17 @@ 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
+                <Tooltip label={t("Interrupt and send now")} withArrow>
-                    stop() does not abort the resumed attach fetch, so the click
+                  <ActionIcon
-                    would be swallowed while flushOnAbortRef would fire minutes
+                    size="xs"
-                    later on the natural finish. Only the remove affordance stays. */}
+                    variant="subtle"
-                {!resumedTurn && (
+                    color="blue"
-                  <Tooltip label={t("Interrupt and send now")} withArrow>
+                    onClick={() => sendNow(m.id)}
-                    <ActionIcon
+                    aria-label={t("Send now")}
-                      size="xs"
+                  >
-                      variant="subtle"
+                    <IconPlayerPlayFilled size={12} />
-                      color="blue"
+                  </ActionIcon>
-                      onClick={() => sendNow(m.id)}
+                </Tooltip>
-                      aria-label={t("Send now")}
-                    >
-                      <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/auth/hooks/use-auth.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// react-i18next: identity t() so the hook renders without an i18n provider.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+// react-router-dom: only useNavigate is used by the hook.
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+// The auth service is the network boundary; stub login/logout per test.
+const loginMock = vi.fn();
+const logoutMock = vi.fn();
+vi.mock("@/features/auth/services/auth-service", () => ({
+  login: (...args: unknown[]) => loginMock(...args),
+  logout: (...args: unknown[]) => logoutMock(...args),
+  forgotPassword: vi.fn(),
+  passwordReset: vi.fn(),
+  setupWorkspace: vi.fn(),
+  verifyUserToken: vi.fn(),
+}));
+
+vi.mock("@/features/workspace/services/workspace-service.ts", () => ({
+  acceptInvitation: vi.fn(),
+}));
+
+// The offline cache purge is the unit under test — assert it is invoked.
+const clearOfflineCacheMock = vi.fn();
+vi.mock("@/features/offline/clear-offline-cache", () => ({
+  clearOfflineCache: () => clearOfflineCacheMock(),
+}));
+
+// app-route helpers are pure config; provide deterministic values.
+vi.mock("@/lib/app-route.ts", () => ({
+  default: { AUTH: { LOGIN: "/login" }, HOME: "/home" },
+  getPostLoginRedirect: () => "/home",
+}));
+
+// Mantine notifications: avoid touching the DOM-bound notification system.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+import useAuth from "./use-auth";
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  loginMock.mockReset();
+  loginMock.mockResolvedValue(undefined);
+  logoutMock.mockReset();
+  logoutMock.mockResolvedValue(undefined);
+  clearOfflineCacheMock.mockReset();
+  clearOfflineCacheMock.mockResolvedValue(undefined);
+});
+
+describe("useAuth.handleSignIn", () => {
+  it("clears the offline cache BEFORE logging in (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    loginMock.mockImplementation(async () => {
+      order.push("login");
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    // The purge must run before the new session's login resolves.
+    expect(order).toEqual(["clear", "login"]);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+
+  it("does not block sign-in when the cache purge throws (best-effort)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    // Login still proceeds despite the cleanup failure.
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+});
+
+describe("useAuth.handleLogout", () => {
+  const replaceMock = vi.fn();
+  let originalLocation: Location;
+
+  beforeEach(() => {
+    replaceMock.mockReset();
+    // window.location.replace is the post-logout redirect. jsdom's real `replace`
+    // is a non-configurable method that warns "not implemented", so swap the
+    // whole location object for one whose `replace` we can capture.
+    originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { replace: replaceMock },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: originalLocation,
+    });
+  });
+
+  it("purges the offline cache exactly once BEFORE redirecting (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    replaceMock.mockImplementation((url: string) => {
+      order.push(`replace:${url}`);
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    // Purge must complete before the redirect (which would otherwise interrupt
+    // the async cleanup).
+    expect(order).toEqual(["clear", "replace:/login?logout=1"]);
+  });
+
+  it("still redirects when the cache purge throws (best-effort, never blocks logout)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    // The thrown purge error is swallowed and the redirect still fires.
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledWith("/login?logout=1");
+  });
+});

apps/client/src/features/auth/hooks/use-auth.ts

@@ -24,6 +24,7 @@ import APP_ROUTE, { getPostLoginRedirect } from "@/lib/app-route.ts";
 import { RESET } from "jotai/utils";
 import { useTranslation } from "react-i18next";
 import { clearPersistedTreeCaches } from "@/features/page/tree/atoms/tree-data-atom";
+import { clearOfflineCache } from "@/features/offline/clear-offline-cache";
 
 export default function useAuth() {
   const { t } = useTranslation();
@@ -34,6 +35,20 @@ export default function useAuth() {
   const handleSignIn = async (data: ILogin) => {
     setIsLoading(true);
 
+    // Purge any previous user's offline data BEFORE signing in (mirrors logout).
+    // On a shared/kiosk device the prior session may have ended WITHOUT an
+    // explicit logout (cookie/JWT expiry, tab close, force-quit), leaving user
+    // A's persisted query cache (gitmost-rq-cache) and Yjs page bodies
+    // (page.<id>) in IndexedDB. Without this purge user B would briefly read A's
+    // cached currentUser/pages/comments on first render (UserProvider serves the
+    // cached user) and A's page bodies would stay readable offline. Best-effort:
+    // never block sign-in on cache cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block sign-in on cache cleanup
+    }
+
     try {
       await login(data);
       setIsLoading(false);
@@ -129,6 +144,13 @@ export default function useAuth() {
     // remain.)
     clearPersistedTreeCaches();
     await logout();
+    // Purge the previous user's offline data while the page is still alive —
+    // window.location.replace below would otherwise interrupt async cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block logout on cache cleanup
+    }
     window.location.replace(`${APP_ROUTE.AUTH.LOGIN}?logout=1`);
   };
 

apps/client/src/features/auth/queries/auth-query.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { AxiosError } from "axios";
+import { collabTokenRetry } from "./auth-query";
+
+// Regression for the offline white-screen (#237/#238): offline the collab-token
+// POST rejects as an axios NETWORK error (isAxiosError === true but
+// error.response === undefined). The old predicate read `error.response.status`
+// without a guard and threw an uncaught TypeError inside the React Query retryer
+// BEFORE React mounted, blanking the whole app. The predicate must stay total.
+describe("collabTokenRetry", () => {
+  it("does NOT throw and returns a retryable value for a network error with no response (offline)", () => {
+    // An axios error with no `response` is exactly the offline/network-failure shape.
+    const networkError = new AxiosError("Network Error");
+    expect(networkError.response).toBeUndefined();
+
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, networkError);
+    }).not.toThrow();
+    // Network failures stay retryable (truthy), matching the original intent.
+    expect(result).toBe(true);
+  });
+
+  it("returns false (no retry) for a real 404 response", () => {
+    const notFound = new AxiosError("Not Found");
+    notFound.response = { status: 404 } as AxiosError["response"];
+    expect(collabTokenRetry(0, notFound)).toBe(false);
+  });
+
+  it("retries for a non-404 response (e.g. 500)", () => {
+    const serverError = new AxiosError("Server Error");
+    serverError.response = { status: 500 } as AxiosError["response"];
+    expect(collabTokenRetry(0, serverError)).toBe(true);
+  });
+
+  it("does not throw and retries for a non-axios error", () => {
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, new Error("boom"));
+    }).not.toThrow();
+    expect(result).toBe(true);
+  });
+});

apps/client/src/features/auth/queries/auth-query.tsx

@@ -3,6 +3,27 @@ import { getCollabToken, verifyUserToken } from "../services/auth-service";
 import { ICollabToken, IVerifyUserToken } from "../types/auth.types";
 import { isAxiosError } from "axios";
 
+/**
+ * Retry predicate for the collab-token query.
+ *
+ * Offline (or any network failure) the POST rejects as an axios NETWORK error:
+ * `isAxiosError(error) === true` but `error.response === undefined`. Reading
+ * `error.response.status` without a guard threw an uncaught TypeError inside the
+ * React Query retryer BEFORE React mounted, white-screening the whole app on an
+ * offline cold boot (#237/#238). Optional-chaining `error.response?.status`
+ * keeps the predicate total: a network error (no response) is retryable, a real
+ * 404 is not. Extracted (and exported) so it can be unit-tested in isolation.
+ */
+export function collabTokenRetry(
+  _failureCount: number,
+  error: Error,
+): boolean {
+  if (isAxiosError(error) && error.response?.status === 404) {
+    return false;
+  }
+  return true;
+}
+
 export function useVerifyUserTokenQuery(
   verify: IVerifyUserToken,
 ): UseQueryResult<any, Error> {
@@ -22,13 +43,7 @@ export function useCollabToken(): UseQueryResult<ICollabToken, Error> {
     //refetchInterval: 12 * 60 * 60 * 1000, // 12hrs
     //refetchIntervalInBackground: true,
     refetchOnMount: true,
-    //@ts-ignore
+    retry: collabTokenRetry,
-    retry: (failureCount, error) => {
-      if (isAxiosError(error) && error.response.status === 404) {
-        return false;
-      }
-      return 10;
-    },
     retryDelay: (retryAttempt) => {
       // Exponential backoff: 5s, 10s, 20s, etc.
       return 5000 * Math.pow(2, retryAttempt - 1);

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/comment/queries/comment-query.ts

@@ -23,6 +23,7 @@ import { notifications } from "@mantine/notifications";
 import { IPagination } from "@/lib/types.ts";
 import { useTranslation } from "react-i18next";
 import { useEffect, useMemo } from "react";
+import { offlineMutationKeys } from "@/features/offline/offline-mutations";
 
 export const RQ_KEY = (pageId: string) => ["comments", pageId];
 
@@ -66,6 +67,9 @@ export function useCreateCommentMutation() {
   const { t } = useTranslation();
 
   return useMutation<IComment, Error, Partial<IComment>>({
+    // Stable key so a paused comment-create restored from IndexedDB after an
+    // offline reload finds its default mutationFn and is replayed on reconnect.
+    mutationKey: offlineMutationKeys.createComment,
     mutationFn: (data) => createComment(data),
     onSuccess: (newComment) => {
       const cache = queryClient.getQueryData(

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";
 
@@ -14,6 +11,12 @@ export const readOnlyEditorAtom = atom<Editor | null>(null);
 
 export const yjsConnectionStatusAtom = atom<string>("");
 
+// Local (IndexedDB) persistence sync state for the current page's Y.Doc.
+export const isLocalSyncedAtom = atom<boolean>(false);
+
+// Remote (Hocuspocus) sync state for the current page's Y.Doc.
+export const isRemoteSyncedAtom = atom<boolean>(false);
+
 export const showLinkMenuAtom = atom(false);
 
 // Current page's edit mode — initialized from the user's saved preference on

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/contexts/editor-providers-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import type * as Y from "yjs";
+
+// Shared collaboration providers lifted above the title/body editors so that
+// both siblings bind to the SAME Y.Doc and HocuspocusProvider. The title lives
+// in a dedicated 'title' fragment of the same doc as the body.
+export interface EditorProvidersContextValue {
+  ydoc: Y.Doc;
+  remote: HocuspocusProvider;
+  providersReady: boolean;
+}
+
+export const EditorProvidersContext =
+  createContext<EditorProvidersContextValue | null>(null);
+
+// Returns the shared providers, or null when rendered outside of a provider.
+// Consumers must be null-safe (the body editor falls back to a non-collab mode).
+export function useEditorProviders(): EditorProvidersContextValue | null {
+  return useContext(EditorProvidersContext);
+}

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/full-editor.tsx

@@ -34,6 +34,8 @@ import {
 } from "@/features/editor/atoms/editor-atoms.ts";
 import { DictationGroup } from "@/features/editor/components/fixed-toolbar/groups/dictation-group";
 import { GenerateTitleGroup } from "@/features/editor/components/fixed-toolbar/groups/generate-title-group";
+import { usePageCollabProviders } from "@/features/editor/hooks/use-page-collab-providers";
+import { EditorProvidersContext } from "@/features/editor/contexts/editor-providers-context";
 
 const MemoizedTitleEditor = React.memo(TitleEditor);
 const MemoizedPageEditor = React.memo(PageEditor);
@@ -80,16 +82,24 @@ export function FullEditor({
   // AI title generation is gated by the general AI chat flag (the same toggle
   // that enables the chat agent); the server enforces it too (#199).
   const isTitleGenEnabled = workspace?.settings?.ai?.chat === true;
-  const fullPageWidth = user.settings?.preferences?.fullPageWidth;
+  // `user` can momentarily be null during logout teardown (the currentUser atom
+  // is reset before this subtree unmounts). Optional-chain every access so the
+  // teardown render does not throw "Cannot read properties of null (reading
+  // 'settings')".
+  const fullPageWidth = user?.settings?.preferences?.fullPageWidth;
   const editorToolbarEnabled =
-    user.settings?.preferences?.editorToolbar ?? false;
+    user?.settings?.preferences?.editorToolbar ?? false;
   const [currentPageEditMode, setCurrentPageEditMode] = useAtom(
     currentPageEditModeAtom,
   );
   const userPageEditMode =
-    user.settings?.preferences?.pageEditMode ?? PageEditMode.Edit;
+    user?.settings?.preferences?.pageEditMode ?? PageEditMode.Edit;
   const isEditMode = currentPageEditMode === PageEditMode.Edit;
 
+  // Single shared Y.Doc + HocuspocusProvider for both the title and body
+  // editors (title lives in the 'title' fragment of the same doc).
+  const { ydoc, remote, providersReady } = usePageCollabProviders(pageId);
+
   // Apply the user's saved preference only once on initial load, not on every
   // page navigation — so the mode sticks across navigations within a session.
   useEffect(() => {
@@ -110,28 +120,32 @@ export function FullEditor({
       )}
       <MemoizedDeletedPageBanner slugId={slugId} />
       <MemoizedTemporaryNoteBanner slugId={slugId} />
-      <MemoizedTitleEditor
+      <EditorProvidersContext.Provider
-        pageId={pageId}
+        value={ydoc && remote ? { ydoc, remote, providersReady } : null}
-        slugId={slugId}
+      >
-        title={title}
+        <MemoizedTitleEditor
-        spaceSlug={spaceSlug}
+          pageId={pageId}
-        editable={editable}
+          slugId={slugId}
-      />
+          title={title}
-      <PageByline
+          spaceSlug={spaceSlug}
-        pageId={pageId}
+          editable={editable}
-        creator={creator}
+        />
-        contributors={contributors}
+        <PageByline
-        editable={editable}
+          pageId={pageId}
-        isEditMode={isEditMode}
+          creator={creator}
-        isDictationEnabled={isDictationEnabled}
+          contributors={contributors}
-        isTitleGenEnabled={isTitleGenEnabled}
+          editable={editable}
-      />
+          isEditMode={isEditMode}
-      <MemoizedPageEditor
+          isDictationEnabled={isDictationEnabled}
-        pageId={pageId}
+          isTitleGenEnabled={isTitleGenEnabled}
-        editable={editable}
+        />
-        content={content}
+        <MemoizedPageEditor
-        canComment={canComment}
+          pageId={pageId}
-      />
+          editable={editable}
+          content={content}
+          canComment={canComment}
+        />
+      </EditorProvidersContext.Provider>
     </Container>
   );
 }

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/collab-token.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// jwt-decode is mocked so we can drive the four token states deterministically
+// (decode success with a chosen exp, or a thrown decode error).
+const decodeMock = vi.hoisted(() => vi.fn());
+vi.mock("jwt-decode", () => ({
+  jwtDecode: decodeMock,
+}));
+
+import { collabTokenNeedsRefresh } from "./collab-token";
+
+const NOW_MS = 1_000_000_000; // fixed "now" in ms (so NOW_MS/1000 seconds)
+
+beforeEach(() => {
+  decodeMock.mockReset();
+});
+
+describe("collabTokenNeedsRefresh", () => {
+  it("returns true when there is no token (fetch a fresh one)", () => {
+    expect(collabTokenNeedsRefresh(undefined, NOW_MS)).toBe(true);
+    // jwtDecode must not even be called for a missing token.
+    expect(decodeMock).not.toHaveBeenCalled();
+  });
+
+  it("returns true when the token is malformed (jwtDecode throws)", () => {
+    decodeMock.mockImplementation(() => {
+      throw new Error("invalid token");
+    });
+    expect(collabTokenNeedsRefresh("garbage", NOW_MS)).toBe(true);
+  });
+
+  it("returns false for a valid, not-yet-expired token (no reconnect)", () => {
+    // exp is in the future relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 + 60 });
+    expect(collabTokenNeedsRefresh("good", NOW_MS)).toBe(false);
+  });
+
+  it("returns true for a valid but expired token (refresh + reconnect)", () => {
+    // exp is in the past relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 - 60 });
+    expect(collabTokenNeedsRefresh("expired", NOW_MS)).toBe(true);
+  });
+
+  it("treats exp exactly equal to now as expired (>= boundary)", () => {
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 });
+    expect(collabTokenNeedsRefresh("boundary", NOW_MS)).toBe(true);
+  });
+});

apps/client/src/features/editor/hooks/collab-token.ts

@@ -0,0 +1,26 @@
+import { jwtDecode } from "jwt-decode";
+
+/**
+ * Decide whether a collab token must be refreshed before reconnecting after an
+ * onAuthenticationFailed event. Pure and side-effect free so the four token
+ * states can be unit-tested directly:
+ *   - no token              -> true  (fetch a fresh one and reconnect)
+ *   - undecodable/malformed -> true  (jwtDecode throws -> refresh)
+ *   - valid, not expired    -> false (token is still good; do NOT reconnect)
+ *   - valid, expired        -> true  (refresh + reconnect)
+ *
+ * `nowMs` is injectable for deterministic tests; it defaults to `Date.now()`.
+ */
+export function collabTokenNeedsRefresh(
+  token: string | undefined,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!token) return true;
+  try {
+    const payload = jwtDecode<{ exp: number }>(token);
+    return nowMs / 1000 >= payload.exp;
+  } catch {
+    // malformed/undecodable token -> refresh
+    return true;
+  }
+}

apps/client/src/features/editor/hooks/use-generate-page-title.test.tsx

@@ -139,7 +139,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("happy path: applies the title, refreshes cache, writes the field, broadcasts", async () => {
+  it("happy path: applies the title, refreshes cache, broadcasts, and does NOT write the editor", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor();
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -157,9 +157,11 @@ describe("useGeneratePageTitle", () => {
       title: "Generated Title",
     });
     expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    expect(titleEditor.commands.setContent).toHaveBeenCalledWith(
+    // The title editor is bound to the Yjs `title` fragment; the server REST
-      "Generated Title",
+    // update reseeds that fragment and the reseed reaches the bound editor on
-    );
+    // its own. Writing here too would double/garble the title, so the hook must
+    // NOT touch the editor (regression guard for the Yjs duplication trap).
+    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
     expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
     expect(notificationsShowMock).toHaveBeenCalledWith(
@@ -167,7 +169,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("does NOT write the visible title field when the user navigated away during generation", async () => {
+  it("keeps the DB write keyed by the captured pageId and still broadcasts after navigation", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor(); // persistent across navigation
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -203,55 +205,9 @@ describe("useGeneratePageTitle", () => {
       pageId: "pageA",
       title: "Generated Title",
     });
-    // ...but we must NOT stamp page A's title into page B's visible field.
+    // ...the hook never writes the editor regardless of navigation...
     expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
+    // ...and the change is still broadcast to other clients.
-    expect(emitMock).toHaveBeenCalled();
-  });
-
-  it("does NOT write the visible title field when the title editor is focused", async () => {
-    const store = createStore();
-    const titleEditor = makeTitleEditor();
-    store.set(pageEditorAtom as never, makePageEditor("pageA"));
-    store.set(titleEditorAtom as never, titleEditor);
-
-    // Resolve generation under our control so we can mark the live title editor
-    // as focused before the post-generation write runs.
-    let resolveTitle!: (t: string) => void;
-    generatePageTitleMock.mockReturnValue(
-      new Promise<string>((res) => {
-        resolveTitle = res;
-      }),
-    );
-    updateTitleMock.mockResolvedValue(PAGE_A);
-    const { result } = setup("pageA", store);
-
-    let pending!: Promise<void>;
-    act(() => {
-      pending = result.current.mutateAsync();
-    });
-
-    // The user clicked into the title field while the model ran — overwriting it
-    // now would clobber what they are actively typing.
-    act(() => {
-      (titleEditor as { isFocused: boolean }).isFocused = true;
-    });
-
-    await act(async () => {
-      resolveTitle("Generated Title");
-      await pending;
-    });
-
-    // The DB write still persists the value...
-    expect(updateTitleMock).toHaveBeenCalledWith({
-      pageId: "pageA",
-      title: "Generated Title",
-    });
-    expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    // ...but the visible field is left alone while it is focused.
-    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
   });
 

apps/client/src/features/editor/hooks/use-generate-page-title.ts

@@ -1,13 +1,9 @@
-import { useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
-  pageEditorAtom,
-  titleEditorAtom,
-} from "@/features/editor/atoms/editor-atoms.ts";
 import {
   updatePageData,
   useUpdateTitlePageMutation,
@@ -33,18 +29,9 @@ const MAX_CONTENT_CHARS = 20000;
 export function useGeneratePageTitle(pageId: string) {
   const { t } = useTranslation();
   const pageEditor = useAtomValue(pageEditorAtom);
-  const titleEditor = useAtomValue(titleEditorAtom);
   const { mutateAsync: updateTitle } = useUpdateTitlePageMutation();
   const emit = useQueryEmit();
 
-  // The page/title editors come from GLOBAL atoms that re-point when the user
-  // navigates to another page. The mutation below awaits the model for 1-3s, and
-  // its closure captures the editors from the render that started it. Keep a live
-  // reference so the post-generation write targets whatever page is on screen
-  // *now*, not the page the generation was started from.
-  const editorsRef = useRef({ pageEditor, titleEditor });
-  editorsRef.current = { pageEditor, titleEditor };
-
   return useMutation<void, Error, void>({
     mutationFn: async () => {
       if (!pageEditor || pageEditor.isDestroyed) return;
@@ -70,33 +57,15 @@ export function useGeneratePageTitle(pageId: string) {
       const page = await updateTitle({ pageId, title }); // POST /pages/update
       updatePageData(page); // refresh the react-query cache
 
-      // Reflect the new title in the field immediately. The button lives in the
+      // Do NOT write the title into the editor here. The title editor is bound to
-      // byline, so the title editor is not focused — setContent is safe and stays
+      // the Yjs `title` fragment and Yjs is the source of truth. The server REST
-      // undoable through its History extension (Ctrl/Cmd+Z reverts the change).
+      // /pages/update reseeds that fragment (writePageTitle → writeTitleFragment,
-      //
+      // a full clear+replace) and the reseed reaches the bound title editor on
-      // Guard against navigation during generation: if the user switched pages
+      // its own as a remote provider update. The old REST-era setContent here
-      // while the model ran, the (persistent) title editor now shows ANOTHER
+      // would race that reseed and double/garble the title (the "Yjs duplication
-      // page, so writing here would drop page A's title into page B's visible
+      // trap"), so it is intentionally omitted. The DB write above is keyed by
-      // field. page-editor.tsx stamps the live page editor with its pageId
+      // the captured `pageId`, so it stays correct even if the user navigated
-      // (`editor.storage.pageId`), mirroring TitleEditor's `activePageId !==
+      // away during generation.
-      // pageId` guard — bail the visible write unless that live editor still
-      // belongs to the page this title was generated for. The DB write above is
-      // already correct (keyed by the captured `pageId`), and the broadcast below
-      // still propagates page A's change to other clients.
-      const livePageEditor = editorsRef.current.pageEditor;
-      const liveTitleEditor = editorsRef.current.titleEditor;
-      // `storage.pageId` is stamped untyped in page-editor.tsx's onCreate.
-      const livePageId = (livePageEditor?.storage as { pageId?: string })
-        ?.pageId;
-      const stillOnPage = livePageId === pageId;
-      if (
-        stillOnPage &&
-        liveTitleEditor &&
-        !liveTitleEditor.isDestroyed &&
-        !liveTitleEditor.isFocused
-      ) {
-        liveTitleEditor.commands.setContent(page.title);
-      }
 
       // Broadcast to other clients, mirroring TitleEditor.saveTitle's event shape.
       const event: UpdateEvent = {

apps/client/src/features/editor/hooks/use-page-collab-providers.ts

@@ -0,0 +1,189 @@
+import { useEffect, useRef, useState } from "react";
+import { IndexeddbPersistence } from "y-indexeddb";
+import * as Y from "yjs";
+import {
+  HocuspocusProvider,
+  onStatusParameters,
+  WebSocketStatus,
+  HocuspocusProviderWebsocket,
+  onSyncedParameters,
+  onStatelessParameters,
+} from "@hocuspocus/provider";
+import { useAtom, useSetAtom } from "jotai";
+import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
+import {
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
+  yjsConnectionStatusAtom,
+} from "@/features/editor/atoms/editor-atoms";
+import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
+import { 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";
+import { useParams } from "react-router-dom";
+import { extractPageSlugId } from "@/lib";
+import { FIVE_MINUTES } from "@/lib/constants.ts";
+import { collabTokenNeedsRefresh } from "@/features/editor/hooks/collab-token";
+import { pageYdocName } from "@/features/editor/page-ydoc-name";
+import { pageKeys } from "@/features/page/queries/page-query";
+
+export interface PageCollabProviders {
+  ydoc: Y.Doc | null;
+  remote: HocuspocusProvider | null;
+  socket: HocuspocusProviderWebsocket | null;
+  providersReady: boolean;
+}
+
+/**
+ * Owns the full collaboration provider lifecycle for a page so that the title
+ * and body editors can share a single Y.Doc + HocuspocusProvider. The behavior
+ * is relocated verbatim from page-editor.tsx: it creates the providers once per
+ * pageId, connects/disconnects on idle/visibility, attaches each render,
+ * destroys on unmount, refreshes the collab token on auth failure, and applies
+ * the onStateless 'page.updated' cache update.
+ */
+export function usePageCollabProviders(pageId: string): PageCollabProviders {
+  const collaborationURL = useCollaborationUrl();
+  const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
+    yjsConnectionStatusAtom,
+  );
+  const setIsLocalSyncedAtom = useSetAtom(isLocalSyncedAtom);
+  const setIsRemoteSyncedAtom = useSetAtom(isRemoteSyncedAtom);
+  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
+  // The provider-creating effect runs only once per pageId, so any token read
+  // inside its handlers would be captured STALE (the old token at first render).
+  // Mirror the latest token into a ref the auth-failure handler can read live.
+  const collabTokenRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    collabTokenRef.current = collabQuery?.token;
+  }, [collabQuery?.token]);
+  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
+  const documentState = useDocumentVisibility();
+  const { pageSlug } = useParams();
+  const slugId = extractPageSlugId(pageSlug);
+
+  // Providers only created once per pageId
+  const providersRef = useRef<{
+    ydoc: Y.Doc;
+    local: IndexeddbPersistence;
+    remote: HocuspocusProvider;
+    socket: HocuspocusProviderWebsocket;
+  } | null>(null);
+  const [providersReady, setProvidersReady] = useState(false);
+
+  useEffect(() => {
+    if (!providersRef.current) {
+      const documentName = pageYdocName(pageId);
+      const ydoc = new Y.Doc();
+      const local = new IndexeddbPersistence(documentName, ydoc);
+      const socket = new HocuspocusProviderWebsocket({
+        url: collaborationURL,
+      });
+      const onLocalSyncedHandler = () => {
+        setIsLocalSyncedAtom(true);
+      };
+      const onStatusHandler = (event: onStatusParameters) => {
+        setYjsConnectionStatus(event.status);
+      };
+      const onSyncedHandler = (event: onSyncedParameters) => {
+        setIsRemoteSyncedAtom(event.state);
+      };
+      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
+        try {
+          const message = JSON.parse(payload);
+          if (message?.type !== "page.updated" || !message.updatedAt) return;
+          const pageData = queryClient.getQueryData<IPage>(
+            pageKeys.detail(slugId),
+          );
+          if (pageData) {
+            queryClient.setQueryData(pageKeys.detail(slugId), {
+              ...pageData,
+              updatedAt: message.updatedAt,
+              ...(message.lastUpdatedBy && {
+                lastUpdatedBy: message.lastUpdatedBy,
+              }),
+            });
+          }
+        } catch {
+          // ignore unrelated stateless messages
+        }
+      };
+      const onAuthenticationFailedHandler = () => {
+        // Read the token from the ref, not the closed-over `collabQuery`: this
+        // handler is created once and would otherwise decode a stale token after
+        // a refetch. A missing/malformed token must NOT crash the handler —
+        // jwtDecode(undefined) throws — so treat any decode failure as "needs
+        // refresh" and proceed to refetch + reconnect instead of getting stuck.
+        if (!collabTokenNeedsRefresh(collabTokenRef.current)) return;
+        refetchCollabToken().then((result) => {
+          if (result.data?.token) {
+            socket.disconnect();
+            setTimeout(() => {
+              remote.configuration.token = result.data.token;
+              socket.connect();
+            }, 100);
+          }
+        });
+      };
+      const remote = new HocuspocusProvider({
+        websocketProvider: socket,
+        name: documentName,
+        document: ydoc,
+        token: collabQuery?.token,
+        onAuthenticationFailed: onAuthenticationFailedHandler,
+        onStatus: onStatusHandler,
+        onSynced: onSyncedHandler,
+        onStateless: onStatelessHandler,
+      });
+
+      local.on("synced", onLocalSyncedHandler);
+      providersRef.current = { ydoc, socket, local, remote };
+      setProvidersReady(true);
+    } else {
+      setProvidersReady(true);
+    }
+    // Only destroy on final unmount
+    return () => {
+      providersRef.current?.socket.destroy();
+      providersRef.current?.remote.destroy();
+      providersRef.current?.local.destroy();
+      providersRef.current = null;
+      // Reset shared sync state on page change/unmount.
+      setIsLocalSyncedAtom(false);
+      setIsRemoteSyncedAtom(false);
+    };
+  }, [pageId]);
+
+  // Only connect/disconnect on tab/idle, not destroy
+  useEffect(() => {
+    if (!providersReady || !providersRef.current) return;
+    const socket = providersRef.current.socket;
+
+    if (
+      isIdle &&
+      documentState === "hidden" &&
+      yjsConnectionStatus === WebSocketStatus.Connected
+    ) {
+      socket.disconnect();
+      return;
+    }
+    if (
+      documentState === "visible" &&
+      yjsConnectionStatus === WebSocketStatus.Disconnected
+    ) {
+      resetIdle();
+      socket.connect();
+    }
+  }, [isIdle, documentState, providersReady, resetIdle]);
+
+  // Attach here, to make sure the connection gets properly established
+  providersRef.current?.remote.attach();
+
+  return {
+    ydoc: providersRef.current?.ydoc ?? null,
+    remote: providersRef.current?.remote ?? null,
+    socket: providersRef.current?.socket ?? null,
+    providersReady,
+  };
+}

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

@@ -6,16 +6,7 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { IndexeddbPersistence } from "y-indexeddb";
+import { WebSocketStatus } from "@hocuspocus/provider";
-import * as Y from "yjs";
-import {
-  HocuspocusProvider,
-  onStatusParameters,
-  WebSocketStatus,
-  HocuspocusProviderWebsocket,
-  onSyncedParameters,
-  onStatelessParameters,
-} from "@hocuspocus/provider";
 import {
   Editor,
   EditorContent,
@@ -28,14 +19,16 @@ import {
   mainExtensions,
 } from "@/features/editor/extensions/extensions";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
-import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
   currentPageEditModeAtom,
   dictationAvailabilityAtom,
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -59,11 +52,9 @@ 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 } from "@mantine/hooks";
-import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
@@ -74,12 +65,9 @@ import {
   GitmostInsertRecordingResult,
   gitmostInsertRecordingIntoEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
-import { FIVE_MINUTES } from "@/lib/constants.ts";
 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";
@@ -114,7 +102,6 @@ export default function PageEditor({
   canComment,
 }: PageEditorProps) {
   const { t } = useTranslation();
-  const collaborationURL = useCollaborationUrl();
   const isComponentMounted = useRef(false);
   const editorRef = useRef<Editor | null>(null);
 
@@ -128,22 +115,10 @@ export default function PageEditor({
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
   const [showReadOnlyCommentPopup] = useAtom(showReadOnlyCommentPopupAtom);
-  const [isLocalSynced, setIsLocalSynced] = useState(false);
-  const [isRemoteSynced, setIsRemoteSynced] = useState(false);
   const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
     yjsConnectionStatusAtom,
   );
   const menuContainerRef = useRef(null);
-  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
-  // Always holds the latest collab token. The provider effect below runs once
-  // per pageId, so a handler created inside it would otherwise close over a
-  // stale `collabQuery`. Reading the ref gives the current token instead.
-  const collabTokenRef = useRef<string | undefined>(undefined);
-  useEffect(() => {
-    collabTokenRef.current = collabQuery?.token;
-  }, [collabQuery?.token]);
-  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
-  const documentState = useDocumentVisibility();
   const { pageSlug } = useParams();
   const slugId = extractPageSlugId(pageSlug);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
@@ -153,152 +128,27 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  // Providers only created once per pageId
-  const providersRef = useRef<{
-    local: IndexeddbPersistence;
-    remote: HocuspocusProvider;
-    socket: HocuspocusProviderWebsocket;
-  } | null>(null);
-  const [providersReady, setProvidersReady] = useState(false);
 
-  useEffect(() => {
+  // Shared providers + Y.Doc lifted into full-editor via context. The provider
-    if (!providersRef.current) {
+  // lifecycle (creation, idle/visibility connect, attach, destroy, token
-      const documentName = `page.${pageId}`;
+  // refresh) lives in usePageCollabProviders. Null-safe when rendered without
-      const ydoc = new Y.Doc();
+  // the context (defensive) — in practice full-editor always provides it.
-      const local = new IndexeddbPersistence(documentName, ydoc);
+  const editorProviders = useEditorProviders();
-      const socket = new HocuspocusProviderWebsocket({
+  const remote = editorProviders?.remote ?? null;
-        url: collaborationURL,
+  const providersReady = editorProviders?.providersReady ?? false;
-      });
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
-      const onLocalSyncedHandler = () => {
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
-        setIsLocalSynced(true);
-      };
-      const onStatusHandler = (event: onStatusParameters) => {
-        setYjsConnectionStatus(event.status);
-      };
-      const onSyncedHandler = (event: onSyncedParameters) => {
-        setIsRemoteSynced(event.state);
-      };
-      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
-        try {
-          const message = JSON.parse(payload);
-          if (message?.type !== "page.updated" || !message.updatedAt) return;
-          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-          if (pageData) {
-            queryClient.setQueryData(["pages", slugId], {
-              ...pageData,
-              updatedAt: message.updatedAt,
-              ...(message.lastUpdatedBy && {
-                lastUpdatedBy: message.lastUpdatedBy,
-              }),
-            });
-          }
-        } catch {
-          // ignore unrelated stateless messages
-        }
-      };
-      const onAuthenticationFailedHandler = () => {
-        // Read the latest token via the ref (the closure-captured `collabQuery`
-        // may be stale). Guard the decode: a missing or unparseable token must
-        // not throw "Invalid token specified" and should trigger a refresh so
-        // the editor reconnects even when the initial token fetch failed.
-        const token = collabTokenRef.current;
-        let needsRefresh = true; // no/unparseable token -> fetch a fresh one and reconnect
-        if (token) {
-          try {
-            // A token that decodes but lacks a numeric `exp` must be treated as
-            // expired (`Date.now()/1000 >= undefined` is `false`, which would
-            // otherwise skip the reconnect), so refresh on any missing/non-number exp.
-            const exp = jwtDecode<{ exp?: number }>(token).exp;
-            needsRefresh = typeof exp !== "number" || Date.now() / 1000 >= exp;
-          } catch {
-            needsRefresh = true;
-          }
-        }
-        if (!needsRefresh) return;
-        refetchCollabToken().then((result) => {
-          if (result.data?.token) {
-            socket.disconnect();
-            setTimeout(() => {
-              remote.configuration.token = result.data.token;
-              socket.connect();
-            }, 100);
-          }
-        });
-      };
-      const remote = new HocuspocusProvider({
-        websocketProvider: socket,
-        name: documentName,
-        document: ydoc,
-        token: collabQuery?.token,
-        onAuthenticationFailed: onAuthenticationFailedHandler,
-        onStatus: onStatusHandler,
-        onSynced: onSyncedHandler,
-        onStateless: onStatelessHandler,
-      });
-
-      local.on("synced", onLocalSyncedHandler);
-      providersRef.current = { socket, local, remote };
-      setProvidersReady(true);
-    } else {
-      setProvidersReady(true);
-    }
-    // Only destroy on final unmount
-    return () => {
-      providersRef.current?.socket.destroy();
-      providersRef.current?.remote.destroy();
-      providersRef.current?.local.destroy();
-      providersRef.current = null;
-    };
-  }, [pageId]);
-
-  // Only connect/disconnect on tab/idle, not destroy
-  useEffect(() => {
-    if (!providersReady || !providersRef.current) return;
-    const socket = providersRef.current.socket;
-
-    if (
-      isIdle &&
-      documentState === "hidden" &&
-      yjsConnectionStatus === WebSocketStatus.Connected
-    ) {
-      socket.disconnect();
-      return;
-    }
-    if (
-      documentState === "visible" &&
-      yjsConnectionStatus === WebSocketStatus.Disconnected
-    ) {
-      resetIdle();
-      socket.connect();
-    }
-  }, [isIdle, documentState, providersReady, resetIdle]);
-
-  // Attach the remote provider once it's ready (and again after a pageId swap
-  // 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) {
+    if (!providersReady || !remote || !currentUser?.user) {
       return mainExtensions;
     }
 
-    const remoteProvider = providersRef.current.remote;
-
     return [
       ...mainExtensions,
-      ...collabExtensions(remoteProvider, currentUser?.user),
+      ...collabExtensions(remote, currentUser?.user),
     ];
-  }, [providersReady, currentUser?.user]);
+  }, [providersReady, remote, 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(
     {
@@ -404,11 +254,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 +304,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;
 
@@ -652,7 +513,7 @@ export default function PageEditor({
             {editor &&
               !editorIsEditable &&
               (editable || canComment) &&
-              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
+              remote && <ReadonlyBubbleMenu editor={editor} />}
             {showCommentPopup && (
               <CommentDialog editor={editor} pageId={pageId} />
             )}

apps/client/src/features/editor/page-ydoc-name.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of truth for the IndexedDB / Hocuspocus document name of a
+ * page's collaborative Yjs doc.
+ *
+ * The `page.<id>` convention is shared knowledge across three call sites: the
+ * live editor providers (`use-page-collab-providers`), the offline warm path
+ * (`make-offline`), and the offline purge (`clear-offline-cache`, which matches
+ * the databases to delete by this prefix). Centralizing it here stops those
+ * sites from silently drifting apart.
+ */
+export const PAGE_YDOC_NAME_PREFIX = "page.";
+
+export const pageYdocName = (pageId: string): string =>
+  `${PAGE_YDOC_NAME_PREFIX}${pageId}`;

apps/client/src/features/editor/title-collab.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// isChangeOrigin is mocked so we can simulate local vs remote/collab-origin
+// transactions without constructing a real ProseMirror/Yjs transaction.
+const isChangeOriginMock = vi.hoisted(() => vi.fn());
+vi.mock("@tiptap/extension-collaboration", () => ({
+  isChangeOrigin: isChangeOriginMock,
+}));
+
+import { shouldPropagateTitleChange } from "./title-collab";
+
+beforeEach(() => {
+  isChangeOriginMock.mockReset();
+});
+
+describe("shouldPropagateTitleChange", () => {
+  it("propagates a genuine local edit (isChangeOrigin false)", () => {
+    isChangeOriginMock.mockReturnValue(false);
+    expect(shouldPropagateTitleChange({ local: true })).toBe(true);
+    expect(isChangeOriginMock).toHaveBeenCalledWith({ local: true });
+  });
+
+  it("skips a remote/collab-origin update (isChangeOrigin true)", () => {
+    isChangeOriginMock.mockReturnValue(true);
+    expect(shouldPropagateTitleChange({ remote: true })).toBe(false);
+  });
+
+  it("propagates when there is no transaction (treated as local)", () => {
+    expect(shouldPropagateTitleChange(undefined)).toBe(true);
+    // isChangeOrigin must not be called for a missing transaction.
+    expect(isChangeOriginMock).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/title-collab.ts

@@ -0,0 +1,19 @@
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+
+/**
+ * Whether a TitleEditor `onUpdate` should drive URL + tree propagation.
+ *
+ * Only genuine LOCAL edits propagate. Remote/collab-origin Yjs updates
+ * (detected via `isChangeOrigin`) are skipped so a remote title change is not
+ * re-broadcast back, which would create a feedback loop. A missing transaction
+ * is treated as a local edit (propagate).
+ *
+ * Extracted as a pure helper so the skip decision is unit-testable without
+ * mounting the full collaborative editor.
+ */
+export function shouldPropagateTitleChange(transaction: unknown): boolean {
+  return !(
+    transaction &&
+    isChangeOrigin(transaction as Parameters<typeof isChangeOrigin>[0])
+  );
+}

apps/client/src/features/editor/title-editor.test.tsx

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+// Drive the fallback-vs-collaborative switch (titleReady = providersReady &&
+// !!ydoc) by controlling what the editor-providers context returns.
+const editorProvidersValue: { ydoc: unknown; providersReady: boolean } = {
+  ydoc: null,
+  providersReady: false,
+};
+vi.mock("@/features/editor/contexts/editor-providers-context", () => ({
+  useEditorProviders: () => editorProvidersValue,
+}));
+
+// Mock the tiptap React bindings so the test does not mount a real editor:
+// useEditor returns a minimal stub and EditorContent renders a marker.
+vi.mock("@tiptap/react", () => ({
+  useEditor: () => ({
+    isInitialized: true,
+    commands: { focus: vi.fn() },
+    setEditable: vi.fn(),
+    getText: () => "",
+  }),
+  EditorContent: () => <div data-testid="collab-editor" />,
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+vi.mock("@/features/websocket/use-query-emit.ts", () => ({
+  useQueryEmit: () => vi.fn(),
+}));
+
+// page-query transitively imports @/main.tsx; mock it to a pure stub.
+vi.mock("@/features/page/queries/page-query", () => ({
+  updatePageData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData: vi.fn(), setQueryData: vi.fn() },
+}));
+
+import { TitleEditor } from "./title-editor";
+
+const baseProps = {
+  pageId: "p1",
+  slugId: "slug-1",
+  title: "My Page Title",
+  spaceSlug: "space",
+  editable: true,
+};
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  editorProvidersValue.ydoc = null;
+  editorProvidersValue.providersReady = false;
+});
+
+describe("TitleEditor fallback vs collaborative switch", () => {
+  it("renders a static <h1> with the title before the shared doc is ready", () => {
+    editorProvidersValue.ydoc = null;
+    editorProvidersValue.providersReady = false;
+
+    render(<TitleEditor {...baseProps} />);
+
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent).toBe("My Page Title");
+    // The collaborative editor must NOT mount until the doc is ready.
+    expect(screen.queryByTestId("collab-editor")).toBeNull();
+  });
+
+  it("renders the collaborative editor once the shared doc is ready", () => {
+    editorProvidersValue.ydoc = {}; // truthy shared doc
+    editorProvidersValue.providersReady = true;
+
+    render(<TitleEditor {...baseProps} />);
+
+    expect(screen.getByTestId("collab-editor")).toBeDefined();
+    // The static fallback <h1> is gone — Yjs is the single source of truth and
+    // the prop is never seeded into the collaborative editor.
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+});

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

@@ -1,5 +1,5 @@
 import "@/features/editor/styles/index.css";
-import React, { useCallback, useEffect, useState } from "react";
+import { useEffect } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import { Document } from "@tiptap/extension-document";
 import { Heading } from "@tiptap/extension-heading";
@@ -11,14 +11,11 @@ import {
   pageEditorAtom,
   titleEditorAtom,
 } from "@/features/editor/atoms/editor-atoms";
-import {
+import { pageKeys, updatePageData } from "@/features/page/queries/page-query";
-  updatePageData,
-  useUpdateTitlePageMutation,
-} from "@/features/page/queries/page-query";
 import { useDebouncedCallback, getHotkeyHandler } from "@mantine/hooks";
 import { useAtom } from "jotai";
-import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
+import { Collaboration } from "@tiptap/extension-collaboration";
-import { History } from "@tiptap/extension-history";
+import { shouldPropagateTitleChange } from "@/features/editor/title-collab";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -29,6 +26,9 @@ import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { platformModifierKey } from "@/lib";
 import { useTitleAutofocus } from "@/features/editor/hooks/use-title-autofocus";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
 
 export interface TitleEditorProps {
   pageId: string;
@@ -46,65 +46,82 @@ export function TitleEditor({
   editable,
 }: TitleEditorProps) {
   const { t } = useTranslation();
-  const { mutateAsync: updateTitlePageMutationAsync } =
-    useUpdateTitlePageMutation();
   const pageEditor = useAtomValue(pageEditorAtom);
   const [, setTitleEditor] = useAtom(titleEditorAtom);
-  const emit = useQueryEmit();
   const navigate = useNavigate();
-  const [activePageId, setActivePageId] = useState(pageId);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
 
-  const titleEditor = useEditor({
+  // Shared Y.Doc (title lives in its own 'title' fragment of the same doc as
-    extensions: [
+  // the body). Yjs is the source of truth for the title content.
-      Document.extend({
+  const editorProviders = useEditorProviders();
-        content: "heading",
+  const ydoc = editorProviders?.ydoc ?? null;
-      }),
+  const providersReady = editorProviders?.providersReady ?? false;
-      Heading.configure({
+
-        levels: [1],
+  // Until the shared doc is ready, the collaborative editor binds nothing and
-      }),
+  // would render an empty heading until the Yjs 'title' fragment hydrates. Show
-      Text,
+  // a non-editable static <h1> with the `title` prop in the meantime. The prop
-      Placeholder.configure({
+  // is NEVER fed into the collaborative editor (Yjs stays the single source of
-        placeholder: t("Untitled"),
+  // truth — seeding it would duplicate the title).
-        showOnlyWhenEditable: false,
+  const titleReady = providersReady && !!ydoc;
-      }),
+
-      History.configure({
+  const titleEditor = useEditor(
-        depth: 20,
+    {
-      }),
+      extensions: [
-      EmojiCommand,
+        Document.extend({
-    ],
+          content: "heading",
-    onCreate({ editor }) {
+        }),
-      if (editor) {
+        Heading.configure({
-        // @ts-ignore
+          levels: [1],
-        setTitleEditor(editor);
+        }),
-        setActivePageId(pageId);
+        Text,
-      }
+        Placeholder.configure({
-    },
+          placeholder: t("Untitled"),
-    onUpdate({ editor }) {
+          showOnlyWhenEditable: false,
-      debounceUpdate();
+        }),
-    },
+        // Bind the title to the dedicated 'title' fragment of the shared doc.
-    editable: editable,
+        // Collaboration also manages undo/redo, so the History extension is
-    content: title,
+        // intentionally omitted (it would conflict with Yjs). When the doc is
-    immediatelyRender: true,
+        // not ready yet the editor renders empty until the doc arrives.
-    shouldRerenderOnTransaction: false,
+        ...(ydoc
-    editorProps: {
+          ? [Collaboration.configure({ document: ydoc, field: "title" })]
-      attributes: {
+          : []),
-        "aria-label": t("Page title"),
+        EmojiCommand,
+      ],
+      onCreate({ editor }) {
+        if (editor) {
+          // @ts-ignore
+          setTitleEditor(editor);
+        }
       },
-      handleDOMEvents: {
+      onUpdate({ editor, transaction }) {
-        keydown: (_view, event) => {
+        // Drive URL + tree propagation only on genuine local edits; skip
-          if (platformModifierKey(event) && event.code === "KeyS") {
+        // remote/collab-origin Yjs updates to avoid feedback loops.
-            event.preventDefault();
+        if (!shouldPropagateTitleChange(transaction)) return;
-            return true;
+        debouncedPropagateTitle(editor.getText());
-          }
+      },
-          if (platformModifierKey(event) && event.code === "KeyK") {
+      editable: editable,
-            searchSpotlight.open();
+      immediatelyRender: true,
-            return true;
+      shouldRerenderOnTransaction: false,
-          }
+      editorProps: {
+        attributes: {
+          "aria-label": t("Page title"),
+        },
+        handleDOMEvents: {
+          keydown: (_view, event) => {
+            if (platformModifierKey(event) && event.code === "KeyS") {
+              event.preventDefault();
+              return true;
+            }
+            if (platformModifierKey(event) && event.code === "KeyK") {
+              searchSpotlight.open();
+              return true;
+            }
+          },
         },
       },
     },
-  });
+    [pageId, ydoc],
+  );
 
   useEffect(() => {
     const anchorId = window.location.hash
@@ -114,69 +131,48 @@ export function TitleEditor({
     navigate(pageSlug, { replace: true });
   }, [title]);
 
-  const saveTitle = useCallback(() => {
+  // On a local title change: update the URL slug and propagate the change to
-    if (!titleEditor || activePageId !== pageId) return;
+  // the live tree/breadcrumbs for online users. No REST round-trip — the title
-
+  // itself is persisted through Yjs. Offline this simply no-ops the socket
-    if (
+  // emit and the title syncs on reconnect.
-      titleEditor.getText() === title ||
+  const debouncedPropagateTitle = useDebouncedCallback((titleText: string) => {
-      (titleEditor.getText() === "" && title === null)
+    const anchorId = window.location.hash
-    ) {
+      ? window.location.hash.substring(1)
-      return;
+      : undefined;
-    }
+    navigate(buildPageUrl(spaceSlug, slugId, titleText, anchorId), {
-
+      replace: true,
-    updateTitlePageMutationAsync({
-      pageId: pageId,
-      title: titleEditor.getText(),
-    }).then((page) => {
-      const event: UpdateEvent = {
-        operation: "updateOne",
-        spaceId: page.spaceId,
-        entity: ["pages"],
-        id: page.id,
-        payload: {
-          title: page.title,
-          slugId: page.slugId,
-          parentPageId: page.parentPageId,
-          icon: page.icon,
-        },
-      };
-
-      if (page.title !== titleEditor.getText()) return;
-
-      updatePageData(page);
-
-      localEmitter.emit("message", event);
-      emit(event);
     });
-  }, [pageId, title, titleEditor]);
 
-  const debounceUpdate = useDebouncedCallback(saveTitle, 500);
+    const page =
+      queryClient.getQueryData<IPage>(pageKeys.detail(slugId)) ??
+      queryClient.getQueryData<IPage>(pageKeys.detail(pageId));
+    if (!page) return;
 
-  useEffect(() => {
+    const updatedPage: IPage = { ...page, title: titleText };
-    // Do not overwrite the title while the user is actively editing it. The
+
-    // server rebroadcasts PAGE_UPDATED to the author too, and that echo can
+    const event: UpdateEvent = {
-    // carry a title that lags behind what the user has just typed; resetting
+      operation: "updateOne",
-    // content from it here would drop in-progress characters and jump the
+      spaceId: page.spaceId,
-    // cursor. Apply external title changes only when the field is not focused.
+      entity: ["pages"],
-    if (
+      id: page.id,
-      titleEditor &&
+      payload: {
-      !titleEditor.isDestroyed &&
+        title: titleText,
-      !titleEditor.isFocused &&
+        slugId: page.slugId,
-      title !== titleEditor.getText()
+        parentPageId: page.parentPageId,
-    ) {
+        icon: page.icon,
-      titleEditor.commands.setContent(title);
+      },
-    }
+    };
-  }, [pageId, title, titleEditor]);
+
+    updatePageData(updatedPage);
+    // Drive the local (same-tab) tree/breadcrumb update. The cross-user tree
+    // refresh is handled server-side: the collab process extracts the renamed
+    // 'title' Yjs fragment and broadcasts a treeUpdate. The previous socket
+    // `emit(event)` here was a no-op (the gateway ignores it) and was removed.
+    localEmitter.emit("message", event);
+  }, 500);
 
   useTitleAutofocus(titleEditor, pageId);
 
-  useEffect(() => {
-    return () => {
-      // force-save title on navigation
-      saveTitle();
-    };
-  }, [pageId]);
-
   useEffect(() => {
     if (!titleEditor) return;
     titleEditor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
@@ -243,16 +239,22 @@ export function TitleEditor({
 
   return (
     <div className="page-title">
-      <EditorContent
+      {titleReady ? (
-        editor={titleEditor}
+        <EditorContent
-        onKeyDown={(event) => {
+          editor={titleEditor}
-          // First handle the search hotkey
+          onKeyDown={(event) => {
-          getHotkeyHandler([["mod+F", openSearchDialog]])(event);
+            // First handle the search hotkey
+            getHotkeyHandler([["mod+F", openSearchDialog]])(event);
 
-          // Then handle other key events
+            // Then handle other key events
-          handleTitleKeyDown(event);
+            handleTitleKeyDown(event);
-        }}
+          }}
-      />
+        />
+      ) : (
+        // Static, non-editable fallback so the title is visible before Yjs
+        // hydrates the 'title' fragment. Not wired into the collaborative editor.
+        <h1>{title}</h1>
+      )}
     </div>
   );
 }

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/home/components/new-note-button.tsx

@@ -3,6 +3,8 @@ import { IconHourglass, IconPlus } from "@tabler/icons-react";
 import { ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
+import { onlineManager } from "@tanstack/react-query";
+import { notifications } from "@mantine/notifications";
 import { useGetSpacesQuery } from "@/features/space/queries/space-query.ts";
 import { useCreatePageMutation } from "@/features/page/queries/page-query.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -36,21 +38,39 @@ function CreateNoteButton({
   const createPageMutation = useCreatePageMutation();
 
   const createNote = async (space: ISpace) => {
+    // `spaceId`/`temporary` are accepted by the create-page endpoint but are
+    // not part of the shared `IPageInput` type; cast to satisfy the mutation
+    // signature.
+    const variables = {
+      spaceId: space.id,
+      ...(temporary ? { temporary: true } : {}),
+    } as any;
+
+    if (!onlineManager.isOnline()) {
+      // Offline: the create is PAUSED and queued — its promise will not resolve
+      // until we are back online, so awaiting it here would spin the button
+      // forever. Fire it without awaiting (it persists and replays on reconnect)
+      // and tell the user it was saved offline instead of leaving a dead spinner.
+      createPageMutation.mutate(variables);
+      notifications.show({
+        color: "blue",
+        message: t("You're offline. This note will be created once you reconnect."),
+      });
+      return;
+    }
+
     try {
-      // `spaceId`/`temporary` are accepted by the create-page endpoint but are
+      const createdPage = await createPageMutation.mutateAsync(variables);
-      // not part of the shared `IPageInput` type; cast to satisfy the mutation
-      // signature.
-      const createdPage = await createPageMutation.mutateAsync({
-        spaceId: space.id,
-        ...(temporary ? { temporary: true } : {}),
-      } as any);
       navigate(buildPageUrl(space.slug, createdPage.slugId, createdPage.title));
     } catch {
       // useCreatePageMutation already surfaces a red notification on error.
     }
   };
 
-  const isPending = createPageMutation.isPending;
+  // A paused (offline) mutation stays `isPending`, so gate the spinner on it NOT
+  // being paused — otherwise the button would spin forever after an offline
+  // create. The offline path above gives its own "saved offline" feedback.
+  const isPending = createPageMutation.isPending && !createPageMutation.isPaused;
 
   // Exactly one writable space → create directly, no picker needed.
   if (writableSpaces.length === 1) {

apps/client/src/features/offline/clear-offline-cache.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so the spies they reference must
+// be declared via vi.hoisted (also hoisted). These are inspected by assertions.
+const h = vi.hoisted(() => ({
+  clear: vi.fn(),
+  del: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { clear: h.clear },
+}));
+vi.mock("idb-keyval", () => ({
+  del: h.del,
+}));
+
+import { clearOfflineCache } from "./clear-offline-cache";
+import { OFFLINE_CACHE_KEY } from "./query-persister";
+
+// jsdom does not provide indexedDB.databases() or Cache Storage, so the browser
+// globals are stubbed per-test. We restore them afterwards.
+const originalIndexedDB = (globalThis as any).indexedDB;
+const originalCaches = (globalThis as any).caches;
+
+beforeEach(() => {
+  h.clear.mockClear();
+  h.del.mockClear();
+});
+
+afterEach(() => {
+  (globalThis as any).indexedDB = originalIndexedDB;
+  (globalThis as any).caches = originalCaches;
+  vi.restoreAllMocks();
+});
+
+describe("clearOfflineCache", () => {
+  it("resolves without throwing when the browser globals are absent", async () => {
+    (globalThis as any).indexedDB = undefined;
+    delete (globalThis as any).caches;
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // The two store-agnostic steps still run.
+    expect(h.clear).toHaveBeenCalledTimes(1);
+    expect(h.del).toHaveBeenCalledWith(OFFLINE_CACHE_KEY);
+  });
+
+  it("deletes only `page.*` IndexedDB databases and only `api-get-cache` caches", async () => {
+    const deleteDatabase = vi.fn((_name: string) => {
+      const request: any = {};
+      // Resolve the deletion on the next microtask, like a real IDBRequest.
+      queueMicrotask(() => request.onsuccess && request.onsuccess());
+      return request;
+    });
+    (globalThis as any).indexedDB = {
+      databases: vi
+        .fn()
+        .mockResolvedValue([
+          { name: "page.aaa" },
+          { name: "page.bbb" },
+          { name: "keyval-store" },
+          { name: undefined },
+        ]),
+      deleteDatabase,
+    };
+
+    const cacheDelete = vi.fn().mockResolvedValue(true);
+    (globalThis as any).caches = {
+      keys: vi
+        .fn()
+        .mockResolvedValue([
+          "workbox-runtime-https://app/api-get-cache",
+          "other-cache",
+        ]),
+      delete: cacheDelete,
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // Only the two page.* databases are deleted.
+    expect(deleteDatabase).toHaveBeenCalledTimes(2);
+    expect(deleteDatabase).toHaveBeenCalledWith("page.aaa");
+    expect(deleteDatabase).toHaveBeenCalledWith("page.bbb");
+
+    // Only the api-get-cache entry is deleted.
+    expect(cacheDelete).toHaveBeenCalledTimes(1);
+    expect(cacheDelete).toHaveBeenCalledWith(
+      "workbox-runtime-https://app/api-get-cache",
+    );
+  });
+
+  it("never throws even if a step rejects (best-effort)", async () => {
+    h.del.mockRejectedValueOnce(new Error("idb boom"));
+    (globalThis as any).indexedDB = {
+      databases: vi.fn().mockRejectedValue(new Error("databases boom")),
+      deleteDatabase: vi.fn(),
+    };
+    (globalThis as any).caches = {
+      keys: vi.fn().mockRejectedValue(new Error("caches boom")),
+      delete: vi.fn(),
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+    expect(h.clear).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/clear-offline-cache.ts

@@ -0,0 +1,112 @@
+import { del } from "idb-keyval";
+
+import { queryClient } from "@/main.tsx";
+import {
+  OFFLINE_CACHE_KEY,
+  freezeOfflinePersistence,
+  unfreezeOfflinePersistence,
+} from "./query-persister";
+import { PAGE_YDOC_NAME_PREFIX } from "@/features/editor/page-ydoc-name";
+
+/**
+ * Best-effort purge of all of the current user's offline data from the browser.
+ *
+ * On logout the previous user's private data would otherwise linger locally and
+ * be readable by the next person on the device. This clears the three offline
+ * stores the app writes:
+ *   1. the in-memory + IndexedDB-persisted TanStack Query cache (idb-keyval key
+ *      `OFFLINE_CACHE_KEY`),
+ *   2. the Yjs page documents (IndexedDB databases named `page.<id>` created by
+ *      y-indexeddb in make-offline.ts), and
+ *   3. any legacy service worker `api-get-cache` Cache Storage entry. The
+ *      Workbox runtime no longer creates this cache (the GET /api NetworkFirst
+ *      rule was removed — offline reads come from the persisted RQ cache), so
+ *      this is now a defensive cleanup for caches left by older app versions.
+ *
+ * Fully best-effort: every step is isolated so a single failure neither blocks
+ * the remaining steps nor throws to the caller (logout must never be blocked on
+ * cache cleanup). Callers may ignore the resolved value.
+ *
+ * Limitations:
+ *   - Deleting the Yjs page databases relies on `indexedDB.databases()`, which
+ *     is unavailable in some browsers (notably Firefox). There we skip silently;
+ *     those `page.<id>` databases are then left in place.
+ *   - Cache Storage clearing only runs where `caches` exists (secure contexts /
+ *     service-worker-capable browsers).
+ */
+export async function clearOfflineCache(): Promise<void> {
+  // Freeze the throttled persister BEFORE touching the cache so the
+  // queryClient.clear() below cannot trigger a late re-write of the (still
+  // nearly-full) dehydrated snapshot after we del() the key — which would
+  // otherwise resurrect the previous user's persisted data in IndexedDB.
+  // Re-enabled in `finally` so the next (sign-in) session persists normally.
+  freezeOfflinePersistence();
+
+  try {
+    // 1a. Drop the in-memory query cache immediately.
+    try {
+      queryClient.clear();
+    } catch {
+      // best-effort: ignore in-memory cache reset failures
+    }
+
+    // 1b. Delete the persisted RQ cache from IndexedDB.
+    try {
+      await del(OFFLINE_CACHE_KEY);
+    } catch {
+      // best-effort: ignore persisted-cache deletion failures
+    }
+
+  // 2. Delete the Yjs page IndexedDB databases (`page.<id>`).
+  // `indexedDB.databases()` is not implemented everywhere (e.g. Firefox); when
+  // it is missing we cannot enumerate the page databases, so we skip silently.
+  try {
+    if (
+      typeof indexedDB !== "undefined" &&
+      typeof indexedDB.databases === "function"
+    ) {
+      const dbs = await indexedDB.databases();
+      for (const db of dbs) {
+        const name = db?.name;
+        if (typeof name !== "string" || !name.startsWith(PAGE_YDOC_NAME_PREFIX))
+          continue;
+        try {
+          // Fire-and-forget delete; await a thin wrapper so a slow delete does
+          // not race the page teardown, but never reject on it.
+          await new Promise<void>((resolve) => {
+            const request = indexedDB.deleteDatabase(name);
+            request.onsuccess = () => resolve();
+            request.onerror = () => resolve();
+            request.onblocked = () => resolve();
+          });
+        } catch {
+          // best-effort per database
+        }
+      }
+    }
+  } catch {
+    // best-effort: ignore enumeration/deletion failures
+  }
+
+  // 3. Clear any legacy service worker API cache. Current builds no longer
+  // create it, but an older client may have left an "api-get-cache" entry
+  // (Workbox may prefix the name), so match by substring rather than exact name.
+  try {
+    if ("caches" in window) {
+      const keys = await caches.keys();
+      await Promise.all(
+        keys
+          .filter((key) => key.includes("api-get-cache"))
+          .map((key) => caches.delete(key)),
+      );
+    }
+  } catch {
+    // best-effort: ignore Cache Storage failures
+  }
+  } finally {
+    // Re-enable persistence for the next session (sign-in continues running in
+    // the same tab; logout reloads via window.location.replace, so this is a
+    // harmless no-op there).
+    unfreezeOfflinePersistence();
+  }
+}

apps/client/src/features/offline/make-offline.test.ts

@@ -0,0 +1,373 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so any spy they reference must be
+// declared with vi.hoisted (which is hoisted as well). These shared spies are
+// inspected by the assertions below.
+const h = vi.hoisted(() => ({
+  ydocDestroy: vi.fn(),
+  idbDestroy: vi.fn(),
+  providerOn: vi.fn(),
+  providerOff: vi.fn(),
+  providerDestroy: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), prefetchQuery: vi.fn() },
+}));
+vi.mock("@/features/page/services/page-service", () => ({
+  getPageById: vi.fn(),
+  getPageBreadcrumbs: vi.fn(),
+  getSidebarPages: vi.fn(),
+  getAllSidebarPages: vi.fn(),
+}));
+vi.mock("@/features/space/services/space-service.ts", () => ({
+  getSpaceById: vi.fn(),
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  getPageComments: vi.fn(),
+}));
+
+// Use the `function` form (not an arrow) so Vitest binds the constructor return
+// value when the module under test calls `new Y.Doc()` etc.
+vi.mock("yjs", () => ({
+  Doc: vi.fn(function () {
+    return { destroy: h.ydocDestroy };
+  }),
+}));
+vi.mock("y-indexeddb", () => ({
+  IndexeddbPersistence: vi.fn(function () {
+    return { destroy: h.idbDestroy };
+  }),
+}));
+vi.mock("@hocuspocus/provider", () => ({
+  HocuspocusProvider: vi.fn(function () {
+    return { on: h.providerOn, off: h.providerOff, destroy: h.providerDestroy };
+  }),
+}));
+
+import {
+  warmInfiniteAll,
+  warmPageYdoc,
+  makePageAvailableOffline,
+} from "./make-offline";
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import { getPageComments } from "@/features/comment/services/comment-service";
+
+const setQueryData = (queryClient as any).setQueryData as ReturnType<
+  typeof vi.fn
+>;
+const prefetchQuery = (queryClient as any).prefetchQuery as ReturnType<
+  typeof vi.fn
+>;
+
+beforeEach(() => {
+  // Clear call history WITHOUT wiping the mock implementations the vi.mock
+  // factories installed (vi.clearAllMocks would drop the constructor return
+  // objects and break the provider/idb/yjs spies).
+  setQueryData.mockClear();
+  prefetchQuery.mockReset();
+  prefetchQuery.mockResolvedValue(undefined);
+  (getPageById as ReturnType<typeof vi.fn>).mockReset();
+  (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockReset();
+  (getSidebarPages as ReturnType<typeof vi.fn>).mockReset();
+  (getPageComments as ReturnType<typeof vi.fn>).mockReset();
+  h.ydocDestroy.mockClear();
+  h.idbDestroy.mockClear();
+  h.providerOn.mockClear();
+  h.providerOff.mockClear();
+  h.providerDestroy.mockClear();
+});
+
+describe("warmInfiniteAll", () => {
+  it("warms a single page and writes the InfiniteData cache shape", async () => {
+    const res = { items: [{ id: 1 }], meta: { nextCursor: null } };
+    const fetchPage = vi.fn().mockResolvedValue(res);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(1);
+    expect(fetchPage).toHaveBeenCalledWith(undefined);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["comments", "p1"], {
+      pages: [res],
+      pageParams: [undefined],
+    });
+  });
+
+  it("walks the cursor chain across multiple pages", async () => {
+    const r0 = { items: [], meta: { nextCursor: "c1" } };
+    const r1 = { items: [], meta: { nextCursor: "c2" } };
+    const r2 = { items: [], meta: { nextCursor: null } };
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValueOnce(r0)
+      .mockResolvedValueOnce(r1)
+      .mockResolvedValueOnce(r2);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(3);
+    expect(fetchPage.mock.calls.map((c) => c[0])).toEqual([
+      undefined,
+      "c1",
+      "c2",
+    ]);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toEqual([r0, r1, r2]);
+    expect(payload.pageParams).toEqual([undefined, "c1", "c2"]);
+  });
+
+  it("caps pagination at maxPages and reports the truncation (returns false)", async () => {
+    // Always returns a non-null cursor — the cap is the only thing that stops it.
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: "more" } });
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Hitting maxPages with a cursor still pending is a truncated warm: the
+    // (partial) cache is still written, but the result is reported as false.
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage, 2),
+    ).resolves.toBe(false);
+
+    expect(fetchPage).toHaveBeenCalledTimes(2);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toHaveLength(2);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("returns true on success", async () => {
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: null } });
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(true);
+  });
+
+  it("reports errors (returns false) and never writes the cache on failure", async () => {
+    const fetchPage = vi.fn().mockRejectedValue(new Error("network"));
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(false);
+    expect(setQueryData).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("makePageAvailableOffline", () => {
+  const okPage = {
+    id: "uuid-1",
+    slugId: "slug-1",
+    space: { slug: "space-slug" },
+  };
+
+  it("returns ok:true with no failures when every step succeeds", async () => {
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result).toEqual({ ok: true, failed: [] });
+  });
+
+  it("returns ok:false with the failed step label when a warm step fails", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    // Comments warm fails -> labeled "comments".
+    (getPageComments as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("network"),
+    );
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.failed).toContain("comments");
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  // Helper: the page-ids passed to the sidebar-children warm (its query key is
+  // ["sidebar-pages", { pageId, spaceId }]) — i.e. which nodes were prefetched.
+  const warmedSidebarIds = () =>
+    prefetchQuery.mock.calls
+      .map((c) => c[0])
+      .filter((opts: any) => opts?.queryKey?.[0] === "sidebar-pages")
+      .map((opts: any) => opts.queryKey[1]?.pageId);
+
+  it("warms the page + every ancestor's children once and skips the self-ancestor guard", async () => {
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    // Breadcrumbs include two real ancestors, the page's OWN id (must be skipped
+    // by the ancestorId === pageId guard so it is not warmed twice), and a
+    // malformed entry with no id (also skipped).
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([
+      { id: "anc-1" },
+      { id: "uuid-1" }, // === pageId -> guard
+      { id: "anc-2" },
+      {}, // no id -> skipped
+    ]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    const ids = warmedSidebarIds();
+    // The page's own children (warmSidebarChildren(pageId)) plus each real
+    // ancestor — exactly once each. The self-ancestor (uuid-1 in breadcrumbs) is
+    // NOT a second warm: uuid-1 appears once (from the page's own children call).
+    expect(ids).toEqual(["uuid-1", "anc-1", "anc-2"]);
+    expect(ids.filter((id: string) => id === "uuid-1")).toHaveLength(1);
+    expect(result).toEqual({ ok: true, failed: [] });
+  });
+
+  it("dedupes repeated tree failures into a single 'tree' label", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([
+      { id: "anc-1" },
+      { id: "anc-2" },
+    ]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    // Fail ONLY the sidebar-children prefetches (page-own + both ancestors = 3
+    // failures); the currentUser/space prefetches still resolve.
+    prefetchQuery.mockImplementation(async (opts: any) => {
+      if (opts?.queryKey?.[0] === "sidebar-pages") throw new Error("network");
+      return undefined;
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    // Three node warms failed but the contract collapses them to one "tree".
+    expect(result.ok).toBe(false);
+    expect(result.failed).toEqual(["tree"]);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("records 'breadcrumbs' (not 'tree') when the breadcrumbs lookup rejects", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    // Ancestor discovery fails -> the ancestor-walk is recorded as "breadcrumbs".
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("network"),
+    );
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    // The page's own children still warmed fine (prefetch resolves), so the only
+    // failure is the breadcrumbs lookup.
+    expect(result.ok).toBe(false);
+    expect(result.failed).toEqual(["breadcrumbs"]);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("warmPageYdoc", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves on synced, detaches the listener once, and tears everything down (settle-once)", async () => {
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Grab the synced handler the provider registered.
+    expect(h.providerOn).toHaveBeenCalledWith("synced", expect.any(Function));
+    const handler = h.providerOn.mock.calls.find(
+      (c) => c[0] === "synced",
+    )![1] as () => void;
+
+    handler();
+    await expect(promise).resolves.toBeUndefined();
+
+    // Listener detached and everything cleaned up.
+    expect(h.providerOff).toHaveBeenCalledWith("synced", expect.any(Function));
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+
+    // Firing the handler again must NOT re-run cleanup (settled guard).
+    handler();
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves and cleans up after the timeout when synced never fires", async () => {
+    vi.useFakeTimers();
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Do not fire "synced"; let the 8s safety timeout settle it.
+    await vi.advanceTimersByTimeAsync(8000);
+    await expect(promise).resolves.toBeUndefined();
+
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/make-offline.ts

@@ -0,0 +1,315 @@
+import * as Y from "yjs";
+import { IndexeddbPersistence } from "y-indexeddb";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import {
+  pageKeys,
+  sidebarPagesQueryOptions,
+} from "@/features/page/queries/page-query";
+import { spaceByIdQueryOptions } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { getPageComments } from "@/features/comment/services/comment-service";
+import { getMyInfo } from "@/features/user/services/user-service";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+import { IPage } from "@/features/page/types/page.types";
+import { IPagination } from "@/lib/types.ts";
+import { pageYdocName } from "@/features/editor/page-ydoc-name";
+
+/**
+ * Fully paginate an infinite query and write the @tanstack InfiniteData cache
+ * shape ({ pages, pageParams }) that the matching useInfiniteQuery hook reads.
+ *
+ * The default prefetchInfiniteQuery only warms the FIRST page, which leaves
+ * hooks that treat hasNextPage as still-loading (e.g. the comments panel)
+ * spinning forever offline, and silently truncates large lists. This walks the
+ * cursor chain until it runs out (or hits maxPages) so the whole list is cached.
+ *
+ * Best-effort: a failure does not throw (a partial/failed warm is still useful),
+ * but it is reported — the error is logged with context and `false` is returned
+ * so the caller can record the failed step instead of silently succeeding.
+ *
+ * Returns true ONLY if the cursor chain was fully exhausted and written. If the
+ * walk stops because it hit `maxPages` while a `nextCursor` is still pending,
+ * the cached list is truncated AND its last page keeps a nextCursor that cannot
+ * be re-fetched offline (hooks that gate on hasNextPage would spin forever), so
+ * that case is logged and returns false too — the caller records it as a failed
+ * warm instead of a silent truncated success. The (partial) cache is still
+ * written so what we did fetch is usable.
+ *
+ * Exported for unit testing of the cursor-walk / cache-write behavior.
+ */
+export async function warmInfiniteAll<T>(
+  queryKey: readonly unknown[],
+  fetchPage: (cursor: string | undefined) => Promise<IPagination<T>>,
+  maxPages = 50,
+): Promise<boolean> {
+  try {
+    const pages: IPagination<T>[] = [];
+    const pageParams: (string | undefined)[] = [];
+    let cursor: string | undefined = undefined;
+    let exhausted = false;
+
+    for (let i = 0; i < maxPages; i++) {
+      const res = await fetchPage(cursor);
+      pages.push(res);
+      pageParams.push(cursor);
+      cursor = res?.meta?.nextCursor ?? undefined;
+      if (!cursor) {
+        exhausted = true;
+        break;
+      }
+    }
+
+    queryClient.setQueryData(queryKey, { pages, pageParams });
+
+    if (!exhausted) {
+      // Stopped at maxPages with a cursor still pending: the list is truncated
+      // and the last cached page's nextCursor is un-fetchable offline. Report it
+      // as a failed warm rather than a silent truncated success.
+      console.error("warmInfiniteAll truncated at maxPages", {
+        queryKey,
+        maxPages,
+      });
+      return false;
+    }
+    return true;
+  } catch (error) {
+    console.error("warmInfiniteAll failed", { queryKey, error });
+    return false;
+  }
+}
+
+export interface MakePageAvailableOfflineParams {
+  pageId: string;
+  spaceId?: string;
+}
+
+/**
+ * Outcome of {@link makePageAvailableOffline}. `ok` is true only when every warm
+ * step succeeded; `failed` lists the labels of the steps that failed (a subset
+ * of: "currentUser", "page", "space", "tree", "breadcrumbs", "comments").
+ */
+export interface MakePageAvailableOfflineResult {
+  ok: boolean;
+  failed: string[];
+}
+
+/**
+ * Best-effort prefetch of a page's read queries so they get persisted to
+ * IndexedDB and become readable offline.
+ *
+ * Each step is isolated and this function does NOT throw — a partial warm is
+ * still useful. Instead of silently succeeding, every failed step is logged
+ * with a label and recorded in the returned result: `{ ok, failed }` where
+ * `ok` is true only if no step failed and `failed` lists the failed step
+ * labels. Only meaningful while online (the underlying requests must succeed).
+ */
+export async function makePageAvailableOffline({
+  pageId,
+  spaceId,
+}: MakePageAvailableOfflineParams): Promise<MakePageAvailableOfflineResult> {
+  const failed: string[] = [];
+
+  // Warm the current user (['currentUser']) so the auth-gated <Layout> can
+  // hydrate offline. UserProvider blanks the whole app while useCurrentUser has
+  // no data, and the offline POST /api/users/me fails as a network error, so
+  // without a persisted user a pinned page still white-screens after relaunch
+  // (#238). Persisted via OFFLINE_PERSIST_ROOTS; warmed here so the persisted
+  // cache actually has an entry to restore.
+  try {
+    await queryClient.prefetchQuery({
+      queryKey: userKeys.currentUser(),
+      queryFn: () => getMyInfo(),
+    });
+  } catch (error) {
+    console.error("makePageAvailableOffline: currentUser step failed", {
+      pageId,
+      error,
+    });
+    failed.push("currentUser");
+  }
+
+  // Fetch the page document ONCE and write it under BOTH cache keys, exactly
+  // like usePageQuery's onData effect. Every page consumer reads
+  // pageKeys.detail(slugId) (usePageQuery keys on the slugId for routed reads),
+  // so warming only the uuid key would leave the offline page blank.
+  let page: IPage | undefined;
+  try {
+    page = await getPageById({ pageId });
+    queryClient.setQueryData(pageKeys.detail(page.slugId), page);
+    queryClient.setQueryData(pageKeys.detail(page.id), page);
+  } catch (error) {
+    console.error("makePageAvailableOffline: page step failed", {
+      pageId,
+      error,
+    });
+    failed.push("page");
+  }
+
+  // Warm the space — page.tsx renders nothing until the space query resolves
+  // (useGetSpaceBySlugQuery). Awaited (not the fire-and-forget prefetchSpace) so
+  // the space is actually persisted before the caller fires its toast. Shares
+  // spaceByIdQueryOptions so the key/fn cannot drift from the hook.
+  try {
+    const spaceSlug = page?.space?.slug;
+    if (spaceSlug) {
+      await queryClient.prefetchQuery(spaceByIdQueryOptions(spaceSlug));
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: space step failed", {
+      pageId,
+      error,
+    });
+    failed.push("space");
+  }
+
+  // Warm the sidebar tree root so the WHOLE root level renders offline (matches
+  // useGetRootSidebarPagesQuery's pageKeys.rootSidebar(spaceId) infinite cache).
+  // Fully paginated so large root levels are not truncated at 100.
+  if (spaceId) {
+    const ok = await warmInfiniteAll(pageKeys.rootSidebar(spaceId), (cursor) =>
+      getSidebarPages({ spaceId, cursor, limit: 100 }),
+    );
+    if (!ok) failed.push("tree");
+  }
+
+  // Warm the children of the page and of every ancestor so the path to this
+  // page is expandable offline. We MIRROR fetchAllAncestorChildren exactly via
+  // sidebarPagesQueryOptions — same pageKeys.sidebar({ pageId, spaceId }) key,
+  // same getAllSidebarPages fn (which aggregates ALL children pages, so nothing
+  // is truncated at 100), same 30min staleTime — otherwise the warmed cache
+  // would never be read by the offline tree.
+  const warmSidebarChildren = async (id: string): Promise<boolean> => {
+    try {
+      // Keep EXACTLY { pageId, spaceId } so the key hashes identically to
+      // fetchAllAncestorChildren's (no parentPageId, no extra fields).
+      const params = { pageId: id, spaceId };
+      await queryClient.prefetchQuery(sidebarPagesQueryOptions(params));
+      return true;
+    } catch (error) {
+      console.error("makePageAvailableOffline: tree node step failed", {
+        pageId: id,
+        error,
+      });
+      return false;
+    }
+  };
+
+  // The page's own children.
+  if (!(await warmSidebarChildren(pageId))) failed.push("tree");
+
+  // Each ancestor's children. Use the breadcrumbs endpoint ONLY to discover the
+  // ancestor ids — we intentionally do NOT cache the breadcrumbs themselves
+  // (the UI derives the path from the tree).
+  try {
+    const ancestors = (await getPageBreadcrumbs(pageId)) as
+      | Array<{ id?: string }>
+      | undefined;
+    for (const ancestor of ancestors ?? []) {
+      const ancestorId = ancestor?.id;
+      if (!ancestorId || ancestorId === pageId) continue;
+      if (!(await warmSidebarChildren(ancestorId))) failed.push("tree");
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: breadcrumbs step failed", {
+      pageId,
+      error,
+    });
+    failed.push("breadcrumbs");
+  }
+
+  // Comments (matches useCommentsQuery's RQ_KEY(pageId) infinite cache).
+  // useCommentsQuery reports isLoading while hasNextPage is true, so warming
+  // only the first page leaves the offline comments panel spinning forever on
+  // pages with >100 comments. Fully paginate so the last cached page has no
+  // nextCursor and the panel settles offline.
+  const commentsOk = await warmInfiniteAll(RQ_KEY(pageId), (cursor) =>
+    getPageComments({ pageId, cursor, limit: 100 }),
+  );
+  if (!commentsOk) failed.push("comments");
+
+  // Dedupe — the tree label can be recorded once per failed node/ancestor.
+  const uniqueFailed = [...new Set(failed)];
+  return { ok: uniqueFailed.length === 0, failed: uniqueFailed };
+}
+
+/**
+ * Best-effort warm-up of the page's Yjs document into IndexedDB so the editor
+ * can open offline.
+ *
+ * Opens a local IndexeddbPersistence plus a transient HocuspocusProvider to
+ * pull the server state into IndexedDB, then tears both down once synced (or
+ * after a timeout). Entirely wrapped in try/catch — NEVER throws.
+ *
+ * Only meaningful when online at warm time; offline it is a no-op that resolves.
+ */
+export async function warmPageYdoc(
+  pageId: string,
+  collabUrl: string,
+  token?: string,
+): Promise<void> {
+  let ydoc: Y.Doc | null = null;
+  let local: IndexeddbPersistence | null = null;
+  let remote: HocuspocusProvider | null = null;
+
+  try {
+    const documentName = pageYdocName(pageId);
+    ydoc = new Y.Doc();
+    local = new IndexeddbPersistence(documentName, ydoc);
+    remote = new HocuspocusProvider({
+      url: collabUrl,
+      name: documentName,
+      document: ydoc,
+      token,
+    });
+
+    const provider = remote;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        // Clear the pending timeout and detach the listener so neither leaks
+        // after we resolve.
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        try {
+          provider.off("synced", finish);
+        } catch {
+          // best-effort
+        }
+        resolve();
+      };
+
+      // Resolve once the server state has synced into the local doc...
+      provider.on("synced", finish);
+      // ...or give up after a short timeout so we never hang.
+      timeoutId = setTimeout(finish, 8000);
+    });
+  } catch {
+    // best-effort
+  } finally {
+    try {
+      remote?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      local?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      ydoc?.destroy();
+    } catch {
+      // best-effort
+    }
+  }
+}

apps/client/src/features/offline/offline-fallback.tsx

@@ -0,0 +1,45 @@
+import { Button, Container, Group, Stack, Text, Title } from "@mantine/core";
+import { Helmet } from "react-helmet-async";
+import { useTranslation } from "react-i18next";
+import { getAppName } from "@/lib/config";
+
+/**
+ * Shown when the authenticated app shell cannot hydrate because the current
+ * user is unavailable AND there is no cached user to fall back on (e.g. an
+ * offline cold boot of a page that was never warmed for offline).
+ *
+ * Previously UserProvider returned a bare `<></>` in this situation, which
+ * white-screened the whole app on any offline reload (#237/#238). Rendering an
+ * explicit "you're offline" state with a retry instead gives the user a clear,
+ * non-blank fallback and a way to recover once the network returns.
+ */
+export function OfflineFallback() {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Helmet>
+        <title>
+          {t("You're offline")} - {getAppName()}
+        </title>
+      </Helmet>
+      <Container size="sm" py={80}>
+        <Stack align="center" gap="md">
+          <Title order={2} ta="center">
+            {t("You're offline")}
+          </Title>
+          <Text c="dimmed" size="lg" ta="center">
+            {t(
+              "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+            )}
+          </Text>
+          <Group justify="center">
+            <Button onClick={() => window.location.reload()} variant="subtle">
+              {t("Retry")}
+            </Button>
+          </Group>
+        </Stack>
+      </Container>
+    </>
+  );
+}

apps/client/src/features/offline/offline-mutations.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { QueryClient, hydrate, dehydrate } from "@tanstack/react-query";
+
+// Stub the network services so a replayed mutation hits a spy, not the network.
+const h = vi.hoisted(() => ({
+  createPage: vi.fn(),
+  movePage: vi.fn(),
+  createComment: vi.fn(),
+}));
+
+vi.mock("@/features/page/services/page-service", () => ({
+  createPage: h.createPage,
+  movePage: h.movePage,
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  createComment: h.createComment,
+}));
+// page-query pulls in the app entry (queryClient) and a lot of UI deps via its
+// cache helpers; we only need invalidateOnCreatePage to be a no-op here.
+vi.mock("@/features/page/queries/page-query", () => ({
+  invalidateOnCreatePage: vi.fn(),
+}));
+
+import {
+  offlineMutationKeys,
+  registerOfflineMutationDefaults,
+} from "./offline-mutations";
+
+beforeEach(() => {
+  h.createPage.mockReset().mockResolvedValue({ id: "new-page" });
+  h.movePage.mockReset().mockResolvedValue(undefined);
+  h.createComment.mockReset().mockResolvedValue({ id: "new-comment" });
+});
+
+describe("registerOfflineMutationDefaults", () => {
+  it("registers a default mutationFn for every offline mutation key", () => {
+    const qc = new QueryClient();
+    registerOfflineMutationDefaults(qc);
+
+    for (const key of Object.values(offlineMutationKeys)) {
+      const defaults = qc.getMutationDefaults(key);
+      expect(typeof defaults?.mutationFn).toBe("function");
+    }
+  });
+
+  // The headline durability guarantee: a paused mutation dehydrated into
+  // IndexedDB while offline must, after a reload, have a mutationFn so
+  // resumePausedMutations() actually replays the write on reconnect.
+  it("makes a rehydrated paused create replayable by resumePausedMutations", async () => {
+    // 1) Simulate the offline tab: a paused create mutation gets dehydrated.
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.createPage,
+    });
+    // Force the dehydrate-worthy paused state (offline = isPaused) with the
+    // payload the user submitted before losing connectivity.
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { spaceId: "s1", title: "Offline page" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+    expect(dehydrated.mutations).toHaveLength(1);
+    // The dehydrated mutation carries NO mutationFn (functions aren't
+    // serializable) — only its key + variables survive the reload.
+    expect((dehydrated.mutations[0] as any).mutationFn).toBeUndefined();
+
+    // 2) Simulate the fresh page after reload: register defaults, then hydrate
+    //    the persisted paused mutation back in.
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+
+    expect(freshClient.getMutationCache().getAll()).toHaveLength(1);
+
+    // 3) Reconnect: replay the paused mutations.
+    await freshClient.resumePausedMutations();
+
+    // The default mutationFn ran with the persisted variables — the write is
+    // NOT silently dropped.
+    expect(h.createPage).toHaveBeenCalledTimes(1);
+    expect(h.createPage).toHaveBeenCalledWith({
+      spaceId: "s1",
+      title: "Offline page",
+    });
+  });
+
+  it("makes a rehydrated paused move replayable by resumePausedMutations", async () => {
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.movePage,
+    });
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { pageId: "p1", parentPageId: null, position: "a" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+    await freshClient.resumePausedMutations();
+
+    expect(h.movePage).toHaveBeenCalledTimes(1);
+    expect(h.movePage).toHaveBeenCalledWith({
+      pageId: "p1",
+      parentPageId: null,
+      position: "a",
+    });
+  });
+});

apps/client/src/features/offline/offline-mutations.ts

@@ -0,0 +1,64 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createPage, movePage } from "@/features/page/services/page-service";
+import { createComment } from "@/features/comment/services/comment-service";
+import { invalidateOnCreatePage } from "@/features/page/queries/page-query";
+import type {
+  IMovePage,
+  IPage,
+  IPageInput,
+} from "@/features/page/types/page.types";
+import type { IComment } from "@/features/comment/types/comment.types";
+
+/**
+ * Stable mutation keys for the offline-relevant structural mutations.
+ *
+ * When the browser goes offline, React Query PAUSES these mutations and the
+ * PersistQueryClientProvider dehydrates the paused mutation into IndexedDB. On a
+ * reload-while-offline the mutation is restored, but a restored mutation has NO
+ * observer (no component is mounted) — so its replay relies entirely on the
+ * `mutationFn` registered via `setMutationDefaults` for its `mutationKey`.
+ * Without that, `resumePausedMutations()` finds a paused mutation with no
+ * `mutationFn` and silently no-ops, dropping the offline create/move/comment
+ * (#237/#238). Each offline mutation hook tags itself with the matching key so
+ * the rehydrated paused mutation can find its default `mutationFn` and replay.
+ */
+export const offlineMutationKeys = {
+  createPage: ["create-page"] as const,
+  movePage: ["move-page"] as const,
+  createComment: ["create-comment"] as const,
+};
+
+/**
+ * Register default `mutationFn`s (and the minimal success side effects safe to
+ * run without a mounted component) for the offline-relevant mutation keys, so a
+ * paused mutation restored from IndexedDB after an offline reload is replayable
+ * by `resumePausedMutations()` on reconnect.
+ *
+ * Called once when the QueryClient is created (see main.tsx). The hooks still
+ * carry their own inline `mutationFn`/`onSuccess` for the live in-session path;
+ * these defaults only take over for a rehydrated paused mutation that lost its
+ * observer across the reload.
+ */
+export function registerOfflineMutationDefaults(queryClient: QueryClient): void {
+  queryClient.setMutationDefaults(offlineMutationKeys.createPage, {
+    mutationFn: (data: Partial<IPageInput>) => createPage(data),
+    // Re-converge the sidebar tree / recent-changes from the authoritative
+    // create response. Pure cache writes — safe with no component mounted.
+    onSuccess: (data: IPage) => {
+      invalidateOnCreatePage(data);
+    },
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.movePage, {
+    // Replay the server-side move. The tree re-converges from the next online
+    // sidebar fetch / websocket `moveTreeNode` echo, so no cache write is
+    // needed here (the optimistic tree state was local-only anyway).
+    mutationFn: (data: IMovePage) => movePage(data),
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.createComment, {
+    // Replay the server-side comment create. The comments list refetches on the
+    // online reload, so the replay only needs to persist the write.
+    mutationFn: (data: Partial<IComment>) => createComment(data),
+  });
+}

apps/client/src/features/offline/offline-resume.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { QueryClient, onlineManager } from "@tanstack/react-query";
+import {
+  persistQueryClientRestore,
+  persistQueryClientSave,
+} from "@tanstack/react-query-persist-client";
+
+// Stub the network services so a replayed mutation hits a spy, not the network.
+const h = vi.hoisted(() => ({
+  createPage: vi.fn(),
+  movePage: vi.fn(),
+  createComment: vi.fn(),
+}));
+
+vi.mock("@/features/page/services/page-service", () => ({
+  createPage: h.createPage,
+  movePage: h.movePage,
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  createComment: h.createComment,
+}));
+vi.mock("@/features/page/queries/page-query", () => ({
+  invalidateOnCreatePage: vi.fn(),
+}));
+
+// In-memory idb-keyval so the REAL queryPersister round-trips through a fake
+// store (the actual persist -> reload -> restore path, not a hand-built blob).
+const store = new Map<string, string>();
+vi.mock("idb-keyval", () => ({
+  get: vi.fn((k: string) => Promise.resolve(store.get(k) ?? undefined)),
+  set: vi.fn((k: string, v: string) => {
+    store.set(k, v);
+    return Promise.resolve();
+  }),
+  del: vi.fn((k: string) => {
+    store.delete(k);
+    return Promise.resolve();
+  }),
+}));
+
+import { queryPersister } from "./query-persister";
+import {
+  offlineMutationKeys,
+  registerOfflineMutationDefaults,
+} from "./offline-mutations";
+
+const BUSTER = "test-buster";
+
+beforeEach(() => {
+  store.clear();
+  h.createPage.mockReset().mockResolvedValue({ id: "new-page" });
+  h.movePage.mockReset().mockResolvedValue(undefined);
+  h.createComment.mockReset().mockResolvedValue({ id: "new-comment" });
+});
+
+afterEach(() => {
+  // onlineManager is a global singleton; leave it in the default online state.
+  onlineManager.setOnline(true);
+});
+
+describe("offline paused-mutation resume across a reload", () => {
+  // This is the #120 silent-data-loss reproduction: a paused mutation persisted
+  // to IndexedDB while offline, then the tab RELOADS while still offline, must
+  // resume on reconnect. It exercises the real persister round-trip plus the two
+  // boot-time fixes the app wiring relies on:
+  //   (a) onlineManager seeded to the real offline state so the later reconnect
+  //       is a true offline->online transition that auto-resumes, and
+  //   (b) resumePausedMutations() called after the persister restores (what the
+  //       PersistQueryClientProvider onSuccess does), with mutation defaults
+  //       registered BEFORE the resume so the rehydrated mutation has a fn.
+  it("replays a rehydrated paused create on reconnect (mutationFn fires)", async () => {
+    // --- Tab 1, OFFLINE: user creates a page; it pauses and gets persisted. ---
+    onlineManager.setOnline(false); // (a) boot seeded offline
+
+    const client1 = new QueryClient();
+    registerOfflineMutationDefaults(client1);
+    const observer = client1.getMutationCache().build(client1, {
+      mutationKey: offlineMutationKeys.createPage,
+    });
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { spaceId: "s1", title: "Offline page" };
+
+    await persistQueryClientSave({
+      // Cast: persist-client-core and react-query may resolve to different
+      // @tanstack/query-core copies whose QueryClient brands are nominally
+      // incompatible (see query-persister.ts). Structurally identical at runtime.
+      queryClient: client1 as any,
+      persister: queryPersister,
+      buster: BUSTER,
+      dehydrateOptions: { shouldDehydrateMutation: () => true },
+    });
+    // The paused mutation is now in the persisted store.
+    expect(store.size).toBe(1);
+
+    // --- RELOAD while still offline: fresh client restores from the SAME
+    //     persister. Defaults are registered BEFORE restore/resume. ---
+    const client2 = new QueryClient();
+    registerOfflineMutationDefaults(client2);
+    client2.mount(); // subscribes to onlineManager (auto-resume on reconnect)
+
+    await persistQueryClientRestore({
+      queryClient: client2 as any,
+      persister: queryPersister,
+      buster: BUSTER,
+    });
+    expect(client2.getMutationCache().getAll()).toHaveLength(1);
+
+    // (b) onSuccess wiring resumes after restore — but we are still OFFLINE, so
+    // the mutation must stay paused and NOT fire yet.
+    await client2.resumePausedMutations();
+    expect(h.createPage).not.toHaveBeenCalled();
+
+    // --- RECONNECT: the offline->online transition auto-resumes the paused
+    //     mutation and its registered default mutationFn finally fires. ---
+    onlineManager.setOnline(true);
+
+    await vi.waitFor(() => {
+      expect(h.createPage).toHaveBeenCalledTimes(1);
+    });
+    expect(h.createPage).toHaveBeenCalledWith({
+      spaceId: "s1",
+      title: "Offline page",
+    });
+
+    client2.unmount();
+  });
+});

apps/client/src/features/offline/persist-roots.guard.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+// The query modules transitively import the app entry (@/main.tsx) for the
+// shared queryClient; mock it so importing the key factories has no side effects.
+import { vi } from "vitest";
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), getQueryData: vi.fn() },
+}));
+
+import { OFFLINE_PERSIST_ROOTS } from "./query-persister";
+import { pageKeys } from "@/features/page/queries/page-query";
+import { spaceKeys } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+
+/**
+ * Architecture guard (#13): every string persisted via OFFLINE_PERSIST_ROOTS
+ * must be the ROOT (queryKey[0]) of some exported query-key factory. If a
+ * factory's root is renamed without updating the persist registry — or vice
+ * versa — offline persist/warm silently breaks (persisted keys never match the
+ * live queries). This turns that silent regression into a red build.
+ *
+ * Each factory is invoked with throwaway args; only queryKey[0] is inspected.
+ */
+function rootOf(key: readonly unknown[]): string {
+  return String(key[0]);
+}
+
+const FACTORY_ROOTS = new Set<string>([
+  rootOf(pageKeys.detail("x")),
+  rootOf(pageKeys.sidebar({})),
+  rootOf(pageKeys.rootSidebar("x")),
+  rootOf(pageKeys.breadcrumbs("x")),
+  rootOf(pageKeys.recentChanges("x")),
+  rootOf(spaceKeys.detail("x")),
+  rootOf(spaceKeys.list()),
+  rootOf(RQ_KEY("x")),
+  rootOf(userKeys.currentUser()),
+]);
+
+describe("OFFLINE_PERSIST_ROOTS is backed by real query-key factories", () => {
+  it("maps every persisted root to an exported factory root", () => {
+    const unbacked = [...OFFLINE_PERSIST_ROOTS].filter(
+      (root) => !FACTORY_ROOTS.has(root),
+    );
+    expect(unbacked).toEqual([]);
+  });
+});