@akira-tl/forgerelay 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-08-10
+
+### Changed
+
+- Human-facing `pretty` logs are workspace-first: normal tool and hook lines no longer show transient MCP transport session IDs, MCP session create/close lifecycle events are debug-only, and project names receive stable per-project terminal colors while the logical `ws_...` identifier remains visible.
+- MCP App tool metadata now uses a content-hashed UI resource URI derived from the built JavaScript/CSS, advertises both `model` and `app` visibility, and includes the ChatGPT `openai/outputTemplate` compatibility alias. Legacy `ui://forgerelay/workspace-app.html` and historical `workspace-app-*.html` pointers continue to resolve to the current template so stale ChatGPT metadata snapshots do not fail with a missing resource. Debug logs now distinguish current, legacy, and historical template reads, and real acceptance exercises current/compatibility resources plus the referenced JavaScript asset.
+- `~/...` paths are expanded before allowed-root resolution, so advertised skills rendered with home-relative paths can be read directly instead of being interpreted as a literal `~` directory under the workspace.
+- Successful MCP session shutdown and idle-cleanup lifecycle logs moved to `debug`; individual session close failures remain visible as warnings.
+
 ## [0.2.4] - 2026-08-09
 
 ### Added

package/dist/logger.js

@@ -13,6 +13,14 @@ const LEVEL_STYLE = {
     info: "green",
     debug: "gray",
 };
+const WORKSPACE_PROJECT_COLORS = [
+    "cyanBright",
+    "greenBright",
+    "yellowBright",
+    "magentaBright",
+    "blueBright",
+    "whiteBright",
+];
 export function shouldLog(config, level) {
     return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
 }
@@ -70,11 +78,13 @@ export function formatPrettyLogEntry(entry, options = {}) {
     const level = logLevel(entry.level);
     const time = formatTimestamp(entry.ts);
     const source = stringField(entry.workspace) ?? stringField(entry.workspaceId) ?? "forgerelay";
-    const session = stringField(entry.session) ?? stringField(entry.sessionIdPrefix);
+    const session = level === "debug"
+        ? stringField(entry.session) ?? stringField(entry.sessionIdPrefix)
+        : undefined;
     const prefix = [
         style("gray", time, options),
         `[${style(LEVEL_STYLE[level], level.toUpperCase(), options)}]`,
-        style(["cyan", "underline"], source, options),
+        formatPrettySource(source, options),
         session ? style("gray", `session:${session}`, options) : undefined,
         style("gray", "|", options),
     ].filter((value) => Boolean(value)).join(" ");
@@ -92,10 +102,18 @@ function formatPrettyMessage(entry, options) {
             return formatHookMessage(entry, options);
         case "http_request":
             return formatHttpMessage(entry, options);
+        case "mcp_request":
+            return formatMcpRequestMessage(entry);
+        case "mcp_app_template_read":
+            return formatAppTemplateMessage(entry, options, false);
+        case "mcp_app_template_read_failed":
+            return formatAppTemplateMessage(entry, options, true);
         case "mcp_session_created":
             return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} created`;
         case "mcp_session_closed":
             return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} closed`;
+        case "mcp_sessions_closed":
+            return `${numberField(entry.count) ?? 0} sessions closed`;
         case "mcp_session_close_failed":
             return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} close -> ${style("red", "error", options)}`;
         case "auth_denied":
@@ -161,6 +179,42 @@ function formatHttpMessage(entry, options) {
     const statusStyle = status !== undefined && status >= 400 ? "red" : "green";
     return `http ${method} ${path} -> ${style(statusStyle, statusText, options)}`;
 }
+function formatMcpRequestMessage(entry) {
+    const method = stringField(entry.rpcMethod) ?? stringField(entry.httpMethod) ?? "request";
+    const target = stringField(entry.rpcTarget);
+    return target ? `mcp ${method} ${target}` : `mcp ${method}`;
+}
+function formatAppTemplateMessage(entry, options, failed) {
+    const requestedUri = stringField(entry.requestedUri) ?? "unknown";
+    const compatibility = stringField(entry.compatibility) ?? "unknown";
+    if (failed) {
+        const error = stringField(entry.error);
+        return `app template ${compatibility} ${requestedUri} -> ${style("red", error ? `error: ${error}` : "error", options)}`;
+    }
+    const currentUri = stringField(entry.currentUri);
+    const target = compatibility === "current" || !currentUri
+        ? requestedUri
+        : `${requestedUri} => ${currentUri}`;
+    return `app template ${compatibility} ${target} -> ${style("green", "ok", options)}`;
+}
+function formatPrettySource(source, options) {
+    const separator = source.lastIndexOf("/");
+    if (separator <= 0 || separator === source.length - 1) {
+        return style(["cyan", "underline"], source, options);
+    }
+    const project = source.slice(0, separator);
+    const workspace = source.slice(separator + 1);
+    const projectColor = WORKSPACE_PROJECT_COLORS[stableColorIndex(project)];
+    return `${style([projectColor, "bold"], project, options)}/${style(["cyan", "underline"], workspace, options)}`;
+}
+function stableColorIndex(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0) % WORKSPACE_PROJECT_COLORS.length;
+}
 function formatGenericMessage(entry) {
     const event = String(entry.event ?? "log");
     const detail = [entry.reason, entry.error]

package/dist/mcp-app-template.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+export const WORKSPACE_APP_MANIFEST_ENTRY = "workspace-app.html";
+export const WORKSPACE_APP_LEGACY_URI = "ui://forgerelay/workspace-app.html";
+export const WORKSPACE_APP_URI_TEMPLATE = "ui://forgerelay/workspace-app-{revision}.html";
+export function workspaceAppUriForRevision(revision) {
+    return `ui://forgerelay/workspace-app-${encodeURIComponent(revision)}.html`;
+}
+export function readWorkspaceAppManifestEntry(manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const entry = manifest[WORKSPACE_APP_MANIFEST_ENTRY];
+    if (!entry?.file) {
+        throw new Error(`Missing ${WORKSPACE_APP_MANIFEST_ENTRY} in UI manifest.`);
+    }
+    return entry;
+}
+export function workspaceAppBundleRevision(entry, buildDirectoryUrl) {
+    const hash = createHash("sha256");
+    const assetPaths = [entry.file, ...(entry.css ?? [])];
+    for (const assetPath of assetPaths) {
+        hash.update(assetPath);
+        hash.update("\0");
+        hash.update(readFileSync(new URL(assetPath, buildDirectoryUrl)));
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 12);
+}
+export function resolveWorkspaceAppIdentity(options) {
+    try {
+        const entry = readWorkspaceAppManifestEntry(options.manifestUrl);
+        const revision = workspaceAppBundleRevision(entry, options.buildDirectoryUrl);
+        return {
+            revision,
+            uri: workspaceAppUriForRevision(revision),
+            source: "bundle",
+        };
+    }
+    catch {
+        return {
+            revision: options.fallbackRevision,
+            uri: workspaceAppUriForRevision(options.fallbackRevision),
+            source: "fallback",
+        };
+    }
+}

