Subtree handoff

Most provider paths are answered by provider dispatch: the host calls lookup-child, list-children, or read-file, and the provider returns directory entries, file bytes, or effects.

Some paths are better served by a real backing tree. Git repository contents are the main example. Once a provider resolves a repository, the host can clone or open it, bind the resulting tree into the mounted namespace, and let normal filesystem traversal continue from that backing path.

The model

A subtree handoff has three pieces:

1. The provider recognizes a path that should become a real tree.
2. The provider returns a tree-ref through the WIT result.
3. The host maps that tree-ref to a backing path and routes later filesystem operations there.

The provider does not mount host directories itself. It asks for host work, and the host owns the backing path.

Why it exists

Some resources are already filesystem-shaped. A Git repository has nested paths, files, executable bits, symlinks, and tool expectations that would be awkward to re-project file by file.

Subtree handoff lets omnifs preserve the useful path interface without forcing every byte through provider WIT calls.

GitHub repository trees

For GitHub, issue and pull-request metadata are projected provider paths. Repository contents use subtree handoff.

That split matters:

• issue fields can be cached as object/view data,
• repository files can behave like real checked-out files,
• grep, find, tar, and editors can operate on the backing tree,
• clone transport and SSH agent forwarding remain host/runtime responsibilities.

Runtime responsibility

The host owns clone management, backing paths, bind mounts, and later traversal. The provider owns the path decision and the tree-ref it returns.

This preserves the authority boundary. Providers do not receive ambient disk access, and they do not read host private keys. Git clone currently uses SSH with a forwarded agent socket rather than mounting host private key material into the container.

Cache relationship

Subtree handoff is not the object/view cache path. Object-shaped provider results can store canonical objects and rendered view leaves. A backing tree is different: it is a host-managed subtree that the filesystem can traverse directly.

If a resource should be rendered into small field files, use the object/view path. If a resource already is a tree of files, subtree handoff is often the better fit.