@akira-tl/forgerelay 0.2.4 → 0.2.6

package/dist/server.js

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { access, realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
@@ -20,26 +20,26 @@ import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
 import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
-import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, workspaceLogLabel, } from "./logger.js";
+import { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
-import { McpSessionRegistry, } from "./mcp-sessions.js";
-import { ProcessSessionManager, } from "./process-sessions.js";
+import { McpTransportRegistry, } from "./mcp-sessions.js";
+import { ProcessManager, resolveProcessId, } from "./process-sessions.js";
 import { createReviewCheckpointManager } from "./review-checkpoints.js";
 import { openAiConversationScopeId } from "./request-meta.js";
+import { readWorkspaceAppManifestEntry, resolveWorkspaceAppIdentity, WORKSPACE_APP_LEGACY_URI, WORKSPACE_APP_URI_TEMPLATE, } from "./mcp-app-template.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { formatPathForPrompt } from "./skills.js";
 import { createWorkspaceStore } from "./workspace-store.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { summarizeLocalAgentProfile } from "./local-agent-profiles.js";
 import { formatLocalAgentProviderAvailabilitySummary, getLocalAgentProviderAvailabilitySnapshot, } from "./local-agent-availability.js";
-// MCP clients can reconnect without closing the previous transport. Bound stale
-// session retention so abandoned MCP servers do not accumulate for the life of the process.
-const MCP_SESSION_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+// Legacy MCP Streamable HTTP clients can reconnect without closing the previous
+// transport. Bound stale transport-session retention so abandoned transports do
+// not accumulate for the life of the process.
+const MCP_TRANSPORT_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
 const FORGERELAY_VERSION = readForgeRelayVersion();
-const MCP_SESSION_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
-const WORKSPACE_APP_URI = "ui://forgerelay/workspace-app.html";
-const WORKSPACE_APP_MANIFEST_ENTRY = "workspace-app.html";
+const MCP_TRANSPORT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
 const WRITE_TOOL_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: true,
@@ -71,20 +71,21 @@ function shouldAttachWidget(mode, kind) {
 function toolWidgetDescriptorMeta(config, kind) {
     if (!shouldAttachWidget(config.widgets, kind))
         return { _meta: {} };
+    const resourceUri = currentWorkspaceAppIdentity().uri;
     return {
         _meta: {
             ui: {
-                resourceUri: WORKSPACE_APP_URI,
-                visibility: ["model"],
+                resourceUri,
+                visibility: ["model", "app"],
             },
+            "openai/outputTemplate": resourceUri,
         },
     };
 }
-function workspaceLogContext(workspace, sessionId) {
+function workspaceLogContext(workspace, _transportSessionId) {
     return {
         workspaceId: workspace.id,
         workspace: workspaceLogLabel(workspace.root, workspace.id),
-        session: sessionIdPrefix(sessionId),
     };
 }
 function formatVisibleAgent(agent) {
@@ -161,6 +162,23 @@ function requestLogFields(req, config) {
         contentLength: req.header("content-length"),
     };
 }
+function mcpRequestDebugFields(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return {};
+    const request = body;
+    const rpcMethod = typeof request.method === "string" ? request.method : undefined;
+    const params = request.params && typeof request.params === "object" && !Array.isArray(request.params)
+        ? request.params
+        : undefined;
+    let rpcTarget;
+    if (rpcMethod === "resources/read" && typeof params?.uri === "string") {
+        rpcTarget = params.uri;
+    }
+    else if (rpcMethod === "tools/call" && typeof params?.name === "string") {
+        rpcTarget = params.name;
+    }
+    return { rpcMethod, rpcTarget };
+}
 function logToolCall(config, fields) {
     if (!config.logging.toolCalls)
         return;
@@ -247,16 +265,20 @@ function assetBaseUrl(config) {
 function uiManifestUrl() {
     return new URL("../dist/ui/.vite/manifest.json", import.meta.url);
 }
-function readWorkspaceAppManifest() {
-    return JSON.parse(readFileSync(uiManifestUrl(), "utf8"));
+function uiBuildDirectoryUrl() {
+    return new URL("../dist/ui/", import.meta.url);
+}
+let cachedWorkspaceAppIdentity;
+function currentWorkspaceAppIdentity() {
+    cachedWorkspaceAppIdentity ??= resolveWorkspaceAppIdentity({
+        manifestUrl: uiManifestUrl(),
+        buildDirectoryUrl: uiBuildDirectoryUrl(),
+        fallbackRevision: FORGERELAY_VERSION,
+    });
+    return cachedWorkspaceAppIdentity;
 }
 function getWorkspaceAppManifestEntry() {
-    const manifest = readWorkspaceAppManifest();
-    const entry = manifest[WORKSPACE_APP_MANIFEST_ENTRY];
-    if (!entry?.file) {
-        throw new Error(`Missing ${WORKSPACE_APP_MANIFEST_ENTRY} in UI manifest.`);
-    }
-    return entry;
+    return readWorkspaceAppManifestEntry(uiManifestUrl());
 }
 function assetUrl(baseUrl, assetPath) {
     return `${baseUrl}/${assetPath.replace(/^\/+/, "")}`;
@@ -306,9 +328,54 @@ async function assertWorkspaceAppAssets() {
         await access(candidate);
     }
 }
+function workspaceAppCompatibilityKind(requestedUri, currentUri) {
+    if (requestedUri === currentUri)
+        return "current";
+    if (requestedUri === WORKSPACE_APP_LEGACY_URI)
+        return "legacy";
+    return "historical";
+}
+async function readWorkspaceAppResource(config, requestedUri, transportSessionId) {
+    const currentUri = currentWorkspaceAppIdentity().uri;
+    const compatibility = workspaceAppCompatibilityKind(requestedUri, currentUri);
+    try {
+        await assertWorkspaceAppAssets();
+        const result = {
+            contents: [
+                {
+                    uri: requestedUri,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: workspaceAppHtml(config),
+                    _meta: {
+                        ui: {
+                            csp: appCsp(config),
+                        },
+                    },
+                },
+            ],
+        };
+        logEvent(config.logging, "debug", "mcp_app_template_read", {
+            requestedUri,
+            currentUri,
+            compatibility,
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
+        });
+        return result;
+    }
+    catch (error) {
+        logEvent(config.logging, "warn", "mcp_app_template_read_failed", {
+            requestedUri,
+            currentUri,
+            compatibility,
+            error: error instanceof Error ? error.message : String(error),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
+        });
+        throw error;
+    }
+}
 function processResult(snapshot) {
     const status = snapshot.running
-        ? `Process running with session ID ${snapshot.sessionId}.`
+        ? `Process running with process ID ${snapshot.processId}.`
         : snapshot.signal
             ? `Process exited after signal ${snapshot.signal}.`
             : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
@@ -316,8 +383,8 @@ function processResult(snapshot) {
 }
 function completedProcessResult(snapshot) {
     const status = snapshot.signal
-        ? `Background process ${snapshot.sessionId} exited after signal ${snapshot.signal}.`
-        : `Background process ${snapshot.sessionId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
+        ? `Background process ${snapshot.processId} exited after signal ${snapshot.signal}.`
+        : `Background process ${snapshot.processId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
     const command = `Command: ${snapshot.command}`;
     const output = snapshot.output ? `\n${snapshot.output.replace(/\n$/, "")}` : "";
     return `${status}\n${command}${output}`;
@@ -339,10 +406,14 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
     if (!Array.isArray(content))
         return result;
     const structured = result.structuredContent;
-    const currentSessionId = structured?.running === true && typeof structured.sessionId === "number"
-        ? structured.sessionId
+    const currentProcessId = structured?.running === true
+        ? typeof structured.processId === "number"
+            ? structured.processId
+            : typeof structured.sessionId === "number"
+                ? structured.sessionId
+                : undefined
         : undefined;
-    const completed = processSessions.takeCompleted(workspaceId, undefined, currentSessionId);
+    const completed = processSessions.takeCompleted(workspaceId, undefined, currentProcessId);
     if (completed.length === 0)
         return result;
     return {
@@ -355,7 +426,8 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
 }
 function processOutputSchema() {
     return resultOutputSchema({
-        sessionId: z.number().optional(),
+        processId: z.number().int().positive().optional().describe("Canonical process handle for write_stdin."),
+        sessionId: z.number().int().positive().optional().describe("Deprecated alias of processId for compatibility."),
         running: z.boolean(),
         exitCode: z.number().int().optional(),
         signal: z.string().optional(),
@@ -386,6 +458,7 @@ function processToolResponse(tool, workspaceId, snapshot, summary) {
         },
         structuredContent: {
             result,
+            processId: snapshot.processId,
             sessionId: snapshot.sessionId,
             running: snapshot.running,
             exitCode: snapshot.exitCode,
@@ -410,7 +483,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
     if (config.toolMode === "codex") {
         registerAppTool(server, "exec_command", {
             title: "Execute command",
-            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
+            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a processId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
             inputSchema: {
                 workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
                 cmd: z.string().min(1).describe("Shell command to execute."),
@@ -430,7 +503,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     .min(0)
                     .max(30_000)
                     .optional()
-                    .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
+                    .describe("Milliseconds to wait before returning a running process. Defaults to 10000."),
                 maxOutputTokens: z
                     .number()
                     .int()
@@ -471,7 +544,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                         commandLength: cmd.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || snapshot.exitCode === 0,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -491,7 +564,8 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         description: "Poll or write characters to a running process returned by bash or exec_command. Omit chars or pass an empty string to poll. Waiting never kills the process; pass \\u0003 to explicitly send Ctrl-C.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier used to start the process."),
-            sessionId: z.number().describe("Process session identifier returned by exec_command."),
+            processId: z.number().int().positive().optional().describe("Canonical process identifier returned by bash or exec_command."),
+            sessionId: z.number().int().positive().optional().describe("Deprecated alias for processId. Retained for compatibility."),
             chars: z.string().optional().describe("Characters to write. Omit or pass an empty string to poll."),
             columns: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this width."),
             rows: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this height."),
@@ -513,13 +587,14 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         outputSchema: processOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "shell"),
         annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
+    }, async ({ workspaceId, processId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
+        const resolvedProcessId = resolveProcessId(processId, sessionId);
         return runToolWithHooks(hooks, {
             tool: "write_stdin",
             invocation: workspaceHookInvocation(workspace),
             payload: {
-                sessionId,
+                processId: resolvedProcessId,
                 charactersWritten: chars?.length ?? 0,
                 columns,
                 rows,
@@ -528,7 +603,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                 const startedAt = performance.now();
                 const snapshot = await processSessions.write({
                     workspaceId,
-                    sessionId,
+                    processId: resolvedProcessId,
                     chars,
                     columns,
                     rows,
@@ -540,12 +615,12 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     ...workspaceLogContext(workspace, extra.sessionId),
                     exitCode: snapshot.exitCode,
                     running: snapshot.running,
-                    processSessionId: snapshot.sessionId,
+                    processId: snapshot.processId,
                     success: snapshot.running || snapshot.exitCode === 0,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
                 return processToolResponse("write_stdin", workspaceId, snapshot, {
-                    sessionId,
+                    processId: resolvedProcessId,
                     charactersWritten: chars?.length ?? 0,
                     running: snapshot.running,
                     exitCode: snapshot.exitCode,
@@ -568,30 +643,21 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             artifactDownloadSupported: isArtifactDownloadSupportedPlatform(),
         }),
     });
-    registerAppResource(server, "ForgeRelay Diff Card", WORKSPACE_APP_URI, {
+    const currentWorkspaceAppUri = currentWorkspaceAppIdentity().uri;
+    const workspaceAppResourceMetadata = {
         description: "Interactive card for viewing ForgeRelay file diffs.",
         _meta: {
             ui: {
                 csp: appCsp(config),
             },
         },
-    }, async () => {
-        await assertWorkspaceAppAssets();
-        return {
-            contents: [
-                {
-                    uri: WORKSPACE_APP_URI,
-                    mimeType: RESOURCE_MIME_TYPE,
-                    text: workspaceAppHtml(config),
-                    _meta: {
-                        ui: {
-                            csp: appCsp(config),
-                        },
-                    },
-                },
-            ],
-        };
-    });
+    };
+    registerAppResource(server, "ForgeRelay Diff Card", currentWorkspaceAppUri, workspaceAppResourceMetadata, async (uri, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
+    registerAppResource(server, "ForgeRelay Diff Card legacy", WORKSPACE_APP_LEGACY_URI, workspaceAppResourceMetadata, async (uri, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
+    server.registerResource("ForgeRelay Diff Card compatibility", new ResourceTemplate(WORKSPACE_APP_URI_TEMPLATE, { list: undefined }), {
+        ...workspaceAppResourceMetadata,
+        mimeType: RESOURCE_MIME_TYPE,
+    }, async (uri, _variables, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
     registerAppTool(server, "open_workspace", {
         title: "Open workspace",
         description: "Open or resume a local coding workspace. A conversation keeps a stable workspaceId for a project, while different conversations normally receive different logical workspaceIds that may point at the same physical checkout or worktree. Pass workspaceId to explicitly resume an existing logical workspace in this conversation. Default to checkout mode and only use mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Workspaces idle for more than two days are reported for user-directed cleanup or resumption.",
@@ -944,7 +1010,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: z
                 .string()
                 .describe(config.skillsEnabled
-                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill path from open_workspace skills."
+                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill path from open_workspace skills, including a ~/... home-relative path."
                 : "File path to read, relative to the workspace root or absolute inside the OS temp directory."),
             offset: z
                 .number()
@@ -1690,7 +1756,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         commandLength: command.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -1729,7 +1795,7 @@ export function createServer(config = loadConfig(), options = {}) {
         host: config.host,
         ...(allowedHosts ? { allowedHosts } : {}),
     });
-    const transports = new McpSessionRegistry();
+    const transports = new McpTransportRegistry();
     const mcpUrl = new URL("/mcp", config.publicBaseUrl);
     const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
     const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
@@ -1741,34 +1807,44 @@ export function createServer(config = loadConfig(), options = {}) {
     const workspaceStore = createWorkspaceStore(config.stateDir);
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
     const reviewCheckpoints = createReviewCheckpointManager();
-    const processSessions = new ProcessSessionManager();
+    const processSessions = new ProcessManager();
     const localAgentProviders = config.subagents
         ? getLocalAgentProviderAvailabilitySnapshot()
         : [];
-    const logSessionCloseResults = (reason, results) => {
+    const logTransportCloseResults = (reason, results) => {
+        let closedCount = 0;
         for (const result of results) {
             if (result.error) {
-                logEvent(config.logging, "warn", "mcp_session_close_failed", {
+                logEvent(config.logging, "warn", "mcp_transport_session_close_failed", {
                     reason,
-                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
                     error: result.error instanceof Error
                         ? result.error.message
                         : String(result.error),
                 });
                 continue;
             }
-            logEvent(config.logging, "info", "mcp_session_closed", {
+            closedCount += 1;
+            if (reason === "idle_timeout") {
+                logEvent(config.logging, "debug", "mcp_transport_session_closed", {
+                    reason,
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
+                });
+            }
+        }
+        if (reason === "server_shutdown" && closedCount > 0) {
+            logEvent(config.logging, "debug", "mcp_transport_sessions_closed", {
                 reason,
-                sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                count: closedCount,
             });
         }
     };
-    const sessionCleanupTimer = setInterval(() => {
+    const transportCleanupTimer = setInterval(() => {
         void transports
-            .closeIdle(MCP_SESSION_IDLE_TIMEOUT_MS)
-            .then((results) => logSessionCloseResults("idle_timeout", results));
-    }, MCP_SESSION_CLEANUP_INTERVAL_MS);
-    sessionCleanupTimer.unref();
+            .closeIdle(MCP_TRANSPORT_IDLE_TIMEOUT_MS)
+            .then((results) => logTransportCloseResults("idle_timeout", results));
+    }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
+    transportCleanupTimer.unref();
     if (config.logging.trustProxy) {
         app.set("trust proxy", true);
     }
@@ -1816,7 +1892,7 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     app.all("/mcp", async (req, res) => {
         const requestId = res.locals.requestId;
-        const sessionId = req.header("mcp-session-id");
+        const transportSessionId = req.header("mcp-session-id");
         const initializeRequest = req.method === "POST" && isInitializeRequest(req.body);
         await new Promise((resolve, reject) => {
             bearerAuth(req, res, (error) => {
@@ -1841,39 +1917,40 @@ export function createServer(config = loadConfig(), options = {}) {
         }
         logEvent(config.logging, "debug", "mcp_request", {
             requestId,
-            method: req.method,
-            sessionIdPresent: Boolean(sessionId),
-            sessionIdPrefix: sessionIdPrefix(sessionId),
+            httpMethod: req.method,
+            transportSessionIdPresent: Boolean(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
             isInitialize: initializeRequest,
+            ...mcpRequestDebugFields(req.body),
         });
         try {
             let transport;
-            if (sessionId) {
-                transport = transports.get(sessionId);
+            if (transportSessionId) {
+                transport = transports.get(transportSessionId);
                 if (!transport) {
-                    sendJsonRpcError(res, 404, -32000, "Unknown MCP session");
+                    sendJsonRpcError(res, 404, -32000, "Unknown MCP transport session");
                     return;
                 }
             }
             else if (initializeRequest) {
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
-                    onsessioninitialized: (newSessionId) => {
+                    onsessioninitialized: (newTransportSessionId) => {
                         if (transport)
-                            transports.register(newSessionId, transport);
-                        logEvent(config.logging, "info", "mcp_session_created", {
+                            transports.register(newTransportSessionId, transport);
+                        logEvent(config.logging, "debug", "mcp_transport_session_created", {
                             requestId,
-                            sessionIdPrefix: sessionIdPrefix(newSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(newTransportSessionId),
                             ...requestLogFields(req, config),
                         });
                     },
                 });
                 transport.onclose = () => {
-                    const closedSessionId = transport?.sessionId;
-                    if (closedSessionId && transports.remove(closedSessionId)) {
-                        logEvent(config.logging, "info", "mcp_session_closed", {
+                    const closedTransportSessionId = transport?.sessionId;
+                    if (closedTransportSessionId && transports.remove(closedTransportSessionId)) {
+                        logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                             reason: "transport_close",
-                            sessionIdPrefix: sessionIdPrefix(closedSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(closedTransportSessionId),
                         });
                     }
                 };
@@ -1881,7 +1958,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 await server.connect(transport);
             }
             else {
-                sendJsonRpcError(res, 400, -32000, "No valid MCP session");
+                sendJsonRpcError(res, 400, -32000, "No valid MCP transport session");
                 return;
             }
             await transport.handleRequest(req, res, req.body);
@@ -1903,9 +1980,9 @@ export function createServer(config = loadConfig(), options = {}) {
         localAgentProviders,
         close: () => {
             closePromise ??= (async () => {
-                clearInterval(sessionCleanupTimer);
+                clearInterval(transportCleanupTimer);
                 const results = await transports.closeAll();
-                logSessionCloseResults("server_shutdown", results);
+                logTransportCloseResults("server_shutdown", results);
                 processSessions.shutdown();
                 oauthProvider.close();
                 workspaceStore.close?.();

package/docs/chatgpt-coding-workflow.md

@@ -168,10 +168,11 @@ The exact lifecycle tools available depend on the active server configuration.
 In minimal mode, normal shell inspection commands such as `rg`, `find`, and `ls`
 can be used rather than dedicated MCP search tools. `bash` waits in the foreground
 for at most 300 seconds. If the command is still running, ForgeRelay returns a
-process `sessionId` without killing it. The Agent can use `write_stdin` to poll,
+canonical `processId` without killing it. The Agent can use `write_stdin` to poll,
 wait again, interact, or explicitly send Ctrl-C, or continue other work; once the
 command finishes, its completion is attached to a later tool result using the
-same workspace ID.
+same workspace ID. The former process `sessionId` remains a deprecated alias in
+0.2.x for compatibility with existing clients.
 
 `FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
 

package/docs/configuration.md

@@ -132,16 +132,17 @@ receives a different ID for the same physical checkout/worktree. Pass
 `workspaceId` to `open_workspace` to explicitly resume an existing handle in the
 current conversation. `newWorkspace: true` allocates a new logical handle without
 creating another checkout or Git worktree and should be used only on explicit user
-request. Sessions idle for more than two days are returned in `staleWorkspaces` so
+request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
 the user can choose whether to resume or release them. `close_workspace` removes a
 logical handle without deleting checkout files; it refuses to remove the last
 handle anchoring a physical worktree.
 
 `bash` has no execution-timeout input. It waits in the foreground for at most 300
 seconds; if the process is still alive, the result contains `running: true` and a
-`sessionId`. `write_stdin` can poll or interact with that session for up to another
-300 seconds per call. ForgeRelay does not kill a process merely because a wait
-window expires. Completed background processes are delivered once with a later
+canonical `processId`. `write_stdin` can poll or interact with that process for up
+to another 300 seconds per call. The former `sessionId` field remains a deprecated
+alias during the 0.2.x compatibility window. ForgeRelay does not kill a process
+merely because a wait window expires. Completed background processes are delivered once with a later
 tool result for the same logical workspace ID.
 
 ## Widgets
@@ -336,8 +337,12 @@ forgerelay agents show <id>
 | `FORGERELAY_TRUST_PROXY` | `0` |
 
 `pretty` is the human-facing local console format. It uses terminal-aware color,
-short timestamps, workspace/session context, and compact operation results while
-keeping HTTP request records off by default. Shell command previews are enabled
+short timestamps, workspace-first context, and compact operation results while
+keeping HTTP request records off by default. Project names receive stable
+per-project colors and logical `ws_...` identifiers remain visible; transient MCP
+transport session IDs and normal transport lifecycle events are shown only at
+`debug` level, where they are labeled as `transport` rather than workspace/process
+identity. Shell command previews are enabled
 in this mode and truncated to 120 characters; set
 `FORGERELAY_LOG_SHELL_COMMANDS=0` when command arguments may contain secrets.
 

package/docs/debugging.md

@@ -59,17 +59,45 @@ The acceptance checks:
 3. unauthenticated `/mcp` rejection;
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
-6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, and workspace resume/stale-session schema;
-7. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessSessionManager`, and a deliberate failed `edit`;
-8. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP session, plus rejection of an arbitrary path outside the workspace/temp roots;
-9. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
-10. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
-11. deterministic local subagent error path，不联系任何模型 provider；
-12. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。
+6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
+7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
+8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
+9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
+10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
+11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
+12. deterministic local subagent error path，不联系任何模型 provider；
+13. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。
 
 `curl` must be available on `PATH` for this acceptance command. Node and Git are
 already normal ForgeRelay development prerequisites.
 
+## Debug ChatGPT template loading
+
+The normal debug runtime keeps widgets off so source-only server iteration does
+not accidentally serve stale UI assets. To debug the MCP App path, build first
+and enable widgets explicitly:
+
+```bash
+npm run build
+FORGERELAY_DEBUG_WIDGETS=full \
+FORGERELAY_LOG_LEVEL=debug \
+FORGERELAY_LOG_REQUESTS=1 \
+FORGERELAY_LOG_ASSETS=1 \
+npm run dev
+```
+
+At `debug` level, MCP requests include the JSON-RPC method and a safe target for
+`resources/read` and `tools/call`, while transport session IDs remain out of
+normal `info` tool logs. Successful template callbacks also emit `app template`
+entries identifying `current`, `legacy`, or `historical` compatibility reads. A
+successful ChatGPT template load should produce a sequence containing
+`resources/list`, `resources/read ui://...`, an `app template ... -> ok` entry,
+and then an HTTP `GET /mcp-app-assets/...` request. If `resources/read` never
+arrives, inspect the client/developer-mode connection. If it arrives and fails,
+inspect the MCP resource registration/build artifacts. If it succeeds but the
+asset request fails, inspect the public base URL, CSP, asset route, and browser
+console.
+
 ## Debug configuration
 
 The checked-in debug configuration is:

package/docs/gotchas.md

@@ -234,7 +234,28 @@ FORGERELAY_WIDGETS=full
 ```
 
 Use `FORGERELAY_WIDGETS=changes` for aggregate `show_changes`, or `off` to
-disable UI. Plain MCP clients may ignore ChatGPT Apps widget metadata.
+disable UI. Plain MCP clients may ignore MCP App widget metadata.
+
+If ChatGPT shows `Failed to fetch template`, first verify the server-side template
+chain with:
+
+```bash
+npm run build
+npm run debug:accept
+```
+
+The acceptance runner enables full widgets and checks that the tool advertises a
+content-hashed `ui://forgerelay/workspace-app-<hash>.html` resource, that
+`resources/read` returns `text/html;profile=mcp-app`, and that the referenced
+JavaScript asset is reachable. ForgeRelay also keeps the legacy
+`ui://forgerelay/workspace-app.html` pointer and historical
+`workspace-app-*.html` pointers readable so an older ChatGPT metadata snapshot
+can still fetch the current template while the connection is being refreshed.
+For a live ChatGPT trace, run the debug server with
+`FORGERELAY_DEBUG_WIDGETS=full`, `FORGERELAY_LOG_LEVEL=debug`,
+`FORGERELAY_LOG_REQUESTS=1`, and `FORGERELAY_LOG_ASSETS=1`; then distinguish a
+missing `resources/read` request from a template callback failure or a failed
+`/mcp-app-assets/` fetch.
 
 ## Data retention