@akira-tl/forgerelay 0.9.3 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-05
+
+### Added
+
+- Added a first-class Command Shell Runtime identity with launch-shell/fallback selection, explicit pinned shell executable support, owner-visible diagnostics, and one shared shell contract for Agent commands and Hooks.
+- Added editable ForgeRelay shell Instructions for PowerShell 7, Windows PowerShell 5.1, cmd, zsh, and fish. `forgerelay init` seeds exact-release-tag templates into the user config directory, preserves user edits, and projects loaded/disabled/unavailable state through the existing Workspace Instructions UI and context-delta path.
+
+### Security
+
+- ForgeRelay now refuses elevated root/Administrator/SYSTEM-equivalent runtime authority by default across supported platforms. Intentional elevated startup requires the invocation-scoped `--allow-elevated` acknowledgement and always exposes a mandatory Agent safety notice.
+
+## [0.9.4] - 2026-09-04
+
+### Added
+
+- Added owner-facing `forgerelay maintenance inspect` and `forgerelay maintenance prune` for the 0.9.4 retention contract. Durable Activity/Audit, Host Turn, and Bash history remains unlimited by default; configured retention is explicit prune authorization, whole Host Turn cohorts protect recent/nonterminal/running Bash/active Subagent work, and persistent Workspace identity, aliases, Task Lists, named checkpoints, managed worktrees/branches, and non-empty private Workspace state remain protected.
+- Added a runtime state lease so `serve` and destructive maintenance cannot operate on the same state directory concurrently. Retained Activity payloads sharing segments with pruned history are compacted before unreferenced old segments are removed, and repeat prune is idempotent.
+
+### Fixed
+
+- Made routed `publicBaseUrl` path prefixes real inbound MCP/OAuth/health/App deployment boundaries, split setup network modes into safe loopback proxy versus direct LAN binds, and replaced permissive proxy trust with explicit trusted proxy sources. This fixes reverse-proxy `X-Forwarded-For` failures without enabling spoofable global `trust proxy` behavior.
+
 ## [0.9.3] - 2026-09-04
 
 ### Added

package/README.md

@@ -55,8 +55,10 @@ http://127.0.0.1:7676/mcp
 
 If the MCP host cannot reach localhost, put ForgeRelay behind a public HTTPS
 tunnel or reverse proxy such as Cloudflare Tunnel, ngrok, Pinggy, Tailscale
-Funnel, or your own proxy. During setup, enter the public base URL before the
-final `/mcp`; routed prefixes are allowed:
+Funnel, or your own proxy. Setup separates **Direct LAN** (`0.0.0.0`) from
+**HTTPS reverse proxy / tunnel** (`127.0.0.1` with loopback-only proxy trust), so
+you do not need to choose a bind address manually. During setup, enter the public
+base URL before the final `/mcp`; routed prefixes are allowed:
 
 ```text
 https://your-tunnel-host.example.com/forgerelay/main
@@ -69,7 +71,11 @@ https://your-tunnel-host.example.com/forgerelay/main/mcp
 ```
 
 `publicBaseUrl` may also be an ordered list when multiple public entries are
-valid; each entry may use its own route and the first is canonical.
+valid; each entry may use its own route and the first is canonical for generated
+metadata/links. Every configured pathname is an accepted inbound operational route
+boundary. If the only configured route is `/forgerelay/main`, MCP/OAuth/health/App
+routes are served below that prefix rather than in parallel at naked `/mcp`,
+`/authorize`, or `/healthz` paths.
 
 ForgeRelay uses an Owner-password OAuth approval flow. `forgerelay init` prints
 the password and stores it in the active config directory. New installations use:
