march-cli 0.1.37 → 0.1.39

package/src/cli/session/pi-session-switch-command.mjs

@@ -1,4 +1,4 @@
-import { loadPiSessionSidecar } from "../../session/sidecar.mjs";
+import { loadMarchSessionStateForPiBackend } from "../../session/state/march-session-state.mjs";
 
 export async function resumePiSessionById(id, { runner, sessions, projectMarchDir }) {
   if (!runner.canSwitchPiSession?.()) {
@@ -12,21 +12,21 @@ export async function resumePiSessionById(id, { runner, sessions, projectMarchDi
   }
 
   const session = matches[0];
-  let sidecar;
+  let stored;
   try {
-    sidecar = loadPiSessionSidecar({ projectMarchDir, sessionRef: session.path });
+    stored = loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId: session.id, sessionRef: session.path });
   } catch (err) {
-    return [`Error: pi session sidecar is invalid for ${session.id}: ${err.message}`];
+    return [`Error: March session state is invalid for ${session.id}: ${err.message}`];
   }
-  if (!sidecar) {
-    return [`Error: pi session sidecar not found for ${session.id}; refusing partial resume`];
+  if (!stored) {
+    return [`Error: March session state not found for ${session.id}; refusing partial resume`];
   }
-  if (sidecar.state.cwd && sidecar.state.cwd !== runner.engine.cwd) {
-    return [`Error: pi session sidecar cwd mismatch for ${session.id}: ${sidecar.state.cwd}`];
+  if (stored.state.cwd && stored.state.cwd !== runner.engine.cwd) {
+    return [`Error: March session state cwd mismatch for ${session.id}: ${stored.state.cwd}`];
   }
 
   let result;
-  const restoreState = toContextSessionState(sidecar.state);
+  const restoreState = toContextSessionState(stored.state);
   try {
     result = await runner.switchPiSession(session.path, restoreState);
   } catch (err) {
@@ -36,6 +36,6 @@ export async function resumePiSessionById(id, { runner, sessions, projectMarchDi
   return [`Resumed pi session: ${session.id}`];
 }
 
-function toContextSessionState(sidecarState) {
-  return { ...sidecarState };
+function toContextSessionState(sessionState) {
+  return { ...sessionState };
 }

package/src/cli/session/session-list-command.mjs

@@ -23,7 +23,7 @@ export function formatPiSessionList(sessions) {
     const savedAt = session.savedAt?.slice(0, 19) ?? "?";
     return `  ${session.id}  ${session.turnCount}m  ${savedAt}  ${label}`;
   });
-  lines.push("(pi JSONL session files; use /session to restore a previous session)");
+  lines.push("(pi JSONL session files)");
   return lines;
 }
 

package/src/cli/session/session-source-command.mjs

@@ -1,13 +1,7 @@
-import { listPiSessionInfos } from "../../session/pi-manager.mjs";
-import { loadPiSessionTranscriptTurns } from "../../session/transcript.mjs";
-import { resumePiSessionById } from "./pi-session-switch-command.mjs";
-
 export async function handleSessionSourceCommand(trimmed, {
   ui,
   runner,
   sessionState,
-  sessionsRoot,
-  projectMarchDir,
 }) {
   if (trimmed === "/save") {
     const stats = runner.getSessionStats?.();
@@ -15,75 +9,5 @@ export async function handleSessionSourceCommand(trimmed, {
     return { handled: true };
   }
 
-  if (trimmed === "/session") {
-    const sessions = await listPiSessionInfos({
-      cwd: runner.engine.cwd,
-      projectMarchDir,
-    });
-    if (sessions.length === 0) {
-      ui.writeln("No previous sessions.");
-      return { handled: true };
-    }
-    if (!ui.selectList) {
-      ui.writeln("Session selector is only available in TUI.");
-      return { handled: true };
-    }
-    const currentSessionId = runner.getSessionStats?.().sessionId ?? null;
-    const item = await ui.selectList({
-      items: buildSessionSelectItems(sessions, currentSessionId),
-      selectedIndex: Math.max(0, sessions.findIndex((session) => session.id === currentSessionId)),
-      width: 72,
-      suppressInitialConfirm: true,
-      searchable: true,
-      getSearchText: sessionSelectSearchText,
-    });
-    if (!item) {
-      ui.writeln("Session unchanged.");
-      return { handled: true };
-    }
-    const lines = await resumePiSessionById(item.session.id, { runner, sessions, projectMarchDir });
-    if (isResumeSuccess(lines)) restoreTranscriptFromSession(item.session, ui);
-    for (const line of lines) {
-      ui.writeln(line);
-    }
-    return { handled: true };
-  }
-
   return { handled: false };
 }
-
-export function buildSessionSelectItems(sessions, currentSessionId = null) {
-  return sessions.map((session) => {
-    const label = session.name || session.firstMessage || "(no messages)";
-    const savedAt = formatSessionSelectTime(session.savedAt);
-    return {
-      value: session.id,
-      label,
-      description: savedAt,
-      session,
-    };
-  });
-}
-
-function sessionSelectSearchText(item) {
-  const session = item?.session;
-  return `${item?.label ?? ""} ${item?.description ?? ""} ${session?.id ?? ""} ${session?.name ?? ""} ${session?.firstMessage ?? ""} ${session?.turnCount ?? ""}`;
-}
-
-function restoreTranscriptFromSession(session, ui) {
-  if (typeof ui.restoreTranscript !== "function") return;
-  try {
-    ui.restoreTranscript(loadPiSessionTranscriptTurns(session.path));
-  } catch (err) {
-    ui.writeln(`Warning: failed to restore session transcript: ${err.message}`);
-  }
-}
-
-function isResumeSuccess(lines) {
-  return Array.isArray(lines) && lines.some((line) => String(line).startsWith("Resumed pi session:"));
-}
-
-function formatSessionSelectTime(value) {
-  if (!value) return "?";
-  return String(value).slice(0, 16).replace("T", " ");
-}

package/src/cli/startup/app-runtime.mjs

@@ -19,6 +19,13 @@ import { defaultProfilePaths, ensureProfileFiles } from "../../context/profiles.
 import { normalizeRemoteMemorySources } from "../../memory/remote/config.mjs";
 import { resolveMemoryRoot } from "../../memory/root.mjs";
 import { ensureBrowserDaemon } from "../../browser/client/lifecycle.mjs";
+import { registerProject } from "../../workspace/project-registry.mjs";
+import { listWorkspaceSessions } from "../../workspace/session-index.mjs";
+import { createWorkspaceSessionSupervisor } from "../../workspace/supervisor.mjs";
+import { createWorkspaceProjectRuntime } from "../workspace/project-runtime.mjs";
+import { createWorkspaceOutputRouter } from "../workspace/output-router.mjs";
+import { syncRuntimeSessionStateFromRunner } from "../workspace/runtime-session-state.mjs";
+import { loadMarchSessionRenderTimeline, saveMarchSessionRenderTimeline } from "../../session/state/march-session-ui-state.mjs";
 
 export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot } = {}) {
   if (!existsSync(stateRoot)) mkdirSync(stateRoot, { recursive: true });
@@ -56,6 +63,8 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
   const inputHistoryStore = createInputHistoryStore({ path: join(projectMarchDir, "input-history.json") });
   const modeState = createModeState();
   const namespace = loadOrCreateProjectId(projectMarchDir);
+  const currentProjectInfo = registerProject({ stateRoot, rootPath: cwd });
+  const projectMarchDirs = new Map([[currentProjectInfo.projectId, projectMarchDir]]);
   const memoryRoot = resolveMemoryRoot(config.memoryRoot, stateRoot);
   const profilePaths = defaultProfilePaths();
   ensureProfileFiles(profilePaths);
@@ -64,7 +73,6 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
   const currentProject = basename(cwd);
   const shellRuntime = args.shellRuntime ? createCliShellRuntime({ cwd }) : null;
 
-  const permissionMode = args.permissionMode;
   const sessionSource = "pi";
   const sessionsRoot = join(projectMarchDir, "sessions");
   const sessionState = {
@@ -82,7 +90,13 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
     shellRuntime,
     historyStore: inputHistoryStore,
   });
-
+  const outputRouter = createWorkspaceOutputRouter({
+    ui,
+    activeProjectId: currentProjectInfo.projectId,
+    activeSessionId: sessionState.sessionId,
+    onRenderTimelineChange: persistRenderTimeline,
+  });
+  const runtimeUi = outputRouter.createProjectUi(currentProjectInfo.projectId, () => sessionState.sessionId);
   let turnRunning = false;
   let refreshStatusBar = null;
   const runnerOptions = {
@@ -98,21 +112,26 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
     namespace,
     projectMarchDir,
     extensionPaths,
-    permissionMode,
     shellRuntime: Boolean(shellRuntime),
     lifecycleHooks: lifecycleManifests.hooks,
     lifecycleDiagnostics: lifecycleManifests.diagnostics,
     modelContextDumper: { enabled: args.dumpContext, rootDir: contextDumpRoot },
     remoteMemorySources,
+    notificationContext: { projectId: currentProjectInfo.projectId },
   };
 
   let runner;
+  let workspaceSupervisor = null;
+  const onNotificationActivation = (activation) => {
+    handleNotificationActivation({ activation, stateRoot, workspaceSupervisor, ui }).catch((err) => ui.writeln(`Notification activation failed: ${err.message}`));
+  };
   try {
     runner = await createRuntimeRunner({
       runnerOptions,
-      ui,
+      ui: runtimeUi,
       shellRuntime,
       refreshStatusBar: (...args) => refreshStatusBar?.(...args),
+      onNotificationActivation,
     });
   } catch (err) {
     process.stderr.write(`Error: ${err.message}\n`);
@@ -120,6 +139,46 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
     memoryStore.close?.();
     return { ok: false, code: 1, logger };
   }
+  syncRuntimeSessionStateFromRunner(sessionState, runner, sessionsRoot);
+
+  const initialRuntime = {
+    project: currentProjectInfo,
+    cwd,
+    currentProject,
+    runner,
+    ui: runtimeUi,
+    memoryStore,
+    sessionState,
+    sessionsRoot,
+    projectMarchDir,
+    extensionPaths,
+    keybindingConfig,
+    promptTemplateConfig,
+  };
+  workspaceSupervisor = createWorkspaceSessionSupervisor({
+    initialRuntime,
+    createProjectRuntime: (project) => {
+      projectMarchDirs.set(project.projectId, resolve(project.rootPath, ".march"));
+      return createWorkspaceProjectRuntime({
+        project,
+        args,
+        config,
+        stateRoot,
+        memoryRoot,
+        profilePaths,
+        createMemoryStore: () => new MarkdownMemoryStore({ root: memoryRoot }),
+        provider,
+        serviceTier,
+        model,
+        remoteMemorySources,
+        createUi: (runtimeSessionState) => outputRouter.createProjectUi(project.projectId, () => runtimeSessionState.sessionId),
+        refreshStatusBar: (...args) => refreshStatusBar?.(...args),
+        onNotificationActivation,
+      });
+    },
+    onActivate: ({ projectId, sessionId }) => outputRouter.setActiveSession(projectId, sessionId, { renderTimeline: loadStoredRenderTimeline(projectMarchDirs.get(projectId), sessionId) }),
+  });
+  runner = workspaceSupervisor.runner;
 
   refreshStatusBar = createStatusLineUpdater({
     ui,
@@ -150,16 +209,32 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
     projectMarchDir,
     ui,
   });
+  workspaceSupervisor.refreshActiveRuntime();
+  outputRouter.setActiveSession(currentProjectInfo.projectId, sessionState.sessionId, { renderTimeline: loadStoredRenderTimeline(projectMarchDir, sessionState.sessionId) });
   refreshStatusBar();
 
+  function persistRenderTimeline({ projectId, sessionId, events, event }) {
+    if (!sessionId || !shouldPersistRenderEvent(event?.method)) return;
+    const routeProjectMarchDir = projectMarchDirs.get(projectId);
+    if (!routeProjectMarchDir) return;
+    try {
+      saveMarchSessionRenderTimeline({ projectMarchDir: routeProjectMarchDir, sessionId, renderTimeline: events });
+    } catch {
+      // Render persistence is separate from model context; a UI write failure must not corrupt the turn.
+    }
+  }
+
   return {
     ok: true,
     args,
     cwd,
     ui,
     runner,
+    workspaceSupervisor,
+    workspaceOutputRouter: outputRouter,
     memoryStore,
     currentProject,
+    currentProjectInfo,
     sessionState,
     sessionsRoot,
     projectMarchDir,
@@ -175,3 +250,27 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
     setTurnRunning(value) { turnRunning = value; },
   };
 }
+function loadStoredRenderTimeline(projectMarchDir, sessionId) {
+  if (!projectMarchDir || !sessionId) return null;
+  try {
+    return loadMarchSessionRenderTimeline({ projectMarchDir, sessionId })?.renderTimeline ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function shouldPersistRenderEvent(method) {
+  return method === "turnEnd" || method === "assistantReplyEnd" || method === "toolEnd" || method === "writeln" || method === "clearOutput";
+}
+
+async function handleNotificationActivation({ activation, stateRoot, workspaceSupervisor, ui }) {
+  if (activation?.type !== "workspace-session" || !activation.projectId) return;
+  if (!workspaceSupervisor) throw new Error("workspace supervisor is not ready");
+  const projects = await listWorkspaceSessions({ stateRoot, currentProjectId: workspaceSupervisor.getActive?.()?.project?.projectId ?? null });
+  const runtime = await workspaceSupervisor.activateWorkspaceSessionById({
+    projects,
+    projectId: activation.projectId,
+    sessionId: activation.sessionId,
+  });
+  ui.writeln(`Activated session from notification: ${runtime.project.displayName}`);
+}

package/src/cli/startup/create-runtime-runner.mjs

@@ -5,6 +5,7 @@ export async function createRuntimeRunner({
   ui,
   shellRuntime,
   refreshStatusBar,
+  onNotificationActivation = null,
 } = {}) {
   const onModelPayload = ({ estimatedTokens }) => {
     refreshStatusBar?.({ contextTokens: estimatedTokens });
@@ -13,7 +14,7 @@ export async function createRuntimeRunner({
     refreshStatusBar?.();
   };
 
-  const { runner } = await createRunnerProcessClient({ runnerOptions, ui, onModelPayload, onLspStatusChange });
+  const { runner } = await createRunnerProcessClient({ runnerOptions, ui, onModelPayload, onLspStatusChange, onNotificationActivation });
   runner.shellRuntime ??= shellRuntime;
   return runner;
 }

package/src/cli/startup/startup-session.mjs

@@ -1,20 +1,10 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { loadOrCreateProjectId } from "../../workspace/project-id.mjs";
 import { listPiSessionInfos } from "../../session/pi-manager.mjs";
+
 import { loadPiSessionTranscriptTurns } from "../../session/transcript.mjs";
 import { resumePiSessionById } from "../session/pi-session-switch-command.mjs";
 
-export function loadOrCreateProjectId(projectMarchDir) {
-  if (!existsSync(projectMarchDir)) mkdirSync(projectMarchDir, { recursive: true });
-  const idFile = resolve(projectMarchDir, "project-id");
-  if (existsSync(idFile)) {
-    return readFileSync(idFile, "utf8").trim();
-  }
-  const id = randomUUID();
-  writeFileSync(idFile, id, "utf8");
-  return id;
-}
+export { loadOrCreateProjectId };
 
 export async function resumeStartupSession({
   resumeId,

package/src/cli/ui.mjs

@@ -5,7 +5,6 @@ import { buildMarchCommands, MarchAutocompleteProvider } from "./input/autocompl
 import { createJsonUI, createPlainUI } from "./fallback-ui.mjs";
 import { createKeybindingDispatcher } from "./input/keybinding-dispatch.mjs";
 import { OutputBuffer } from "./tui/output-buffer.mjs";
-import { requestToolPermission } from "./tui/permission-request-ui.mjs";
 import { runTuiExternalEditor } from "./tui/editor/external-editor-runner.mjs";
 import { createRetryStatusController } from "./tui/status/retry-status.mjs";
 import { createShellDrawerControls } from "./shell/shell-drawer-controls.mjs";
@@ -248,11 +247,6 @@ export function createTuiUI({
       requestRender();
     },
 
-    requestPermission: async ({ toolName, params, category }) => {
-      ensureStarted();
-      spinnerStatus.stop();
-      return requestToolPermission({ toolName, params, category, output, selectList, requestRender });
-    },
 
     setEscapeHandler: (fn) => { onEscapeHandler = fn; },
     setCtrlCHandler: (fn) => { onCtrlCHandler = fn; },

package/src/cli/workspace/command.mjs

@@ -0,0 +1,121 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { brightBlack } from "../tui/ui-theme.mjs";
+import { registerProject, listRegisteredProjects } from "../../workspace/project-registry.mjs";
+import { buildWorkspaceSessionSelectItems, listWorkspaceSessions, workspaceSessionSearchText } from "../../workspace/session-index.mjs";
+
+export const WORKSPACE_SLASH_COMMANDS = [
+  {
+    metadata: [
+      { name: "project", description: "List registered projects" },
+      { name: "project add", helpSyntax: "project add <path>", description: "Register a project root" },
+    ],
+    match: (trimmed) => {
+      const parsed = parseProjectCommand(trimmed);
+      return parsed.type === "none" ? null : { parsed };
+    },
+    run: async (ctx, command) => writeLines(ctx.ui, await handleProjectCommand(command, ctx)),
+  },
+  {
+    metadata: [{ name: "session", description: "Open workspace session selector" }],
+    match: (trimmed) => trimmed === "/session" ? { parsed: { type: "session" } } : null,
+    run: handleSessionCommand,
+  },
+];
+
+export function parseProjectCommand(trimmed) {
+  if (trimmed === "/project" || trimmed === "/project list") return { type: "list" };
+  if (trimmed.startsWith("/project add ")) return { type: "add", path: trimmed.slice("/project add ".length).trim() };
+  return { type: "none" };
+}
+
+export async function handleProjectCommand(command, { stateRoot }) {
+  if (!stateRoot) return ["Error: workspace registry is not available."];
+  if (command.type === "add") {
+    const rootPath = resolve(command.path);
+    if (!existsSync(rootPath)) return [`Error: project path does not exist: ${rootPath}`];
+    const project = registerProject({ stateRoot, rootPath });
+    return [`Registered project: ${project.displayName}`, brightBlack(project.rootPath)];
+  }
+
+  const projects = listRegisteredProjects({ stateRoot });
+  if (projects.length === 0) return ["No registered projects."];
+  return ["Registered projects:", ...projects.map((project) => `- ${project.displayName}  ${brightBlack(project.rootPath)}`)];
+}
+
+export async function handleSessionCommand({ stateRoot, currentProjectId, runner, workspaceSupervisor, workspaceOutputRouter, ui }) {
+  if (!stateRoot) {
+    ui.writeln("Session selector is not available: workspace registry is missing.");
+    return { handled: true };
+  }
+  const projects = await listWorkspaceSessions({ stateRoot, currentProjectId });
+  const currentSessionId = runner.getSessionStats?.().sessionId ?? null;
+  const runtimeSummaries = workspaceSupervisor?.getRuntimeSummaries?.() ?? [];
+  const items = annotateWorkspaceItems(buildWorkspaceSessionSelectItems(projects, currentSessionId), runtimeSummaries);
+  if (items.length === 0) {
+    ui.writeln("No registered projects. Start March in a project or run /project add <path>.");
+    return { handled: true };
+  }
+  if (!ui.selectList) {
+    ui.writeln("Session selector is only available in TUI.");
+    return { handled: true };
+  }
+  const selectedIndex = Math.max(0, items.findIndex((item) => item.project.current && item.session?.id === currentSessionId));
+  const item = await ui.selectList({
+    items,
+    selectedIndex,
+    width: 90,
+    suppressInitialConfirm: true,
+    searchable: true,
+    getSearchText: workspaceSessionSearchText,
+  });
+  if (!item) {
+    ui.writeln("Session unchanged.");
+    return { handled: true };
+  }
+  if (!item.session) {
+    if (!workspaceSupervisor?.startNewWorkspaceSession) {
+      ui.writeln("New session creation requires the workspace supervisor.");
+      return { handled: true };
+    }
+    try {
+      const { result } = await workspaceSupervisor.startNewWorkspaceSession(item.project);
+      ui.writeln(`Created session: ${item.project.displayName} / ${result?.sessionId ?? "new session"}`);
+      return { handled: true, refreshContextTokens: true, activeChanged: true };
+    } catch (err) {
+      ui.writeln(`Error: ${err.message}`);
+      return { handled: true };
+    }
+  }
+  if (workspaceSupervisor) {
+    try {
+      await workspaceSupervisor.activateWorkspaceSession({ project: item.project, session: item.session });
+      ctxRenderActiveSession({ workspaceOutputRouter, projectId: item.project.projectId, sessionId: item.session.id });
+      return { handled: true, refreshContextTokens: true, activeChanged: true };
+    } catch (err) {
+      ui.writeln(`Error: ${err.message}`);
+      return { handled: true };
+    }
+  }
+  ui.writeln("Workspace session activation requires the workspace supervisor.");
+  return { handled: true };
+}
+
+function annotateWorkspaceItems(items, runtimeSummaries) {
+  if (!runtimeSummaries.length) return items;
+  const running = new Set(runtimeSummaries.filter((runtime) => runtime.running).map((runtime) => `${runtime.projectId}:${runtime.sessionId}`));
+  return items.map((item) => {
+    if (!item.session) return item;
+    if (!running.has(`${item.project.projectId}:${item.session.id}`)) return item;
+    return { ...item, description: `running · ${item.description}` };
+  });
+}
+
+function ctxRenderActiveSession({ workspaceOutputRouter, projectId, sessionId }) {
+  return workspaceOutputRouter?.getRenderEventCount?.(projectId, sessionId) ?? 0;
+}
+
+function writeLines(ui, lines) {
+  for (const line of lines) ui.writeln(line);
+  return { handled: true };
+}

package/src/cli/workspace/output-router.mjs

@@ -0,0 +1,127 @@
+const RENDER_METHODS = new Set([
+  "turnStart",
+  "turnEnd",
+  "assistantReplyEnd",
+  "textDelta",
+  "thinkingStart",
+  "thinkingDelta",
+  "thinkingEnd",
+  "thinkingBlock",
+  "toolStart",
+  "toolEnd",
+  "retryStart",
+  "retryEnd",
+  "status",
+  "recall",
+  "editDiff",
+  "write",
+  "writeln",
+  "clearOutput",
+]);
+
+const MAX_RENDER_EVENTS_PER_ROUTE = 4000;
+
+export function createWorkspaceOutputRouter({ ui, activeProjectId, activeSessionId = null, onRenderTimelineChange = null }) {
+  let active = routeKey(activeProjectId, activeSessionId);
+  const timelines = new Map();
+
+  return {
+    setActiveProject(projectId) {
+      this.setActiveSession(projectId, null);
+    },
+    setActiveSession(projectId, sessionId, { renderTimeline = null } = {}) {
+      const next = routeKey(projectId, sessionId);
+      if (Array.isArray(renderTimeline)) setRenderEvents(next, renderTimeline);
+      if (next === active) return renderRoute(next);
+      active = next;
+      return renderRoute(next);
+    },
+    getActiveRouteKey() {
+      return active;
+    },
+    getActiveProject() {
+      return parseRouteKey(active).projectId;
+    },
+    createProjectUi(projectId, getSessionId = null) {
+      return this.createSessionUi({ projectId, getSessionId });
+    },
+    createSessionUi({ projectId, sessionId = null, getSessionId = null }) {
+      return new Proxy({}, {
+        get(_target, prop) {
+          if (prop === "__projectId") return projectId;
+          const value = ui[prop];
+          if (typeof value !== "function") return value;
+          return (...args) => {
+            const key = routeKey(projectId, typeof getSessionId === "function" ? getSessionId() : sessionId);
+            if (!RENDER_METHODS.has(prop)) return value.apply(ui, args);
+            recordRenderEvent(key, prop, args);
+            if (key === active) return value.apply(ui, args);
+            return undefined;
+          };
+        },
+        set(_target, prop, value) {
+          ui[prop] = value;
+          return true;
+        },
+        has(_target, prop) {
+          return prop in ui;
+        },
+      });
+    },
+    renderActiveSession() {
+      return renderRoute(active);
+    },
+    getRenderEvents(projectId, sessionId = null) {
+      return [...(timelines.get(routeKey(projectId, sessionId)) ?? [])];
+    },
+    setRenderEvents(projectId, sessionId = null, events = []) {
+      setRenderEvents(routeKey(projectId, sessionId), events);
+    },
+    getRenderEventCount(projectId, sessionId = null) {
+      return timelines.get(routeKey(projectId, sessionId))?.length ?? 0;
+    },
+  };
+
+  function renderRoute(key) {
+    ui.clearOutput?.();
+    const events = timelines.get(key) ?? [];
+    for (const event of events) applyRenderEvent(event);
+    return events.length;
+  }
+
+  function applyRenderEvent({ method, args }) {
+    const value = ui[method];
+    if (typeof value === "function") value.apply(ui, args);
+  }
+
+  function recordRenderEvent(key, method, args) {
+    if (method === "clearOutput") {
+      timelines.delete(key);
+      onRenderTimelineChange?.({ ...parseRouteKey(key), events: [], event: { method, args } });
+      return;
+    }
+    const events = timelines.get(key) ?? [];
+    events.push({ method, args, at: Date.now() });
+    if (events.length > MAX_RENDER_EVENTS_PER_ROUTE) events.splice(0, events.length - MAX_RENDER_EVENTS_PER_ROUTE);
+    timelines.set(key, events);
+    onRenderTimelineChange?.({ ...parseRouteKey(key), events: [...events], event: { method, args } });
+  }
+
+  function setRenderEvents(key, events) {
+    timelines.set(key, normalizeRenderEvents(events));
+  }
+}
+
+export function routeKey(projectId, sessionId = null) {
+  return `${projectId ?? ""}:${sessionId ?? ""}`;
+}
+
+function parseRouteKey(key) {
+  const [projectId, sessionId = ""] = String(key ?? "").split(":", 2);
+  return { projectId: projectId || null, sessionId: sessionId || null };
+}
+
+function normalizeRenderEvents(events) {
+  if (!Array.isArray(events)) return [];
+  return events.filter((event) => typeof event?.method === "string" && Array.isArray(event.args));
+}