@young1lin/dsh-ui-gitworkbench 0.1.15 → 0.1.17

package/lib/dir-listing.js

@@ -0,0 +1,34 @@
+/**
+ * One lazily listed directory, shaped for the wire.
+ *
+ * The Files tab browses ignored directories by reading them from the
+ * filesystem ONE level at a time — git cannot do this scoped: a pathspec
+ * under `--directory` still collapses the whole ignored directory to a
+ * single line, and dropping `--directory` would enumerate every file inside
+ * `node_modules` at once. A `readdir` is one level by construction, costs
+ * milliseconds, and says what a browser wants to know: what is HERE.
+ *
+ * Only the shaping is pure (ordering, capping); the read itself stays in
+ * `index.ts`, which vitest cannot load. Same split as `fs-remove.ts`.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/dir-listing
+ */
+/** The most entries one expansion returns. A real directory level is a few
+ *  hundred at most (`node_modules`'s own top level); a cap beyond that is a
+ *  reported fuse against a pathological directory, not a working number. */
+export const DIR_CHILD_CAP = 5_000;
+/**
+ * Order and cap raw readdir results: directories before files (the shape
+ * every file tree has, matching `treeRows`), each run by name, and a cut
+ * REPORTED rather than silent.
+ *
+ * @param raw - the directory's entries with their best-known dir-ness
+ *              (symlinks already resolved by the caller).
+ * @param cap - most entries to return.
+ */
+export function shapeDirChildren(raw, cap = DIR_CHILD_CAP) {
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const ordered = [...raw.filter(entry => entry.dir).sort(byName), ...raw.filter(entry => !entry.dir).sort(byName)];
+    const truncated = ordered.length > cap;
+    return { entries: truncated ? ordered.slice(0, cap) : ordered, truncated };
+}

package/lib/fs-remove.js

@@ -6,8 +6,8 @@
  * `git clean` refuses paths it cannot index, which on Windows includes every
  * reserved device name (`nul`, `con`, `aux`, `com1`, and the same names with
  * any extension). So the removal goes through the filesystem, where git's own
- * refusal to leave the repository does not apply — hence the checks here
- * rather than a bare `rm`.
+ * refusal to leave the repository does not apply — hence the path lock in
+ * `path-lock.ts` rather than a bare `rm`.
  *
  * Lives outside `index.ts` so vitest can load it: the class there needs the
  * dsh runtime, and the property worth testing is "what does this delete, and
@@ -16,36 +16,7 @@
  * @module @young1lin/dsh-ui-gitworkbench/fs-remove
  */
 import { rm } from 'node:fs/promises';