@@ -216,7 +222,7 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
 }
 ```
 
-命中 `BeforeTool` 后，Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。Hook 不运行、也不要求本地 CI。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。`npm run release:verify` 仅作为可选的本地云端复现工具。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+命中 `BeforeTool` 后，普通 tag push 的 Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。force release-tag push 始终拒绝。对于失败发布后显式执行的 `git push --delete origin vX.Y.Z`，Hook 仅在当前 HEAD 有有效 `release:verify` proof，且联网确认 npm 对应版本与 GitHub Release 都不存在时允许删除；任一不可撤回产物存在或远端状态无法确认都会拒绝。因此仅有 tag 时可以重建同版本，一旦 GitHub Release 或包仓库版本存在就进入不可变状态。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 

package/dist/cli/init.js

@@ -2,10 +2,13 @@ import { resolve } from "node:path";
 import * as prompts from "@clack/prompts";
 import { publicEndpointUrl } from "../mcp/oauth/public-url.js";
 import { expandHomePath } from "../mcp/filesystem/roots.js";
+import { detectLauncherCommandShell, } from "../runtime/shell/command-shell-runtime.js";
+import { seedShellInstructionFiles, shellInstructionFamiliesToSeed, } from "../runtime/instructions/shell-instructions.js";
 import { installManagedLanguageServers, installedManagedLanguageServers, managedLanguageServerOptions, } from "../lsp/runtime/managed-language-servers.js";
 import { generateInstanceId, generateOwnerToken, loadForgeRelayFiles, resolveSubagentsFlag, writeForgeRelayAuth, writeForgeRelayConfig, } from "../runtime/config/user-config.js";
-import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, SetupCancelledError, textPrompt, validateBindAddress, validateClientFacingBaseUrls, validatePort, } from "./setup-support.js";
-export async function runInit({ force }) {
+import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, setupBindAddress, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
+import { commandShellCompatibilityWarning, commandShellSetupOptions, customPinnedPreference, defaultCommandShellSetupChoice, followLauncherPreference, pinnedFamilyPreference, preservePinnedPreference, shellFamiliesForCustomSelection, } from "./shell/setup.js";
+export async function runInit({ force, version }) {
     const files = loadForgeRelayFiles();
     if (!force && files.configExists && files.authExists) {
         prompts.log.info(`ForgeRelay is already configured at ${files.dir}`);
@@ -36,9 +39,11 @@ export async function runInit({ force }) {
         const existingPublicBaseUrls = Array.isArray(files.config.publicBaseUrl)
             ? files.config.publicBaseUrl
             : files.config.publicBaseUrl ? [files.config.publicBaseUrl] : [];
-        const defaultNetworkMode = !isLoopbackBindAddress(files.config.host ?? "127.0.0.1") || existingPublicBaseUrls.length > 0
-            ? "network"
-            : "local";
+        const defaultNetworkMode = !isLoopbackBindAddress(files.config.host ?? "127.0.0.1")
+            ? "lan"
+            : existingPublicBaseUrls.some((baseUrl) => new URL(baseUrl).protocol === "https:")
+                ? "proxy"
+                : "local";
         const selectedMode = await prompts.select({
             message: "How should clients reach this ForgeRelay instance?",
             initialValue: defaultNetworkMode,
@@ -54,40 +59,53 @@ export async function runInit({ force }) {
                     hint: "Bind to loopback; another ForgeRelay reaches it through an SSH tunnel.",
                 },
                 {
-                    value: "network",
-                    label: "LAN / HTTPS proxy",
-                    hint: "Expose through a LAN address or an HTTPS reverse proxy/tunnel.",
+                    value: "lan",
+                    label: "Direct LAN",
+                    hint: "Bind to 0.0.0.0; clients connect directly over a trusted private LAN.",
+                },
+                {
+                    value: "proxy",
+                    label: "HTTPS reverse proxy / tunnel",
+                    hint: "Bind to 127.0.0.1; a local trusted proxy publishes the HTTPS endpoint.",
                 },
             ],
         });
         if (prompts.isCancel(selectedMode))
             throw new SetupCancelledError();
         const networkMode = selectedMode;
-        let host = "127.0.0.1";
+        const host = setupBindAddress(networkMode);
         let publicBaseUrl = null;
         let clientFacingBaseUrls = [`http://127.0.0.1:${port}`];
