Local folder merge

When you connect a local folder to a server Project, devctrl brings that folder's local-only work to the server and merges it with what is already there. You connect a folder with ./devctl project add|sync|add-all|sync-all and a folder source.

The local work is:

You see what would be merged and confirm it. Alternatively, a Project setting applies merges automatically.

Nothing local is written, and nothing on the server is overwritten.

The merge runs only where the devctrl local agent (client-agent) runs, and only for the folders you connected.

How it works

  1. The connection. Connecting a folder records it in .devctl/project-interchanges.json. The client-agent sees the folder through its existing read-only mount /project-policy/<host>/<project>. It also sees only that folder's Claude Code transcript directory, mounted read-only at /project-native/<host>/<project>/claude. Set DEVCTL_LOCAL_MERGE_CLAUDE=off before project add|sync to leave that mount out. Every registration takes part, including folders whose Exchange is a per-repository pair and legacy registrations; a legacy registration's checkout gets the same read-only mount, outside the Exchange mount generation.

  2. The plan.

    • About every five minutes, the agent visits every repository Project that Core lists for this client and fingerprints its connected folder: branch tips, stashes, HEAD, status, and transcript names and sizes. It also does this after every connect or sync.
    • Each pass logs one JSON line per Project, local-merge.folder, with the outcome: planned (refs, sessions, upload bytes), nothing-to-merge, unchanged, skipped with a reason (mode-off, disabled, not-mounted, not-git) or failed with a fixed code. One local-merge.pass summary line follows. The lines hold counts, codes and IDs, never paths or content.
    • A connected folder that is not itself a Git checkout (a parent folder) merges its one direct child checkout whose origin is the Project's remote.
    • A large folder stays mergeable. A bundle or transcript over the 2 GiB artifact bound, or refs beyond 5000, are left out and shown in the plan as skipped (too-large, with count and size); the rest of the folder still merges. Failures name the HTTP status (core-413), core-timeout, core-unreachable, or invalid-response with the rejected field.
    • Only local-only work is sent. A branch whose commits the folder's remote-tracking refs already contain is on the remote and is only counted (pushedRefs). A clean checkout has no snapshot.
    • When the fingerprint changes, it collects the folder read-only and sends Core a metadata manifest: refs, commits, counts, sizes and sha256 values. The manifest holds no content and no local path.
    • Core checks that this client is linked to that Project and that the client and the Project have the same owner.
    • Core plans the merge against its own state and its ledger. A newer plan replaces an older open one for the same folder.
  3. The confirmation. In mode confirm (the default) the Project owner reviews the plan and confirms or discards it:

    devctl local-merge list PROJECT
    devctl local-merge show PROJECT lmr-...
    devctl local-merge apply PROJECT lmr-... --plan-sha256 <sha>
    devctl local-merge discard PROJECT lmr-...
    devctl local-merge pending        # every open merge (installation owner)
    

    In mode auto the plan is confirmed when it is made.

  4. The upload. The agent uploads the plan's artifacts: one Git bundle and the transcripts. Core stores them by content and verifies size and sha256 while writing.

  5. The import. Core plans again from the stored manifest.

    • If anything changed, the merge is superseded and the folder is planned again.
    • Otherwise one local-merge.apply command goes to the Project's checkout Host. The Host downloads and verifies each artifact, imports it by the rules below, and returns a receipt. Core records the receipt and the ledger.

What is merged

Local work On the server
Local branch B Hidden ref refs/devctrl-import/<source>/heads/B
Stash n refs/devctrl-import/<source>/stashes/<n>-<sha12>, the stash commit with its index and untracked parents
Uncommitted work A snapshot commit at refs/devctrl-import/<source>/worktrees/main, plus the create-only branch refs/heads/imported/<source>/worktree-main
Claude Code transcript Retained at <data root>/local-imports/<source>/claude/<native id>.<sha12>.jsonl on the Host

<source> is <client id>-<folder key8>, so every connected folder of every device has its own namespace.

How the snapshot is built:

How the bundle is built:

Merge rules

The server's own refs are never written: refs/heads/*, refs/remotes/*, tags, HEAD, the index and the working tree. Each hidden ref is set by compare-and-swap:

Server state of the ref Outcome
absent created
same commit unchanged
an ancestor of the new commit fast-forward (the old commit stays reachable)
anything else (rebase or reset) diverged-kept: the old ref stays, and the new commit goes to <ref>@<sha12>
the commit is neither in the bundle nor on the server missing

imported/... branches are create-only. A different tip gets a -<sha12> suffix.

Transcripts are linked into place with an exclusive create. An identical file is unchanged. A different file under the same name is an error, and the file stays as it was.

A session the server already holds under the same native ID is already-on-server.

Idempotency:

Settings

devctl local-merge settings PROJECT
devctl local-merge configure PROJECT --mode off|confirm|auto [--codex-sessions true|false]

codexSessions is stored, and it filters plans. Codex rollouts are not mounted yet, because Codex stores them by date, not by folder.

Privacy and authorization

The local agent reads only:

It sends only those folders' Git objects and those transcripts. It never sends other folders, provider history or state databases, credentials, ignored files or absolute local paths.

Only a client linked to a Project, and with the same owner, can plan that Project's merge. Only that client can upload the artifacts.

Confirm, discard and settings are Project-owner routes; the server-user perimeter asserts ownership. The global list of open merges is for the installation owner.

A Host reads an artifact only while its own import that names it is in flight.

What is not merged

Not yet included