@young1lin/dsh-ui-gitworkbench 0.1.0 → 0.1.2

package/lib/index.js

@@ -76,7 +76,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
  * @module @young1lin/dsh-ui-gitworkbench
  */
 import { randomBytes } from 'node:crypto';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
@@ -86,7 +86,7 @@ import { CommitPayloadCache, cacheKey } from './commit-cache.js';
 import { NETWORK_GRACE_MS, NON_INTERACTIVE_ENV, capBranches, classifyFailure, clipDiff, commitArgv, countBufferLines, fetchArgv, isBinaryPrefix, isNoMergeBaseError, parseNameStatus, parseNumstat, parseStatus, parseTracking, pullArgv, pushArgv, stageArgv, unstageArgv, } from './git-ops.js';
 import { LOG_FORMAT, parseLog } from './git-log.js';
 import { isBlankEntry, loadStyle, sanitizeEntry, stylePath, } from './style-store.js';
-import { bindingsPath, branchFor, isRefName, loadBindings, parseWorktreeList, sanitizeName, saveBindings, worktreeDir, } from './worktree.js';
+import { bindingsPath, findRegisteredWorktree, isRefName, loadBindings, parseWorktreeList, 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. */
@@ -242,7 +242,8 @@ let GitWorkbenchService = (() => {
                         if (binding === undefined)
                             return '';
                         const rel = `.agents/worktrees/${binding.name}`;
-                        return `This session is bound to git worktree "${binding.name}" (branch ${branchFor(binding.name)}).\n`
+                        const branchNote = binding.branch === undefined ? '' : ` (branch ${binding.branch})`;
+                        return `This session is bound to git worktree "${binding.name}"${branchNote}.\n`
                             + 'The session working directory is still the repository root, so the binding is a convention you must apply yourself:\n'
                             + `- shell commands: pass workdir "${rel}"\n`
                             + `- file tools: prefix every path with ${rel}/\n`
@@ -290,13 +291,14 @@ let GitWorkbenchService = (() => {
             };
             ctx.tools.register(defineTool({
                 name: 'worktree_enter',
-                description: 'Enter (create or reuse) an isolated git worktree at .agents/worktrees/<name> on branch wt/<name> '
-                    + 'and bind this session to it. After entering, address the worktree relatively from the session cwd: '
+                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, '
+                    + '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 ([A-Za-z0-9._-], max 40). Auto-generated when omitted.' },
+                    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.' },
                 },
                 output: output(OP_SCHEMA),
                 execute: async (args, exec) => {
@@ -652,39 +654,49 @@ let GitWorkbenchService = (() => {
             // on disk — otherwise a stale entry passes for a reusable worktree and the
             // session binds to a directory that no longer exists.
             await this.git(repoRoot, ['worktree', 'prune'], signal);
-            // Directory already a registered worktree -> reuse it, no second `add`.
-            const existing = parseWorktreeList((await this.git(repoRoot, ['worktree', 'list', '--porcelain'], signal)).stdout)
-                .find(entry => entry.path.replace(/\\/g, '/') === dir);
+            // A registered worktree already lives at the target directory -> reuse it,
+            // whatever made it. The match is on real paths, not strings: junctions
+            // (`.agents/worktrees` pointing at `.claude/worktrees`) and the spelling a
+            // foreign tool registered under all collapse to the same directory, and
+            // the worktree keeps ITS OWN branch — only the binding is new.
+            const existing = await findRegisteredWorktree(parseWorktreeList((await this.git(repoRoot, ['worktree', 'list', '--porcelain'], signal)).stdout), dir, realpath);
             // Branch point, read BEFORE `add` so a fresh worktree records exactly where it
             // 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;
+            let reusedWorktree = false;
             let reusedBranch = false;
             let baseCommit;
             if (existing === undefined) {
-                const add = await this.git(repoRoot, ['worktree', 'add', '-b', branchFor(wtName), dir], signal);
+                const add = await this.git(repoRoot, ['worktree', 'add', '-b', wtName, dir], signal);
                 if (add.exitCode === 0) {
                     baseCommit = headBefore.length > 0 ? headBefore : undefined;
                 }
                 else {
-                    // `git worktree remove` keeps branch wt/<name> (exit never deletes it — it may
-                    // carry unmerged commits), so a re-enter after remove finds the branch present:
-                    // verify the ref and check the existing branch out instead of failing on `-b`.
-                    const branch = branchFor(wtName);
-                    const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], signal);
+                    // `git worktree remove` keeps the branch (it may carry unmerged
+                    // 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);
                     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, branch], signal);
+                    const retry = await this.git(repoRoot, ['worktree', 'add', dir, wtName], signal);
                     if (retry.exitCode !== 0) {
                         return { ok: false, error: `git worktree add failed (exit ${retry.exitCode})${retry.stderr.length > 0 ? `: ${retry.stderr}` : ''}` };
                     }
                     reusedBranch = true;
                 }
             }
+            else {
+                reusedWorktree = true;
+            }
             if (baseCommit === undefined) {
                 // Reused worktree or branch: its real branch point is historical, so take the
                 // merge base with the repo's current HEAD. A failure leaves the field absent.
-                const merged = await this.git(repoRoot, ['merge-base', branchFor(wtName), 'HEAD'], signal);
+                const merged = await this.git(repoRoot, ['merge-base', branch, 'HEAD'], signal);
                 if (merged.exitCode === 0)
                     baseCommit = merged.stdout.trim() || undefined;
             }
@@ -692,6 +704,7 @@ let GitWorkbenchService = (() => {
                 const file = await io.load();
                 const binding = {
                     repoRoot, worktreePath: dir, name: wtName, enteredAt: new Date().toISOString(),
+                    branch,
                     ...baseCommit === undefined ? {} : { baseCommit },
                 };
                 file.bindings[sessionId] = binding;
@@ -700,8 +713,8 @@ let GitWorkbenchService = (() => {
             });
             const rel = `.agents/worktrees/${wtName}`;
             return {
-                ok: true, worktreePath: dir, branch: branchFor(wtName),
-                hint: `Session bound to worktree "${wtName}" 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.${reusedBranch ? ` Note: reused existing branch ${branchFor(wtName)} (carries its prior commits).` : ''}`,
+                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).` : ''}`,
             };
         }
         /** Unbind the session's worktree; with remove=true, delete a clean worktree from disk. */

package/lib/worktree.js

@@ -12,7 +12,9 @@ function isBinding(value) {
     // Absent is normal; present-but-malformed is corruption, and dropping the
     // whole record beats trusting half of it.
     const base = record['baseCommit'];
-    return base === undefined || (typeof base === 'string' && base.length > 0);
+    const branch = record['branch'];
+    return (base === undefined || (typeof base === 'string' && base.length > 0))
+        && (branch === undefined || (typeof branch === 'string' && branch.length > 0));
 }
 export function bindingsPath(home) {
     return join(home, '.dsh', 'gitworkbench-worktree-bindings.json').replace(/\\/g, '/');
@@ -45,13 +47,75 @@ export async function saveBindings(ensureDir, writeText, rename, path, file) {
     await saveJsonAtomic(ensureDir, writeText, rename, path, file);
 }
 // ---- Task 2: worktree name/branch/path derivation + porcelain parsing ----
-const NAME_PATTERN = /^[A-Za-z0-9._-]{1,40}$/;
+/**
+ * The charset a worktree name may use: the intersection of what git accepts
+ * in a ref component and what survives as a Windows directory name.
+ *
+ * The name is used verbatim as BOTH the directory under `.agents/worktrees/`
+ * and the branch — there is NO forced prefix, the name the caller asks for is
+ * the branch it gets — so every character must be legal in both worlds:
+ *
+ *   - git (check-ref-format): rejects `..`, a trailing dot, a `.lock` ending,
+ *     control characters, space and `~ ^ : ? * [ \`. `+` is LEGAL — the
+ *     earlier allowlist `[A-Za-z0-9._-]` rejected it and silently renamed
+ *     `feature+20260810-...` to a generated `wt-<hex>`.
+ *   - Windows (NTFS): rejects `< > : " | ? *` (git already covers those) and
+ *     the reserved device names CON/PRN/AUX/NUL/COM1-9/LPT1-9 — even before
+ *     the first dot, case-insensitive — which git never objects to.
+ *   - argv: a leading `-` would read as an option; a leading `.` both hides
+ *     the directory and starts the dot-component git rejects. So: start
+ *     alphanumeric.
+ */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+/** Windows device names that are legal git branches but catastrophic dirs. */
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+function isWorktreeName(raw) {
+    return NAME_PATTERN.test(raw)
+        && !raw.includes('..')
+        && !raw.endsWith('.')
+        && !raw.endsWith('.lock')
+        && raw.toLowerCase() !== 'head'
+        && !WINDOWS_RESERVED.test(raw.split('.')[0] ?? raw);
+}
 export function sanitizeName(raw, rng) {
-    if (raw !== undefined && NAME_PATTERN.test(raw) && raw !== '.' && raw !== '..')
+    if (raw !== undefined && isWorktreeName(raw))
         return raw;
-    return `wt-${rng()}`;
+    // No `wt-` here either: the caller's name is the identity everywhere, so a
+    // generated fallback gets a neutral, self-describing one instead.
+    return `worktree-${rng()}`;
+}
+async function resolveReal(resolve, path) {
+    try {
+        return (await resolve(path.replace(/\\/g, '/'))).replace(/\\/g, '/');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the registered worktree that IS `dir`, if any.
+ *
+ * String comparison is not enough: `.agents/worktrees` may be a junction to
+ * `.claude/worktrees`, and git lists the path a worktree was REGISTERED
+ * under, not the spelling this session would type. Both sides go through a
+ * real-path resolution, so junctions, symlinks and separator styles collapse
+ * to the same directory — and a worktree made by another tool (checked out
+ * under its own branch, no `wt/` anywhere) is recognized and reused instead
+ * of colliding with `git worktree add`.
+ * @param entries - parsed `git worktree list --porcelain`.
+ * @param dir - the worktree directory the caller wants.
+ * @param resolve - real-path resolver (node:fs/promises realpath in the host).
+ */
+export async function findRegisteredWorktree(entries, dir, resolve) {
+    const target = await resolveReal(resolve, dir);
+    if (target === null)
+        return undefined;
+    for (const entry of entries) {
+        if (await resolveReal(resolve, entry.path) === target)
+            return entry;
+    }
+    return undefined;
 }
-export function branchFor(name) { return `wt/${name}`; }
 /** Longest ref name accepted — well past any real branch, short of a payload. */
 const REF_MAX_LENGTH = 200;
 /** The character set git allows in a branch or tag name. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@young1lin/dsh-ui-gitworkbench",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -18,6 +18,8 @@
     "scripts/install.ps1",
     "README.md",
     "README_EN.md",
+    "CHANGELOG.md",
+    "CHANGELOG_EN.md",
     "AGENTS.md",
     "LICENSE",
     "cordis.patch.yml"

package/src/client/GitWorkbenchPanel.tsx

@@ -62,7 +62,7 @@ import {
   type CheckState, type Tick, type TickAction,
 } from './stage-tree.ts'
 import { grammarLoadCount, highlightForRows, shikiLangOf, shikiThemeOf, subscribeGrammarLoaded, type HighlightRun } from './highlight.ts'
-import { badgeRepeatsBranch, bindingChanged, branchOfWorktree, probesClosedBinding, samePath, showsPending, splitPath, viewedPath } from './worktree-view.ts'
+import { badgeRepeatsBranch, bindingChanged, branchOfWorktree, probesClosedBinding, samePath, showsPending, splitPath, turnSettled, viewedPath } from './worktree-view.ts'
 import { BUSY_DELAY_MS, BUSY_HOLD_MS, holdRemaining, quietlyDisabled } from './op-feedback.ts'
 import type { WorkbenchKey } from './locales.ts'
 import css from './GitWorkbenchPanel.module.css'
@@ -630,6 +630,43 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
     return () => { alive = false; clearInterval(id) }
   }, [open, agentRunning, sessionId, worktreePath, fetchSessionBinding, fetchWorktreeStatus])
 
+  /** The agent's `running` on the previous render. The flag itself says
+   *  whether a turn is in flight; only the EDGE of it says the turn has
+   *  ended, and the edge is what the effect below keys on. */
+  const wasRunningRef = useRef<boolean | undefined>(undefined)
+
+  /**
+   * Refresh the SHUT chip's stats when a turn ends.
+   *
+   * The keyed fetch below runs on mount, on source switches and on gen bumps,
+   * and the 3-15s poll starts at `if (!open) return` — so while the drawer was
+   * shut, an agent that wrote files all turn left the header counting the tree
+   * as it stood before the turn. Opening the drawer was the only thing that
+   * refreshed it, and an indicator you must open to read is not an indicator.
+   *
+   * `running` is mirrored live by the sessions store, and a turn boundary is
+   * when agent-caused side effects have settled ({@link turnSettled}), so one
+   * fetch per turn buys the chip the numbers the turn just made true — ahead
+   * counts included, which ride along in the same payload. The write follows
+   * the poll's discipline exactly: guarded on the source so a retired worktree
+   * cannot repaint the tree, touching neither `gen` (which would reset tree
+   * expansion) nor `statsLoading` (which would swap the header totals for a
+   * `—` while a good answer is still on screen).
+   *
+   * An open drawer skips it — the poll is running there and the open itself
+   * bumped gen. Like the probe's full refetch above, the fetch is left to land
+   * guarded rather than aborted: a cleanup fired for an unrelated dep (the
+   * drawer opening mid-flight) must not cancel the only fetch this turn gets.
+   */
+  useEffect(() => {
+    const settled = turnSettled(wasRunningRef.current, agentRunning)
+    wasRunningRef.current = agentRunning
+    if (!settled || open) return
+    fetchStats(statsPath, new AbortController().signal)
+      .then(value => { if (value !== null && statsPathRef.current === statsPath) setStats(value) })
+      .catch(() => {})
+  }, [agentRunning, open, statsPath, fetchStats])
+
   // Stats for the active source: on mount, on source change and on gen bumps
   // (manual refresh / source switch). Cleanup aborts a superseded in-flight fetch.
   useEffect(() => {

package/src/client/highlight.ts

@@ -48,6 +48,14 @@ const LAZY_GRAMMARS = new Map<string, () => Promise<LangModule>>([
   ['java', () => import('@shikijs/langs/java')],
   ['c', () => import('@shikijs/langs/c')],
   ['cpp', () => import('@shikijs/langs/cpp')],
+  // sql/xml were the loud gap: schema dumps and pom/config diffs rendered as
+  // plain text. ini and diff ride along — small grammars, common in repos.
+  // Every entry lands in client.js (inlineDynamicImports), so additions stay
+  // deliberate, not encyclopedic.
+  ['sql', () => import('@shikijs/langs/sql')],
+  ['xml', () => import('@shikijs/langs/xml')],
+  ['ini', () => import('@shikijs/langs/ini')],
+  ['diff', () => import('@shikijs/langs/diff')],
 ])
 
 const LANG_ALIASES = new Map<string, string>([
@@ -68,6 +76,10 @@ const LANG_ALIASES = new Map<string, string>([
   ['java', 'java'],
   ['c', 'c'],
   ['cpp', 'cpp'], ['h', 'c'], ['hpp', 'cpp'],
+  ['sql', 'sql'],
+  ['xml', 'xml'], ['xsl', 'xml'], ['xsd', 'xml'], ['svg', 'xml'],
+  ['ini', 'ini'], ['properties', 'ini'], ['conf', 'ini'], ['cfg', 'ini'],
+  ['diff', 'diff'], ['patch', 'diff'],
 ])
 
 /** Drawer `data-gs-theme` → a loaded Shiki theme name. */

package/src/client/worktree-view.ts

@@ -109,6 +109,36 @@ export function bindingChanged(
   return (probe.name ?? '') !== (shown?.name ?? '')
 }
 
+/**
+ * Whether a turn that was in flight has just come to an end.
+ *
+ * The shut chip's stats freeze on mount: the fetch that carries them re-runs
+ * only on source switches and gen bumps, and the 3-15s poll starts at
+ * `if (!open) return`. So an agent that wrote files all turn left the header
+ * counting the tree as it was before the turn — until someone opened the
+ * drawer, which is the one act that already refreshes everything.
+ *
+ * `running` is mirrored live by the sessions store, and a turn boundary is
+ * when agent-caused side effects have stopped accumulating — the one instant
+ * a shut chip should pay for fresh numbers. One fetch per turn, and none for
+ * an idle session, which is the cost rule this panel lives under (it mounts
+ * in every session header).
+ *
+ * The transition is read strictly: `false → true` is a turn STARTING, whose
+ * numbers are seconds away from being rewritten, and a missing `next` counts
+ * as ended because a turn in flight cannot still be in flight once the store
+ * stops saying so.
+ *
+ * @param prevRunning - whether the agent had a turn in flight last render.
+ * @param nextRunning - whether it has one now.
+ */
+export function turnSettled(
+  prevRunning: boolean | undefined,
+  nextRunning: boolean | undefined,
+): boolean {
+  return prevRunning === true && nextRunning !== true
+}
+
 /**
  * Whether a view should say "pending" rather than show what it has.
  *
@@ -135,17 +165,18 @@ export function showsPending(loading: boolean, fileCount: number): boolean {
 /**
  * Whether a worktree's badge would only repeat the branch chip beside it.
  *
- * dsh derives one from the other — `branchFor` in `src/worktree.ts` turns the
- * name `demo` into the branch `wt/demo` — so for every worktree dsh made, the
- * session card was printing the same word twice, once as `wt/fixture-03` and
- * once as a `fixture-03` badge next to it. A worktree made outside dsh has no
- * such relation, and there the badge is the only thing naming the directory.
+ * The plugin derives one from the other: a worktree it entered has the
+ * binding's name as its branch VERBATIM (and legacy bindings from the
+ * `wt/<name>` era derive it just as directly) — so for those, the session
+ * card would print the same word twice, once as the branch chip and once as
+ * the badge. A worktree made outside the plugin has no such relation, and
+ * there the badge is the only thing naming the directory.
  *
  * @param branch - the branch checked out there.
  * @param name - the worktree's name, as the binding records it.
  */
 export function badgeRepeatsBranch(branch: string, name: string): boolean {
-  return branch.length > 0 && branch === `wt/${name}`
+  return branch.length > 0 && (branch === name || branch === `wt/${name}`)
 }
 
 /**

package/src/index.ts

@@ -42,7 +42,7 @@
  * @module @young1lin/dsh-ui-gitworkbench
  */
 import { randomBytes } from 'node:crypto'
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Readable } from 'node:stream'
@@ -65,7 +65,7 @@ import {
   type StyleEntry, type StyleFile,
 } from './style-store.js'
 import {
-  bindingsPath, branchFor, isRefName, loadBindings, parseWorktreeList, sanitizeName, saveBindings, worktreeDir,
+  bindingsPath, findRegisteredWorktree, isRefName, loadBindings, parseWorktreeList, sanitizeName, saveBindings, worktreeDir,
   type BindingsFile, type WorktreeBinding, type WorktreeEntry, type WorktreeOpResult,
 } from './worktree.js'
 
@@ -228,7 +228,8 @@ export class GitWorkbenchService extends TypertRemoteService {
           const binding = sessionId === undefined ? undefined : this.bindingMirror.get(sessionId)
           if (binding === undefined) return ''
           const rel = `.agents/worktrees/${binding.name}`
-          return `This session is bound to git worktree "${binding.name}" (branch ${branchFor(binding.name)}).\n`
+          const branchNote = binding.branch === undefined ? '' : ` (branch ${binding.branch})`
+          return `This session is bound to git worktree "${binding.name}"${branchNote}.\n`
             + 'The session working directory is still the repository root, so the binding is a convention you must apply yourself:\n'
             + `- shell commands: pass workdir "${rel}"\n`
             + `- file tools: prefix every path with ${rel}/\n`
@@ -278,13 +279,14 @@ 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> on branch wt/<name> '
-        + 'and bind this session to it. After entering, address the worktree relatively from the session cwd: '
+      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, '
+        + '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 ([A-Za-z0-9._-], max 40). Auto-generated when omitted.' },
+        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.' },
       },
       output: output(OP_SCHEMA),
       execute: async (args: { name?: string }, exec: ToolRunContext) => {
@@ -648,44 +650,58 @@ export class GitWorkbenchService extends TypertRemoteService {
     // on disk — otherwise a stale entry passes for a reusable worktree and the
     // session binds to a directory that no longer exists.
     await this.git(repoRoot, ['worktree', 'prune'], signal)
-    // Directory already a registered worktree -> reuse it, no second `add`.
-    const existing = parseWorktreeList((await this.git(repoRoot, ['worktree', 'list', '--porcelain'], signal)).stdout)
-      .find(entry => entry.path.replace(/\\/g, '/') === dir)
+    // A registered worktree already lives at the target directory -> reuse it,
+    // whatever made it. The match is on real paths, not strings: junctions
+    // (`.agents/worktrees` pointing at `.claude/worktrees`) and the spelling a
+    // foreign tool registered under all collapse to the same directory, and
+    // the worktree keeps ITS OWN branch — only the binding is new.
+    const existing = await findRegisteredWorktree(
+      parseWorktreeList((await this.git(repoRoot, ['worktree', 'list', '--porcelain'], signal)).stdout),
+      dir,
+      realpath,
+    )
     // Branch point, read BEFORE `add` so a fresh worktree records exactly where it
     // 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
+    let reusedWorktree = false
     let reusedBranch = false
     let baseCommit: string | undefined
     if (existing === undefined) {
-      const add = await this.git(repoRoot, ['worktree', 'add', '-b', branchFor(wtName), dir], signal)
+      const add = await this.git(repoRoot, ['worktree', 'add', '-b', wtName, dir], signal)
       if (add.exitCode === 0) {
         baseCommit = headBefore.length > 0 ? headBefore : undefined
       } else {
-        // `git worktree remove` keeps branch wt/<name> (exit never deletes it — it may
-        // carry unmerged commits), so a re-enter after remove finds the branch present:
-        // verify the ref and check the existing branch out instead of failing on `-b`.
-        const branch = branchFor(wtName)
-        const verified = await this.git(repoRoot, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], signal)
+        // `git worktree remove` keeps the branch (it may carry unmerged
+        // 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)
         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, branch], signal)
+        const retry = await this.git(repoRoot, ['worktree', 'add', dir, wtName], signal)
         if (retry.exitCode !== 0) {
           return { ok: false, error: `git worktree add failed (exit ${retry.exitCode})${retry.stderr.length > 0 ? `: ${retry.stderr}` : ''}` }
         }
         reusedBranch = true
       }
+    } else {
+      reusedWorktree = true
     }
     if (baseCommit === undefined) {
       // Reused worktree or branch: its real branch point is historical, so take the
       // merge base with the repo's current HEAD. A failure leaves the field absent.
-      const merged = await this.git(repoRoot, ['merge-base', branchFor(wtName), 'HEAD'], signal)
+      const merged = await this.git(repoRoot, ['merge-base', branch, 'HEAD'], signal)
       if (merged.exitCode === 0) baseCommit = merged.stdout.trim() || undefined
     }
     await this.withBindings(async io => {
       const file = await io.load()
       const binding: WorktreeBinding = {
         repoRoot, worktreePath: dir, name: wtName, enteredAt: new Date().toISOString(),
+        branch,
         ...baseCommit === undefined ? {} : { baseCommit },
       }
       file.bindings[sessionId] = binding
@@ -694,8 +710,8 @@ export class GitWorkbenchService extends TypertRemoteService {
     })
     const rel = `.agents/worktrees/${wtName}`
     return {
-      ok: true, worktreePath: dir, branch: branchFor(wtName),
-      hint: `Session bound to worktree "${wtName}" 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.${reusedBranch ? ` Note: reused existing branch ${branchFor(wtName)} (carries its prior commits).` : ''}`,
+      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).` : ''}`,
     }
   }
 

package/src/worktree.ts

@@ -7,6 +7,12 @@ export interface WorktreeBinding {
   readonly worktreePath: string
   readonly name: string
   readonly enteredAt: string
+  /**
+   * The branch checked out in the bound worktree. Optional on purpose:
+   * bindings written before this field existed stay valid; a consumer without
+   * it falls back to reading the branch off the worktree list.
+   */
+  readonly branch?: string
   /**
    * Commit the worktree's branch started from. Optional on purpose: bindings
    * written before this field existed stay valid, and a reuse path can fail to
@@ -29,7 +35,9 @@ function isBinding(value: unknown): value is WorktreeBinding {
   // Absent is normal; present-but-malformed is corruption, and dropping the
   // whole record beats trusting half of it.
   const base = record['baseCommit']
-  return base === undefined || (typeof base === 'string' && base.length > 0)
+  const branch = record['branch']
+  return (base === undefined || (typeof base === 'string' && base.length > 0))
+    && (branch === undefined || (typeof branch === 'string' && branch.length > 0))
 }
 
 export function bindingsPath(home: string): string {
@@ -80,16 +88,76 @@ export interface WorktreeOpResult {
 
 // ---- Task 2: worktree name/branch/path derivation + porcelain parsing ----
 
-const NAME_PATTERN = /^[A-Za-z0-9._-]{1,40}$/
+/**
+ * The charset a worktree name may use: the intersection of what git accepts
+ * in a ref component and what survives as a Windows directory name.
+ *
+ * The name is used verbatim as BOTH the directory under `.agents/worktrees/`
+ * and the branch — there is NO forced prefix, the name the caller asks for is
+ * the branch it gets — so every character must be legal in both worlds:
+ *
+ *   - git (check-ref-format): rejects `..`, a trailing dot, a `.lock` ending,
+ *     control characters, space and `~ ^ : ? * [ \`. `+` is LEGAL — the
+ *     earlier allowlist `[A-Za-z0-9._-]` rejected it and silently renamed
+ *     `feature+20260810-...` to a generated `wt-<hex>`.
+ *   - Windows (NTFS): rejects `< > : " | ? *` (git already covers those) and
+ *     the reserved device names CON/PRN/AUX/NUL/COM1-9/LPT1-9 — even before
+ *     the first dot, case-insensitive — which git never objects to.
+ *   - argv: a leading `-` would read as an option; a leading `.` both hides
+ *     the directory and starts the dot-component git rejects. So: start
+ *     alphanumeric.
+ */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/
+/** Windows device names that are legal git branches but catastrophic dirs. */
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i
+
+function isWorktreeName(raw: string): boolean {
+  return NAME_PATTERN.test(raw)
+    && !raw.includes('..')
+    && !raw.endsWith('.')
+    && !raw.endsWith('.lock')
+    && raw.toLowerCase() !== 'head'
+    && !WINDOWS_RESERVED.test(raw.split('.')[0] ?? raw)
+}
 
 export interface WorktreeEntry { readonly path: string; readonly head: string; readonly branch: string }
 
 export function sanitizeName(raw: string | undefined, rng: () => string): string {
-  if (raw !== undefined && NAME_PATTERN.test(raw) && raw !== '.' && raw !== '..') return raw
-  return `wt-${rng()}`
+  if (raw !== undefined && isWorktreeName(raw)) return raw
+  // No `wt-` here either: the caller's name is the identity everywhere, so a
+  // generated fallback gets a neutral, self-describing one instead.
+  return `worktree-${rng()}`
 }
 
-export function branchFor(name: string): string { return `wt/${name}` }
+/** Resolves a path or fails — the failure is the caller's "does not exist". */
+export type PathResolver = (path: string) => Promise<string>
+
+async function resolveReal(resolve: PathResolver, path: string): Promise<string | null> {
+  try { return (await resolve(path.replace(/\\/g, '/'))).replace(/\\/g, '/') } catch { return null }
+}
+
+/**
+ * Find the registered worktree that IS `dir`, if any.
+ *
+ * String comparison is not enough: `.agents/worktrees` may be a junction to
+ * `.claude/worktrees`, and git lists the path a worktree was REGISTERED
+ * under, not the spelling this session would type. Both sides go through a
+ * real-path resolution, so junctions, symlinks and separator styles collapse
+ * to the same directory — and a worktree made by another tool (checked out
+ * under its own branch, no `wt/` anywhere) is recognized and reused instead
+ * of colliding with `git worktree add`.
+ * @param entries - parsed `git worktree list --porcelain`.
+ * @param dir - the worktree directory the caller wants.
+ * @param resolve - real-path resolver (node:fs/promises realpath in the host).
+ */
+export async function findRegisteredWorktree(entries: readonly WorktreeEntry[], dir: string, resolve: PathResolver): Promise<WorktreeEntry | undefined> {
+  const target = await resolveReal(resolve, dir)
+  if (target === null) return undefined
+  for (const entry of entries) {
+    if (await resolveReal(resolve, entry.path) === target) return entry
+  }
+  return undefined
+}
 
 /** Longest ref name accepted — well past any real branch, short of a payload. */
 const REF_MAX_LENGTH = 200