@akira-tl/forgerelay 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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
+
+- Extended `workspace.checkpoint` with `restore.preflight` and optimistic-concurrency-protected `restore`. Restore uses deterministic Git-visible working-tree snapshot identities, refuses stale preflight tokens before mutation, restores content without moving branch HEAD or rewriting history, leaves ignored files outside the restore model, does not reconstruct staged-versus-unstaged state, remains independent from managed-worktree recovery, and routes through the owning Execution ForgeRelay / explicit Composite member.
+
 ## [0.9.2] - 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:

package/capabilities/workspace/workspace-checkpoints/GUIDE.md

@@ -2,16 +2,18 @@
 
 `workspace.checkpoint` provides low-frequency, persistent checkpoints owned by the current filesystem Workspace. Checkpoints are immutable Git-backed snapshots intended for deliberate recovery/history workflows.
 
-## v0.9.2 surface
+## v0.9.3 surface
 
-Supported operations are deliberately limited to:
+Supported operations are:
 
 - `create` — create a named immutable checkpoint of the current Git-visible working tree.
-- `list` — return bounded checkpoint metadata, newest identity preserved in creation order.
+- `list` — return bounded checkpoint metadata, preserving checkpoint creation order.
 - `inspect` — return bounded metadata for one checkpoint.
+- `restore.preflight` — identify the selected checkpoint content snapshot and the current Git-visible working snapshot without mutating files.
+- `restore` — restore checkpoint content only when the caller supplies the still-current snapshot identity returned by preflight.
 - `delete` — explicitly delete one checkpoint and its ForgeRelay-owned Git ref.
 
-Restore is **not** part of v0.9.2. Do not emulate restore with checkout/reset or other destructive Git commands unless the user separately and explicitly asks for such Git work outside this Capability.
+Restore is deliberately a two-step optimistic-concurrency operation. Do not replace it with checkout/reset, hidden merge/rebase behavior, or branch-history rewrites.
 
 ## Create
 
@@ -53,6 +55,35 @@ Use `inspect` only after selecting an id:
 
 `list` and `inspect` expose bounded metadata only. Checkpoints do not move when `review.changes` advances its independent last-shown baseline.
 
+## Restore preflight and restore
+
+First preflight the selected checkpoint:
+
+```json
+{
+  "operation": "restore.preflight",
+  "checkpointId": "cp_0123456789"
+}
+```
+
+The result includes `checkpointSnapshot`, the immutable Git tree identity selected for restore, plus `currentSnapshot`, the deterministic Git tree identity of the current Git-visible working content. It also includes a bounded `restoreSummary`. Preflight does not mutate the Workspace.
+
+Then pass that exact `currentSnapshot` back as `expectedCurrentSnapshot`:
+
+```json
+{
+  "operation": "restore",
+  "checkpointId": "cp_0123456789",
+  "expectedCurrentSnapshot": "0123456789abcdef0123456789abcdef01234567"
+}
+```
+
+Immediately before applying content changes ForgeRelay recomputes the current Git-visible working snapshot. If it no longer matches `expectedCurrentSnapshot`, restore fails before mutation and the intervening edits remain untouched. Run preflight again before deciding whether to retry.
+
+A successful restore writes only ordinary working-tree content needed to reproduce the checkpoint's Git-visible tree. It does **not** move branch `HEAD`, rewrite commit history, merge/rebase, auto-commit, or use `git reset --hard` semantics. Ignored files remain outside the checkpoint/restore content model and are not intentionally changed.
+
+The 0.9 restore contract is **content-state only**. ForgeRelay does not reconstruct or promise the historical staged-versus-unstaged partition. Restore does not rewrite the real Git index; existing staging state may therefore differ from the restored working-tree content and should be inspected normally with Git afterward. Results expose `stagingStateRestored: false` to make this explicit.
+
 ## Delete
 
 Deletion is explicit:

package/dist/cli/init.js

@@ -4,7 +4,7 @@ import { publicEndpointUrl } from "../mcp/oauth/public-url.js";
 import { expandHomePath } from "../mcp/filesystem/roots.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";
+import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, setupBindAddress, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
 export async function runInit({ force }) {
     const files = loadForgeRelayFiles();
     if (!force && files.configExists && files.authExists) {
@@ -36,9 +36,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 +56,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.",
@@ -140,6 +155,7 @@ export async function runInit({ force }) {
             allowedRoots,
             publicBaseUrl,
             allowedHosts: files.config.allowedHosts,
+            trustedProxies,
             workflowInstructions: files.config.workflowInstructions,
             appendInstructions: files.config.appendInstructions,
             subagents: resolveSubagentsFlag(files.config),