@4fu/dsh-arbor-driver 0.0.0-stage → 2026.1110.0

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,235 @@
-# 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.0`; 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.0
+dsh web
+```
+
+`dsh plugin` adds the bundle to the profile's `dsh.profile.bundles` and installs
+its packages into the profile. Pick **Arbor** in a composer and send a message.
+The optional [font plugin](https://github.com/4fuu/dsh-arbor-fonts) installs the
+same way:
+
+```bash
+dsh plugin --profile web add @4fu/dsh-arbor-fonts@2026.1110.0
+```
+
+### 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.0 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`.
+
+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.
+
+## 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 DSH pin check, the release build and the publish dry run
+```
+
+## 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/assistant-stream.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Process-local assistant attempt framing for arbor sessions.
+ *
+ * A compact mirror of `packages/core/agent-loop/src/assistant-stream.ts`
+ * (AssistantStreamAttempt): the same dsh-llm primitives
+ * (`AssistantStreamAccumulator`, `BlockAssembler`), the same frame order
+ * (start, chunk*, end), and the same settlement contract — the durable
+ * `assistant/message` or `assistant/attempt` append commits BEFORE the
+ * terminal frame is emitted.
+ */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import { LlmAttemptId, type AssistantStreamRecord, type ContentBlock, type FinishReason, type ReplayEnvelope, type StreamChunk, type TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session';
+/** Folds one model attempt into one compact stream plus ordered transient frames. */
+export declare class ArborStreamAttempt {
+    private readonly accumulator;
+    private readonly assembler;
+    private index;
+    private terminal;
+    readonly attemptId: LlmAttemptId;
+    private readonly nextRevision;
+    readonly turn: number;
+    readonly step: number;
+    private readonly emit;
+    constructor(sessionId: SessionId, attempt: number, nextRevision: () => number, turn: number, step: number, emit: (frame: AssistantStreamFrame) => void);
+    get ended(): boolean;
+    /** Publish the opening marker before the first delivered chunk. */
+    start(): void;
+    /** Snapshot one chunk once, then feed durable compaction, assembly, and live publication. */
+    push(chunk: StreamChunk): void;
+    /** Publish terminal settlement after the matching durable event commits. */
+    settle(eventType: 'assistant/message' | 'assistant/attempt', append: () => SessionSeq): void;
+    /** Publish abandonment when no durable attempt event can be committed. */
+    abandon(): void;
+    /** Exact compact stream for the final durable event. */
+    get stream(): AssistantStreamRecord[];
+    /** Canonical completed-message blocks from the same chunks. */
+    blocks(): ContentBlock[];
+    /** Safe visible prefix when cancellation interrupts the attempt. */
+    interruptedBlocks(): ContentBlock[];
+    /** Latest adapter-reported usage in the stream. */
+    get usage(): TokenUsage | undefined;
+    /** Terminal reason, defaulting to stop when the stream omitted one. */
+    get finish(): FinishReason;
+    /** Replay state carried by the terminal finish record. */
+    get replayState(): ReplayEnvelope | undefined;
+}

package/assistant-stream.js

@@ -0,0 +1,98 @@
+/**
+ * Process-local assistant attempt framing for arbor sessions.
+ *
+ * A compact mirror of `packages/core/agent-loop/src/assistant-stream.ts`
+ * (AssistantStreamAttempt): the same dsh-llm primitives
+ * (`AssistantStreamAccumulator`, `BlockAssembler`), the same frame order
+ * (start, chunk*, end), and the same settlement contract — the durable
+ * `assistant/message` or `assistant/attempt` append commits BEFORE the
+ * terminal frame is emitted.
+ */
+import { AssistantStreamAccumulator, BlockAssembler, LlmAttemptId, } from '@deepseek-ai/dsh-llm';
+/** Folds one model attempt into one compact stream plus ordered transient frames. */
+export class ArborStreamAttempt {
+    accumulator = new AssistantStreamAccumulator();
+    assembler = new BlockAssembler();
+    index = 0;
+    terminal = false;
+    attemptId;
+    nextRevision;
+    turn;
+    step;
+    emit;
+    constructor(sessionId, attempt, nextRevision, turn, step, emit) {
+        this.nextRevision = nextRevision;
+        this.turn = turn;
+        this.step = step;
+        this.emit = emit;
+        this.attemptId = LlmAttemptId(`${sessionId}:${attempt}`);
+    }
+    get ended() {
+        return this.terminal;
+    }
+    /** Publish the opening marker before the first delivered chunk. */
+    start() {
+        this.emit({ type: 'start', attemptId: this.attemptId, revision: this.nextRevision(), turn: this.turn, step: this.step });
+    }
+    /** Snapshot one chunk once, then feed durable compaction, assembly, and live publication. */
+    push(chunk) {
+        const timed = this.accumulator.push({ time: Date.now(), chunk });
+        this.assembler.push(timed.chunk);
+        this.emit({
+            type: 'chunk',
+            attemptId: this.attemptId,
+            revision: this.nextRevision(),
+            index: this.index++,
+            time: timed.time,
+            chunk: timed.chunk,
+        });
+    }
+    /** Publish terminal settlement after the matching durable event commits. */
+    settle(eventType, append) {
+        let seq;
+        try {
+            seq = append();
+        }
+        catch (error) {
+            this.abandon();
+            throw error;
+        }
+        this.terminal = true;
+        this.emit({
+            type: 'end',
+            attemptId: this.attemptId,
+            revision: this.nextRevision(),
+            index: this.index,
+            outcome: { kind: 'committed', eventType, seq },
+        });
+    }
+    /** Publish abandonment when no durable attempt event can be committed. */
+    abandon() {
+        this.terminal = true;
+        this.emit({ type: 'end', attemptId: this.attemptId, revision: this.nextRevision(), index: this.index, outcome: { kind: 'abandoned' } });
+    }
+    /** Exact compact stream for the final durable event. */
+    get stream() {
+        return [...this.accumulator.snapshot()];
+    }
+    /** Canonical completed-message blocks from the same chunks. */
+    blocks() {
+        return this.assembler.blocks();
+    }
+    /** Safe visible prefix when cancellation interrupts the attempt. */
+    interruptedBlocks() {
+        return this.assembler.interruptedBlocks();
+    }
+    /** Latest adapter-reported usage in the stream. */
+    get usage() {
+        return this.assembler.usage;
+    }
+    /** Terminal reason, defaulting to stop when the stream omitted one. */
+    get finish() {
+        return this.assembler.finish;
+    }
+    /** Replay state carried by the terminal finish record. */
+    get replayState() {
+        return this.assembler.replayState;
+    }
+}

package/driver.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The arbor driver: the AgentFactory that runs arbor-preset sessions, and the
+ * Cordis plugin row that mounts it.
+ *
+ * One DSH user session is one conversation target of the process's single Arbor
+ * host (`@4fu/dsh-arbor-host`): the journal, the note store and the board are
+ * shared by every session, and each session is one source of that one host.
+ * Arbor's own model is what a session's windows follow — a window ends when its
+ * run ends and the session's next turn opens the next window of its chain, so
+ * several windows serve one session and none of them is the session. Per
+ * session the driver owns
+ *
+ *  - the window, opened through `host.dispatch` on the session's first turn and
+ *    taken back — not reopened — when the session already has a live one, which
+ *    is what a restart's continuation is;
+ *  - the bridge the session agent drives: `ensureWindow`, `modelCall`,
+ *    `runToolCall` (arbor's tool path into `ctx.tools.execute`), `publish`,
+ *    `finishRun`, `close`; and
+ *  - the window's DSH agent registration, which keeps it out of the session
+ *    list (`meta.origin: 'subagent'`, owned by the session's agent).
+ *
+ * `resume` loads the persisted session, replays onto its log what the arbor
+ * journal recorded and the log lost, and binds the session back to the window
+ * the journal says is its own — the window the host continued at boot.
+ *
+ * The creation lifecycle mirrors `AgentLoop.createAgent`
+ * (packages/core/agent-loop/src/index.ts): prepare the session, take
+ * persistence ownership when a backend is mounted, run setup while the agent
+ * is unpublished, then enter and announce the session and the agent through
+ * the same registries the official loop uses.
+ *
+ * B1 scope, per the plan: compaction, goals, agentTeams, retry and fork are
+ * off for arbor sessions.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent, AgentFactory, AgentHandle, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type ArborHostService } from '@4fu/dsh-arbor-host';
+import type { WindowRef } from '@4fu/arbor-interfaces';
+/** Plugin config: the arbor settings live in the host row, so there is nothing here. */
+export type Config = Record<string, never>;
+/** What the driver exposes about one session's arbor world. */
+export interface SessionArborLike {
+    /** The window this session's work runs in, once it has one. */
+    readonly windowRef: WindowRef | undefined;
+    /** The agent registered for this session's window, once one exists. */
+    readonly windowAgentOf: Agent | undefined;
+}
+/** The arbor agent factory and Cordis plugin. */
+export declare class ArborDriver extends Service implements AgentFactory {
+    static inject: string[];
+    static Config: z<Config, Config>;
+    readonly config: Config;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    private readonly runtime;
+    private readonly sessions;
+    /**
+     * Sessions the embedded AgentLoop is running, with the handle its creation
+     * returned. The driver created every one of them — the registry routes every
+     * session through this factory — so it holds the only thing that can end one:
+     * that is what lets a preset selection re-route a session that has not started
+     * a turn. An ordinary session is never touched unless its user picks arbor.
+     */
+    private readonly embedded;
+    private modelProjectionHandle;
+    private inboxProjectionHandle;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Re-route one session from the embedded AgentLoop to arbor.
+     *
+     * The loop's agent is ended with the handle its creation returned — which
+     * unregisters the agent and detaches the session from the store, leaving the
+     * durable log exactly as it stands — and the session is then opened again
+     * under arbor, the way a restart opens it. The session keeps its identity, its
+     * log and every event it already committed, so the composer that is bound to
+     * it keeps working; what changes is which driver its next turn runs.
+     */
+    private rerouteToArbor;
+    /**
+     * Record a directory an arbor session named as an external pointer for that
+     * session, when the user had added the directory through DSH's own
+     * add-workspace action.
+     *
+     * The host answers whether the directory was added, because that is a fact
+     * about the project list rather than about this session; a directory that was
+     * never added — a cwd the session inherited — is left alone, which is the
+     * mistake the earlier resolve-time recording made.
+     */
+    private noteExternalProject;
+    /**
+     * Re-route one session from arbor back to the embedded AgentLoop.
+     *
+     * The mirror of {@link rerouteToArbor}, and it exists for one case only: a
+     * session that SELECTED arbor while it was blank can select something else
+     * again while it is still blank, and the label and the driver under it must
+     * say the same thing. That is the SDK or remote `agent-preset/select` path —
+     * every surface that knows what the user clicked creates the session under
+     * the picked preset instead (the hero mint, the adopt at create), so nothing
+     * in the web profile switches a blank in place. The arbor agent is ended with
+     * the handle this driver holds, the window keeps running out arbor's own idle
+     * policy, and the session is opened again on the embedded loop with the same
+     * id, the same log and the same cwd it was created with.
+     *
+     * **A session created under arbor is never moved off it here.** Its creation
+     * header says `agentPreset: 'arbor'`, which is a frozen creation fact
+     * (`@deepseek-ai/dsh-agent-preset-registry`, `lib/types/session.js`), and the
+     * one selection that can still arrive on it is DSH's own: the session
+     * controller re-selects the resolved deployment default whenever a blank is
+     * reused with no preset named — `reuseLive` calls `presets.select` with
+     * `composition.agentPreset` and `reuseSetup` appends the event itself
+     * (`@deepseek-ai/dsh-api-session-controller`, `lib/index.js`). The log cannot
+     * tell that re-select from a user's pick, because `presets.select` is the
+     * single writer of `agent-preset/selected` (`lib/index.js`), so the
+     * attribution has to come from the header instead: a session created as arbor
+     * keeps arbor, and its label is put back through the registry's own select so
+     * the projection and the driver agree ({@link reassertArbor}). The client side
+     * of the same guarantee is that the restore names the recorded preset, so the
+     * re-select is never written in the first place — this gate is what stands
+     * behind it.
+     *
+     * A session that has started a turn keeps the driver it began with: DSH refuses
+     * that selection before it is committed, so this is the same defensive guard the
+     * arbor direction carries, and the alternative — silently keeping the old driver
+     * — is the one outcome the owner ruled out.
+     */
+    private rerouteToEmbedded;
+    /**
+     * Put a session's label back on arbor, through the registry's own select.
+     *
+     * The selection being refused has already been appended to the log, so the
+     * session's `agentPreset` projection now names another preset while this
+     * driver still runs arbor — a label that says one thing while the driver does
+     * another, which is the untruth the gate exists to prevent. `presets.select`
+     * is the single writer of that event (`@deepseek-ai/dsh-agent-preset-registry`,
+     * `lib/index.js`), and it appends only when the projection does not already
+     * name the preset, so this writes one honest event and nothing else: the
+     * registry's `bind` is a no-op when the agent's context already holds the
+     * preset's generation. The event reaches this driver's own observer, which
+     * finds the session already running arbor and does nothing.
+     */
+    private reassertArbor;
+    /** The driver's own DSH context, for the per-session arbor worlds. */
+    get driverContext(): Context;
+    /** The one Arbor host of this process. */
+    get hostService(): ArborHostService;
+    /** The per-session arbor world, for tests and diagnostics. */
+    sessionArbor(sessionId: SessionId): SessionArborLike | undefined;
+    /** The agent registered for a session's arbor window, once one exists. */
+    windowAgentOf(sessionId: SessionId): Agent | undefined;
+    /** The system prompt the session's arbor window rendered, once it opened. */
+    systemPromptOf(sessionId: SessionId): string | undefined;
+    /**
+     * Whether a persisted session runs under arbor.
+     *
+     * The creation header names the preset a session STARTED with and is frozen
+     * because it is a creation fact; a session may still select another while it
+     * is blank, and DSH's own reconstruction rule for exactly this reason reads
+     * the `agentPreset` projection, "never the header alone"
+     * (`@deepseek-ai/dsh-agent-preset-registry`, `lib/types/session.js`). So the
+     * log's `agent-preset/selected` events are folded over the header's value:
+     * that is what makes a re-routed session come back as arbor after a restart
+     * instead of silently resuming on the embedded loop.
+     */
+    ownsSession(sessionId: SessionId): Promise<boolean>;
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /** Create the agent of a session that runs arbor. */
+    private createArborAgent;
+    /**
+     * Create an agent for a session the embedded AgentLoop will run.
+     *
+     * The embedded factory is delegated to exactly the way the base
+     * `AgentRegistry` delegates, so an ordinary session's agent, its ownership and
+     * its teardown are the official loop's own. The one difference is that this
+     * driver keeps the handle: a session whose user later picks arbor is re-routed
+     * by ending the loop's agent and opening the session's arbor window, and
+     * ending an agent needs the handle its creation returned.
+     */
+    private createEmbedded;
+    /** Resume an agent for a session the embedded AgentLoop will run. */
+    private resumeEmbedded;
+    /**
+     * Resume a persisted arbor session.
+     *
+     * The session's log is loaded the way the official loop loads it, with two
+     * arbor-specific steps around it: the window chain the journal holds is read
+     * back and the `tool/call` events the log lost are replayed onto it, so DSH's
+     * own `interruptedTurnClosers` closes them as outcome-unknown rather than
+     * not-started; and the session is bound to the window the host continued at
+     * boot, so its next turn drives that window instead of opening a new chain.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /**
+     * The cwd a persisted session was created with, read without taking its write
+     * ownership: the resume path needs it to resolve the session's cwd before it
+     * opens the log for writing.
+     */
+    private storedCwd;
+    /** Resume a persisted session that runs arbor. */
+    private resumeArbor;
+    /** Build the session agent for one prepared session, create or resume. */
+    private agentFor;
+    /** Take a fresh session's write ownership when persistence is mounted. */
+    private createStoredSession;
+    /** Durably store the session events appended since the last stored cursor. */
+    private appendUnstoredSuffix;
+    /** Enter and announce the session and the agent, exactly like AgentLoop does. */
+    private publish;
+}
+export default ArborDriver;