Drive9 for DeepSeek Harness

Persistent agent workspaces and durable, bounded tool evidence for
DeepSeek Harness.

@drive9/drive9-dsh is a standard DSH bundle with four independent Cordis components:

• a Drive9 revision-CAS filesystem for Harness read, write, and edit tools;
• an isolated evidence backend for oversized tool results;
• model-visible result_search and result_read tools with hard output limits;
• a model-visible runtime-context warning for the opt-in eventual mount profile.

The architecture keeps four lifecycles separate:

Layer	Owner
Agent loop	DeepSeek Harness
Session and conversation history	DeepSeek Harness
Persistent workspace and immutable evidence	Drive9
Shell, sandbox, language servers, and compute runtime	the user's DSH deployment

The Drive9 mount only exposes the persistent workspace inside an existing runtime.
It does not create, own, or keep that runtime alive. Evidence remains readable after
the runtime or workspace disappears because it is stored under a separate, unmounted
Drive9 root.

Drive9 does not provide a shell or sandbox. V1 exposes two explicit mount-consistency
profiles:

• strong (default and recommended) uses a Linux Drive9 FUSE mount in the same
  execution world as Harness process tools. Startup proves SDK-to-mount and
  mount-to-SDK coherence, and writes wait for exact mounted bytes before returning.
• eventual is an opt-in WebDAV profile. Model-facing reads, writes, revision CAS, and
  evidence still use the Drive9 SDK, but process tools may observe stale mounted bytes
  for more than 30 seconds after an SDK write.

The integration never silently downgrades strong to eventual. In real macOS
WebDAVFS validation, the Drive9 bridge observed an SDK write immediately while the
mounted open/stat view remained stale or blocked for more than 30 seconds.

Why

Agent work has two different kinds of state:

model filesystem tools ── Drive9 SDK + revision CAS ── persistent workspace
                                  │
process tools ── /mnt/drive9 ─────┘

large tool output ── isolated Drive9 evidence root ── exact result_id
                                                   ├─ result_search
                                                   └─ result_read

The workspace remains process-visible, while evidence stays outside the workspace
mount. A shell command, workspace deletion, or workspace rollback cannot address the
evidence namespace.

Prerequisites

• Linux with Node.js 22.19 or newer, npm, and pnpm on PATH;
• DeepSeek Harness 0.1.0-rc.6, including the standard dsh CLI;
• a current Drive9 CLI with drive9 token issue support and access to a Drive9
  server;
• /dev/fuse and fusermount3 for the recommended strong profile, or a WebDAV
  mount for the opt-in eventual profile;
• separate, path-scoped workspace and evidence credentials. An owner credential is
  needed only to create roots and issue those scoped credentials.

Install the Harness CLI and pnpm before continuing:

npm install --global @deepseek-ai/[email protected] pnpm

Install the Drive9 CLI from the
public Drive9 repository and verify both CLIs:

dsh --version
drive9 version

Quick start

Supply the owner credential through your normal secret injector, then configure the
non-secret paths once. The assertion fails before provisioning if the secret is
absent:

: "${DRIVE9_OWNER_API_KEY:?inject the Drive9 owner credential}"

export DRIVE9_BASE_URL="https://api.drive9.ai"
export DRIVE9_EVIDENCE_BASE_URL="$DRIVE9_BASE_URL"
export DRIVE9_MOUNT_ROOT="/mnt/drive9"
export DRIVE9_REMOTE_ROOT="/workspace"
export DRIVE9_EVIDENCE_ROOT="/evidence/dsh"
export DRIVE9_MOUNT_CONSISTENCY="strong"

1. Provision isolated roots and credentials

Create both roots once. Keep the evidence root unmounted so workspace tools and shell
commands cannot address it:

drive9 ctx add \
  --name dsh-owner \
  --server "$DRIVE9_BASE_URL" \
  --api-key "$DRIVE9_OWNER_API_KEY"
