@akira-tl/forgerelay 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.5] - 2026-08-31
+
+### Added
+
+- Added source-controlled GitHub Wiki pages with validation and publishing tooling.
+
+### Changed
+
+- Relayed checkout and managed-worktree Workspaces now preserve stable Gateway identity and Execution-owned Task/lifecycle semantics across close, reopen, delete, inspection, and Composite member routing.
+
+### Fixed
+
+- Task reminders and relayed/Composite runtime state now survive independent MCP transport sessions instead of resetting or presenting stale session-local state.
+- Managed-worktree Relay acceptance now tolerates Git-native LF/CRLF checkout normalization, keeping the release matrix portable across Linux, macOS, and Windows.
+
 ## [0.8.4] - 2026-08-31
 
 ### Added

package/README.md

@@ -348,6 +348,7 @@ Trusted Publishing setup.
 
 ## Documentation
 
+- [GitHub Wiki](https://github.com/Akira-TL/forgerelay/wiki) — 面向用户的使用指南、概念说明与故障排查入口。
 - [Setup Guide](docs/setup.md)
 - [Local Debugging and 7677 Acceptance](docs/debugging.md)
 - [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
@@ -358,6 +359,7 @@ Trusted Publishing setup.
 - [Troubleshooting](docs/gotchas.md)
 - [Roadmap](docs/roadmap.md)
 - [Versioning and Release Management](docs/versioning.md)
+- [GitHub Wiki Maintenance](docs/maintenance/wiki.md)
 - [Changelog](CHANGELOG.md)
 - [Attribution Notice](NOTICE.md)
 

package/dist/remote-workspace-relay.js

@@ -27,20 +27,57 @@ export class RemoteWorkspaceRelay {
         this.loadRoutes();
         return this.routes.has(workspaceId);
     }
-    inspectWorkspace(gatewayWorkspaceId) {
+    async inspectWorkspace(gatewayWorkspaceId) {
         const route = this.requireRoute(gatewayWorkspaceId);
         const resolved = this.remoteByInstance(route.remoteInstanceId);
-        return {
+        let result;
+        try {
+            result = await this.callRemoteTool(resolved.alias, resolved.remote, "open_workspace", {
+                action: "inspect",
+                workspaceId: route.remoteWorkspaceId,
+            });
+            assertRemoteToolSucceeded(resolved.alias, "open_workspace", result);
+        }
+        catch (error) {
+            throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
+        }
+        const structured = result.structuredContent;
+        const remoteInspection = structured?.inspection;
+        if (!remoteInspection || remoteInspection.kind !== "workspace") {
+            throw new Error(`Remote ForgeRelay ${resolved.alias} inspection did not return a Workspace projection.`);
+        }
+        const root = stringField(remoteInspection, "root", "Remote Workspace inspection");
+        const mode = remoteInspection.mode;
+        if (mode !== "checkout" && mode !== "worktree") {
+            throw new Error(`Remote ForgeRelay ${resolved.alias} inspection did not return a valid Workspace mode.`);
+        }
+        const projection = {
             workspaceId: route.gatewayWorkspaceId,
             kind: "workspace",
             location: "relay",
-            root: route.root,
+            root,
             routeState: "known",
-            mode: route.mode,
-            ...(route.sourceRoot ? { sourceRoot: route.sourceRoot } : {}),
+            mode,
             relay: resolved.alias,
             executionLocation: `remote:${resolved.alias}`,
         };
+        copyStringField(remoteInspection, projection, "status");
+        const state = remoteInspection.state;
+        if (state === "active" || state === "stale" || state === "invalid" || state === "closed") {
+            projection.state = state;
+        }
+        copyStringField(remoteInspection, projection, "sourceRoot");
+        copyStringField(remoteInspection, projection, "branch");
+        copyStringField(remoteInspection, projection, "targetBranch");
+        copyBooleanField(remoteInspection, projection, "managed");
+        copyStringField(remoteInspection, projection, "createdAt");
+        copyStringField(remoteInspection, projection, "lastUsedAt");
+        copyNumberField(remoteInspection, projection, "idleMs");
+        copyBooleanField(remoteInspection, projection, "rootValid");
+        const taskSummary = safeTaskSummary(remoteInspection.taskSummary);
+        if (taskSummary)
+            projection.taskSummary = taskSummary;
+        return projection;
     }
     async openWorkspace(alias, input, conversationScopeId) {
         const resolved = this.remoteByAlias(alias);
@@ -66,18 +103,15 @@ export class RemoteWorkspaceRelay {
         if (mode !== "checkout" && mode !== "worktree") {
             throw new Error("Remote open_workspace response did not include a valid workspace mode.");
         }
-        const gatewayWorkspaceId = this.allocateGatewayWorkspaceId();
         const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : undefined;
-        const route = {
-            gatewayWorkspaceId,
+        const route = this.findOrCreateRoute({
             remoteInstanceId: resolved.remote.instanceId,
             remoteWorkspaceId,
             root,
             mode,
             ...(sourceRoot ? { sourceRoot } : {}),
-        };
-        this.routes.set(gatewayWorkspaceId, route);
-        this.persistRoute(route);
+        });
+        const gatewayWorkspaceId = route.gatewayWorkspaceId;
         const remapContext = (value) => replaceExactWorkspaceId(value, remoteWorkspaceId, gatewayWorkspaceId);
         const remoteInstruction = typeof structured?.instruction === "string"
             ? String(remapContext(structured.instruction))
@@ -117,10 +151,24 @@ export class RemoteWorkspaceRelay {
         };
     }
     async resumeWorkspace(gatewayWorkspaceId, context = "auto", conversationScopeId) {
+        const route = this.requireRoute(gatewayWorkspaceId);
         const result = await this.callWorkspaceTool(gatewayWorkspaceId, "open_workspace", { context }, conversationScopeId);
         if (result.isError === true) {
             throw new Error(`Remote open_workspace failed: ${toolResultText(result)}`);
         }
+        const structured = result.structuredContent;
+        const root = typeof structured?.root === "string" ? structured.root : route.root;
+        const mode = structured?.mode === "checkout" || structured?.mode === "worktree"
+            ? structured.mode
+            : route.mode;
+        const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : route.sourceRoot;
+        this.findOrCreateRoute({
+            remoteInstanceId: route.remoteInstanceId,
+            remoteWorkspaceId: route.remoteWorkspaceId,
+            root,
+            mode,
+            ...(sourceRoot ? { sourceRoot } : {}),
+        });
         return result;
     }
     async read(gatewayWorkspaceId, input, conversationScopeId) {
@@ -221,14 +269,16 @@ export class RemoteWorkspaceRelay {
             throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
         }
     }
-    async closeWorkspace(gatewayWorkspaceId, commitMessage, conversationScopeId) {
+    async closeWorkspace(gatewayWorkspaceId, input = {}, conversationScopeId) {
         const route = this.requireRoute(gatewayWorkspaceId);
         const resolved = this.remoteByInstance(route.remoteInstanceId);
+        const action = input.action ?? "close";
         let result;
         try {
             result = await this.callRemoteTool(resolved.alias, resolved.remote, "close_workspace", {
                 workspaceId: route.remoteWorkspaceId,
-                ...(commitMessage !== undefined ? { commitMessage } : {}),
+                action,
+                ...(input.commitMessage !== undefined ? { commitMessage: input.commitMessage } : {}),
             }, conversationScopeId);
             assertRemoteToolSucceeded(resolved.alias, "close_workspace", result);
         }
@@ -236,21 +286,26 @@ export class RemoteWorkspaceRelay {
             throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
         }
         const remoteStructured = result.structuredContent;
-        this.routes.delete(gatewayWorkspaceId);
-        this.deletePersistedRoute(gatewayWorkspaceId);
+        if (action === "delete") {
+            this.routes.delete(gatewayWorkspaceId);
+            this.deletePersistedRoute(gatewayWorkspaceId);
+        }
         for (const [turnId, routedWorkspaceId] of this.turnRoutes) {
             if (routedWorkspaceId === gatewayWorkspaceId)
                 this.turnRoutes.delete(turnId);
         }
+        const actionText = action === "delete" ? "Deleted" : "Closed";
         const text = route.mode === "worktree"
-            ? `Closed relayed worktree workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`
-            : `Closed relayed checkout workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`;
+            ? `${actionText} relayed worktree workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`
+            : `${actionText} relayed checkout workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`;
         const structuredContent = {
             result: text,
             workspaceId: gatewayWorkspaceId,
+            action,
             mode: route.mode,
         };
         for (const field of [
+            "status",
             "sourceRoot",
             "branch",
             "targetBranch",
@@ -270,6 +325,7 @@ export class RemoteWorkspaceRelay {
                 tool: "close_workspace",
                 card: {
                     workspaceId: gatewayWorkspaceId,
+                    action,
                     mode: route.mode,
                     payload: { content: [{ type: "text", text }] },
                 },
@@ -292,10 +348,26 @@ export class RemoteWorkspaceRelay {
             this.routes.set(workspaceId, route);
         }
     }
-    persistRoute(route) {
-        this.updatePersistedRoutes((routes) => {
-            routes.set(route.gatewayWorkspaceId, route);
+    findOrCreateRoute(input) {
+        let selected;
+        mkdirSync(this.routeStateDir, { recursive: true });
+        this.withRouteFileLock(() => {
+            const routes = this.readRoutesFromDisk();
+            const existing = [...routes.values()]
+                .filter((route) => route.remoteInstanceId === input.remoteInstanceId &&
+                route.remoteWorkspaceId === input.remoteWorkspaceId)
+                .sort((left, right) => left.gatewayWorkspaceId.localeCompare(right.gatewayWorkspaceId))[0];
+            selected = {
+                gatewayWorkspaceId: existing?.gatewayWorkspaceId ?? this.allocateGatewayWorkspaceId(routes),
+                ...input,
+            };
+            routes.set(selected.gatewayWorkspaceId, selected);
+            this.writeRoutesToDisk(routes);
         });
+        if (!selected)
+            throw new Error("Failed to persist relayed Workspace route.");
+        this.routes.set(selected.gatewayWorkspaceId, selected);
+        return selected;
     }
     deletePersistedRoute(workspaceId) {
         this.updatePersistedRoutes((routes) => {
@@ -423,11 +495,11 @@ export class RemoteWorkspaceRelay {
         writeForgeRelayRemote(alias, refreshed, this.authEnv);
         return refreshed;
     }
-    allocateGatewayWorkspaceId() {
+    allocateGatewayWorkspaceId(routes = this.routes) {
         let workspaceId;
         do {
             workspaceId = `rws_${randomBytes(5).toString("hex")}`;
-        } while (this.routes.has(workspaceId));
+        } while (routes.has(workspaceId));
         return workspaceId;
     }
 }
@@ -443,6 +515,62 @@ function stringField(structured, field, label) {
     }
     return value;
 }
+function copyStringField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "string")
+        target[field] = value;
+}
+function copyBooleanField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "boolean")
+        target[field] = value;
+}
+function copyNumberField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        target[field] = value;
+}
+function safeTaskSummary(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const summary = value;
+    if (summary.level !== "summary" ||
+        summary.version !== 1 ||
+        typeof summary.revision !== "number" ||
+        !Number.isInteger(summary.revision) ||
+        summary.revision < 0 ||
+        !Array.isArray(summary.lists)) {
+        return undefined;
+    }
+    const lists = [];
+    for (const value of summary.lists) {
+        if (!value || typeof value !== "object")
+            return undefined;
+        const list = value;
+        if (typeof list.id !== "string" ||
+            typeof list.name !== "string" ||
+            (list.state !== "active" && list.state !== "archived") ||
+            typeof list.revision !== "number" || !Number.isInteger(list.revision) || list.revision <= 0 ||
+            typeof list.taskCount !== "number" || !Number.isInteger(list.taskCount) || list.taskCount < 0 ||
+            typeof list.unfinishedTaskCount !== "number" || !Number.isInteger(list.unfinishedTaskCount) || list.unfinishedTaskCount < 0) {
+            return undefined;
+        }
+        lists.push({
+            id: list.id,
+            name: list.name,
+            state: list.state,
+            revision: list.revision,
+            taskCount: list.taskCount,
+            unfinishedTaskCount: list.unfinishedTaskCount,
+        });
+    }
+    return {
+        level: "summary",
+        version: 1,
+        revision: summary.revision,
+        lists,
+    };
+}
 function toolResultText(result) {
     return (result.content ?? [])
         .filter((entry) => entry.type === "text")

package/dist/server.js

@@ -311,8 +311,18 @@ const workspaceInspectionOutputSchema = z.union([
         location: z.literal("relay"),
         root: z.string(),
         routeState: z.literal("known"),
+        status: z.string().optional(),
+        state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
         mode: z.enum(["checkout", "worktree"]),
         sourceRoot: z.string().optional(),
+        branch: z.string().optional(),
+        targetBranch: z.string().optional(),
+        managed: z.boolean().optional(),
+        createdAt: z.string().optional(),
+        lastUsedAt: z.string().optional(),
+        idleMs: z.number().nonnegative().optional(),
+        rootValid: z.boolean().optional(),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
         relay: z.string(),
         executionLocation: z.string(),
     }),
@@ -1332,10 +1342,13 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
 }
 export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, subagentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle, bashOutputStore, activityQueries, options = {}) {
     const connectionScopeId = `mcp-connection:${randomUUID()}`;
-    const remoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
-    const compositeWorkspaces = new CompositeWorkspaceRegistry(config.stateDir);
+    const remoteWorkspaces = options.remoteWorkspaces
+        ?? new RemoteWorkspaceRelay(config.configDir, config.stateDir);
+    const compositeWorkspaces = options.compositeWorkspaces
+        ?? new CompositeWorkspaceRegistry(config.stateDir);
     const workspaceTasks = new WorkspaceTaskStore(config.stateDir);
-    const taskReminders = new WorkspaceTaskReminderTracker(config.taskReminderInterval, workspaceTasks);
+    const taskReminders = options.taskReminders
+        ?? new WorkspaceTaskReminderTracker(config.taskReminderInterval, workspaceTasks);
     const compositeTaskGuides = loadCapabilityGuides(config).filter((guide) => guide.name === "workspace-tasks");
     const compositeActivity = new CompositeActivityCoordinator(compositeWorkspaces, activityQueries, remoteWorkspaces);
     const resolveExecutionTarget = (workspaceId, memberName) => {
@@ -2349,16 +2362,29 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         };
         const inspectCompositeMember = async (entry) => {
             if (remoteWorkspaces.has(entry.workspaceId)) {
-                const inspected = remoteWorkspaces.inspectWorkspace(entry.workspaceId);
-                return {
-                    name: entry.name,
-                    purpose: entry.purpose,
-                    workspaceId: entry.workspaceId,
-                    known: true,
-                    location: inspected.location,
-                    routeState: inspected.routeState,
-                    mode: inspected.mode,
-                };
+                try {
+                    const inspected = await remoteWorkspaces.inspectWorkspace(entry.workspaceId);
+                    return {
+                        name: entry.name,
+                        purpose: entry.purpose,
+                        workspaceId: entry.workspaceId,
+                        known: true,
+                        location: inspected.location,
+                        routeState: inspected.routeState,
+                        state: inspected.state,
+                        status: inspected.status,
+                        mode: inspected.mode,
+                        rootValid: inspected.rootValid,
+                    };
+                }
+                catch {
+                    return {
+                        name: entry.name,
+                        purpose: entry.purpose,
+                        workspaceId: entry.workspaceId,
+                        known: false,
+                    };
+                }
             }
             try {
                 const inspected = await workspaces.inspectWorkspace(entry.workspaceId);
@@ -2412,7 +2438,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 };
             }
             else if (remoteWorkspaces.has(workspaceId)) {
-                inspection = remoteWorkspaces.inspectWorkspace(workspaceId);
+                inspection = await remoteWorkspaces.inspectWorkspace(workspaceId);
             }
             else {
                 const inspected = await workspaces.inspectWorkspace(workspaceId);
@@ -2428,9 +2454,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 inspection.kind === "composite"
                     ? `State: ${inspection.state}; members=${inspection.members.length}.`
                     : inspection.location === "relay"
-                        ? `Route: ${inspection.routeState}; mode=${inspection.mode}; location=${inspection.location}. Remote lifecycle is not probed by inspection.`
+                        ? inspection.state
+                            ? `State: ${inspection.state}; route=${inspection.routeState}; mode=${inspection.mode}; location=${inspection.location}. Lifecycle and Task facts come from the Execution ForgeRelay.`
+                            : `Route: ${inspection.routeState}; mode=${inspection.mode}; location=${inspection.location}.`
                         : `State: ${inspection.state}; mode=${inspection.mode}; location=${inspection.location}.`,
-                "Task summary is included only when durable local Task state already exists; Task bodies are never returned.",
+                "Task summary is included only when durable Task state already exists on the owning Workspace; Task bodies are never returned.",
                 instruction,
             ].join("\n");
             logToolCall(config, {
@@ -2754,10 +2782,16 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         if (name !== undefined || memberName !== undefined) {
             throw new Error("open_workspace name/memberName are only valid for a Composite Workspace.");
         }
-        if (relay !== undefined) {
-            if (workspaceId !== undefined) {
-                throw new Error("Relayed open_workspace requires a path; resuming a relayed workspace is not available in this tracer bullet.");
+        if (workspaceId !== undefined && remoteWorkspaces.has(workspaceId)) {
+            if (path !== undefined || relay !== undefined || mode !== undefined || baseRef !== undefined ||
+                newWorktree !== undefined || newWorkspace !== undefined) {
+                throw new Error("Resuming a relayed Workspace by workspaceId accepts context only.");
             }
+            const resumed = await remoteWorkspaces.resumeWorkspace(workspaceId, context ?? "auto", hostScopeIdFor(_meta, sessionId));
+            rememberWorkspacePanelState(workspaceId, resumed);
+            return resumed;
+        }
+        if (relay !== undefined) {
             if (!path)
                 throw new Error("Relayed open_workspace requires path.");
             const opened = await remoteWorkspaces.openWorkspace(relay, {
@@ -3306,7 +3340,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close workspace",
-        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout, managed-worktree, and Composite identity for later reopen. action=delete permanently removes ForgeRelay-owned state. Managed-worktree-backed Workspaces still finalize safely when active and require commitMessage. Composite delete dissolves only Composite-owned state and never closes member Workspaces. Checkout project files are never deleted; relayed delete remains unavailable.",
+        description: "Close or explicitly delete one Workspace after the user chooses cleanup. action=close (default) preserves checkout, managed-worktree, Composite, and relayed identity for later reopen. action=delete permanently removes ForgeRelay-owned state. Managed-worktree-backed Workspaces still finalize safely when active and require commitMessage. Composite delete dissolves only Composite-owned state and never closes member Workspaces. Checkout project files are never deleted.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier to close or delete."),
             action: z
@@ -3393,10 +3427,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             };
         }
         if (remoteWorkspaces.has(workspaceId)) {
-            if (action === "delete") {
-                throw new Error("close_workspace action=delete is not available for relayed Workspaces until Workspace Relay lifecycle parity is implemented.");
-            }
-            const response = await remoteWorkspaces.closeWorkspace(workspaceId, commitMessage, hostScopeIdFor(extra._meta, extra.sessionId));
+            const response = await remoteWorkspaces.closeWorkspace(workspaceId, { action, ...(commitMessage !== undefined ? { commitMessage } : {}) }, hostScopeIdFor(extra._meta, extra.sessionId));
             workspacePanelStates.delete(workspaceId);
             return response;
         }
@@ -4226,6 +4257,10 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     const workspaceStore = createWorkspaceStore(config.stateDir);
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
+    const sharedRemoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
+    const sharedCompositeWorkspaces = new CompositeWorkspaceRegistry(config.stateDir);
+    const sharedWorkspaceTasks = new WorkspaceTaskStore(config.stateDir);
+    const sharedTaskReminders = new WorkspaceTaskReminderTracker(config.taskReminderInterval, sharedWorkspaceTasks);
     const activityAuditStore = new ActivityAuditStore(config.stateDir);
     const bashOutputStore = new BashOutputStore(config.stateDir);
     const hostTurnStore = new HostTurnStore(config.stateDir);
@@ -4420,7 +4455,11 @@ export function createServer(config = loadConfig(), options = {}) {
                         });
                     }
                 };
-                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, subagentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle, bashOutputStore, activityQueries);
+                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, subagentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle, bashOutputStore, activityQueries, {
+                    taskReminders: sharedTaskReminders,
+                    remoteWorkspaces: sharedRemoteWorkspaces,
+                    compositeWorkspaces: sharedCompositeWorkspaces,
+                });
                 await server.connect(transport);
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -40,7 +40,10 @@
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
     "debug:accept": "node scripts/debug/accept.mjs",
+    "debug:accept:relay": "node scripts/debug/relay-accept.mjs",
     "lsp:interop": "node scripts/lsp-interop.mjs",
+    "wiki:check": "node scripts/wiki/sync.mjs check",
+    "wiki:publish": "node scripts/wiki/sync.mjs publish",
     "ci:verify": "node scripts/ci/verify.mjs",
     "release:parity": "node scripts/release-parity.mjs",
     "release:pack": "node scripts/release/pack.mjs",