@akira-tl/forgerelay 0.6.0 → 0.6.1

package/dist/server.js

@@ -45,6 +45,7 @@ import { createCoreOperationExecutor, } from "./operations/core-operation-execut
 import { McpTransportRegistry, } from "./mcp-sessions.js";
 import { ProcessManager, resolveProcessId, } from "./process-sessions.js";
 import { createReviewCheckpointManager } from "./review-checkpoints.js";
+import { RemoteWorkspaceRelay } from "./remote-workspace-relay.js";
 import { hostConversationScopeId, openAiConversationScopeId } from "./request-meta.js";
 import { ACTIVITY_PANEL_APP_LEGACY_URI, ACTIVITY_PANEL_APP_URI_TEMPLATE, MCP_APP_RESOURCE_TEMPLATE_REVISION, readActivityPanelAppManifestEntry, readWorkspaceAppManifestEntry, readWorkspaceLifecycleAppManifestEntry, resolveActivityPanelAppIdentity, resolveWorkspaceAppIdentity, resolveWorkspaceLifecycleAppIdentity, WORKSPACE_APP_LEGACY_URI, WORKSPACE_APP_URI_TEMPLATE, WORKSPACE_LIFECYCLE_APP_LEGACY_URI, WORKSPACE_LIFECYCLE_APP_URI_TEMPLATE, } from "./mcp-app-template.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
@@ -1124,6 +1125,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
 }
 export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle, bashOutputStore, activityQueries) {
     const connectionScopeId = `mcp-connection:${randomUUID()}`;
+    const remoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
     const hostScopeIdFor = (requestMeta, transportSessionId) => hostConversationScopeId(requestMeta, transportSessionId, connectionScopeId);
     const toolDescriptions = buildToolDescriptions(config);
     const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result, (snapshot) => recordBashCompletion(activityLifecycle, bashOutputStore, snapshot.outputId)));
@@ -1735,6 +1737,26 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         instructions: buildServerInstructions(config),
     });
     const workspacePanelStates = new Map();
