@akira-tl/forgerelay 0.2.3 → 0.2.5

package/dist/workspace-store.js

@@ -79,6 +79,19 @@ export class SqliteWorkspaceStore {
                 : query.where(and(...conditions)).all();
         return rows.map(rowToWorkspaceSession);
     }
+    deleteSession(id) {
+        this.database.db
+            .delete(workspaceSessions)
+            .where(eq(workspaceSessions.id, id))
+            .run();
+    }
+    listConversationBindings() {
+        return this.database.db
+            .select()
+            .from(workspaceConversationBindings)
+            .all()
+            .map(rowToWorkspaceConversationBinding);
+    }
     getConversationBinding(conversationScopeId, targetKey) {
         const row = this.database.db
             .select()

package/dist/workspaces.js

@@ -7,31 +7,116 @@ import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
 import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
 import { loadLocalAgentProfiles, } from "./local-agent-profiles.js";
+const WORKSPACE_STALE_REMINDER_MS = 2 * 24 * 60 * 60 * 1_000;
+const WORKSPACE_SESSION_IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1_000;
+const WORKSPACE_GC_INTERVAL_MS = 60 * 60 * 1_000;
 export class WorkspaceRegistry {
     config;
     store;
     workspaces = new Map();
     pendingOpens = new Map();
     hooks;
+    lastWorkspaceGcAt = 0;
     constructor(config, store) {
         this.config = config;
         this.store = store;
         this.hooks = new HookRunner(config.hooks, config.logging);
+        this.pruneIdleWorkspaceSessions(new Set(), true);
     }
     async openWorkspace(input, openOptions = {}) {
+        this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
         const workspaceInput = typeof input === "string" ? { path: input } : input;
+        if (workspaceInput.workspaceId) {
+            return this.resumeWorkspace(workspaceInput.workspaceId, openOptions.conversationScopeId);
+        }
+        if (!workspaceInput.path) {
+            throw new Error("open_workspace requires either path or workspaceId.");
+        }
         const mode = workspaceInput.mode ?? "checkout";
         if (mode === "worktree") {
             return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
         }
-        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId);
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false);
+    }
+    async resumeWorkspace(workspaceId, conversationScopeId) {
+        const workspace = this.getWorkspace(workspaceId);
+        const context = await this.reusedWorkspaceContext(workspace);
+        if (!conversationScopeId || !this.store) {
+            return { ...context, includeBootstrapContext: true };
+        }
+        const targetKeys = await this.workspaceTargetKeys(workspace);
+        const alreadyBound = targetKeys.some((targetKey) => this.store?.getConversationBinding(conversationScopeId, targetKey)?.workspaceSessionId === workspace.id);
+        for (const targetKey of targetKeys) {
+            this.store.setConversationBinding({
+                conversationScopeId,
+                targetKey,
+                workspaceSessionId: workspace.id,
+            });
+        }
+        return { ...context, includeBootstrapContext: !alreadyBound };
+    }
+    async listStaleWorkspaces(workspace) {
+        if (!this.store)
+            return [];
+        const now = Date.now();
+        const workspaceRootKey = await canonicalPath(workspace.root);
+        const stale = [];
+        for (const session of this.store.listSessions({ status: "active", mode: workspace.mode })) {
+            if (session.id === workspace.id)
+                continue;
+            const lastUsedAt = Date.parse(session.lastUsedAt);
+            if (!Number.isFinite(lastUsedAt) || now - lastUsedAt < WORKSPACE_STALE_REMINDER_MS)
+                continue;
+            const root = await this.validSessionRoot(session);
+            if (!root || await canonicalPath(root) !== workspaceRootKey)
+                continue;
+            stale.push({
+                workspaceId: session.id,
+                root,
+                mode: session.mode,
+                lastUsedAt: session.lastUsedAt,
+                idleMs: now - lastUsedAt,
+                branch: session.branch,
+                targetBranch: session.targetBranch,
+                managed: session.managed,
+            });
+        }
+        return stale.sort((left, right) => left.lastUsedAt.localeCompare(right.lastUsedAt));
+    }
+    closeWorkspace(workspaceId) {
+        const workspace = this.getWorkspace(workspaceId);
+        if (workspace.mode === "worktree") {
+            const aliases = this.activeSessions("worktree")
+                .filter((session) => resolve(session.root) === resolve(workspace.root));
+            if (aliases.length <= 1) {
+                throw new Error(`Workspace ${workspaceId} is the last active handle for a worktree. Use close_worktree to finalize and remove the physical worktree, or keep this handle as its anchor.`);
+            }
+        }
+        if (this.store) {
+            for (const binding of this.store.listConversationBindings()) {
+                if (binding.workspaceSessionId === workspaceId) {
+                    this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
+                }
+            }
+            this.store.deleteSession(workspaceId);
+        }
+        this.workspaces.delete(workspaceId);
+    }
+    workspaceIdsForPhysicalWorkspace(workspace) {
+        const root = resolve(workspace.root);
+        return this.activeSessions(workspace.mode)
+            .filter((session) => resolve(session.root) === root)
+            .map((session) => session.id);
     }
     async listKnownWorktrees(workspace) {
         const sourceRoot = workspace.mode === "worktree" ? workspace.sourceRoot : workspace.root;
         if (!sourceRoot)
             return [];
         const sourceKey = await canonicalPath(sourceRoot);
-        const results = [];
+        const currentRootKey = workspace.mode === "worktree"
+            ? await canonicalPath(workspace.root)
+            : undefined;
+        const resultsByRoot = new Map();
         for (const session of this.activeSessions("worktree")) {
             if (!session.sourceRoot)
                 continue;
@@ -40,7 +125,8 @@ export class WorkspaceRegistry {
             const root = await this.validSessionRoot(session);
             if (!root)
                 continue;
-            results.push({
+            const rootKey = await canonicalPath(root);
+            const candidate = {
                 workspaceId: session.id,
                 path: root,
                 baseRef: session.baseRef ?? "HEAD",
@@ -48,10 +134,14 @@ export class WorkspaceRegistry {
                 branch: session.branch,
                 targetBranch: session.targetBranch,
                 managed: session.managed,
-                current: session.id === workspace.id,
-            });
+                current: rootKey === currentRootKey,
+            };
+            const existing = resultsByRoot.get(rootKey);
+            if (!existing || session.id === workspace.id) {
+                resultsByRoot.set(rootKey, candidate);
+            }
         }
-        return results;
+        return [...resultsByRoot.values()];
     }
     async closeWorktree(workspaceId, commitMessage) {
         const workspace = this.getWorkspace(workspaceId);
@@ -85,6 +175,9 @@ export class WorkspaceRegistry {
                 targetBranch: managedWorktree.targetBranch,
             },
         });
+        const aliasedWorkspaceIds = this.activeSessions("worktree")
+            .filter((session) => resolve(session.root) === resolve(workspace.root))
+            .map((session) => session.id);
         const result = await closeManagedWorktree({
             worktree: managedWorktree,
             commitMessage,
@@ -106,52 +199,105 @@ export class WorkspaceRegistry {
                 cleanupWarning: result.cleanupWarning,
             },
         }));
