@akira-tl/forgerelay 0.2.3 → 0.2.5

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";
@@ -21,12 +21,13 @@ 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 { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, runShellTool, writeFileTool, } from "./pi-tools.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 { 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}.`
@@ -314,6 +380,45 @@ function processResult(snapshot) {
             : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
     return snapshot.output ? `${snapshot.output.replace(/\n$/, "")}\n${status}` : status;
 }
+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"}.`;
+    const command = `Command: ${snapshot.command}`;
+    const output = snapshot.output ? `\n${snapshot.output.replace(/\n$/, "")}` : "";
+    return `${status}\n${command}${output}`;
+}
+function attachCompletedProcessNotices(processSessions, workspaceId, result) {
+    if (result instanceof Error) {
+        const completed = processSessions.takeCompleted(workspaceId);
+        if (completed.length > 0) {
+            result.message = [
+                result.message,
+                ...completed.map((snapshot) => completedProcessResult(snapshot)),
+            ].join("\n\n");
+        }
+        return result;
+    }
+    if (typeof result !== "object" || result === null)
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    const structured = result.structuredContent;
+    const currentSessionId = structured?.running === true && typeof structured.sessionId === "number"
+        ? structured.sessionId
+        : undefined;
+    const completed = processSessions.takeCompleted(workspaceId, undefined, currentSessionId);
+    if (completed.length === 0)
+        return result;
+    return {
+        ...result,
+        content: [
+            ...content,
+            ...completed.map((snapshot) => textBlock(completedProcessResult(snapshot))),
+        ],
+    };
+}
 function processOutputSchema() {
     return resultOutputSchema({
         sessionId: z.number().optional(),
@@ -367,86 +472,89 @@ function workspaceHookInvocation(workspace) {
 function toolResultIsError(result) {
     return typeof result === "object" && result !== null && result.isError === true;
 }
-function registerCodexProcessTools(server, config, workspaces, processSessions, hooks) {
-    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.`,
-        inputSchema: {
-            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
-            cmd: z.string().min(1).describe("Shell command to execute."),
-            tty: z
-                .boolean()
-                .optional()
-                .describe("Allocate a pseudo-terminal for interactive commands. Defaults to false."),
-            columns: z.number().int().min(1).max(1_000).optional().describe("Initial PTY width. Defaults to 80."),
-            rows: z.number().int().min(1).max(1_000).optional().describe("Initial PTY height. Defaults to 24."),
-            workingDirectory: z
-                .string()
-                .optional()
-                .describe("Working directory relative to the workspace root. Defaults to the workspace root."),
-            yieldTimeMs: z
-                .number()
-                .int()
-                .min(0)
-                .max(30_000)
-                .optional()
-                .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
-            maxOutputTokens: z
-                .number()
-                .int()
-                .positive()
-                .max(100_000)
-                .optional()
-                .describe("Approximate output token budget. Defaults to 10000."),
-        },
-        outputSchema: processOutputSchema(),
-        ...toolWidgetDescriptorMeta(config, "shell"),
-        annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens }, extra) => {
-        const workspace = workspaces.getWorkspace(workspaceId);
-        return runToolWithHooks(hooks, {
-            tool: "exec_command",
-            invocation: workspaceHookInvocation(workspace),
-            payload: { command: cmd, workingDirectory: workingDirectory ?? "." },
-            operation: async () => {
-                const startedAt = performance.now();
-                const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
-                const snapshot = await processSessions.start({
-                    workspaceId,
-                    command: cmd,
-                    cwd,
-                    workspaceRoot: workspace.root,
-                    tty,
-                    columns,
-                    rows,
-                    yieldTimeMs,
-                    maxOutputTokens,
-                });
-                logToolCall(config, {
-                    tool: "exec_command",
-                    ...workspaceLogContext(workspace, extra.sessionId),
-                    workingDirectory: workingDirectory ?? ".",
-                    command: cmd,
-                    commandLength: cmd.length,
-                    exitCode: snapshot.exitCode,
-                    running: snapshot.running,
-                    processSessionId: snapshot.sessionId,
-                    success: snapshot.running || snapshot.exitCode === 0,
-                    durationMs: Math.round(performance.now() - startedAt),
-                });
-                return processToolResponse("exec_command", workspaceId, snapshot, {
-                    command: cmd,
-                    workingDirectory: workingDirectory ?? ".",
-                    running: snapshot.running,
-                    exitCode: snapshot.exitCode,
-                    wallTimeMs: snapshot.wallTimeMs,
-                });
+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.`,
+            inputSchema: {
+                workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+                cmd: z.string().min(1).describe("Shell command to execute."),
+                tty: z
+                    .boolean()
+                    .optional()
+                    .describe("Allocate a pseudo-terminal for interactive commands. Defaults to false."),
+                columns: z.number().int().min(1).max(1_000).optional().describe("Initial PTY width. Defaults to 80."),
+                rows: z.number().int().min(1).max(1_000).optional().describe("Initial PTY height. Defaults to 24."),
+                workingDirectory: z
+                    .string()
+                    .optional()
+                    .describe("Working directory relative to the workspace root. Defaults to the workspace root."),
+                yieldTimeMs: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(30_000)
+                    .optional()
+                    .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
+                maxOutputTokens: z
+                    .number()
+                    .int()
+                    .positive()
+                    .max(100_000)
+                    .optional()
+                    .describe("Approximate output token budget. Defaults to 10000."),
             },
+            outputSchema: processOutputSchema(),
+            ...toolWidgetDescriptorMeta(config, "shell"),
+            annotations: SHELL_TOOL_ANNOTATIONS,
+        }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens }, extra) => {
+            const workspace = workspaces.getWorkspace(workspaceId);
+            return runToolWithHooks(hooks, {
+                tool: "exec_command",
+                invocation: workspaceHookInvocation(workspace),
+                payload: { command: cmd, workingDirectory: workingDirectory ?? "." },
+                operation: async () => {
+                    const startedAt = performance.now();
+                    const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                    const snapshot = await processSessions.start({
+                        workspaceId,
+                        command: cmd,
+                        cwd,
+                        workspaceRoot: workspace.root,
+                        tty,
+                        columns,
+                        rows,
+                        yieldTimeMs,
+                        maxOutputTokens,
+                        codexCi: true,
+                    });
+                    logToolCall(config, {
+                        tool: "exec_command",
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        workingDirectory: workingDirectory ?? ".",
+                        command: cmd,
+                        commandLength: cmd.length,
+                        exitCode: snapshot.exitCode,
+                        running: snapshot.running,
+                        processSessionId: snapshot.sessionId,
+                        success: snapshot.running || snapshot.exitCode === 0,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return processToolResponse("exec_command", workspaceId, snapshot, {
+                        command: cmd,
+                        workingDirectory: workingDirectory ?? ".",
+                        running: snapshot.running,
+                        exitCode: snapshot.exitCode,
+                        wallTimeMs: snapshot.wallTimeMs,
+                    });
+                },
+            });
         });
-    });
+    }
     registerAppTool(server, "write_stdin", {
         title: "Write to process",
-        description: "Poll or write characters to a process returned by exec_command. Omit chars or pass an empty string to poll. Pass \\u0003 to send Ctrl-C.",
+        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."),
@@ -457,9 +565,9 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
                 .number()
                 .int()
                 .min(0)
-                .max(30_000)
+                .max(300_000)
                 .optional()
-                .describe("Milliseconds to wait for process output or completion. Defaults to 10000."),
+                .describe("Milliseconds to keep waiting before returning again, max 300000. Polling defaults to 5000; interaction defaults to 250."),
             maxOutputTokens: z
                 .number()
                 .int()
@@ -515,7 +623,7 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
 }
 export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters) {
     const toolDescriptions = buildToolDescriptions(config);
-    const hooks = new HookRunner(config.hooks, config.logging);
+    const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result));
     const server = new McpServer({
         name: "forgerelay",
         title: "ForgeRelay",
@@ -526,37 +634,33 @@ 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 a local project directory as a coding workspace. The same directory reuses the same active workspaceId across requests. Default to checkout mode and only use mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches and can later be safely closed into their original target branch with close_worktree. Existing managed worktree paths can also be reopened directly.",
+        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.",
         inputSchema: {
             path: z
                 .string()
-                .describe("Absolute path, or a leading-tilde home path such as ~/project, to a local project directory inside an allowed root. With mode=\"worktree\", this may also be a managed worktree path previously returned by ForgeRelay."),
+                .optional()
+                .describe("Project path to open. Required unless workspaceId is supplied. With mode=\"worktree\", this may also be a managed worktree path previously returned by ForgeRelay."),
+            workspaceId: z
+                .string()
+                .optional()
+                .describe("Existing logical workspace ID to resume in this conversation. When supplied, ForgeRelay resumes that workspace rather than allocating another ID."),
             mode: z
                 .enum(["checkout", "worktree"])
                 .optional()
@@ -568,7 +672,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             newWorktree: z
                 .boolean()
                 .optional()
-                .describe("When true, create another isolated managed worktree instead of reusing the existing worktree for this project and baseRef. Use only when the user explicitly requests a separate worktree."),
+                .describe("When true, create another isolated managed Git worktree instead of reusing the existing physical worktree. Use only when the user explicitly requests separate Git isolation."),
+            newWorkspace: z
+                .boolean()
+                .optional()
+                .describe("When true, allocate a fresh logical workspaceId for the same physical checkout or worktree and bind this conversation to it. Use only after the user explicitly requests a new logical workspace."),
         },
         outputSchema: {
             workspaceId: z.string(),
@@ -597,6 +705,16 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 managed: z.boolean(),
                 current: z.boolean(),
             })),
