dsh-tiddlywiki 0.19.2 → 0.19.4

package/src/host/routes.ts

@@ -21,16 +21,16 @@
  */
 import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http'
 import { createHash, timingSafeEqual } from 'node:crypto'
-import { mkdir, writeFile, access, stat } from 'node:fs/promises'
+import { mkdir, writeFile, stat } from 'node:fs/promises'
 import { basename, extname, isAbsolute, join } from 'node:path'
 import { Readable } from 'node:stream'
 import type { TiddlyWebClient } from './tw-api.ts'
-import { TEXT_LIST_FILTER, isBinaryType, toIsoDateString } from './tw-api.ts'
+import { isBinaryType, toIsoDateString } from './tw-api.ts'
 import type { WikiServer } from './wiki.ts'
 import type { GitFace } from './git.ts'
 import { PATH_PREFIX, TW_PROXY_PREFIX, TW_PROXY_PATH } from './wiki.ts'
 import { writeSessionSummary, type SessionQueryFace } from './session-summary.ts'
-import { readBody, readBodyBuffer, json, rejectCrossSiteWrite, rejectNonRead, MAX_PROXY_BODY_BYTES, MAX_UPLOAD_BYTES } from './http.ts'
+import { readBody, readBodyBuffer, json, guardHandler, errorStatus, rejectCrossSiteWrite, rejectNonRead, MAX_PROXY_BODY_BYTES, MAX_UPLOAD_BYTES } from './http.ts'
 import { sanitizeTwFragment } from './sanitize.ts'
 import { flushPendingWrites } from './seeds.ts'
 import { WriteConflictError, assertNoConflict, buildWriteTiddler, flattenTiddlerFields } from './write-policy.ts'
