@akira-tl/forgerelay 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.2.5] - 2026-09-16
+
+### Changed
+
+- Config v2 现在把监听端口的支持范围统一为 `1`–`65535`，并让 JSON Schema、环境变量、`init --advanced`、持久化写入、迁移与运行时使用同一验证约束；External MCP OAuth `callbackPort` 继续保持独立的 `1024`–`65535` 范围。
+- 初始化只持久化用户真正选择的网络 override；HTTPS proxy 场景不再重复写入可从 loopback bind 与 public URL 安全推导的 `trustedProxies: ["loopback"]`。
+
+### Fixed
+
+- `config.json` 写入与 legacy migration 现在会在持久化前通过 Config v2 schema 校验，避免 CLI 或迁移先写出运行时随后拒绝的非法配置；迁移遇到非法 General Config 时会在创建 canonical target 或 backup 之前失败。
+- 明确 `host` / `port`、`publicBaseUrl`、`allowedHosts` 与 `trustedProxies` 的配置权威关系：显式用户值始终优先，派生值只在对应 override 缺失时生效。
+
+## [1.2.4] - 2026-09-15
+
+### Added
+
+- Managed worktrees can now start from arbitrary Git commit-ish refs while keeping their integration target branch independent, so a pinned historical baseline no longer has to be a local branch.
+
+### Changed
+
+- Release verification now splits more independent CI work in parallel and reuses pinned npm / packaged shell runtime state where safe, reducing repeated setup in the cross-platform release matrix.
+
+### Fixed
+
+- Pinned-base managed worktrees now preserve their baseline metadata across reuse, reopen, recovery, rebase, and close, while still integrating into the configured target branch; pinned workspaces with different immutable baselines no longer collapse onto one reuse identity.
+- Workspace Panel long paths now wrap instead of truncating important Root / checkout details, and Workspace identity color is shared consistently between pretty logs and Panel SVG icons. The identity palette now uses 14 normal/bright terminal color slots, avoids duplicates for the first 14 distinct Workspace names in one process, and normalizes both POSIX and Windows-style paths consistently.
+
 ## [1.2.3] - 2026-09-14
 
 ### Fixed

package/README.md