-import { resolve, sep } from 'node:path';
-import { isSafeRelativePath } from './discard-ops.js';
-/**
- * Resolve a repo-relative path against the worktree root, refusing to leave it.
- *
- * The second lock rather than the only one: {@link isSafeRelativePath} already
- * rejected traversal spellings when the plan was made. This re-checks the
- * RESOLVED path, which is the form the filesystem acts on, so a path that
- * survives the first check by being spelled unusually still has to land inside
- * the root to be acted on.
- *
- * @param root - the worktree directory, absolute.
- * @param relative - repo-relative path from a plan step.
- * @returns the absolute path to act on.
- * @throws if the path is not a safe relative path, resolves outside the root,
- *         or IS the root.
- */
-export function resolveInside(root, relative) {
-    if (!isSafeRelativePath(relative)) {
-        throw new Error(`unsafe path to delete: ${JSON.stringify(relative)}`);
-    }
-    const base = resolve(root);
-    const target = resolve(base, relative);
-    if (target === base)
-        throw new Error('refusing to delete the worktree root');
-    if (!target.startsWith(base + sep)) {
-        throw new Error(`refusing to delete outside the worktree: ${JSON.stringify(relative)}`);
-    }
-    return target;
-}
+import { resolveInside } from './path-lock.js';
 /**
  * Remove one entry from the worktree, having proven it is inside it.
  *
@@ -60,10 +31,8 @@ export function resolveInside(root, relative) {
  * `force` makes an absent entry a success: the reader asked for it to be gone,
  * and it is.
  *
- * A symlinked directory inside the worktree could still point outward; that is
- * a repository someone already has write access to, and resolving link targets
- * per segment on every delete would cost a stat per segment for a case git
- * itself does not defend against.
+ * A symlinked directory inside the worktree could still point outward — the
+ * limit of a lexical resolve, stated where the lock is.
  *
  * @param root - the worktree directory, absolute.
  * @param relative - repo-relative path from a plan step.

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, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
@@ -86,9 +86,11 @@ import { saveJsonAtomic } from './atomic-json.js';
 import { runWriteChecked } from './write-checked.js';
 import { CommitPayloadCache, cacheKey } from './commit-cache.js';
 import { NETWORK_GRACE_MS, NON_INTERACTIVE_ENV, capBranches, classifyFailure, clipDiff, commitArgv, countBufferLines, decodesAsUtf8, fetchArgv, isBinaryPrefix, isNoMergeBaseError, isSafePathArg, parseNameStatus, parseNumstat, parseStatus, parseTracking, pullArgv, pushArgv, stageArgv, unstageArgv, } from './git-ops.js';
-import { planFromStatus, } from './discard-ops.js';
+import { isSafeRelativePath, planFromStatus, } from './discard-ops.js';
+import { shapeDirChildren } from './dir-listing.js';
 import { parseBlame } from './blame.js';
 import { removePathInside } from './fs-remove.js';
+import { resolveInside } from './path-lock.js';
 import { resolveRepoRoot, rootedDir } from './repo-root.js';
 import { diffTooLarge, targetTooLarge, SIDE_BYTE_CAP, SIDE_LINE_CAP } from './side-guard.js';
 import { IMAGE_BYTE_CAP, sniffImage } from './image-sniff.js';
@@ -96,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 { bindingsPath, findRegisteredWorktree, isRefName, loadBindings, parseWorktreeList, 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. */
@@ -121,6 +123,11 @@ const SHORTLOG_CAP = 500;
 /** Path list cap for the picker: a monorepo can outrun any popup; past this
  *  the tree is cut and the truncation reported, never silent. */
 const TREE_PATH_CAP = 50_000;
+/** Cap on the ignored entry listing `repoTree` rides along. The listing is
+ *  proportional to the .gitignore's coverage, not the repository (git
+ *  collapses every fully-ignored directory to one line), so real repos sit in
+ *  the tens; this is a reported fuse for a pathological ignore setup. */
+const IGNORED_PATH_CAP = 5_000;
 /**
  * Most branch names sent to the browser. `worktreeStatus` is polled, so an
  * unbounded list would repeat on the wire every few seconds; the picker reports
@@ -164,6 +171,7 @@ let GitWorkbenchService = (() => {
     let _commits_decorators;
     let _authors_decorators;
     let _repoTree_decorators;
+    let _ignoredDir_decorators;
     let _compareRefs_decorators;
     let _sessionWorktree_decorators;
     let _worktreeEnter_decorators;
@@ -194,6 +202,7 @@ let GitWorkbenchService = (() => {
             _commits_decorators = [Remote('commits')];
             _authors_decorators = [Remote('authors')];
             _repoTree_decorators = [Remote('repoTree')];
+            _ignoredDir_decorators = [Remote('ignoredDir')];
             _compareRefs_decorators = [Remote('compareRefs')];
             _sessionWorktree_decorators = [Remote('sessionWorktree')];
             _worktreeEnter_decorators = [Remote('worktreeEnter')];
@@ -221,6 +230,7 @@ let GitWorkbenchService = (() => {
             __esDecorate(this, null, _commits_decorators, { kind: "method", name: "commits", static: false, private: false, access: { has: obj => "commits" in obj, get: obj => obj.commits }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _authors_decorators, { kind: "method", name: "authors", static: false, private: false, access: { has: obj => "authors" in obj, get: obj => obj.authors }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _repoTree_decorators, { kind: "method", name: "repoTree", static: false, private: false, access: { has: obj => "repoTree" in obj, get: obj => obj.repoTree }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _ignoredDir_decorators, { kind: "method", name: "ignoredDir", static: false, private: false, access: { has: obj => "ignoredDir" in obj, get: obj => obj.ignoredDir }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _compareRefs_decorators, { kind: "method", name: "compareRefs", static: false, private: false, access: { has: obj => "compareRefs" in obj, get: obj => obj.compareRefs }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sessionWorktree_decorators, { kind: "method", name: "sessionWorktree", static: false, private: false, access: { has: obj => "sessionWorktree" in obj, get: obj => obj.sessionWorktree }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _worktreeEnter_decorators, { kind: "method", name: "worktreeEnter", static: false, private: false, access: { has: obj => "worktreeEnter" in obj, get: obj => obj.worktreeEnter }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -250,10 +260,32 @@ let GitWorkbenchService = (() => {
          * mutation updates this inside the same critical section that writes it.
          */
         bindingMirror = new Map();