+    const workspacePanelState = (workspaceId) => {
+        const remembered = workspacePanelStates.get(workspaceId);
+        if (remembered)
+            return remembered;
+        try {
+            const workspace = workspaces.getWorkspace(workspaceId);
+            return {
+                workspaceId: workspace.id,
+                root: workspace.root,
+                path: workspace.root,
+                mode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+                instruction: `Use workspaceId ${workspace.id} for subsequent calls.`,
+                summary: { mode: workspace.mode },
+            };
+        }
+        catch {
+            return undefined;
+        }
+    };
     const rememberWorkspacePanelState = (workspaceId, response) => {
         if (typeof response._meta !== "object" || response._meta === null)
             return;
@@ -1772,7 +1794,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     server.registerResource("ForgeRelay Activity Panel compatibility", new ResourceTemplate(ACTIVITY_PANEL_APP_URI_TEMPLATE, { list: undefined }), { ...activityPanelResourceMetadata, mimeType: RESOURCE_MIME_TYPE }, async (uri, _variables, extra) => readActivityPanelAppResource(config, uri.toString(), extra.sessionId));
     registerAppTool(server, "open_workspace", {
         title: "Open workspace",
-        description: "Open or resume a local coding workspace. Reuse the returned workspaceId for later calls. Default to checkout; use mode=\"worktree\" only when the user explicitly requests isolated or parallel Git work. Every call returns lightweight workspace metadata; bootstrap context is delivered automatically only when needed and can be explicitly suppressed or refreshed.",
+        description: "Open or resume a coding workspace. Defaults to local execution; for a new workspace, relay may name a registered direct remote ForgeRelay. Reuse the returned Gateway workspaceId for later calls. Default to checkout; use mode=\"worktree\" only for explicitly isolated or parallel Git work. Bootstrap context is delivered automatically only when needed and can be suppressed or refreshed.",
         inputSchema: {
             action: z
                 .enum(["open", "list"])
@@ -1782,6 +1804,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 .string()
                 .optional()
                 .describe("Project path to open. Required for action=open unless workspaceId is supplied. With mode=\"worktree\", this may also be a managed worktree path previously returned by ForgeRelay."),
+            relay: z
+                .string()
+                .optional()
+                .describe("Optional registered remote ForgeRelay alias. When supplied for action=open, the workspace is opened and executed on that remote instance while this Gateway returns its own workspaceId."),
             workspaceId: z
                 .string()
                 .optional()
@@ -1896,14 +1922,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ action = "open", path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context, root, status, state, staleOnly, offset, limit, }, { _meta, sessionId }) => {
+    }, async ({ action = "open", path, relay, workspaceId, mode, baseRef, newWorktree, newWorkspace, context, root, status, state, staleOnly, offset, limit, }, { _meta, sessionId }) => {
         const startedAt = performance.now();
         const conversationScopeId = openAiConversationScopeId(_meta);
         const protectedWorkspaceIds = processSessions.activeWorkspaceIds();
         if (action === "list") {
-            if (path !== undefined || baseRef !== undefined || newWorktree !== undefined ||
+            if (path !== undefined || relay !== undefined || baseRef !== undefined || newWorktree !== undefined ||
                 newWorkspace !== undefined || context !== undefined) {
-                throw new Error("open_workspace action=list does not accept path, baseRef, newWorktree, newWorkspace, or context. Use root/workspaceId/mode/status/state/staleOnly for inventory filters.");
+                throw new Error("open_workspace action=list does not accept path, relay, baseRef, newWorktree, newWorkspace, or context. Use root/workspaceId/mode/status/state/staleOnly for inventory filters.");
             }
             const inventory = await workspaces.listWorkspaces({ workspaceId, mode, root, status, state, staleOnly, offset, limit }, { conversationScopeId, protectedWorkspaceIds });
             const nextOffset = inventory.page.offset + inventory.page.limit;
@@ -1949,6 +1975,96 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             staleOnly !== undefined || offset !== undefined || limit !== undefined) {
             throw new Error("open_workspace inventory filters root, status, state, staleOnly, offset, and limit are only valid with action=list.");
         }
+        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 (!path)
+                throw new Error("Relayed open_workspace requires path.");
+            const opened = await remoteWorkspaces.openWorkspace(relay, {
+                path,
+                mode,
+                baseRef,
+                newWorktree,
+                newWorkspace,
+                context,
+            }, hostScopeIdFor(_meta, sessionId));
+            const relayedSkills = Array.isArray(opened.skills)
+                ? opened.skills
+                : [];
+            const relayedCapabilities = Array.isArray(opened.capabilityCatalog)
+                ? opened.capabilityCatalog
+                : [];
+            const result = [
+                `Opened relayed workspace ${opened.workspaceId}.`,
+                `Execution remote: ${relay}`,
+                `Root: ${opened.root}`,
+                `Mode: ${opened.mode}`,
+                relayedSkills.length > 0
+                    ? `Available skills: ${relayedSkills.map((skill) => String(skill.name ?? "")).filter(Boolean).join(", ")}`
+                    : undefined,
+                relayedCapabilities.length > 0
+                    ? `Optional capabilities: ${relayedCapabilities.map((entry) => String(entry.name ?? "")).filter(Boolean).join(", ")}`
+                    : undefined,
+                opened.instruction,
+            ].filter(Boolean).join("\n");
+            const response = {
+                content: [textBlock(result)],
+                _meta: {
+                    tool: "open_workspace",
+                    card: {
+                        workspaceId: opened.workspaceId,
+                        root: opened.root,
+                        path: opened.root,
+                        mode: opened.mode,
+                        relay,
+                        instruction: opened.instruction,
+                        summary: { mode: opened.mode, relay },
+                    },
+                },
+                structuredContent: {
+                    action: "open",
+                    workspaceId: opened.workspaceId,
+                    root: opened.root,
+                    mode: opened.mode,
+                    ...(opened.sourceRoot ? { sourceRoot: opened.sourceRoot } : {}),
+                    ...(opened.contextFingerprint !== undefined
+                        ? { contextFingerprint: opened.contextFingerprint }
+                        : {}),
+                    ...(opened.capabilityFingerprint !== undefined
+                        ? { capabilityFingerprint: opened.capabilityFingerprint }
+                        : {}),
+                    ...(opened.capabilityCatalog !== undefined
+                        ? { capabilityCatalog: opened.capabilityCatalog }
+                        : {}),
+                    ...(opened.capabilityGuides !== undefined
+                        ? { capabilityGuides: opened.capabilityGuides }
+                        : {}),
+                    ...(opened.agentsFiles !== undefined ? { agentsFiles: opened.agentsFiles } : {}),
+                    ...(opened.availableAgentsFiles !== undefined
+                        ? { availableAgentsFiles: opened.availableAgentsFiles }
+                        : {}),
+                    ...(opened.skills !== undefined ? { skills: opened.skills } : {}),
+                    ...(opened.agentProviders !== undefined
+                        ? { agentProviders: opened.agentProviders }
+                        : {}),
+                    ...(opened.agents !== undefined ? { agents: opened.agents } : {}),
+                    ...(opened.skillDiagnostics !== undefined
+                        ? { skillDiagnostics: opened.skillDiagnostics }
+                        : {}),
+                    instruction: opened.instruction,
+                },
+            };
+            logToolCall(config, {
+                tool: "open_workspace",
+                action: "relay",
+                path: opened.root,
+                success: true,
+                durationMs: Math.round(performance.now() - startedAt),
+            });
+            rememberWorkspacePanelState(opened.workspaceId, response);
+            return response;
+        }
         const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, contextFingerprint, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context }, {
             conversationScopeId,
             protectedWorkspaceIds,
@@ -2144,7 +2260,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         rememberWorkspacePanelState(workspace.id, response);
         return response;
     });
-    registerActivityQueryTools(server, activityQueries, connectionScopeId, toolWidgetDescriptorMeta(config, "activity")._meta, config.activityPanelExpanded, config.logging, (workspaceId) => workspacePanelStates.get(workspaceId));
+    registerActivityQueryTools(server, activityQueries, connectionScopeId, toolWidgetDescriptorMeta(config, "activity")._meta, config.activityPanelExpanded, config.logging, workspacePanelState, {
+        panel: async (workspaceId, conversationScopeId) => remoteWorkspaces.has(workspaceId)
+            ? remoteWorkspaces.activityPanel(workspaceId, conversationScopeId)
+            : undefined,
+        snapshot: (input, conversationScopeId) => remoteWorkspaces.activitySnapshot(input, conversationScopeId),
+        detail: (turnId, activityId, conversationScopeId) => remoteWorkspaces.activityDetail(turnId, activityId, conversationScopeId),
+        output: (turnId, outputId, conversationScopeId) => remoteWorkspaces.activityOutput(turnId, outputId, conversationScopeId),
+    });
     registerAppTool(server, toolNames.capability, {
         title: "Use optional capability",
         description: "Describe or run one optional ForgeRelay capability advertised by open_workspace. Use describe when the capability contract is unfamiliar, then read its advertised guide if needed. Run dispatches only explicitly registered capabilities; it cannot invoke arbitrary shell commands, URLs, or methods.",
@@ -2182,6 +2305,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             openWorldHint: true,
         },
     }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }, extra) => {
+        if (remoteWorkspaces.has(workspaceId)) {
+            return remoteWorkspaces.capability(workspaceId, {
+                name,
+                action,
+                ...(capabilityArguments !== undefined ? { arguments: capabilityArguments } : {}),
+                ...(file !== undefined ? { file } : {}),
+            }, hostScopeIdFor(extra._meta, extra.sessionId));
+        }
         if (action === "run" && name === "batch.execute") {
             const workspace = workspaces.getWorkspace(workspaceId);
             const startedAt = performance.now();
@@ -2318,6 +2449,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         _meta: {},
         annotations: WRITE_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, commitMessage }, extra) => {
+        if (remoteWorkspaces.has(workspaceId)) {
+            const response = await remoteWorkspaces.closeWorkspace(workspaceId, commitMessage, hostScopeIdFor(extra._meta, extra.sessionId));
+            workspacePanelStates.delete(workspaceId);
+            return response;
+        }
         const workspace = workspaces.getWorkspace(workspaceId);
         const response = await runToolWithHooks(hooks, {
             signal: extra.signal,
@@ -2470,6 +2606,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         if ((path === undefined) === (paths === undefined)) {
             throw new Error("read requires exactly one of path or paths.");
         }
+        if (remoteWorkspaces.has(workspaceId)) {
+            return remoteWorkspaces.read(workspaceId, { path, paths, offset, limit }, hostScopeIdFor(extra._meta, extra.sessionId));
+        }
         if (path !== undefined) {
             return coreOperations.read({ workspaceId, path, offset, limit }, {
                 requestMeta: extra._meta,
@@ -2548,11 +2687,16 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "write"),
             annotations: WRITE_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, ...input }, extra) => coreOperations.write({ workspaceId, ...input }, {
-            requestMeta: extra._meta,
-            signal: extra.signal,
-            sessionId: extra.sessionId,
-        }));
+        }, async ({ workspaceId, ...input }, extra) => {
+            if (remoteWorkspaces.has(workspaceId)) {
+                return remoteWorkspaces.write(workspaceId, input, hostScopeIdFor(extra._meta, extra.sessionId));
+            }
+            return coreOperations.write({ workspaceId, ...input }, {
+                requestMeta: extra._meta,
+                signal: extra.signal,
+                sessionId: extra.sessionId,
+            });
+        });
         registerAppTool(server, toolNames.edit, {
             title: "Edit file",
             description: toolDescriptions.edit,
@@ -2597,6 +2741,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             if ((path === undefined) === (paths === undefined)) {
                 throw new Error("edit requires exactly one of path or paths.");
             }
+            if (remoteWorkspaces.has(workspaceId)) {
+                return remoteWorkspaces.edit(workspaceId, { path, paths, edits }, hostScopeIdFor(extra._meta, extra.sessionId));
+            }
             if (path !== undefined) {
                 return coreOperations.edit({ workspaceId, path, edits }, {
                     requestMeta: extra._meta,
@@ -2626,11 +2773,16 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         }),
         ...toolWidgetDescriptorMeta(config, "edit"),
         annotations: EDIT_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, path, newPath }, extra) => coreOperations.rename({ workspaceId, path, newPath }, {
-        requestMeta: extra._meta,
-        signal: extra.signal,
-        sessionId: extra.sessionId,
-    }));
+    }, async ({ workspaceId, path, newPath }, extra) => {
+        if (remoteWorkspaces.has(workspaceId)) {
+            return remoteWorkspaces.rename(workspaceId, { path, newPath }, hostScopeIdFor(extra._meta, extra.sessionId));
+        }
+        return coreOperations.rename({ workspaceId, path, newPath }, {
+            requestMeta: extra._meta,
+            signal: extra.signal,
+            sessionId: extra.sessionId,
+        });
+    });
     registerAppTool(server, toolNames.delete, {
         title: "Delete path",
         description: toolDescriptions.delete,
@@ -2665,6 +2817,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         if ((path === undefined) === (paths === undefined)) {
             throw new Error("delete requires exactly one of path or paths.");
         }
+        if (remoteWorkspaces.has(workspaceId)) {
+            return remoteWorkspaces.delete(workspaceId, { path, paths, recursive }, hostScopeIdFor(extra._meta, extra.sessionId));
+        }
         if (path !== undefined) {
             return coreOperations.delete({ workspaceId, path, recursive }, {
                 requestMeta: extra._meta,
@@ -2835,6 +2990,23 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             ...toolWidgetDescriptorMeta(config, "shell"),
             annotations: SHELL_TOOL_ANNOTATIONS,
         }, async ({ workspaceId, action = "run", command, processId, outputId, input, interrupt, tty, columns, rows, workingDirectory, yieldTimeMs, timeoutMs, maxOutputTokens, }, extra) => {
+            if (remoteWorkspaces.has(workspaceId)) {
+                return remoteWorkspaces.bash(workspaceId, {
+                    action,
+                    ...(command !== undefined ? { command } : {}),
+                    ...(processId !== undefined ? { processId } : {}),
+                    ...(outputId !== undefined ? { outputId } : {}),
+                    ...(input !== undefined ? { input } : {}),
+                    ...(interrupt !== undefined ? { interrupt } : {}),
+                    ...(tty !== undefined ? { tty } : {}),
+                    ...(columns !== undefined ? { columns } : {}),
+                    ...(rows !== undefined ? { rows } : {}),
+                    ...(workingDirectory !== undefined ? { workingDirectory } : {}),
+                    ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+                }, hostScopeIdFor(extra._meta, extra.sessionId));
+            }
             const workspace = workspaces.getWorkspace(workspaceId);
             if (action === "run") {
                 if (!command)
@@ -3069,6 +3241,8 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     app.use(createForgeRelayAuthRouter({
         provider: oauthProvider,
+        cliAuthenticationProvider: oauthProvider,
+        instanceId: config.instanceId,
         issuerUrl: new URL(config.publicBaseUrl),
         resourceServerUrl,
         scopesSupported: config.oauth.scopes,

package/dist/user-config.js

@@ -1,9 +1,13 @@
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { randomBytes, randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { expandHomePath } from "./roots.js";
 import { mergeHookConfigs, parseHookFile, } from "./hooks.js";
+const AUTH_LOCK_RETRY_MS = 10;
+const AUTH_LOCK_TIMEOUT_MS = 5_000;
+const AUTH_LOCK_STALE_MS = 30_000;
+const AUTH_LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
 export function forgerelayConfigDir(env = process.env) {
     const explicit = env.FORGERELAY_CONFIG_DIR ?? env.DEVSPACE_CONFIG_DIR;
     if (explicit)
@@ -64,12 +68,81 @@ export function writeForgeRelayConfig(config, env = process.env) {
 export function writeForgeRelayAuth(auth, env = process.env) {
     const filePath = forgerelayAuthPath(env);
     mkdirSync(forgerelayConfigDir(env), { recursive: true });
-    writeJsonFile(filePath, auth, 0o600);
-    return filePath;
+    return withAuthFileLock(filePath, () => {
+        writeJsonFile(filePath, auth, 0o600);
+        return filePath;
+    });
 }
 export function generateOwnerToken() {
     return randomBytes(32).toString("base64url");
 }
+export function generateInstanceId() {
+    return `forge-${randomUUID()}`;
+}
+export function ensureForgeRelayInstanceId(env = process.env) {
+    const existing = loadForgeRelayFiles(env).auth.instanceId?.trim();
+    if (existing)
+        return existing;
+    let resolved = "";
+    updateForgeRelayAuth((auth) => {
+        const current = auth.instanceId?.trim();
+        if (current) {
+            resolved = current;
+            return auth;
+        }
+        resolved = generateInstanceId();
+        return { ...auth, instanceId: resolved };
+    }, env);
+    return resolved;
+}
+function normalizeRemoteAlias(alias) {
+    const normalized = alias.trim();
+    if (!normalized || /\s/.test(normalized)) {
+        throw new Error("Remote alias must be a non-empty name without whitespace.");
+    }
+    return normalized;
+}
+export function writeForgeRelayRemote(alias, remote, env = process.env) {
+    const normalizedAlias = normalizeRemoteAlias(alias);
+    return updateForgeRelayAuth((auth) => {
+        const remotes = { ...(auth.remotes ?? {}) };
+        const existing = remotes[normalizedAlias];
+        if (existing && existing.instanceId !== remote.instanceId) {
+            throw new Error(`Remote alias ${normalizedAlias} already belongs to another ForgeRelay instance.`);
+        }
+        const duplicate = Object.entries(remotes).find(([name, record]) => name !== normalizedAlias && record.instanceId === remote.instanceId);
+        if (duplicate) {
+            throw new Error(`ForgeRelay instance is already registered as ${duplicate[0]}; rename that remote instead.`);
+        }
+        remotes[normalizedAlias] = remote;
+        return { ...auth, remotes };
+    }, env);
+}
+export function renameForgeRelayRemote(fromAlias, toAlias, env = process.env) {
+    const from = normalizeRemoteAlias(fromAlias);
+    const to = normalizeRemoteAlias(toAlias);
+    return updateForgeRelayAuth((auth) => {
+        const remotes = { ...(auth.remotes ?? {}) };
+        const remote = remotes[from];
+        if (!remote)
+            throw new Error(`Unknown remote alias: ${from}`);
+        if (from !== to && remotes[to])
+            throw new Error(`Remote alias already exists: ${to}`);
+        delete remotes[from];
+        remotes[to] = remote;
+        return { ...auth, remotes };
+    }, env);
+}
+export function removeForgeRelayRemote(alias, env = process.env) {
+    const normalizedAlias = normalizeRemoteAlias(alias);
+    return updateForgeRelayAuth((auth) => {
+        const remotes = { ...(auth.remotes ?? {}) };
+        if (!remotes[normalizedAlias])
+            throw new Error(`Unknown remote alias: ${normalizedAlias}`);
+        delete remotes[normalizedAlias];
+        return { ...auth, remotes };
+    }, env);
+}
 export function ensureForgeRelayDefaultSkills(env = process.env) {
     const targetPath = join(forgerelaySkillsDir(env), "subagent-delegation", "SKILL.md");
     if (existsSync(targetPath))
@@ -124,6 +197,59 @@ function readJsonFile(filePath) {
         throw new Error(`Unable to read ${filePath}: ${reason}`);
     }
 }
+function updateForgeRelayAuth(update, env) {
+    const filePath = forgerelayAuthPath(env);
+    mkdirSync(forgerelayConfigDir(env), { recursive: true });
+    return withAuthFileLock(filePath, () => {
+        const auth = existsSync(filePath) ? readJsonFile(filePath) : {};
+        writeJsonFile(filePath, update(auth), 0o600);
+        return filePath;
+    });
+}
+function withAuthFileLock(filePath, operation) {
+    const lockPath = `${filePath}.lock`;
+    const deadline = Date.now() + AUTH_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, "wx", 0o600);
+            closeSync(fd);
+            break;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > AUTH_LOCK_STALE_MS) {
+                    rmSync(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT")
+                    continue;
+                throw statError;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for ForgeRelay auth lock: ${lockPath}`);
+            }
+            Atomics.wait(AUTH_LOCK_SLEEP, 0, 0, AUTH_LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return operation();
+    }
+    finally {
+        rmSync(lockPath, { force: true });
+    }
+}
 function writeJsonFile(filePath, value, mode) {
-    writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", { mode });
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n", { mode });
+        renameSync(tempPath, filePath);
+    }
+    finally {
+        rmSync(tempPath, { force: true });
+    }
 }

package/docs/configuration.md

@@ -386,7 +386,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
 <workspace>/.forgerelay/hooks/<hook-name>.json
 ```
 
-文件名去掉 `.json` 后就是 Hook 名，也是日志和 Agent-visible report 中显示的名称。例如 `release-tag-local-ci.json` 会显示为 `release-tag-local-ci`。目录内按文件名字典序执行；需要显式排序时可以使用 `10-release-verify.json`、`20-package-inspection.json` 这样的前缀。ForgeRelay 只读取普通 `*.json` 文件，所以临时停用某条 Hook 时可以把扩展名改掉。
+文件名去掉 `.json` 后就是 Hook 名，也是日志和 Agent-visible report 中显示的名称。例如 `release-tag-gate.json` 会显示为 `release-tag-gate`。目录内按文件名字典序执行；需要显式排序时可以使用 `10-release-verify.json`、`20-package-inspection.json` 这样的前缀。ForgeRelay 只读取普通 `*.json` 文件，所以临时停用某条 Hook 时可以把扩展名改掉。
 
 全局 Hook 在 server 启动时读取，修改后需要重启 ForgeRelay；项目目录在每次事件时重新读取，所以 Agent 修改项目 Hook 后不需要重启。全局规则先执行，项目规则随后执行，两边都只做追加，不互相覆盖。
 
@@ -405,7 +405,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
 }
 ```
 
-这个例子可以保存为 `.forgerelay/hooks/release-tag-local-ci.json`。耗时的 `npm run release:verify` 应在已提交的 release-ready HEAD 上提前运行，并在 `.git/forgerelay/` 写入 release proof。Agent 之后通过 ForgeRelay `bash` 请求推送稳定版本 tag 时，Hook 只快速校验 proof、当前 HEAD/package version、clean working tree（含 untracked）与本地 tag 指向；全部一致才执行原始 `git push`。因此发布 gate 不再依赖一个持续数分钟的单次 MCP request，同时任何验证后的代码变化都会使 proof 失效并阻断推送。
+这个例子可以保存为 `.forgerelay/hooks/release-tag-gate.json`。Agent 通过 ForgeRelay `bash` 请求推送稳定版本 tag 时，Hook 只执行轻量仓库状态门禁：拒绝 force/delete 形式，校验 clean working tree（含 untracked）、tag 与 package version 一致，并要求本地 tag 指向当前 HEAD。Hook 不运行、也不要求本地 CI；tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后发布 job 才会继续。`npm run release:verify` 仅用于需要时本地复现云端环境。
 
 独立 Hook 文件支持这些顶层字段：
 
@@ -472,7 +472,7 @@ Matcher 匹配 ForgeRelay 收到的那次 tool request，不会窥探该命令
 
 ```text
 Hook results:
-✓ release-tag-local-ci (BeforeTool, project) passed in 42ms
+✓ release-tag-gate (BeforeTool, project) passed in 42ms
 ```
 
 阻断失败会明确显示 `failed`。ForgeRelay 的 server instructions 要求 Agent 在出现 Hook results 时，向用户说明有意义的 Hook 是否通过或阻断了操作。异步 subagent 的 `SubagentStart` / `SubagentStop` 报告会随 session 持久化，并由 `forgerelay agents show` 展示。

package/docs/versioning.md

@@ -79,25 +79,20 @@ The bump commands update:
 
 They do not commit, tag, push, or publish.
 
-Run the full local release gate with:
+For local diagnosis or cloud-parity reproduction, you can optionally run:
 
 ```bash
 npm run release:verify
 ```
 
-`release:verify` checks the current committed release-ready runtime and then runs a focused
-`release:parity` gate in an isolated Node 22.19.0 sandbox. After every check passes it
-records a local release proof under `.git/forgerelay/`, binding that verification to
-current HEAD and the package version. The parity sandbox
-performs its own `npm ci` so native addons use the same Node ABI as cloud CI,
-then reruns the LSP/release tests most sensitive to event-loop timing, process
-lifecycle, path canonicalization, executable discovery, and cleanup behavior.
-It also tests that a command which exists on `PATH` but fails its `--version`
-preflight is treated as unavailable rather than as an installed Language server.
+`release:verify` runs the same focused parity checks in an isolated Node 22.19.0 sandbox
+and records a local proof under `.git/forgerelay/` for debugging/audit purposes. It is
+not a prerequisite for pushing a release tag. The authoritative release verification
+is the tag-triggered GitHub Actions matrix on Linux, macOS, and Windows.
 
-Cloud verification and the publication job are both pinned to Node 22.19.0, the
-minimum supported Node release, so local parity and the release runners use the
-same runtime instead of drifting across separate Node 22/24 variants.
+Cloud verification and the publication job are pinned to Node 22.19.0, the minimum
+supported Node release. The optional local parity tool uses the same runtime so a cloud
+failure can be reproduced locally without making local execution part of the release gate.
 
 Validate a specific tag with:
 
@@ -172,11 +167,8 @@ npm publishing token.
 3. Run the appropriate `release:patch`, `release:minor`, or `release:major`
    command.
 4. Review the generated version and changelog diff, then commit the release-ready code and metadata.
-5. Run `npm run release:verify` locally on that clean committed HEAD. This full local gate includes the isolated
-   Node 22.19.0 parity sandbox and records the local release proof consumed by the tag-push Hook; ordinary development
-   pushes do not need to run the full release gate.
-6. Push the verified `main` commit without changing it afterward.
-7. Create the exact version tag, for example:
+5. Push the release-ready `main` commit without changing it afterward.
+6. Create the exact version tag, for example:
 
    ```bash
    git tag v0.2.0
@@ -185,7 +177,7 @@ npm publishing token.
 
 The tag push is the publication action. The release workflow publishes npm only after cloud CI passes, then extracts the matching `CHANGELOG.md` release section as the GitHub Release body. Keep `Unreleased` user-facing and structured (`Added`, `Changed`, `Fixed`, `Security`) because those notes are what users see on the Release page.
 
-Project release Hooks match the stable tag-push command as a substring of the ForgeRelay shell request. A compound command is allowed: when `commandRegex` matches `git push origin vX.Y.Z`, the Hook receives that matched command as `FORGERELAY_HOOK_PAYLOAD.command` and retains the complete shell request as `originalCommand` when they differ. The release Hook does **not** rerun the multi-minute local gate inside the tag-push MCP request. Instead it quickly verifies the proof written by `release:verify`, requires a clean working tree including untracked files, requires the proof HEAD/package version to equal the current release state, and requires the local tag to resolve to that same verified HEAD. Any change after verification invalidates the proof and blocks the push until `release:verify` is rerun.
+Project release Hooks match the stable tag-push command as a substring of the ForgeRelay shell request. A compound command is allowed: when `commandRegex` matches `git push origin vX.Y.Z`, the Hook receives that matched command as `FORGERELAY_HOOK_PAYLOAD.command` and retains the complete shell request as `originalCommand` when they differ. The release Hook is intentionally lightweight: it rejects force/deletion forms, requires a clean working tree including untracked files, requires the tag to match the package version, and requires the local tag to resolve to current HEAD. It does not run or require local CI. The pushed tag then starts the authoritative Linux/macOS/Windows cloud verification; publication cannot run unless that matrix succeeds.
 
 ## Attribution guardrails
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -41,10 +41,13 @@
     "debug:serve": "node scripts/debug/serve.mjs",
     "debug:accept": "node scripts/debug/accept.mjs",
     "lsp:interop": "node scripts/lsp-interop.mjs",
+    "ci:verify": "node scripts/ci/verify.mjs",
     "release:parity": "node scripts/release-parity.mjs",
+    "release:pack": "node scripts/release/pack.mjs",
+    "release:publish": "node scripts/release/publish.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/remote-auth-cli.test.ts && tsx src/remote-ssh-auth-cli.test.ts && tsx src/remote-workspace-relay.test.ts && tsx src/remote-workspace-relay-process.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/ci/verify.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+const npmCli = process.env.npm_execpath;
+if (!npmCli) {
+  throw new Error("ci:verify must be launched through npm so npm_execpath is available");
+}
+
+console.log(`CI environment: ${process.platform}/${process.arch} ${process.version}`);
+runNpm(["--version"], "npm version");
+runNpm(["run", "release:check"], "Release metadata");
+runNpm(["run", "typecheck"], "Typecheck");
+runNpm(["test"], "Full test suite");
+runNpm(["run", "build"], "Build");
+runNpm(["run", "lsp:interop"], "Optional LSP interoperability");
+run(process.execPath, ["dist/cli.js", "doctor"], "Doctor");
+
+console.log("CI verification passed.");
+
+function runNpm(args, label) {
+  run(process.execPath, [npmCli, ...args], label);
+}
+
+function run(command, args, label) {
+  console.log(`\n== ${label} ==`);
+  const result = spawnSync(command, args, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+    shell: false,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${label} failed with exit ${result.status ?? "unknown"}`);
+  }
+}