@akira-tl/forgerelay 0.9.2 → 0.9.4

package/dist/cli.js

@@ -9,7 +9,9 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
 import { loadConfig } from "./runtime/config/config.js";
+import { acquireRuntimeLease } from "./runtime/state/runtime-lease.js";
 import { runInit } from "./cli/init.js";
+import { runMaintenanceCommand } from "./cli/maintenance.js";
 import { runHooksCommand } from "./mcp/hooks/hook-cli.js";
 import { executeSubagentSession } from "./subagents/sessions/execution.js";
 import { SubagentDeliveryMailbox } from "./subagents/sessions/delivery-mailbox.js";
@@ -50,6 +52,9 @@ async function main(argv) {
         case "auth":
             await runAuthCommand(args);
             return;
+        case "maintenance":
+            runMaintenanceCommand(args);
+            return;
         case "help":
             printHelp();
             return;
@@ -61,7 +66,7 @@ async function main(argv) {
 function normalizeCommand(command) {
     if (!command || command === "serve" || command === "start")
         return "serve";
-    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth")
+    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth" || command === "maintenance")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
         return "help";
@@ -104,9 +109,18 @@ async function serve() {
     }
     const { createServer } = await import("./server.js");
     const config = loadConfig();
-    const { app, close, subagentProviders } = createServer(config);
+    const runtimeLease = acquireRuntimeLease(config.stateDir);
+    let server;
+    try {
+        server = createServer(config);
+    }
+    catch (error) {
+        runtimeLease.release();
+        throw error;
+    }
+    const { app, close, subagentProviders } = server;
     const httpServer = app.listen(config.port, config.host, () => {
-        console.log(`forgerelay listening on http://${config.host}:${config.port}/mcp`);
+        console.log(`forgerelay listening on http://${config.host}:${config.port}${publicEndpointUrl(config.publicBaseUrl, "mcp").pathname}`);
         console.log(`client-facing base url: ${config.publicBaseUrl}`);
         console.log(`allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`allowed hosts: ${config.allowedHosts.join(", ")}`);
@@ -120,11 +134,19 @@ async function serve() {
         }
     });
     let shuttingDown = false;
+    const releaseRuntimeLease = () => runtimeLease.release();
+    process.once("exit", releaseRuntimeLease);
     const shutdown = async () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
-        await shutdownHttpServer(httpServer, close);
+        try {
+            await shutdownHttpServer(httpServer, close);
+        }
+        finally {
+            process.removeListener("exit", releaseRuntimeLease);
+            runtimeLease.release();
+        }
         process.exit(0);
     };
     const handleShutdown = () => {
@@ -308,13 +330,13 @@ async function runDoctor() {
     console.log(`SQLite native dependency: ${checkSqliteNative()}`);
     try {
         const config = loadConfig();
-        console.log(`Bind MCP URL: http://${config.host}:${config.port}/mcp`);
+        console.log(`Bind MCP URL: http://${config.host}:${config.port}${publicEndpointUrl(config.publicBaseUrl, "mcp").pathname}`);
         console.log(`Client-facing base URLs: ${config.publicBaseUrls.join(", ")}`);
         console.log(`Client-facing base URL: ${config.publicBaseUrl}`);
         console.log(`Client-facing MCP URL: ${publicEndpointUrl(config.publicBaseUrl, "mcp").toString()}`);
         console.log(`Tool mode: ${config.toolMode}`);
         console.log(`Widgets: ${config.widgets}`);
-        console.log(`Trust proxy: ${config.logging.trustProxy ? "one hop" : "off"}`);
+        console.log(`Trust proxy: ${config.proxyTrust === false ? "off" : config.proxyTrust.join(", ")}`);
         console.log(`Artifacts: ${config.artifactsEnabled ? "enabled" : "disabled"}`);
         console.log(`Subagents: ${config.subagents ? "enabled" : "disabled"}`);
         console.log(`Skills: ${config.skillsEnabled ? "enabled" : "disabled"}`);
@@ -370,6 +392,7 @@ function printHelp() {
         "  forgerelay auth test <alias>",
         "  forgerelay auth rename <old-alias> <new-alias>",
         "  forgerelay auth remove <alias>",
+        "  forgerelay maintenance inspect [--json]",
         "  forgerelay -v, --version   Print the installed version",
         "",
         "For temporary tunnels:",

package/dist/mcp/oauth/public-url.js

@@ -7,6 +7,9 @@ export function publicEndpointUrl(baseUrl, suffix) {
     url.hash = "";
     return url;
 }
+export function publicEndpointPaths(baseUrls, suffix) {
+    return Array.from(new Set(baseUrls.map((baseUrl) => publicEndpointUrl(baseUrl, suffix).pathname)));
+}
 export function oauthAuthorizationServerMetadataPath(issuerUrl) {
     const issuer = new URL(issuerUrl instanceof URL ? issuerUrl.href : issuerUrl);
     const issuerPath = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/+$/, "");

package/dist/mcp/oauth/router.js

@@ -5,9 +5,9 @@ import { tokenHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/tok
 import { clientRegistrationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/register.js";
 import { revocationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/revoke.js";
 import { metadataHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/metadata.js";
-import { oauthAuthorizationServerMetadataPath, publicEndpointUrl, } from "./public-url.js";
+import { oauthAuthorizationServerMetadataPath, publicEndpointPaths, publicEndpointUrl, } from "./public-url.js";
 export function createForgeRelayAuthRouter(options) {
-    const { provider, cliAuthenticationProvider, instanceId, issuerUrl, resourceServerUrl, scopesSupported, resourceName, } = options;
+    const { provider, cliAuthenticationProvider, instanceId, issuerUrl, resourceServerUrl, routeBaseUrls = [issuerUrl], scopesSupported, resourceName, } = options;
     const authorizationEndpoint = publicEndpointUrl(issuerUrl, "authorize");
     const tokenEndpoint = publicEndpointUrl(issuerUrl, "token");
     const registrationEndpoint = provider.clientsStore.registerClient
@@ -16,6 +16,11 @@ export function createForgeRelayAuthRouter(options) {
     const revocationEndpoint = provider.revokeToken
         ? publicEndpointUrl(issuerUrl, "revoke")
         : undefined;
+    const cliAuthenticationPaths = publicEndpointPaths(routeBaseUrls, "auth/cli");
+    const authorizationPaths = publicEndpointPaths(routeBaseUrls, "authorize");
+    const tokenPaths = publicEndpointPaths(routeBaseUrls, "token");
+    const registrationPaths = publicEndpointPaths(routeBaseUrls, "register");
+    const revocationPaths = publicEndpointPaths(routeBaseUrls, "revoke");
     const oauthMetadata = {
         ...createOAuthMetadata({
             provider,
@@ -36,7 +41,7 @@ export function createForgeRelayAuthRouter(options) {
     };
     const router = express.Router();
     if (cliAuthenticationProvider) {
-        router.post("/auth/cli", express.json({ limit: "4kb" }), (req, res) => {
+        router.post(cliAuthenticationPaths, express.json({ limit: "4kb" }), (req, res) => {
             const ownerToken = typeof req.body?.owner_token === "string" ? req.body.owner_token : undefined;
             const refreshToken = typeof req.body?.refresh_token === "string" ? req.body.refresh_token : undefined;
             if ((ownerToken ? 1 : 0) + (refreshToken ? 1 : 0) !== 1) {
@@ -55,13 +60,13 @@ export function createForgeRelayAuthRouter(options) {
             res.status(200).json({ ...tokens, ...(instanceId ? { instance_id: instanceId } : {}) });
         });
     }
-    router.use("/authorize", authorizationHandler({ provider }));
-    router.use("/token", tokenHandler({ provider }));
-    if (provider.clientsStore.registerClient) {
-        router.use("/register", clientRegistrationHandler({ clientsStore: provider.clientsStore }));
+    router.use(authorizationPaths, authorizationHandler({ provider }));
+    router.use(tokenPaths, tokenHandler({ provider }));
+    if (provider.clientsStore.registerClient && registrationEndpoint) {
+        router.use(registrationPaths, clientRegistrationHandler({ clientsStore: provider.clientsStore }));
     }
-    if (provider.revokeToken) {
-        router.use("/revoke", revocationHandler({ provider }));
+    if (provider.revokeToken && revocationEndpoint) {
+        router.use(revocationPaths, revocationHandler({ provider }));
     }
     router.use(oauthAuthorizationServerMetadataPath(issuerUrl), metadataHandler(oauthMetadata));
     router.use(new URL(getOAuthProtectedResourceMetadataUrl(resourceServerUrl)).pathname, metadataHandler(protectedResourceMetadata));

package/dist/mcp/server/core/capabilities/workspace-checkpoint.js

@@ -13,6 +13,15 @@ export const workspaceCheckpointInputSchema = z.discriminatedUnion("operation",
         operation: z.literal("inspect"),
         checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
     }).strict(),
+    z.object({
+        operation: z.literal("restore.preflight"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+    }).strict(),
+    z.object({
+        operation: z.literal("restore"),
+        checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
+        expectedCurrentSnapshot: z.string().regex(/^[a-f0-9]{40,64}$/),
+    }).strict(),
     z.object({
         operation: z.literal("delete"),
         checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),

package/dist/mcp/server/core/capability-registry.js

@@ -308,7 +308,7 @@ export function createCapabilityRegistry(dependencies) {
         ...(dependencies.workspaceCheckpoint
             ? [{
                     name: "workspace.checkpoint",
-                    description: "Create, list, inspect, or delete immutable Git-backed checkpoints owned by the current persistent Workspace.",
+                    description: "Create, list, inspect, safely restore, or delete immutable Git-backed checkpoints owned by the current persistent Workspace.",
                     guideName: "workspace-checkpoints",
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",

package/dist/mcp/server/transport/http-server.js

@@ -16,7 +16,7 @@ import { createOpenAIIncomingArtifactAdapter } from "../../artifacts/incoming-ar
 import { logEvent, requestPath, transportSessionIdPrefix } from "../../../runtime/logging/logger.js";
 import { SingleUserOAuthProvider } from "../../oauth/oauth-provider.js";
 import { createForgeRelayAuthRouter } from "../../oauth/router.js";
-import { publicEndpointUrl } from "../../oauth/public-url.js";
+import { publicEndpointPaths, publicEndpointUrl } from "../../oauth/public-url.js";
 import { McpTransportRegistry } from "./mcp-sessions.js";
 import { ProcessManager } from "../../process/process-sessions.js";
 import { createReviewCheckpointManager } from "../../../workspaces/review/review-checkpoints.js";
@@ -45,7 +45,11 @@ export function createHttpServer(config, options, createMcpServer) {
     const transports = new McpTransportRegistry({
         maxTransports: MAX_MCP_TRANSPORT_SESSIONS,
     });
+    const routeBaseUrls = config.publicBaseUrls.map((baseUrl) => new URL(baseUrl));
     const mcpUrl = publicEndpointUrl(config.publicBaseUrl, "mcp");
+    const mcpPaths = publicEndpointPaths(routeBaseUrls, "mcp");
+    const activityPanelAssetsPaths = publicEndpointPaths(routeBaseUrls, "mcp-app-assets");
+    const healthPaths = publicEndpointPaths(routeBaseUrls, "healthz");
     const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
     const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
     const bearerAuth = requireBearerAuth({
@@ -140,8 +144,8 @@ export function createHttpServer(config, options, createMcpServer) {
     }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
     transportCleanupTimer.unref();
     logRuntimeResources();
-    if (config.logging.trustProxy) {
-        app.set("trust proxy", 1);
+    if (config.proxyTrust !== false) {
+        app.set("trust proxy", config.proxyTrust);
     }
     app.use((req, res, next) => {
         const requestId = randomUUID();
@@ -151,7 +155,7 @@ export function createHttpServer(config, options, createMcpServer) {
             const path = requestPath(req);
             if (!config.logging.requests)
                 return;
-            if (!config.logging.assets && path.startsWith("/mcp-app-assets"))
+            if (!config.logging.assets && activityPanelAssetsPaths.some((assetPath) => path.startsWith(assetPath)))
                 return;
             logEvent(config.logging, "info", "http_request", {
                 requestId,
@@ -170,23 +174,24 @@ export function createHttpServer(config, options, createMcpServer) {
         instanceId: config.instanceId,
         issuerUrl: new URL(config.publicBaseUrl),
         resourceServerUrl,
+        routeBaseUrls,
         scopesSupported: config.oauth.scopes,
         resourceName: "ForgeRelay",
     }));
-    app.options("/mcp-app-assets/{*asset}", (_req, res) => {
+    app.options(activityPanelAssetsPaths.map((assetPath) => `${assetPath}/{*asset}`), (_req, res) => {
         setActivityPanelAssetHeaders(res);
         res.sendStatus(204);
     });
-    app.use("/mcp-app-assets", express.static(activityPanelAssetDirectory(), {
+    app.use(activityPanelAssetsPaths, express.static(activityPanelAssetDirectory(), {
         immutable: true,
         maxAge: "1y",
         fallthrough: false,
         setHeaders: setActivityPanelAssetHeaders,
     }));
-    app.get("/healthz", (_req, res) => {
+    app.get(healthPaths, (_req, res) => {
         res.json({ ok: true, name: "forgerelay" });
     });
-    app.all("/mcp", async (req, res) => {
+    app.all(mcpPaths, async (req, res) => {
         const requestId = res.locals.requestId;
         const transportSessionId = req.header("mcp-session-id");
         const initializeRequest = req.method === "POST" && isInitializeRequest(req.body);

package/dist/runtime/config/config.js

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
@@ -118,12 +119,11 @@ function parseNonNegativeInteger(value, fallback, name) {
     }
     return parsed;
 }
-function parseLoggingConfig(env, trustProxyDefault) {
+function parseLoggingConfig(env, trustProxy) {
     const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
     const toolCalls = productEnv(env, "LOG_TOOL_CALLS");
     const shellCommands = productEnv(env, "LOG_SHELL_COMMANDS");
-    const trustProxy = productEnv(env, "TRUST_PROXY");
     return {
         level: parseLogLevel(productEnv(env, "LOG_LEVEL")),
         format,
@@ -131,11 +131,57 @@ function parseLoggingConfig(env, trustProxyDefault) {
         assets: parseBoolean(productEnv(env, "LOG_ASSETS")),
         toolCalls: toolCalls === undefined ? true : parseBoolean(toolCalls),
         shellCommands: shellCommands === undefined ? format === "pretty" : parseBoolean(shellCommands),
-        trustProxy: trustProxy === undefined ? trustProxyDefault : parseBoolean(trustProxy),
+        trustProxy,
     };
 }
-function shouldTrustOneProxyByDefault(host, publicBaseUrl) {
-    return isLoopbackHost(host) && !isLoopbackHost(new URL(publicBaseUrl).hostname);
+function resolveProxyTrust(env, config, host, publicBaseUrl) {
+    const legacyTrustProxy = productEnv(env, "TRUST_PROXY");
+    if (legacyTrustProxy !== undefined) {
+        if (!parseBoolean(legacyTrustProxy))
+            return false;
+        if (!isLoopbackHost(host)) {
+            throw new Error("FORGERELAY_TRUST_PROXY=1 is only safe with a loopback bind. Use FORGERELAY_TRUSTED_PROXIES with explicit proxy IP addresses or CIDRs for LAN binds.");
+        }
+        return ["loopback"];
+    }
+    const envTrustedProxies = productEnv(env, "TRUSTED_PROXIES");
+    const explicitTrustedProxies = parseTrustedProxies(envTrustedProxies === undefined ? config.trustedProxies : envTrustedProxies);
+    if (explicitTrustedProxies !== undefined)
+        return explicitTrustedProxies;
+    return isLoopbackHost(host) && !isLoopbackHost(new URL(publicBaseUrl).hostname)
+        ? ["loopback"]
+        : false;
+}
+function parseTrustedProxies(value) {
+    if (value === undefined)
+        return undefined;
+    const entries = (Array.isArray(value) ? value : value.split(","))
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (entries.length === 0)
+        return undefined;
+    if (entries.some((entry) => !isTrustedProxyAddress(entry))) {
+        throw new Error("FORGERELAY_TRUSTED_PROXIES must list trusted proxy IP addresses or CIDRs; only the internal `loopback` alias is also accepted.");
+    }
+    return Array.from(new Set(entries));
+}
+function isTrustedProxyAddress(value) {
+    if (value === "loopback")
+        return true;
+    if (value === "*" || value === "0.0.0.0/0" || value === "::/0")
+        return false;
+    if (isIP(value) !== 0)
+        return true;
+    const slashIndex = value.lastIndexOf("/");
+    if (slashIndex <= 0 || slashIndex === value.length - 1)
+        return false;
+    const address = value.slice(0, slashIndex);
+    const prefixText = value.slice(slashIndex + 1);
+    const family = isIP(address);
+    const prefix = Number(prefixText);
+    if (!Number.isInteger(prefix) || prefix < 0)
+        return false;
+    return family === 4 ? prefix <= 32 : family === 6 ? prefix <= 128 : false;
 }
 function isLoopbackHost(host) {
     const normalized = host.trim().toLowerCase().replace(/^\[(.*)\]$/, "$1");
@@ -221,6 +267,7 @@ export function loadConfig(env = process.env) {
     const port = parsePort(env.PORT ?? files.config.port);
     const publicDeployment = resolvePublicDeployment(env, files.config, host, port);
     const publicBaseUrl = publicDeployment.canonicalBaseUrl;
+    const proxyTrust = resolveProxyTrust(env, files.config, host, publicBaseUrl);
     const derivedAllowedHosts = [
         "localhost",
         "127.0.0.1",
@@ -239,6 +286,7 @@ export function loadConfig(env = process.env) {
         allowedHosts: parseAllowedHosts(productEnv(env, "ALLOWED_HOSTS"), derivedAllowedHosts),
         publicBaseUrl,
         publicBaseUrls: publicDeployment.baseUrls,
+        proxyTrust,
         toolMode: parseToolMode(env),
         workflowInstructions: parseWorkflowInstructions(productEnv(env, "WORKFLOW_INSTRUCTIONS"), files.config.workflowInstructions),
         appendInstructions: parseAppendInstructions(productEnv(env, "APPEND_INSTRUCTIONS"), files.config.appendInstructions),
@@ -265,7 +313,7 @@ export function loadConfig(env = process.env) {
         agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
         systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
         hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),
-        logging: parseLoggingConfig(env, shouldTrustOneProxyByDefault(host, publicBaseUrl)),
+        logging: parseLoggingConfig(env, proxyTrust !== false),
     };
 }
 function numberConfigValue(value) {

package/dist/runtime/state/runtime-lease.js

@@ -0,0 +1,109 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, constants as fsConstants, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+const RUNTIME_LEASE_FILE = "forgerelay-runtime.lock";
+export function runtimeLeasePath(stateDir) {
+    return join(stateDir, RUNTIME_LEASE_FILE);
+}
+export function acquireRuntimeLease(stateDir) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const path = runtimeLeasePath(stateDir);
+    const record = {
+        pid: process.pid,
+        token: randomBytes(16).toString("hex"),
+        startedAt: new Date().toISOString(),
+    };
+    const serialized = `${JSON.stringify(record)}\n`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        let fd;
+        try {
+            fd = openSync(path, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+            writeFileSync(fd, serialized, "utf8");
+            closeSync(fd);
+            fd = undefined;
+            return {
+                path,
+                pid: record.pid,
+                release: () => releaseRuntimeLease(path, record),
+            };
+        }
+        catch (error) {
+            if (fd !== undefined)
+                closeSync(fd);
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+            const inspection = inspectRuntimeLease(stateDir);
+            if (inspection.active || inspection.malformed) {
+                const owner = inspection.pid === undefined ? "an unknown process" : `PID ${inspection.pid}`;
+                throw new Error(`ForgeRelay state is already in use by ${owner}: ${path}`);
+            }
+            rmSync(path, { force: true });
+        }
+    }
+    throw new Error(`Unable to acquire ForgeRelay runtime lease: ${path}`);
+}
+export function inspectRuntimeLease(stateDir) {
+    const path = runtimeLeasePath(stateDir);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return { path, active: false, stale: false, malformed: false };
+        }
+        throw error;
+    }
+    const record = parseRecord(raw);
+    if (!record)
+        return { path, active: true, stale: false, malformed: true };
+    const active = processIsAlive(record.pid);
+    return {
+        path,
+        active,
+        stale: !active,
+        pid: record.pid,
+        malformed: false,
+    };
+}
+function releaseRuntimeLease(path, expected) {
+    let current;
+    try {
+        current = parseRecord(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    if (!current || current.pid !== expected.pid || current.token !== expected.token)
+        return;
+    rmSync(path, { force: true });
+}
+function parseRecord(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0)
+            return undefined;
+        if (typeof value.token !== "string" || value.token.length < 16)
+            return undefined;
+        if (typeof value.startedAt !== "string" || !Number.isFinite(Date.parse(value.startedAt)))
+            return undefined;
+        return { pid: value.pid, token: value.token, startedAt: value.startedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isErrno(error, "ESRCH");
+    }
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/server.js

@@ -156,6 +156,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         return { value: await workspaceCheckpoints.list(context.workspaceId, root, input) };
                     case "inspect":
                         return { value: await workspaceCheckpoints.inspect(context.workspaceId, root, input.checkpointId) };
+                    case "restore.preflight":
+                        return { value: await workspaceCheckpoints.preflightRestore(context.workspaceId, root, input.checkpointId) };
+                    case "restore":
+                        return {
+                            value: await workspaceCheckpoints.restore(context.workspaceId, root, input.checkpointId, input.expectedCurrentSnapshot),
+                        };
                     case "delete":
                         return { value: await workspaceCheckpoints.delete(context.workspaceId, root, input.checkpointId) };
                 }

package/dist/workspaces/state/workspace-checkpoints.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
-import { mkdtemp, realpath, rm } from "node:fs/promises";
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import * as z from "zod/v4";
@@ -117,6 +117,73 @@ export class WorkspaceCheckpointStore {
         await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
         return { workspaceId: id, checkpoint: cloneCheckpoint(checkpoint), ignoredFilesIncluded: false };
     }
+    async preflightRestore(workspaceId, workspaceRoot, checkpointId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        const repository = await resolveRepository(workspaceRoot);
+        const state = this.requireState(id);
+        await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+        const checkpoint = requireCheckpoint(state, cpId);
+        await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+        const [checkpointSnapshot, current] = await Promise.all([
+            checkpointTree(repository.gitRoot, checkpoint.commit),
+            snapshotWorkingTree(repository.gitRoot),
+        ]);
+        const restoreSummary = summarizeNumstat((await git(repository.gitRoot, [
+            "diff",
+            "--numstat",
+            "-z",
+            "--no-renames",
+            current.tree,
+            checkpointSnapshot,
+            "--",
+            ".",
+        ], { maxBuffer: 50 * 1024 * 1024 })).stdout);
+        return {
+            workspaceId: id,
+            checkpoint: cloneCheckpoint(checkpoint),
+            checkpointSnapshot,
+            currentSnapshot: current.tree,
+            restoreSummary,
+            ignoredFilesIncluded: false,
+            stagingStateRestored: false,
+        };
+    }
+    async restore(workspaceId, workspaceRoot, checkpointId, expectedCurrentSnapshot) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const cpId = normalizeCheckpointId(checkpointId);
+        const expected = normalizeSnapshotId(expectedCurrentSnapshot);
+        return this.runMutation(id, async () => {
+            const repository = await resolveRepository(workspaceRoot);
+            const state = this.requireState(id);
+            await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+            const checkpoint = requireCheckpoint(state, cpId);
+            await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+            const checkpointSnapshot = await checkpointTree(repository.gitRoot, checkpoint.commit);
+            const current = await snapshotWorkingTree(repository.gitRoot);
+            assertExpectedCurrentSnapshot(expected, current.tree);
+            if (current.tree !== checkpointSnapshot) {
+                await applyTreeRestore(repository.gitRoot, current.tree, checkpointSnapshot, async () => {
+                    const immediate = await snapshotWorkingTree(repository.gitRoot);
+                    assertExpectedCurrentSnapshot(expected, immediate.tree);
+                });
+            }
+            const restored = await snapshotWorkingTree(repository.gitRoot);
+            if (restored.tree !== checkpointSnapshot) {
+                throw new Error(`Workspace checkpoint restore did not reproduce checkpoint snapshot ${checkpointSnapshot}; current snapshot is ${restored.tree}.`);
+            }
+            return {
+                workspaceId: id,
+                checkpointId: cpId,
+                restored: true,
+                checkpointSnapshot,
+                previousSnapshot: current.tree,
+                currentSnapshot: restored.tree,
+                ignoredFilesIncluded: false,
+                stagingStateRestored: false,
+            };
+        });
+    }
     async delete(workspaceId, workspaceRoot, checkpointId) {
         const id = normalizeWorkspaceId(workspaceId);
         const cpId = normalizeCheckpointId(checkpointId);
@@ -247,6 +314,21 @@ async function resolveRepository(workspaceRoot) {
     return { gitRoot: eligibility.gitRoot, gitCommonDir: commonDir };
 }
 async function createWorkingTreeSnapshot(gitRoot) {
+    const snapshot = await snapshotWorkingTree(gitRoot);
+    const commit = (await git(gitRoot, [
+        "commit-tree",
+        snapshot.tree,
+        "-p",
+        snapshot.baseHead,
+        "-m",
+        "ForgeRelay persistent workspace checkpoint",
+    ], { env: checkpointIdentityEnv() })).stdout.trim();
+    const numstat = (await git(gitRoot, ["diff", "--numstat", "-z", snapshot.baseHead, commit], {
+        maxBuffer: 50 * 1024 * 1024,
+    })).stdout;
+    return { commit, baseHead: snapshot.baseHead, summary: summarizeNumstat(numstat) };
+}
+async function snapshotWorkingTree(gitRoot) {
     const tempDir = await mkdtemp(join(tmpdir(), "forgerelay-checkpoint-index-"));
     const indexPath = join(tempDir, "index");
     const env = checkpointEnv(indexPath);
@@ -255,18 +337,35 @@ async function createWorkingTreeSnapshot(gitRoot) {
         await git(gitRoot, ["add", "-A", "--", "."], { env });
         const tree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
         const baseHead = (await git(gitRoot, ["rev-parse", "--verify", "HEAD^{commit}"])).stdout.trim();
-        const commit = (await git(gitRoot, [
-            "commit-tree",
-            tree,
-            "-p",
-            baseHead,
-            "-m",
-            "ForgeRelay persistent workspace checkpoint",
-        ], { env })).stdout.trim();
-        const numstat = (await git(gitRoot, ["diff", "--numstat", "-z", baseHead, commit], {
-            maxBuffer: 50 * 1024 * 1024,
-        })).stdout;
-        return { commit, baseHead, summary: summarizeNumstat(numstat) };
+        return { tree, baseHead };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function checkpointTree(gitRoot, checkpointCommit) {
+    return (await git(gitRoot, ["rev-parse", "--verify", `${checkpointCommit}^{tree}`])).stdout.trim();
+}
+async function applyTreeRestore(gitRoot, currentTree, checkpointTreeId, verifyImmediatelyBeforeApply) {
+    const tempDir = await mkdtemp(join(tmpdir(), "forgerelay-checkpoint-restore-"));
+    const patchPath = join(tempDir, "restore.patch");
+    try {
+        const patch = (await git(gitRoot, [
+            "diff",
+            "--binary",
+            "--full-index",
+            "--no-renames",
+            "--no-ext-diff",
+            "--no-textconv",
+            currentTree,
+            checkpointTreeId,
+            "--",
+            ".",
+        ], { maxBuffer: 100 * 1024 * 1024 })).stdout;
+        await writeFile(patchPath, patch, { encoding: "utf8", mode: 0o600 });
+        await git(gitRoot, ["apply", "--check", "--binary", "--whitespace=nowarn", patchPath]);
+        await verifyImmediatelyBeforeApply();
+        await git(gitRoot, ["apply", "--binary", "--whitespace=nowarn", patchPath]);
     }
     finally {
         await rm(tempDir, { recursive: true, force: true });
@@ -296,7 +395,12 @@ function parseStatNumber(value) {
 }
 function checkpointEnv(indexPath) {
     return {
+        ...checkpointIdentityEnv(),
         GIT_INDEX_FILE: indexPath,
+    };
+}
+function checkpointIdentityEnv() {
+    return {
         GIT_AUTHOR_NAME: "ForgeRelay",
         GIT_AUTHOR_EMAIL: "forgerelay@users.noreply.local",
         GIT_COMMITTER_NAME: "ForgeRelay",
@@ -358,6 +462,18 @@ function normalizeCheckpointId(checkpointId) {
         throw new Error(`Invalid checkpoint id ${checkpointId}.`);
     return value;
 }
+function normalizeSnapshotId(snapshotId) {
+    const value = snapshotId.trim();
+    if (!/^[a-f0-9]{40,64}$/.test(value)) {
+        throw new Error("Workspace checkpoint snapshot identity must be a Git object id.");
+    }
+    return value;
+}
+function assertExpectedCurrentSnapshot(expected, actual) {
+    if (actual !== expected) {
+        throw new Error(`Workspace checkpoint restore refused because the current working snapshot changed: expected ${expected}, found ${actual}. Run restore.preflight again before retrying.`);
+    }
+}
 function normalizeCheckpointName(name) {
     const value = name.trim();
     if (!value)