# ADR 0009: trusted agents receive private ordinary workspaces

Status: proposed

Date: 2026-08-10

Refines ADR 0008's `Environment` and `AgentSession` filesystem contract.

## Context

PDB needs multiple trusted coding agents to start from one exact program state
without observing or overwriting one another's dirty files. Editors, language
servers, package managers, test watchers, development servers, and local
databases must continue to see an ordinary repository filesystem.

Git is an optional interchange and recovery projection, not PDB's canonical
database. Git worktrees therefore remain a compatibility reference rather than
the required Session lifecycle. Docker, privileged mounts, a cloud service, and
hostile-code containment are also not initial prerequisites.

The complete research and backend bake-off are retained in
[AgentSession isolation research](agent-environment-isolation.md).

## Decision

PDB separates an immutable program state from a private writable attempt:

- an `Environment` is a logical lineage with an immutable head;
- an `AgentSession` is one private ordinary directory pinned to one exact
  Environment Snapshot;
- a checkpoint extracts immutable PDB objects plus a base-bound exact
  changeset; and
- Environment-head publication remains a later deterministic expected-head
  transaction.

The initial threat model is **trusted, cooperative coding agents**. The product
guarantee is workspace isolation: PDB-managed Sessions do not share dirty
writes. The service reports `security_isolation=false`; it does not claim to
contain hostile same-user processes, credentials, or network access. Security
isolation may be composed later, but it does not make containers or VMs
mandatory for ordinary local use.

## Workspace-service contract

The host-local `pdb-environment` service owns four lifecycle mutations:

1. `prepare` materializes a stable immutable base into a unique writable root;
2. `acquire_checkpoint` and lease release cooperatively quiesce PDB-managed
   writers;
3. `checkpoint` scans the visible tree, installs immutable objects, and returns
   the exact Snapshot and changeset identities; and
4. `discard` removes only the named bounded Session root and is idempotent.

Capability inspection and workspace-root lookup are read-only operations. A
missing capability fails closed; no backend may silently claim semantics it did
not provide.

The v1 canonical source contract includes UTF-8 relative path, entry kind,
regular-file bytes, symlink target bytes, and the regular-file executable bit.
Directories, regular files, and symlinks are supported. ACLs, xattrs, sparse
extent identity, hard-link identity, and arbitrary special files are not v1
canonical source.

Checkpoint authority comes from a complete scan of the leased visible root,
not Git status or backend-private change history. The Snapshot object binds the
base Snapshot to every resulting entry and leaf object. The changeset object
binds the base Snapshot, result Snapshot, and exact path changes. Installing
immutable objects alone does not publish a checkpoint or advance an
Environment.

## Backend selection

`full-copy` is the enabled correctness-first default and behavioral oracle. It
uses explicit userspace byte copying so APFS cannot transparently turn the
oracle into a clone benchmark.

`apfs-clone` remains an explicit experimental capability. The research harness
proved its core semantics on two independent arm64 APFS hosts and observed
large space savings, but the product service reports it unavailable until PDB
can force and observe clone success without silent fallback and repeated
performance gates justify selection.

AgentFS v0.6.4 is rejected on the tested macOS profile after its first command
timed out twice with no mutation. A future release may re-enter only through a
checksum-pinned bounded external adapter; PDB will not embed its SDK or adopt
its SQLite/NFS state as canonical.

## Host and agent boundary

`pdb-host` owns `.pdb-host/workspaces`, verifies that the logical
`AgentSession` already exists and is active, and opens `pdb-environment` against
the canonical immutable object store. It passes only the prepared ordinary
root to `pdb-agent`'s ACP implementation request.

The adapter may prepare, run, checkpoint, and discard. It does not create a
second Session identity, advance an Environment, publish a checkpoint record,
share mutable dependencies, or grant the agent ledger/object-store authority.

## Evidence

The checked-in
[core receipt](../evidence/workspace-service-core.json)
records the two-agent privacy proof, pinned base, cooperative lease, exact
checkpoint objects, host-to-fake-ACP handoff, and idempotent cleanup.

The production full-copy service then completed 30 fresh sequential npm cases
and 30 fresh sequential pnpm cases on arm64 macOS 26.6.1. Every case passed
private installation, TypeScript, `tsserver`, Vite, Next.js, Jest and Vitest
initial/update watcher events, base-integrity verification, and cleanup. The
[npm](../evidence/workspace-service-node-npm-30.json)
and
[pnpm](../evidence/workspace-service-node-pnpm-30.json)
receipts retain every case without absolute paths or raw dependency trees.

The research-only `pdb env` switcher then created two ordinary full-copy
directories from one base digest and ran real Codex CLI 0.142.5 and Claude Code
2.1.201 processes through the command boundary. Both agents independently
edited the same base path, created, deleted, renamed, symlinked, changed an
executable bit, and created nested files. Neither saw the other agent's output,
and the source base remained unchanged. The compact
[real-agent receipt](../evidence/pdb-env-real-agents.json)
records the invocations, initial tool-runtime failures, and verified result.

Two npm attempts before the isolated blocks timed out waiting for Jest's first
watch event. A diagnostic run and all 30 sequential npm cases passed. This is
retained as an unreproduced resource/concurrency-sensitive harness flake, not
discarded evidence and not a demonstrated filesystem mismatch.

## Consequences

- Two trusted coding agents can edit the same paths from one base without
  colliding or requiring Git worktrees.
- Ordinary native filesystem semantics remain the compatibility target.
- Full copy costs time and disk but gives PDB a portable shipping baseline.
- APFS acceleration, dependency-store sharing, Environment-head publication,
  canonical publication commands, and hostile-code containment remain separate
  work. The experimental `pdb env` command is only a workspace switcher.
- Cooperative quiescence can reject a busy PDB-managed writer; it cannot freeze
  an arbitrary editor or same-user process.
- Raw experiment trees stay ignored. Small versioned receipts carry the
  evidence needed to review this decision.

## Promotion criteria

Accept this ADR after review confirms the v1 path/metadata contract, host-local
storage layout, cooperative lease semantics, and full-copy default. Acceptance
does not select APFS automatically. That separate decision still requires
randomized performance blocks, OS/hardware diversity, real repository
fixtures, forced-clone observability, and approved fallback behavior.