@akira-tl/forgerelay 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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/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/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/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));