@@ -247,6 +247,11 @@ function sanitizeUploadName(input: unknown): string {
     .replace(/^\.+/, '')
     .trim()
   if (name.length === 0 || name === '.' || name === '..') return ''
+  // Windows stores a trailing dot/space verbatim but never strips it, and
+  // `extname('evil.html.')` is just `.` — so the extension denylist was
+  // bypassable with `evil.html.` (v0.19.3). Canonicalize before the check.
+  name = name.replace(/[. ]+$/, '')
+  if (name.length === 0) return ''
   // `CON`, `NUL`, `COM1…` are not creatable on Windows — prefix instead of 500.
   if (WINDOWS_RESERVED_NAMES.test(name)) name = `_${name}`
   if (name.length > 160) name = name.slice(0, 160)
@@ -293,6 +298,28 @@ function snippetOf(text: string, max = 120): string {
   return flat.length <= max ? flat : `${flat.slice(0, max)}…`
 }
 
+/** Max `limit` accepted by the list routes (bounded payloads, v0.19.4). */
+const MAX_LIST_LIMIT = 200
+
+/** Max `limit` accepted by `/tags` — the tag list is a small wrapper around one
+ *  full listing, so a larger cap is fine while still bounding the payload. */
+const MAX_TAGS_LIMIT = 500
+
+/** Clamp a `limit` query param. `fallback` covers absent/unparsable values. */
+function readLimit(url: URL, fallback: number, max = MAX_LIST_LIMIT): number {
+  const raw = Number(url.searchParams.get('limit') ?? fallback)
+  return Number.isFinite(raw) ? Math.max(1, Math.min(Math.floor(raw), max)) : fallback
+}
+
+/** Optional `limit` query param: `undefined` when absent/unparsable (= no cap). */
+function readOptionalLimit(url: URL, max: number): number | undefined {
+  const raw = url.searchParams.get('limit')
+  if (raw === null || raw.trim().length === 0) return undefined
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed)) return undefined
+  return Math.max(1, Math.min(Math.floor(parsed), max))
+}
+
 /** Default note title: `YYYY-MM-DD HH:mm` (design doc D6). */
 function timestampTitle(date = new Date()): string {
   return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`
@@ -482,6 +509,13 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         json(res, { ok: false, error: 'session is required' }, 400)
         return
       }
+      // The id becomes part of a tiddler title (`$:/temp/dsh/session-summary/<id>`)
+      // and is echoed into the summary wikitext — keep it to a safe charset
+      // instead of trusting the request body (v0.19.3).
+      if (!/^[A-Za-z0-9._:-]{1,120}$/.test(session)) {
+        json(res, { ok: false, error: 'session id has an unsupported format' }, 400)
+        return
+      }
       const client = deps.getClient()
       if (client === undefined) {
         json(res, { ok: false, error: 'wiki service is not running' }, 503)
@@ -495,7 +529,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       const result = await writeSessionSummary(client, sq, session)
       json(res, { ok: true, ...result, twUrl: TW_PROXY_PATH })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -545,7 +579,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         .sort((a, b) => b.updatedAt - a.updatedAt)
       json(res, { ok: true, items })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -622,7 +656,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         permissions,
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -659,7 +693,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       }
       json(res, { ok: true, requestId, sessionId })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -709,6 +743,26 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         json(res, { ok: false, error: 'session service unavailable' }, 503)
         return
       }
+      // Validate the agent preset (工作模式) BEFORE any side effect (v0.19.3):
+      // the old code created the cwd directory + workspace first, so an unknown
+      // mode left an orphaned directory behind a 500 from `sc.create`.
+      if (mode !== undefined) {
+        const ap = deps.getAgentPresets()
+        if (ap === undefined) {
+          json(res, { ok: false, error: 'agent presets service unavailable' }, 503)
+          return
+        }
+        try {
+          const presets = await ap.list()
+          if (!presets.some((preset) => preset.id === mode)) {
+            json(res, { ok: false, error: `unknown agent preset "${mode}" (available: ${presets.map((preset) => preset.id).join(', ')})` }, 400)
+            return
+          }
+        } catch (err) {
+          json(res, { ok: false, error: `cannot validate agent preset: ${err instanceof Error ? err.message : String(err)}` }, 503)
+          return
+        }
+      }
       const ws = deps.getWorkspaceRegistry()
       if (cwd.length > 0) {
         // Only absolute paths, and never clobber an existing non-directory:
@@ -763,7 +817,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         permissionApplied,
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -812,7 +866,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         json(res, { ok: false, error: err.message, conflict: true }, 409)
         return
       }
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -843,14 +897,19 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         json(res, { ok: false, error: err.message, conflict: true }, 409)
         return
       }
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
   /** Distinct non-system tags for the quick-note tag autocomplete. The flat
    *  `tags` array feeds note-widget's chip autocomplete; the parallel `items`
    *  (tag → tiddler count) feeds the reply-stream `tiddlywiki_list_tags` tool
-   *  card, so both consumers share one endpoint. */
+   *  card, so both consumers share one endpoint.
+   *
+   *  Query params (v0.19.4): `limit` caps the payload (absent = every tag, so
+   *  the autocomplete keeps its full vocabulary), `sort=count` orders by usage
+   *  (default `alpha`). `tags`/`items` are always the same set in the same
+   *  order, plus `total`/`truncated` so a capped caller can say "N of M". */
   const handleTags = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (rejectNonRead(req, res)) return
     const client = deps.getClient()
@@ -859,23 +918,23 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       return
     }
     try {
-      // Text-bearing tiddlers only (server-side filter): tags that exist solely
-      // on binary attachments must not show up in the autocomplete / tool card.
-      const items = await client.list(TEXT_LIST_FILTER, false)
-      const counts = new Map<string, number>()
-      for (const item of items) {
-        for (const tag of item.tags ?? []) {
-          if (tag.length > 0 && !tag.startsWith('$:/')) counts.set(tag, (counts.get(tag) ?? 0) + 1)
-        }
-      }
-      const tags = [...counts.keys()].sort((a, b) => a.localeCompare(b, 'zh'))
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+      const limit = readOptionalLimit(url, MAX_TAGS_LIMIT)
+      const byCount = (url.searchParams.get('sort') ?? 'alpha') === 'count'
+      // Text-bearing tiddlers only (server-side filter) — the same counting the
+      // `tiddlywiki_list_tags` tool uses, so the card and the model agree.
+      const { total, tags: all } = await client.tagStats()
+      const ordered = byCount ? all : [...all].sort((a, b) => a.tag.localeCompare(b.tag, 'zh'))
+      const picked = limit === undefined ? ordered : ordered.slice(0, limit)
       json(res, {
         ok: true,
-        tags,
-        items: tags.map((tag) => ({ tag, count: counts.get(tag) ?? 0 })),
+        tags: picked.map((t) => t.tag),
+        items: picked,
+        total,
+        truncated: picked.length < total,
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -889,8 +948,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
     try {
       const url = new URL(req.url ?? '/', 'http://127.0.0.1')
-      const limitRaw = Number(url.searchParams.get('limit') ?? 15)
-      const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(Math.floor(limitRaw), 200)) : 15
+      const limit = readLimit(url, 15)
       const items = await client.recent(limit)
       json(res, {
         ok: true,
@@ -903,7 +961,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         })),
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -955,7 +1013,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         fields: flattenTiddlerFields(t),
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -979,8 +1037,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       const tag = url.searchParams.get('tag') ?? undefined
       const since = url.searchParams.get('since') ?? undefined
       const type = url.searchParams.get('type') ?? undefined
-      const limitRaw = Number(url.searchParams.get('limit') ?? 30)
-      const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(Math.floor(limitRaw), 200)) : 30
+      const limit = readLimit(url, 30)
       const { items, total } = await client.search(query, { tags, tag, since, type, limit })
       json(res, {
         ok: true,
@@ -999,7 +1056,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         })),
       })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -1017,7 +1074,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       }
       json(res, { ok: true, status: deps.server.status().status })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     }
   }
 
@@ -1087,7 +1144,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         lastSync: new Date().toISOString(),
       }, pushed.ok ? 200 : 502)
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
     } finally {
       endMutation()
     }
@@ -1126,16 +1183,31 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       }
       const filesDir = join(deps.getWikiPath(), 'files')
       await mkdir(filesDir, { recursive: true })
+      // Collision avoidance with an ATOMIC create (v0.19.3): the old code did
+      // `access(candidate)` then `writeFile(candidate)`, so (a) any access error
+      // (EACCES/EBUSY, not just ENOENT) was read as "name free" and (b) two
+      // concurrent uploads could both pick the same name and one silently
+      // replaced the other — contradicting the route's own "nothing is ever
+      // overwritten" contract. `flag: 'wx'` fails with EEXIST instead, and we
+      // walk the suffix chain on that error only. Bounded, so a pathological
+      // directory cannot spin this loop forever.
       const ext = extname(name)
       const stem = ext.length > 0 ? name.slice(0, -ext.length) : name
-      // Collision avoidance: files/some.txt, files/some-1.txt, … (bounded, so a
-      // pathological directory cannot spin this loop forever).
-      let candidate = name
-      for (let i = 1; i <= 10_000; i++) {
-        try { await access(join(filesDir, candidate)) } catch { break }
-        candidate = `${stem}-${i}${ext}`
+      let candidate = ''
+      let wrote = false
+      for (let i = 0; i <= 10_000 && !wrote; i++) {
+        candidate = i === 0 ? name : `${stem}-${i}${ext}`
+        try {
+          await writeFile(join(filesDir, candidate), buf, { flag: 'wx' })
+          wrote = true
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+        }
+      }
+      if (!wrote) {
+        json(res, { ok: false, error: '同名文件过多，请换一个文件名' }, 409)
+        return
       }
-      await writeFile(join(filesDir, candidate), buf)
       deps.autoCommit()
       invalidateGitStatus()
       json(res, {
@@ -1216,6 +1288,32 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
   }
 
+  /**
+   * Titles the browser-facing TW proxies must never serve (v0.19.3).
+   *
+   * `$:/plugins/dsh-tiddlywiki/config` holds the shared tokens and the git
+   * remote (possibly with a PAT); both `/tw` and `/api` forward ANY path to the
+   * loopback TW child, whose TiddlyWeb REST answers for `$:/…` titles — a
+   * route-level guard on `/get` was therefore trivially bypassed by
+   * `GET /dsh-tiddlywiki/tw/recipes/default/tiddlers/%24%3A%2Fplugins%2F…`
+   * (verified). The whole plugin namespace is blocked: nothing under it is
+   * needed by the TW frontend, and the host itself talks to TW directly.
+   */
+  const BLOCKED_PROXY_TITLE_PREFIXES = ['$:/plugins/dsh-tiddlywiki/']
+
+  /** True when a proxied pathname addresses a blocked (secret-bearing) tiddler. */
+  const isBlockedProxyPath = (pathname: string): boolean => {
+    const marker = '/tiddlers/'
+    const at = pathname.indexOf(marker)
+    if (at < 0) return false
+    const raw = pathname.slice(at + marker.length)
+    let title = raw
+    try {
+      title = decodeURIComponent(raw)
+    } catch { /* malformed encoding: check the raw form */ }
+    return BLOCKED_PROXY_TITLE_PREFIXES.some((prefix) => title.startsWith(prefix))
+  }
+
   /** Passthrough /dsh-tiddlywiki/api/<rest> → TW root /<rest>. */
   const handleApiProxy = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (rejectCrossSiteWrite(req, res)) return
@@ -1224,9 +1322,13 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       json(res, { ok: false, error: 'wiki service is not running' }, 503)
       return
     }
-    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
-    const rest = url.pathname.replace(/^\/dsh-tiddlywiki\/api/, '') || '/'
     try {
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+      const rest = url.pathname.replace(/^\/dsh-tiddlywiki\/api/, '') || '/'
+      if (isBlockedProxyPath(rest)) {
+        json(res, { ok: false, error: 'system tiddler not exposed' }, 403)
+        return
+      }
       // Share the /tw proxy's header forwarding so `authorization`/`cookie`
       // reach the TW child: in locked-down mode (auth.username configured) the
       // /api passthrough used to 401 on every call because it dropped them.
@@ -1266,12 +1368,22 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
     const url = new URL(req.url ?? '/', 'http://127.0.0.1')
     const rest = url.pathname.replace(new RegExp(`^${TW_PROXY_PREFIX}(?=/|$)`), '') || '/'
+    if (isBlockedProxyPath(rest)) {
+      json(res, { ok: false, error: 'system tiddler not exposed' }, 403)
+      return
+    }
     try {
       const method = (req.method ?? 'GET').toUpperCase()
       const headers = forwardHeaders(req.headers)
       // TW's CSRF gate requires X-Requested-With on writes; forward it through.
       if (method === 'PUT' || method === 'DELETE' || method === 'POST') headers['x-requested-with'] = 'TiddlyWiki'
-      const init: RequestInit = { method, headers, signal: AbortSignal.timeout(30_000) }
+      // Abort the upstream fetch when the CLIENT goes away: without this the TW
+      // child kept streaming a large attachment into the DSH process until the
+      // 30s timeout fired, long after the browser had cancelled (v0.19.3).
+      const abort = new AbortController()
+      const timeout = AbortSignal.timeout(30_000)
+      const signal = typeof AbortSignal.any === 'function' ? AbortSignal.any([abort.signal, timeout]) : timeout
+      const init: RequestInit = { method, headers, signal }
       if (method === 'PUT' || method === 'POST') init.body = await readBodyBuffer(req, MAX_UPLOAD_BYTES)
       const upstream = await fetch(`${deps.server.url}${rest}${url.search}`, init)
       const responseHeaders: Record<string, string> = {
@@ -1300,7 +1412,13 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       await new Promise<void>((resolveP, rejectP) => {
         body.on('error', rejectP)
         res.on('error', rejectP)
-        res.on('close', () => resolveP())
+        res.on('close', () => {
+          // Client hung up (aborted download / closed tab): stop pulling from the
+          // TW child instead of draining it until the timeout.
+          try { abort.abort() } catch { /* already aborted */ }
+          try { body.destroy() } catch { /* already closed */ }
+          resolveP()
+        })
         res.on('finish', () => resolveP())
         body.pipe(res)
       })
@@ -1313,25 +1431,29 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
   }
 
+  // Every handler goes through guardHandler (v0.19.3): a rejection — including a
+  // synchronous throw before the handler's own try, e.g. `new URL(req.url)` —
+  // becomes a 413/500 JSON response instead of an unhandled rejection that
+  // would exit the dsh web process with the request hanging.
   const disposers = [
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/status`, handler: (req, res) => { void handleStatus(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/note`, handler: (req, res) => { void handleNote(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/edit`, handler: (req, res) => { void handleEdit(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/tags`, handler: (req, res) => { void handleTags(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/recent`, handler: (req, res) => { void handleRecent(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/get`, handler: (req, res) => { void handleGet(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/search`, handler: (req, res) => { void handleSearch(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/render`, handler: (req, res) => { void handleRender(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/sync`, handler: (req, res) => { void handleSync(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/upload`, handler: (req, res) => { void handleUpload(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/session/summary`, handler: (req, res) => { void handleSessionSummary(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/sessions`, handler: (req, res) => { void handleAgentSessions(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/modes`, handler: (req, res) => { void handleAgentModes(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/send`, handler: (req, res) => { void handleAgentSend(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/create`, handler: (req, res) => { void handleAgentCreate(req, res) } }),
-    ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: (req, res) => { void handleApiProxy(req, res) } }),
-    ctx.webServer.register({ kind: 'prefix', path: `${TW_PROXY_PREFIX}`, handler: (req, res) => { void handleTwProxy(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/status`, handler: guardHandler(handleStatus) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/note`, handler: guardHandler(handleNote) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/edit`, handler: guardHandler(handleEdit) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/tags`, handler: guardHandler(handleTags) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/recent`, handler: guardHandler(handleRecent) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/get`, handler: guardHandler(handleGet) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/search`, handler: guardHandler(handleSearch) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/render`, handler: guardHandler(handleRender) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/sync`, handler: guardHandler(handleSync) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/upload`, handler: guardHandler(handleUpload) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/restart`, handler: guardHandler(handleRestart) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/session/summary`, handler: guardHandler(handleSessionSummary) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/sessions`, handler: guardHandler(handleAgentSessions) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/modes`, handler: guardHandler(handleAgentModes) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/send`, handler: guardHandler(handleAgentSend) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/agent/create`, handler: guardHandler(handleAgentCreate) }),
+    ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: guardHandler(handleApiProxy) }),
+    ctx.webServer.register({ kind: 'prefix', path: `${TW_PROXY_PREFIX}`, handler: guardHandler(handleTwProxy) }),
   ]
   return () => {
     for (const dispose of disposers) dispose()

package/src/host/session-summary.ts

@@ -204,7 +204,7 @@ function scanSnapshot(snap: SessionLogSnapshot | undefined, subagent: boolean, c
               title: args.newTitle,
               action: 'produced',
               time: t,
-              detail: old !== undefined ? `重命名自「${old}」` : undefined,
+              detail: old !== undefined && isPlausibleTitle(old) ? `重命名自「${old}」` : undefined,
               subagent,
             })
           }
@@ -243,12 +243,29 @@ function scanSnapshot(snap: SessionLogSnapshot | undefined, subagent: boolean, c
   }
 }
 
+/**
+ * 内联文本净化（v0.19.3）：汇总 wikitext 会被 TW 渲染成 HTML 片段再注入 DSH 页面，
+ * 而 TW 的解析器**原样透传 HTML**。凡是来自会话日志/请求体的字符串（sessionId、
+ * rename 的旧标题、检索词）都要先转义 HTML 元字符并去掉控制字符，别指望上层净化。
+ */
+export function escapeInline(text: string, max = 200): string {
+  return text
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/[[\]|]/g, ' ')
+    .slice(0, max)
+}
+
 /** 当前状态（存在？标签？修改时间？摘要）。 */
 interface TitleState {
   exists: boolean
   tags: string[]
   modified?: string
   snippet?: string
+  /** 查询失败（非 404）：状态未知，不能报「已删除/不存在」。 */
+  unknown?: boolean
 }
 
 /** 并发（8 路）查询每篇笔记的当前状态（404 → 不存在/已删除）。 */
@@ -266,7 +283,10 @@ async function enrichTitles(client: TiddlyWebClient, titles: string[]): Promise<
         snippet: flat.length > 48 ? `${flat.slice(0, 48)}…` : flat,
       }]
     } catch {
-      return [title, { exists: false, tags: [] }]
+      // 只有 404 才算「不存在」（tw-api 的 get 只在 404 返回 undefined）：
+      // 超时/5xx/服务重启中的查询失败必须报「状态未知」，否则一篇还在的笔记
+      // 会被标成「已删除」——正是项目里反复强调的「读取失败 ≠ 条目不存在」。
+      return [title, { exists: false, tags: [], unknown: true }]
     }
   }
   // Bounded batches: parallel within a batch, insertion order preserved across
@@ -305,7 +325,7 @@ function buildWikitext(
   lines.push('! 会话相关 wiki 汇总')
   lines.push('')
   lines.push(
-    `本页列出会话 \`${sessionId}\`（含其后代子代理）在本会话中产生 / 读取 / 检索过的知识库笔记。`,
+    `本页列出会话 \`${escapeInline(sessionId, 120)}\`（含其后代子代理）在本会话中产生 / 读取 / 检索过的知识库笔记。`,
   )
   lines.push('')
   const producedCount = producedTitles.length
@@ -332,16 +352,18 @@ function buildWikitext(
 
   const entryLine = (title: string, state: TitleState | undefined, entry: NoteEntry): string => {
     const bits: string[] = [`[[${title}]]`]
-    if (state === undefined || !state.exists) {
+    if (state !== undefined && state.unknown === true) {
+      bits.push('⚠️ 状态未知（查询失败）')
+    } else if (state === undefined || !state.exists) {
       bits.push('⚠️ 已删除/不存在')
     } else {
-      if (state.tags.length > 0) bits.push(`标签 ${state.tags.slice(0, 6).join('、')}${state.tags.length > 6 ? '…' : ''}`)
+      if (state.tags.length > 0) bits.push(`标签 ${state.tags.slice(0, 6).map((tag) => escapeInline(tag, 40)).join('、')}${state.tags.length > 6 ? '…' : ''}`)
       const mod = fmtModified(state.modified)
       if (mod.length > 0) bits.push(`修改 ${mod}`)
     }
     const t = fmtTime(entry.time)
     if (t.length > 0) bits.push(`会话内 ${t}`)
-    if (entry.detail !== undefined) bits.push(entry.detail)
+    if (entry.detail !== undefined) bits.push(escapeInline(entry.detail, 200))
     if (entry.subagent) bits.push('（子代理）')
     return `* ${bits.join(' · ')}`
   }
@@ -367,8 +389,8 @@ function buildWikitext(
     for (const r of collected.searches) {
       const bits: string[] = []
       if (r.kind === 'search') {
-        bits.push(`\`tiddlywiki_search\` query=「${r.query.length > 0 ? r.query : '(空)'}」`)
-        if (r.tags.length > 0) bits.push(`tags ${r.tags.join('、')}`)
+        bits.push(`\`tiddlywiki_search\` query=「${r.query.length > 0 ? escapeInline(r.query, 120) : '(空)'}」`)
+        if (r.tags.length > 0) bits.push(`tags ${r.tags.map((tag) => escapeInline(tag, 40)).join('、')}`)
       } else {
         bits.push('`tiddlywiki_recent`（最近修改）')
       }

package/src/host/tools.ts

@@ -345,21 +345,32 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
   // ── tiddlywiki_list_tags ─────────────────────────────────────────────────
   register(defineTool({
     name: 'tiddlywiki_list_tags',
-    description: '列出 TiddlyWiki 知识库现有的非系统标签及各自计数（按使用次数降序），方便决定给笔记打什么 tag。',
-    parameters: {},
+    description: '列出 TiddlyWiki 知识库现有的非系统标签及各自计数（按使用次数降序），方便决定给笔记打什么 tag。默认最多返回 200 个（`limit` 可调，上限 1000），被截断时结果里会带 total/truncated。',
+    parameters: {
+      limit: { type: 'integer', description: '可选：最多返回多少个标签（按使用次数降序），默认 200，上限 1000。' },
+    },
     output: {
       schema: { type: 'json' },
       render: (_args, value: TagListResult) => {
         if (value.tags.length === 0) return [{ type: 'text', text: '知识库暂无标签。' }]
-        const lines = [`现有标签（${value.tags.length} 个，按使用次数降序）：`]
+        const lines = [
+          value.truncated
+            ? `现有标签（共 ${value.total} 个，仅列出使用最多的 ${value.tags.length} 个，按使用次数降序）：`
+            : `现有标签（${value.total} 个，按使用次数降序）：`,
+        ]
         for (const t of value.tags) lines.push(`- ${t.tag} × ${t.count}`)
+        if (value.truncated) lines.push(`（其余 ${value.total - value.tags.length} 个较少使用的标签未列出；需要时可提高 limit 重试）`)
         return [{ type: 'text', text: lines.join('\n') }]
       },
     },
-    execute: async (): Promise<TagListResult> => {
+    execute: async (args: { limit?: number }): Promise<TagListResult> => {
       const wiki = requireWiki()
-      const tags = await wiki.listTags()
-      return { count: tags.length, tags }
+      const stats = await wiki.tagStats()
+      const limit = typeof args.limit === 'number' && Number.isFinite(args.limit)
+        ? Math.max(1, Math.min(Math.floor(args.limit), 1000))
+        : 200
+      const tags = stats.tags.slice(0, limit)
+      return { count: tags.length, total: stats.total, truncated: tags.length < stats.total, tags }
     },
   }))
 
@@ -1100,7 +1111,7 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
 interface SearchHit { title: string; tags: string[]; modified: string | null; snippet: string }
 interface SearchResult { query: string; tags: string[]; since: string | null; type: string | null; field: string | null; value: string | null; total: number; results: SearchHit[] }
 interface RecentResult { since: string | null; results: SearchHit[] }
-interface TagListResult { count: number; tags: Array<{ tag: string; count: number }> }
+interface TagListResult { count: number; total: number; truncated: boolean; tags: Array<{ tag: string; count: number }> }
 interface GetResult {
   notFound: boolean
   title: string

package/src/host/tw-api.ts

@@ -456,8 +456,19 @@ export class TiddlyWebClient {
   /**
    * Distinct non-system tags with their tiddler counts, most-used first then
    * zh-locale. One skinny listing request (no text payloads).
+   *
+   * `limit` (v0.19.4) caps the returned array after sorting; the caller loses
+   * the tail count unless it also asks `tagStats()`.
    */
-  async listTags(): Promise<Array<{ tag: string; count: number }>> {
+  async listTags(limit?: number): Promise<Array<{ tag: string; count: number }>> {
+    const tags = (await this.tagStats()).tags
+    if (limit === undefined) return tags
+    return tags.slice(0, Math.max(1, Math.min(Math.floor(limit), 1000)))
+  }
+
+  /** Full tag vocabulary + its size, so callers that cap can still report the
+   *  total ("showing 200 of N") — one listing request either way. */
+  async tagStats(): Promise<{ total: number; tags: Array<{ tag: string; count: number }> }> {
     // TEXT_LIST_FILTER (server-side, whitelist self-healed) so a tag that only
     // hangs off binary attachments is not counted as a knowledge-base tag
     // (v0.19.0 — the unfiltered skinny listing included image/book-page tags).
@@ -470,9 +481,10 @@ export class TiddlyWebClient {
         map.set(tag, (map.get(tag) ?? 0) + 1)
       }
     }
-    return [...map.entries()]
+    const tags = [...map.entries()]
       .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0], 'zh'))
       .map(([tag, count]) => ({ tag, count }))
+    return { total: tags.length, tags }
   }
 }
 

package/src/index.ts

@@ -57,7 +57,8 @@ export {
 export { openInTwEditor, registerRoutes } from './host/routes.ts'
 export { writeSessionSummary, SESSION_SUMMARY_PREFIX } from './host/routes.ts'
 export type { SessionQueryFace, SessionSummaryResult } from './host/routes.ts'
-export { registerAdminRoutes, resolveTwRoot, readWikiInfo, writeWikiInfo, ensurePlugin, bundledCatalog, ensureLanguage, normalizeThemes } from './host/admin.ts'
+export { registerAdminRoutes, resolveTwRoot, readWikiInfo, writeWikiInfo, ensurePlugin, bundledCatalog, ensureLanguage, normalizeThemes, MASKED_SECRET, maskConfigSecrets, stripMaskedSecrets } from './host/admin.ts'
+export { escapeInline } from './host/session-summary.ts'
 export { seedDocNote, DOC_NOTE_TITLE, DOC_NOTE_TAG, DOC_NOTE_TEXT } from './host/seed-notes.ts'
 export { seedStarterDocs, STARTER_DOCS_ITEMS, STARTER_DOCS_MARKER_TITLE, DSH_DOCS_TAG } from './host/seed-starter-docs.ts'
 export { seedSendToAgent, SEND_TO_AGENT_PLUGIN_TITLE, SEND_TO_AGENT_MARKER_TITLE, SEND_TO_AGENT_BUNDLE_TEXT } from './host/seed-send-to-agent.ts'