@@ -64,7 +64,7 @@ forgerelay config sources
 forgerelay config explain <logical-path>
 ```
 
-v1.2 的 Config System 统一解析 User、Project 和机器私有 Project Local 配置，统一优先级是 `runtime > project-local > project > user > built-in`。External MCP、Language Servers、Hooks 和 Subagent Profiles 支持按需热刷新与 last-known-good；需要重启的 General 配置会区分 configured / applied，不会自动重启 Server。Canonical JSON 可以引用 npm package 中的 `schemas/v1/*` `$schema`，受支持的敏感字段可用 `${ENV_NAME}`，诊断不会输出解析后的 secret。ForgeRelay 启动不会自动重写旧配置，需要迁移时使用 `forgerelay config migrate --dry-run ...` 先预览。
+ForgeRelay 的 Config System 统一解析 User、Project 和机器私有 Project Local 配置，优先级是 `runtime > project-local > project > user > built-in`。External MCP、Language Servers、Hooks 和 Subagent Profiles 支持按需刷新与 last-known-good；启动不会自动重写旧配置。需要深入配置、迁移或排查来源时，直接看 [配置指南](https://github.com/Akira-TL/forgerelay/wiki/Configuration)。
 
 ### ChatGPT 访问不到 localhost？
 
@@ -100,9 +100,9 @@ bash(command="npm test")
 bash(command="git status --short")
 ```
 
-ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔离或并行开发时，才使用 managed worktree。
+ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔离或并行开发时，才使用 managed worktree。Worktree 可以从本地 branch、tag 或历史 commit SHA 启动，同时把最终集成的本地 `targetBranch` 单独记录；不需要为了历史基线先造一个临时 branch。
 
-长命令也不会要求 Agent 高频轮询。命令超过当前等待窗口时会返回稳定的 `processId`，后续继续等待或中断同一个进程即可。
+长命令也不会要求 Agent 高频轮询。命令超过当前等待窗口时会返回稳定的 `processId`，后续继续等待、交互或中断同一个进程即可。
 
 ## 主要能力
 
@@ -110,8 +110,9 @@ ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔
 - Linux / macOS 可以用 Bash、zsh、POSIX sh；Windows 原生支持 PowerShell 7、Windows PowerShell 5.1 和 `cmd.exe`。
 - 同一个 checkout 会保留自己的 Workspace 身份。换一次对话，不需要重新创建工作区。
 - `code.intelligence` 可以查 definition、hover、references、symbols 和 diagnostics。
-- 项目里的 `AGENTS.md`、`CLAUDE.md` 和 Agent Skills 按需加载，不会每次都把整套说明重新塞进上下文。
-- 需要并行开发时可以创建真实 Git worktree；集成回主分支时只接受安全的 fast-forward，不自动制造 merge conflict。
+- 项目里的 `AGENTS.md`、`CLAUDE.md` 和 Agent Skills 按需加载，不会每次都把整套说明重新塞进上下文。Skill 来自项目级 `.agents/skills`、项目/系统 ForgeRelay Skills 和显式附加路径；不会自动扫描全局 `~/.agents/skills`。
+- 需要并行开发时可以创建真实 Git worktree；起始 commit 与最终 `targetBranch` 独立，集成仍只接受安全的 fast-forward，不自动制造 merge conflict。
+- 支持 MCP Apps 的 Host 会显示 Workspace Summary / Activity Panel；Workspace 身份色在 Panel 与 pretty log 中保持一致，长路径会在详情区正常换行。
 - Workspace Relay 可以把执行放到另一台 ForgeRelay；Composite Workspace 可以同时协调几个独立环境。
 - `read` 可以直接把 PNG、JPEG、WebP 和 GIF 作为临时 MCP Media content 返回；外部 MCP 通过独立的 global/Project `mcp.json` 热加载到 `mcp.external` Capability，并支持人工 OAuth 认证，而不会自动打开它返回的路径或 URL。
 
@@ -125,7 +126,7 @@ ForgeRelay 给 Agent 的是真实本机执行权限，不是模拟环境。
 
 文件工具受 Workspace 和 allowed roots 限制；Shell 命令使用启动 ForgeRelay 的本地用户权限执行，**Shell 不是 OS sandbox**。因此只连接你信任的 MCP Host，只开放确实需要的项目目录，并保护好 Owner password。
 
-Allowed roots 是文件系统 / Workspace authority，不等于 Project Trust approval。v1.2.0 已把项目中的可执行配置统一接入 Project execution trust seam，但首个稳定策略是 compatibility-allow；完整的交互式 Project Trust approval UI 不是 v1.2.0 已实现功能。
+Allowed roots 是文件系统 / Workspace authority，不等于 Project Trust approval。项目中的可执行配置已经统一接入 Project execution trust seam；当前稳定策略仍是 compatibility-allow，完整的交互式 Project Trust approval UI 尚未实现。
 
 ForgeRelay 默认拒绝 elevated / administrator 启动。只有你显式选择高权限运行时才会继续，并会提示系统级修改可能不可逆。
 
@@ -135,6 +136,8 @@ ForgeRelay 默认拒绝 elevated / administrator 启动。只有你显式选择
 
 - [快速开始](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)
 - [配置](https://github.com/Akira-TL/forgerelay/wiki/Configuration)
+- [Managed Worktree](https://github.com/Akira-TL/forgerelay/wiki/Managed-Worktrees)
+- [ChatGPT 与 MCP 工作流](https://github.com/Akira-TL/forgerelay/wiki/ChatGPT-and-MCP-Workflow)
 - [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)
 - [安全模型](https://github.com/Akira-TL/forgerelay/wiki/Security)
 - [故障排查](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)
@@ -185,7 +188,7 @@ forgerelay config sources
 forgerelay config explain <logical-path>
 ```
 
-Config System v2 in v1.2 resolves User, Project, and machine-private Project Local sources using `runtime > project-local > project > user > built-in`. External MCP, Language Servers, Hooks, and Subagent Profiles refresh on demand with last-known-good protection; restart-required General settings keep configured and applied values distinct and never auto-restart the server. Canonical JSON can point at the packaged `schemas/v1/*` `$schema` files, supported sensitive fields may use `${ENV_NAME}`, and diagnostics do not expose resolved secrets. Startup never rewrites legacy configuration automatically; preview an explicit migration with `forgerelay config migrate --dry-run ...` first.
+ForgeRelay's Config System resolves User, Project, and machine-private Project Local sources using `runtime > project-local > project > user > built-in`. External MCP, Language Servers, Hooks, and Subagent Profiles refresh on demand with last-known-good protection, and startup never rewrites legacy configuration automatically. See [Configuration](https://github.com/Akira-TL/forgerelay/wiki/Configuration) for scopes, migration, schemas, and diagnostics.
 
 ### Host cannot reach localhost?
 
@@ -221,7 +224,7 @@ bash(command="npm test")
 bash(command="git status --short")
 ```
 
-ForgeRelay does not create a worktree for every task. Managed worktrees are for cases where you explicitly want isolation or parallel development.
+ForgeRelay does not create a worktree for every task. Managed worktrees are for cases where you explicitly want isolation or parallel development. A worktree may start from a local branch, tag, or historical commit SHA while keeping the eventual local `targetBranch` separate, so a temporary baseline branch is unnecessary.
 
 Long commands do not require tight polling either. Once the current wait window expires, ForgeRelay returns a stable `processId`; later calls wait on, interact with, or interrupt that same process.
 
@@ -231,8 +234,9 @@ Long commands do not require tight polling either. Once the current wait window
 - Linux/macOS can use Bash, zsh, or POSIX sh. Windows has native PowerShell 7, Windows PowerShell 5.1, and `cmd.exe` support.
 - Reopening the same checkout reuses the same Workspace identity instead of creating another one for every conversation.
 - `code.intelligence` provides definition, hover, references, symbols, and diagnostics.
-- `AGENTS.md`, `CLAUDE.md`, and Agent Skills are loaded as needed instead of being resent in full on every open.
-- Managed worktrees provide real Git isolation when you ask for parallel work, with fast-forward-only finalization.
+- `AGENTS.md`, `CLAUDE.md`, and Agent Skills are loaded as needed instead of being resent in full on every open. Skills come from project `.agents/skills`, project/system ForgeRelay Skill directories, and explicit extra paths; global `~/.agents/skills` is not scanned automatically.
+- Managed worktrees provide real Git isolation when you ask for parallel work. Starting commit and local `targetBranch` are tracked independently, while finalization remains fast-forward-only.
+- MCP Apps-capable hosts can render the Workspace Summary / Activity Panel. Workspace identity colors stay consistent between the panel and pretty logs, and long paths wrap in detail rows instead of hiding their tail.
 - Workspace Relay runs work on another ForgeRelay instance; Composite Workspaces coordinate several independent environments from one Host.
 - `read` can return PNG, JPEG, WebP, and GIF directly as transient MCP Media content; external MCP servers hot-reload from standalone global/Project `mcp.json` files into the `mcp.external` Capability, with explicit human OAuth when needed and no automatic dereferencing of returned paths or URLs.
 
@@ -246,7 +250,7 @@ ForgeRelay gives an Agent real local execution capability.
 
 Filesystem tools are constrained by the opened Workspace and configured allowed roots. Shell commands run with the authority of the local user running ForgeRelay; **the shell is not an OS sandbox**. Connect only MCP hosts you trust, expose only project roots you want an Agent to access, and keep the Owner password private.
 
-Allowed roots grant filesystem/Workspace authority; they are not a Project Trust approval. v1.2.0 routes executable project configuration through a shared Project execution trust seam, but its initial policy is compatibility-allow. A full interactive Project Trust approval UI is not claimed for v1.2.0.
+Allowed roots grant filesystem/Workspace authority; they are not a Project Trust approval. Executable project configuration is routed through a shared Project execution trust seam; the current stable policy remains compatibility-allow, and a full interactive Project Trust approval UI is not implemented yet.
 
 Elevated / administrator startup is rejected by default. It only proceeds after explicit opt-in, with a warning that system-level AI-driven changes may be irreversible.
 
@@ -256,6 +260,8 @@ See the [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security) f
 
 - [Getting Started](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)
 - [Configuration](https://github.com/Akira-TL/forgerelay/wiki/Configuration)
+- [Managed Worktrees](https://github.com/Akira-TL/forgerelay/wiki/Managed-Worktrees)
+- [ChatGPT and MCP Workflow](https://github.com/Akira-TL/forgerelay/wiki/ChatGPT-and-MCP-Workflow)
 - [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)
 - [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security)
 - [Troubleshooting](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)
@@ -276,3 +282,5 @@ npm run build
 ```
 
 `npm run dev` uses the 7677 debug runtime. Product port 7676 is kept separate from development acceptance.
+
+Release tags are created only after a developer has manually exercised and explicitly accepted the exact release-ready state. Automated verification and the Linux/macOS/Windows release matrix remain additional gates; they do not replace manual acceptance.

package/capabilities/workspace/managed-worktrees/GUIDE.md

@@ -15,8 +15,10 @@
 
 - 默认 `mode="checkout"`，直接使用用户已有 checkout；
 - 只有明确需要隔离/并行 Git 工作时才选 `mode="worktree"`；
-- `baseRef` 只用于 managed worktree，默认取 source checkout 当前分支；
-- 已有 `workspaceId` 用于恢复同一个逻辑 workspace；
+- `baseRef` 只用于 managed worktree，表示新 managed branch 的起始 commit-ish；可以是本地 branch、tag、commit SHA 等可解析到 commit 的 ref，默认使用 source checkout 当前 `HEAD`；
+- `targetBranch` 表示最终允许 `close_workspace` fast-forward 的本地 branch；未显式指定时，本地 branch `baseRef` 自身优先作为 target，否则使用 source checkout 当前本地 branch；detached source 无法推导 target 时必须显式提供；
+- 显式固定到历史 base 的请求按解析后的 `baseSha` 区分复用身份，不会与同一 target 上另一历史 base 或普通 branch-following backing 混用；
+- 已有 `workspaceId` 用于恢复同一个逻辑 workspace；closed managed-worktree Workspace reopen 时从当前持久化 `targetBranch` 建立新 backing，不重新钉回最初的历史 `baseRef`；
 - `newWorkspace` 只创建新的逻辑 handle；
 - `newWorktree` 才表示同一项目再创建一个独立物理 worktree。
 

package/dist/cli/config/migrate.js

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { parseConfigSource } from "../../runtime/config/definition/definition.js";
 import { configSchemaId } from "../../runtime/config/definition/schema.js";
 import { generalConfigDefinition } from "../../runtime/config/definition/general-config.js";
 import { externalMcpConfigDefinition } from "../../runtime/config/definition/external-mcp.js";
@@ -137,8 +138,10 @@ function buildGlobalMigrationPlan(configDir) {
         nextConfig.$schema = generalSchema;
         configChanged = true;
     }
-    if (configChanged)
-        writes.push(jsonWrite(files.configPath, nextConfig));
+    if (configChanged) {
+        const validatedConfig = parseConfigSource(generalConfigDefinition, "user", nextConfig);
+        writes.push(jsonWrite(files.configPath, validatedConfig));
+    }
     if (configChanged && files.configExists)
         backupSources.push({ path: files.configPath, relativePath: "config.json" });
     if (files.hooksExists)

package/dist/cli/init/setup-config.js

@@ -21,8 +21,6 @@ function applyNetworkSelection(config, selection) {
         }
         config.publicBaseUrl = selection.publicBaseUrl;
     }
-    if (selection.mode === "proxy")
-        config.trustedProxies = ["loopback"];
 }
 function applyAdvancedSelection(config, selection) {
     if (selection.port === 7676)

package/dist/cli/setup-support.js

@@ -2,6 +2,7 @@ import { isIP } from "node:net";
 import { createRequire } from "node:module";
 import * as prompts from "@clack/prompts";
 import { satisfies } from "semver";
+import { isIntegerPort, LISTEN_PORT_MIN, PORT_MAX } from "../runtime/config/validation/ports.js";
 const SUPPORTED_NODE_RANGE = ">=20.12 <27";
 const require = createRequire(import.meta.url);
 export function isNullConfigValue(value) {
@@ -118,9 +119,9 @@ export async function textPrompt(options) {
 }
 export function validatePort(value) {
     const port = Number(value);
-    return Number.isInteger(port) && port >= 1 && port <= 65535
+    return isIntegerPort(port, LISTEN_PORT_MIN, PORT_MAX)
         ? undefined
-        : "Enter a port between 1 and 65535.";
+        : `Enter a port between ${LISTEN_PORT_MIN} and ${PORT_MAX}.`;
 }
 export function isLoopbackBindAddress(value) {
     const host = value.trim().toLowerCase();

package/dist/mcp/server/core/schemas.js

@@ -122,6 +122,8 @@ export const workspaceInventoryEntryOutputSchema = z.object({
     state: z.enum(["active", "stale", "invalid", "closed"]),
     mode: z.enum(["checkout", "worktree"]),
     sourceRoot: z.string().optional(),
+    baseRef: z.string().optional(),
+    baseSha: z.string().optional(),
     branch: z.string().optional(),
     targetBranch: z.string().optional(),
     managed: z.boolean(),
@@ -181,6 +183,8 @@ export const workspaceInspectionOutputSchema = z.union([
         state: z.enum(["active", "stale", "invalid", "closed"]),
         mode: z.enum(["checkout", "worktree"]),
         sourceRoot: z.string().optional(),
+        baseRef: z.string().optional(),
+        baseSha: z.string().optional(),
         branch: z.string().optional(),
         targetBranch: z.string().optional(),
         managed: z.boolean(),
@@ -201,6 +205,8 @@ export const workspaceInspectionOutputSchema = z.union([
         state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
         mode: z.enum(["checkout", "worktree"]),
         sourceRoot: z.string().optional(),
+        baseRef: z.string().optional(),
+        baseSha: z.string().optional(),
         branch: z.string().optional(),
         targetBranch: z.string().optional(),
         managed: z.boolean().optional(),

package/dist/mcp/server/workspace/runtime/workspace-open-presentation.js

@@ -10,13 +10,14 @@ import { capabilityContextFor } from "../../core/capability-support.js";
 import { redactSkillDiagnosticPaths } from "../../core/schemas.js";
 import { logToolCall, workspaceLogContext } from "../../core/tool-support.js";
 import { buildExecutionShellContext } from "../../../server-instructions.js";
+import { workspaceColorFor, workspaceIdentityName } from "../../../../workspace-colors.js";
 export const workspaceTaskUsageInstruction = "Use workspace.tasks proactively for work that spans multiple steps or sessions: create or update Tasks to preserve useful next steps and current state, and read its summary when resuming relevant unfinished work. Do not query it mechanically on every open_workspace call.";
 export const capabilityDiscoveryInstruction = "For capability describe/run, use only names present in capabilityCatalog. capabilityFingerprint.capabilities is a semantic feature fingerprint, not a callable registry; capabilityGuides are documentation descriptors, not callable capabilities.";
 export async function presentLocalWorkspaceOpen(options, input, contextData) {
     const { config, forgerelayVersion: FORGERELAY_VERSION, workspaces, workspaceTasks, reviewCheckpoints, capabilityRegistry, subagentProviders, hooks, rememberWorkspacePanelState, } = options;
-    const { path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context } = input;
+    const { path, workspaceId, mode, baseRef, targetBranch, newWorktree, newWorkspace, context } = input;
     const { conversationScopeId, protectedWorkspaceIds, startedAt, sessionId } = contextData;
-    const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, bootstrapContextComponents, contextFingerprint, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context }, {
+    const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, bootstrapContextComponents, contextFingerprint, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, targetBranch, newWorktree, newWorkspace, context }, {
         conversationScopeId,
         protectedWorkspaceIds,
     });
@@ -189,6 +190,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
         kind: "workspace",
         root: workspace.root,
         path: workspace.root,
+        workspaceColor: workspaceColorFor(workspaceIdentityName(workspace.root)),
         mode: workspace.mode,
         workspaceReused,
         includeBootstrapContext: effectiveIncludeBootstrapContext,

package/dist/mcp/server/workspace/runtime/workspace-open-schema.js

@@ -21,6 +21,7 @@ export const openWorkspaceToolDefinition = {
             relay: z.string().optional().describe("Optional registered remote ForgeRelay alias for a path-backed member."),
             mode: z.enum(["checkout", "worktree"]).optional(),
             baseRef: z.string().optional(),
+            targetBranch: z.string().optional(),
             newWorktree: z.boolean().optional(),
             newWorkspace: z.boolean().optional(),
         }).optional().describe("Composite member definition used by action=member."),
@@ -55,7 +56,11 @@ export const openWorkspaceToolDefinition = {
         baseRef: z
             .string()
             .optional()
-            .describe("Local branch to base a managed worktree on and eventually merge back into. Only used with mode=\"worktree\". Defaults to the source checkout's current branch."),
+            .describe("Commit-ish to base a managed worktree on. Only used with mode=\"worktree\"; may be a local branch, tag, commit SHA, or other ref that resolves to a commit. Defaults to HEAD."),
+        targetBranch: z
+            .string()
+            .optional()
+            .describe("Existing local branch that close_workspace may fast-forward when finalizing the managed worktree. Only used with mode=\"worktree\". Defaults to baseRef when baseRef names a local branch, otherwise the source checkout's current local branch."),
         newWorktree: z
             .boolean()
             .optional()

package/dist/mcp/server/workspace/runtime/workspace-open.js

@@ -4,6 +4,7 @@ import { formatPathForPrompt } from "../../../../workspaces/resources/skills.js"
 import { compositeCapabilityContext } from "../../core/capability-support.js";
 import { compositeWorkspaceLogContext, logToolCall, textBlock } from "../../core/tool-support.js";
 import { openWorkspaceToolDefinition } from "./workspace-open-schema.js";
+import { workspaceColorFor, workspaceIdentityName } from "../../../../workspace-colors.js";
 import { presentLocalWorkspaceOpen, workspaceTaskUsageInstruction, } from "./workspace-open-presentation.js";
 export function registerOpenWorkspaceTool(options) {
     const { server } = options;
@@ -11,7 +12,7 @@ export function registerOpenWorkspaceTool(options) {
 }
 async function handleOpenWorkspace(options, input, requestContext) {
     const { config, workspaces, remoteWorkspaces, compositeWorkspaces, workspaceTasks, processSessions, capabilityRegistry, compositeTaskGuides, loadCompositeMemberContext, rememberWorkspacePanelState, hostScopeIdFor, contextDeliveryScopeIdFor, presentation, } = options;
-    const { action = "open", memberAction, member, kind, name, memberName, path, relay, workspaceId, mode, baseRef, newWorktree, newWorkspace, context, root, status, state, staleOnly, offset, limit, } = input;
+    const { action = "open", memberAction, member, kind, name, memberName, path, relay, workspaceId, mode, baseRef, targetBranch, newWorktree, newWorkspace, context, root, status, state, staleOnly, offset, limit, } = input;
     const startedAt = performance.now();
     const conversationScopeId = contextDeliveryScopeIdFor(requestContext);
     const protectedWorkspaceIds = processSessions.activeWorkspaceIds();
@@ -82,7 +83,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
         }
         if (memberAction !== undefined || member !== undefined || kind !== undefined || name !== undefined ||
             memberName !== undefined || path !== undefined || relay !== undefined || mode !== undefined ||
-            baseRef !== undefined || newWorktree !== undefined || newWorkspace !== undefined || context !== undefined ||
+            baseRef !== undefined || targetBranch !== undefined || newWorktree !== undefined || newWorkspace !== undefined || context !== undefined ||
             root !== undefined || status !== undefined || state !== undefined || staleOnly !== undefined ||
             offset !== undefined || limit !== undefined) {
             throw new Error("open_workspace action=inspect accepts only workspaceId. It never opens, resumes, binds, or mutates the inspected Workspace.");
@@ -156,7 +157,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
             throw new Error("open_workspace action=member requires memberAction and member.");
         }
         if (kind !== undefined || name !== undefined || memberName !== undefined || path !== undefined || relay !== undefined || mode !== undefined ||
-            baseRef !== undefined || newWorktree !== undefined || newWorkspace !== undefined || context !== undefined ||
+            baseRef !== undefined || targetBranch !== undefined || newWorktree !== undefined || newWorkspace !== undefined || context !== undefined ||
             root !== undefined || status !== undefined || state !== undefined || staleOnly !== undefined ||
             offset !== undefined || limit !== undefined) {
             throw new Error("open_workspace action=member accepts workspaceId, memberAction, and member only. Put any Workspace open definition inside member.");
@@ -173,8 +174,8 @@ async function handleOpenWorkspace(options, input, requestContext) {
                     throw new Error("A Composite Workspace cannot be mounted as a Composite Workspace member.");
                 }
                 if (member.relay !== undefined || member.mode !== undefined || member.baseRef !== undefined ||
-                    member.newWorktree !== undefined || member.newWorkspace !== undefined) {
-                    throw new Error("member.workspaceId cannot be combined with relay/mode/baseRef/newWorktree/newWorkspace.");
+                    member.targetBranch !== undefined || member.newWorktree !== undefined || member.newWorkspace !== undefined) {
+                    throw new Error("member.workspaceId cannot be combined with relay/mode/baseRef/targetBranch/newWorktree/newWorkspace.");
                 }
                 if (!remoteWorkspaces.has(targetWorkspaceId))
                     workspaces.getWorkspace(targetWorkspaceId);
@@ -185,6 +186,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
                     path: member.path,
                     ...(member.mode ? { mode: member.mode } : {}),
                     ...(member.baseRef ? { baseRef: member.baseRef } : {}),
+                    ...(member.targetBranch ? { targetBranch: member.targetBranch } : {}),
                     ...(member.newWorktree !== undefined ? { newWorktree: member.newWorktree } : {}),
                     ...(member.newWorkspace !== undefined ? { newWorkspace: member.newWorkspace } : {}),
                     context: "none",
@@ -195,6 +197,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
                 path: member.path,
                 ...(member.mode ? { mode: member.mode } : {}),
                 ...(member.baseRef ? { baseRef: member.baseRef } : {}),
+                ...(member.targetBranch ? { targetBranch: member.targetBranch } : {}),
                 ...(member.newWorktree !== undefined ? { newWorktree: member.newWorktree } : {}),
                 ...(member.newWorkspace !== undefined ? { newWorkspace: member.newWorkspace } : {}),
                 context: "none",
@@ -218,8 +221,8 @@ async function handleOpenWorkspace(options, input, requestContext) {
         }
         else if (memberAction === "update") {
             const targetFieldsPresent = member.workspaceId !== undefined || member.path !== undefined || member.relay !== undefined ||
-                member.mode !== undefined || member.baseRef !== undefined || member.newWorktree !== undefined ||
-                member.newWorkspace !== undefined;
+                member.mode !== undefined || member.baseRef !== undefined || member.targetBranch !== undefined ||
+                member.newWorktree !== undefined || member.newWorkspace !== undefined;
             if (member.newName === undefined && member.purpose === undefined && !targetFieldsPresent) {
                 throw new Error("Updating a Composite Workspace member requires newName, purpose, or a replacement Workspace target.");
             }
@@ -235,7 +238,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
         else {
             if (member.newName !== undefined || member.purpose !== undefined || member.workspaceId !== undefined || member.path !== undefined ||
                 member.relay !== undefined || member.mode !== undefined || member.baseRef !== undefined ||
-                member.newWorktree !== undefined || member.newWorkspace !== undefined) {
+                member.targetBranch !== undefined || member.newWorktree !== undefined || member.newWorkspace !== undefined) {
                 throw new Error("Removing a Composite Workspace member accepts only member.name.");
             }
             composite = compositeWorkspaces.removeMember(workspaceId, member.name);
@@ -291,9 +294,9 @@ async function handleOpenWorkspace(options, input, requestContext) {
         return response;
     }
     if (action === "list") {
-        if (path !== undefined || relay !== undefined || name !== undefined || memberName !== undefined || baseRef !== undefined || newWorktree !== undefined ||
-            newWorkspace !== undefined || context !== undefined) {
-            throw new Error("open_workspace action=list does not accept path, relay, name, memberName, baseRef, newWorktree, newWorkspace, or context. Use kind/root/workspaceId/mode/status/state/staleOnly for inventory filters.");
+        if (path !== undefined || relay !== undefined || name !== undefined || memberName !== undefined || baseRef !== undefined || targetBranch !== undefined ||
+            newWorktree !== undefined || newWorkspace !== undefined || context !== undefined) {
+            throw new Error("open_workspace action=list does not accept path, relay, name, memberName, baseRef, targetBranch, newWorktree, newWorkspace, or context. Use kind/root/workspaceId/mode/status/state/staleOnly for inventory filters.");
         }
         const compositeInventory = () => compositeWorkspaces.list()
             .filter((entry) => workspaceId === undefined || entry.id === workspaceId)
@@ -382,7 +385,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
     const openingComposite = kind === "composite" ||
         (workspaceId !== undefined && compositeWorkspaces.has(workspaceId));
     if (openingComposite) {
-        if (relay !== undefined || path !== undefined || mode !== undefined || baseRef !== undefined ||
+        if (relay !== undefined || path !== undefined || mode !== undefined || baseRef !== undefined || targetBranch !== undefined ||
             newWorktree !== undefined || newWorkspace !== undefined) {
             throw new Error("Composite Workspace open accepts name/workspaceId/context only; members are attached separately and keep their own Workspace definitions.");
         }
@@ -432,6 +435,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
                     kind: "composite",
                     name: composite.name,
                     path: composite.name,
+                    workspaceColor: workspaceColorFor(workspaceIdentityName(composite.name)),
                     members: composite.members,
                     instruction,
                     summary: { members: composite.members.length, status: composite.status },
@@ -464,7 +468,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
         throw new Error("open_workspace name/memberName are only valid for a Composite Workspace.");
     }
     if (workspaceId !== undefined && remoteWorkspaces.has(workspaceId)) {
-        if (path !== undefined || relay !== undefined || mode !== undefined || baseRef !== undefined ||
+        if (path !== undefined || relay !== undefined || mode !== undefined || baseRef !== undefined || targetBranch !== undefined ||
             newWorktree !== undefined || newWorkspace !== undefined) {
             throw new Error("Resuming a relayed Workspace by workspaceId accepts context only.");
         }
@@ -479,6 +483,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
             path,
             mode,
             baseRef,
+            targetBranch,
             newWorktree,
             newWorkspace,
             context,
@@ -511,6 +516,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
                     kind: "workspace",
                     root: opened.root,
                     path: opened.root,
+                    workspaceColor: workspaceColorFor(workspaceIdentityName(opened.root)),
                     mode: opened.mode,
                     relay,
                     instruction: opened.instruction,

package/dist/runtime/config/definition/general-config.js

@@ -1,5 +1,6 @@
 import * as z from "zod/v4";
 import { defineConfigDomain } from "./definition.js";
+import { LISTEN_PORT_MIN, PORT_MAX } from "../validation/ports.js";
 const USER_RUNTIME_SCOPES = ["runtime", "user", "built-in"];
 const USER_SCOPES = ["user", "built-in"];
 const USER_ONLY_SCOPES = ["user"];
@@ -24,11 +25,11 @@ export const generalConfigDefinition = defineConfigDomain({
             reload: "restart-required",
             runtimeOverride: runtimeEnv("HOST", (env) => env.HOST),
         }),
-        port: field(z.number().int().min(1).max(65535), "Local listening port.", {
+        port: field(z.number().int().min(LISTEN_PORT_MIN).max(PORT_MAX), `Local listening port (${LISTEN_PORT_MIN}-${PORT_MAX}).`, {
             scopes: USER_RUNTIME_SCOPES,
             builtIn: literal(7676),
             reload: "restart-required",
-            runtimeOverride: runtimeEnv("PORT", (env) => readIntegerEnv(env, "PORT", 1, 65535)),
+            runtimeOverride: runtimeEnv("PORT", (env) => readIntegerEnv(env, "PORT", LISTEN_PORT_MIN, PORT_MAX)),
         }),
         allowedRoots: field(z.array(z.string()), "Filesystem roots that Workspaces may open.", {
             scopes: USER_RUNTIME_SCOPES,
@@ -119,7 +120,7 @@ export const generalConfigDefinition = defineConfigDomain({
         }),
         commandShell: field(commandShellSchema, "Recorded command-shell preference for ForgeRelay command and Hook execution.", {
             scopes: USER_SCOPES,
-            builtIn: computed("Detected launcher shell with the recorded compatibility fallback used when needed."),
+            builtIn: computed("Platform compatibility default unless an explicit shell preference is recorded."),
             reload: "restart-required",
         }),
         shellInstructions: field(z.boolean(), "Enable ForgeRelay-owned runtime shell instructions.", {

package/dist/runtime/config/external-mcp-config.js

@@ -1,4 +1,5 @@
 import * as z from "zod/v4";
+import { isIntegerPort, OAUTH_CALLBACK_PORT_MIN, PORT_MAX } from "./validation/ports.js";
 const MCP_SERVER_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
 const MAX_MCP_SERVERS = 32;
 const nonEmptyStringSchema = z.string().trim().min(1);
@@ -13,7 +14,7 @@ const clientMetadataUrlSchema = z.string().url().refine((value) => {
 }, "clientMetadataUrl must use https and contain a non-root path.");
 const oauthSourceSchema = z.object({
     clientMetadataUrl: clientMetadataUrlSchema,
-    callbackPort: z.number().int().min(1024).max(65535),
+    callbackPort: z.number().int().min(OAUTH_CALLBACK_PORT_MIN).max(PORT_MAX),
 }).strict();
 const stdioSourceSchema = z.object({
     transport: z.literal("stdio"),
@@ -136,8 +137,8 @@ function parseOAuthClientConfig(value, label) {
         throw new Error(`${label}.clientMetadataUrl must use https and contain a non-root path.`);
     }
     const callbackPort = value.callbackPort;
-    if (!Number.isInteger(callbackPort) || Number(callbackPort) < 1024 || Number(callbackPort) > 65535) {
-        throw new Error(`${label}.callbackPort must be an integer from 1024 to 65535.`);
+    if (!isIntegerPort(callbackPort, OAUTH_CALLBACK_PORT_MIN, PORT_MAX)) {
+        throw new Error(`${label}.callbackPort must be an integer from ${OAUTH_CALLBACK_PORT_MIN} to ${PORT_MAX}.`);
     }
     return {
         clientMetadataUrl: parsed.toString(),

package/dist/runtime/config/user-config.js

@@ -5,6 +5,8 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { withFileLock } from "../state/lock/file-lock.js";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
+import { parseConfigSource } from "./definition/definition.js";
+import { generalConfigDefinition } from "./definition/general-config.js";
 export function forgerelayConfigDir(env = process.env) {
     const explicit = env.FORGERELAY_CONFIG_DIR;
     if (explicit)
@@ -49,8 +51,9 @@ export function loadForgeRelayFiles(env = process.env, options = {}) {
 }
 export function writeForgeRelayConfig(config, env = process.env) {
     const filePath = forgerelayConfigPath(env);
+    const validated = parseConfigSource(generalConfigDefinition, "user", config);
     mkdirSync(forgerelayConfigDir(env), { recursive: true });
-    writeJsonFile(filePath, config, 0o600);
+    writeJsonFile(filePath, validated, 0o600);
     return filePath;
 }
 export async function writeForgeRelayAuth(auth, env = process.env) {

package/dist/runtime/config/validation/ports.js

@@ -0,0 +1,9 @@
+export const LISTEN_PORT_MIN = 1;
+export const PORT_MAX = 65_535;
+export const OAUTH_CALLBACK_PORT_MIN = 1_024;
+export function isIntegerPort(value, minimum = LISTEN_PORT_MIN, maximum = PORT_MAX) {
+    return typeof value === "number"
+        && Number.isInteger(value)
+        && value >= minimum
+        && value <= maximum;
+}

package/dist/runtime/logging/logger.js

@@ -1,5 +1,5 @@
-import { basename } from "node:path";
 import { styleText } from "node:util";
+import { workspaceColorFor, workspaceIdentityName, } from "../../workspace-colors.js";
 const LEVEL_WEIGHT = {
     silent: 0,
     error: 1,
@@ -13,14 +13,22 @@ const LEVEL_STYLE = {
     info: "green",
     debug: "gray",
 };
-const WORKSPACE_PROJECT_COLORS = [
-    "cyanBright",
-    "greenBright",
-    "yellowBright",
-    "magentaBright",
-    "blueBright",
-    "whiteBright",
-];
+const WORKSPACE_PROJECT_COLORS = {
+    red: "red",
+    green: "green",
+    yellow: "yellow",
+    blue: "blue",
+    magenta: "magenta",
+    cyan: "cyan",
+    white: "white",
+    redBright: "redBright",
+    greenBright: "greenBright",
+    yellowBright: "yellowBright",
+    blueBright: "blueBright",
+    magentaBright: "magentaBright",
+    cyanBright: "cyanBright",
+    whiteBright: "whiteBright",
+};
 export function shouldLog(config, level) {
     return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
 }
@@ -59,7 +67,7 @@ export function transportSessionIdPrefix(transportSessionId) {
 /** @deprecated Use transportSessionIdPrefix. */
 export const sessionIdPrefix = transportSessionIdPrefix;
 export function workspaceLogLabel(root, workspaceId) {
-    return `${basename(root)}/${workspaceId}`;
+    return `${workspaceIdentityName(root)}/${workspaceId}`;
 }
 export function commandPreview(command) {
     const normalized = command.replace(/\s+/g, " ").trim();
@@ -215,17 +223,9 @@ function formatPrettySource(source, options) {
     }
     const project = source.slice(0, separator);
     const workspace = source.slice(separator + 1);
-    const projectColor = WORKSPACE_PROJECT_COLORS[stableColorIndex(project)];
+    const projectColor = WORKSPACE_PROJECT_COLORS[workspaceColorFor(project)];
     return `${style([projectColor, "bold"], project, options)}/${style(["cyan", "underline"], workspace, options)}`;
 }
-function stableColorIndex(value) {
-    let hash = 2166136261;
-    for (let index = 0; index < value.length; index += 1) {
-        hash ^= value.charCodeAt(index);
-        hash = Math.imul(hash, 16777619);
-    }
-    return (hash >>> 0) % WORKSPACE_PROJECT_COLORS.length;
-}
 function formatRuntimeResources(entry) {
     const rssMb = bytesToMegabytes(numberField(entry.rssBytes));
     const heapUsedMb = bytesToMegabytes(numberField(entry.heapUsedBytes));