drive9 ctx use dsh-owner

drive9 fs mkdir :/workspace
drive9 fs mkdir :/evidence/dsh

drive9 token issue dsh-workspace \
  --ttl 24h \
  --allow /workspace:read,list,write,delete \
  --print

drive9 token issue dsh-evidence \
  --ttl 24h \
  --allow /evidence/dsh:read,write \
  --print

Each command prints only the bearer token and saves its local name for later rotation
or revocation. Store the printed value in your secret manager without leaving it on
disk, then inject the values as distinct credentials. The package rejects a shared
credential:

: "${DRIVE9_WORKSPACE_API_KEY:?inject the workspace-scoped credential}"
: "${DRIVE9_EVIDENCE_API_KEY:?inject the separate evidence-scoped credential}"

See credential and deployment guidance for production token
scope, TTL, and rotation guidance.

2. Mount the workspace

Mount the workspace into the Harness runtime. The default strong profile requires
Linux with /dev/fuse and fusermount3:

mkdir -p "$DRIVE9_MOUNT_ROOT"

DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
  drive9 mount --mode=fuse --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

The mount must exist in the same execution world as Harness subprocesses. If
Harness runs inside a container, mount Drive9 inside that container or bind the mount
into it before Harness starts.

--profile=none is part of the strong profile. A coding-agent mount profile can
route process paths through a local overlay while SDK calls still address Drive9,
splitting the two sides of the revision-CAS contract. Do not use a local-overlay
profile, and do not disable the startup proof to make one start.

To opt into relaxed WebDAV semantics instead, mount with WebDAV and explicitly select
eventual:

DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
  drive9 mount --mode=webdav --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

export DRIVE9_MOUNT_CONSISTENCY="eventual"

This profile returns from writes after the SDK CAS commits; it does not wait for the
mounted path to converge. Do not use it for workflows that write through Harness and
immediately validate with cat, rg, tests, a language server, or another subprocess.

3. Install the bundle

The recommended release channel is the prebuilt npm package:

dsh plugin --profile web add @drive9/drive9-dsh

To validate an unreleased checkout or install before registry publication, build the
same prebuilt tarball from the public repository instead of installing the TypeScript
sources directly from Git:

git clone https://github.com/drive9-ai/drive9-dsh.git
cd drive9-dsh
npm ci
PACKAGE_TARBALL="$(npm pack --silent)"
dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
cd ..

This source-build route runs the package's normal prepack build and gives DSH a
tarball containing dist/. A direct github:drive9-ai/drive9-dsh dependency does not
contain built output and is not a supported install path.

The package declares a DSH bundle, so the standard dsh plugin command installs it
and adds its cordis.patch.yml layer to the selected profile. The bundle disables the stock
fs-sandbox and spill-local storage providers, then installs the Drive9 filesystem,
evidence backend, and result tools. Harness's stock filesystem tools, subprocess
runtime, sandbox policy, observation policy, and spill policy remain in place. The
Drive9 filesystem implements the same per-call read-only, workspace-write, and
danger-full-access mutation policy that the replaced filesystem provider enforced.

4. Configure and run

cd "$DRIVE9_MOUNT_ROOT"
dsh web --dump-config
dsh web

dsh web --dump-config is the recommended preflight. Its composed tree must contain
exactly one active fs provider: @drive9/drive9-dsh/filesystem. Custom profiles
use the equivalent dsh --profile <name> --dump-config and dsh --profile <name>
commands; no Drive9-specific launcher is required.

To remove the bundle and its profile layer:

dsh plugin --profile web remove @drive9/drive9-dsh

In the default strong profile, startup fails instead of falling back or weakening the
contract when:

• the mount is missing or not writable;
• the remote root is missing or not a directory;
• SDK writes do not appear through the mount;
• mount writes do not produce a newer Drive9 revision through the SDK.

