@young1lin/dsh-ui-gitworkbench 0.1.14 → 0.1.16

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/repo-root.ts

@@ -0,0 +1,66 @@
+/**
+ * Where the drawer runs git: at the repository ROOT, not at the directory the
+ * session happened to open.
+ *
+ * Every path the drawer carries — the tree's entries, the diff's pathspecs,
+ * the editor's save target — is REPOSITORY-RELATIVE, because that is what
+ * `git status --porcelain` and `git diff --numstat` print wherever they run.
+ * Pathspecs and `:path` revisions are the opposite: git resolves them against
+ * the process cwd. The two coincide only when the session opened the root
+ * itself. A session opened at a subdirectory (a monorepo's `server/`, say)
+ * gets a drawer that LISTS the right files and then quietly fails to do
+ * anything with them: `git diff HEAD -- server/main.go` run from `server/`
+ * looks for `server/server/main.go`, matches nothing, and exits 0 with empty
+ * output — a changed file that opens to a blank pane, a stage tick that dies
+ * with "pathspec did not match", a blame that cannot find the path in HEAD.
+ *
+ * Resolving the root once and running everything there makes every
+ * repository-relative spelling correct by construction, whatever directory the
+ * session opened. The resolve is a real git spawn per RPC entry — folded into
+ * the parallel batch where a poll pays for it — and deliberately NOT cached:
+ * re-resolving per call is what lets `git init` run inside a subdirectory
+ * mid-session and be picked up by the next poll, and a cache would trade that
+ * for a spawn that already runs concurrently with the reads it precedes.
+ *
+ * Pure and git-injected (the `write-checked` pattern) so vitest can pin both
+ * halves: the resolution itself, and the git behaviors the whole arrangement
+ * rests on.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/repo-root
+ */
+
+import type { GitRun } from './apply-blocks.js'
+
+/** Run git in `cwd`. Must not throw — report through `exitCode`/`stderr`. */
+export type RootGit = (cwd: string, argv: readonly string[]) => Promise<GitRun>
+
+/**
+ * The repository root of a directory, or null when git knows none.
+ *
+ * `--show-toplevel` is the discovery git itself uses, so what it returns is by
+ * definition where the porcelain paths of commands run in that directory are
+ * rooted — including a linked worktree's own root when the directory sits in
+ * one. Output is normalized to forward slashes so `join()` behaves the same on
+ * every platform (git for Windows already prints them that way).
+ * @param git - how to run git.
+ * @param cwd - any directory inside the repository.
+ */
+export async function resolveRepoRoot(git: RootGit, cwd: string): Promise<string | null> {
+  const out = await git(cwd, ['rev-parse', '--show-toplevel'])
+  if (out.exitCode !== 0) return null
+  return out.stdout.trim().replace(/\\/g, '/') || null
+}
+
+/**
+ * The directory to run git in for a session's workspace: its repository root,
+ * or the directory itself when it is not inside a repository.
+ *
+ * The fallback keeps the failure honest: outside a repository the caller's own
+ * git run fails exactly as it did before this module existed, and that error —
+ * not a resolution error — is what the reader should see.
+ * @param git - how to run git.
+ * @param cwd - the directory the session opened.
+ */
+export async function rootedDir(git: RootGit, cwd: string): Promise<string> {
+  return (await resolveRepoRoot(git, cwd)) ?? cwd
+}

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. */

package/src/worktree.ts

@@ -187,6 +187,103 @@ export function worktreeDir(repoRoot: string, name: string): string {
   return `${repoRoot.replace(/\/+$/, '')}/.agents/worktrees/${name}`
 }
 