-        if (networkMode === "network") {
-            const defaultHost = files.config.host && !isLoopbackBindAddress(files.config.host)
-                ? files.config.host
-                : "0.0.0.0";
-            host = await textPrompt({
-                message: "Which address should ForgeRelay bind to? Use 0.0.0.0 for direct LAN, or 127.0.0.1 behind a local reverse proxy.",
-                placeholder: defaultHost,
-                defaultValue: defaultHost,
-                validate: validateBindAddress,
-            });
-            const defaultClientFacing = existingPublicBaseUrls.join(", ");
+        const trustedProxies = networkMode === "proxy" ? ["loopback"] : undefined;
+        if (networkMode === "lan" || networkMode === "proxy") {
+            const validateBaseUrls = networkMode === "lan"
+                ? validateLanClientFacingBaseUrls
+                : validateHttpsProxyBaseUrls;
+            const existingClientFacing = existingPublicBaseUrls.join(", ");
+            const defaultClientFacing = existingClientFacing && validateBaseUrls(existingClientFacing) === undefined
+                ? existingClientFacing
+                : "";
+            if (networkMode === "proxy") {
+                prompts.note([
+                    "The public URL may include a path prefix, for example https://example.com/forgerelay/debug.",
+                    "That prefix is the deployment route boundary, so MCP, OAuth, health, and App assets are served below it.",
+                ].join("\n"), "Routed public URL");
+            }
             clientFacingBaseUrls = normalizePublicBaseUrlsInput(await textPrompt({
                 message: defaultClientFacing
                     ? `What client-facing base URLs should clients use? Press Enter to keep ${defaultClientFacing}`
-                    : "What client-facing base URL should clients use?",
-                placeholder: defaultClientFacing || `http://192.168.1.20:${port} or https://forge.example.com`,
+                    : networkMode === "lan"
+                        ? "What direct LAN base URL should clients use?"
+                        : "What HTTPS public base URL should clients use?",
+                placeholder: defaultClientFacing || (networkMode === "lan"
+                    ? `http://192.168.1.20:${port}`
+                    : "https://example.com/forgerelay/debug"),
                 defaultValue: defaultClientFacing,
-                validate: validateClientFacingBaseUrls,
+                validate: validateBaseUrls,
             }));
             for (const baseUrl of clientFacingBaseUrls)
                 classifyClientFacingBaseUrl(baseUrl);
-            if (hasInsecureLanBaseUrl(clientFacingBaseUrls)) {
+            if (networkMode === "lan" && hasInsecureLanBaseUrl(clientFacingBaseUrls)) {
                 prompts.note([
                     "Plain HTTP does not encrypt the ForgeRelay Owner approval flow or MCP bearer tokens.",
                     "Use this only on a trusted private LAN. Prefer SSH relay or HTTPS when the network is not fully trusted.",
@@ -101,6 +119,64 @@ export async function runInit({ force }) {
             }
             publicBaseUrl = compactPublicBaseUrlConfig(clientFacingBaseUrls);
         }
+        const launcherShell = detectLauncherCommandShell();
+        const selectedShellChoice = await prompts.select({
+            message: "Which command shell should Agent commands and Hooks use?",
+            initialValue: defaultCommandShellSetupChoice(files.config.commandShell),
+            options: commandShellSetupOptions(process.platform, files.config.commandShell, launcherShell),
+        });
+        if (prompts.isCancel(selectedShellChoice))
+            throw new SetupCancelledError();
+        let commandShell;
+        const shellChoice = selectedShellChoice;
+        if (shellChoice === "follow-launcher") {
+            commandShell = followLauncherPreference(files.config.commandShell, launcherShell);
+        }
+        else if (shellChoice === "keep-pinned") {
+            commandShell = preservePinnedPreference(files.config.commandShell);
+        }
+        else if (shellChoice === "custom") {
+            const customFamily = await prompts.select({
+                message: "Which command language does the custom executable implement?",
+                options: shellFamiliesForCustomSelection(),
+            });
+            if (prompts.isCancel(customFamily))
+                throw new SetupCancelledError();
+            const executable = await textPrompt({
+                message: "What is the command-shell executable path?",
+                placeholder: process.platform === "win32" ? "D:\\Portable\\PowerShell\\pwsh.exe" : "/opt/custom/bin/zsh",
+                defaultValue: "",
+                validate: (value) => value?.trim() ? undefined : "Enter an executable path.",
+            });
+            commandShell = customPinnedPreference(customFamily, executable);
+        }
+        else {
+            commandShell = pinnedFamilyPreference(shellChoice);
+        }
+        const shellWarning = commandShellCompatibilityWarning(commandShell.family);
+        if (shellWarning)
+            prompts.note(shellWarning, "Command shell compatibility");
+        const shellInstructionFamilies = shellInstructionFamiliesToSeed(process.platform, commandShell.family);
+        let shellInstructions = files.config.shellInstructions;
+        let shellInstructionSeedResults = [];
+        if (shellInstructionFamilies.length > 0) {
+            const shellInstructionsAnswer = await prompts.confirm({
+                message: "Load ForgeRelay-provided extra Instructions for this command shell?",
+                initialValue: files.config.shellInstructions !== false,
+            });
+            if (prompts.isCancel(shellInstructionsAnswer))
+                throw new SetupCancelledError();
+            shellInstructions = shellInstructionsAnswer === true;
+            shellInstructionSeedResults = await seedShellInstructionFiles({
+                configDir: files.dir,
+                version,
+                families: shellInstructionFamilies,
+            });
+            const failedShellInstructions = shellInstructionSeedResults.filter((result) => result.status === "failed");
+            if (failedShellInstructions.length > 0) {
+                prompts.note(failedShellInstructions.map((result) => `${result.family}: ${result.error ?? "download failed"}\n${result.sourceUrl}`).join("\n\n"), "Shell Instructions unavailable");
+            }
+        }
         const installedManaged = installedManagedLanguageServers(files.dir);
         const selectedManaged = await prompts.multiselect({
             message: "Which Language Servers should ForgeRelay manage with npm?",
@@ -135,13 +211,17 @@ export async function runInit({ force }) {
             }
         }
         const config = {
+            ...files.config,
             host,
             port,
             allowedRoots,
             publicBaseUrl,
             allowedHosts: files.config.allowedHosts,
+            trustedProxies,
             workflowInstructions: files.config.workflowInstructions,
             appendInstructions: files.config.appendInstructions,
+            commandShell,
+            shellInstructions,
             subagents: resolveSubagentsFlag(files.config),
             languageServers: files.config.languageServers,
             allowAgentLanguageServerInstall,
@@ -157,6 +237,13 @@ export async function runInit({ force }) {
             `Config: ${configPath}`,
             `Auth: ${authPath}`,
             `Bind: http://${config.host}:${config.port}`,
+            `Command shell: ${commandShell.mode} ${commandShell.family} (${commandShell.executable})`,
+            ...(shellInstructionFamilies.length > 0
+                ? [
+                    `Shell Instructions: ${shellInstructions ? "enabled" : "disabled"}`,
+                    ...shellInstructionSeedResults.map((result) => `Shell Instructions ${result.family}: ${result.status} (${result.path})`),
+                ]
+                : []),
             ...clientFacingBaseUrls.map((baseUrl, index) => `${index === 0 ? "Client-facing MCP URL" : "Client-facing MCP alias"}: ${publicEndpointUrl(baseUrl, "mcp").toString()}`),
         ];
         if (networkMode === "ssh") {