-        this.store?.setSessionStatus(workspace.id, "closed");
-        this.workspaces.delete(workspace.id);
+        for (const aliasedWorkspaceId of aliasedWorkspaceIds) {
+            this.store?.setSessionStatus(aliasedWorkspaceId, "closed");
+            this.workspaces.delete(aliasedWorkspaceId);
+        }
         return { ...result, hookReports };
     }
-    async openReusableCheckout(path, conversationScopeId) {
+    async openReusableCheckout(path, conversationScopeId, newWorkspace) {
         const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
         const projectKey = await canonicalPath(allowedPath);
         const targetKey = JSON.stringify(["checkout", projectKey, null]);
-        const context = await this.openOnce(targetKey, async () => {
+        if (!newWorkspace) {
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey);
+            if (boundContext)
+                return boundContext;
+        }
+        if (newWorkspace) {
+            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
+            const freshContext = reusableWorkspace
+                ? await this.cloneWorkspaceContext(reusableWorkspace)
+                : await this.openCheckoutWorkspace(path);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+        }
+        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
+        const context = await this.openOnce(operationKey, async () => {
             const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
-            return reusableWorkspace
-                ? this.reusedWorkspaceContext(reusableWorkspace)
-                : this.openCheckoutWorkspace(path);
+            if (!reusableWorkspace)
+                return this.openCheckoutWorkspace(path);
+            return conversationScopeId && this.store
+                ? this.cloneWorkspaceContext(reusableWorkspace)
+                : this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey);
     }
     async openReusableWorktree(input, conversationScopeId) {
-        const managedPath = this.tryManagedWorktreePath(input.path);
+        const path = input.path;
+        if (!path)
+            throw new Error("Worktree mode requires path.");
+        const managedPath = this.tryManagedWorktreePath(path);
         if (managedPath) {
             const worktreeKey = await canonicalPath(managedPath);
             const targetKey = JSON.stringify(["worktree-path", worktreeKey]);
-            const context = await this.openOnce(targetKey, async () => {
+            if (!input.newWorkspace) {
+                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey);
+                if (boundContext)
+                    return boundContext;
+            }
+            if (input.newWorkspace) {
                 const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
                 if (!reusableWorkspace) {
                     throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
                 }
-                return this.reusedWorkspaceContext(reusableWorkspace);
+                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey);
+            }
+            const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
+            const context = await this.openOnce(operationKey, async () => {
+                const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
+                if (!reusableWorkspace) {
+                    throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
+                }
+                return conversationScopeId && this.store
+                    ? this.cloneWorkspaceContext(reusableWorkspace)
+                    : this.reusedWorkspaceContext(reusableWorkspace);
             });
             return this.withConversationContext(context, conversationScopeId, targetKey);
         }
         const resolvedBase = await resolveManagedWorktreeBase({
-            sourcePath: input.path,
+            sourcePath: path,
             baseRef: input.baseRef,
             config: this.config,
         });
         const sourceKey = await canonicalPath(resolvedBase.sourceRoot);
         const targetKey = JSON.stringify(["worktree", sourceKey, resolvedBase.targetBranch]);
         if (input.newWorktree) {
-            const context = await this.openWorktreeWorkspace(input.path, input.baseRef);
+            const context = await this.openWorktreeWorkspace(path, input.baseRef);
             return this.withConversationContext(context, conversationScopeId, targetKey);
         }
-        const context = await this.openOnce(targetKey, async () => {
+        if (!input.newWorkspace) {
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session) => session.mode === "worktree" &&
+                session.sourceRoot !== undefined &&
+                await canonicalPath(session.sourceRoot) === sourceKey &&
+                session.targetBranch === resolvedBase.targetBranch);
+            if (boundContext)
+                return boundContext;
+        }
+        if (input.newWorkspace) {
+            const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
+            const freshContext = reusableWorkspace
+                ? await this.cloneWorkspaceContext(reusableWorkspace)
+                : await this.openWorktreeWorkspace(path, input.baseRef);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+        }
+        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
+        const context = await this.openOnce(operationKey, async () => {
             const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
-            return reusableWorkspace
-                ? this.reusedWorkspaceContext(reusableWorkspace)
-                : this.openWorktreeWorkspace(input.path, input.baseRef);
+            if (!reusableWorkspace)
+                return this.openWorktreeWorkspace(path, input.baseRef);
+            return conversationScopeId && this.store
+                ? this.cloneWorkspaceContext(reusableWorkspace)
+                : this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey);
     }
@@ -172,6 +318,49 @@ export class WorkspaceRegistry {
             }
         }
     }
+    async workspaceTargetKeys(workspace) {
+        if (workspace.mode === "checkout") {
+            return [JSON.stringify(["checkout", await canonicalPath(workspace.root), null])];
+        }
+        const keys = [JSON.stringify(["worktree-path", await canonicalPath(workspace.root)])];
+        if (workspace.sourceRoot && workspace.worktree?.targetBranch) {
+            keys.push(JSON.stringify([
+                "worktree",
+                await canonicalPath(workspace.sourceRoot),
+                workspace.worktree.targetBranch,
+            ]));
+        }
+        return keys;
+    }
+    conversationOpenKey(targetKey, conversationScopeId) {
+        return conversationScopeId && this.store
+            ? JSON.stringify(["conversation", conversationScopeId, targetKey])
+            : targetKey;
+    }
+    async boundConversationContext(conversationScopeId, targetKey, mode, matches) {
+        if (!conversationScopeId || !this.store)
+            return undefined;
+        const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
+        if (!binding)
+            return undefined;
+        const session = this.store.getSession(binding.workspaceSessionId);
+        if (!session || session.status !== "active" || session.mode !== mode) {
+            this.store.deleteConversationBinding(conversationScopeId, targetKey);
+            return undefined;
+        }
+        const root = await this.validSessionRoot(session);
+        if (!root) {
+            this.store.deleteConversationBinding(conversationScopeId, targetKey);
+            return undefined;
+        }
+        if (!await matches(session, root)) {
+            this.store.deleteConversationBinding(conversationScopeId, targetKey);
+            return undefined;
+        }
+        const context = await this.reusedWorkspaceContext(this.getWorkspace(session.id));
+        this.store.touchConversationBinding(conversationScopeId, targetKey);
+        return { ...context, includeBootstrapContext: false };
+    }
     withConversationContext(context, conversationScopeId, targetKey) {
         if (!conversationScopeId || !this.store) {
             return { ...context, includeBootstrapContext: true };
@@ -188,6 +377,49 @@ export class WorkspaceRegistry {
         });
         return { ...context, includeBootstrapContext: true };
     }
+    pruneIdleWorkspaceSessions(protectedWorkspaceIds, force = false) {
+        if (!this.store)
+            return;
+        const now = Date.now();
+        if (!force && now - this.lastWorkspaceGcAt < WORKSPACE_GC_INTERVAL_MS)
+            return;
+        this.lastWorkspaceGcAt = now;
+        const activeSessions = this.store.listSessions({ status: "active" });
+        const sessionsById = new Map(activeSessions.map((session) => [session.id, session]));
+        const isIdle = (session) => {
+            const lastUsedAt = Date.parse(session.lastUsedAt);
+            return Number.isFinite(lastUsedAt) && now - lastUsedAt >= WORKSPACE_SESSION_IDLE_TTL_MS;
+        };
+        for (const binding of this.store.listConversationBindings()) {
+            const session = sessionsById.get(binding.workspaceSessionId);
+            if (!session) {
+                this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
+            }
+        }
+        const boundWorkspaceIds = new Set(this.store.listConversationBindings().map((binding) => binding.workspaceSessionId));
+        const worktreeAnchors = new Map();
+        for (const session of activeSessions) {
+            if (session.mode !== "worktree")
+                continue;
+            const key = resolve(session.root);
+            const current = worktreeAnchors.get(key);
+            if (!current || current.lastUsedAt < session.lastUsedAt) {
+                worktreeAnchors.set(key, session);
+            }
+        }
+        for (const session of activeSessions) {
+            if (!isIdle(session))
+                continue;
+            if (protectedWorkspaceIds.has(session.id) || boundWorkspaceIds.has(session.id))
+                continue;
+            if (session.mode === "worktree" &&
+                worktreeAnchors.get(resolve(session.root))?.id === session.id) {
+                continue;
+            }
+            this.store.deleteSession(session.id);
+            this.workspaces.delete(session.id);
+        }
+    }
     async findReusableWorkspaceByDirectory(directoryKey, mode) {
         for (const session of this.activeSessions(mode)) {
             const root = await this.validSessionRoot(session);
@@ -195,7 +427,7 @@ export class WorkspaceRegistry {
                 continue;
             if (await canonicalPath(root) !== directoryKey)
                 continue;
-            return this.getWorkspace(session.id);
+            return this.workspaceFromSession(session, false);
         }
         return undefined;
     }
@@ -208,7 +440,7 @@ export class WorkspaceRegistry {
             const root = await this.validSessionRoot(session);
             if (!root)
                 continue;
-            return this.getWorkspace(session.id);
+            return this.workspaceFromSession(session, false);
         }
         return undefined;
     }
@@ -257,6 +489,14 @@ export class WorkspaceRegistry {
             throw error;
         }
     }
+    async cloneWorkspaceContext(workspace) {
+        return this.createWorkspaceContext({
+            root: workspace.root,
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            worktree: workspace.worktree ? { ...workspace.worktree } : undefined,
+        });
+    }
     async reusedWorkspaceContext(workspace) {
         workspace.agentProfiles = await loadLocalAgentProfiles(this.config, workspace.root);
         const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
@@ -280,6 +520,15 @@ export class WorkspaceRegistry {
         if (!session || session.status !== "active") {
             throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
         }
+        return this.workspaceFromSession(session, true);
+    }
+    workspaceFromSession(session, touch) {
+        const existing = this.workspaces.get(session.id);
+        if (existing) {
+            if (touch)
+                this.store?.touchSession(session.id);
+            return existing;
+        }
         const root = this.assertWorkspaceRootAllowed(session.root, session.mode, session.sourceRoot);
         const restoredWorkspace = {
             id: session.id,
@@ -302,7 +551,8 @@ export class WorkspaceRegistry {
             agentProfiles: [],
             activatedSkillDirs: new Set(),
         };
-        this.store?.touchSession(workspaceId);
+        if (touch)
+            this.store?.touchSession(session.id);
         this.workspaces.set(restoredWorkspace.id, restoredWorkspace);
         return restoredWorkspace;
     }

package/docs/chatgpt-coding-workflow.md

@@ -153,18 +153,25 @@ Default `FORGERELAY_TOOL_MODE=minimal` exposes:
 
 ```text
 open_workspace
+close_workspace
 read
 write
 edit
 rename
 delete
 bash
+write_stdin
 close_worktree
 ```
 
 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.
+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,
+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.
 
 `FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
 
@@ -172,6 +179,16 @@ Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
 surface including direct `rename`/`delete` path mutations alongside `apply_patch`,
 `exec_command`, and `write_stdin`.
 
+Workspace IDs are logical conversation handles rather than physical-directory
+identities. The same conversation keeps a stable ID for a project, while another
+conversation normally receives a different ID pointing at the same checkout or
+worktree. `open_workspace` can explicitly resume a known `workspaceId`, and a
+fresh logical ID is created only when the user asks for one. When a project has
+other logical workspaces idle for more than two days, `open_workspace` reports
+all of them so the user can choose to resume or clean them up. `close_workspace`
+releases only the logical handle; the last handle for a physical worktree cannot
+be released that way and must be finalized with `close_worktree`.
+
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply
 a blanket ban to package managers, generators, formatters, or similar commands

package/docs/configuration.md

@@ -115,9 +115,9 @@ MCP clients discover metadata from:
 
 | Value | Behavior |
 | --- | --- |
-| `minimal` | Default. Exposes `open_workspace`, `read`, `write`, `edit`, `rename`, `delete`, and `bash`. |
+| `minimal` | Default. Exposes `open_workspace`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, `bash`, `write_stdin`, and `close_worktree`. |
 | `full` | Adds dedicated `grep`, `glob`, and `ls` tools. |
-| `codex` | Experimental Codex-shaped tool surface using `open_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, and `write_stdin`. |
+| `codex` | Experimental Codex-shaped tool surface using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `close_worktree`. |
 
 `FORGERELAY_MINIMAL_TOOLS` remains a compatibility-style boolean alias when the
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
@@ -126,6 +126,24 @@ also accepted.
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
+Logical workspace IDs are conversation-scoped handles. Reopening the same project
+from the same conversation keeps its ID stable; a different conversation normally
+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
+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
+tool result for the same logical workspace ID.
+
 ## Widgets
 
 `FORGERELAY_WIDGETS` controls ChatGPT Apps-compatible UI attachments.
@@ -318,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 the non-blanket `bash` mutation policy;
-7. a real checkout workspace with `write`, `read`, `rename`, `delete`, `bash`, 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