@akira-tl/forgerelay 0.9.3 → 0.9.4

package/dist/cli/setup-support.js

@@ -34,6 +34,9 @@ export function normalizePublicBaseUrl(value) {
     parsed.pathname = parsed.pathname.replace(/\/+$/, "");
     return parsed.toString().replace(/\/$/, "");
 }
+export function setupBindAddress(mode) {
+    return mode === "lan" ? "0.0.0.0" : "127.0.0.1";
+}
 export function classifyClientFacingBaseUrl(value) {
     const parsed = new URL(normalizePublicBaseUrl(value));
     if (parsed.protocol === "https:")
@@ -62,6 +65,24 @@ export function validateClientFacingBaseUrls(value) {
 export function hasInsecureLanBaseUrl(baseUrls) {
     return baseUrls.some((baseUrl) => classifyClientFacingBaseUrl(baseUrl) === "insecure-lan");
 }
+export function validateLanClientFacingBaseUrls(value) {
+    const validation = validateClientFacingBaseUrls(value);
+    if (validation)
+        return validation;
+    const baseUrls = normalizePublicBaseUrlsInput(value ?? "");
+    return baseUrls.every((baseUrl) => new URL(baseUrl).protocol === "http:")
+        ? undefined
+        : "Direct LAN mode requires http:// client-facing URLs on a trusted private network.";
+}
+export function validateHttpsProxyBaseUrls(value) {
+    const validation = validateClientFacingBaseUrls(value);
+    if (validation)
+        return validation;
+    const baseUrls = normalizePublicBaseUrlsInput(value ?? "");
+    return baseUrls.every((baseUrl) => new URL(baseUrl).protocol === "https:")
+        ? undefined
+        : "HTTPS proxy mode requires HTTPS client-facing URLs.";
+}
 function isPrivateNetworkHost(hostname) {
     const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
     if (host === "localhost" || !host.includes(".") || host.endsWith(".local") || host.endsWith(".lan") || host.endsWith(".home.arpa")) {

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/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/docs/configuration.md

@@ -26,6 +26,7 @@ npx @akira-tl/forgerelay serve
 npx @akira-tl/forgerelay doctor
 npx @akira-tl/forgerelay config get
 npx @akira-tl/forgerelay config set publicBaseUrl https://forge.example.com/forgerelay/main,https://forge-alt.example.com/relay
+npx @akira-tl/forgerelay maintenance inspect
 ```
 
 ## Environment variables
@@ -46,6 +47,73 @@ The public environment-variable prefix is `FORGERELAY_*`.
 | `FORGERELAY_WORKTREE_ROOT` | Managed worktree directory. New default: `~/.forgerelay/worktrees`. |
 | `FORGERELAY_WORKFLOW_INSTRUCTIONS` | Replace the built-in workflow policy while retaining the capability contract. |
 | `FORGERELAY_APPEND_INSTRUCTIONS` | Append project/operator workflow policy. |
+| `FORGERELAY_RETENTION_HISTORY_DAYS` | Optional owner-authorized age window for related Activity/Audit, Host Turn, and durable Bash history. Unset means unlimited retention. |
+| `FORGERELAY_RETENTION_ORPHANED_ADMIN` | Optional boolean authorization for provably orphaned/rebuildable administrative state. Unset/false means do not reclaim it. |
+
+### Retention inspection and prune
+
+Durable ForgeRelay history is retained without an age limit by default. The owner can
+inspect what is retained, protected, and potentially reclaimable without starting the
+server:
+
+```bash
+npx @akira-tl/forgerelay maintenance inspect
+npx @akira-tl/forgerelay maintenance inspect --json
+```
+
+Inspection is read-only: it snapshots an existing SQLite database and WAL into a
+temporary directory before opening that snapshot read-only, reads bounded
+Workspace-private Task/checkpoint metadata, and uses read-only Git ref/worktree
+queries. It does not create or migrate a missing/older source database, touch Workspace
+last-used timestamps, move refs, or alter worktrees.
+
+After reviewing that report, the owner can explicitly apply the configured policy:
+
+```bash
+npx @akira-tl/forgerelay maintenance prune
+npx @akira-tl/forgerelay maintenance prune --json
+```
+
+`maintenance prune` is manual and policy-gated. With neither `historyDays` nor
+`orphanedAdministrativeState` authorized it is a no-op. It acquires the ForgeRelay
+runtime lease before any destructive work, so it refuses to run concurrently with a
+server using the same state directory. Historical cleanup is performed in whole Host
+Turn cohorts: a turn is retained if any Activity is recent, nonterminal, owns a running
+Bash stream, or is tied to an active Subagent Run. When removed Activity payloads share
+a segmented log with retained payloads, retained bytes are compacted to a new segment
+before the old unreferenced segment is deleted.
+
+Administrative cleanup is deliberately conservative. It removes only review refs that
+can be proven orphaned and rebuildable, plus empty orphan Workspace-state directories.
+Canonical and alias Workspace identities, any non-empty private Workspace state,
+Workspace Tasks, named checkpoints, active/runtime state, managed worktrees, and
+managed branches remain protected. Repeating the same prune is idempotent and should
+report no newly eligible state after the first successful pass.
+
+The persisted policy shape is:
+
+```json
+{
+  "retention": {
+    "historyDays": 30,
+    "orphanedAdministrativeState": false
+  }
+}
+```
+
+`historyDays` is one shared cutoff for related Activity/Audit, Host Turn, and durable
+Bash history so later owner-authorized maintenance can preserve cross-store
+consistency. Omit it for unlimited durable-history retention. The environment override
+is `FORGERELAY_RETENTION_HISTORY_DAYS`. `orphanedAdministrativeState` is a separate
+explicit authorization, with `FORGERELAY_RETENTION_ORPHANED_ADMIN` as its environment
+override.
+
+Named Workspace checkpoints and Workspace Tasks are protected by this policy:
+checkpoint removal remains an explicit checkpoint operation, and retention maintenance
+never treats Tasks as disposable history. Existing automatic runtime GC is separate:
+it bounds rebuildable/in-memory runtime resources and expires stale context-delivery
+bookkeeping; it does **not** age-prune durable Activity/Audit history, durable Bash
+output, named checkpoints, persistent Workspace identity, or Task Lists.
 
 ### Routed and multi-origin public deployments
 
@@ -61,12 +129,18 @@ or multiple URLs as an array:
 }
 ```
 
-Each entry keeps its own route prefix. The first URL is canonical and is used for
-generated OAuth/MCP URLs; every configured hostname is included in the derived
-Host-header allowlist. MCP App `_meta.ui.domain` uses the canonical URL's origin,
-while CSP resource/connect entries include every full public base URL. The full
-ordered `publicBaseUrl` list also participates in the MCP App resource cache
-identity, so changing any domain or route produces a new `ui://` resource URI.
+Each entry keeps its own route prefix. Every configured pathname is an accepted
+inbound operational route boundary; the first URL remains canonical for generated
+OAuth/MCP metadata and links. For example, if the only configured URL is
+`https://forge.example.com/forgerelay/main`, MCP, OAuth operations, health, and MCP App
+assets are served below `/forgerelay/main/*`; naked `/mcp`, `/authorize`, `/token`,
+`/healthz`, and `/mcp-app-assets/*` are not parallel deployment routes. Standards-based
+OAuth/MCP discovery metadata remains under its required `/.well-known/...` paths.
+Every configured hostname is included in the derived Host-header allowlist. MCP App
+`_meta.ui.domain` uses the canonical URL's origin, while CSP resource/connect entries
+include every full public base URL. The full ordered `publicBaseUrl` list also
+participates in the MCP App resource cache identity, so changing any domain or route
+produces a new `ui://` resource URI.
 
 A single persisted string remains fully supported, so existing configs require no
 migration. For environment configuration, use a comma-separated list in
@@ -632,7 +706,8 @@ from the normal Skill paths; ForgeRelay does not reserve, delete, or rewrite it.
 | `FORGERELAY_LOG_ASSETS` | `0` |
 | `FORGERELAY_LOG_TOOL_CALLS` | `1` |
 | `FORGERELAY_LOG_SHELL_COMMANDS` | `1` in `pretty`, `0` in `json` |
-| `FORGERELAY_TRUST_PROXY` | auto: `1` only for loopback bind + non-loopback public URL; otherwise `0` |
+| `FORGERELAY_TRUST_PROXY` | legacy compatibility override; `1` is accepted only with a loopback bind |
+| `FORGERELAY_TRUSTED_PROXIES` | explicit comma-separated trusted proxy IP addresses/CIDRs; unset by default |
 
 `pretty` is the human-facing local console format. It uses terminal-aware color,
 short timestamps, workspace-first context, and compact operation results while
@@ -650,12 +725,24 @@ overridden, JSON mode preserves request logging and omits shell command previews
 these format-specific defaults when set.
 
 When ForgeRelay binds to loopback (`127.0.0.1`, `::1`, or `localhost`) but is
-configured with a non-loopback public URL, it automatically trusts exactly one
-upstream proxy hop. This matches the normal tunnel/reverse-proxy topology and
-keeps OAuth rate limiting aligned with Express client-IP resolution. Set
-`FORGERELAY_TRUST_PROXY=0` to disable this inference, or `=1` to enable one-hop
-trust explicitly. ForgeRelay never auto-enables proxy trust when binding to
-`0.0.0.0` or another directly reachable interface.
+configured with a non-loopback public URL, it trusts only the loopback proxy source.
+This matches the normal local tunnel/reverse-proxy topology while preventing a public
+or LAN client from becoming trusted merely because it supplied forwarded headers.
+`forgerelay init` uses this model for **HTTPS reverse proxy / tunnel** mode and binds
+that mode to `127.0.0.1`; **Direct LAN** mode binds to `0.0.0.0` and does not trust a
+proxy by default.
+
+Set `FORGERELAY_TRUST_PROXY=0` to disable inferred loopback trust. The legacy
+`FORGERELAY_TRUST_PROXY=1` form is accepted only when ForgeRelay itself is bound to
+loopback. For an advanced topology that intentionally combines direct LAN reachability
+with a reverse proxy, list only the actual proxy source addresses or CIDRs, for example:
+
+```bash
+FORGERELAY_TRUSTED_PROXIES="127.0.0.1,10.20.30.0/24" forgerelay serve
+```
+
+The same list may be persisted as `trustedProxies` in `config.json`. Wildcard/global
+trust is rejected; do not replace this with Express `trust proxy=true` on a LAN bind.
 
 ## Environment-only example