package/dist/roots.js

@@ -33,7 +33,7 @@ export function assertAllowedPath(path, allowedRoots) {
     throw new AccessDeniedError(`Path is outside allowed roots: ${path}`);
 }
 export function resolveAllowedPath(inputPath, cwd, allowedRoots) {
-    const absolutePath = resolve(cwd, inputPath);
+    const absolutePath = resolve(cwd, expandHomePath(inputPath));
     return assertAllowedPath(absolutePath, allowedRoots);
 }
 export async function resolveCanonicalAllowedPath(inputPath, cwd, allowedRoots) {

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";
@@ -27,6 +27,7 @@ import { McpSessionRegistry, } from "./mcp-sessions.js";
 import { ProcessSessionManager, } 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";
@@ -38,8 +39,6 @@ import { formatLocalAgentProviderAvailabilitySummary, getLocalAgentProviderAvail
 const MCP_SESSION_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 WRITE_TOOL_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: true,
@@ -71,20 +70,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, _sessionId) {
     return {
         workspaceId: workspace.id,
         workspace: workspaceLogLabel(workspace.root, workspace.id),
-        session: sessionIdPrefix(sessionId),
     };
 }
 function formatVisibleAgent(agent) {
@@ -161,6 +161,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 +264,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,6 +327,51 @@ 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,
+            sessionIdPrefix: sessionIdPrefix(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),
+            sessionIdPrefix: sessionIdPrefix(transportSessionId),
+        });
+        throw error;
+    }
+}
 function processResult(snapshot) {
     const status = snapshot.running
         ? `Process running with session ID ${snapshot.sessionId}.`
@@ -568,30 +634,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 +1001,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()
@@ -1746,6 +1803,7 @@ export function createServer(config = loadConfig(), options = {}) {
         ? getLocalAgentProviderAvailabilitySnapshot()
         : [];
     const logSessionCloseResults = (reason, results) => {
+        let closedCount = 0;
         for (const result of results) {
             if (result.error) {
                 logEvent(config.logging, "warn", "mcp_session_close_failed", {
@@ -1757,9 +1815,18 @@ export function createServer(config = loadConfig(), options = {}) {
                 });
                 continue;
             }
-            logEvent(config.logging, "info", "mcp_session_closed", {
+            closedCount += 1;
+            if (reason === "idle_timeout") {
+                logEvent(config.logging, "debug", "mcp_session_closed", {
+                    reason,
+                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                });
+            }
+        }
+        if (reason === "server_shutdown" && closedCount > 0) {
+            logEvent(config.logging, "debug", "mcp_sessions_closed", {
                 reason,
-                sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                count: closedCount,
             });
         }
     };
@@ -1841,10 +1908,11 @@ export function createServer(config = loadConfig(), options = {}) {
         }
         logEvent(config.logging, "debug", "mcp_request", {
             requestId,
-            method: req.method,
+            httpMethod: req.method,
             sessionIdPresent: Boolean(sessionId),
             sessionIdPrefix: sessionIdPrefix(sessionId),
             isInitialize: initializeRequest,
+            ...mcpRequestDebugFields(req.body),
         });
         try {
             let transport;
@@ -1861,7 +1929,7 @@ export function createServer(config = loadConfig(), options = {}) {
                     onsessioninitialized: (newSessionId) => {
                         if (transport)
                             transports.register(newSessionId, transport);
-                        logEvent(config.logging, "info", "mcp_session_created", {
+                        logEvent(config.logging, "debug", "mcp_session_created", {
                             requestId,
                             sessionIdPrefix: sessionIdPrefix(newSessionId),
                             ...requestLogFields(req, config),
@@ -1871,7 +1939,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 transport.onclose = () => {
                     const closedSessionId = transport?.sessionId;
                     if (closedSessionId && transports.remove(closedSessionId)) {
-                        logEvent(config.logging, "info", "mcp_session_closed", {
+                        logEvent(config.logging, "debug", "mcp_session_closed", {
                             reason: "transport_close",
                             sessionIdPrefix: sessionIdPrefix(closedSessionId),
                         });

package/docs/configuration.md

@@ -336,8 +336,11 @@ 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 session lifecycle events are shown only at
+`debug` level. 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`, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-session 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 `ProcessSessionManager`, and a deliberate failed `edit`;
+9. 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;
+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
 

package/docs/roadmap.md

@@ -82,6 +82,26 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 
 0.2 不引入审批 UI、HTTP/prompt/agent handler、Git 字符串解析器或插件注册表。只有出现真实需求时再扩展 handler 类型。
 
+### 0.2.5 — MCP App template reliability
+
+0.2.5 收敛 ChatGPT/MCP App 模板身份与排障链路：
+
+- 当前 UI resource URI 由实际构建出的 JavaScript/CSS 内容哈希生成，而不是仅依赖 npm 版本；
+- `ui://forgerelay/workspace-app.html` 继续作为 legacy pointer；
+- 历史 `workspace-app-*.html` URI 通过兼容 resource template 继续读取当前模板，避免旧 metadata snapshot 直接变成 missing resource；
+- debug 日志区分 current / legacy / historical template read，并保留 asset request trace；
+- 7677 acceptance 覆盖 tool metadata、resource list/template list、三类 template read 和静态 bundle HTTP fetch。
+
+### 0.2.6 — identity and transport terminology
+
+0.2.6 整理 ForgeRelay 中多个 `session` 含义，不改变 workspace-first 架构：
+
+- `workspaceId` 是唯一持久的逻辑工作身份，跨请求和 transport 重连保持连续；
+- `requestId` 只追踪单次 HTTP/JSON-RPC 请求，不持久化；
+- MCP 协议层 session 在内部和 debug 输出中明确称为 `transportSessionId`，业务状态不得依赖它；
+- 后台命令句柄逐步迁移为 `processId` / process handle；若公开 schema 改名需要兼容窗口，则在明确的版本边界完成；
+- 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
+
 ## 0.3 — LSP code intelligence v1
 
 LSP is moderate implementation complexity if ForgeRelay does not become a
@@ -90,6 +110,12 @@ language-server installer.
 The first version should launch only language servers already available on the
 user's machine or explicitly configured by the user/project.
 
+During 0.3 development, MCP App UI hardening can land alongside the LSP work when
+it does not distort the code-intelligence scope. In particular, evaluate a more
+self-contained template/bootstrap bundle, reduce avoidable external chunk fetches,
+and keep the current content-hash/compatibility-resource contract intact. This is
+reliability work, not a requirement to move application state into the UI.
+
 Initial operations:
 
 - diagnostics;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -41,7 +41,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -38,7 +38,13 @@ await assertDebugPortFree();
 rmSync(acceptanceRoot, { recursive: true, force: true });
 mkdirSync(acceptanceRoot, { recursive: true });
 
-const { env } = createDebugEnvironment({ ownerToken, stateDir, worktreeRoot, hookLog });
+const { env } = createDebugEnvironment({
+  ownerToken,
+  stateDir,
+  worktreeRoot,
+  hookLog,
+  widgets: "full",
+});
 const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
   cwd: repoRoot,
   env,
@@ -124,8 +130,64 @@ try {
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
+  const templateUri = bashTool?._meta?.ui?.resourceUri;
+  assert.match(
+    templateUri ?? "",
+    /^ui:\/\/forgerelay\/workspace-app-[0-9a-f]{12}\.html$/,
+    JSON.stringify(bashTool ?? {}),
+  );
+  assert.deepEqual(bashTool?._meta?.ui?.visibility, ["model", "app"]);
+  assert.equal(bashTool?._meta?.["openai/outputTemplate"], templateUri);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
+  const resources = mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id: 21,
+    method: "resources/list",
+    params: {},
+  }).message.result.resources;
+  assert.ok(resources.some((resource) => resource.uri === templateUri));
+  assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
+
+  const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id: 22,
+    method: "resources/templates/list",
+    params: {},
+  }).message.result.resourceTemplates;
+  assert.ok(resourceTemplates.some(
+    (resourceTemplate) => resourceTemplate.uriTemplate === "ui://forgerelay/workspace-app-{revision}.html",
+  ));
+
+  const readTemplate = (id, uri) => mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id,
+    method: "resources/read",
+    params: { uri },
+  }).message.result.contents[0];
+
+  const template = readTemplate(23, templateUri);
+  assert.equal(template.uri, templateUri);
+  assert.equal(template.mimeType, "text/html;profile=mcp-app");
+  assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
+  assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
+  const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
+  assert.ok(scriptUrl);
+  const scriptAsset = curlRequest({ method: "GET", url: scriptUrl });
+  assert.equal(scriptAsset.status, 200, scriptAsset.body);
+
+  const legacyTemplate = readTemplate(24, "ui://forgerelay/workspace-app.html");
+  assert.equal(legacyTemplate.uri, "ui://forgerelay/workspace-app.html");
+  assert.equal(legacyTemplate.mimeType, "text/html;profile=mcp-app");
+  assert.equal(legacyTemplate.text, template.text);
+
+  const historicalUri = "ui://forgerelay/workspace-app-0.2.4.html";
+  const historicalTemplate = readTemplate(25, historicalUri);
+  assert.equal(historicalTemplate.uri, historicalUri);
+  assert.equal(historicalTemplate.mimeType, "text/html;profile=mcp-app");
+  assert.equal(historicalTemplate.text, template.text);
+  pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
+
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
     path: checkoutWorkspace,
   });
@@ -364,7 +426,13 @@ function initializeRequest(id) {
     method: "initialize",
     params: {
       protocolVersion: "2025-06-18",
-      capabilities: {},
+      capabilities: {
+        extensions: {
+          "io.modelcontextprotocol/ui": {
+            mimeTypes: ["text/html;profile=mcp-app"],
+          },
+        },
+      },
       clientInfo: { name: "forgerelay-debug-acceptance", version: "1.0.0" },
     },
   };

package/scripts/debug/runtime.mjs

@@ -20,6 +20,7 @@ export function createDebugEnvironment({
   stateDir = resolve(debugRoot, "state"),
   worktreeRoot = resolve(debugRoot, "worktrees"),
   hookLog = debugHookLog,
+  widgets = process.env.FORGERELAY_DEBUG_WIDGETS ?? "off",
 } = {}) {
   const token = ownerToken ?? process.env.FORGERELAY_DEBUG_OWNER_TOKEN ?? createDebugOwnerToken();
   mkdirSync(debugRoot, { recursive: true });
@@ -37,7 +38,7 @@ export function createDebugEnvironment({
       FORGERELAY_WORKTREE_ROOT: worktreeRoot,
       FORGERELAY_OAUTH_OWNER_TOKEN: token,
       FORGERELAY_TOOL_MODE: "full",
-      FORGERELAY_WIDGETS: "off",
+      FORGERELAY_WIDGETS: widgets,
       FORGERELAY_LOG_LEVEL: process.env.FORGERELAY_LOG_LEVEL ?? "info",
       FORGERELAY_LOG_FORMAT: process.env.FORGERELAY_LOG_FORMAT ?? "pretty",
       FORGERELAY_DEBUG_HOOK_RECORDER: debugHookRecorder,