@akira-tl/forgerelay 0.9.2 → 0.9.4

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -52,7 +52,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/runtime/state/runtime-lease.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/maintenance.test.ts && tsx src/cli/maintenance-prune.test.ts && tsx src/cli/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/ci/architecture.mjs

@@ -9,6 +9,13 @@ const MAX_DIRECT_FILES = 8;
 const MAX_DIRECT_DIRS = 8;
 const LINE_LIMIT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs", ".css"]);
 
+// Append-only versioned archives grow by design and must keep their canonical
+// flat paths for release tooling and stable links. They remain subject to all
+// other architecture checks, including code line limits where applicable.
+const DIRECT_FILE_LIMIT_EXEMPT_DIRS = new Set([
+  "docs/releases",
+]);
+
 // Repository-root protocol files are intentionally discoverable by Git, npm,
 // Node, Vite, contributors, and agents. Keep that conventional surface explicit
 // instead of hiding required/default-discovery files merely to satisfy a count.
@@ -67,7 +74,7 @@ const directories = new Set([...directFiles.keys(), ...directDirs.keys()]);
 for (const directory of [...directories].sort()) {
   const files = directFiles.get(directory) ?? 0;
   const dirs = directDirs.get(directory)?.size ?? 0;
-  if (directory !== "." && files > MAX_DIRECT_FILES) {
+  if (directory !== "." && !DIRECT_FILE_LIMIT_EXEMPT_DIRS.has(directory) && files > MAX_DIRECT_FILES) {
     violations.push(`${directory}: ${files} direct files > ${MAX_DIRECT_FILES}`);
   }
   if (dirs > MAX_DIRECT_DIRS) {
@@ -83,7 +90,7 @@ if (violations.length > 0) {
 
 console.log(
   `Architecture check passed: ${tracked.length} tracked files; ` +
-  `code <= ${MAX_LINES} lines; non-root directories <= ${MAX_DIRECT_FILES} files / ${MAX_DIRECT_DIRS} directories.`,
+  `code <= ${MAX_LINES} lines; bounded non-root directories <= ${MAX_DIRECT_FILES} files / ${MAX_DIRECT_DIRS} directories.`,
 );
 
 function gitTrackedFiles() {

package/scripts/release/release-gate.test.mjs

@@ -60,6 +60,12 @@ test("cross-platform cloud CI delegates to one shell-free verification entrypoin
   }
 });
 
+test("architecture gate treats the append-only release-note archive as an explicit flat-path exception", async () => {
+  const architecture = await readFile(resolve(repoRoot, "scripts/ci/architecture.mjs"), "utf8");
+  assert.match(architecture, /DIRECT_FILE_LIMIT_EXEMPT_DIRS/);
+  assert.match(architecture, /"docs\/releases"/);
+});
+
 test("release runtime and local parity share the checked-in Node contract", async () => {
   const nodeVersion = (await readFile(resolve(repoRoot, ".nvmrc"), "utf8")).trim();
   assert.equal(nodeVersion, "22.19.0");