The eventual profile still validates the local mount directory and remote Drive9 root,
logs a prominent warning, adds the same warning to the model's durable runtime-context
snapshot, and skips the bidirectional proof by default. Explicitly setting
verifyCoherence: true still runs the complete proof and propagates any failure.

Components

@drive9/drive9-dsh/filesystem

Drive9FileSystem implements the complete Harness FileSystem contract.

Operation	Drive9 behavior
resolve	Canonical mount resolution with lexical and symlink escape rejection
processPath / fileUrl	Authenticated provider targets mapped below the real mount
stat	Drive9 metadata; revision becomes an opaque Harness version
readText / streamText	Strict UTF-8, NUL rejection, no silent binary coercion
readBytes	Metadata preflight plus bounded range read
listDir	Stable sorting and batchStat requests capped at 256 paths
guarded write/edit	Exact Drive9 revision CAS
unconditional write/edit	Bounded read/modify/CAS retry
mutation policy	DSH per-call sandbox policy, rechecked against the fresh canonical target

In strong, ordinary success returns only after the SDK write commits and the mounted
path exposes the same bytes. If Drive9 commits but the mount cannot be confirmed before
the bounded coherence deadline, the operation throws
DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED with workspaceCommitted: true, the
committed version, and reason timeout, aborted, or io. This is neither success nor
evidence that the write did not happen; callers must inspect/reconcile rather than
blindly retrying. In eventual, it returns after the SDK CAS succeeds; processPath() and
fileUrl() remain available, but their mounted view has no read-your-writes guarantee.
Both methods reject targets not authenticated by that filesystem instance.

@drive9/drive9-dsh/evidence

Drive9EvidenceStore implements Harness SpillStore:

1. generate a random 256-bit capability;
2. create the content object;
3. create the canonical manifest with byte count and SHA-256;
4. publish result_id and a provenance receipt only after both writes succeed.

Reads verify stable revisions, exact byte count, manifest shape, SHA-256, and strict
UTF-8. A failed manifest write returns no locator. The unreachable content orphan can
be reclaimed by operator retention without exposing partial evidence to the model.

@drive9/drive9-dsh/result-tools

The bundle registers:

result_search(result_id, query, max_matches?, context_lines?)
result_read(result_id, offset?, limit?)

Both tools require an exact locator already issued into the current session's durable
tool history, or inherited from its explicitly seeded direct parent. Guessing,
enumeration, plain-text echoes, unseeded parent references, and sibling references are
denied.

Hard package limits:

• 1,000 returned lines;
• 64 KiB returned UTF-8 text;
• 100 search matches;
• 64 MiB scanned per request;
• 64 KiB search query.

Configuration

The shipped bundle reads these environment variables:

Variable	Required	Default	Purpose
DRIVE9_BASE_URL	no	Drive9 SDK default	Drive9 API base for workspace SDK calls
DRIVE9_WORKSPACE_API_KEY	yes	—	Workspace-scoped SDK credential
DRIVE9_MOUNT_ROOT	no	/mnt/drive9	Process-visible Drive9 mount
DRIVE9_REMOTE_ROOT	no	/	Remote subtree represented by the mount
DRIVE9_MOUNT_CONSISTENCY	no	strong	strong Linux FUSE or explicit eventual WebDAV semantics
DRIVE9_EVIDENCE_BASE_URL	no	DRIVE9_BASE_URL	Drive9 API base for evidence
DRIVE9_EVIDENCE_API_KEY	yes	—	Separate evidence-scoped credential
DRIVE9_EVIDENCE_ROOT	no	/evidence/dsh	Unmounted evidence root

Programmatic composition is also supported inside a DSH context that already provides
the standard sandboxPolicy, systemPrompt, and tools services:

import { Context } from '@deepseek-ai/cordis'
import * as Drive9Dsh from '@drive9/drive9-dsh'

const ctx = new Context()

