@young1lin/dsh-ui-gitworkbench 0.1.16 → 0.1.17

package/lib/index.js

@@ -98,7 +98,7 @@ import { LOG_FORMAT, parseLog } from './git-log.js';
 import { emptyLogFilter, logFilterArgs } from './log-filter.js';
 import { parseShortlog } from './shortlog.js';
 import { isBlankEntry, loadStyle, sanitizeEntry, stylePath, } from './style-store.js';
-import { bindingNotice, bindingsPath, findRegisteredWorktree, isRefName, lineageEdgeOf, loadBindings, parseWorktreeList, resolveEffectiveBinding, sanitizeName, saveBindings, worktreeDir, } from './worktree.js';
+import { bindingNotice, bindingsPath, findRegisteredWorktree, isRefName, lineageEdgeOf, loadBindings, parseWorktreeList, resolveEffectiveBinding, resolveEnterBranch, sanitizeName, saveBindings, worktreeDir, } from './worktree.js';
 /** Cap the bundled unified diff so a huge change cannot blow the RPC response. */
 const DIFF_CHAR_CAP = 400_000;
 /** Untracked files larger than this are listed + counted but never diffed. */
@@ -376,20 +376,22 @@ let GitWorkbenchService = (() => {
             ctx.tools.register(defineTool({
                 name: 'worktree_enter',
                 description: 'Enter (create or reuse) an isolated git worktree at .agents/worktrees/<name> — the directory is '
-                    + 'always derived from the name (there is no dir parameter), the branch is the name VERBATIM, '
+                    + 'always derived from the name (there is no dir parameter), the branch defaults to the name '
+                    + '(or pass branch to choose one — unlike the name it may contain slashes, e.g. feature/foo), '
                     + 'and the session is bound to it. After entering, address the worktree relatively from the session cwd: '
                     + 'for shell commands pass workdir ".agents/worktrees/<name>" (per-call workdir is supported and resolved '
                     + 'against the session cwd); for file tools use paths prefixed with .agents/worktrees/<name>/. '
                     + 'Call with no name to auto-generate one. Use worktree_exit to leave.',
                 parameters: {
-                    name: { type: 'string', description: 'Optional worktree name: letters, digits, . _ - + (must start alphanumeric, max 64 chars; ".." and a trailing dot are refused). The name is used VERBATIM as the branch — no prefix is added. If the target directory already holds a registered worktree (e.g. one made by another tool), it is reused as-is with its own branch. Auto-generated when omitted or illegal.' },
+                    name: { type: 'string', description: 'Optional worktree name: letters, digits, . _ - + (must start alphanumeric, max 64 chars; ".." and a trailing dot are refused). The name doubles as the default branch — pass branch to split them (no prefix is added either way). If the target directory already holds a registered worktree (e.g. one made by another tool), it is reused as-is with its own branch. Auto-generated when omitted or illegal.' },
+                    branch: { type: 'string', description: 'Optional branch for a NEW worktree; defaults to the name. Unlike the name it may contain slashes (feature/foo) — the one spelling a directory name cannot express. Validated and REFUSED when illegal (never auto-generated); set aside — the worktree keeps its own branch, the hint says so — when the target directory already holds a registered worktree.' },
                 },
                 output: output(OP_SCHEMA),
                 execute: async (args, exec) => {
                     const session = exec.agent?.session;
                     if (session === undefined)
                         return { ok: false, error: 'worktree tools require a calling session' };
-                    return this.worktreeEnter(session.id, session.header.cwd ?? '', args?.name, exec.signal);
+                    return this.worktreeEnter(session.id, session.header.cwd ?? '', args?.name, args?.branch, exec.signal);
                 },
                 presentCall: () => ({ card: 'generic', title: 'Enter worktree', kind: 'other' }),
             }));
@@ -572,6 +574,13 @@ let GitWorkbenchService = (() => {
             const tracked = await this.git(root, ['diff', 'HEAD', '--', path], signal);
             if (tracked.stdout.trim().length > 0)
                 return { diff: tracked.stdout };
+            // Empty for a TRACKED file is real, not a missing diff: the line-ending
+            // phantom (autocrlf / eol attributes make the stat check and the clean
+            // filter disagree) lists such files modified forever while git itself
+            // finds no content difference. Synthesizing a new-file segment for one
+            // would paint a whole-file addition git does not see.
+            if (!await this.isUntracked(root, path, signal))
+                return { diff: '' };
             return { diff: await untrackedSegment(root, path) ?? '' };
         }
         /**
@@ -1277,8 +1286,25 @@ let GitWorkbenchService = (() => {
                 ? { worktreePath: null, name: null, inherited: false }
                 : { worktreePath: effective.binding.worktreePath, name: effective.binding.name, inherited: effective.inherited };
         }
-        /** Create (or reuse) a git worktree under `<repoRoot>/.agents/worktrees/` and bind the session to it. */
-        async worktreeEnter(sessionId, repoPath, name, signal) {
+        /**
+         * Create (or reuse) a git worktree under `<repoRoot>/.agents/worktrees/`
+         * and bind the session to it.
+         *
+         * The name is the identity — the directory — and the default branch.
+         * branchName (optional) splits the two for the one spelling the name can
+         * never express: a slash branch (`feature/foo` is a legal ref and an
+         * impossible Windows directory). It applies to a FRESH create only — a
+         * reused worktree keeps its own branch, and the hint says so when an
+         * explicit request was set aside. An illegal branchName is refused, never
+         * substituted: a branch is semantic in a way a directory label is not.
+         * @param sessionId - session to bind to the worktree.
+         * @param repoPath - caller's directory, used to locate the repository.
+         * @param name - worktree name (directory + default branch), sanitized;
+         * auto-generated when omitted or illegal.
+         * @param branchName - branch for a fresh create; defaults to the name.
+         * @param signal - abort signal.
+         */
+        async worktreeEnter(sessionId, repoPath, name, branchName, signal) {
             if (typeof sessionId !== 'string' || sessionId.length === 0)
                 return { ok: false, error: 'sessionId is required' };
             const cwd = typeof repoPath === 'string' && repoPath.length > 0 ? repoPath.replace(/\\/g, '/') : process.cwd();
@@ -1305,13 +1331,17 @@ let GitWorkbenchService = (() => {
             // started. Reuse paths recover it with merge-base instead (theirs is historical).
             const headBefore = (await this.git(repoRoot, ['rev-parse', 'HEAD'], signal)).stdout.trim();
             // The branch the session actually lands on: the reused worktree's own branch,
-            // or the name VERBATIM for a fresh create — no forced prefix.
-            let branch = existing?.branch ?? wtName;
+            // branchName when the caller asked for one (slashes allowed — a branch can
+            // spell what a directory cannot), else the name VERBATIM — no forced prefix.
+            const choice = resolveEnterBranch(wtName, branchName, existing?.branch);
+            if (!choice.ok)
+                return { ok: false, error: choice.error };
+            const branch = choice.branch;
             let reusedWorktree = false;
             let reusedBranch = false;
             let baseCommit;
             if (existing === undefined) {
-                const add = await this.git(repoRoot, ['worktree', 'add', '-b', wtName, dir], signal);
+                const add = await this.git(repoRoot, ['worktree', 'add', '-b', branch, dir], signal);
                 if (add.exitCode === 0) {
                     baseCommit = headBefore.length > 0 ? headBefore : undefined;
                 }
@@ -1320,11 +1350,11 @@ let GitWorkbenchService = (() => {
                     // commits), so a re-enter after remove finds the name present as a
                     // branch: verify the ref and check the existing branch out instead
                     // of failing on `-b`.
-                    const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${wtName}`], signal);
+                    const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], signal);
                     if (verified.exitCode !== 0) {
                         return { ok: false, error: `git worktree add failed (exit ${add.exitCode})${add.stderr.length > 0 ? `: ${add.stderr}` : ''}` };
                     }
-                    const retry = await this.git(repoRoot, ['worktree', 'add', dir, wtName], signal);
+                    const retry = await this.git(repoRoot, ['worktree', 'add', dir, branch], signal);
                     if (retry.exitCode !== 0) {
                         return { ok: false, error: `git worktree add failed (exit ${retry.exitCode})${retry.stderr.length > 0 ? `: ${retry.stderr}` : ''}` };
                     }
@@ -1355,7 +1385,7 @@ let GitWorkbenchService = (() => {
             const rel = `.agents/worktrees/${wtName}`;
             return {
                 ok: true, worktreePath: dir, branch,
-                hint: `Session bound to worktree "${wtName}" (branch ${branch}) at ${rel}/. For shell commands pass workdir "${rel}" (per-call workdir is supported and resolved against the session cwd); for file tools use paths relative to the session cwd prefixed with ${rel}/. Call worktree_exit to unbind.${reusedWorktree ? ` Note: reused the worktree already registered there; its branch ${branch} was kept.` : ''}${reusedBranch ? ` Note: reused existing branch ${branch} (carries its prior commits).` : ''}`,
+                hint: `Session bound to worktree "${wtName}" (branch ${branch}) at ${rel}/. For shell commands pass workdir "${rel}" (per-call workdir is supported and resolved against the session cwd); for file tools use paths relative to the session cwd prefixed with ${rel}/. Call worktree_exit to unbind.${reusedWorktree ? ` Note: reused the worktree already registered there; its branch ${branch} was kept.` : ''}${choice.branchOverridden ? ` Note: requested branch ${branchName} was not used; the reused worktree keeps its branch ${branch}.` : ''}${reusedBranch ? ` Note: reused existing branch ${branch} (carries its prior commits).` : ''}`,
             };
         }
         /** Unbind the session's worktree; with remove=true, delete a clean worktree from disk. */

package/lib/worktree.js

@@ -138,6 +138,56 @@ export function isRefName(ref) {
         && !ref.includes('..')
         && REF_CHARS.test(ref);
 }
+/**
+ * The extra rules an ENTER branch must satisfy beyond {@link isRefName}.
+ *
+ * isRefName guards untrusted refs that reach git as positional arguments
+ * (leading `-`, `..`, alien characters). A branch worktreeEnter CREATES has
+ * two more classes of trouble: spellings check-ref-format refuses that
+ * REF_CHARS happens to pass (a leading or trailing dot, a `.lock` ending),
+ * and `head` — a legal ref on Linux that collides with HEAD on the
+ * case-insensitive filesystems the host runs on.
+ */
+function isEnterBranch(branch) {
+    return isRefName(branch)
+        && !branch.startsWith('.')
+        && !branch.endsWith('.')
+        && !branch.endsWith('.lock')
+        && branch.toLowerCase() !== 'head';
+}
+/**
+ * Decide the branch a worktreeEnter call lands on.
+ *
+ * The worktree NAME is the identity knob — the directory under
+ * `.agents/worktrees/` — and doubles as the branch by default (the old
+ * contract, kept for callers that pass no branchName). branchName splits the
+ * two for the one thing the name can never express: a SLASH branch
+ * (`feature/foo` is a legal ref and an impossible Windows directory).
+ *
+ * Reuse keeps the registered worktree's own branch, request or no request;
+ * an explicit branchName it displaces is reported as branchOverridden so the
+ * hint can say so — refusing there would break enter's idempotency (the same
+ * call re-issued must rebind, not explode).
+ *
+ * An illegal branchName is REFUSED, never substituted: the worktree name may
+ * be auto-generated because a directory label is arbitrary, but a branch is
+ * semantic — silently renaming it lands work on the wrong branch.
+ * @param wtName - sanitized worktree name (the default branch).
+ * @param branchName - caller-requested branch, or undefined for the default.
+ * @param existingBranch - the registered worktree's own branch when the
+ * target directory already holds one, else undefined.
+ * @returns the branch to create or keep, plus whether an explicit request
+ * was set aside — or the refusal error.
+ */
+export function resolveEnterBranch(wtName, branchName, existingBranch) {
+    if (branchName !== undefined && !isEnterBranch(branchName)) {
+        return { ok: false, error: 'branchName is not a valid branch name' };
+    }
+    if (existingBranch !== undefined) {
+        return { ok: true, branch: existingBranch, branchOverridden: branchName !== undefined && branchName !== existingBranch };
+    }
+    return { ok: true, branch: branchName ?? wtName, branchOverridden: false };
+}
 export function worktreeDir(repoRoot, name) {
     return `${repoRoot.replace(/\/+$/, '')}/.agents/worktrees/${name}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@young1lin/dsh-ui-gitworkbench",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Out-of-tree dsh web UI plugin: a session-header git workbench chip opening a drawer with the file tree, per-file diff, history, compare, staging, commit, and sync (fetch/pull/push).",
   "type": "module",
   "main": "lib/index.js",

package/src/client/DiffViews.tsx

@@ -241,7 +241,7 @@ function renderCode(row: RowWithRanges, tokens: readonly HighlightRun[]): ReactN
  * (history and compare keep it unconditionally), with a notice — a silently
  * different view reads as a broken one, not a guarded one.
  */
-export function SideBySideView({ t, path, palette, wrap, statsPath, fetchSides, writeChecked, scopeKey, gen, fallbackSegment, fallbackLoading, onBlockAction, onSaved, onDirtyChange }: {
+export function SideBySideView({ t, path, palette, wrap, statsPath, fetchSides, writeChecked, scopeKey, gen, fallbackSegment, fallbackLoading, phantomListed, onBlockAction, onSaved, onDirtyChange }: {
   t: Translate
   path: string
   palette: string
@@ -262,6 +262,10 @@ export function SideBySideView({ t, path, palette, wrap, statsPath, fetchSides,
    *  refresh generations — this is how the poll reaches a dirty buffer. */
   fallbackSegment: string
   fallbackLoading: boolean
+  /** The open file is listed modified while its whole-file diff is empty —
+   *  the line-ending phantom. The empty states then explain themselves
+   *  instead of showing the generic "no text changes" a broken pane shows. */
+  phantomListed: boolean
   /** Run one block action; a discard routes to the drawer's confirmation. */
   onBlockAction: (mode: BlockMode, ask: BlockAsk) => Promise<GitOpResult>
   /** After a successful save: refresh the tree and the pane together. */
@@ -724,7 +728,7 @@ export function SideBySideView({ t, path, palette, wrap, statsPath, fetchSides,
   /** The pane the drawer had before this view existed, notice included. */
   const unifiedFallback = (): ReactNode => fallbackSegment.length > 0
     ? <DiffView segment={fallbackSegment} path={path} palette={palette} t={t} wrap={wrap} />
-    : <div className={css.empty}>{fallbackLoading ? t('loadingDiff') : t('noTextDiff')}</div>
+    : <div className={css.empty}>{fallbackLoading ? t('loadingDiff') : phantomListed ? t('phantomNotice') : t('noTextDiff')}</div>
 
   if (failed) return unifiedFallback()
   if (sides === null) return <div className={css.empty}>{t('loadingDiff')}</div>
@@ -923,7 +927,7 @@ export function SideBySideView({ t, path, palette, wrap, statsPath, fetchSides,
           layout only decides how much width each side gets. */}
       <div ref={scrollRef} className={css.sideScroll}>
       {bodyState.kind === 'empty' ? (
-        <div className={css.empty}>{t('noTextDiff')}</div>
+        <div className={css.empty}>{phantomListed ? t('phantomNotice') : t('noTextDiff')}</div>
       ) : (
       <>
       <div

package/src/client/GitWorkbenchPanel.tsx

@@ -76,6 +76,7 @@ import { NO_IGNORED_READS, type DirRead, type IgnoredCache } from './ignored-cac
 import { useIdleValue } from './idle-value.ts'
 import { emptyQueryFilter, parseLogQuery, serializeLogQuery } from './log-filter-query.ts'
 import { nextAfterPlan, type DiscardAnswer, type DiscardPreview } from './discard-flow.ts'
+import { isPhantomModified } from './diff-model.ts'
 import { NO_PATHS, preferredFile } from './active-file.ts'
 import type { LogFilter } from '../log-filter.ts'
 import type { AuthorEntry } from '../shortlog.ts'
@@ -1554,6 +1555,11 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
   // content in the working tree and in every commit.
   const activeKey = active === null ? null : `${viewKey}\x1f${active}`
   const segment = bundled.length > 0 ? bundled : activeKey === null ? '' : fetched.get(activeKey) ?? ''
+  /** The CRLF phantom: listed modified, whole-file diff empty (see
+   *  {@link isPhantomModified}). Changes-tab only — history and compare list
+   *  files from real ref diffs, where an empty segment means a failed fetch,
+   *  and the phantom notice would mislead. */
+  const phantomListed = tab === 'changes' && isPhantomModified(activeFile?.status, segment)
 
   // On-demand diff for files absent from the bundled payload (cap-truncated
   // untracked files, oversize paths).
@@ -2134,6 +2140,13 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
             ) : activeFile !== null && activeFile.previousPath !== undefined ? (
               <div className={css.renameLine}>{t('renamedFrom')} <code>{activeFile.previousPath}</code></div>
             ) : null}
+            {/* An empty compare result is usually the three-dot DIRECTION, not
+                "no differences": A...B diffs from the fork point up to B, so a
+                B that never moved past the fork shows nothing at all. Say so —
+                an empty tree with no word reads as a broken one. */}
+            {tab === 'compare' && comparable && shown !== null && body.files.length === 0 ? (
+              <div className={css.empty}>{t('compareEmptyHint', { base: baseRef ?? '', head: headRef ?? '' })}</div>
+            ) : null}
             {(shown === null && tab !== 'changes') || (tab === 'compare' && !comparable) ? null
               : activeFile !== null && activeFile.binary ? (
                 <div className={css.empty}>{t('binaryFile')}</div>
@@ -2150,6 +2163,7 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
                   gen={gen}
                   fallbackSegment={segment}
                   fallbackLoading={loading && segment.length === 0}
+                  phantomListed={phantomListed}
                   onBlockAction={askBlockAction}
                   onSaved={onRefresh}
                   onDirtyChange={onSideDirty}

package/src/client/diff-model.ts

@@ -19,6 +19,26 @@ export interface RowWithRanges extends Row {
   ranges?: Array<readonly [number, number]>
 }
 
+/**
+ * Whether an empty per-file diff is the line-ending phantom.
+ *
+ * autocrlf / `eol` attributes make git's stat check and its clean filter
+ * disagree, so a file can sit in the tree as modified forever while every
+ * content diff comes back empty — the classic always-modified file of a
+ * Windows checkout. Opening it must explain that, not fall to the generic
+ * "no text changes" a broken pane also shows.
+ *
+ * Only `modified` + an empty WHOLE-FILE segment is the phantom: a fully
+ * staged file has an empty unstaged layer but a non-empty HEAD-diff (the
+ * reader is one click from the content), and every other status always has
+ * a diff or a synthesized one.
+ * @param status - the tree row's status for the open file.
+ * @param segment - the whole-file diff text (HEAD vs worktree).
+ */
+export function isPhantomModified(status: string | undefined, segment: string): boolean {
+  return status === 'modified' && segment.length === 0
+}
+
 /**
  * Parse a unified diff segment into typed rows, tracking line numbers.
  * @param segment - one file's `diff --git` text (headers are skipped).

package/src/client/locales.ts

@@ -39,7 +39,7 @@ export type WorkbenchKey =
   | 'filterDate' | 'filterToday' | 'filterLast7' | 'filterLast30' | 'filterAfter' | 'filterBefore'
   | 'filterPaths' | 'filterPathsMore' | 'allBranches' | 'filterPathSearch'
   | 'filterCalendarSets' | 'filterSelected' | 'filterLocale'
-  | 'compareBase' | 'compareHead' | 'comparePick' | 'compareCommits' | 'loadingCompare' | 'noBranches'
+  | 'compareBase' | 'compareHead' | 'comparePick' | 'compareCommits' | 'compareEmptyHint' | 'loadingCompare' | 'noBranches'
   | 'refSearch' | 'refNone' | 'refCount' | 'refTruncated' | 'refWorktrees' | 'refBranches' | 'historyRefLabel'
   | 'settings' | 'themeMode' | 'themePalette' | 'themeScope' | 'themeBackground' | 'themeCss'
   | 'modeSystem' | 'modeLight' | 'modeDark'
@@ -66,7 +66,7 @@ export type WorkbenchKey =
   // side-by-side editing: arm the editor, save, revert, the stale/conflict
   // banner, the CRLF refusal notice, and the unsaved-changes prompt that
   // guards every gesture dropping the buffer (tab, file, close)
-  | 'editFile' | 'fileSave' | 'fileRevert' | 'editingNotice' | 'crlfNotice' | 'encodingNotice'
+  | 'editFile' | 'fileSave' | 'fileRevert' | 'editingNotice' | 'crlfNotice' | 'encodingNotice' | 'phantomNotice'
   // blame gutter on the working-tree column
   | 'blameToggle' | 'blameHint' | 'blameUncommitted' | 'blameFailed' | 'blameTruncated'
   | 'saveFailed' | 'saveUnavailable' | 'saveRetry'
@@ -118,6 +118,7 @@ export const zh: Record<WorkbenchKey, string> = {
   compareHead: '对比',
   comparePick: '选择两个不同的分支进行对比',
   compareCommits: '{count} 个提交（自共同祖先起）',
+  compareEmptyHint: '{base}...{head} 比较的是自分叉点到 {head} 的变化，没有找到差异；想看另一方向的变化请交换两端。',
   loadingCompare: '加载对比…',
   noBranches: '没有可对比的分支',
   refSearch: '筛选分支…',
@@ -299,6 +300,7 @@ export const zh: Record<WorkbenchKey, string> = {
   blameTruncated: '文件过长，追溯信息只显示了前面一部分。',
   crlfNotice: '这个文件的行尾是 CRLF，暂不支持在线编辑（编辑框会把行尾统一成 LF，保存时整份文件都会被改写）；建议把行尾统一成 LF。差异里的回车已用 ␍ 标出；查看和按块暂存/撤回不受影响。',
   encodingNotice: '这个文件不是 UTF-8 编码（可能是 GBK、Shift JIS 之类），暂不支持在线编辑：页面上看到的文字是一次有损解码，保存回去会把文件里每一个非 ASCII 字节都改写掉，包括你没动过的行。查看和按块暂存/撤回不受影响。',
+  phantomNotice: 'git 把这个文件列为已修改，但行尾归一化（CRLF / autocrlf / eol 属性）之后没有内容差异——这是 Windows 检出常见的「永远已修改」幻影，不是显示故障。统一行尾（建议把行尾统一成 LF）或让 git 重新比对后，这一条目就会消失。',
   saveFailed: '保存失败',
   saveUnavailable: '当前宿主还不支持保存（需要重启 dsh web 加载新版宿主端）。',
   saveRetry: '重试保存',
@@ -363,6 +365,7 @@ export const en: Record<WorkbenchKey, string> = {
   compareHead: 'Compare',
   comparePick: 'Pick two different branches to compare',
   compareCommits: '{count} commits since they diverged',
+  compareEmptyHint: '{base}...{head} compares from the fork point up to {head} and found no differences; to see what changed on the other side, swap the two ends.',
   loadingCompare: 'Loading comparison…',
   noBranches: 'No branches to compare',
   refSearch: 'Filter branches…',
@@ -529,6 +532,7 @@ export const en: Record<WorkbenchKey, string> = {
   blameTruncated: 'The file is long, so blame is shown for the first part only.',
   crlfNotice: 'This file has CRLF line endings, which the editor does not support yet (the edit box would turn every ending into LF, so a save rewrites the whole file); normalising the endings to LF is recommended. Carriage returns are marked ␍ in the diff; viewing and block staging/rolling back still work.',
   encodingNotice: 'This file is not UTF-8 (GBK, Shift JIS or similar), so the editor is unavailable: the text shown is a lossy decode of it, and saving that back would rewrite every non-ASCII byte in the file, including lines you never touched. Viewing and block staging/rolling back still work.',
+  phantomNotice: 'git lists this file as modified, but after line-ending normalisation (CRLF / autocrlf / eol attributes) there is no content difference — the classic "modified forever" phantom of a Windows checkout, not a broken view. Once the endings agree (normalising the endings to LF is recommended) the entry disappears.',
   saveFailed: 'Save failed',
   saveUnavailable: 'This host does not support saving yet — restart dsh web to load the new host half.',
   saveRetry: 'Retry save',

package/src/index.ts

@@ -80,7 +80,7 @@ import {
   type StyleEntry, type StyleFile,
 } from './style-store.js'
 import {
-  bindingNotice, bindingsPath, findRegisteredWorktree, isRefName, lineageEdgeOf, loadBindings, parseWorktreeList, resolveEffectiveBinding, sanitizeName, saveBindings, worktreeDir,
+  bindingNotice, bindingsPath, findRegisteredWorktree, isRefName, lineageEdgeOf, loadBindings, parseWorktreeList, resolveEffectiveBinding, resolveEnterBranch, sanitizeName, saveBindings, worktreeDir,
   type BindingsFile, type WorktreeBinding, type WorktreeEntry, type WorktreeOpResult,
 } from './worktree.js'
 
@@ -408,19 +408,21 @@ export class GitWorkbenchService extends TypertRemoteService {
     ctx.tools.register(defineTool({
       name: 'worktree_enter',
       description: 'Enter (create or reuse) an isolated git worktree at .agents/worktrees/<name> — the directory is '
-        + 'always derived from the name (there is no dir parameter), the branch is the name VERBATIM, '
+        + 'always derived from the name (there is no dir parameter), the branch defaults to the name '
+        + '(or pass branch to choose one — unlike the name it may contain slashes, e.g. feature/foo), '
         + 'and the session is bound to it. After entering, address the worktree relatively from the session cwd: '
         + 'for shell commands pass workdir ".agents/worktrees/<name>" (per-call workdir is supported and resolved '
         + 'against the session cwd); for file tools use paths prefixed with .agents/worktrees/<name>/. '
         + 'Call with no name to auto-generate one. Use worktree_exit to leave.',
       parameters: {
-        name: { type: 'string', description: 'Optional worktree name: letters, digits, . _ - + (must start alphanumeric, max 64 chars; ".." and a trailing dot are refused). The name is used VERBATIM as the branch — no prefix is added. If the target directory already holds a registered worktree (e.g. one made by another tool), it is reused as-is with its own branch. Auto-generated when omitted or illegal.' },
+        name: { type: 'string', description: 'Optional worktree name: letters, digits, . _ - + (must start alphanumeric, max 64 chars; ".." and a trailing dot are refused). The name doubles as the default branch — pass branch to split them (no prefix is added either way). If the target directory already holds a registered worktree (e.g. one made by another tool), it is reused as-is with its own branch. Auto-generated when omitted or illegal.' },
+        branch: { type: 'string', description: 'Optional branch for a NEW worktree; defaults to the name. Unlike the name it may contain slashes (feature/foo) — the one spelling a directory name cannot express. Validated and REFUSED when illegal (never auto-generated); set aside — the worktree keeps its own branch, the hint says so — when the target directory already holds a registered worktree.' },
       },
       output: output(OP_SCHEMA),
-      execute: async (args: { name?: string }, exec: ToolRunContext) => {
+      execute: async (args: { name?: string; branch?: string }, exec: ToolRunContext) => {
         const session = exec.agent?.session
         if (session === undefined) return { ok: false, error: 'worktree tools require a calling session' }
-        return this.worktreeEnter(session.id, session.header.cwd ?? '', args?.name, exec.signal)
+        return this.worktreeEnter(session.id, session.header.cwd ?? '', args?.name, args?.branch, exec.signal)
       },
       presentCall: () => ({ card: 'generic', title: 'Enter worktree', kind: 'other' }),
     }))
@@ -603,6 +605,12 @@ export class GitWorkbenchService extends TypertRemoteService {
     }
     const tracked = await this.git(root, ['diff', 'HEAD', '--', path], signal)
     if (tracked.stdout.trim().length > 0) return { diff: tracked.stdout }
+    // Empty for a TRACKED file is real, not a missing diff: the line-ending
+    // phantom (autocrlf / eol attributes make the stat check and the clean
+    // filter disagree) lists such files modified forever while git itself
+    // finds no content difference. Synthesizing a new-file segment for one
+    // would paint a whole-file addition git does not see.
+    if (!await this.isUntracked(root, path, signal)) return { diff: '' }
     return { diff: await untrackedSegment(root, path) ?? '' }
   }
 
@@ -1333,9 +1341,26 @@ export class GitWorkbenchService extends TypertRemoteService {
       : { worktreePath: effective.binding.worktreePath, name: effective.binding.name, inherited: effective.inherited }
   }
 
-  /** Create (or reuse) a git worktree under `<repoRoot>/.agents/worktrees/` and bind the session to it. */
+  /**
+   * Create (or reuse) a git worktree under `<repoRoot>/.agents/worktrees/`
+   * and bind the session to it.
+   *
+   * The name is the identity — the directory — and the default branch.
+   * branchName (optional) splits the two for the one spelling the name can
+   * never express: a slash branch (`feature/foo` is a legal ref and an
+   * impossible Windows directory). It applies to a FRESH create only — a
+   * reused worktree keeps its own branch, and the hint says so when an
+   * explicit request was set aside. An illegal branchName is refused, never
+   * substituted: a branch is semantic in a way a directory label is not.
+   * @param sessionId - session to bind to the worktree.
+   * @param repoPath - caller's directory, used to locate the repository.
+   * @param name - worktree name (directory + default branch), sanitized;
+   * auto-generated when omitted or illegal.
+   * @param branchName - branch for a fresh create; defaults to the name.
+   * @param signal - abort signal.
+   */
   @Remote('worktreeEnter')
-  async worktreeEnter(sessionId: string, repoPath: string, name: string | undefined, signal: AbortSignal): Promise<WorktreeOpResult> {
+  async worktreeEnter(sessionId: string, repoPath: string, name: string | undefined, branchName: string | undefined, signal: AbortSignal): Promise<WorktreeOpResult> {
     if (typeof sessionId !== 'string' || sessionId.length === 0) return { ok: false, error: 'sessionId is required' }
     const cwd = typeof repoPath === 'string' && repoPath.length > 0 ? repoPath.replace(/\\/g, '/') : process.cwd()
     const repoRoot = await this.repoRootOf(cwd, signal)
@@ -1365,13 +1390,16 @@ export class GitWorkbenchService extends TypertRemoteService {
     // started. Reuse paths recover it with merge-base instead (theirs is historical).
     const headBefore = (await this.git(repoRoot, ['rev-parse', 'HEAD'], signal)).stdout.trim()
     // The branch the session actually lands on: the reused worktree's own branch,
-    // or the name VERBATIM for a fresh create — no forced prefix.
-    let branch = existing?.branch ?? wtName
+    // branchName when the caller asked for one (slashes allowed — a branch can
+    // spell what a directory cannot), else the name VERBATIM — no forced prefix.
+    const choice = resolveEnterBranch(wtName, branchName, existing?.branch)
+    if (!choice.ok) return { ok: false, error: choice.error }
+    const branch = choice.branch
     let reusedWorktree = false
     let reusedBranch = false
     let baseCommit: string | undefined
     if (existing === undefined) {
-      const add = await this.git(repoRoot, ['worktree', 'add', '-b', wtName, dir], signal)
+      const add = await this.git(repoRoot, ['worktree', 'add', '-b', branch, dir], signal)
       if (add.exitCode === 0) {
         baseCommit = headBefore.length > 0 ? headBefore : undefined
       } else {
@@ -1379,11 +1407,11 @@ export class GitWorkbenchService extends TypertRemoteService {
         // commits), so a re-enter after remove finds the name present as a
         // branch: verify the ref and check the existing branch out instead
         // of failing on `-b`.
-        const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${wtName}`], signal)
+        const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], signal)
         if (verified.exitCode !== 0) {
           return { ok: false, error: `git worktree add failed (exit ${add.exitCode})${add.stderr.length > 0 ? `: ${add.stderr}` : ''}` }
         }
-        const retry = await this.git(repoRoot, ['worktree', 'add', dir, wtName], signal)
+        const retry = await this.git(repoRoot, ['worktree', 'add', dir, branch], signal)
         if (retry.exitCode !== 0) {
           return { ok: false, error: `git worktree add failed (exit ${retry.exitCode})${retry.stderr.length > 0 ? `: ${retry.stderr}` : ''}` }
         }
@@ -1412,7 +1440,7 @@ export class GitWorkbenchService extends TypertRemoteService {
     const rel = `.agents/worktrees/${wtName}`
     return {
       ok: true, worktreePath: dir, branch,
-      hint: `Session bound to worktree "${wtName}" (branch ${branch}) at ${rel}/. For shell commands pass workdir "${rel}" (per-call workdir is supported and resolved against the session cwd); for file tools use paths relative to the session cwd prefixed with ${rel}/. Call worktree_exit to unbind.${reusedWorktree ? ` Note: reused the worktree already registered there; its branch ${branch} was kept.` : ''}${reusedBranch ? ` Note: reused existing branch ${branch} (carries its prior commits).` : ''}`,
+      hint: `Session bound to worktree "${wtName}" (branch ${branch}) at ${rel}/. For shell commands pass workdir "${rel}" (per-call workdir is supported and resolved against the session cwd); for file tools use paths relative to the session cwd prefixed with ${rel}/. Call worktree_exit to unbind.${reusedWorktree ? ` Note: reused the worktree already registered there; its branch ${branch} was kept.` : ''}${choice.branchOverridden ? ` Note: requested branch ${branchName} was not used; the reused worktree keeps its branch ${branch}.` : ''}${reusedBranch ? ` Note: reused existing branch ${branch} (carries its prior commits).` : ''}`,
     }
   }
 

package/src/worktree.ts

@@ -183,6 +183,62 @@ export function isRefName(ref: string): boolean {
     && REF_CHARS.test(ref)
 }
 
+/**
+ * The extra rules an ENTER branch must satisfy beyond {@link isRefName}.
+ *
+ * isRefName guards untrusted refs that reach git as positional arguments
+ * (leading `-`, `..`, alien characters). A branch worktreeEnter CREATES has
+ * two more classes of trouble: spellings check-ref-format refuses that
+ * REF_CHARS happens to pass (a leading or trailing dot, a `.lock` ending),
+ * and `head` — a legal ref on Linux that collides with HEAD on the
+ * case-insensitive filesystems the host runs on.
+ */
+function isEnterBranch(branch: string): boolean {
+  return isRefName(branch)
+    && !branch.startsWith('.')
+    && !branch.endsWith('.')
+    && !branch.endsWith('.lock')
+    && branch.toLowerCase() !== 'head'
+}
+
+/**
+ * Decide the branch a worktreeEnter call lands on.
+ *
+ * The worktree NAME is the identity knob — the directory under
+ * `.agents/worktrees/` — and doubles as the branch by default (the old
+ * contract, kept for callers that pass no branchName). branchName splits the
+ * two for the one thing the name can never express: a SLASH branch
+ * (`feature/foo` is a legal ref and an impossible Windows directory).
+ *
+ * Reuse keeps the registered worktree's own branch, request or no request;
+ * an explicit branchName it displaces is reported as branchOverridden so the
+ * hint can say so — refusing there would break enter's idempotency (the same
+ * call re-issued must rebind, not explode).
+ *
+ * An illegal branchName is REFUSED, never substituted: the worktree name may
+ * be auto-generated because a directory label is arbitrary, but a branch is
+ * semantic — silently renaming it lands work on the wrong branch.
+ * @param wtName - sanitized worktree name (the default branch).
+ * @param branchName - caller-requested branch, or undefined for the default.
+ * @param existingBranch - the registered worktree's own branch when the
+ * target directory already holds one, else undefined.
+ * @returns the branch to create or keep, plus whether an explicit request
+ * was set aside — or the refusal error.
+ */
+export function resolveEnterBranch(
+  wtName: string,
+  branchName: string | undefined,
+  existingBranch: string | undefined,
+): { ok: true; branch: string; branchOverridden: boolean } | { ok: false; error: string } {
+  if (branchName !== undefined && !isEnterBranch(branchName)) {
+    return { ok: false, error: 'branchName is not a valid branch name' }
+  }
+  if (existingBranch !== undefined) {
+    return { ok: true, branch: existingBranch, branchOverridden: branchName !== undefined && branchName !== existingBranch }
+  }
+  return { ok: true, branch: branchName ?? wtName, branchOverridden: false }
+}
+
 export function worktreeDir(repoRoot: string, name: string): string {
   return `${repoRoot.replace(/\/+$/, '')}/.agents/worktrees/${name}`
 }