@young1lin/dsh-ui-gitworkbench 0.1.15 → 0.1.17

package/src/index.ts

@@ -42,7 +42,7 @@
  * @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 type { Readable } from 'node:stream'
@@ -62,11 +62,13 @@ import {
   type OpFailure, type PullMode, type Tracking,
 } from './git-ops.js'
 import {
-  planFromStatus,
+  isSafeRelativePath, planFromStatus,
   type DiscardEffect, type DiscardPlan,
 } from './discard-ops.js'
+import { shapeDirChildren, type DirChild } from './dir-listing.js'
 import { parseBlame, type BlameLine } 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'
@@ -78,7 +80,7 @@ import {
   type StyleEntry, type StyleFile,
 } from './style-store.js'
 import {
-  bindingsPath, findRegisteredWorktree, isRefName, loadBindings, parseWorktreeList, 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'
 
@@ -113,6 +115,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
@@ -128,6 +135,21 @@ const COMMIT_HASH = /^[0-9a-fA-F]{4,40}$/
 
 export type { GitCommit } from './git-log.js'
 
+/**
+ * The slice of dsh's `agent/session-start` payload this plugin reads: just the
+ * session identity and its parent edge. Declared structurally (not imported
+ * from `@deepseek-ai/dsh-agent`, which is not a peer of this plugin) so the
+ * shape this code depends on is pinned here regardless of host-side changes.
+ */
+interface SessionStartEvent {
+  readonly agent: {
+    readonly session: {
+      readonly id: string
+      readonly header: { readonly parentSession?: string }
+    }
+  }
+}
+
 export interface WorkbenchStats {
   readonly worktreePath: string
   readonly branch: string
@@ -270,10 +292,32 @@ export class GitWorkbenchService extends TypertRemoteService {
    */
   private readonly bindingMirror = new Map<string, WorktreeBinding>()
 
+  /**
+   * 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.
+   */
+  private readonly parentOf = new Map<string, string>()
+
   constructor(ctx: Context) {
     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: SessionStartEvent) => {
+      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
@@ -305,16 +349,18 @@ export class GitWorkbenchService extends TypertRemoteService {
         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) 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.'
+          const session = context.agent?.session
+          if (session === undefined) return ''
+          // 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)
         },
       })
     })
@@ -352,6 +398,7 @@ export class GitWorkbenchService extends TypertRemoteService {
         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' },
@@ -361,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' }),
     }))
@@ -396,7 +445,8 @@ export class GitWorkbenchService extends TypertRemoteService {
 
     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: Record<string, never>, exec: ToolRunContext) => {
@@ -555,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) ?? '' }
   }
 