await ctx.plugin(Drive9Dsh, {
  filesystem: {
    mountRoot: '/mnt/drive9',
    remoteRoot: '/workspace',
    baseUrl: process.env.DRIVE9_BASE_URL,
    apiKey: process.env.DRIVE9_WORKSPACE_API_KEY,
    mountConsistency: 'strong',
  },
  evidence: {
    root: '/evidence/dsh',
    baseUrl: process.env.DRIVE9_BASE_URL,
    apiKey: process.env.DRIVE9_EVIDENCE_API_KEY!,
  },
  resultTools: {
    maxScanBytes: 16 * 1024 * 1024,
  },
})

The preset rejects missing credentials and rejects using the same credential for
workspace and evidence.

Errors

Filesystem failures use Harness FS_* codes, including FS_STALE_VERSION,
FS_NOT_OBSERVED, FS_PERMISSION_DENIED, FS_TOO_LARGE, FS_NOT_TEXT,
FS_ABORTED, and FS_IO_ERROR.

DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED is the distinct post-commit outcome for
a strong-profile mount verification failure. It carries workspaceCommitted: true and
must never be treated as a retry-safe “write did not happen” error.

Evidence retrieval uses stable DRIVE9_RESULT_* codes:

• DRIVE9_RESULT_INVALID_ID
• DRIVE9_RESULT_NOT_FOUND
• DRIVE9_RESULT_CORRUPT
• DRIVE9_RESULT_UNAUTHORIZED
• DRIVE9_RESULT_SCAN_LIMIT
• DRIVE9_RESULT_ABORTED
• DRIVE9_RESULT_IO

Errors never include credentials or authorization headers.

Security model

• Workspace and evidence credentials must be distinct and path-scoped.
• Evidence has no path, listing, mount, or filesystem-target API.
• Locators are random capabilities but are not authorized by possession alone.
• A versioned issuance receipt, immutable manifest, and enclosing Harness tool event
  must agree on session, tool name, call id, locator, and manifest digest.
• Current-session and explicitly seeded direct-parent evidence are readable; sibling
  and unseeded artifacts are not.
• V1 is append-only from the integration's perspective. Configure Drive9 retention or
  administrative GC for the evidence root.

See SECURITY.md and the complete V1 design lock.

Limits

V1 intentionally does not provide:

• a shell, process sandbox, terminal, or language server;
• automatic Drive9 mounting;
• strong subprocess read-your-writes through WebDAV;
• local-overlay support for either consistency profile;
• LayerFS checkpoints or workspace rollback;
• source-streaming or crash-recoverable tool capture;
• exactly-once external tool side effects;
• evidence enumeration.

The stock Harness spill policy receives a fully materialized tool result. Storage is
durable-before-reference, but tool output is not streamed to Drive9 at source in V1.

Development

npm ci
npm run check
npm test
npm run test:race
npm run build
npm pack --dry-run

The default suite includes a scripted real Harness agent loop: the model uses the
stock filesystem tool, /bin/cat reads the same mounted bytes, an oversized result is
spilled, and later model steps invoke result_search and result_read.

For a real Drive9 service and Linux FUSE mount created with
drive9 mount --mode=fuse --profile=none:

DRIVE9_REAL_E2E=1 npm run test:real

Required environment and cleanup behavior are documented in
docs/operations.md. See CONTRIBUTING.md for
the release checklist. The real test rejects non-Linux and non-FUSE mount roots.

Compatibility

Component or profile	Supported contract
Node.js	22.19 or newer
DeepSeek Harness	0.1.0-rc.6
Drive9 JavaScript SDK	0.1.4
strong	Linux Drive9 FUSE; writes wait for exact process-visible bytes. Current real-service validation observed SDK-to-mount convergence in 1.3–1.5 seconds and mount-close-to-new-SDK-revision convergence in 0.36–0.40 seconds. These observations are not an SLA.
eventual	WebDAV; no subprocess read-your-writes guarantee, with observed staleness beyond 30 seconds.

DeepSeek Harness is a developer preview. Upstream service-contract changes require a
new package release and contract review.