Question: a Git-centred repo on LayerFS — how should main track origin/main, and how should Branches reach Git?

Start with api/docs/agent.md, api/docs/branch.md#branchpublish, api/docs/workspace.md and issue #446, which the reporter says they already read. The issue asks maintainers to decide and document Git refresh, delivery, project cleanup and dependency handling workflows; it does not identify a bounded change or acceptance criteria, so wait for a maintainer direction before proposing work.

Summary

We use LayerFS as the working environment for a GitLab monorepo: 61,535 files, 2.2 GB, and origin/main moves about 180 commits a day. Agents fork Branches, run checks in Sandboxes and commit there; review and delivery stay in GitLab.

LayerFS and Git are two lineages, and keeping them in step by hand is most of our overhead. We would like to know which shape you intend, so we can stop inventing one:

1. re-import — a project's main is a snapshot, and following upstream means a new project;
2. in-Workspace git — agents run git fetch/merge/push inside their Workspaces, and LayerFS Branches are the scratch space;
3. first-class sync — LayerFS gains an upstream ref and a delivery call (the "Publish to Git" item in #446 · Later).

We read api/docs/agent.md, branch.md#branchpublish, workspace.md and #446, so we are not asking why main is read-only, what publish does to other Layers, or why workspace.mount("main") is refused. #487, #417, #511, #502, #462, #466 and #508 match things we hit; we are not re-filing them. This is one question about the workflow, plus three small frictions at the end.

Environment

LayerFS	0.1.0, built from 5fb68ddc1 (2026-10-21), 10 files patched locally
Host	DeepSeek Harness Desktop on macOS 15.6.1 arm64, dsh-layerfs 0.1.0
Engine	Docker Engine in colima; the Store runs in the container layerfs-store
Project	runa-20261026, imported from a curated snapshot of the repository
Repository	61,535 files, 2,221,283,299 bytes; origin/main tip 36ecd59 (2026-10-30)
Our usage	151,873 SDK calls, 1,310 of them writes, 2026-10-22 … 2026-10-30 (from our trace files)

What makes this acute

The baseline rots in days. The snapshot's base is 3d057b0f (2026-10-25 15:31); today origin/main is 36ecd59 (2026-10-30 11:08), 915 commits ahead. A main that was exact when imported is a stale fork of the repository within a week.

The drift is large, not cosmetic. Comparing the project's main with origin/main over the 2,576 tracked files on 2026-10-30: 153 paths absent from LayerFS and 529 with different content — 26% of the tree. We now run a script before every fork that classifies each path (add / overwrite / keep-only-here) and applies it with fs.write. It is a local workaround and the part of our setup we trust least.

Every refresh costs a project. Init is ~5 minutes for this tree, and it creates a new project rather than moving the old one: we already have runa and runa-20261026, their Store files are 766 MB and 1.0 GB, and the current project carries 91 Branches (#511/#411 will eventually let us prune).

What we do today

branch.fork("<task>")                   # from a main we have just re-synced by hand
workspace.mount → exec → commit         # agents work and run pnpm checks in the Workspace
branch.diff_branches("main", "<task>")  # export the change as a patch
# on the Mac, outside LayerFS: git apply → branch → MR → merge into origin/main

Two things force the last step outside LayerFS. The .git inside the project is the snapshot's own working copy, not the repository's current state — its HEAD points at refs/heads/feat/vnc-ttl-renew, and its refs/heads/main is b9ea2a3 (2026-10-26, one commit that never reached GitLab) — so git diff in a Workspace mixes in that original WIP. And the GitLab credentials live on the Mac only; we do not want them in a Sandbox image or a Workspace.

Three small frictions (our counts from the trace files, not bug reports)

• workspace.mount("main") answers NoSuchBranch: Branch main does not exist — 19 times between 2026-10-28 and 2026-10-30. main does exist; it just cannot be mounted. branch.fork("main") refuses with ReservedName, so a refusal that says "fork a Branch from main" would have saved all 19.
• Branch names cannot contain / (names are 1–63 bytes of lowercase letters, digits, ., _, -), while every Git branch we have is feat/… or fix/…: branch.fork("feat/feishu-bot-per-sandbox") → InvalidInput: \feat/feishu-bot-per-sandbox` is not a valid name`. We now keep a name mapping for delivery. Is that the intended shape, or is a Git-shaped name meant to be allowed?
• workspace.unmount refused Dirty: 0 uncommitted change(s) 12 times and Busy: kernel reported the mount busy 7 times, both since 2026-10-28 — that is #462 and #460, noted here only so you know the frequency is not theoretical.

Questions

1 · Which refresh path do you want us to use? Is "re-import a fresh snapshot into a new project" the intended way to follow origin/main? If a project is meant to outlive one upstream commit, what is the sanctioned way to move its main to a Git commit — file-level fs.write/fs.apply from outside, as we do; git inside a Workspace, then a Commit and a publish of that Branch; or something not released yet? At ~180 commits a day, is any of these meant to run per task, per day, or not at all?

2 · How should a Branch reach GitLab until "Publish to Git" exists? #446 puts «document git commit and git push inside a Workspace, layerfs publish to squash a task into one Git commit, a "Publish to Git" action, and Git worktrees measured against LayerFS Branches» under Later. What should we do in the meantime, given host-only credentials: in-Workspace git with a credential helper, a patch export, or something else? #483 (streaming export of a Branch's tree at a Commit) reads like the building block for the last option — is that the intent, and would a Host-side "apply this Branch onto a real checkout" belong in dsh-layerfs rather than here?

3 · Is there a re-baselining procedure that does not accumulate projects? Can one project's main be replaced wholesale — delete and Init under the same name, keeping the volume — or is a new project the only supported shape? If the latter, is #511's explicit-SDK-call deletion the intended cleanup, and in what order should a team retire an old project so that no volume and no Branch is left behind?

4 · Package managers rewrite node_modules inside the Workspace — is /.lww the whole answer? Our snapshot carries Linux node_modules (pnpm's .pnpm/ layout with relative symlinks), because macOS's native packages cannot run in the Sandbox. pnpm 12 rewrites node_modules/.bin and the links on pnpm run (verifyDepsBeforeRun); the next workspace.commit records that, and the Branch is left with a broken dependency tree (node_modules/typescript and friends gone) — we fork a new Branch instead of repairing it. We now set verifyDepsBeforeRun: false in the snapshot's pnpm-workspace.yaml (local config, never exported) and added a /.lww with %include .gitignore. Should dependencies be in the snapshot at all, and does /.lww cover a rewrite of the same paths, or is this meant to be handled elsewhere? We can send a minimal repro (pnpm --version, readlink before and after a Commit) if that helps.

5 · Should we re-base before asking any of this? Two local patches (the Sandbox port HostIp and the endpoint check) look like your 0.0.0.0 listen on main, and one fixes a Session-record error on packaged DSH Desktop (#429). We plan to rebuild against current main and current dsh-layerfs. If the answers to 1–4 differ on that version, say so and we will re-measure first.

What an answer that helps looks like

One paragraph on the loop you expect a Git-centred team to run — where the repository's truth is, what gets re-imported and how often, and how a Branch becomes an MR — plus a pointer to whatever already says it. If any of the four is a "we would take a PR", we would rather write it in the shape you want than send one you have to redo. If this belongs in dsh-layerfs instead, tell us and we will move it rather than split it.