@@ -582,32 +638,36 @@ export class GitWorkbenchService extends TypertRemoteService {
     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. */
-  private async unstagedSides(root: string, path: string, signal: AbortSignal): Promise<FileSides> {
+  /** The unstaged layer: diff index→worktree, target = the working-tree file.
+   *  `full` is that file's absolute path, already through the lock. */
+  private async unstagedSides(root: string, path: string, full: string, signal: AbortSignal): Promise<FileSides> {
     // 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 }
     } catch {
       // Missing file: deleted in the working tree, which the diff below states.
     }
     let bytes: Buffer | null = null
     try {
-      bytes = await readFile(join(root, path))
+      bytes = await readFile(full)
     } catch {
       bytes = null
     }
@@ -860,12 +920,14 @@ export class GitWorkbenchService extends TypertRemoteService {
    */
   @Remote('fileImage')
   async fileImage(worktreePath: string, path: string, signal: AbortSignal): Promise<FileImage> {
-    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)
@@ -1072,25 +1134,124 @@ export class GitWorkbenchService extends TypertRemoteService {
 
   /**
    * 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.
+   *
+   * 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: 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.
+   * `-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.
    */
   @Remote('repoTree')
-  async repoTree(worktreePath: string, signal: AbortSignal): Promise<{ paths: string[]; truncated: boolean }> {
+  async repoTree(worktreePath: string, signal: AbortSignal): Promise<{
+    paths: string[]
+    truncated: boolean
+    /** Ignored entries verbatim; directories keep their trailing slash, which
+     *  is the only thing that tells them from files. */
+    ignored: string[]
+    ignoredTruncated: boolean
+    /** Present only when the ignored listing FAILED, so the browser can tell
+     *  "this repository ignores nothing" from "the question could not be
+     *  asked". Omitted on success — never `undefined`, which is not JSON. */
+    ignoredError?: string
+  }> {
     // The repository root: unlike status and numstat, `ls-tree` prints
     // cwd-RELATIVE paths — from a subdirectory every entry would lose the
     // `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.
+   */
+  @Remote('ignoredDir')
+  async ignoredDir(worktreePath: string, dir: string, signal: AbortSignal): Promise<{ entries: DirChild[]; truncated: boolean }> {
+    // 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])
   }
 
   /**
@@ -1164,18 +1325,42 @@ export class GitWorkbenchService extends TypertRemoteService {
     }
   }
 
-  /** 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).
+   */
   @Remote('sessionWorktree')
-  async sessionWorktree(sessionId: string, signal: AbortSignal): Promise<{ worktreePath: string | null; name: string | null }> {
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return { worktreePath: null, name: null }
+  async sessionWorktree(sessionId: string, signal: AbortSignal): Promise<{ worktreePath: string | null; name: string | null; inherited: boolean }> {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) 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. */
+  /**
+   * 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)
@@ -1205,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 {
@@ -1219,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}` : ''}` }
         }
@@ -1252,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).` : ''}`,
     }
   }
 
@@ -1265,7 +1453,15 @@ export class GitWorkbenchService extends TypertRemoteService {
     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) {
@@ -1297,21 +1493,26 @@ export class GitWorkbenchService extends TypertRemoteService {
    * 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.
    */
   @Remote('worktreeStatus')
-  async worktreeStatus(sessionId: string, repoPath: string, signal: AbortSignal): Promise<{ binding: WorktreeBinding | null; worktrees: WorktreeEntry[]; branches: string[]; branchesTruncated: boolean }> {
+  async worktreeStatus(sessionId: string, repoPath: string, signal: AbortSignal): Promise<{ binding: WorktreeBinding | null; bindingInherited: boolean; worktrees: WorktreeEntry[]; branches: string[]; branchesTruncated: boolean }> {
     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 }
+    if (root === null) 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),
@@ -1320,6 +1521,7 @@ export class GitWorkbenchService extends TypertRemoteService {
     const { branches, branchesTruncated } = capBranches(all, BRANCH_LIST_CAP)
     return {
       binding,
+      bindingInherited,
       worktrees: parseWorktreeList(listed.stdout),
       branches,
       branchesTruncated,
@@ -1805,7 +2007,7 @@ interface UntrackedMeasure {
 async function measureUntracked(root: string, path: string): Promise<UntrackedMeasure> {
   let bytes: Buffer
   try {
-    bytes = await readFile(join(root, path))
+    bytes = await readFile(resolveInside(root, path))
   } catch {
     return { lineCount: 0, binary: false, diffable: false }
   }
@@ -1831,7 +2033,7 @@ async function measureUntracked(root: string, path: string): Promise<UntrackedMe
 async function untrackedSegment(root: string, path: string, byteCap: number = UNTRACKED_FILE_BYTE_CAP): Promise<string | null> {
   let bytes: Buffer
   try {
-    bytes = await readFile(join(root, path))
+    bytes = await readFile(resolveInside(root, path))
   } catch {
     return null
   }

package/src/path-lock.ts

@@ -0,0 +1,56 @@
+/**
+ * The one place a client-supplied path becomes an absolute path on disk.
+ *
+ * git needs no such lock: whatever pathspec it is handed, it will not read or
+ * write outside the repository, which is why `isSafePathArg` only has to keep
+ * a path from being mistaken for an option. The moment a path leaves git and
+ * reaches `readFile`, `stat` or `readdir`, that backstop is gone — `join(root,
+ * '../../../etc/passwd')` is just a path, and the browser is the least trusted
+ * source of paths this plugin has.
+ *
+ * So every filesystem call in the host resolves through here, and the RPCs
+ * that do it are pinned by `host-rooted-paths.test.ts` so a new one cannot
+ * quietly join a client string onto the root instead.
+ *
+ * What this does NOT defend against, deliberately and for the same reason
+ * `fs-remove.ts` says so: `resolve` is lexical, so a SYMLINK inside the
+ * worktree that points outward still resolves inside and is followed. Closing
+ * that means a `realpath` per segment on every read of every file, for a case
+ * git itself does not defend against and that presupposes write access to the
+ * repository the reader already opened.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/path-lock
+ */
+
+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.
+ *
+ * Two locks, not one. {@link isSafeRelativePath} rejects the traversal
+ * SPELLINGS — absolute paths, drive letters, UNC prefixes, NUL bytes, any `..`
+ * segment including one buried mid-path. The `startsWith` below 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 the client or from git's output.
+ * @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: string, relative: string): string {
+  if (!isSafeRelativePath(relative)) {
+    throw new Error(`unsafe path argument: ${JSON.stringify(relative)}`)
+  }
+  const base = resolve(root)
+  const target = resolve(base, relative)
+  if (target === base) throw new Error('refusing to act on the worktree root itself')
+  if (!target.startsWith(base + sep)) {
+    throw new Error(`path escapes the worktree: ${JSON.stringify(relative)}`)
+  }
+  return target
+}

package/src/types/dsh-shim.d.ts

@@ -12,17 +12,27 @@ declare module '@deepseek-ai/cordis' {
       /** ToolRuntime.register — returns the dispose callback; loose here, see file header. */
       register(definition: unknown): () => void
     }
+    /**
+     * Event bus, mixed onto ctx in real cordis. Only `on` is mirrored, loose:
+     * the typed event table lives in the @deepseek-ai/dsh-* packages this shim
+     * stands in for. Listeners are fiber-owned and removed on unload.
+     */
+    events: {
+      on(name: string, listener: (...args: any[]) => void): void
+    }
     /**
      * SystemPrompt registry. Only `context()` is mirrored — the dynamic
      * per-assembly contribution, whose `text` provider is SYNCHRONOUS (see the
      * real `PromptContext` in packages/core/system-prompt/src/index.ts). The
-     * `agent` field on the assemble context is merged in by `dsh-agent`.
+     * `agent` field on the assemble context is merged in by `dsh-agent`; its
+     * session header carries the parent edge a subagent is born with
+     * (`SessionHeader.parentSession` in packages/core/session).
      */
     systemPrompt: {
       context(input: {
         name: string
         order: number
-        text: (context: { agent?: { session: { id: string } } }) => string
+        text: (context: { agent?: { session: { id: string; header?: { parentSession?: string } } } }) => string
       }): () => void
     }
     /** Mount a child scope once the named services are available; loose here, see file header. */