+        /**
+         * Session id → parent session id, as `agent/session-start` delivered it. A
+         * subagent header names its parent, and that edge is all the lineage walk
+         * needs: a child session without a binding of its own works under its
+         * nearest bound ancestor (see {@link resolveEffectiveBinding}). The map is
+         * never pruned — it holds one short string per session this process has
+         * seen, and a stale edge can only make a lookup walk further, never lie.
+         */
+        parentOf = new Map();
         constructor(ctx) {
             super(ctx, 'gitWorkbench');
             this.registerWorktreeTools(ctx);
             this.registerWorktreePrompt(ctx);
+            // Fires for every session the process publishes — fresh subagents and
+            // sessions whose loop resumes from disk. An IDLE session's edge is absent
+            // until its loop (re)starts, so a lookup can simply find no ancestor right
+            // after a host restart — the pre-feature behavior, fail-soft. `events.on`
+            // (not the typed `ctx.on` overload) because the event is declared by
+            // @deepseek-ai/dsh-agent, which this plugin does not depend on; the
+            // listener lives on this ctx's fiber.
+            ctx.events.on('agent/session-start', (payload) => {
+                const session = payload.agent?.session;
+                const parent = lineageEdgeOf(session?.header);
+                if (session !== undefined && parent !== undefined)
+                    this.parentOf.set(session.id, parent);
+            });
             // Hydrate the mirror through the same queue as the mutations, so a binding
             // written before hydration finishes is not overwritten by the stale read.
             // A failed read leaves the mirror empty: sessions then get no standing
@@ -285,17 +317,20 @@ let GitWorkbenchService = (() => {
                     name: 'worktree:binding',
                     order: 115,
                     text: (context) => {
-                        const sessionId = context.agent?.session.id;
-                        const binding = sessionId === undefined ? undefined : this.bindingMirror.get(sessionId);
-                        if (binding === undefined)
+                        const session = context.agent?.session;
+                        if (session === undefined)
                             return '';
-                        const rel = `.agents/worktrees/${binding.name}`;
-                        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`
-                            + 'A path without that prefix acts on the MAIN worktree, not the bound one. Call worktree_exit to unbind.';
+                        // First hop straight off the live header: the prompt must not depend
+                        // on the session-start event having been seen (a plugin reload
+                        // mid-session repopulates the map only through later events).
+                        const parent = lineageEdgeOf(session.header);
+                        if (parent !== undefined && !this.parentOf.has(session.id)) {
+                            this.parentOf.set(session.id, parent);
+                        }
+                        const effective = resolveEffectiveBinding(session.id, this.parentOf, id => this.bindingMirror.get(id));
+                        if (effective === undefined)
+                            return '';
+                        return bindingNotice(effective.binding.name, effective.binding.branch, effective.inherited);
                     },
                 });
             });
@@ -332,6 +367,7 @@ let GitWorkbenchService = (() => {
                     ok: { type: 'boolean' },
                     error: { type: 'string' },
                     binding: { oneOf: [{ type: 'null' }, { type: 'object', additionalProperties: true }] },
+                    bindingInherited: { type: 'boolean' },
                     worktrees: { type: 'array', items: { type: 'object', additionalProperties: true } },
                     branches: { type: 'array', items: { type: 'string' } },
                     branchesTruncated: { type: 'boolean' },
@@ -340,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' }),
             }));
@@ -375,7 +413,8 @@ let GitWorkbenchService = (() => {
             }));
             ctx.tools.register(defineTool({
                 name: 'worktree_status',
-                description: 'Show this session\'s bound worktree (if any) and the repository\'s existing worktrees with branches.',
+                description: 'Show this session\'s worktree (its own, or the one its parent session entered — bindingInherited says which) '
+                    + 'and the repository\'s existing worktrees with branches.',
                 parameters: {},
                 output: output(STATUS_SCHEMA),
                 execute: async (_args, exec) => {
@@ -535,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) ?? '' };
         }
         /**
@@ -560,24 +606,28 @@ let GitWorkbenchService = (() => {
             if (layer !== 'unstaged' && layer !== 'staged') {
                 throw new Error(`unknown layer "${String(layer)}"; expected 'unstaged' or 'staged'`);
             }
-            if (typeof path !== 'string' || !isSafePathArg(path)) {
+            if (typeof path !== 'string' || !isSafeRelativePath(path)) {
                 throw new Error(`unsafe path argument: ${JSON.stringify(path)}`);
             }
             // Repository root, not the session's directory: every path below is
             // repository-relative (pathspecs resolve against the cwd, and so does
             // the file read for the editor's target). See repo-root.ts.
             const root = await this.rootedDirOf(worktreePath, signal);
+            // The unstaged layer READS THE FILE, so its absolute path is built by the
+            // lock rather than by a join — see path-lock.ts. Done here, once, so the
+            // one place that resolves a client path is visible in this method.
             return layer === 'unstaged'
-                ? await this.unstagedSides(root, path, signal)
+                ? await this.unstagedSides(root, path, resolveInside(root, path), signal)
                 : await this.stagedSides(root, path, signal);
         }
-        /** The unstaged layer: diff index→worktree, target = the working-tree file. */
-        async unstagedSides(root, path, signal) {
+        /** The unstaged layer: diff index→worktree, target = the working-tree file.
+         *  `full` is that file's absolute path, already through the lock. */
+        async unstagedSides(root, path, full, signal) {
             // Size guard first, off the stat rather than a read: declining a file past
             // the cap must not mean loading a pathological one whole first. Bytes are
             // all a stat knows; the line half of the guard needs the read below.
             try {
-                const info = await stat(join(root, path));
+                const info = await stat(full);
                 if (info.isFile() && targetTooLarge(info.size, 0))
                     return { ...emptySides(), tooLarge: true };
             }
@@ -586,7 +636,7 @@ let GitWorkbenchService = (() => {
             }
             let bytes = null;
             try {
-                bytes = await readFile(join(root, path));
+                bytes = await readFile(full);
             }
             catch {
                 bytes = null;
@@ -832,12 +882,14 @@ let GitWorkbenchService = (() => {
          * @param signal - abort signal.
          */
         async fileImage(worktreePath, path, signal) {
-            if (typeof path !== 'string' || !isSafePathArg(path)) {
+            if (typeof path !== 'string' || !isSafeRelativePath(path)) {
                 throw new Error(`unsafe path argument: ${JSON.stringify(path)}`);
             }
             // The repository root — the image is read from disk at the same base
-            // every other path in this plugin is relative to (repo-root.ts).
-            const full = join(await this.rootedDirOf(worktreePath, signal), path);
+            // every other path in this plugin is relative to (repo-root.ts) — and
+            // through the lock, because this is a raw read with no git in the way
+            // to refuse a path that leaves the repository (path-lock.ts).
+            const full = resolveInside(await this.rootedDirOf(worktreePath, signal), path);
             let size = 0;
             try {
                 const info = await stat(full);
@@ -1041,11 +1093,21 @@ let GitWorkbenchService = (() => {
         }
         /**
          * Every file path on HEAD — the filter popup's path picker, aggregated into
-         * a directory tree client-side.
+         * a directory tree client-side — plus the ignored-but-present entries the
+         * Files tab browses.
          *
-         * `-z` is load-bearing: NUL-separated output is UNQUOTED, while the default
-         * would render non-ASCII names as quoted octal escapes under
-         * `core.quotepath` and hand the picker garbage.
+         * The ignored listing is `ls-files --others --ignored --exclude-standard
+         * --directory`: every ignored FILE is listed verbatim (`application-local.yml`
+         * is exactly the file a browser must find and `ls-tree HEAD` cannot), while
+         * every directory a rule ignores as a whole collapses to ONE line with a
+         * trailing slash — `node_modules/` costs one entry, not the ~40k files
+         * inside it. The list therefore scales with the .gitignore's coverage, not
+         * the repository: measured 54 entries / 48ms on this checkout with
+         * node_modules present.
+         *
+         * `-z` is load-bearing on both spawns: NUL-separated output is UNQUOTED,
+         * while the default would render non-ASCII names as quoted octal escapes
+         * under `core.quotepath` and hand the picker garbage.
          * @param worktreePath - worktree whose HEAD is listed; empty falls back to the host cwd.
          * @param signal - abort signal.
          */
@@ -1055,10 +1117,88 @@ let GitWorkbenchService = (() => {
             // `server/` prefix and the picker would feed the log filter pathspecs
             // that match nothing (repo-root.ts).
             const root = await this.rootedDirOf(worktreePath, signal);
-            const res = await this.git(root, ['ls-tree', '-r', '-z', '--name-only', 'HEAD'], signal);
+            const [res, ignoredRes] = await Promise.all([
+                this.git(root, ['ls-tree', '-r', '-z', '--name-only', 'HEAD'], signal),
+                this.git(root, ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], signal),
+            ]);
             const all = res.stdout.split('\0').filter(path => path.length > 0);
             const truncated = all.length > TREE_PATH_CAP;
-            return { paths: truncated ? all.slice(0, TREE_PATH_CAP) : all, truncated };
+            const ignoredAll = ignoredRes.stdout.split('\0').filter(path => path.length > 0);
+            const ignoredTruncated = ignoredAll.length > IGNORED_PATH_CAP;
+            // `ls-tree`'s exit code is deliberately NOT checked: a repository with no
+            // HEAD yet fails it, and "this repository has no files" is the honest
+            // answer there. The ignored listing has no such legitimate failure, so a
+            // non-zero exit is reported rather than served as an empty list — the one
+            // shape that is indistinguishable from a repository ignoring nothing.
+            const ignoredError = ignoredRes.exitCode === 0
+                ? undefined
+                : (ignoredRes.stderr.trim() || `git ls-files failed (exit ${ignoredRes.exitCode})`).slice(-500);
+            return {
+                paths: truncated ? all.slice(0, TREE_PATH_CAP) : all,
+                truncated,
+                ignored: ignoredTruncated ? ignoredAll.slice(0, IGNORED_PATH_CAP) : ignoredAll,
+                ignoredTruncated,
+                ...(ignoredError !== undefined ? { ignoredError } : {}),
+            };
+        }
+        /**
+         * One level of one ignored directory, read from the filesystem — the step
+         * behind clicking `node_modules/` open in the Files tab.
+         *
+         * Deliberately NOT a git listing: with `--directory`, a pathspec under an
+         * ignored directory still collapses to that one directory line (probed:
+         * `ls-files --others --ignored --exclude-standard --directory -- 'node_modules/*'`
+         * answers `node_modules/` and nothing else), and dropping `--directory`
+         * would enumerate every file inside at once — the very flood the collapsed
+         * listing exists to avoid. `readdir` is one level by construction and costs
+         * milliseconds. What the entries ARE is inherited anyway: everything below
+         * an ignored directory is ignored by descent, so the browser owes the
+         * reader the directory's contents, not git's opinion of them.
+         *
+         * A directory that vanished between the listing and the click answers
+         * empty: nothing to browse is the honest answer, and the next refresh
+         * drops the row.
+         *
+         * The name says what it is FOR, not what it permits: nothing here checks
+         * that `dir` is ignored, so this lists any directory inside the worktree.
+         * That is the same reach the reader already has through `fileSides` and
+         * `fileImage`, and adding an ignore check would only make the browser ask
+         * git a second question to learn what it already knows from the listing it
+         * was handed. What it does NOT permit is leaving the worktree, which is
+         * what the path lock below is for.
+         * @param worktreePath - worktree the directory lives in; empty falls back to the host cwd.
+         * @param dir - repo-relative directory path, as the collapsed listing named it.
+         * @param signal - abort signal.
+         */
+        async ignoredDir(worktreePath, dir, signal) {
+            // The same lock every filesystem read in this plugin passes: the browser
+            // is a less trusted source of paths than git's own output, and `readdir`
+            // obeys no repository boundary (path-lock.ts).
+            const target = resolveInside(await this.rootedDirOf(worktreePath, signal), dir);
+            let dirents;
+            try {
+                dirents = await readdir(target, { withFileTypes: true });
+            }
+            catch {
+                return { entries: [], truncated: false };
+            }
+            const plain = dirents
+                .filter(entry => !entry.isSymbolicLink())
+                .map(entry => ({ name: entry.name, dir: entry.isDirectory() }));
+            // A pnpm-style layout makes every package row a symlink into the store;
+            // `withFileTypes` reports the LINK, so a follow-up stat decides whether
+            // the row expands. A broken link reads as a file and simply fails to
+            // open, like any other dangling name.
+            const links = dirents.filter(entry => entry.isSymbolicLink());
+            const resolved = await Promise.all(links.map(async (entry) => {
+                try {
+                    return { name: entry.name, dir: (await stat(join(target, entry.name))).isDirectory() };
+                }
+                catch {
+                    return { name: entry.name, dir: false };
+                }
+            }));
+            return shapeDirChildren([...plain, ...resolved]);
         }
         /**
          * Compare two refs, in the same {@link WorkbenchStats} shape as every other view.
@@ -1131,16 +1271,40 @@ let GitWorkbenchService = (() => {
                 files, diff, commits: parseLog(log.stdout),
             };
         }
-        /** The session's worktree binding, or nulls when unbound (plain-identifier params; signal last). */
+        /**
+         * The session's EFFECTIVE worktree binding — its own, else the nearest bound
+         * ancestor's — or nulls when neither exists. This is what the chip follows,
+         * so a subagent session shows the worktree its conversation works in without
+         * ever holding a binding of its own (plain-identifier params; signal last).
+         */
         async sessionWorktree(sessionId, signal) {
             if (typeof sessionId !== 'string' || sessionId.length === 0)
-                return { worktreePath: null, name: null };
+                return { worktreePath: null, name: null, inherited: false };
             const file = await this.bindingsIo().load();
-            const binding = file.bindings[sessionId];
-            return binding === undefined ? { worktreePath: null, name: null } : { worktreePath: binding.worktreePath, name: binding.name };
+            const effective = resolveEffectiveBinding(sessionId, this.parentOf, id => file.bindings[id]);
+            return effective === undefined
+                ? { 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();
@@ -1167,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;
                 }
@@ -1182,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}` : ''}` };
                     }
@@ -1217,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. */
@@ -1229,8 +1397,15 @@ let GitWorkbenchService = (() => {
             return this.withBindings(async (io) => {
                 const file = await io.load();
                 const binding = file.bindings[sessionId];
-                if (binding === undefined)
-                    return { ok: false, error: 'no worktree binding for this session' };
+                if (binding === undefined) {
+                    // A subagent CAN see a worktree in its status while holding no binding
+                    // of its own (it works under its parent's). Naming that here keeps the
+                    // model from retrying an exit that cannot succeed.
+                    const inherited = resolveEffectiveBinding(sessionId, this.parentOf, id => file.bindings[id]);
+                    return inherited === undefined
+                        ? { ok: false, error: 'no worktree binding for this session' }
+                        : { ok: false, error: 'this session has no binding of its own; its worktree is entered by a parent session — ask the parent session to call worktree_exit' };
+                }
                 if (remove === true) {
                     const status = await this.git(binding.worktreePath, ['status', '--porcelain'], signal);
                     if (status.exitCode !== 0) {
@@ -1261,21 +1436,26 @@ let GitWorkbenchService = (() => {
          * Branches come back most-recently-committed first. With hundreds of them the
          * order is what makes the list usable — the handful anyone is working on sit
          * at the top, so the picker is useful before a single character is typed.
-         * @param sessionId - session whose binding is looked up.
+         * @param sessionId - session whose effective binding is looked up.
          * @param repoPath - caller's directory, used when the session is unbound.
          * @param signal - abort signal.
-         * @returns the binding, the repository's worktrees, and its local branches.
+         * @returns the effective binding (with whether an ancestor lent it), the
+         * repository's worktrees, and its local branches.
          */
         async worktreeStatus(sessionId, repoPath, signal) {
             const file = await this.bindingsIo().load();
-            const binding = typeof sessionId === 'string' && sessionId.length > 0 ? file.bindings[sessionId] ?? null : null;
+            const effective = typeof sessionId === 'string' && sessionId.length > 0
+                ? resolveEffectiveBinding(sessionId, this.parentOf, id => file.bindings[id])
+                : undefined;
+            const binding = effective?.binding ?? null;
+            const bindingInherited = effective?.inherited ?? false;
             // Unbound: list the CALLER's repo. Falling back to the host's launch directory
             // would answer about whatever directory dsh was started in, not this session's.
             const caller = typeof repoPath === 'string' && repoPath.length > 0 ? repoPath.replace(/\\/g, '/') : process.cwd();
             const cwd = binding?.repoRoot ?? caller;
             const root = await this.repoRootOf(cwd, signal);
             if (root === null)
-                return { binding, worktrees: [], branches: [], branchesTruncated: false };
+                return { binding, bindingInherited, worktrees: [], branches: [], branchesTruncated: false };
             const [listed, named] = await Promise.all([
                 this.git(root, ['worktree', 'list', '--porcelain'], signal),
                 this.git(root, ['branch', '--sort=-committerdate', '--format=%(refname:short)'], signal),
@@ -1284,6 +1464,7 @@ let GitWorkbenchService = (() => {
             const { branches, branchesTruncated } = capBranches(all, BRANCH_LIST_CAP);
             return {
                 binding,
+                bindingInherited,
                 worktrees: parseWorktreeList(listed.stdout),
                 branches,
                 branchesTruncated,
@@ -1725,7 +1906,7 @@ async function mapPooled(items, limit, task) {
 async function measureUntracked(root, path) {
     let bytes;
     try {
-        bytes = await readFile(join(root, path));
+        bytes = await readFile(resolveInside(root, path));
     }
     catch {
         return { lineCount: 0, binary: false, diffable: false };
@@ -1752,7 +1933,7 @@ async function measureUntracked(root, path) {
 async function untrackedSegment(root, path, byteCap = UNTRACKED_FILE_BYTE_CAP) {
     let bytes;
     try {
-        bytes = await readFile(join(root, path));
+        bytes = await readFile(resolveInside(root, path));
     }
     catch {
         return null;