@ai-setting/roy-plugin-task-show 0.8.9 → 0.9.5

package/dist/tracing/decorator.js

@@ -0,0 +1,310 @@
+/**
+ * @fileoverview @TracedAs decorator stub for the roy-plugin-task-show v0.9.0.
+ *
+ * The plugin is a standalone npm package with `dependencies: {}`, so it
+ * cannot import the host's `roy-agent-core` tracing module statically.
+ * This module provides a minimal local `@TracedAs(name, options)`
+ * decorator that:
+ *
+ *   1. At module load, locates a writable `spans.db` (SQLite) using:
+ *        a. `process.env.ROY_TRACE_DB` if set
+ *        b. `~/.config/roy-agent/spans.db` (host default)
+ *      If none of these resolve to a writable file, the decorator
+ *      degrades to a no-op that just calls the wrapped function.
+ *
+ *   2. Wraps the target method so that every invocation writes a
+ *      single row to the `spans` table mirroring the host's
+ *      OpenTelemetry-compatible schema:
+ *
+ *         trace_id       (16 bytes hex)
+ *         span_id        (8 bytes hex, unique per row)
+ *         parent_span_id (always NULL for top-level spans)
+ *         name           (the span_name passed to @TracedAs)
+ *         kind           (always "internal")
+ *         status         ("ok" or "error")
+ *         start_time     (Unix epoch ms)
+ *         end_time       (Unix epoch ms)
+ *         duration_ms    (end - start)
+ *         created_at     (now)
+ *
+ *      If the DB write throws (locked, missing schema, permission
+ *      denied), the error is swallowed — the decorator must never
+ *      break the wrapped function. This is critical for tests,
+ *      CI, and any environment where the host spans.db is absent.
+ *
+ *   3. Generates a process-lifetime `trace_id` (16 bytes hex) at
+ *      module init. The host's spans.db queries by `name`, so a
+ *      shared trace_id is sufficient.
+ *
+ * The plugin runs in the Bun runtime (declared in `package.json
+ * engines.bun`), so we use `bun:sqlite` for the writer. If Bun is
+ * not available, the decorator degrades to no-op (tests don't
+ * need to write spans to pass).
+ *
+ * Why not import from `@ai-setting/roy-agent-core`? See the
+ * plan doc §3.1 / review op #20182: keeping the plugin zero-dep
+ * is a hard contract. A 90-line local stub is cheaper than
+ * carrying a runtime dep that may not exist in every install
+ * target (e.g. the plugin's own test suite).
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+let cachedDb = null;
+let resolvedSpansDbPath = null;
+/**
+ * Process-lifetime trace_id (16 random bytes hex). The host's
+ * trace_check queries spans by `name`, so a single trace_id per
+ * process is sufficient and matches the host's per-process model.
+ */
+const PROCESS_TRACE_ID = (() => {
+    const bytes = new Uint8Array(16);
+    const c = globalThis.crypto;
+    if (c && typeof c.getRandomValues === "function") {
+        c.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i += 1)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+})();
+/**
+ * Generate a unique 8-byte hex span_id per call.
+ */
+function newSpanId() {
+    const bytes = new Uint8Array(8);
+    const c = globalThis.crypto;
+    if (c && typeof c.getRandomValues === "function") {
+        c.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i += 1)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Locate the spans.db path. Returns null if no candidate exists
+ * or is writable. The lookup is cached after the first successful
+ * resolution.
+ */
+function resolveSpansDbPath() {
+    if (resolvedSpansDbPath !== null)
+        return resolvedSpansDbPath;
+    const candidates = [];
+    if (process.env.ROY_TRACE_DB)
+        candidates.push(process.env.ROY_TRACE_DB);
+    if (process.env.ROY_AGENT_DATA) {
+        candidates.push(join(process.env.ROY_AGENT_DATA, "spans.db"));
+    }
+    candidates.push(join(homedir(), ".config", "roy-agent", "spans.db"));
+    for (const c of candidates) {
+        if (c && existsSync(c)) {
+            resolvedSpansDbPath = c;
+            return c;
+        }
+    }
+    return null;
+}
+/**
+ * Lazily open the spans.db. Returns null if Bun is not available,
+ * the file cannot be opened, or the `spans` table does not exist.
+ */
+function getDb() {
+    if (cachedDb)
+        return cachedDb;
+    if (typeof globalThis.Bun === "undefined")
+        return null;
+    const path = resolveSpansDbPath();
+    if (!path)
+        return null;
+    try {
+        const { Database } = require("bun:sqlite");
+        const db = new Database(path);
+        try {
+            db.exec("SELECT 1 FROM span LIMIT 0");
+        }
+        catch {
+            db.close();
+            return null;
+        }
+        cachedDb = db;
+        return cachedDb;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a single span row. Never throws — decorator must not
+ * break the wrapped function.
+ */
+function writeSpan(row) {
+    const db = getDb();
+    if (!db)
+        return;
+    const spanId = newSpanId();
+    const durationMs = row.endTime - row.startTime;
+    try {
+        db.prepare(`INSERT INTO span (trace_id, span_id, parent_span_id, name, kind, status, start_time, end_time, attributes, time_created)
+       VALUES (?, ?, NULL, ?, 'internal', ?, ?, ?, ?, ?)`).run(PROCESS_TRACE_ID, spanId, row.name, row.status, row.startTime, row.endTime, JSON.stringify({ duration_ms: durationMs, ...(row.errorMessage ? { error: row.errorMessage } : {}) }), Date.now());
+    }
+    catch {
+        // Swallow — see file header.
+    }
+}
+/**
+ * @TracedAs(name, options) decorator factory.
+ *
+ * Usage:
+ *   @TracedAs("server.home.render", { recordParams: false, recordResult: false })
+ *   private async sendIndex(res: http.ServerResponse): Promise<void> { ... }
+ *
+ * If the spans.db is unreachable (no host, no env, schema mismatch),
+ * the decorator becomes a transparent passthrough — the wrapped
+ * function is called with its original `this` and arguments.
+ */
+export function TracedAs(name, _options) {
+    return function (_target, propertyKey, descriptor) {
+        const originalFn = descriptor.value;
+        if (!originalFn)
+            return descriptor;
+        const spanName = name || propertyKey;
+        const wrapped = function (...args) {
+            const startTime = Date.now();
+            let result;
+            try {
+                result = originalFn.apply(this, args);
+            }
+            catch (err) {
+                const endTime = Date.now();
+                writeSpan({
+                    name: spanName,
+                    status: "error",
+                    startTime,
+                    endTime,
+                    errorMessage: err instanceof Error ? err.message : String(err),
+                });
+                throw err;
+            }
+            if (result && typeof result.then === "function") {
+                return Promise.resolve(result).then((value) => {
+                    writeSpan({
+                        name: spanName,
+                        status: "ok",
+                        startTime,
+                        endTime: Date.now(),
+                    });
+                    return value;
+                }, (err) => {
+                    writeSpan({
+                        name: spanName,
+                        status: "error",
+                        startTime,
+                        endTime: Date.now(),
+                        errorMessage: err instanceof Error ? err.message : String(err),
+                    });
+                    throw err;
+                });
+            }
+            writeSpan({
+                name: spanName,
+                status: "ok",
+                startTime,
+                endTime: Date.now(),
+            });
+            return result;
+        };
+        wrapped.__tracedAsName = spanName;
+        return {
+            ...descriptor,
+            value: wrapped,
+        };
+    };
+}
+/**
+ * For tests: reset the module-level db cache so test fixtures
+ * can simulate a fresh host install. Not used in production.
+ */
+export function __resetTracedAsCacheForTests() {
+    if (cachedDb) {
+        try {
+            cachedDb.close();
+        }
+        catch {
+            // ignore
+        }
+    }
+    cachedDb = null;
+    resolvedSpansDbPath = null;
+}
+/**
+ * For tests: returns the resolved spans.db path or null. Allows
+ * tests to assert the decorator located the host DB.
+ */
+export function __getResolvedSpansDbPathForTests() {
+    return resolveSpansDbPath();
+}
+/**
+ * Ensure the parent dir of a candidate spans.db path exists
+ * (used by tests that point at a temp file). Best-effort.
+ */
+export function __ensureSpansDbDirForTests(path) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * `withTrace(name, fn)` — manual instrumentation helper for free
+ * functions (which TS decorators cannot decorate). Runs `fn` and
+ * records a span around the invocation. Mirrors the @TracedAs
+ * contract: never throws, no-ops when spans.db is unavailable.
+ *
+ * Used by `renderSessionForestPage` and `encodeMermaidLabelText`
+ * (top-level exports that cannot carry a class-method decorator).
+ */
+export async function withTrace(name, fn) {
+    const startTime = Date.now();
+    try {
+        const result = await fn();
+        writeSpan({ name, status: "ok", startTime, endTime: Date.now() });
+        return result;
+    }
+    catch (err) {
+        writeSpan({
+            name,
+            status: "error",
+            startTime,
+            endTime: Date.now(),
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Synchronous variant of `withTrace`. Used for top-level
+ * non-async exports.
+ */
+export function withTraceSync(name, fn) {
+    const startTime = Date.now();
+    try {
+        const result = fn();
+        writeSpan({ name, status: "ok", startTime, endTime: Date.now() });
+        return result;
+    }
+    catch (err) {
+        writeSpan({
+            name,
+            status: "error",
+            startTime,
+            endTime: Date.now(),
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+//# sourceMappingURL=decorator.js.map

package/dist/tracing/decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.js","sourceRoot":"","sources":["../../src/tracing/decorator.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -109,6 +109,29 @@ export interface TaskShowConfig {
     cliTimeoutMs?: number;
     /** v0.7.0+: Maximum stdout bytes accepted from the CLI. Default 1 MiB. */
     cliMaxBytes?: number;
+    /**
+     * v0.8.10+: Hard cap on the operations cache (one entry per task id).
+     * Older stale entries are dropped first when the cap is exceeded.
+     * Default 256.
+     */
+    operationsCacheMaxEntries?: number;
+    /**
+     * v0.8.10+: Hard cap on the tasks-tree cache (one entry per unique
+     * filter combination). Default 64.
+     */
+    tasksTreeCacheMaxEntries?: number;
+    /**
+     * v0.8.10+: Grace period for `tool:before.execute` entries that never
+     * receive a matching `tool:after.execute` (e.g. crashed tool, host
+     * bug). Entries older than this are swept on the next `before` hook
+     * call. Default 60_000 ms (1 minute). Set to 0 to disable.
+     */
+    pendingStartTtlMs?: number;
+    /**
+     * v0.8.10+: FIFO cap on the `finalizedTaskIds` dedup set so it cannot
+     * grow unbounded in long-lived hosts. Default 4096.
+     */
+    maxFinalizedTaskIds?: number;
 }
 /**
  * Default configuration. Keeping these as a single source of truth simplifies
@@ -117,6 +140,11 @@ export interface TaskShowConfig {
  * v0.5.0+: SSE replaces the previous `env.notify` mechanism. URL injection
  * is no longer supported — visualization reach-out is via the SSE event
  * stream broadcast by the local HTTP service.
+ *
+ * v0.8.10+: Heap-bounded defaults (Task #2537). `pendingStartTtlMs`,
+ * `operationsCacheMaxEntries`, `tasksTreeCacheMaxEntries`, and
+ * `maxFinalizedTaskIds` keep the plugin's in-memory Maps and Sets
+ * bounded so a long-lived CLI session cannot OOM at 4 GiB V8 heap.
  */
 export declare const DEFAULT_CONFIG: TaskShowConfig;
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -12,6 +12,11 @@
  * v0.5.0+: SSE replaces the previous `env.notify` mechanism. URL injection
  * is no longer supported — visualization reach-out is via the SSE event
  * stream broadcast by the local HTTP service.
+ *
+ * v0.8.10+: Heap-bounded defaults (Task #2537). `pendingStartTtlMs`,
+ * `operationsCacheMaxEntries`, `tasksTreeCacheMaxEntries`, and
+ * `maxFinalizedTaskIds` keep the plugin's in-memory Maps and Sets
+ * bounded so a long-lived CLI session cannot OOM at 4 GiB V8 heap.
  */
 export const DEFAULT_CONFIG = {
     port: 7788,
@@ -19,6 +24,10 @@ export const DEFAULT_CONFIG = {
     autoStart: true,
     maxStoredTasks: 50,
     publicDir: "public",
+    operationsCacheMaxEntries: 256,
+    tasksTreeCacheMaxEntries: 64,
+    pendingStartTtlMs: 60_000,
+    maxFinalizedTaskIds: 4096,
 };
 /**
  * Heartbeat interval (ms) — sent as a `:keep-alive` SSE comment so reverse

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+GH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,EAAE;IAClB,SAAS,EAAE,QAAQ;CACpB,CAAC;AAgFF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsIH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,EAAE;IAClB,SAAS,EAAE,QAAQ;IACnB,yBAAyB,EAAE,GAAG;IAC9B,wBAAwB,EAAE,EAAE;IAC5B,iBAAiB,EAAE,MAAM;IACzB,mBAAmB,EAAE,IAAI;CAC1B,CAAC;AAgFF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "0.8.9",
+  "version": "0.9.5",
   "description": "roy-agent plugin: visualize task solving process via tool call flow on a local web service",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,9 @@
     "start:demo": "bun run scripts/run-demo.ts",
     "verify": "bun run scripts/verify-service.ts",
     "verify:installed": "bun run scripts/verify-installed.ts",
-    "verify:published": "bun run scripts/verify-published.ts"
+    "verify:published": "bun run scripts/verify-published.ts",
+    "verify:heap": "bun run scripts/verify-heap-bounded.ts",
+    "stress:heap": "bun --expose-gc run scripts/stress-heap.ts"
   },
   "keywords": [
     "roy-agent",

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "0.8.9",
+  "version": "0.9.5",
   "type": "tool-plugin",
-  "description": "Visualize the tool call chain of a task on a local web service with real-time SSE updates. v0.5.0+: page refreshes stream over GET /api/events (Server-Sent Events). Subscribes to tool:before.execute, tool:after.execute, task:before.create, task:after.create, task:after.complete (preferred, 2026-07-10+), and task:after.update (legacy fallback). v0.6.11: Mermaid re-rendering is delegated to a self-contained controller (public/mermaid-renderer.js) that prevents the SVG→raw-source regression on async updates and surfaces recoverable .mermaid-error states. v0.6.12: Task lifecycle pipeline (operations timeline) server now emits data-task-id on the pipeline section; client preserves it on swap, so the page actually fetches /api/tasks/<id>/operations and renders the 7-op timeline (previously silently bailed). v0.7.0: Home page redesigned as a hierarchical task tree (driven by `roy-agent tasks tree --json`); new /api/tasks/tree endpoint with status / priority / type / root-id filters, expand/collapse UI, search, and live 30s polling. v0.8.0: per-task page Mermaid area now renders the hierarchical 'Task lifecycle + tools' view — each operation record owns a subgraph that nests its tool calls, with click callbacks (`window.__toolClick`) that scroll-into-view + highlight + auto-expand the matching row in the tool-call table below. Operation record descriptions (`description` + `processDescription`) are now always rendered inline (no `<details>` collapse) so the user sees the lifecycle state at a glance; a fallback `<details>` kicks in only for descriptions longer than 600 chars. v0.8.1: hotfix for two pre-existing bugs in v0.8.0 (browser smoke test surfaced after merge). (a) Mermaid click directives were emitted as `click t1 __toolClick(1)` (missing `call` keyword) — Mermaid 10's parser rejects this with `got 'PS'`. Fixed to `click t1 call __toolClick(1)` (the v10 grammar requires `call` to invoke a callback with arguments). (b) `buildMermaidSource` lived inside the `attachTaskPageTimeline` IIFE but was also called from a listener in the `attachToolClickBridge` IIFE — sibling IIFEs cannot see each other's locals, so the listener threw `ReferenceError: buildMermaidSource is not defined` and the Mermaid diagram silently failed to re-render after `task-show:lifecycle-ops-loaded`. Fixed by hoisting the function (and its three helpers) to script top-level so both IIFEs can see it via the script-wide closure; the function is also exposed on `window.buildMermaidSource` for tests + tooling. v0.8.3: tree-display fix (Task #2426). The home page used to look like a flat list of root tasks because `autoExpandFirstLevels(..., 2)` only opened the first 2 levels — 30/47 roots were leaf nodes and the remaining 17 collapsed to one level so grandchildren were never visible. Default expand depth is now 3 (root + child + grandchild + great-grandchild are visible on first paint), the summary line now shows per-depth count pills (root / child / grandchild / great-grandchild / level-N), each `tree-row` carries a `data-depth` attribute so CSS can paint coloured left rails per level, and the duplicated 'Live tool-call sessions (legacy view)' panel that made the page look like both a flat table AND a tree is now hidden behind `#legacy-sessions[hidden]` (kept for future debug-toggle restoration). v0.8.4: cli-eacces-compat hotfix (Task #2499). The CLI bundle `packages/cli/dist/bin/roy-agent.js` ships with `-rw-rw-r--` (no execute bit); the plugin now invokes `roy-agent` via `node <path>` from the resolved CLI path so EACCES is avoided even when the script lacks the executable bit. Resolution order: explicit `cfg.royAgentCliPath` override → `$ROY_AGENT_CLI` env → sibling-repo .js → monorepo .js → bare `roy-agent` (PATH). v0.8.5: CLI resolution priority fix. v0.8.4's resolution order preferred sibling-repo / monorepo `.js` files over the globally-installed `roy-agent` binary, which meant stale scripts in a sibling checkout could shadow a freshly-updated global install. v0.8.5 flips the order: explicit override → `$ROY_AGENT_CLI` env → **`roy-agent` on PATH** (looked up via `which`/`where`) → sibling-repo .js (dev) → monorepo .js (dev) → literal `roy-agent`. The lookup is exported as a free function `resolveRoyAgentCliPath()` (plus a `findRoyAgentOnPath()` helper) so the new priority order can be unit-tested in isolation. v0.8.7: home page redesigned around a process-scoped ancestor chain. The plugin now records every `task:after.create` payload into a `TaskSessionStore`, exposes it via a new `/api/tasks/ancestor-chain?leafId=N` endpoint, and renders the home page in a fixed top-to-bottom order: (1) ancestor chain — root → leaf, each link tagged with its parent_task_id and status, (2) Task lifecycle + tools — Mermaid diagram of the leaf's tool calls, (3) Task lifecycle pipeline — operations timeline placeholder, (4) a help/legend section that intentionally follows the pipeline so the pipeline is never the trailing element. When no leaf has been recorded yet, the home page falls back to the v0.8.x cross-host tasks tree so the page is never blank. v0.8.8: home page is now a task-list view (click-to-detail). The home page renders ONLY the ancestor chain; every chain item (root → leaf, leaf included) is a clickable link to /task/<id>. The Mermaid lifecycle diagram, the operations pipeline, the tool-calls table, and the raw JSON dump all live on the per-task detail page; the home page no longer loads mermaid.js or initialises the Mermaid renderer. The leaf is no longer special-cased as <strong> (it was a 'current view' marker in v0.8.7) — v0.8.8 promotes it to <a href='/task/<id>'> so the leaf is reachable via click, matching the rest of the chain. v0.8.9: home page ancestor chain rewritten as a real nested <ul>/<li> tree (24px indent per level via CSS, root/parent/→ text markers removed); detail page lifecycle pipeline section moved to immediately follow the Mermaid lifecycle diagram (was after the tool-call stats and tool calls table); extractJsonEnvelope hardened to a balanced-brace scanner so trailing CLI/plugin lifecycle log lines no longer break the JSON envelope and the /api/tasks/<id>/operations endpoint stops reporting cli_failed for normal CLI runs.",
+  "description": "Visualize the tool call chain of a task on a local web service with real-time SSE updates. v0.9.0: Session-scoped home page (only show tasks created after plugin load + their external ancestors), with per-row 「显示全部栏位」 toggle and lazy-loaded operations timeline; per-task Mermaid labels now correctly render CJK / mixed-Latin / emoji text (encoded as \\uXXXX before emission, decoded by the browser); detail page layout reordered to lifecycle → pipeline → stats → toolcalls → rawjson. v0.5.0+: page refreshes stream over GET /api/events (Server-Sent Events). Subscribes to tool:before.execute, tool:after.execute, task:before.create, task:after.create, task:after.complete (preferred, 2026-07-10+), and task:after.update (legacy fallback). v0.6.11: Mermaid re-rendering is delegated to a self-contained controller (public/mermaid-renderer.js) that prevents the SVG→raw-source regression on async updates and surfaces recoverable .mermaid-error states. v0.6.12: Task lifecycle pipeline (operations timeline) server now emits data-task-id on the pipeline section; client preserves it on swap, so the page actually fetches /api/tasks/<id>/operations and renders the 7-op timeline (previously silently bailed). v0.7.0: Home page redesigned as a hierarchical task tree (driven by `roy-agent tasks tree --json`); new /api/tasks/tree endpoint with status / priority / type / root-id filters, expand/collapse UI, search, and live 30s polling. v0.8.0: per-task page Mermaid area now renders the hierarchical 'Task lifecycle + tools' view — each operation record owns a subgraph that nests its tool calls, with click callbacks (`window.__toolClick`) that scroll-into-view + highlight + auto-expand the matching row in the tool-call table below. Operation record descriptions (`description` + `processDescription`) are now always rendered inline (no `<details>` collapse) so the user sees the lifecycle state at a glance; a fallback `<details>` kicks in only for descriptions longer than 600 chars. v0.8.1: hotfix for two pre-existing bugs in v0.8.0 (browser smoke test surfaced after merge). (a) Mermaid click directives were emitted as `click t1 __toolClick(1)` (missing `call` keyword) — Mermaid 10's parser rejects this with `got 'PS'`. Fixed to `click t1 call __toolClick(1)` (the v10 grammar requires `call` to invoke a callback with arguments). (b) `buildMermaidSource` lived inside the `attachTaskPageTimeline` IIFE but was also called from a listener in the `attachToolClickBridge` IIFE — sibling IIFEs cannot see each other's locals, so the listener threw `ReferenceError: buildMermaidSource is not defined` and the Mermaid diagram silently failed to re-render after `task-show:lifecycle-ops-loaded`. Fixed by hoisting the function (and its three helpers) to script top-level so both IIFEs can see it via the script-wide closure; the function is also exposed on `window.buildMermaidSource` for tests + tooling. v0.8.3: tree-display fix (Task #2426). The home page used to look like a flat list of root tasks because `autoExpandFirstLevels(..., 2)` only opened the first 2 levels — 30/47 roots were leaf nodes and the remaining 17 collapsed to one level so grandchildren were never visible. Default expand depth is now 3 (root + child + grandchild + great-grandchild are visible on first paint), the summary line now shows per-depth count pills (root / child / grandchild / great-grandchild / level-N), each `tree-row` carries a `data-depth` attribute so CSS can paint coloured left rails per level, and the duplicated 'Live tool-call sessions (legacy view)' panel that made the page look like both a flat table AND a tree is now hidden behind `#legacy-sessions[hidden]` (kept for future debug-toggle restoration). v0.8.10: bug-fix release (Task #2537 + Task #2534). (a) Heap-bounded plugin caches: OperationsCache and TasksTreeCache now enforce a hard maxEntries cap (default 256 / 64). Oldest stale entries are evicted before inserting a new one, so long-lived roy-agent sessions (BackgroundTaskManager + MemorySessionStore) no longer leak Map entries through the plugin's per-task caches — see Task #2537 for the heap-unbounded-state RED→GREEN repro. (b) Mermaid CJK font-family: server.ts renderTaskPage now configures mermaid.initialize({ themeVariables: { fontFamily: '\"PingFang SC\", \"Microsoft YaHei\", \"Noto Sans CJK SC\", \"Source Han Sans CN\", \"WenQuanYi Micro Hei\", sans-serif' } }) so Chinese node labels render correctly in browsers that have at least one of those fonts installed (see Task #2534).",
   "main": "dist/index.js",
   "hooks": [
     {

package/public/app.js

@@ -247,7 +247,7 @@ function buildMermaidSource(session, operations) {
 // Top-level helpers used by buildMermaidSource. Kept here so both
 // IIFEs can call them via the script-wide closure.
 function toolLabel(t) {
-    const head = escapeMermaid(`${t.sequence}. ${t.toolName}${t.hasAttachment ? " \ud83d\udcce" : ""}`);
+    const head = encodeMermaidLabelTextClient(`${t.sequence}. ${t.toolName}${t.hasAttachment ? " \ud83d\udcce" : ""}`);
     return `${head}<br/><small>${t.success ? "ok" : "FAIL"} \u00b7 ${t.durationMs}ms</small>`;
 }
 
@@ -263,6 +263,35 @@ function escapeMermaid(s) {
     return String(s).replace(/[<>"#]/g, "").replace(/[^A-Za-z0-9_.\-]/g, "_");
 }
 
+/**
+ * v0.9.0 client-side mirror of `encodeMermaidLabelText` from
+ * `src/task-detail-mermaid.ts`. MUST stay byte-for-byte identical
+ * to the server implementation; the parity test in
+ * `test/mermaid-cjk-encoding-client.test.ts` enforces this.
+ */
+function encodeMermaidLabelTextClient(s) {
+    var cleaned = String(s == null ? "" : s)
+        .replace(/["\r\n\t]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    var out = "";
+    for (var i = 0; i < cleaned.length; i++) {
+        var ch = cleaned[i];
+        var code = ch.codePointAt ? ch.codePointAt(0) : (ch.charCodeAt ? ch.charCodeAt(0) : undefined);
+        if (code === undefined) continue;
+        if (code < 0x80) { out += ch; continue; }
+        if (code <= 0xFFFF) {
+            out += "\\u" + code.toString(16).padStart(4, "0");
+        } else {
+            var v = code - 0x10000;
+            var hi = 0xD800 + (v >> 10);
+            var lo = 0xDC00 + (v & 0x3FF);
+            out += "\\u" + hi.toString(16).padStart(4, "0") + "\\u" + lo.toString(16).padStart(4, "0");
+        }
+    }
+    return out;
+}
+
 // ---------------------------------------------------------------------------
 // v0.8.2 (fix/mermaid-readable-labels) — human-readable Mermaid
 // phase labels. This block mirrors `src/task-detail-mermaid.ts` so
@@ -481,6 +510,21 @@ function getPhaseLabel(op) {
 if (typeof window !== "undefined") {
     window.buildMermaidSource = buildMermaidSource;
     window.getPhaseLabel = getPhaseLabel;
+    window.encodeMermaidLabelTextClient = encodeMermaidLabelTextClient;
+    window.toolLabelClient = function (t) { return toolLabel(t); };
+    // v0.9.0 invariant: when invoked with a server encoder, the client
+    // encoder must produce byte-for-byte identical output. Drift is
+    // surfaced as a hard throw so SSR HTML and dynamic re-render stay
+    // in sync.
+    window.__cjkParityCheck = function (serverEncode) {
+        var cases = ["Phase 3: Plan", "\u4efb\u52a1\u7ba1\u7406", "Phase 1: \u4efb\u52a1\u7ba1\u7406"];
+        for (var i = 0; i < cases.length; i++) {
+            if (encodeMermaidLabelTextClient(cases[i]) !== serverEncode(cases[i])) {
+                throw new Error("CJK parity broken: " + JSON.stringify(cases[i]));
+            }
+        }
+        return true;
+    };
 }
 /**
  * v0.8.0+ Mermaid ↔ tool-table bridge.

package/public/index.html

@@ -80,6 +80,9 @@
     </section>
 
     <script src="/static/app.js"></script>
+    <script src="/static/mermaid-renderer.js"></script>
     <script src="/static/tasks-tree.js"></script>
+    <script src="/static/task-operations.js"></script>
+    <script src="/static/session-forest.js"></script>
   </body>
 </html>

package/public/session-forest.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Client-side controller for the v0.9.0 session-scoped forest.
+ *
+ *  - Wires each `[data-toggle="<id>"]` button to its matching
+ *    `details[data-details="<id>"]` block (the "显示全部栏位" toggle).
+ *  - Lazy-loads `/api/tasks/<id>/operations` into each
+ *    `ul.session-operations[data-task-operations="<id>"]` placeholder,
+ *    reusing `renderPipelineHtml` from `task-operations.js`.
+ *
+ *  Vanilla JS, no framework dependency. Bootstraps on DOMContentLoaded.
+ */
+(function () {
+  "use strict";
+
+  function esc(s) {
+    return String(s == null ? "" : s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  function wireToggle(button) {
+    var id = button.getAttribute("data-toggle");
+    if (!id) return;
+    var target = document.querySelector('[data-details="' + cssEscape(id) + '"]');
+    if (!target) return;
+    button.addEventListener("click", function () {
+      target.open = !target.open;
+    });
+  }
+
+  function cssEscape(s) {
+    if (window.CSS && typeof window.CSS.escape === "function") {
+      return window.CSS.escape(s);
+    }
+    return String(s).replace(/[^a-zA-Z0-9_-]/g, function (c) {
+      return "\\" + c;
+    });
+  }
+
+  function loadOperationsFor(placeholder) {
+    var id = placeholder.getAttribute("data-task-operations");
+    if (!id) return;
+    placeholder.innerHTML = '<p class="empty">Loading operations…</p>';
+    fetch("/api/tasks/" + encodeURIComponent(id) + "/operations")
+      .then(function (r) {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.json();
+      })
+      .then(function (envelope) {
+        if (typeof window.renderPipelineHtml === "function") {
+          placeholder.innerHTML = window.renderPipelineHtml(envelope.operations || [], envelope.stale, Number(id));
+        } else {
+          // Fallback: render a minimal list
+          var html = "<ol class=\"ops-fallback\">";
+          (envelope.operations || []).forEach(function (op) {
+            html += "<li>" + esc(op.title || op.milestoneType || "op") + "</li>";
+          });
+          html += "</ol>";
+          placeholder.innerHTML = html;
+        }
+      })
+      .catch(function (err) {
+        placeholder.innerHTML = '<p class="empty error">Failed to load operations: ' + esc(err && err.message || err) + '</p>';
+      });
+  }
+
+  function boot() {
+    var section = document.querySelector('[data-session-forest="1"]');
+    if (!section) return;
+    var buttons = section.querySelectorAll('[data-toggle]');
+    for (var i = 0; i < buttons.length; i++) wireToggle(buttons[i]);
+    var placeholders = section.querySelectorAll('[data-task-operations]');
+    for (var j = 0; j < placeholders.length; j++) loadOperationsFor(placeholders[j]);
+  }
+
+  if (typeof window !== "undefined") {
+    window.__sessionForestBoot = boot;
+  }
+
+  if (typeof document !== "undefined") {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", boot);
+    } else {
+      boot();
+    }
+  } else if (typeof window !== "undefined" && window.document) {
+    // jsdom eval fallback: window may exist but document may not be in scope
+    if (window.document.readyState === "loading") {
+      window.document.addEventListener("DOMContentLoaded", boot);
+    } else {
+      boot();
+    }
+  }
+})();