@4fu/dsh-arbor-host 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,383 @@
+/**
+ * The one Arbor host a DSH process runs.
+ *
+ * Arbor's point is one journal, one note store and one board across many
+ * sources, so a DSH process mounts exactly one `Arbor` host and every DSH user
+ * session is one source (one conversation target) of it. This row owns that
+ * host:
+ *
+ *  - the durable storage under `DSH_HOME/arbor/` — `@4fu/arbor-journal-sqlite`
+ *    for the journal and `@4fu/arbor-notes-sqlite` for the note store, both on
+ *    `node:sqlite`, so nothing native has to build and an arbor window survives
+ *    a DSH restart (the host rebuilds every running window from the journal in
+ *    `Arbor.start`);
+ *  - the DSH-backed `AgentBackend` (`@4fu/dsh-arbor-llm`), which runs each
+ *    window's turns through `ctx.llm` and each tool call through
+ *    `ctx.tools.execute`;
+ *  - the two prompt plugins (`@4fu/dsh-arbor-prompt`): a trusted `<harness>`
+ *    section this bridge writes, and a `<dsh>` data block for third-party
+ *    material;
+ *  - the deployment's persona, read out of DSH's own assembly once and merged
+ *    into arbor's `<identity>` section, because it is the deployment's
+ *    configuration rather than a section of its own;
+ *  - the environment (`@4fu/dsh-arbor-env`): arbor's own under
+ *    `DSH_HOME/arbor/env`, with DSH's skills and MCP servers mounted read-only
+ *    beside them;
+ *  - the workspace (`@4fu/dsh-arbor-workspace`): arbor's own, over the shared
+ *    folder under `DSH_HOME/arbor` — ovnfs when its daemon starts, the plain
+ *    directory workspace otherwise. For arbor sessions there is no DSH sandbox:
+ *    arbor's tools run on the host the way they do in standalone arbor, and the
+ *    only protection is arbor's own secret scrub;
+ *  - the project bridge (`@4fu/dsh-arbor-workspace`): the shared folder's
+ *    project subfolders are registered in DSH's own `workspaceRegistry`, so
+ *    arbor's projects are the DSH project list a user picks from;
+ *  - the `send` executor (`./send.ts`): a window's `send` lands on the DSH
+ *    session log as an assistant message, which is the only surface the user
+ *    reads;
+ *  - the settings, whose window block is left to arbor's own defaults: a window
+ *    stays open 300 s after its run ends and the next input for the session
+ *    opens the next window of its chain.
+ *
+ * The judge is off on purpose in B1: every judge decision is model-based, and
+ * a model-based judge cannot run through the DSH backend yet. With the judge
+ * off, `host.dispatch` is deterministic — one window per session target,
+ * opened on the session's first turn — which is the routing policy B1 ships.
+ *
+ * There is no `workspaces.retentionMs` here: ovnfs checkouts are a window's own
+ * work, and a chain that ends leaves them where they are until a retention
+ * period is set, exactly as arbor's own defaults do. Nothing here is reclaimed
+ * by default, and the shared folder's projects are never removed — they are the
+ * user's work, not arbor's to delete.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Environment, Journal, NoteStore, Plugin, Settings, Target, WindowRef, Workspace } from '@4fu/arbor-interfaces';
+import { Arbor } from '@4fu/arbor-core';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type DshBackend } from '@4fu/dsh-arbor-llm';
+import { DshProjectBridge, type DshProject, type ExternalPointer, type ExternalProject } from '@4fu/dsh-arbor-workspace';
+import type { WorkspaceBackend } from '@4fu/arbor-core';
+export { DshSendExecutor, DSH_TARGET_PREFIX, DSH_USER_TARGET } from './send.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The one Arbor host this DSH process runs. */
+        arborHost: ArborHostService;
+    }
+}
+/** Plugin config: the data root and extra arbor settings, merged over the defaults. */
+export interface Config {
+    /** Where the journal and the note store live. Defaults to `<DSH home>/arbor`. */
+    readonly root?: string;
+    /** Extra arbor settings, merged over {@link defaultSettings}. */
+    readonly settings?: Settings;
+}
+/**
+ * The settings this deployment runs arbor with.
+ *
+ * The identity is this bridge's own sentence, in Chinese like every other
+ * model-facing line dsh-arbor writes, and it says only what is true and not
+ * already said: `<harness>` states that the window runs inside DeepSeek
+ * Harness and that the user sees only what `send` writes, and arbor's own
+ * `<agent>` rules state that a window is disposable and that its chain
+ * continues. Nothing here repeats either, and nothing here claims one DSH
+ * session is one arbor window — several windows serve one source and each ends
+ * on its own.
+ *
+ * `generalRules` is deliberately absent: arbor's own defaults are the seven
+ * rules every window needs, in Chinese, and B0's English replacements dropped
+ * them and restated two of them wrongly.
+ *
+ * The window block is deliberately absent too: arbor's own defaults apply
+ * (300 s idle, 200 000 context tokens, 4 000 reserved), so a window that goes
+ * quiet ends and the session's next turn opens the next window of its chain.
+ *
+ * The workspaces block is deliberately absent as well: the workspace is arbor's
+ * own over the shared folder, ovnfs checkouts are a window's own work, and the
+ * shared folder's projects are never reclaimed — so with no retention period
+ * nothing is removed.
+ */
+export declare function defaultSettings(extra: Settings | undefined): Settings;
+/** The target prefix that names the DSH session a window belongs to. */
+export declare const SESSION_TARGET_PREFIX = "dsh:session:";
+/** The conversation target one DSH user session is, for arbor's dispatch. */
+export declare function sessionTarget(sessionId: string): Target;
+/** The DSH session a conversation target names, or undefined for any other target. */
+export declare function sessionOfTarget(target: Target): SessionId | undefined;
+/**
+ * The plugin that records which DSH session each window serves.
+ *
+ * Arbor's `windowStart` hook runs before the `window_start` event is appended
+ * and before the window's prompt epoch is rendered, and it carries the window
+ * ref together with the task's targets — the only moment at which a window can
+ * be attributed to a session before its prefix is built. A prompt section that
+ * answers per session (the external-project pointers, the project line) is
+ * rendered for a window, and a window's prefix is frozen when it opens, so the
+ * attribution has to exist by then: reading it later would put those lines in a
+ * delta of the window's opening instead of in the prefix it opens with.
+ *
+ * The `windowContinue` hook is the same moment for a continuation window, which
+ * carries no targets of its own — a continuation continues its predecessor's
+ * work, so it serves the session that window served. Without it a window the
+ * host continues (the hard limit, an idle handover, a restart's recovery) opens
+ * with a prefix that names no session and loses both per-session lines.
+ *
+ * The hooks observe and change nothing, so a window they cannot attribute — one
+ * dispatched from outside a DSH session — opens exactly as it would without them.
+ *
+ * @param note - called with the window and the session it serves.
+ * @param sessionOf - the session a window already recorded serves, for a
+ *   continuation to inherit.
+ */
+export declare function windowSessionPlugin(note: (window: WindowRef, sessionId: SessionId) => void, sessionOf: (window: WindowRef) => SessionId | undefined): Plugin;
+/** The one Arbor host per DSH process, and the storage it runs on. */
+export declare class ArborHostService extends Service {
+    static inject: string[];
+    static Config: z<Config, Config>;
+    readonly config: Config;
+    private state;
+    /**
+     * Which DSH session each window serves, written by the `windowStart` hook
+     * before the window's prefix is built. Arbor's own `WindowRef` carries no
+     * session identity, and a per-session prompt section is rendered for a window,
+     * so this is the mapping that section reads.
+     */
+    private readonly windowSessions;
+    /**
+     * The stored cwd of a session whose agent is not live, read once. A session's
+     * stored header never moves, so the answer is remembered; the live projection
+     * takes over the moment the session is back.
+     */
+    private readonly storedCwds;
+    /** Raised whenever a DSH prompt provider changes, so both sections follow. */
+    private promptChanges;
+    /** Plan mode's projection, so the `<harness>` section can read it per step. */
+    private planProjection;
+    /** The deployment's persona, read once when the host is built. */
+    private persona;
+    /** The last provider and model a live session rendered under, for the fallback. */
+    private lastProvider;
+    private lastModel;
+    /** The warnings the bridge raised while the host was built, for diagnostics. */
+    readonly warnings: string[];
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * The dynamic state the `<harness>` section renders, read for the session
+     * whose turn is running.
+     *
+     * A section is frozen per epoch and shared by every window of it, so a
+     * session's own policy is the one whose turn is rendering — the same rule
+     * arbor's `<workspace>` section follows for its root. A window a restart
+     * continued renders outside any turn and therefore without these lines until
+     * its session's next turn moves the revision and delivers them as a delta.
+     */
+    private harnessState;
+    /** The plan-mode state of one session, from the host's own registration. */
+    private planReader;
+    /**
+     * Note that a DSH prompt input changed without a `system-prompt/change`.
+     *
+     * The driver calls this after it installs the arbor tool restriction in a
+     * session's scope: a `tool:*` section's text reads whether its tool is
+     * registered, and the restriction moves that without a registration change.
+     */
+    noteDshPromptChange(): void;
+    /**
+     * The deployment's persona lines, with DSH's prompt variables resolved
+     * against the session whose turn is rendering.
+     *
+     * A window a restart continued renders outside any turn, so the last values
+     * a live session gave are the fallback: the persona then names the model that
+     * session was running rather than carrying a placeholder.
+     */
+    private personaLines;
+    private requireState;
+    /** The one Arbor host of this process. */
+    get host(): Arbor;
+    /** The durable journal every window of this process records into. */
+    get journal(): Journal;
+    /** The durable note store beside the journal. */
+    get notes(): NoteStore;
+    /** The settings this host runs arbor with. */
+    get settings(): Settings;
+    /**
+     * Arbor's own workspace over the shared folder: the implementation every
+     * window's files go through, and the one a read-only surface asks for the
+     * chain's checkouts, keeps and open work.
+     */
+    get workspace(): Workspace;
+    /** The environment every window reads at `/env`, DSH's items mounted beside arbor's. */
+    get environment(): Environment;
+    /** The arbor shared folder: the projects' home and ovnfs's source. */
+    get sharedFolder(): string;
+    /** Which workspace backend arbor settled on: `ovnfs` or `dir`. */
+    get workspaceBackend(): WorkspaceBackend;
+    /** The DSH project bridge over the shared folder. */
+    get projects(): DshProjectBridge;
+    /**
+     * The DSH session whose work this window runs, or undefined while nothing
+     * attributes it. A window a restart continued before its session came back
+     * answers undefined until the session resumes and its next turn opens the
+     * window's own chain entry; the pointer section then reads no pointers rather
+     * than another session's.
+     */
+    sessionOfWindow(window: WindowRef): SessionId | undefined;
+    /**
+     * The project of the shared folder the named window's session works in, or
+     * undefined when it works in none.
+     *
+     * The project is read from the session's own current directory, which the
+     * driver resolves into the shared folder for every arbor session — created
+     * under arbor, re-routed onto it, or resumed after a restart — so a session the
+     * user opened on a project and a session that picked arbor afterwards answer
+     * the same way.
+     */
+    projectOfWindow(window: WindowRef | undefined): Promise<ExternalProject | undefined>;
+    /**
+     * The directory one session works in, the way DSH answers it.
+     *
+     * The `workingDirectory` projection is DSH's own answer for a session's
+     * current directory — the cwd display, the session listing and the skill
+     * catalog all read it — while the session header carries the directory the
+     * session was created with and never moves. A session whose directory changed
+     * therefore names the new one, which is what the project line has to say: the
+     * alternative is a prompt that names a project the UI no longer shows.
+     *
+     * A window recovered before its session resumed has no live agent to read —
+     * the host continues it at boot, long before the user opens the session again
+     * — and its prefix is frozen then. The stored session header is the durable
+     * answer for that moment, the same one the driver resolves a resume from, so
+     * the recovered window opens naming the project it was opened on. It is read
+     * once per session and remembered: a session's stored header never moves, and
+     * the live answer takes over the moment the session is back.
+     */
+    /**
+     * The directory one session works in, the way the `<workspace>` section reads
+     * it: DSH's `workingDirectory` projection when the session is live, the
+     * stored header otherwise. A read-only surface that names the session's
+     * project asks this rather than re-deriving it.
+     */
+    directoryOf(sessionId: SessionId): Promise<string | undefined>;
+    private directoryOfSession;
+    /** The cwd a persisted session was created with, or undefined without a store. */
+    private storedCwdOf;
+    /**
+     * A revision that moves whenever anything the `<workspace>` section names
+     * moves: any session's pointers, or any session's project. The host asks for it
+     * once per step, so a window whose session picks another project before its
+     * first turn is handed a delta of only the project line, and a session that
+     * gains or loses a pointer is handed a delta of only that line.
+     */
+    private workspaceRevision;
+    /**
+     * Every session the `<workspace>` section answers for: the live ones, plus the
+     * ones a recovered window still names — a window the host continued at boot
+     * belongs to a session whose agent is not back yet, and its project is part of
+     * what the section says.
+     */
+    private sessionProjects;
+    /**
+     * Where one arbor session works: a project folder inside the shared folder.
+     *
+     * The driver calls this for an arbor session's requested cwd and sets the
+     * session's cwd to the answer, so the DSH session, its cwd display and the
+     * project picker all agree on the shared folder. A directory outside the
+     * shared folder is not copied; it joins the shared folder only through
+     * {@link adoptArborProject}.
+     */
+    resolveArborCwd(requested: string | undefined): Promise<string>;
+    /**
+     * Whether the user added this directory through DSH's own add-workspace
+     * action, outside the shared folder.
+     *
+     * This is what separates a directory the user means arbor to name from a cwd a
+     * session merely inherited: the add-workspace action is the one path in DSH
+     * that registers a directory of the user's choosing, so it is the only one
+     * that may turn that directory into a pointer. The driver asks before it
+     * records one.
+     */
+    isAddedArborDirectory(path: string): boolean;
+    /**
+     * Record an existing directory as an external pointer for one session: no
+     * copy, no link, no adoption, never a registered project. The owner's decision
+     * for an existing DSH project with its own path — the session works in arbor's
+     * own directory (the shared folder) and the user's original directory is named
+     * in arbor's prompt as a pointer, so the model reaches it directly. The driver
+     * calls it for a session that became an arbor session while naming an added
+     * directory; the model calls it for one it was asked about.
+     */
+    pointerArborProject(path: string, sessionId: SessionId): ExternalPointer;
+    /**
+     * 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 stays live.
+     *
+     * The driver calls this for every arbor session it creates or re-routes, with
+     * the cwd it resolved for it: an arbor session works in arbor's own directory,
+     * and DSH filters a workspace's member list by the session's stored cwd, so
+     * the session has to be a member of the workspace whose path is that
+     * directory. See {@link DshProjectBridge.attachWorkspace} for why the composer
+     * is inert without it.
+     */
+    attachArborWorkspace(sessionId: SessionId, cwd: string): Promise<void>;
+    /** Drop a recorded external pointer by name for one session. */
+    removeArborPointer(name: string, sessionId: SessionId): void;
+    /**
+     * Every external pointer one session recorded whose directory still exists,
+     * true at read. This is what that session's `<workspace>` prompt section
+     * names, and only that session's.
+     */
+    listArborPointers(sessionId: SessionId): Promise<readonly ExternalPointer[]>;
+    /** Every project registered from the shared folder, as DSH lists them. */
+    listArborProjects(): Promise<readonly DshProject[]>;
+    /** The backend every window of this process runs through. */
+    get backend(): DshBackend;
+    /** Write the sends a step delivered, after all its tool results are on the log. */
+    flushSends(): void;
+    /** The directory the journal and the note store live in. */
+    get dataRoot(): string;
+    /**
+     * Every window that serves this session, oldest first.
+     *
+     * A window carries the session's target in its own `window_start`, and a
+     * continuation carries its predecessor instead; a chain therefore starts at a
+     * target-carrying window and every continuation leads back to one. A session
+     * can have several such roots — one per turn after an idle window ended — and
+     * each root's continuations belong to the same session. The journal's start
+     * order is what orders them all, and it is what the relay reads the chain's
+     * tool calls back out of on resume.
+     */
+    windowChainOf(sessionId: SessionId): Promise<WindowRef[]>;
+    /**
+     * The pre-label chain walk: the session's target names its first windows and
+     * each continuation names its predecessor. Only a journal with no labels
+     * reaches this; a current one answers by label.
+     */
+    private windowChainByTarget;
+    /**
+     * Rebuild which session every recorded window serves, from the journal.
+     *
+     * The two hooks attribute a window the moment it opens — `windowStart` from
+     * the task's targets, `windowContinue` from the window it continues — and that
+     * map is process memory: it died with the process that wrote it. The journal
+     * is the durable record of the same fact, because every `window_start` carries
+     * the session's target and a continuation names its predecessor in its body.
+     * So the attribution is rebuilt here, before the host starts, so that a window
+     * the recovery continues opens with a prefix that still names its session.
+     *
+     * A window no chain leads back to a target — one dispatched from outside a DSH
+     * session — is left unattributed, which is the answer the hooks give it too.
+     */
+    private rebuildWindowSessions;
+    /**
+     * The window this session's work is running in, when it has a live one.
+     *
+     * The journal is the record of which window belongs to which session: every
+     * `window_start` carries the label its task named, arbor carries that label
+     * onto the window's continuations, and a window a restart stopped is continued
+     * under a new ref with the same label. So the newest labeled start names the
+     * session's window, and it is the live one unless the chain has ended.
+     */
+    windowFor(sessionId: SessionId): Promise<WindowRef | undefined>;
+}
+export default ArborHostService;