@4fu/dsh-arbor-workspace 0.0.0-stage → 2026.1110.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# dsh-arbor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run [arbor](https://github.com/4fuu/arbor) as the agent driver inside
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).
+
+DSH gives a user a session, a transcript, approvals, plugins, skills and a model
+picker. arbor gives an agent disposable context windows over one shared journal,
+note store and workspace, instead of one long conversation. dsh-arbor connects
+them: one arbor host runs inside the DSH process, each DSH session that selects
+**Arbor** is served by that host, and the window's reply is written back to the
+DSH session as an ordinary assistant message. A DSH session that does not select
+Arbor keeps running on DSH's own embedded AgentLoop, in the same process.
+
+> **Status.** This is a research-grade integration, not a DSH release. It is
+> pinned to one DSH version and relies on DSH internals. Read
+> [Versions and compatibility](docs/versions.md) before installing it on
+> anything you care about. The packages are published under `@4fu` at
+> `2026.1110.1`; the bundle and the font plugin install independently from npm.
+
+## What an arbor session changes
+
+Choosing **Arbor** in a DSH composer creates the session under the `arbor` agent
+preset. That session then runs on arbor, and the following are true for it:
+
+- **One window per turn, one chain per session.** A DSH session is one arbor
+  conversation: its first turn opens a window, a window that ends hands off to a
+  continuation, and the next turn drives the chain. The journal and note store
+  live under `$DSH_HOME/arbor/` and survive a restart.
+- **arbor's workspace, not DSH's sandbox.** A window works in arbor's shared
+  folder (`$DSH_HOME/arbor/shared`). When the `ovnfs` binary is available a
+  window opens a copy-on-write checkout and merges back with `apply`; otherwise
+  arbor uses a plain directory. **There is no DSH sandbox for an arbor session:**
+  arbor's file tools and commands run on the host, and arbor's own secret scrub
+  is the only protection on what reaches the model.
+- **arbor's projects.** The shared folder's project folders are the DSH project
+  list for arbor composers. A directory the user adds outside the shared folder
+  is recorded as an external pointer for that session and used in place.
+- **arbor's prompt and tools.** DSH's official prompt sections are decided one by
+  one; the ones arbor replaces are absent, third-party sections go into a
+  `<dsh>` data block, and a trusted `<harness>` section says what remains true of
+  DSH. DSH tools are offered to the model as arbor external tools, and arbor's
+  own tools replace DSH tools with the same capability.
+- **The Arbor page.** A permanent **Arbor** entry in DSH's left navigation opens
+  the whole-host overview and one tab per arbor session: windows, chains,
+  handoffs, projects, the board, notes, `/env`, schedules and arbor's search.
+  An arbor composer hides DSH's sandbox access-mode switch, because that switch
+  does not apply to it.
+
+## What stays untouched in ordinary DSH sessions
+
+A session that does not select Arbor is an ordinary DSH session. It keeps:
+
+- DSH's embedded AgentLoop, session format, turn boundaries and streaming path;
+- DSH's sandbox policy and its `ctx.fs` / `ctx.shell` file and command tools;
+- DSH's project management, working directory and prompt assembly;
+- its composer, sandbox access-mode switch, header and sidebar behavior.
+
+It gets **no Arbor tab** and no arbor windows. The only shared surface is the
+permanent Arbor entry in the left navigation, which simply does not list that
+session. The routing registry replaces DSH's base `agent` row so it can send
+`agentPreset: 'arbor'` sessions to arbor; every other session goes to the
+official loop. Approvals still use DSH's approval path for both kinds of
+session, and arbor's windows are registered so DSH's sidebar leaves them out.
+
+## Screenshots
+
+| Overview, light | Overview, dark |
+| --- | --- |
+| ![Arbor overview in light mode](docs/screenshots/overview-light.png) | ![Arbor overview in dark mode](docs/screenshots/overview-dark.png) |
+| **Session tab, light** | **Session tab, dark** |
+| ![An arbor session tab in light mode](docs/screenshots/session-light.png) | ![An arbor session tab in dark mode](docs/screenshots/session-dark.png) |
+
+These are the web profile at 1440 px wide with the optional
+[font plugin](https://github.com/4fuu/dsh-arbor-fonts) installed: ChillDIN
+Gothic for labels and ChillDIN for numerals, while body text and code keep
+DSH's fonts. The same overview without the plugin is
+[here](docs/screenshots/overview-without-fonts.png).
+
+## Install
+
+Requirements: Node.js 24.9 or newer and DeepSeek Harness `dsh-v0.2.2-rc.1`.
+The bundle is published with all packages it depends on; nothing has to be
+built or linked.
+
+```bash
+npm install -g @deepseek-ai/dsh@0.2.2-rc.1
+dsh plugin --profile web add @4fu/dsh-arbor-bundle@2026.1110.1
+dsh web
+```
+
+`dsh plugin` adds the bundle to the profile's `dsh.profile.bundles` and installs
+its packages into the profile. The packages declare DSH's runtime packages as
+peer dependencies, so the profile keeps DSH's own copies rather than installing
+a second set. Pick **Arbor** in a composer and send a message.
+The optional [font plugin](https://github.com/4fuu/dsh-arbor-fonts) installs the
+same way, but it is a Host row rather than a bundle. Add the row to the
+profile's `cordis.patch.yml` after installing it:
+
+```bash
+dsh plugin --profile web add @4fu/dsh-arbor-fonts@2026.1110.0
+```
+
+```yaml
+- insert:
+    - id: arbor-fonts
+      name: '@4fu/dsh-arbor-fonts'
+```
+
+Replace the default `[]` in that file with the entry, then restart the profile.
+
+### From a checkout
+
+The proofs and development use the TypeScript sources directly; that checkout is
+what the scripts and the pin check run against.
+
+```bash
+git clone https://github.com/4fuu/dsh-arbor
+cd dsh-arbor
+pnpm install --frozen-lockfile
+pnpm check                 # tsc --noEmit over every package and proof
+pnpm proofs                # 29 proofs against the scripted model
+```
+
+The first install may ask pnpm to approve dependency build scripts. Do not
+approve them by hand: the repository's `pnpm-workspace.yaml` already denies the
+six scripts it pulls in, each with the reason, and `pnpm install` finishes
+cleanly with that policy.
+
+### Hand the install to a model
+
+[docs/install-for-agents.md](docs/install-for-agents.md) is a step-by-step guide
+written for an AI agent: install from npm or a checkout, run the proofs, drive a
+live turn with a restart, boot the web profile, and inspect what ran. Give a
+model this prompt, editing the bracketed parts or dropping them:
+
+```text copy Copy Install Prompt
+Install dsh-arbor (https://github.com/4fuu/dsh-arbor) in this environment [in a
+scratch DSH home under /tmp] and show me that it works: follow
+docs/install-for-agents.md, install @4fu/dsh-arbor-bundle@2026.1110.1 into a DSH
+web profile, pick Arbor for one session, and [also run the proof suite from a
+checkout with pnpm install --frozen-lockfile, pnpm check and pnpm proofs]. Report
+which checks passed, what the live session answered, and anything that did not
+work. Fix only what is yours to fix and tell me what you changed.
+```
+
+## Use it in DSH
+
+The npm install above adds the bundle to a DSH web profile. Pick **Arbor** in a
+composer and send a message: the session is created under the preset, its window
+and chain appear under the **Arbor** entry, and an ordinary session started
+beside it keeps DSH's own composer and sandbox behavior. A checkout can also be
+wired by hand; [section 7 of the install guide](docs/install-for-agents.md#7-wiring-the-bundle-into-a-real-dsh-installation)
+shows the profile layout.
+
+The one-shot `dsh <task>` runner cannot drive an arbor-preset session: DSH's
+runner refuses to adopt a session that runs under a preset. Use the web client,
+the SDK path the proofs use, or a remote `agent-preset/select` on a blank.
+
+## Pinned DSH version
+
+DSH is pinned to **`dsh-v0.2.2-rc.1`** (npm
+`@deepseek-ai/dsh@0.2.2-rc.1`, commit `66491b05e3` of
+`deepseek-ai/deepseek-harness`). Every `@deepseek-ai/dsh*` dependency is an
+exact version, every package under `packages/` declares
+`engines.dsh: 0.2.2-rc.1`, and `pnpm check:pin` checks both plus the prompt
+bridge's `DSH_PINNED_VERSION`. DSH's runtime packages are peer dependencies, and
+`pnpm check:profile` installs the packed packages into a fresh DSH web profile to
+prove the profile keeps one copy and can create both kinds of session.
+
+A different DSH version is unsupported. The bundle depends on DSH's row names,
+its one-`AgentFactory` rule, its prompt-section registry, its client slot
+registration and its exact Fetch registry; a move in any of them can fail the
+boot, leave an official prompt section undecided, or stop the Arbor page from
+registering. `proofs/12-official-sections.ts` and `proofs/18-picker-pin.ts`
+are the behavioral checks. The canonical pin and the upgrade procedure are in
+[Versions and compatibility](docs/versions.md).
+
+## Optional: the font plugin
+
+[dsh-arbor-fonts](https://github.com/4fuu/dsh-arbor-fonts) is a separate DSH
+client plugin that changes only the typography of the Arbor page. It sets
+ChillDIN Gothic for display labels and ChillDIN for numerals, leaves body text
+and code on DSH's fonts, and does nothing on ordinary pages. It is optional and
+installs into the same DSH profile:
+
+```bash
+dsh plugin --profile web add @4fu/dsh-arbor-fonts@2026.1110.0
+```
+
+The fonts are licensed under the SIL Open Font License 1.1; the plugin ships the
+license text, per-file hashes and attribution. The plugin is a Host row rather
+than a bundle: after installing it, add the `arbor-fonts` entry described under
+[Install](#install) to `cordis.patch.yml` and restart the profile.
+
+## Limits worth knowing
+
+- The judge is off: a model-based judge cannot run through the DSH backend yet.
+- The 12 bundle packages are published together at one version; install and
+  upgrade the bundle as a unit, because its packages name each other exactly.
+- `ovnfs` is optional. Without it arbor uses the plain-directory workspace, and a
+  window no longer gets a copy-on-write checkout.
+- The web page's numbers and layout are read from arbor's journal and API; it is
+  not a generic DSH dashboard, and it deliberately shows only arbor sessions.
+- The prompt bridge, the UI and the picker filter are pinned to DSH's internals,
+  not to a stable public API. See [Versions and compatibility](docs/versions.md).
+
+## Documentation
+
+- [Installing and inspecting dsh-arbor](docs/install-for-agents.md) — the
+  agent-facing install, proof, live-turn, web-profile and wiring guide.
+- [Versions and compatibility](docs/versions.md) — the DSH and arbor pins, and
+  what breaks on another DSH version.
+- [B0 findings](docs/b0-findings.md), [B3 findings](docs/b3-findings.md) and
+  [B3b projects and sandbox](docs/b3b-projects-and-sandbox.md) — historical
+  records of the integration's decisions, with the DSH source locations each
+  one rests on. They describe earlier stages; the install guide is the current
+  status.
+- [Layout and proofs](#layout) below for a quick map of the packages.
+
+## Layout
+
+```text
+packages/
+  arbor-host/       one Arbor host per process: SQLite journal and notes,
+                    settings, window lifecycle, workspace and environment
+  arbor-driver/     the routing AgentRegistry, AgentFactory, session agent,
+                    inbox and stream mirrors, and the journal relay
+  arbor-llm/        the arbor AgentBackend over DSH's ctx.llm and ctx.tools
+  arbor-prompt/     <harness>, the <dsh> data block, and the section table
+  arbor-tools/      DSH tools as arbor external tools, same-name replacement
+  arbor-workspace/  arbor's workspace over the shared folder (ovnfs or dir)
+  arbor-env/        /env, with DSH's skills and MCP servers mounted read-only
+  arbor-bundle/     the installable patch that mounts the rows and UI
+  arbor-facts/      the read face behind the Arbor page and its Fetch routes
+  arbor-ui/         the Arbor page, session tabs, copy and composer gate
+  arbor-ui-workspace/
+                    the per-preset hero project picker
+  arbor-preset/     the agent-preset row that puts Arbor in the roster
+  arbor-testkit/    the boot harness, memory journal and scripted model
+patches/            overlay layers a proof applies above the shipped profile
+proofs/             one runnable proof per integration point
+docs/               install, versions, screenshots and historical findings
+scripts/            the pin and profile checks, the release build and packing
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE). The optional font plugin vendors fonts under the
+SIL Open Font License 1.1; its repository carries the license text and
+attribution.

package/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @4fu/dsh-arbor-workspace — arbor's own workspace over the shared folder, and
+ * the DSH project bridge.
+ *
+ * For arbor sessions arbor's tools run on the host the way they do in standalone
+ * arbor, so the workspace is arbor's own: ovnfs when its daemon starts, the
+ * plain-directory workspace otherwise, both rooted at the arbor shared folder
+ * under `DSH_HOME/arbor`. There is no DSH sandbox seam here, no `sandbox_escalate`
+ * and no `fileToolsSandboxed`; the `<workspace>` section and the `workspace.*`
+ * module functions are arbor's own.
+ *
+ * `DshProjectBridge` is the other half of arbor taking over DSH's project
+ * management: it makes the shared folder's project subfolders the DSH project
+ * list (`ctx.workspaceRegistry`), and it records an existing directory with its
+ * own path as an external pointer (name and absolute path, no copy) that
+ * arbor's prompt names, rather than adopting it into the shared folder.
+ */
+export { openArborWorkspace, arborSharedFolder, withArborWorkspace, type ArborWorkspace, type ArborWorkspaceOptions, } from './workspace.js';
+export { withPointerSection, POINTER_BLOCKS, POINTER_TEXT, type PointerSource, } from './section.js';
+export { DshProjectBridge, type DshProject, type DshProjectBridgeOptions, type ExternalPointer, type ExternalProject, } from './projects.js';

package/index.js

@@ -0,0 +1,20 @@
+/**
+ * @4fu/dsh-arbor-workspace — arbor's own workspace over the shared folder, and
+ * the DSH project bridge.
+ *
+ * For arbor sessions arbor's tools run on the host the way they do in standalone
+ * arbor, so the workspace is arbor's own: ovnfs when its daemon starts, the
+ * plain-directory workspace otherwise, both rooted at the arbor shared folder
+ * under `DSH_HOME/arbor`. There is no DSH sandbox seam here, no `sandbox_escalate`
+ * and no `fileToolsSandboxed`; the `<workspace>` section and the `workspace.*`
+ * module functions are arbor's own.
+ *
+ * `DshProjectBridge` is the other half of arbor taking over DSH's project
+ * management: it makes the shared folder's project subfolders the DSH project
+ * list (`ctx.workspaceRegistry`), and it records an existing directory with its
+ * own path as an external pointer (name and absolute path, no copy) that
+ * arbor's prompt names, rather than adopting it into the shared folder.
+ */
+export { openArborWorkspace, arborSharedFolder, withArborWorkspace, } from "./workspace.js";
+export { withPointerSection, POINTER_BLOCKS, POINTER_TEXT, } from "./section.js";
+export { DshProjectBridge, } from "./projects.js";

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@4fu/dsh-arbor-workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1110.1",
+  "type": "module",
+  "description": "Arbor's own workspace over the shared folder (ovnfs, or the plain-directory fallback), with no DSH sandbox, and the bridge that makes the shared folder's projects the DSH project list",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.d.ts",
+    "index.js",
+    "projects.d.ts",
+    "projects.js",
+    "section.d.ts",
+    "section.js",
+    "workspace.d.ts",
+    "workspace.js"
+  ],
+  "dependencies": {
+    "@4fu/arbor-core": "2026.1109.1",
+    "@4fu/arbor-interfaces": "2026.1109.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-workspace": "0.2.2-rc.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/dsh-arbor.git",
+    "directory": "packages/arbor-workspace"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "0.2.2-rc.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js"
+}

package/projects.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The DSH project list, backed by arbor's shared folder.
+ *
+ * DSH models a project as a `Workspace` in its durable `WorkspaceRegistry`
+ * (`ctx.workspaceRegistry`, `@deepseek-ai/dsh-workspace`): a stable id over a
+ * canonical host directory, a title and an ordered session account. The web
+ * client's project list, project picker and creation all read that registry, so
+ * making arbor's projects appear there is what puts them in the UI — no client
+ * patch is needed for the list itself.
+ *
+ * Arbor's decision, which reverses B3: for arbor sessions arbor takes over DSH's
+ * project management, and a DSH project is a project subfolder of arbor's shared
+ * folder (`DSH_HOME/arbor/shared`, ovnfs's source). This bridge keeps that true:
+ *
+ *  - {@link DshProjectBridge.sync} lists the shared folder's subfolders and
+ *    registers each as a DSH `Workspace`, idempotently (the same canonical path
+ *    reuses the existing record). It runs at host start and again whenever the
+ *    shared folder changes, so a project a window creates with `mkdir` shows up
+ *    without a restart.
+ *  - {@link DshProjectBridge.resolveProject} answers where an arbor session
+ *    works: a requested directory that is already inside the shared folder is a
+ *    project; the shared folder itself means "no specific project yet"; and a
+ *    directory outside the shared folder is answered as itself, so the session's
+ *    cwd is the directory the user picked for it. That directory is also
+ *    recorded as a {@link ExternalPointer} (name and absolute path) when the user
+ *    added it through DSH's own add-workspace action — never copied, linked or
+ *    adopted, because the owner's decision is no copy: arbor's tools run on the
+ *    host, so the model can work in the user's own directory directly, and the
+ *    pointer line in arbor's prompt says so. Arbor's own window still works in
+ *    arbor's own directory either way; the pointer is what names the user's
+ *    files. The pointer is recorded for the session that asked for it — see
+ *    {@link addedDirectories} for which directory counts as asked for — so a
+ *    session that never asked never has the line in its prompt.
+ *
+ * The registry is process-global, so this reflects arbor's projects for every
+ * reader; DSH offers no per-session view of the workspace list (see
+ * `docs/b3b-projects-and-sandbox.md`), so hiding arbor's projects from an
+ * ordinary session's picker is not something this bridge can do. Ordinary
+ * sessions keep their own cwd and sandbox on the embedded AgentLoop regardless —
+ * this bridge never touches a session's own directory or its log.
+ */
+import type { WorkspaceId, WorkspaceRegistry } from '@deepseek-ai/dsh-workspace';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** One project as this bridge reports it. */
+export interface DshProject {
+    readonly id: WorkspaceId;
+    readonly path: string;
+    readonly title: string;
+}
+/**
+ * One external directory recorded as a pointer.
+ *
+ * The owner's decision for an existing DSH project with its own path is no copy,
+ * no mount and no adoption: the session goes to arbor's own directory (the
+ * shared folder) and the user's original directory is recorded as a pointer, so
+ * arbor's prompt can name it and the model can work in it directly (arbor's
+ * tools run on the host, so the absolute path is reachable). A pointer is never
+ * registered as a project arbor works in — it is a fact in the prompt, not a
+ * checkout.
+ */
+export interface ExternalPointer {
+    /** The directory's basename, the name the prompt shows. */
+    readonly name: string;
+    /** The absolute path the prompt names, where the user's own files are. */
+    readonly path: string;
+}
+/** One project of the shared folder: the one a session works in. */
+export interface ExternalProject {
+    /** The project folder's own name, the name the DSH project list shows. */
+    readonly name: string;
+    /** The project's absolute path, a subfolder of the shared folder. */
+    readonly path: string;
+}
+/** What this bridge needs. */
+export interface DshProjectBridgeOptions {
+    /**
+     * DSH's durable workspace registry, for a deployment that has one when this
+     * bridge is built. A deployment whose registry activates later — the web
+     * profile's activates after the arbor host — attaches it with
+     * {@link DshProjectBridge.attach} instead; absent throughout leaves the bridge
+     * inert.
+     */
+    readonly registry?: WorkspaceRegistry | undefined;
+    /** The arbor shared folder: the projects' home and ovnfs's source. */
+    readonly sharedFolder: string;
+    /** Called with a non-fatal note, such as an adopt or sync failure. */
+    readonly warn?: (message: string) => void;
+}
+export declare class DshProjectBridge {
+    private registry;
+    private readonly sharedFolder;
+    private readonly warn;
+    private watcher;
+    private debounce;
+    /**
+     * Recorded external directories, per session: name -> absolute path. Never
+     * projects. A session's set is what that session's `<workspace>` section
+     * names, so a directory one session's user added is invisible to a session
+     * that never asked for it.
+     */
+    private readonly pointers;
+    /**
+     * Canonical paths of directories the user added through DSH's own
+     * add-workspace action, recorded by the {@link watchCreates} hook on the
+     * registry. A pointer is recorded for an arbor session only when the session
+     * names one of these: a directory the user deliberately added is a directory
+     * the user means arbor to name, while a cwd a session merely inherited (DSH's
+     * first-use default workspace, the most recent workspace) is not.
+     */
+    private readonly added;
+    constructor(options: DshProjectBridgeOptions);
+    /**
+     * Attach DSH's durable workspace registry, register the shared folder's
+     * projects in it, and keep the list live from then on. Returns a disposer.
+     *
+     * The registry is a web-profile service that activates after the arbor host
+     * does, so a deployment cannot read it while the host is being built; this is
+     * the seam that connects the two, the same one `@4fu/dsh-arbor-preset` uses
+     * for the preset roster.
+     */
+    attach(registry: WorkspaceRegistry): () => void;
+    /**
+     * Watch `WorkspaceRegistry.create` and remember every directory it registers
+     * outside the shared folder.
+     *
+     * This is the seam that makes DSH's own add-workspace action record a pointer
+     * for an arbor session with no new verb and no client change: the client's
+     * add-workspace action calls the `workspace/create` remote verb
+     * (`@deepseek-ai/dsh-api-workspace-controller`, `create`), which is the one
+     * caller of `WorkspaceRegistry.create` in a DSH installation besides this
+     * bridge's own {@link sync} — and `sync` only ever names project subfolders of
+     * the shared folder, which the outside-shared-folder rule already excludes.
+     * DSH's first-use default workspace is registered by
+     * `WorkspaceRegistry.initializeDefault`, a different method that never reaches
+     * `create`, so an inherited cwd is never mistaken for an added directory.
+     *
+     * The hook is a wrapper on the registry instance this bridge was handed,
+     * restored never: the instance lives as long as the process, and the wrapper
+     * delegates to the original for every call.
+     */
+    private watchCreates;
+    /**
+     * Every canonical path the user added through DSH's add-workspace action, in
+     * add order. A directory is added once and stays added: it is a fact about
+     * what the user put in the project list, not about the session that asked.
+     */
+    addedDirectories(): readonly string[];
+    /** Whether the user added this directory through DSH's add-workspace action. */
+    isAddedDirectory(path: string): boolean;
+    /** Whether a requested directory already names the shared folder itself. */
+    isSharedFolder(path: string): boolean;
+    /** Whether a requested directory already sits inside the shared folder. */
+    insideSharedFolder(path: string): boolean;
+    /**
+     * The project a directory names, or undefined when it names none.
+     *
+     * A project is a subfolder of the shared folder, which is the one place a
+     * project lives: the shared folder itself is "no specific project yet", and a
+     * directory outside it is not a project at all (it is a pointer, when the user
+     * added it). The name is the folder's own, so the prompt, the DSH project list
+     * and the checkout a window opens all name the same thing.
+     */
+    projectOf(path: string | undefined): ExternalProject | undefined;
+    /**
+     * Where one arbor session works: the directory its caller named.
+     *
+     * The shared folder itself (or nothing) is answered as-is — a session works in
+     * the shared folder and opens a checkout of whichever project it needs, which
+     * is what "an arbor session is not bound to one cwd" means. A path already
+     * inside the shared folder is a project and is answered as-is, after a sync so
+     * a project a window just made is in DSH's list.
+     *
+     * A directory outside the shared folder is answered as-is too. That reverses
+     * the b3c rule, which moved such a session into the shared folder, and the
+     * reason is DSH's own membership rule: a workspace's `sessionIds` are filtered
+     * by the session's stored cwd (`@deepseek-ai/dsh-workspace`,
+     * `WorkspaceEntity.sessionIds` → `candidateMatches` →
+     * `sessionPaths.get(id) === path`), and `Workspace.attachSession` refuses a
+     * session whose cwd is not the workspace's path. So a session whose cwd was
+     * moved into the shared folder belongs to no workspace the user can see, and
+     * the only way to give it one was to register the shared folder itself — a
+     * row that names arbor's internal folder rather than anything the user
+     * picked. Answering the requested directory as-is makes the DSH session, its
+     * cwd display, the project picker and the sidebar row name one directory:
+     * the project the user picked, or the directory the user added.
+     *
+     * What does not change is where the *window* works: arbor's own directory
+     * under `DSH_HOME/arbor`, reading the shared folder through ovnfs and opening
+     * checkouts in it. The session's cwd is a DSH-side fact — the cwd display, the
+     * project line, the workspace membership — and arbor's prompt says where the
+     * window works in its own words, so the two never contradict each other.
+     *
+     * Recording an outside directory as an {@link ExternalPointer} is NOT done
+     * here. This runs for every arbor session, whatever directory its caller
+     * happened to name, and a pointer is a deliberate record of a directory the
+     * user means arbor to name — a session's requested cwd is not that. The
+     * deliberate callers are {@link addPointer}: the driver, for a session that
+     * became an arbor session while naming a directory the user had added through
+     * DSH's own add-workspace action ({@link addedDirectories}), and the model.
+     */
+    resolveProject(requested: string | undefined): Promise<string>;
+    /**
+     * Record an existing directory as an external pointer for one session: no
+     * copy, no link, no adoption, and never a registered project. The caller that
+     * means it — the driver, for a session that became an arbor session while
+     * naming a directory the user added, or the model — names the directory and
+     * the session it belongs to, and its name and absolute path are recorded so
+     * arbor's prompt can name where the user's own files are; arbor's tools run
+     * on the host, so the model reaches the path directly and a change there
+     * lands on the user's files with no checkout and no apply. A second call for
+     * the same name overwrites the path, so pointing a name at a new directory is
+     * one edit.
+     */
+    addPointer(sessionId: SessionId, externalPath: string): ExternalPointer;
+    /** Drop a pointer by name for one session; a no-op when the name is not recorded. */
+    removePointer(sessionId: SessionId, name: string): void;
+    /**
+     * Every pointer one session recorded whose directory still exists, true at the
+     * moment it is read: a pointer whose directory is gone is dropped here, so the
+     * prompt never names a path that no longer exists. Sorted by name for a stable
+     * line. An unknown session has none, which is the answer a window whose
+     * session cannot be named gives — never another session's list.
+     */
+    listPointers(sessionId: SessionId | undefined): Promise<readonly ExternalPointer[]>;
+    /**
+     * A revision that moves whenever any session's live pointer set moves, so a
+     * running window's section is re-rendered — and handed a delta of only the
+     * changed line — the moment the set changes. The host asks for it once per
+     * step, so the existence check lives here: reading it drops a pointer whose
+     * directory has gone, which moves the revision, which drops the line from the
+     * prompt. It is a digest of every session's live set rather than a counter, so
+     * a pointer removed and re-added at the same path costs nothing.
+     */
+    pointerRevision(): Promise<string>;
+    /**
+     * Make one arbor session a member of the workspace that owns the directory it
+     * works in, so DSH's own hero composer has a workspace to name and the sidebar
+     * shows the session where the user picked it.
+     *
+     * DSH answers "which workspace is this session in" from the workspace whose
+     * member list names it, and filters a workspace's members by the session's
+     * stored cwd (`@deepseek-ai/dsh-workspace`, `WorkspaceEntity.sessionIds` ->
+     * `candidateMatches`), so an arbor session is only ever a member of a
+     * workspace whose path is the directory it works in. Without this, a session
+     * the driver created or re-routed under arbor belongs to no workspace at all,
+     * and the hero composer answers `chipTitle === undefined` and renders inert
+     * (`@deepseek-ai/dsh-client-ui-conversation`, `lib/client.js`:
+     * `inert = sessionId === void 0 || hero && chipTitle === void 0`) — the dead
+     * composer the outside-directory add used to leave behind.
+     *
+     * **The shared folder is never registered.** It is arbor's own internal
+     * directory, not a project the user made, so a DSH workspace row for it would
+     * name something the user never picked. A session whose cwd is the shared
+     * folder itself therefore belongs to no workspace: nothing in the web profile
+     * creates one, because every session there is created in a workspace
+     * (`session/create` takes `workspaceId` or `cwd`, and the picker and the
+     * add-workspace flow both name a workspace).
+     *
+     * A project subfolder of the shared folder is registered the same way
+     * {@link sync} registers one, so a project a window made with `mkdir` is a
+     * workspace the session can belong to. A directory outside the shared folder
+     * is only attached to when DSH's list already has it — which is the case for
+     * every directory a user added through DSH's own add-workspace action, since
+     * that action registers it before it is picked. Registering one here would add
+     * a project-list row for a directory nobody added.
+     */
+    attachWorkspace(sessionId: SessionId, cwd: string): Promise<void>;
+    /** Every project subfolder of the shared folder, registered in DSH's registry. */
+    sync(): Promise<readonly DshProject[]>;
+    /** The projects currently registered, as this bridge last synced the disk. */
+    list(): Promise<readonly DshProject[]>;
+    /**
+     * Watch the shared folder and re-sync when a project appears or disappears, so
+     * a project a window creates with `mkdir` reaches the DSH project list without
+     * a restart. Returns a disposer.
+     */
+    start(): () => void;
+    /** Stop watching. */
+    stop(): void;
+}