+            staleWorkspaces: z.array(z.object({
+                workspaceId: z.string(),
+                root: z.string(),
+                mode: z.enum(["checkout", "worktree"]),
+                lastUsedAt: z.string(),
+                idleMs: z.number().nonnegative(),
+                branch: z.string().optional(),
+                targetBranch: z.string().optional(),
+                managed: z.boolean(),
+            })),
             agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
             availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
             skills: z.array(workspaceSkillOutputSchema).optional(),
@@ -612,10 +730,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ path, mode, baseRef, newWorktree }, { _meta, sessionId }) => {
+    }, async ({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace }, { _meta, sessionId }) => {
         const startedAt = performance.now();
-        const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, } = await workspaces.openWorkspace({ path, mode, baseRef, newWorktree }, { conversationScopeId: openAiConversationScopeId(_meta) });
+        const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace }, {
+            conversationScopeId: openAiConversationScopeId(_meta),
+            protectedWorkspaceIds: processSessions.activeWorkspaceIds(),
+        });
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
+        const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
         if (config.widgets === "changes") {
             await reviewCheckpoints.initializeWorkspace({
                 workspaceId: workspace.id,
@@ -701,6 +823,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     knownWorktrees.length > 0
                         ? `Known worktrees: ${knownWorktrees.map((worktree) => `${worktree.path} [${worktree.workspaceId}]${worktree.branch ? ` branch=${worktree.branch}` : ""}${worktree.targetBranch ? ` target=${worktree.targetBranch}` : ""}${worktree.current ? " (current)" : ""}`).join(", ")}`
                         : undefined,
+                    staleWorkspaces.length > 0
+                        ? `Idle logical workspaces for this same physical workspace (>2 days): ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. Tell the user these are available to resume or explicitly close; do not clean them up automatically.`
+                        : undefined,
                     instruction,
                 ].filter(Boolean).join("\n"),
             },
@@ -712,7 +837,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             success: true,
             durationMs: Math.round(performance.now() - startedAt),
         });
