@akira-tl/forgerelay 0.2.2 → 0.2.4

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,24 @@ 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
+that write files. The Agent contract still prohibits shell mutation of
+security- or privilege-sensitive operating-system files and credential material,
+and requires an explicit user request before changing configuration files
+through `bash` or `exec_command`.
+
 ## Change review UI
 
 By default `FORGERELAY_WIDGETS=full` attaches ChatGPT Apps-compatible UI to the

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.

package/docs/debugging.md

@@ -58,9 +58,9 @@ The acceptance checks:
 2. OAuth protected-resource and authorization-server discovery;
 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;
-6. `tools/list` for the full debug tool surface;
-7. a real checkout workspace with `write`, `read`, `rename`, `delete`, `bash`, and a deliberate failed `edit`;
+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`；

package/docs/security.md

@@ -97,6 +97,21 @@ repositories, local services, and other resources outside a narrow workspace
 sandbox, and MCP currently does not provide a clean universal interaction model
 for dynamically crossing such a boundary.
 
+The Agent-facing shell contract therefore does not ban every command that can
+change files. Commands may modify ordinary project files when that is a natural
+part of the user's requested development task, including package managers,
+generators, formatters, and similar tooling. The contract does prohibit shell
+mutation of security- or privilege-sensitive operating-system files and
+credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, PAM or
+authentication policy, SSH private keys, and equivalent privileged targets.
+Configuration files may be changed through shell only when the user's request
+explicitly calls for that configuration change rather than merely making it a
+convenient implementation detail.
+
+This is an Agent execution policy, not an OS-level sandbox or command parser.
+Operators that need a stronger project-specific runtime gate can use blocking
+`BeforeTool` Hooks around `bash` or `exec_command`.
+
 The security model is therefore based on:
 
 - strong authentication;
@@ -107,6 +122,16 @@ The security model is therefore based on:
 
 Do not describe ForgeRelay as a sandboxed coding environment.
 
+Shell execution has a 300-second foreground wait ceiling, not a 300-second
+process lifetime. When `bash` is still running after that window, ForgeRelay
+returns a process `sessionId` and leaves the process alive. `write_stdin` can poll,
+wait, interact, or explicitly interrupt it. An asynchronously completed process
+is reported on a later tool result for the same logical workspace ID, including
+error-result paths, and is never broadcast to another workspace ID. Explicitly
+resuming the same workspace ID in another conversation intentionally transfers
+that completion scope as well. Hook handlers keep their separate bounded timeout
+policy because they are lifecycle gates rather than user-command execution.
+
 ## Lifecycle hooks
 
 Hook command 是本地代码执行，使用与 ForgeRelay 相同的操作系统用户权限并继承进程环境。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -83,6 +83,11 @@ try {
   assert.equal(initialized.message.result.serverInfo.name, "forgerelay");
   assert.equal(initialized.message.result.serverInfo.title, "ForgeRelay");
   assert.equal(initialized.message.result.serverInfo.version, packageJson.version);
+  const serverInstructions = initialized.message.result.instructions ?? "";
+  assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
+  assert.match(serverInstructions, /\/etc\/sudoers/);
+  assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
+  assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
   pass(
     "MCP initialize",
     JSON.stringify(initialized.message.result.serverInfo),
@@ -103,9 +108,22 @@ try {
     params: {},
   }).message.result.tools;
   const toolNames = tools.map((tool) => tool.name);
-  for (const expected of ["open_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash"]) {
+  for (const expected of ["open_workspace", "close_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "write_stdin"]) {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
+  const bashTool = tools.find((tool) => tool.name === "bash");
+  assert.match(bashTool?.description ?? "", /may modify ordinary project files/);
+  assert.match(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
+  assert.equal(bashTool?.inputSchema?.properties?.timeout, undefined);
+  assert.match(bashTool?.description ?? "", /waits up to 300 seconds/);
+  assert.match(bashTool?.description ?? "", /write_stdin/);
+  const writeStdinTool = tools.find((tool) => tool.name === "write_stdin");
+  assert.equal(writeStdinTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
+  const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
+  assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
+  assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
@@ -136,7 +154,8 @@ try {
     command: "printf debug-bash-ok",
   });
   assert.match(shell.structuredContent.result, /debug-bash-ok/);
-  pass("bash", "debug-bash-ok");
+  assert.equal(shell.structuredContent.running, false);
+  pass("bash", "foreground command completed through ProcessSessionManager");
 
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,