+// ---- session lineage: the binding a session effectively works under ----
+
+/** A binding resolved for a session, with whether it is the session's own. */
+export interface EffectiveBinding<T> {
+  readonly binding: T
+  /** False when the binding is the session's own; true when an ancestor's. */
+  readonly inherited: boolean
+}
+
+/**
+ * Deepest ancestor chain walked before the lookup gives up. Real delegation
+ * nests two or three levels; the cap exists so a corrupt lineage (a cycle the
+ * guard below somehow missed, a pathologically deep chain) costs a bounded
+ * number of lookups instead of walking forever.
+ */
+const LINEAGE_HOP_CAP = 8
+
+/**
+ * Resolve the binding a session effectively works under: its own, else the
+ * nearest ancestor's.
+ *
+ * A subagent session never gets a binding of its own — `worktree_enter` is
+ * called by the session that wants the worktree — but it works wherever its
+ * parent conversation works: the standing prompt, the chip, and `worktree_exit`'s
+ * diagnostics all answer "which worktree is THIS session in" through here. The
+ * walk is re-resolved on every read, so a session exiting its worktree changes
+ * only its own binding: descendants lend the next bound ancestor up the chain
+ * on their next read (possibly none — the common case — possibly a grandparent's,
+ * which is still the conversation tree they work in) and nothing dangles.
+ *
+ * Own wins over inherited on purpose: a session that enters a worktree of its
+ * own is deliberately somewhere else than its parent.
+ * @param sessionId - the session whose effective binding is wanted.
+ * @param parentOf - session id → parent session id, as `agent/session-start`
+ * delivered it (subagent headers name their parent).
+ * @param bindingOf - binding lookup (the bindings file, or the prompt mirror).
+ * @returns the effective binding, or undefined when neither the session nor any
+ * ancestor (within the hop cap) is bound.
+ */
+export function resolveEffectiveBinding<T>(
+  sessionId: string,
+  parentOf: ReadonlyMap<string, string>,
+  bindingOf: (id: string) => T | undefined,
+): EffectiveBinding<T> | undefined {
+  const own = bindingOf(sessionId)
+  if (own !== undefined) return { binding: own, inherited: false }
+  const seen = new Set<string>([sessionId])
+  let ancestor = parentOf.get(sessionId)
+  for (let hops = 0; ancestor !== undefined && hops < LINEAGE_HOP_CAP; hops += 1) {
+    if (seen.has(ancestor)) return undefined
+    seen.add(ancestor)
+    const binding = bindingOf(ancestor)
+    if (binding !== undefined) return { binding, inherited: true }
+    ancestor = parentOf.get(ancestor)
+  }
+  return undefined
+}
+
+/**
+ * The session's parent edge, read off a dsh session header: the id of the
+ * session this one was delegated by, or undefined for a top-level session (or
+ * a malformed empty value). Both `parentOf` feeds — the `agent/session-start`
+ * listener and the prompt-time self-heal — go through here, so their input
+ * guards cannot drift apart.
+ */
+export function lineageEdgeOf(header: { readonly parentSession?: string } | undefined): string | undefined {
+  const parent = header?.parentSession
+  return typeof parent === 'string' && parent.length > 0 ? parent : undefined
+}
+
+/**
+ * The standing notice for a session's effective binding — the text the
+ * `worktree:binding` prompt context returns. Both variants carry the same two
+ * operational rules; what differs is who holds the binding, and the inherited
+ * variant must NOT offer `worktree_exit` (the caller cannot unbind a parent's
+ * binding — the exit would fail, and the model should not be told to try).
+ * @param name - worktree name (also the directory under `.agents/worktrees/`).
+ * @param branch - branch checked out there, when known.
+ * @param inherited - whether an ancestor, not this session, holds the binding.
+ */
+export function bindingNotice(name: string, branch: string | undefined, inherited: boolean): string {
+  const rel = `.agents/worktrees/${name}`
+  const branchNote = branch === undefined ? '' : ` (branch ${branch})`
+  const opening = inherited
+    ? `This session works in git worktree "${name}"${branchNote}, entered by its parent session.`
+    : `This session is bound to git worktree "${name}"${branchNote}.`
+  const closing = inherited
+    ? 'A path without that prefix acts on the MAIN worktree, not the worktree this conversation works in. '
+      + '(The binding belongs to the parent session; worktree_exit here would not unbind it.)'
+    : 'A path without that prefix acts on the MAIN worktree, not the bound one. Call worktree_exit to unbind.'
+  return `${opening}\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`
+    + closing
+}
+
 export function parseWorktreeList(porcelain: string): WorktreeEntry[] {
   const out: WorktreeEntry[] = []
   let path = ''

package/src/write-checked.ts

@@ -33,7 +33,7 @@
 import { randomBytes } from 'node:crypto'
 
 import { renameWithRetry } from './atomic-json.js'
-import { resolveInside } from './fs-remove.js'
+import { resolveInside } from './path-lock.js'
 import { decodesAsUtf8, isSafePathArg, type OpFailure } from './git-ops.js'
 import type { GitRun } from './apply-blocks.js'