-        return attachHookReports({
+        return hooks.decorateResult(workspace.id, attachHookReports({
             content: resultContent,
             _meta: {
                 tool: "open_workspace",
@@ -726,6 +851,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     sourceRoot: workspace.sourceRoot,
                     worktree: workspace.worktree,
                     worktrees: knownWorktrees,
+                    staleWorkspaces,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -749,6 +875,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 sourceRoot: workspace.sourceRoot,
                 worktree: workspace.worktree,
                 worktrees: knownWorktrees,
+                staleWorkspaces,
                 ...(includeBootstrapContext
                     ? {
                         agentsFiles: loadedAgentsFiles,
@@ -761,7 +888,35 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     : {}),
                 instruction,
             },
-        }, hookReports);
+        }, hookReports));
+    });
+    registerAppTool(server, toolNames.closeWorkspace, {
+        title: "Close logical workspace",
+        description: "Release one logical ForgeRelay workspaceId after the user explicitly chooses to clean it up. This never deletes checkout files. A worktree handle can be released only when another logical handle still anchors the same physical worktree; use close_worktree to finalize and remove the last managed worktree. Running or unconsumed background processes prevent closure.",
+        inputSchema: {
+            workspaceId: z.string().describe("Logical workspace ID to release."),
+        },
+        outputSchema: resultOutputSchema({ workspaceId: z.string() }),
+        _meta: {},
+        annotations: WRITE_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId }) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.closeWorkspace,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { workspaceId },
+            operation: async () => {
+                if (processSessions.activeWorkspaceIds().has(workspaceId)) {
+                    throw new Error(`Workspace ${workspaceId} still owns a running process or an unconsumed process completion. Poll or consume it before closing this workspace.`);
+                }
+                workspaces.closeWorkspace(workspaceId);
+                const result = `Closed logical workspace ${workspaceId}. Physical project files were not removed.`;
+                return {
+                    content: [textBlock(result)],
+                    structuredContent: { result, workspaceId },
+                };
+            },
+        });
     });
     registerAppTool(server, toolNames.closeWorktree, {
         title: "Close worktree",
@@ -795,6 +950,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             payload: { commitMessage },
             afterCwd: (response) => response.structuredContent.sourceRoot,
             operation: async () => {
+                const busyWorkspaceIds = workspaces
+                    .workspaceIdsForPhysicalWorkspace(workspace)
+                    .filter((id) => processSessions.activeWorkspaceIds().has(id));
+                if (busyWorkspaceIds.length > 0) {
+                    throw new Error(`Cannot close this worktree while logical workspace processes are still running or awaiting completion delivery: ${busyWorkspaceIds.join(", ")}.`);
+                }
                 const startedAt = performance.now();
                 const closed = await workspaces.closeWorktree(workspaceId, commitMessage);
                 const result = [
@@ -840,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()
@@ -1554,80 +1715,57 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     .string()
                     .optional()
                     .describe("Optional working directory relative to the workspace root. Defaults to the workspace root."),
-                timeout: z
-                    .number()
-                    .positive()
-                    .max(300)
-                    .optional()
-                    .describe("Timeout in seconds. Defaults to 30, max 300."),
             },
-            outputSchema: resultOutputSchema(),
+            outputSchema: processOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "shell"),
             annotations: SHELL_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, workingDirectory, ...input }, extra) => {
+        }, async ({ workspaceId, command, workingDirectory }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.shell,
                 invocation: workspaceHookInvocation(workspace),
                 payload: {
-                    command: input.command,
+                    command,
                     workingDirectory: workingDirectory ?? ".",
-                    timeoutSeconds: input.timeout,
                 },
                 isFailure: toolResultIsError,
                 operation: async () => {
                     const startedAt = performance.now();
                     const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
-                    const response = await runShellTool(input, {
+                    const snapshot = await processSessions.start({
+                        workspaceId,
+                        command,
                         cwd,
-                        root: workspace.root,
+                        workspaceRoot: workspace.root,
+                        yieldTimeMs: 300_000,
                     });
-                    if (response.isError) {
-                        logFailedToolResponse(config, {
-                            tool: toolNames.shell,
-                            ...workspaceLogContext(workspace, extra.sessionId),
-                            workingDirectory: workingDirectory ?? ".",
-                            command: input.command,
-                            commandLength: input.command.length,
-                        }, response.content, startedAt);
-                        return response;
-                    }
-                    const summary = {
-                        command: input.command,
-                        workingDirectory: workingDirectory ?? ".",
-                        ...textSummary(response.content),
-                    };
                     logToolCall(config, {
                         tool: toolNames.shell,
                         ...workspaceLogContext(workspace, extra.sessionId),
                         workingDirectory: workingDirectory ?? ".",
-                        command: input.command,
-                        commandLength: input.command.length,
-                        success: true,
+                        command,
+                        commandLength: command.length,
+                        exitCode: snapshot.exitCode,
+                        running: snapshot.running,
+                        processSessionId: snapshot.sessionId,
+                        success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
                         durationMs: Math.round(performance.now() - startedAt),
                     });
-                    return {
-                        ...response,
-                        _meta: {
-                            tool: toolNames.shell,
-                            card: {
-                                workspaceId,
-                                path: workingDirectory,
-                                summary,
-                                payload: { content: response.content },
-                            },
-                        },
-                        structuredContent: {
-                            result: contentText(response.content),
-                        },
-                    };
+                    const response = processToolResponse(toolNames.shell, workspaceId, snapshot, {
+                        command,
+                        workingDirectory: workingDirectory ?? ".",
+                        running: snapshot.running,
+                        exitCode: snapshot.exitCode,
+                        wallTimeMs: snapshot.wallTimeMs,
+                    });
+                    return !snapshot.running && (snapshot.signal || snapshot.exitCode !== 0)
+                        ? { ...response, isError: true }
+                        : response;
                 },
             });
         });
     }
-    if (config.toolMode === "codex") {
-        registerCodexProcessTools(server, config, workspaces, processSessions, hooks);
-    }
+    registerProcessTools(server, config, workspaces, processSessions, hooks);
     if (config.artifactsEnabled && isArtifactDownloadSupportedPlatform()) {
         registerArtifactTools(server, {
             config,
@@ -1665,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", {
@@ -1676,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,
             });
         }
     };
@@ -1760,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;
@@ -1780,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),
@@ -1790,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),
                         });