Add nvrsion: per-file shared-trunk versioning for multi-agent orchestration

An opt-in (Beta, Nucleic-Control-only) versioning mode where a project's agent
sessions share one nucleic/trunk checkout, lock individual files per-edit, land each
completed edit into the trunk immediately, and release fast — instead of holding a
session-long lock until a big merge. Conflicts are structurally impossible within the
trunk (serialized per-file writes + forced re-ground), so 'merge' collapses to 'commit'.

- Phase A: ProjectNvrsion config, migration v20-nvrsion, nvrsionActive gate, Beta toggle
- Phase B: NvrsionTrunk actor (ensureTrunk/land/regroundOnGrant), shared-trunk topology
  (no per-session worktree), per-edit host-mediated path-scoped commit + release
- Phase C: NvrsionReleaseGovernor keep-warm idle eviction, launch crash-recovery,
  flip-safety guard
- Phase D: pre-land validation hook, trunk->base squash promotion + 'Promote trunk' UI

Design and rationale: docs/NVRSION.md. Full suite green (585 tests).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Sources/NucleicApp/Sheets.swift

@@ -145,6 +145,11 @@ struct ProjectSettingsSheet: View {
     @State private var image: String
     @State private var idleMinutes: Int
     @State private var allowHostExec: Bool
+    // nvrsion (Beta) — shared-trunk versioning; control-only (NVRSION §10).
+    @State private var nvrsionEnabled: Bool
+    @State private var nvrsionKeepWarm: Int
+    @State private var nvrsionPrelandHook: String
+    @State private var nvrsionPromoting = false
     @State private var showMove = false
     /// Drives the "Convert to Nucleic Control" confirmation popup (the conversion is permanent —
     /// a Control project can't be released — so it always asks first).
@@ -168,6 +173,16 @@ struct ProjectSettingsSheet: View {
         _image = State(initialValue: sandbox.image ?? "")
         _idleMinutes = State(initialValue: max(1, sandbox.idleTimeoutSeconds / 60))
         _allowHostExec = State(initialValue: sandbox.allowHostExec)
+        let nvrsion = project.nvrsion ?? ProjectNvrsion()
+        _nvrsionEnabled = State(initialValue: nvrsion.enabled)
+        _nvrsionKeepWarm = State(initialValue: nvrsion.keepWarmIdleSeconds)
+        _nvrsionPrelandHook = State(initialValue: nvrsion.prelandHook ?? "")
+    }
+
+    /// nvrsion is offered only on control projects using the shared container, with the service on.
+    /// (Per-session containers aren't supported in v0; see NVRSION §15.)
+    private var nvrsionAvailable: Bool {
+        controlled && containerServiceEnabled && !(project.sandbox?.perSessionContainers ?? false)
     }
 
     var body: some View {
@@ -282,6 +297,82 @@ struct ProjectSettingsSheet: View {
             .background(AppTheme.surface, in: .rect(cornerRadius: 12))
             .overlay(RoundedRectangle(cornerRadius: 12).strokeBorder(AppTheme.hairline, lineWidth: 1))
 
+            if controlled {
+                VStack(alignment: .leading, spacing: 10) {
+                    Toggle(isOn: $nvrsionEnabled) {
+                        VStack(alignment: .leading, spacing: 2) {
+                            HStack(spacing: 6) {
+                                Text("nvrsion — shared trunk")
+                                Text("BETA")
+                                    .font(.caption2).bold()
+                                    .padding(.horizontal, 5).padding(.vertical, 1)
+                                    .background(AppTheme.hairline, in: .capsule)
+                            }
+                            Text("Sessions share one `nucleic/trunk` checkout and land each edit "
+                                + "into it the instant it completes, releasing the file's lock right "
+                                + "away — instead of holding it until the whole chat ships. Trunk "
+                                + "reaches your real branch only when promoted.")
+                                .font(.caption).foregroundStyle(.secondary)
+                        }
+                    }
+                    .disabled(!nvrsionAvailable)
+
+                    if !nvrsionAvailable {
+                        Text(project.sandbox?.perSessionContainers ?? false
+                            ? "Unavailable with per-session containers — nvrsion needs the shared "
+                                + "primary container in this version."
+                            : "Turn on the container service in Settings → Sandbox to use nvrsion.")
+                            .font(.caption).foregroundStyle(.secondary)
+                    }
+
+                    if nvrsionEnabled && nvrsionAvailable {
+                        Divider()
+                        Stepper(
+                            "Release an idle file after \(nvrsionKeepWarm)s",
+                            value: $nvrsionKeepWarm, in: 1...60)
+                        Text("Keep-warm window: a file you've stopped editing is handed to a "
+                            + "waiting session after this long, even mid-chat. Lower = faster "
+                            + "hand-off, more re-reads.")
+                            .font(.caption).foregroundStyle(.secondary)
+
+                        Divider()
+                        HStack {
+                            Text("Pre-land check")
+                            TextField("optional command — e.g. nvrsion-check", text: $nvrsionPrelandHook)
+                                .textFieldStyle(.roundedBorder)
+                        }
+                        Text("Runs on the edited files before each lands in trunk. Non-zero exit "
+                            + "rejects that edit back to the agent. Leave blank to land immediately.")
+                            .font(.caption).foregroundStyle(.secondary)
+
+                        Divider()
+                        HStack(spacing: 8) {
+                            Button {
+                                Task {
+                                    nvrsionPromoting = true
+                                    await store.promoteNvrsionTrunk(project.id)
+                                    nvrsionPromoting = false
+                                }
+                            } label: {
+                                if nvrsionPromoting {
+                                    ProgressView().controlSize(.small)
+                                } else {
+                                    Text("Promote trunk → \(defaultBranchPlaceholder)")
+                                }
+                            }
+                            .disabled(nvrsionPromoting)
+                            Spacer()
+                        }
+                        Text("Squash everything currently on the trunk into your real branch as one "
+                            + "commit. Trunk reaches your real branch only when you promote.")
+                            .font(.caption).foregroundStyle(.secondary)
+                    }
+                }
+                .padding(14)
+                .background(AppTheme.surface, in: .rect(cornerRadius: 12))
+                .overlay(RoundedRectangle(cornerRadius: 12).strokeBorder(AppTheme.hairline, lineWidth: 1))
+            }
+
             VStack(alignment: .leading, spacing: 8) {
                 HStack(alignment: .firstTextBaseline) {
                     VStack(alignment: .leading, spacing: 2) {
@@ -390,6 +481,18 @@ struct ProjectSettingsSheet: View {
             allowHostExec: allowHostExec,
             // Per-session containers aren't user-settable yet; preserve any existing choice.
             perSessionContainers: project.sandbox?.perSessionContainers ?? false)
+        // nvrsion (Beta) — only meaningful on control projects; store nil when off so the model
+        // stays clean. Preserve the trunk-branch name from any existing config.
+        let hook = nvrsionPrelandHook.trimmingCharacters(in: .whitespacesAndNewlines)
+        if controlled && nvrsionEnabled {
+            updated.nvrsion = ProjectNvrsion(
+                enabled: true,
+                trunkBranch: project.nvrsion?.trunkBranch ?? ProjectNvrsion.defaultTrunkBranch,
+                prelandHook: hook.isEmpty ? nil : hook,
+                keepWarmIdleSeconds: nvrsionKeepWarm)
+        } else {
+            updated.nvrsion = nil
+        }
         await store.updateProject(updated)
         dismiss()
     }

Sources/NucleicCore/AppStore.swift

@@ -447,6 +447,19 @@ public final class AppStore: ConflictArbiter {
     /// replace the old `unmergedFiles`-derived "lock". Acquired via `arbitrate` on edit, released
     /// by `reconcileLocks` once work lands in the parent (any merger), plus mediated/lifecycle.
     private let lockManager = LockManager()
+    /// Host-side coordinator for the shared nvrsion trunk (NVRSION). Owns each nvrsion project's
+    /// `nucleic/trunk` checkout and lands per-edit commits into it; nil-effect for non-nvrsion
+    /// projects (it's only ever invoked when `project.nvrsionActive`).
+    private let nvrsionTrunk = NvrsionTrunk()
+    /// Keep-warm governor (NVRSION §4): tracks which landed files a session still holds and which
+    /// have gone idle past their project's `keepWarmIdle`, so the sweep can release them mid-turn.
+    /// Internal (not private) so tests can drive `warmed`/`sweep` against a controlled clock.
+    let nvrsionGovernor: NvrsionReleaseGovernor
+    /// The keep-warm sweep loop; nil when nothing is warm (NVRSION §4). Restarts on the next land.
+    private var nvrsionKeepWarmTask: Task<Void, Never>?
+    /// How often the keep-warm sweep runs while files are warm. Internal so tests can shorten it (or
+    /// drive `runNvrsionSweep()` directly with a controlled clock).
+    var nvrsionKeepWarmInterval: Duration = .seconds(1)
     /// The release-reconcile loop; nil when nothing holds a lock (LOCKING §4.4).
     private var lockReconcileTask: Task<Void, Never>?
     /// Re-check cadence for `reconcileLocks` — a slow backstop, since release is also event-driven
@@ -568,6 +581,7 @@ public final class AppStore: ConflictArbiter {
         self.containerManager = containerManager
         self.conflictCoordinator = conflictCoordinator
         self.now = now
+        self.nvrsionGovernor = NvrsionReleaseGovernor(now: now)
         self.backendFactory = backendFactory
     }
 
@@ -619,6 +633,8 @@ public final class AppStore: ConflictArbiter {
         await containerManager?.reconcile(activeSessions: Array(controllers.keys))
         // Rebuild held locks from authoritative git state now that controllers exist (LOCKING §6).
         await reconstructLocks()
+        // Commit any uncommitted residue a crash left on an nvrsion trunk (NVRSION §8).
+        await reconcileNvrsionTrunks()
     }
 
     /// The last complete assistant reply in a transcript, or nil if unreadable/empty —
@@ -742,7 +758,20 @@ public final class AppStore: ConflictArbiter {
     /// Persist edits to a project's configuration (e.g. sandbox settings) and refresh the
     /// in-memory list. Sandbox changes take effect on the next turn started in the project.
     public func updateProject(_ project: Project) async {
-        let wasSandboxed = projectsByID[project.id]?.sandbox?.enabled == true
+        var project = project
+        let prev = projectsByID[project.id]
+        let wasSandboxed = prev?.sandbox?.enabled == true
+        // Flip-safety (NVRSION §10): toggling nvrsion (shared-trunk) on/off must not let the two
+        // versioning models coexist on live work. Refuse the flip while the project has a live
+        // (non-terminal) chat — keep its previous nvrsion setting and surface why — but let every
+        // other field of the update through.
+        let nvrsionFlip = (prev?.nvrsion?.enabled ?? false) != (project.nvrsion?.enabled ?? false)
+        if nvrsionFlip,
+            summaries.contains(where: { $0.projectID == project.id && !$0.archived && !$0.status.isTerminal })
+        {
+            project.nvrsion = prev?.nvrsion
+            lastError = "Finish or stop this project's chats before changing nvrsion (shared-trunk) mode."
+        }
         do {
             try await database.saveProject(project)
             await loadProjects()
@@ -1910,10 +1939,15 @@ public final class AppStore: ConflictArbiter {
     /// control container (the `git` interceptor shim, [[git-event]]). Outside it we couldn't
     /// reliably unlock, so we don't lock at all rather than strand files.
     private func lockDomain(for session: Session) -> LockDomain? {
-        guard projectsByID[session.projectID]?.isNucleicControlled == true else { return nil }
+        guard let project = projectsByID[session.projectID], project.isNucleicControlled else { return nil }
+        // nvrsion (NVRSION §10): the whole project shares one lock domain — the trunk branch —
+        // so every nvrsion session contends on a file and lands into the same trunk.
+        if project.nvrsionActive, let nvrsion = project.nvrsion {
+            return LockDomain(nvrsion.trunkBranch)
+        }
         if let root = session.rootRef { return LockDomain(root) }
         if let parent = session.parentRef { return LockDomain(parent) }
-        return projectsByID[session.projectID].map { LockDomain($0.defaultBranch.value) }
+        return LockDomain(project.defaultBranch.value)
     }
 
     /// Update-on-grant hook for the LockManager (LOCKING §4.5): bring a just-granted session's
@@ -1921,6 +1955,14 @@ public final class AppStore: ConflictArbiter {
     /// proceeding. `.clean` if gone; `.changed` when the parent moved one of those files.
     private func runUpdateOnGrant(_ id: SessionID, files: [String]) async -> LockUpdateResult {
         guard let controller = controllers[id] else { return .clean }
+        let session = await controller.snapshot.session
+        // nvrsion (NVRSION §3.2): there's no per-session worktree to merge a parent into — the
+        // session edits the shared trunk live. "Re-ground" = did a requested file move in the trunk
+        // since this session last had it? If so, tell the agent to re-read before editing.
+        if let project = projectsByID[session.projectID], project.nvrsionActive,
+            let trunk = session.worktreePath {
+            return await nvrsionTrunk.regroundOnGrant(trunkPath: trunk, session: id, files: files)
+        }
         return await controller.updateFromParent(requestedFiles: files)
     }
 
@@ -2072,6 +2114,128 @@ public final class AppStore: ConflictArbiter {
     /// user — by reusing `unmergedFiles`), and release everything for a terminal/archived holder.
     /// Refreshes the "waiting"/deadlock indicators. Liveness is owned by the driver (`isIdle`), so
     /// this no longer decides when to stop — it just does the work.
+    /// The nvrsion edit loop (NVRSION §3–4), driven off each session's event stream. On every
+    /// completed edit (`.fileChange`, emitted only after a successful tool_result) land the file
+    /// into the shared trunk as a path-scoped commit. At turn-end (`.runFinished`) release the
+    /// turn's held files — "keep-warm within a turn", so a sibling can't interleave between two of
+    /// the agent's edits to one file, but can take it once the turn settles (NVRSION §4). No-op
+    /// unless the session's project has nvrsion active.
+    private func handleNvrsionEvent(
+        _ sessionID: SessionID, _ controller: SessionController, _ event: AgentEvent
+    ) async {
+        // Cheap pre-filter: only a completed edit or a turn boundary drives nvrsion — skip the
+        // snapshot fetch for the common text/thinking/tool-delta events (every session, every run).
+        switch event.kind {
+        case .fileChange, .runFinished: break
+        default: return
+        }
+        let session = await controller.snapshot.session
+        guard let project = projectsByID[session.projectID], project.nvrsionActive,
+            let trunkPath = session.worktreePath
+        else { return }
+        switch event.kind {
+        case .fileChange(let change):
+            let rel = ConflictDetector.normalize(stripWorktreePrefix(change.path, trunkPath))
+            guard !rel.isEmpty else { return }
+            let message = session.title.isEmpty ? "nvrsion edit" : session.title
+            switch await nvrsionTrunk.land(
+                trunkPath: trunkPath, session: sessionID, paths: [rel], message: message,
+                prelandHook: project.nvrsion?.resolvedPrelandHook)
+            {
+            case .landed, .noop:
+                // Keep-warm (NVRSION §4): the file is landed but stays held; mark it warm so the
+                // sweep releases it once it goes idle past the project's keepWarmIdle (or at turn-end).
+                let idle = project.nvrsion?.keepWarmIdleSeconds ?? ProjectNvrsion.defaultKeepWarmIdleSeconds
+                await nvrsionGovernor.warmed(sessionID, rel, idleSeconds: idle)
+                startNvrsionKeepWarmIfNeeded()
+            case .rejected(let why):
+                await controller.note("nvrsion pre-land check rejected \(rel): \(why)",
+                                      icon: "exclamationmark.triangle")
+            case .failed(let why):
+                await controller.note("nvrsion could not land \(rel): \(why)",
+                                      icon: "exclamationmark.triangle")
+            }
+        case .runFinished:
+            // Turn-end: release every file the turn held warm (NVRSION §4).
+            await lockManager.releaseAll(sessionID)
+            await nvrsionGovernor.forget(sessionID)
+        default:
+            break
+        }
+    }
+
+    /// Start the keep-warm sweep loop if it isn't running (NVRSION §4). It wakes on its interval,
+    /// releases any landed file that's gone idle past its window, and parks itself once nothing is
+    /// warm — the next land restarts it. Cheap: it only runs while files are actually held warm.
+    private func startNvrsionKeepWarmIfNeeded() {
+        guard nvrsionKeepWarmTask == nil else { return }
+        nvrsionKeepWarmTask = Task { [weak self] in
+            while let self, !Task.isCancelled {
+                try? await Task.sleep(for: self.nvrsionKeepWarmInterval)
+                if Task.isCancelled { break }
+                if await self.runNvrsionSweep() { break }  // nothing left warm → park
+            }
+            await self?.clearNvrsionKeepWarmTask()
+        }
+    }
+    private func clearNvrsionKeepWarmTask() { nvrsionKeepWarmTask = nil }
+
+    /// One keep-warm sweep pass: release each landed file that's gone idle past its window, then
+    /// report whether the governor is now empty (so the loop can park). Internal so tests can drive
+    /// it deterministically against a controlled clock.
+    @discardableResult
+    func runNvrsionSweep() async -> Bool {
+        for (session, paths) in await nvrsionGovernor.sweep() {
+            await lockManager.release(session, paths: paths)
+        }
+        return await nvrsionGovernor.isEmpty
+    }
+
+    /// Launch crash-recovery (NVRSION §8): for each nvrsion project, ensure its trunk exists and
+    /// commit any uncommitted residue a crash mid-edit may have left, so the trunk starts clean.
+    /// Lock state itself needs no reconstruction — a restart kills every agent, so in-flight nvrsion
+    /// locks correctly vanish (and worktree-less nvrsion sessions are already skipped by
+    /// `reconstructLocks`); only the trunk's working tree can carry residue across a crash.
+    private func reconcileNvrsionTrunks() async {
+        for project in projects where project.nvrsionActive {
+            guard let nvrsion = project.nvrsion else { continue }
+            await nvrsionTrunk.recover(
+                root: project.rootPath, trunkPath: project.resolvedTrunkPath,
+                trunkBranch: nvrsion.trunkBranch, base: project.defaultBranch.value)
+        }
+    }
+
+    /// Promote an nvrsion project's accumulated trunk work into its real base branch (NVRSION §6) —
+    /// the explicit "ship everything on the trunk" action. Squashes the trunk into the base as one
+    /// commit. Returns true on success; reports nothing-to-promote / conflicts / failure via
+    /// `lastError`. (Per-session autoship-on-completion is a future refinement; see docs/NVRSION.md.)
+    @discardableResult
+    public func promoteNvrsionTrunk(_ projectID: ProjectID) async -> Bool {
+        guard let project = projectsByID[projectID], project.nvrsionActive, let nvrsion = project.nvrsion
+        else { lastError = "nvrsion is not active for this project."; return false }
+        let base = project.defaultBranch.value
+        switch await nvrsionTrunk.promote(
+            root: project.rootPath, trunkPath: project.resolvedTrunkPath,
+            trunkBranch: nvrsion.trunkBranch, base: base,
+            message: "nvrsion: promote trunk to \(base)")
+        {
+        case .promoted(let sha):
+            lastError = nil
+            lockLog.notice("nvrsion promoted project=\(projectID.rawValue, privacy: .public) base=\(base, privacy: .public) sha=\(sha, privacy: .public)")
+            return true
+        case .nothingToPromote:
+            lastError = "Nothing on the nvrsion trunk to promote to \(base)."
+            return false
+        case .conflicted(let files):
+            lastError = "Promoting the nvrsion trunk conflicted in \(Self.lockPathList(files)). "
+                + "Resolve on \(base) and retry."
+            return false
+        case .failed(let why):
+            lastError = "nvrsion promote failed: \(why)"
+            return false
+        }
+    }
+
     private func reconcileLocks() async {
         for sid in await lockManager.sessionsHoldingLocks() {
             let heldPaths = await lockManager.heldPaths(sid)
@@ -2664,13 +2828,23 @@ public final class AppStore: ConflictArbiter {
         let backendID = BackendID.forModel(resolvedModel) ?? project.defaultBackend ?? .claudeCode
         let resolvedBase = base ?? project.defaultBranch
 
+        // nvrsion (NVRSION §2): the whole project shares one `nucleic/trunk` checkout — the session
+        // makes NO isolated worktree; it edits the shared trunk directly and lands each edit into it.
+        // So it behaves like a worktree-less session whose working dir is the trunk.
+        let nvrsionTrunkPath: String? = project.nvrsionActive ? project.resolvedTrunkPath : nil
+        if let nvrsionTrunkPath, let nvrsion = project.nvrsion {
+            try await nvrsionTrunk.ensureTrunk(
+                root: project.rootPath, trunkPath: nvrsionTrunkPath,
+                trunkBranch: nvrsion.trunkBranch, base: project.defaultBranch.value)
+        }
+
         // With a worktree (the default), the chat runs on its own isolated branch.
         // Without one, it runs directly in the project's main checkout on the chosen
         // branch — no isolation, so merges/discards have nothing to remove.
-        let worktree: Worktree? = useWorktree
+        let worktree: Worktree? = (useWorktree && nvrsionTrunkPath == nil)
             ? try await worktrees.create(for: sessionID, in: project, base: resolvedBase, slug: title)
             : nil
-        let worktreePath = worktree?.path ?? project.rootPath
+        let worktreePath = nvrsionTrunkPath ?? worktree?.path ?? project.rootPath
 
         let transcriptURL = transcriptsDir
             .appendingPathComponent(sessionID.rawValue)
@@ -2690,14 +2864,17 @@ public final class AppStore: ConflictArbiter {
         // inherit that session's `rootRef` (the tree's top-level branch) and link to it; else
         // this base *is* the root of a new tree.
         let parentSession = await liveSession(whoseBranchIs: resolvedBase.value)
+        // nvrsion sessions all live on the shared trunk branch (their lock domain, NVRSION §10);
+        // they have no fork point (`baseSHA`) and no nesting — the trunk is the one shared base.
+        let nvrsionBranch = nvrsionTrunkPath != nil ? project.nvrsion?.trunkBranch : nil
         let session = Session(
             id: sessionID, projectID: project.id, backend: backendID,
             title: title, status: trimmedPrompt.isEmpty ? .awaitingInput : .running,
-            worktreePath: worktreePath, branch: worktree?.branch ?? resolvedBase.value,
+            worktreePath: worktreePath, branch: nvrsionBranch ?? worktree?.branch ?? resolvedBase.value,
             baseSHA: worktree?.baseSHA,
-            parentRef: resolvedBase.value,
+            parentRef: nvrsionBranch ?? resolvedBase.value,
-            rootRef: parentSession?.rootRef ?? resolvedBase.value,
+            rootRef: nvrsionBranch ?? parentSession?.rootRef ?? resolvedBase.value,
-            parentSessionID: parentSession?.id,
+            parentSessionID: nvrsionBranch != nil ? nil : parentSession?.id,
             model: resolvedModel, effort: effort ?? defaultEffort,
             transcriptPath: transcriptURL.path, auto: resolvedAuto,
             autoShip: resolvedAutoShip,
@@ -3163,6 +3340,7 @@ public final class AppStore: ConflictArbiter {
 
     private func ingestUI(_ sessionID: SessionID, _ event: AgentEvent) async {
         guard let controller = controllers[sessionID] else { return }
+        await handleNvrsionEvent(sessionID, controller, event)
         // The account-wide rate-limit window the CLI reports out of band: mirror the
         // latest one as the coarse fallback for the global quota indicator.
         if case .rateLimit(let rl) = event.kind { latestRateLimit = rl }

Sources/NucleicCore/NvrsionReleaseGovernor.swift

@@ -0,0 +1,53 @@
+import Foundation
+
+/// Keep-warm release governor for nvrsion (NVRSION §4). After an agent *lands* a file it keeps the
+/// lock ("warm") past that single edit, so a sibling can't interleave between two edits of one
+/// logical change — but only until the file goes idle past the project's `keepWarmIdle`, at which
+/// point a sweep releases it without waiting for the whole turn to end. Turn-end / lifecycle drops
+/// everything (the host calls `forget`). Re-landing a file refreshes its idle clock, so a file under
+/// active editing stays held while a finished one is handed off quickly.
+///
+/// Pure timekeeping over an injected clock — no locks, no git — so the eviction policy is unit
+/// testable in isolation; `AppStore` performs the actual `LockManager.release` for whatever `sweep`
+/// returns. Releasing a file the agent later returns to simply re-acquires + re-grounds (NVRSION §4).
+public actor NvrsionReleaseGovernor {
+    private let now: @Sendable () -> Date
+
+    private struct Warm { var landedAt: Date; var idle: TimeInterval }
+    /// `warm[session][path]` — a file the session has landed and still holds, with its idle window.
+    private var warm: [SessionID: [String: Warm]] = [:]
+
+    public init(now: @escaping @Sendable () -> Date = { Date() }) { self.now = now }
+
+    /// Record (or refresh) that `session` just landed `path` and still holds it; `idleSeconds` is
+    /// the project's keep-warm window (NVRSION §4). Re-landing refreshes the idle clock.
+    public func warmed(_ session: SessionID, _ path: String, idleSeconds: Int) {
+        warm[session, default: [:]][path] = Warm(landedAt: now(), idle: TimeInterval(max(0, idleSeconds)))
+    }
+
+    /// Forget everything `session` holds warm — turn-end or lifecycle (the host released the locks).
+    public func forget(_ session: SessionID) { warm[session] = nil }
+
+    /// The files idle past their window, grouped by session; the governor drops them from its table
+    /// (the caller releases the corresponding locks). A file re-landed within its window is kept.
+    public func sweep() -> [(session: SessionID, paths: [String])] {
+        let t = now()
+        var out: [(session: SessionID, paths: [String])] = []
+        for (session, files) in warm {
+            let due = files.filter { t.timeIntervalSince($0.value.landedAt) >= $0.value.idle }.map(\.key)
+            guard !due.isEmpty else { continue }
+            for p in due { warm[session]?[p] = nil }
+            if warm[session]?.isEmpty == true { warm[session] = nil }
+            out.append((session: session, paths: due.sorted()))
+        }
+        return out
+    }
+
+    /// Nothing is warm — the host stops the sweep timer until the next land.
+    public var isEmpty: Bool { warm.isEmpty }
+
+    /// Warm paths a session currently holds, sorted (tests / introspection).
+    public func warmPaths(_ session: SessionID) -> [String] {
+        (warm[session].map { Array($0.keys) } ?? []).sorted()
+    }
+}

Sources/NucleicCore/NvrsionTrunk.swift

@@ -0,0 +1,357 @@
+import Foundation
+import os
+
+/// nvrsion lifecycle tracing (NVRSION). Every trunk ensure / land / reground is logged so a
+/// stuck edit can be diagnosed from `log stream --predicate 'subsystem == "com.nucleic"'`
+/// (category "nvrsion"). Paths + session ids are `.public` (a local project's own data).
+let nvrsionLog = Logger(subsystem: "com.nucleic", category: "nvrsion")
+
+/// Outcome of landing one edit into the trunk (NVRSION §3).
+public enum NvrLandResult: Sendable, Equatable {
+    /// Committed — `sha` is the new trunk HEAD.
+    case landed(sha: String)
+    /// Nothing to commit (the edit left the file identical to HEAD) — treated as success.
+    case noop
+    /// The pre-land hook rejected the edit (NVRSION §5); `stderr` is fed back to the agent.
+    /// (Wired in Phase D; defined here so the contract is stable.)
+    case rejected(String)
+    /// Git failed (after retries) — the edit stays on disk uncommitted; lock kept.
+    case failed(String)
+}
+
+/// Outcome of promoting the trunk into the real base branch (NVRSION §6).
+public enum NvrPromoteResult: Sendable, Equatable {
+    /// The trunk's accumulated work was squashed into `base` as one commit (`sha`).
+    case promoted(sha: String)
+    /// The trunk already matches `base` — nothing to promote.
+    case nothingToPromote
+    /// The squash into `base` conflicted (e.g. the base was edited outside the trunk); `files` list it.
+    case conflicted([String])
+    case failed(String)
+}
+
+/// Host-side coordinator for the shared **nvrsion trunk** (NVRSION §2–3). Owns the single
+/// `nucleic/trunk` checkout for a project and lands each *completed* edit into it as a
+/// **path-scoped** commit. The host performs every commit (the agent only writes the file, which
+/// the virtiofs mount reflects on the host), so lock release is **host-certain** — there is no
+/// landing-detection poll, and "committed ≠ landed" can't strand a lock (NVRSION §4).
+///
+/// Although an `actor`, git work suspends at `await`, and Swift actors are *reentrant* — two
+/// `land`s would otherwise interleave their `add`+`commit` on the one shared `.git/index`. So an
+/// explicit serial gate (`withGate`) makes the add→commit sequence atomic against any other trunk
+/// op; the agent's own in-container git can still race the index, handled by bounded retry.
+public actor NvrsionTrunk {
+    private let git: GitRunner
+
+    public init(git: GitRunner = GitRunner()) { self.git = git }
+
+    // MARK: Serial gate (reentrancy-safe actor mutex)
+
+    private var busy = false
+    private var waiters: [CheckedContinuation<Void, Never>] = []
+
+    private func acquireGate() async {
+        if !busy { busy = true; return }
+        await withCheckedContinuation { waiters.append($0) }
+    }
+    private func releaseGate() {
+        if waiters.isEmpty { busy = false } else { waiters.removeFirst().resume() }
+    }
+    /// Run `body` with exclusive access to this trunk's git index (serializes add+commit etc.).
+    private func withGate<T>(_ body: () async throws -> T) async rethrows -> T {
+        await acquireGate()
+        do { let r = try await body(); releaseGate(); return r }
+        catch { releaseGate(); throw error }
+    }
+
+    // MARK: State
+
+    /// Trunk checkouts already ensured this run (idempotence), keyed by trunk path.
+    private var ensured: Set<String> = []
+    /// `observed[session][path]` = the trunk blob sha the session last had for `path` — drives the
+    /// on-grant re-ground decision (NVRSION §3.2). Absent path → `""`.
+    private var observed: [SessionID: [String: String]] = [:]
+
+    // MARK: Ensure the trunk worktree exists (NVRSION §2)
+
+    /// Idempotently ensure `<repo>/.nucleic/trunk` is a worktree checked out on `trunkBranch`,
+    /// forking it from `base` when the branch is new. Safe to call on every nvrsion session create.
+    public func ensureTrunk(root: String, trunkPath: String, trunkBranch: String, base: String) async throws {
+        if ensured.contains(trunkPath) { return }
+        try await withGate {
+            if ensured.contains(trunkPath) { return }
+            let dotGit = (trunkPath as NSString).appendingPathComponent(".git")
+            if FileManager.default.fileExists(atPath: dotGit) {
+                ensured.insert(trunkPath)
+                nvrsionLog.info("nvrsion ensureTrunk reuse path=\(trunkPath, privacy: .public)")
+                return
+            }
+            let parent = (trunkPath as NSString).deletingLastPathComponent
+            try? FileManager.default.createDirectory(atPath: parent, withIntermediateDirectories: true)
+            // Drop any stale worktree registration for this path before re-adding.
+            _ = try? await git.run(["worktree", "prune"], in: root)
+            let branchExists =
+                (try? await git.run(["rev-parse", "--verify", "--quiet", "\(trunkBranch)^{commit}"], in: root))?.ok == true
+            let args = branchExists
+                ? ["worktree", "add", trunkPath, trunkBranch]
+                : ["worktree", "add", trunkPath, "-b", trunkBranch, base]
+            let res = try await git.run(args, in: root)
+            guard res.ok else {
+                nvrsionLog.error("nvrsion ensureTrunk FAILED path=\(trunkPath, privacy: .public) stderr=\(res.stderr, privacy: .public)")
+                throw GitError.commandFailed(
+                    command: "git " + args.joined(separator: " "), status: res.status, stderr: res.stderr)
+            }
+            ensured.insert(trunkPath)
+            nvrsionLog.notice("nvrsion ensureTrunk created path=\(trunkPath, privacy: .public) branch=\(trunkBranch, privacy: .public) base=\(base, privacy: .public)")
+        }
+    }
+
+    // MARK: Land one edit (NVRSION §3)
+
+    /// Commit exactly `paths` (repo-relative) into the trunk as one path-scoped commit, attributed
+    /// to `session`. Serialized; retries a few times if the agent's own git holds `.git/index.lock`.
+    /// Returns `.landed`/`.noop` on success (lock may release), or `.failed` (lock kept).
+    ///
+    /// `prelandHook` (NVRSION §5), when set, runs on the edited files *before* the commit; a non-zero
+    /// exit returns `.rejected` so the edit does **not** land (its content stays on disk, lock kept).
+    /// The hook runs OUTSIDE the index gate (it only reads files), so a slow hook can't wedge other
+    /// sessions' lands — only its own edit waits.
+    public func land(
+        trunkPath: String, session: SessionID, paths: [String], message: String,
+        prelandHook: String? = nil
+    ) async -> NvrLandResult {
+        let specs = paths.filter { !$0.isEmpty }
+        guard !specs.isEmpty else { return .noop }
+        if let prelandHook {
+            let (passed, output) = await runPrelandHook(prelandHook, trunkPath: trunkPath, paths: specs)
+            if !passed {
+                nvrsionLog.notice("nvrsion preland REJECT session=\(session.rawValue, privacy: .public) paths=\(specs.joined(separator: ","), privacy: .public)")
+                return .rejected(output.isEmpty ? "pre-land check failed" : output)
+            }
+        }
+        return await withGate {
+            for attempt in 0..<3 {
+                // Stage adds/mods/deletes scoped to these paths only — never another session's
+                // in-flight file (the per-edit isolation that keeps trunk consistent).
+                let add = try? await git.run(["add", "-A", "--"] + specs, in: trunkPath)
+                let commit = try? await git.run(
+                    ["-c", "commit.gpgsign=false", "commit", "-m", message,
+                     "--trailer", "Nucleic-Session: \(session.rawValue)", "--"] + specs,
+                    in: trunkPath)
+                guard let commit else {
+                    if attempt < 2 { try? await Task.sleep(nanoseconds: 60_000_000); continue }
+                    return .failed("git did not run")
+                }
+                if commit.ok {
+                    let head = (try? await git.run(["rev-parse", "HEAD"], in: trunkPath))?
+                        .stdout.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                    await recordObserved(session: session, trunkPath: trunkPath, paths: specs)
+                    nvrsionLog.notice("nvrsion land session=\(session.rawValue, privacy: .public) paths=\(specs.joined(separator: ","), privacy: .public) sha=\(head, privacy: .public)")
+                    return .landed(sha: head)
+                }
+                let blob = commit.stdout + commit.stderr
+                if blob.contains("nothing to commit") || blob.contains("no changes added") {
+                    // The edit produced no net change vs HEAD (identical content) — fine.
+                    await recordObserved(session: session, trunkPath: trunkPath, paths: specs)
+                    return .noop
+                }
+                if blob.contains("index.lock") && attempt < 2 {
+                    try? await Task.sleep(nanoseconds: 60_000_000); continue  // agent's git holds it; retry
+                }
+                _ = add
+                nvrsionLog.error("nvrsion land FAILED session=\(session.rawValue, privacy: .public) paths=\(specs.joined(separator: ","), privacy: .public) stderr=\(commit.stderr, privacy: .public)")
+                return .failed(commit.stderr)
+            }
+            return .failed("exhausted retries")
+        }
+    }
+
+    // MARK: Launch crash-recovery (NVRSION §8)
+
+    /// Ensure the trunk exists, then commit any uncommitted residue a crash mid-edit may have left
+    /// on it (the agent wrote a file but the app died before the `.fileChange` landed it), so the
+    /// trunk starts each run clean and nothing is silently lost. Best-effort — failures only log.
+    public func recover(root: String, trunkPath: String, trunkBranch: String, base: String) async {
+        do {
+            try await ensureTrunk(root: root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: base)
+        } catch {
+            nvrsionLog.error("nvrsion recover ensure-failed path=\(trunkPath, privacy: .public)")
+            return
+        }
+        await withGate {
+            let status = (try? await git.run(["status", "--porcelain"], in: trunkPath))?
+                .stdout.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !status.isEmpty else { return }
+            _ = try? await git.run(["add", "-A"], in: trunkPath)
+            _ = try? await git.run(
+                ["-c", "commit.gpgsign=false", "commit",
+                 "-m", "nvrsion: recovered uncommitted work after restart",
+                 "--trailer", "Nucleic-Recovery: 1"],
+                in: trunkPath)
+            nvrsionLog.notice("nvrsion recovered dirty trunk path=\(trunkPath, privacy: .public)")
+        }
+    }
+
+    // MARK: Re-ground on grant (NVRSION §3.2)
+
+    /// The nvrsion update-on-grant: did any of `files` move in the trunk since `session` last had
+    /// them? `.clean` on first acquaintance (matching LOCKING §4.5: re-ground only fires when a file
+    /// the session *already had* advanced), else `.changed` so the host tells the agent to re-read.
+    public func regroundOnGrant(
+        trunkPath: String, session: SessionID, files: [String]
+    ) async -> LockUpdateResult {
+        let specs = files.filter { !$0.isEmpty }
+        guard !specs.isEmpty else { return .clean }
+        return await withGate {
+            var moved: [String] = []
+            for f in specs {
+                let cur = await blobSha(trunkPath: trunkPath, path: f)
+                if let last = observed[session]?[f], last != cur { moved.append(f) }
+                observed[session, default: [:]][f] = cur  // now the session has seen the current content
+            }
+            if moved.isEmpty { return .clean }
+            nvrsionLog.notice("nvrsion reground session=\(session.rawValue, privacy: .public) files=\(moved.joined(separator: ","), privacy: .public)")
+            return .changed(files: moved, diff: "")  // empty diff → the host's notice says "re-read"
+        }
+    }
+
+    /// Forget a finished session's observed-sha state (called on release-all / lifecycle).
+    public func forget(_ session: SessionID) {
+        observed[session] = nil
+    }
+
+    // MARK: Promotion — trunk → base (NVRSION §6)
+
+    /// Squash the trunk's accumulated work into the real `base` branch as one clean commit, run in
+    /// the project's root checkout (which is on `base` and untouched by nvrsion agents). Then
+    /// best-effort merge `base` back into the trunk so the next promotion is incremental. Conflicts
+    /// (e.g. `base` edited outside the trunk) leave both branches untouched and are reported.
+    public func promote(
+        root: String, trunkPath: String, trunkBranch: String, base: String, message: String
+    ) async -> NvrPromoteResult {
+        await withGate {
+            // The squash merges trunk INTO whatever `root` has checked out — require that to be `base`,
+            // so we never land trunk work on the wrong branch.
+            let onBranch = (try? await git.run(["rev-parse", "--abbrev-ref", "HEAD"], in: root))?
+                .stdout.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard onBranch == base else {
+                return .failed("root checkout is on \(onBranch ?? "?"), not \(base) — can't promote")
+            }
+            // Nothing to do when the trunk's content already equals base.
+            if let diff = try? await git.run(["diff", "--quiet", base, trunkBranch], in: root), diff.status == 0 {
+                return .nothingToPromote
+            }
+            let merge = try? await git.run(["merge", "--squash", trunkBranch], in: root)
+            guard let merge else { return .failed("git did not run") }
+            if !merge.ok {
+                // Capture the conflicted paths, then reset (── --squash sets no MERGE_HEAD, so only a
+                // hard reset is the true inverse, mirroring WorktreeManager.integrate).
+                let conflicts = (try? await git.run(
+                    ["diff", "--name-only", "--diff-filter=U"], in: root))?
+                    .stdout.split(separator: "\n").map(String.init) ?? []
+                _ = try? await git.run(["reset", "--hard", "HEAD"], in: root)
+                nvrsionLog.error("nvrsion promote CONFLICT base=\(base, privacy: .public) files=\(conflicts.joined(separator: ","), privacy: .public)")
+                return .conflicted(conflicts.isEmpty ? ["<unknown>"] : conflicts)
+            }
+            // --squash stages without committing; commit unless the squash was a no-op.
+            if let staged = try? await git.run(["diff", "--cached", "--quiet"], in: root), staged.status == 0 {
+                return .nothingToPromote
+            }
+            let commit = try? await git.run(
+                ["-c", "commit.gpgsign=false", "commit", "-m", message, "--trailer", "Nucleic-Promote: 1"],
+                in: root)
+            guard let commit, commit.ok else {
+                _ = try? await git.run(["reset", "--hard", "HEAD"], in: root)
+                return .failed(commit?.stderr ?? "commit failed")
+            }
+            let head = (try? await git.run(["rev-parse", "HEAD"], in: root))?
+                .stdout.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            // Resync the trunk onto the new base so the next promotion squashes only NEW work
+            // (advances the merge-base). Best-effort: skipped harmlessly if the trunk is dirty.
+            _ = try? await git.run(["merge", base], in: trunkPath)
+            nvrsionLog.notice("nvrsion promote base=\(base, privacy: .public) sha=\(head, privacy: .public)")
+            return .promoted(sha: head)
+        }
+    }
+
+    // MARK: Pre-land hook (NVRSION §5)
+
+    /// How long a pre-land hook may run before it's killed and the edit rejected.
+    public static let prelandTimeoutSeconds: TimeInterval = 10
+
+    private enum HookOutcome: Sendable { case exited(Int32); case spawnFailed; case timedOut }
+
+    /// Run `command` via `/bin/sh -c` on the host in the trunk dir, with the edited paths in
+    /// `NUCLEIC_NVR_PATHS`. Returns whether it passed (exit 0 within the timeout) and its combined
+    /// output (stderr+stdout) to feed back. A timeout or spawn failure counts as a failure.
+    private func runPrelandHook(
+        _ command: String, trunkPath: String, paths: [String]
+    ) async -> (passed: Bool, output: String) {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/bin/sh")
+        process.arguments = ["-c", command]
+        process.currentDirectoryURL = URL(fileURLWithPath: trunkPath)
+        var env = ProcessInfo.processInfo.environment
+        env["NUCLEIC_NVR_PATHS"] = paths.joined(separator: " ")
+        process.environment = env
+        let outPipe = Pipe(), errPipe = Pipe()
+        process.standardOutput = outPipe
+        process.standardError = errPipe
+        process.standardInput = FileHandle.nullDevice
+
+        async let outData = Self.readToEnd(outPipe.fileHandleForReading)
+        async let errData = Self.readToEnd(errPipe.fileHandleForReading)
+
+        // Wait for exit (handler set *before* run, GitRunner-style, so a fast exit isn't missed).
+        let exitWait = Task { () -> HookOutcome in
+            await withCheckedContinuation { (c: CheckedContinuation<HookOutcome, Never>) in
+                process.terminationHandler = { c.resume(returning: .exited($0.terminationStatus)) }
+                do { try process.run() } catch {
+                    process.terminationHandler = nil
+                    c.resume(returning: .spawnFailed)
+                }
+            }
+        }
+        let outcome = await withTaskGroup(of: HookOutcome.self) { group -> HookOutcome in
+            group.addTask { await exitWait.value }
+            group.addTask {
+                try? await Task.sleep(for: .seconds(Self.prelandTimeoutSeconds)); return .timedOut
+            }
+            let first = await group.next() ?? .timedOut
+            group.cancelAll()
+            return first
+        }
+        let out = (String(decoding: await errData, as: UTF8.self)
+            + String(decoding: await outData, as: UTF8.self))
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        switch outcome {
+        case .timedOut:
+            process.terminate()
+            return (false, "pre-land hook timed out after \(Int(Self.prelandTimeoutSeconds))s"
+                + (out.isEmpty ? "" : "\n\(out)"))
+        case .spawnFailed:
+            return (false, "could not start pre-land hook")
+        case .exited(let status):
+            return (status == 0, out)
+        }
+    }
+
+    private static func readToEnd(_ handle: FileHandle) async -> Data {
+        await withCheckedContinuation { c in
+            DispatchQueue.global().async { c.resume(returning: (try? handle.readToEnd()) ?? Data()) }
+        }
+    }
+
+    // MARK: Helpers
+
+    private func recordObserved(session: SessionID, trunkPath: String, paths: [String]) async {
+        for p in paths { observed[session, default: [:]][p] = await blobSha(trunkPath: trunkPath, path: p) }
+    }
+
+    /// The trunk's current blob sha for `path` (`""` if absent — deleted/untracked).
+    private func blobSha(trunkPath: String, path: String) async -> String {
+        let res = try? await git.run(["rev-parse", "--verify", "--quiet", "HEAD:\(path)"], in: trunkPath)
+        guard let res, res.ok else { return "" }
+        return res.stdout.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

Sources/NucleicCore/Persistence/GRDBMetadataStore.swift

@@ -162,6 +162,11 @@ public final class GRDBMetadataStore: SessionMetadataStore {
             try db.execute(
                 sql: "ALTER TABLE session ADD COLUMN auto_ship_conflict INTEGER NOT NULL DEFAULT 0;")
         }
+        migrator.registerMigration("v20-nvrsion") { db in
+            // Per-project nvrsion (Beta) config, JSON-encoded like sandbox_config; NULL → off
+            // (NVRSION §8, §10). New fields are additive within the JSON, no further migration.
+            try db.execute(sql: "ALTER TABLE project ADD COLUMN nvrsion_config TEXT;")
+        }
         return migrator
     }
 
@@ -291,6 +296,7 @@ private struct ProjectRow: Codable, FetchableRecord, PersistableRecord {
     var setup_script: String?
     var setup_policy: String
     var sandbox_config: String?
+    var nvrsion_config: String?
     var created_at: Date
     var archived_at: Date?
 
@@ -307,6 +313,9 @@ private struct ProjectRow: Codable, FetchableRecord, PersistableRecord {
         sandbox_config = p.sandbox.flatMap { sandbox in
             (try? JSONEncoder().encode(sandbox)).map { String(decoding: $0, as: UTF8.self) }
         }
+        nvrsion_config = p.nvrsion.flatMap { nvrsion in
+            (try? JSONEncoder().encode(nvrsion)).map { String(decoding: $0, as: UTF8.self) }
+        }
         created_at = p.createdAt
         archived_at = p.archivedAt
     }
@@ -325,6 +334,9 @@ private struct ProjectRow: Codable, FetchableRecord, PersistableRecord {
             sandbox: sandbox_config.flatMap { json in
                 try? JSONDecoder().decode(ProjectSandbox.self, from: Data(json.utf8))
             },
+            nvrsion: nvrsion_config.flatMap { json in
+                try? JSONDecoder().decode(ProjectNvrsion.self, from: Data(json.utf8))
+            },
             createdAt: created_at,
             archivedAt: archived_at)
     }

Sources/NucleicCore/Project.swift

@@ -108,6 +108,64 @@ public struct ProjectSandbox: Sendable, Codable, Equatable {
     }
 }
 
+/// Per-project **nvrsion** settings (NVRSION, Beta). When active a control project's sessions
+/// share a single `nucleic/trunk` checkout and land each edit into it immediately — instead of
+/// each session forking an isolated worktree/branch held until ship (LOCKING). `nil` on a Project
+/// (or `enabled == false`) means off — the default, classic per-session-worktree behavior.
+///
+/// Persisted as `nvrsion_config` JSON on the `project` row (mirrors `ProjectSandbox`), so new
+/// fields are additive without a migration. Only meaningful for Nucleic Control projects that use
+/// the shared control container — see `Project.nvrsionActive` (NVRSION §10).
+public struct ProjectNvrsion: Sendable, Codable, Equatable {
+    /// Master switch for the mode. Default off (Beta, opt-in).
+    public var enabled: Bool
+    /// The shared trunk branch all the project's nvrsion sessions edit and land into.
+    public var trunkBranch: String
+    /// Optional fast validation command run after an edit is written and **before** it lands in
+    /// trunk (NVRSION §5). Receives the edited paths; non-zero exit rejects the edit back to the
+    /// agent (kept warm, not committed). `nil`/empty → land immediately (the default).
+    public var prelandHook: String?
+    /// Keep-warm idle window in seconds (NVRSION §4): a held file untouched this long is released
+    /// mid-turn so a waiter can take it. Lower = faster hand-off, more re-reads.
+    public var keepWarmIdleSeconds: Int
+
+    public static let defaultTrunkBranch = "nucleic/trunk"
+    public static let defaultKeepWarmIdleSeconds = 4
+
+    public init(
+        enabled: Bool = false,
+        trunkBranch: String = ProjectNvrsion.defaultTrunkBranch,
+        prelandHook: String? = nil,
+        keepWarmIdleSeconds: Int = ProjectNvrsion.defaultKeepWarmIdleSeconds
+    ) {
+        self.enabled = enabled
+        self.trunkBranch = trunkBranch
+        self.prelandHook = prelandHook
+        self.keepWarmIdleSeconds = keepWarmIdleSeconds
+    }
+
+    // Tolerant decode: rows persisted before a field existed decode to its default rather than
+    // failing the whole blob (the store decodes with `try?`, so a strict miss drops the config).
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        enabled = try c.decodeIfPresent(Bool.self, forKey: .enabled) ?? false
+        trunkBranch =
+            try c.decodeIfPresent(String.self, forKey: .trunkBranch).flatMap {
+                $0.trimmingCharacters(in: .whitespaces).isEmpty ? nil : $0
+            } ?? ProjectNvrsion.defaultTrunkBranch
+        prelandHook = try c.decodeIfPresent(String.self, forKey: .prelandHook)
+        keepWarmIdleSeconds =
+            try c.decodeIfPresent(Int.self, forKey: .keepWarmIdleSeconds)
+            ?? ProjectNvrsion.defaultKeepWarmIdleSeconds
+    }
+
+    /// The pre-land hook to actually run, or `nil` when unset/blank (→ land immediately).
+    public var resolvedPrelandHook: String? {
+        guard let h = prelandHook?.trimmingCharacters(in: .whitespaces), !h.isEmpty else { return nil }
+        return h
+    }
+}
+
 /// App-wide container preferences, persisted in `UserDefaults`. These gate and seed the
 /// *per-project* `ProjectSandbox` config above — they never sandbox sessions on their own.
 /// Surfaced in Settings → General; read here so `NucleicCore` (e.g. `SessionController`,
@@ -419,6 +477,9 @@ public struct Project: Identifiable, Sendable, Codable, Equatable {
     public var setupPolicy: SetupPolicy
     /// Execution-sandbox settings. `nil` → sessions run on the host (default).
     public var sandbox: ProjectSandbox?
+    /// nvrsion (Beta) settings. `nil`/`enabled == false` → classic per-session-worktree behavior
+    /// (the default). See `nvrsionActive` for the full gate (NVRSION §10).
+    public var nvrsion: ProjectNvrsion?
     public var createdAt: Date
     /// When the project was archived, or `nil` if it's active. Archiving hides the project
     /// from the active list and stops its live sessions, but leaves all files and records in
@@ -436,6 +497,7 @@ public struct Project: Identifiable, Sendable, Codable, Equatable {
         setupScript: String? = nil,
         setupPolicy: SetupPolicy = .block,
         sandbox: ProjectSandbox? = nil,
+        nvrsion: ProjectNvrsion? = nil,
         createdAt: Date = Date(),
         archivedAt: Date? = nil
     ) {
@@ -449,6 +511,7 @@ public struct Project: Identifiable, Sendable, Codable, Equatable {
         self.setupScript = setupScript
         self.setupPolicy = setupPolicy
         self.sandbox = sandbox
+        self.nvrsion = nvrsion
         self.createdAt = createdAt
         self.archivedAt = archivedAt
     }
@@ -495,6 +558,22 @@ public struct Project: Identifiable, Sendable, Codable, Equatable {
         isNucleicControlled && !(effectiveSandbox?.perSessionContainers ?? false)
     }
 
+    /// Whether **nvrsion** (Beta) governs this project's sessions — the single gate both the spawn
+    /// path and teardown read so they can't drift (NVRSION §10). Requires a Nucleic Control project,
+    /// the mode enabled, and the shared control container (v0 doesn't support per-session
+    /// containers). Like `effectiveSandbox` it stays subordinate to the app-wide container-service
+    /// master switch, which callers check first.
+    public var nvrsionActive: Bool {
+        isNucleicControlled && (nvrsion?.enabled ?? false) && usesSharedControlContainer
+    }
+
+    /// Host path of the shared nvrsion trunk checkout: `<repoRoot>/.nucleic/trunk` — kept inside the
+    /// project under `.nucleic/` (git-excluded) on the same volume, beside the worktrees dir.
+    public var resolvedTrunkPath: String {
+        let nucleicDir = (rootPath as NSString).appendingPathComponent(".nucleic")
+        return (nucleicDir as NSString).appendingPathComponent("trunk")
+    }
+
     /// `<repoSlug>` used in the worktree path and branch derivation.
     public var repoSlug: String {
         let last = (rootPath as NSString).lastPathComponent

Tests/NucleicCoreTests/AppStoreTests.swift

@@ -177,6 +177,166 @@ struct AppStoreTests {
                 .appendingPathComponent(".nucleic/worktrees/make-a-file/made.txt")))
     }
 
+    // MARK: - nvrsion (NVRSION) — shared-trunk mode, end to end
+
+    /// Turn a control project into an nvrsion project and return the refreshed `Project`.
+    private func enableNvrsion(_ store: AppStore, _ project: Project) async -> Project {
+        var p = project
+        p.nvrsion = ProjectNvrsion(enabled: true)
+        await store.updateProject(p)
+        return store.project(project.id) ?? p
+    }
+
+    @Test func nvrsionLandsEditOnTrunkAndMakesNoPerSessionWorktree() async throws {
+        let repo = try await GitTestRepo(controlled: true)  // nvrsion is Control-only (NVRSION §10)
+        defer { repo.cleanup() }
+        let store = makeStore(repo: repo)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        let project = await enableNvrsion(store, created)
+        #expect(project.nvrsionActive)
+
+        let session = try await store.createSession(in: project, title: "make a file", prompt: "go")
+        store.openSessionID = session
+        await store.awaitOpenSessionSettled()
+
+        let trunkPath = project.resolvedTrunkPath
+        // The scripted edit (made.txt) landed on `nucleic/trunk` as a path-scoped, attributed commit.
+        let names = try await repo.run(["show", "--name-only", "--format=", "HEAD"], in: trunkPath).stdout
+        #expect(names.contains("made.txt"))
+        let body = try await repo.run(["log", "-1", "--format=%B", "HEAD"], in: trunkPath).stdout
+        #expect(body.contains("Nucleic-Session: \(session.rawValue)"))
+        // No isolated per-session worktree/branch — only the shared trunk branch exists.
+        let branches = try await repo.run(["branch", "--list"]).stdout
+        #expect(branches.contains("nucleic/trunk"))
+        #expect(!branches.contains("make-a-file"))
+        // And no per-session worktree directory was created under .nucleic/worktrees.
+        #expect(!FileManager.default.fileExists(
+            atPath: (repo.root as NSString).appendingPathComponent(".nucleic/worktrees/make-a-file")))
+    }
+
+    @Test func nvrsionSessionsShareTheOneTrunkLockDomain() async throws {
+        let repo = try await GitTestRepo(controlled: true)
+        defer { repo.cleanup() }
+        let store = makeStore(repo: repo)
+        store.lockReconcileInterval = .milliseconds(20)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        let project = await enableNvrsion(store, created)
+
+        let a = try await store.createSession(in: project, title: "alpha", prompt: "go")
+        let b = try await store.createSession(in: project, title: "bravo", prompt: "go")
+        await waitFor {
+            store.summaries.first { $0.id == a }?.status == .awaitingInput
+                && store.summaries.first { $0.id == b }?.status == .awaitingInput
+        }
+
+        // A acquires shared.txt. Because every nvrsion session shares ONE lock domain (the trunk),
+        // B asking for the same file must queue — not proceed independently.
+        #expect(await store.arbitrate(sessionID: a, task: "edit", files: ["shared.txt"]).resolution == .proceed)
+        let arbitration = Task { await store.arbitrate(sessionID: b, task: "edit", files: ["shared.txt"]) }
+        await waitFor { store.sessionsWaitingForAccess.contains(b) }
+        #expect(store.sessionsWaitingForAccess.contains(b))
+
+        // Releasing A grants B — proving they contended in the same domain.
+        await store.forceReleaseLocks(a)
+        #expect(await arbitration.value.resolution == .proceed)
+    }
+
+    @Test func nvrsionKeepWarmSweepReleasesAnIdleHeldLock() async throws {
+        let repo = try await GitTestRepo(controlled: true)
+        defer { repo.cleanup() }
+        let clock = MutableClock(Date(timeIntervalSince1970: 1_700_000_000))
+        let store = makeStore(repo: repo, now: clock.now)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        let project = await enableNvrsion(store, created)
+
+        // A session that doesn't run (empty prompt) — so no turn-end clears the warm set under us.
+        let a = try await store.createSession(in: project, title: "alpha", prompt: "")
+        // It holds shared.txt (acquired via arbitrate); mark it warm with a 1s window, as a land would.
+        #expect(await store.arbitrate(sessionID: a, task: "edit", files: ["shared.txt"]).resolution == .proceed)
+        await store.nvrsionGovernor.warmed(a, "shared.txt", idleSeconds: 1)
+
+        // Before the window elapses, the sweep keeps the lock held (keep-warm).
+        #expect(await store.runNvrsionSweep() == false)
+        let held = await store.lockQueueSnapshot()
+        #expect(held.files.contains { $0.path == "shared.txt" && $0.holders.contains { $0.sessionID == a } })
+
+        // Past the window, the sweep releases it without waiting for the turn to end (NVRSION §4).
+        clock.advance(2)
+        #expect(await store.runNvrsionSweep() == true)
+        let freed = await store.lockQueueSnapshot()
+        #expect(!freed.files.contains { $0.path == "shared.txt" })
+    }
+
+    @Test func nvrsionPromoteShipsTrunkWorkToTheRealBranch() async throws {
+        let repo = try await GitTestRepo(controlled: true)
+        defer { repo.cleanup() }
+        let store = makeStore(repo: repo)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        let project = await enableNvrsion(store, created)
+
+        // A scripted session lands made.txt on the trunk.
+        let session = try await store.createSession(in: project, title: "alpha", prompt: "go")
+        store.openSessionID = session
+        await store.awaitOpenSessionSettled()
+
+        let mainBefore = try await repo.revParse("refs/heads/main")
+        // Promote → the real branch (main) gets the trunk's work as one squashed commit.
+        #expect(await store.promoteNvrsionTrunk(project.id) == true)
+        #expect(try await repo.revParse("refs/heads/main") != mainBefore)
+        #expect(repo.read("made.txt", in: repo.root) == "by agent\n")
+
+        // Nothing new on the trunk now → a second promote reports nothing-to-promote.
+        #expect(await store.promoteNvrsionTrunk(project.id) == false)
+        #expect(store.lastError?.contains("Nothing on the nvrsion trunk") == true)
+    }
+
+    @Test func nvrsionPrelandHookRejectsAnEditFromLanding() async throws {
+        let repo = try await GitTestRepo(controlled: true)
+        defer { repo.cleanup() }
+        let store = makeStore(repo: repo)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        // Enable nvrsion with a pre-land hook that always fails.
+        var p = created
+        p.nvrsion = ProjectNvrsion(enabled: true, prelandHook: "exit 1")
+        await store.updateProject(p)
+        let project = try #require(store.project(created.id))
+        #expect(project.nvrsionActive)
+
+        let session = try await store.createSession(in: project, title: "alpha", prompt: "go")
+        store.openSessionID = session
+        await store.awaitOpenSessionSettled()
+
+        // The scripted edit was rejected by the hook, so it never landed on the trunk.
+        let trunkPath = project.resolvedTrunkPath
+        let inTrunk = try await repo.run(["cat-file", "-e", "HEAD:made.txt"], in: trunkPath)
+        #expect(inTrunk.status != 0)  // made.txt is not in the trunk's committed tree
+        // And a rejection note was posted.
+        #expect(store.openTranscript.contains {
+            if case .note(let n) = $0.kind { return n.text.contains("pre-land check rejected") }
+            return false
+        })
+    }
+
+    @Test func nvrsionFlipIsRefusedWhileAChatIsLive() async throws {
+        let repo = try await GitTestRepo(controlled: true)
+        defer { repo.cleanup() }
+        let store = makeStore(repo: repo)
+        let created = try #require(await store.addProject(name: "demo", rootPath: repo.root, defaultBranch: "main"))
+        let project = await enableNvrsion(store, created)  // enabled with no live chats — allowed
+        #expect(project.nvrsionActive)
+
+        // A non-terminal chat now exists (the scripted run settles it at awaitingInput).
+        let session = try await store.createSession(in: project, title: "alpha", prompt: "go")
+        await waitFor { store.summaries.first { $0.id == session }?.status == .awaitingInput }
+
+        // Turning nvrsion OFF is refused while the chat is live — the project stays nvrsion-active.
+        var off = project
+        off.nvrsion = ProjectNvrsion(enabled: false)
+        await store.updateProject(off)
+        #expect(store.project(project.id)?.nvrsionActive == true)
+        #expect(store.lastError?.contains("nvrsion") == true)
+    }
+
     @Test func archivedWorktreeCleanupReclaimsPastThresholdThenRestoresOnUnarchive() async throws {
         let repo = try await GitTestRepo()
         defer { repo.cleanup() }

Tests/NucleicCoreTests/GRDBMetadataStoreTests.swift

@@ -32,6 +32,60 @@ struct GRDBMetadataStoreTests {
         #expect(loaded == [project])
     }
 
+    @Test func nvrsionConfigRoundTrips() async throws {
+        let store = try GRDBMetadataStore(path: nil)
+        // Default project: no nvrsion config → nil (off).
+        let plain = makeProject()
+        try await store.saveProject(plain)
+        #expect(try await store.loadProjects().first(where: { $0.id == plain.id })?.nvrsion == nil)
+
+        // Project with an explicit nvrsion config round-trips every field (v20).
+        var project = makeProject()
+        project.nvrsion = ProjectNvrsion(
+            enabled: true, trunkBranch: "nucleic/trunk", prelandHook: "nvrsion-check",
+            keepWarmIdleSeconds: 9)
+        try await store.saveProject(project)
+        let loaded = try await store.loadProjects().first(where: { $0.id == project.id })?.nvrsion
+        #expect(loaded == ProjectNvrsion(
+            enabled: true, trunkBranch: "nucleic/trunk", prelandHook: "nvrsion-check",
+            keepWarmIdleSeconds: 9))
+
+        // A blank pre-land hook decodes back to nil (→ land immediately), and a missing
+        // trunk-branch falls back to the default — the tolerant decode (NVRSION §10).
+        let blankHook = #"{"enabled":true,"prelandHook":"  ","keepWarmIdleSeconds":2}"#
+        let decoded = try JSONDecoder().decode(ProjectNvrsion.self, from: Data(blankHook.utf8))
+        #expect(decoded.resolvedPrelandHook == nil)
+        #expect(decoded.trunkBranch == ProjectNvrsion.defaultTrunkBranch)
+    }
+
+    @Test func nvrsionActiveGate() {
+        // A control-located repo with nvrsion on and the shared container → active.
+        let controlPath = (ProjectCloner.controlBase as NSString).appendingPathComponent("demo")
+        var control = Project(
+            id: .generate(), name: "demo", rootPath: controlPath, defaultBranch: "main",
+            nvrsion: ProjectNvrsion(enabled: true), createdAt: now)
+        #expect(control.isNucleicControlled)
+        #expect(control.usesSharedControlContainer)
+        #expect(control.nvrsionActive)
+
+        // Disabled → not active.
+        control.nvrsion = ProjectNvrsion(enabled: false)
+        #expect(!control.nvrsionActive)
+
+        // Enabled but per-session containers (no shared container) → not active in v0.
+        control.nvrsion = ProjectNvrsion(enabled: true)
+        control.sandbox = ProjectSandbox(enabled: true, perSessionContainers: true)
+        #expect(!control.usesSharedControlContainer)
+        #expect(!control.nvrsionActive)
+
+        // A non-control repo is never nvrsion-active, even with the flag on.
+        let outside = Project(
+            id: .generate(), name: "demo", rootPath: "/repos/demo", defaultBranch: "main",
+            nvrsion: ProjectNvrsion(enabled: true), createdAt: now)
+        #expect(!outside.isNucleicControlled)
+        #expect(!outside.nvrsionActive)
+    }
+
     @Test func shipDestinationResolutionPrecedence() {
         var project = makeProject()  // defaultBranch == "main", no autoship override
         var session = makeSession(projectID: project.id)

Tests/NucleicCoreTests/NvrsionReleaseGovernorTests.swift

@@ -0,0 +1,93 @@
+import Foundation
+import Testing
+
+@testable import NucleicCore
+
+/// A clock the test advances by hand, so keep-warm eviction (which is pure timekeeping) is
+/// deterministic without real sleeps. Thread-safe — the governor reads it from an actor.
+final class MutableClock: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _date: Date
+    init(_ date: Date = Date(timeIntervalSince1970: 1_000_000)) { _date = date }
+    var date: Date { lock.withLock { _date } }
+    func advance(_ seconds: TimeInterval) { lock.withLock { _date = _date.addingTimeInterval(seconds) } }
+    var now: @Sendable () -> Date { { [self] in date } }
+}
+
+@Suite("NvrsionReleaseGovernor — keep-warm eviction (NVRSION §4)")
+struct NvrsionReleaseGovernorTests {
+    @Test func keepsAFileUntilIdlePastWindowThenSweepsIt() async throws {
+        let clock = MutableClock()
+        let gov = NvrsionReleaseGovernor(now: clock.now)
+        let s = SessionID.generate()
+        await gov.warmed(s, "a.txt", idleSeconds: 4)
+
+        // Before the window: held — the sweep returns nothing and the file stays warm.
+        clock.advance(3)
+        #expect(await gov.sweep().isEmpty)
+        #expect(await gov.warmPaths(s) == ["a.txt"])
+
+        // Past the window: swept and dropped.
+        clock.advance(2)  // 5 ≥ 4
+        let swept = await gov.sweep()
+        #expect(swept.count == 1)
+        #expect(swept.first?.session == s)
+        #expect(swept.first?.paths == ["a.txt"])
+        #expect(await gov.isEmpty)
+    }
+
+    @Test func reLandingRefreshesTheIdleClock() async throws {
+        let clock = MutableClock()
+        let gov = NvrsionReleaseGovernor(now: clock.now)
+        let s = SessionID.generate()
+        await gov.warmed(s, "a.txt", idleSeconds: 4)
+        clock.advance(3)
+        await gov.warmed(s, "a.txt", idleSeconds: 4)  // active edit refreshes the clock
+
+        clock.advance(2)  // only 2 since the refresh
+        #expect(await gov.sweep().isEmpty)  // still held — active work protected
+        clock.advance(3)  // now 5 since the refresh
+        #expect(await gov.sweep().first?.paths == ["a.txt"])
+    }
+
+    @Test func forgetDropsEverythingForASession() async throws {
+        let clock = MutableClock()
+        let gov = NvrsionReleaseGovernor(now: clock.now)
+        let s = SessionID.generate()
+        await gov.warmed(s, "a.txt", idleSeconds: 4)
+        await gov.warmed(s, "b.txt", idleSeconds: 4)
+        await gov.forget(s)  // turn-end / lifecycle
+        #expect(await gov.isEmpty)
+        clock.advance(100)
+        #expect(await gov.sweep().isEmpty)
+    }
+
+    @Test func sweepsIdleFilesButKeepsActiveOnes() async throws {
+        let clock = MutableClock()
+        let gov = NvrsionReleaseGovernor(now: clock.now)
+        let s = SessionID.generate()
+        await gov.warmed(s, "old.txt", idleSeconds: 2)
+        clock.advance(1)
+        await gov.warmed(s, "new.txt", idleSeconds: 2)  // landed 1s after old
+
+        clock.advance(1.5)  // old: 2.5 ≥ 2 (due);  new: 1.5 < 2 (kept)
+        let swept = await gov.sweep()
+        #expect(swept.first?.paths == ["old.txt"])
+        #expect(await gov.warmPaths(s) == ["new.txt"])
+    }
+
+    @Test func differentSessionsAreSweptIndependently() async throws {
+        let clock = MutableClock()
+        let gov = NvrsionReleaseGovernor(now: clock.now)
+        let a = SessionID.generate()
+        let b = SessionID.generate()
+        await gov.warmed(a, "x", idleSeconds: 2)
+        clock.advance(3)
+        await gov.warmed(b, "y", idleSeconds: 2)  // b is fresh
+
+        let swept = await gov.sweep()
+        #expect(swept.count == 1)
+        #expect(swept.first?.session == a)
+        #expect(await gov.warmPaths(b) == ["y"])  // b kept
+    }
+}

Tests/NucleicCoreTests/NvrsionTrunkTests.swift

@@ -0,0 +1,238 @@
+import Foundation
+import Testing
+
+@testable import NucleicCore
+
+@Suite("NvrsionTrunk — real git on temp repos (NVRSION §2–3)")
+struct NvrsionTrunkTests {
+    let trunkBranch = "nucleic/trunk"
+
+    /// Create a repo + ensure its trunk; returns (repo, trunk, trunkPath).
+    func makeTrunk() async throws -> (GitTestRepo, NvrsionTrunk, String) {
+        let repo = try await GitTestRepo()
+        let trunk = NvrsionTrunk()
+        let trunkPath = repo.project().resolvedTrunkPath
+        try await trunk.ensureTrunk(
+            root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main")
+        return (repo, trunk, trunkPath)
+    }
+
+    @Test func ensureTrunkCreatesWorktreeOnBranchOffBase() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+
+        #expect(FileManager.default.fileExists(atPath: trunkPath))
+        // The trunk branch exists and starts at the base (main) HEAD.
+        let mainHead = try await repo.revParse("HEAD")
+        let trunkHead = try await repo.revParse("refs/heads/\(trunkBranch)")
+        #expect(trunkHead == mainHead)
+        // The checkout in the trunk dir is on the trunk branch.
+        let onBranch = try await repo.run(["rev-parse", "--abbrev-ref", "HEAD"], in: trunkPath).stdout
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        #expect(onBranch == trunkBranch)
+
+        // Idempotent: a second ensure is a no-op and doesn't throw.
+        try await trunk.ensureTrunk(
+            root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main")
+        #expect(try await repo.revParse("refs/heads/\(trunkBranch)") == trunkHead)
+    }
+
+    @Test func landsEditAsScopedCommitWithTrailer() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let session = SessionID.generate()
+
+        // Agent "writes" a new file into the shared trunk dir; the host lands it.
+        try repo.write("src/a.swift", "let a = 1\n", in: trunkPath)
+        let before = try await repo.revParse("refs/heads/\(trunkBranch)")
+        let result = await trunk.land(
+            trunkPath: trunkPath, session: session, paths: ["src/a.swift"], message: "add a")
+
+        guard case .landed = result else { Issue.record("expected .landed, got \(result)"); return }
+        let after = try await repo.revParse("refs/heads/\(trunkBranch)")
+        #expect(after != before)  // trunk advanced
+        // The file is committed on the trunk branch...
+        let names = try await repo.run(["show", "--name-only", "--format=", "HEAD"], in: trunkPath).stdout
+        #expect(names.contains("src/a.swift"))
+        // ...with the session attribution trailer (NVRSION §3).
+        let body = try await repo.run(["log", "-1", "--format=%B", "HEAD"], in: trunkPath).stdout
+        #expect(body.contains("Nucleic-Session: \(session.rawValue)"))
+    }
+
+    @Test func landIsPathScopedAndDoesNotSweepOtherSessionsFiles() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let a = SessionID.generate()
+        let b = SessionID.generate()
+
+        // Both sessions have in-flight writes in the one shared trunk dir at once.
+        try repo.write("a.txt", "from A\n", in: trunkPath)
+        try repo.write("b.txt", "from B\n", in: trunkPath)
+
+        // A lands only a.txt — the commit must contain a.txt and NOT b.txt (b stays uncommitted).
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: a, paths: ["a.txt"], message: "A") else {
+            Issue.record("A land failed"); return
+        }
+        let firstNames = try await repo.run(["show", "--name-only", "--format=", "HEAD"], in: trunkPath).stdout
+        #expect(firstNames.contains("a.txt"))
+        #expect(!firstNames.contains("b.txt"))
+
+        // B then lands b.txt as its own commit.
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: b, paths: ["b.txt"], message: "B") else {
+            Issue.record("B land failed"); return
+        }
+        let secondNames = try await repo.run(["show", "--name-only", "--format=", "HEAD"], in: trunkPath).stdout
+        #expect(secondNames.contains("b.txt"))
+        #expect(!secondNames.contains("a.txt"))
+        // Both files now live in the trunk tree.
+        #expect(repo.read("a.txt", in: trunkPath) == "from A\n")
+        #expect(repo.read("b.txt", in: trunkPath) == "from B\n")
+    }
+
+    @Test func landIsNoopWhenContentUnchanged() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let session = SessionID.generate()
+
+        try repo.write("c.txt", "v1\n", in: trunkPath)
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: session, paths: ["c.txt"], message: "c") else {
+            Issue.record("first land failed"); return
+        }
+        // Landing again with identical content commits nothing.
+        let again = await trunk.land(
+            trunkPath: trunkPath, session: session, paths: ["c.txt"], message: "c again")
+        #expect(again == .noop)
+    }
+
+    @Test func prelandHookGatesTheCommit() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let s = SessionID.generate()
+
+        // A failing hook rejects the edit: nothing is committed and the file stays on disk.
+        try repo.write("gated.txt", "v1\n", in: trunkPath)
+        let before = try await repo.revParse("refs/heads/\(trunkBranch)")
+        let rejected = await trunk.land(
+            trunkPath: trunkPath, session: s, paths: ["gated.txt"], message: "g", prelandHook: "exit 1")
+        guard case .rejected = rejected else { Issue.record("expected .rejected, got \(rejected)"); return }
+        #expect(try await repo.revParse("refs/heads/\(trunkBranch)") == before)  // trunk unchanged
+        let dirty = try await repo.run(["status", "--porcelain"], in: trunkPath).stdout
+        #expect(dirty.contains("gated.txt"))  // the agent's work is still on disk, not lost
+
+        // A passing hook lets the same edit land.
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: s, paths: ["gated.txt"], message: "g", prelandHook: "exit 0") else {
+            Issue.record("expected .landed after passing hook"); return
+        }
+        #expect(try await repo.revParse("refs/heads/\(trunkBranch)") != before)
+    }
+
+    @Test func prelandHookReceivesEditedPaths() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let s = SessionID.generate()
+        try repo.write("p.txt", "x\n", in: trunkPath)
+        // The hook passes only when NUCLEIC_NVR_PATHS carries the edited path.
+        let result = await trunk.land(
+            trunkPath: trunkPath, session: s, paths: ["p.txt"], message: "p",
+            prelandHook: #"[ "$NUCLEIC_NVR_PATHS" = "p.txt" ]"#)
+        guard case .landed = result else { Issue.record("expected .landed, got \(result)"); return }
+    }
+
+    @Test func promoteSquashesTrunkIntoBase() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+
+        // Two sessions land work on the trunk.
+        try repo.write("a.txt", "from A\n", in: trunkPath)
+        _ = await trunk.land(trunkPath: trunkPath, session: .generate(), paths: ["a.txt"], message: "A")
+        try repo.write("b.txt", "from B\n", in: trunkPath)
+        _ = await trunk.land(trunkPath: trunkPath, session: .generate(), paths: ["b.txt"], message: "B")
+
+        let baseBefore = try await repo.revParse("refs/heads/main")
+        let result = await trunk.promote(
+            root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main",
+            message: "promote")
+        guard case .promoted = result else { Issue.record("expected .promoted, got \(result)"); return }
+
+        // The real branch (main, checked out at root) advanced and now carries both files.
+        #expect(try await repo.revParse("refs/heads/main") != baseBefore)
+        #expect(repo.read("a.txt", in: repo.root) == "from A\n")
+        #expect(repo.read("b.txt", in: repo.root) == "from B\n")
+        let body = try await repo.run(["log", "-1", "--format=%B", "main"]).stdout
+        #expect(body.contains("Nucleic-Promote: 1"))
+
+        // Re-promoting with no new trunk work is a no-op (trunk was resynced onto the new base).
+        #expect(await trunk.promote(
+            root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main",
+            message: "promote again") == .nothingToPromote)
+    }
+
+    @Test func promoteIsNothingWhenTrunkMatchesBase() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        // Fresh trunk == base → nothing to promote.
+        #expect(await trunk.promote(
+            root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main",
+            message: "promote") == .nothingToPromote)
+    }
+
+    @Test func recoverCommitsDirtyTrunkResidueOnLaunch() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+
+        // Simulate a crash mid-edit: a file written into the trunk but never committed.
+        try repo.write("half.swift", "// written, never landed\n", in: trunkPath)
+        let before = try await repo.revParse("refs/heads/\(trunkBranch)")
+
+        await trunk.recover(root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main")
+
+        // The residue is now committed (a recovery commit), so the trunk is clean.
+        let status = try await repo.run(["status", "--porcelain"], in: trunkPath).stdout
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        #expect(status.isEmpty)
+        let after = try await repo.revParse("refs/heads/\(trunkBranch)")
+        #expect(after != before)
+        let body = try await repo.run(["log", "-1", "--format=%B", "HEAD"], in: trunkPath).stdout
+        #expect(body.contains("recovered uncommitted work"))
+        #expect(body.contains("Nucleic-Recovery: 1"))
+
+        // Idempotent: a second recovery on a clean trunk commits nothing.
+        await trunk.recover(root: repo.root, trunkPath: trunkPath, trunkBranch: trunkBranch, base: "main")
+        #expect(try await repo.revParse("refs/heads/\(trunkBranch)") == after)
+    }
+
+    @Test func regroundFiresOnlyAfterAFileMovesUnderASession() async throws {
+        let (repo, trunk, trunkPath) = try await makeTrunk()
+        defer { repo.cleanup() }
+        let a = SessionID.generate()
+        let b = SessionID.generate()
+
+        // A lands x.txt.
+        try repo.write("x.txt", "one\n", in: trunkPath)
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: a, paths: ["x.txt"], message: "x1") else {
+            Issue.record("A land failed"); return
+        }
+
+        // B's FIRST acquaintance with x.txt is clean (matches LOCKING §4.5: re-ground only when a
+        // file the session already had advances). It now records B has seen the current content.
+        #expect(await trunk.regroundOnGrant(trunkPath: trunkPath, session: b, files: ["x.txt"]) == .clean)
+
+        // A changes x.txt under B.
+        try repo.write("x.txt", "two\n", in: trunkPath)
+        guard case .landed = await trunk.land(
+            trunkPath: trunkPath, session: a, paths: ["x.txt"], message: "x2") else {
+            Issue.record("A reland failed"); return
+        }
+
+        // Now B is granted x.txt again → it moved since B last saw it → re-ground.
+        let moved = await trunk.regroundOnGrant(trunkPath: trunkPath, session: b, files: ["x.txt"])
+        #expect(moved == .changed(files: ["x.txt"], diff: ""))
+        // And once B has re-read (state updated), a further grant with no movement is clean again.
+        #expect(await trunk.regroundOnGrant(trunkPath: trunkPath, session: b, files: ["x.txt"]) == .clean)
+    }
+}

docs/NVRSION.md

@@ -0,0 +1,463 @@
+# nvrsion — a version manager for multi-agent orchestration (v0, Beta)
+
+A per-file, per-edit version-control mode for Nucleic Control projects. Where git (and today's
+Nucleic locking) is built for slow human coworkers who fork an isolated branch/worktree and merge a
+big batch of work back hours later, **nvrsion** is built for fast agents: a session locks a *single
+file* for the duration of *one edit*, the edit lands in a shared **trunk** the instant it completes,
+and the lock releases immediately so the next agent can take the file and re-read it.
+
+It is a *mode*, not a rewrite: it builds directly on the existing `LockManager` acquire path and the
+shared control container. It is **opt-in per project, default off, Beta, and Nucleic-Control-only**.
+
+**Status:** design draft (2026-06-25). Amends [[LOCKING.md]] (a control project with nvrsion on
+takes the trunk path instead of the worktree-per-session path) and WORKTREE_MANAGER (nvrsion sessions
+create *no* per-session worktree). Git plumbing is spelled out so it's reviewable; the Swift surface
+(§12) is the stable contract.
+
+---
+
+## 0. Problem & motivation
+
+### 0.1 The lock-hold window is too long
+
+Today a session = an isolated worktree + branch forked at an immutable `baseSHA`. A file's lock is
+acquired at the session's first edit and **held until the session's whole branch lands in its parent**
+(autoship merge, or a mediated/agent merge detected by the git interceptor). See LOCKING §4.4. That is
+correct and leak-free, but the *hold window is the entire session*: a second agent that needs the same
+file waits for the first agent to finish **all** its edits and ship.
+
+That window is sized for humans. A human holds a file for an afternoon, so isolation (a private
+worktree) and batch merge (one review-able PR) are the right trade. Agents edit a file in seconds.
+Making a second agent wait an entire session to touch one file — when the first agent touched it once,
+early, and moved on — is the slowness this targets.
+
+### 0.2 The git model carries weight nvrsion doesn't need
+
+The per-session worktree exists to give each agent an isolated copy that can diverge and be merged.
+But if the lock already guarantees **no two sessions edit a file at once** (LOCKING §2.2), and a granted
+session is forced to **re-ground on the latest content before it edits** (the existing
+`grantedNeedsReground` handshake, [LockManager.swift:262](../Sources/NucleicCore/LockManager.swift)),
+then for the locked file *there is never any divergence to merge*. The isolated copy, the fork point,
+the per-session branch, the nested-worktree cascade (LOCKING §5), and the conflict-resolution flow are
+all machinery for a divergence that, under a per-file lock + re-ground, **cannot occur**.
+
+### 0.3 The core bet
+
+> Serialize writes per file (already done) + force re-ground before each edit (already done) ⇒
+> textual merge conflicts within the trunk are **structurally impossible**, so "merge" collapses to
+> "commit," and the lock need only be held for one edit.
+
+The cost is the loss of the isolation buffer: a half-written or broken edit is visible to every other
+agent the instant it lands (classic trunk-based development). That trade is accepted for v0; an
+optional fast **pre-land validation hook** (§5) is the safety valve.
+
+### 0.4 Design decisions (from review, 2026-06-25)
+
+| Question | Decision |
+| --- | --- |
+| What is "trunk," and how does work reach the user's real branch? | **A dedicated `nucleic/trunk` branch** shared by all nvrsion sessions. Edits land there instantly; trunk is **promoted to the project's real base only at ship** (§6). A bad edit never touches the real branch directly. |
+| Lock hold duration? | **Keep-warm within a turn** (§4). A file's edit lands in trunk immediately (others can *read* the latest), but the lock is *held* across the agent's consecutive edits to that file and released on turn-end / file-switch / a short idle — so a sibling can't interleave between two edits of one logical change. |
+| Any gate before an edit lands in trunk? | **Optional fast pre-land hook** (§5), per project, default empty. Truly immediate when unset. |
+| Opt-in surface? | **Per-project toggle, default OFF, Beta-labeled, Nucleic-Control-only**, and further requires the shared control container (`usesSharedControlContainer`). |
+| Where is the shared trunk on disk? | One checkout at `<repo>/.nucleic/trunk`, on branch `nucleic/trunk`, **bind-mounted RW into the shared control container** that all the project's sessions already share. No per-session worktree. |
+| Who performs the commit? | **The host**, via the `GitWorktreeManager` actor, scoped per edit (`git commit -- <paths>`), serialized. The agent writes the file (its container write *is* the host file, via virtiofs); Nucleic commits and releases. Host-mediated commit = a **certain, immediate** release signal — no detection poll needed. |
+| Concurrent edits to the same file? | Impossible by the lock. Concurrent edits to *different* files share one trunk index, so commits are **path-scoped and serialized** through the actor; disjoint edits never collide. |
+
+---
+
+## 1. Invariants
+
+1. **One trunk per project, shared by all nvrsion sessions.** Branch `nucleic/trunk`, one checkout,
+   one index. The trunk is the only working copy — there is **no per-session worktree, no per-session
+   branch, no fork-point (`baseSHA`)**.
+2. **An edit lands the instant it completes.** On the edit-completion signal, Nucleic commits exactly
+   the edited paths to `nucleic/trunk` (host-mediated, path-scoped). Trunk always reflects every
+   *completed* edit.
+3. **A lock is held for an edit, kept warm for a turn.** Acquired before an edit; retained across the
+   agent's consecutive edits to that file; released on turn-end, file-switch, or short idle (§4) —
+   never held to session-ship as today.
+4. **No two sessions edit a file at once; the granted session always re-grounds.** The `LockManager`
+   exclusion (LOCKING §2.2) and the `grantedNeedsReground` handshake are unchanged and are what make
+   trunk conflicts structurally impossible (§0.3).
+5. **Trunk reaches the real branch only by promotion.** The project's actual base branch changes only
+   when trunk is **promoted** (§6) — an explicit action or autoship-on-completion — never as a side
+   effect of an edit.
+6. **Survivable.** At most one edit's worth of work is ever uncommitted (invariant 2). A small
+   persisted `nvr_file_state` (§8) plus a launch reconcile rebuild lock state and never strand a file.
+7. **Fail toward progress.** A failed pre-land hook (§5) rejects *that edit* back to the agent (it
+   does not land, the lock stays warm, the agent fixes and re-issues) — it never wedges the trunk or
+   the queue.
+
+---
+
+## 2. Topology — shared trunk in the shared container
+
+A Nucleic Control project already runs **all its sessions in one shared container** with the whole
+control base bind-mounted read-write
+([Project.swift:494](../Sources/NucleicCore/Project.swift), `usesSharedControlContainer`;
+[SessionController.swift:284](../Sources/NucleicCore/SessionController.swift)). nvrsion reuses exactly
+this — it does **not** introduce a new container or mount model.
+
+```
+~/.nucleic/control/<repo>/                         (the control base, RW-mounted into the
+  ├── .git/                                          shared "nucleic-control" container)
+  ├── .nucleic/
+  │     ├── worktrees/<slug>/   ← per-session worktrees  (NON-nvrsion sessions, unchanged)
+  │     └── trunk/              ← THE shared nvrsion checkout, branch `nucleic/trunk`
+  └── <project files>           ← the real base branch checkout (e.g. dev)
+
+nvrsion session A ─┐
+nvrsion session B ─┼─ all CWD = .nucleic/trunk, all editing one working copy on `nucleic/trunk`
+nvrsion session C ─┘
+```
+
+- **`createSession` for an nvrsion project skips worktree creation** and points the session's
+  `worktreePath` at the shared `.nucleic/trunk` (created lazily on the project's first nvrsion
+  session via `git worktree add .nucleic/trunk -b nucleic/trunk <defaultBranch>`).
+- The trunk dir is host-side under `.nucleic/` (git-excluded), so the **host runs git on it directly**
+  — commits don't depend on the in-container interceptor (though the interceptor still reports any git
+  the agent runs itself, as today).
+- **Gating.** nvrsion is active for a session iff `project.nvrsionActive` (§10): controlled +
+  `nvrsion.enabled` + `usesSharedControlContainer` + the container service is on. Per-session
+  containers (`perSessionContainers`) are **excluded in v0** — a non-shared topology would need
+  per-container checkouts synced to trunk (deferred, §15).
+
+---
+
+## 3. The edit → land → release loop
+
+The whole feature is one loop layered onto the existing acquire path. The acquire half
+([AppStore.arbitrate](../Sources/NucleicCore/AppStore.swift) → `LockManager.acquire`) is **unchanged**;
+nvrsion adds the *land + release* half on a new edit-completion signal.
+
+```
+agent issues Edit/Write(file F)
+  │
+  ├─ arbitrate(S, files:[F]) → LockManager.acquire(S, domain, [F])        # UNCHANGED
+  │     • domain = nvrsion trunk domain (§10), one per (project, trunk)
+  │     • all-or-nothing; queues if F is held by another session
+  │     • on grant: completeGrant → re-ground if trunk moved F under the
+  │       agent's last Read (existing grantedNeedsReground / diff)        # UNCHANGED
+  │
+  ├─ agent's native Edit tool writes F  (its container write IS the host file via virtiofs)
+  │
+  └─ EDIT-COMPLETE signal (new seam, §3.1)
+        │
+        ├─ pre-land hook (§5)?  fail → reject this edit to the agent, KEEP lock warm, do not commit
+        │
+        ├─ landToTrunk(S, [F]):                                           # host-mediated, serialized
+        │     git -C .nucleic/trunk add -- F
+        │     git -C .nucleic/trunk commit -- F  -m "<title> (nvrsion: session <S>)"
+        │        --author "<session author>"  --trailer "Nucleic-Session: <S>"
+        │     # path-scoped: never sweeps in another session's in-flight file
+        │
+        └─ keep F warm (held) — release governed by §4, not here
+```
+
+### 3.1 The edit-completion seam (the one genuinely new wiring)
+
+Today there is no "edit done" callback — `finalize()` (stage+commit) lives only at the ship boundary
+inside `SessionController.integrate()`
+([SessionController.swift:1055](../Sources/NucleicCore/SessionController.swift)). nvrsion needs the
+commit to happen *per edit*. The signal already latent in the system: the backend **synthesizes
+file-change events from Edit/Write/MultiEdit tool calls** ([ClaudeCodeBackend](../Sources/NucleicCore/Claude/ClaudeCodeBackend.swift),
+`emitsFileChangeEvents=false`). nvrsion subscribes to *that* completion, post-approval and
+post-tool-result.
+
+**Design rule:** the backend must **not** call git. It emits a structured "edit completed: session S,
+paths P" event; `AppStore` (which already owns the `LockManager` and the git collaborators) owns an
+`NvrsionTrunk` coordinator that performs `landToTrunk`. This keeps the backend↔git decoupling the
+codebase already enforces (the same shape as `LockManager`'s injected collaborators).
+
+### 3.2 Why landing is conflict-free
+
+The lock guaranteed no other session touched F during the edit, and re-ground guaranteed the agent
+edited against trunk's current F. So `git add F; git commit -- F` on trunk is always a clean
+fast-forward of F's content — there is nothing to merge. Files the agent *read but did not lock* may
+have moved; that surfaces through the existing re-ground/diff path on the agent's next edit, as a
+*notice*, never a hard trunk conflict.
+
+---
+
+## 4. Lock duration — keep-warm within a turn
+
+Two independent clocks, deliberately decoupled:
+
+| Clock | Fires when | Effect |
+| --- | --- | --- |
+| **Land** | each edit completes (§3) | commit F to trunk — others can **read** the latest immediately |
+| **Release** | turn-end ∨ file-switch ∨ idle > `keepWarmIdle` | drop the lock — others can **write** F |
+
+So trunk is always current, but the *lock* is held a little longer than a single edit, to protect a
+multi-edit logical change from a sibling slipping in between two of its edits.
+
+```
+releaseGovernor(session S):
+    on EDIT-COMPLETE(F):     mark F warm, stamp lastTouched[F] = now      # keep holding F
+    on TURN-END(S):          releaseAll-nvrsion(S)                        # drop every warm file
+    on EDIT-COMPLETE(G≠F):   if S no longer intends F → release(S, [F])   # file-switch eviction
+    idle sweep (timer):      for F in warm(S) where now-lastTouched[F] > keepWarmIdle: release(S,[F])
+```
+
+- **Released ⇒ re-read on return.** If S releases F then edits it again, it re-acquires; if another
+  session changed F meanwhile, the existing re-ground hands S the diff. This is the per-file re-read
+  contract, made explicit.
+- **`keepWarmIdle`** is a project config (default 4s). Lower = faster handoff, more re-reads; higher =
+  fewer re-reads, longer waits. Turn-end always releases regardless.
+- **Release is host-certain.** Because the host performs the commit and the host performs the release,
+  there is no "did it land?" detection lag and no leak surface — the central failure mode LOCKING was
+  built to prevent simply doesn't exist on the nvrsion path (nothing to detect; we *did* the merge).
+
+---
+
+## 5. Pre-land validation hook *(Phase D)*
+
+Optional per-project command (`ProjectNvrsion.prelandHook`), default empty. It runs **after the edit is
+written, before the trunk commit** (`NvrsionTrunk.land`), so a broken edit never poisons the trunk —
+and therefore never reaches the real branch (promotion, §6, only ships *committed* trunk work).
+
+```
+prelandHook (e.g. "swift -frontend -parse $NUCLEIC_NVR_PATHS" or a project script):
+   • runs via `/bin/sh -c` on the HOST in the trunk dir, with the edited paths in NUCLEIC_NVR_PATHS,
+   • OUTSIDE the index gate (it only reads files) — a slow hook can't wedge other sessions' lands,
+   • with a 10s timeout (NvrsionTrunk.prelandTimeoutSeconds): overrun ⇒ killed ⇒ rejected.
+   exit 0 → land.   non-zero / timeout / spawn-fail → DON'T land (`NvrLandResult.rejected`):
+        • the edit's content stays on disk (uncommitted) — the agent's work isn't lost,
+        • the file's lock stays warm (released at turn-end / idle like any held file),
+        • a transcript note carries the hook's output so the agent (or user) can fix and re-edit;
+          the next edit to that file re-runs the hook and lands once it passes.
+```
+
+Keep it fast — it is on the per-edit hot path. Intended for syntax/format/typecheck of *just the
+edited files*, not a full build/test (that belongs at promotion, §6). Unset ⇒ landing is immediate.
+
+> **v0 limitation (honest):** the hook runs on the **host** (not in the agent's container) and the
+> rejection is surfaced as a *note*, not folded into the agent's edit tool-result — because the edit's
+> result is already sent by the time `.fileChange` fires (§3.1). The safety property still holds (a
+> rejected edit never lands/promotes); tighter in-container execution + agent re-prompt is future work.
+
+---
+
+## 6. Trunk → base promotion (ship) *(Phase D)*
+
+Trunk accumulates per-edit, session-attributed commits. The project's **real base branch changes only
+by promotion**, which keeps the user in command (NUCLEIC_CONCEPT) and the real history clean despite
+per-edit churn.
+
+- **Explicit promotion** *(implemented)* — `AppStore.promoteNvrsionTrunk` / `NvrsionTrunk.promote`,
+  surfaced as the **"Promote trunk → `<base>`"** button in the project's nvrsion settings.
+  `git merge --squash nucleic/trunk` in the project's root checkout (which is on `base` and untouched
+  by nvrsion agents) → **one clean commit** on the real branch (trailer `Nucleic-Promote: 1`), then a
+  best-effort merge of `base` back into the trunk so the *next* promotion squashes only new work.
+  Conflicts (e.g. `base` edited outside the trunk) reset cleanly and are reported; an unchanged trunk
+  returns *nothing-to-promote*.
+- **Autoship-on-completion** *(deferred — see §15)*: squashing a *single session's* attributed commits
+  out of an interleaved shared history is ill-defined when sessions edit overlapping files over time
+  (which commit is "theirs" after a later session touched the same file?). v0 ships the well-defined
+  **whole-trunk** promotion; per-session autoship is left as future work.
+- Promotion is the *only* place a real-branch mutation happens, so it stays the single audit gate.
+
+---
+
+## 7. Coexistence — what the nvrsion path bypasses
+
+When `project.nvrsionActive`, a session takes the trunk path; everything else is unchanged. The two
+models never run for the same project at once (gated whole-project).
+
+| Subsystem | nvrsion session |
+| --- | --- |
+| Per-session worktree / branch / `baseSHA` ([WorktreeManager](../Sources/NucleicCore/Git/WorktreeManager.swift)) | **Not created.** `worktreePath` = shared `.nucleic/trunk`. |
+| `LockManager.acquire` + re-ground (LOCKING §4.2, §4.5) | **Reused as-is.** Domain = trunk (§10). |
+| Lock *release* (LOCKING §4.4: detect landing) | **Replaced** by host-certain release on commit (§4). No `hasLanded` poll on the nvrsion path. |
+| `SessionController.integrate` / `finalize` at ship | **Repurposed** to *trunk→base promotion* only (§6), not per-session merge. |
+| Nested worktrees / cascade / `parentRef` / `rootRef` (LOCKING §5) | **Unused** — flat trunk, no tree. |
+| Git interceptor → `observeGitOp` | **Still on** (reports agent-run git), but not required for release. |
+| Autoship `MergeQueue` | **Reused** only at trunk→base promotion (§6). |
+
+A startup/runtime audit must ensure a project never has *both* live per-session worktrees and nvrsion
+on (flip is allowed only when the project is quiescent; §10).
+
+---
+
+## 8. Persistence & recovery
+
+Today lock state is rebuilt at launch purely from `unmergedFiles` (LOCKING §6,
+[AppStore.reconstructLocks](../Sources/NucleicCore/AppStore.swift)). On the nvrsion path edits land
+immediately, so there are no unmerged files to reconstruct from — the recovery source disappears. But
+that loss is **correct**, not a problem to solve: a restart kills every agent process, so any
+in-flight nvrsion lock has no agent behind it and *should* vanish. Worktree-less nvrsion sessions are
+already skipped by `reconstructLocks`, so no stale lock survives a restart. The only thing that can
+carry across a crash is the **trunk's working tree** — hence:
+
+- **`nvrsion_config`** — a JSON column on `project` (migration `v20-nvrsion`), holding the
+  `ProjectNvrsion` struct (`enabled`, `trunkBranch`, `prelandHook`, `keepWarmIdleSeconds`).
+  JSON-encoded like `sandbox_config`, so future fields need no new migration. *(Phase A.)*
+- **Launch trunk-recovery** (`NvrsionTrunk.recover`, driven by `AppStore.reconcileNvrsionTrunks` after
+  `reconstructLocks`). Invariant 2 bounds loss to a single edit: a crash can leave a file
+  written-but-uncommitted on the trunk (the agent wrote it; the app died before `.fileChange` landed
+  it). On launch, for each nvrsion project, `recover` ensures the trunk exists and **commits any
+  uncommitted residue** as a `Nucleic-Recovery: 1` commit, so the trunk starts every run clean and no
+  work is silently lost. The trunk's git history is the durable record. *(Phase C.)*
+
+> **Design note (revised in Phase C):** the earlier sketch proposed an `nvr_file_state` table to
+> re-seed warm locks across a restart. It was dropped — re-seeding is pointless because the agents
+> that held those locks are gone, and crash safety is fully covered by committing the trunk's dirty
+> residue (above). One less table, one less migration, same guarantees.
+
+---
+
+## 9. Failure semantics (truth table)
+
+| Event | Trunk | Lock |
+| --- | --- | --- |
+| Edit completes, no hook | committed (path-scoped) | kept warm (§4) |
+| Pre-land hook fails | **not** committed; edit stays on disk | kept warm; edit re-issued |
+| Turn ends | (already committed per edit) | released (all warm) |
+| Idle > `keepWarmIdle` | — | that file released |
+| Agent runs `git` itself in trunk | its commit recorded; interceptor reports it | reconciled like any commit |
+| App/container crash mid-edit | ≤1 edit uncommitted on trunk | re-seeded from `nvr_file_state` at launch |
+| Two sessions, same file | — | impossible (lock); second queues |
+| Two sessions, different files | both commit (path-scoped, serialized) | independent |
+| Promotion to base conflicts | trunk unchanged | n/a (heavier flow, §6, surfaced like autoship conflict) |
+
+---
+
+## 10. Opt-in surface & Beta gating
+
+- **`Project.nvrsion: ProjectNvrsion?`** — `nil`/`enabled:false` ⇒ off (default). Persisted as
+  `nvrsion_config` JSON (migration `v20-nvrsion`), mirroring `sandbox`.
+- **`Project.nvrsionActive: Bool`** — the single gate both spawn and teardown read:
+  ```
+  isNucleicControlled && (nvrsion?.enabled ?? false) && usesSharedControlContainer
+  ```
+  (and, like `effectiveSandbox`, subordinate to the app-wide container-service master switch).
+- **UI:** a **Beta**-labeled toggle in `ProjectSettingsSheet`
+  ([Sheets.swift](../Sources/NucleicApp/Sheets.swift)), shown only for control projects, disabled
+  (with an explanatory caption) when `perSessionContainers` is on. Optional `keepWarmIdle` /
+  `prelandHook` fields behind a disclosure.
+- **Flip safety:** toggling nvrsion is only allowed when the project has **no live sessions** (so the
+  two models never coexist on live work); enforced in `updateProject`.
+- **No app-wide default-on for v0** (the chosen rollout is opt-in/off). A
+  `nvrsionByDefault` UserDefaults key can be added later beside `controlByDefault` if wanted.
+
+---
+
+## 11. Reuse vs replace (summary)
+
+| Component | Verdict |
+| --- | --- |
+| `LockManager` acquire + queue + re-ground | **Reuse unchanged** (it's the heart; nvrsion only changes *when release fires*). |
+| `arbitrate` / `handleApprovalCall` acquire path | **Reuse**; add the edit-completion subscription. |
+| Per-session `WorktreeManager` worktree/branch/`baseSHA` | **Bypass** on the nvrsion path. |
+| `WorktreeManager.finalize`/`integrate` | **Repurpose** for trunk→base promotion only. |
+| Lock-release detection (`hasLanded`, reconcile poll) | **Replace** with host-certain release. |
+| Nested worktree / cascade / `parentRef`·`rootRef` | **Unused** on the nvrsion path. |
+| Git interceptor `observeGitOp` | **Keep** (agent-run git), not required for release. |
+| `reconstructLocks` from `unmergedFiles` | **Replace** with `nvr_file_state` re-seed (§8). |
+| `MergeQueue` | **Reuse** at promotion only. |
+| `lockDomain` / `isNucleicControlled` gate | **Reuse** as the opt-in gate carrier. |
+
+---
+
+## 12. Swift surface (the stable contract)
+
+```swift
+/// Per-project nvrsion config (persisted as `nvrsion_config` JSON, like ProjectSandbox).
+public struct ProjectNvrsion: Sendable, Codable, Equatable {
+    public var enabled: Bool                 // default false
+    public var trunkBranch: String           // default "nucleic/trunk"
+    public var prelandHook: String?          // default nil → land immediately
+    public var keepWarmIdleSeconds: Int      // default 4
+}
+
+extension Project {
+    /// nvrsion governs this project's sessions (the single spawn/teardown gate).
+    public var nvrsionActive: Bool { /* §10 */ }
+    /// Host path of the shared trunk checkout: <repo>/.nucleic/trunk.
+    public var resolvedTrunkPath: String { /* … */ }
+}
+
+/// Host-side coordinator owned by AppStore (mirrors LockManager's injected-collaborator shape).
+/// The backend NEVER calls this directly — it emits edit-completion events AppStore routes here.
+public actor NvrsionTrunk {
+    /// Ensure `.nucleic/trunk` exists on `nucleic/trunk`, forked from the base. Idempotent.
+    public func ensureTrunk(_ project: Project) async throws
+    /// Land exactly `paths` for `session` as one path-scoped commit (serialized). Runs the
+    /// pre-land hook first; returns .rejected(stderr) if it fails (lock kept warm by the caller).
+    public func land(_ session: SessionID, paths: [String]) async -> NvrLandResult
+    /// Promote trunk → base (squash; §6), optionally scoped to one session's attributed commits.
+    public func promote(_ project: Project, session: SessionID?) async -> NvrPromoteResult
+}
+
+public enum NvrLandResult: Sendable, Equatable { case landed(sha: String); case rejected(String); case failed(String) }
+```
+
+Release/keep-warm is driven through the existing `LockManager.release` / `releaseAll`; nvrsion adds a
+small `ReleaseGovernor` (§4) in `AppStore` that owns the warm-set + idle timer and calls them.
+
+---
+
+## 13. Phased rollout
+
+Each phase builds + `swift test --build-system native` green before the next.
+
+| Phase | Scope | Status |
+| --- | --- | --- |
+| **A — Opt-in scaffolding** (§10) | `ProjectNvrsion`, migration `v20-nvrsion`, `ProjectRow` column, `Project.nvrsionActive`/`resolvedTrunkPath`, Beta toggle in `ProjectSettingsSheet`. No behavior change (gate is read nowhere yet). | ✅ **Landed** — `Project.swift`, `GRDBMetadataStore.swift`, `Sheets.swift`; tests in `GRDBMetadataStoreTests`. |
+| **B — Trunk topology + land loop** (§2, §3) | `NvrsionTrunk` actor (`ensureTrunk`, `land`, `regroundOnGrant`); skip worktree creation for nvrsion sessions (CWD = shared trunk); `lockDomain` = trunk; the edit-completion seam (§3.1, `.fileChange` → host-mediated path-scoped commit); **release at turn-end** (keep-warm's conservative form — idle/file-switch eviction is C). | ✅ **Landed** — `NvrsionTrunk.swift` + `AppStore` wiring; `NvrsionTrunkTests` + 2 `AppStore` integration tests. |
+| **C — Keep-warm eviction + crash-recovery** (§4, §8) | `NvrsionReleaseGovernor` idle eviction on top of B's turn-end release (sweep loop in `AppStore`); launch trunk-recovery (`NvrsionTrunk.recover`); flip-safety guard in `updateProject`. (`nvr_file_state` dropped — see §8.) | ✅ **Landed** — `NvrsionReleaseGovernor.swift`, `NvrsionTrunk.recover`, `AppStore` wiring; `NvrsionReleaseGovernorTests` + trunk-recover + 2 `AppStore` tests. |
+| **D — Pre-land hook + promotion** (§5, §6) | Per-edit `prelandHook` (host-side, 10s timeout, `.rejected` → not committed); explicit whole-trunk → base promotion (`promoteNvrsionTrunk`, squash + resync) + a "Promote trunk" button. Per-session autoship-on-completion deferred (§6). | ✅ **Landed** — `NvrsionTrunk.land(prelandHook:)`/`.promote`, `AppStore.promoteNvrsionTrunk`, `Sheets.swift` button; `NvrsionTrunkTests` (hook + promote) + 2 `AppStore` tests. |
+
+**All four phases are landed.** An nvrsion session edits the shared trunk, lands each completed edit
+as a path-scoped commit (optionally gated by a pre-land hook), holds a file warm until idle past
+`keepWarmIdle` or turn-end, recovers cleanly from a crash, refuses an unsafe mid-flight mode flip, and
+the user promotes the trunk's accumulated work into the real branch as one squashed commit on demand.
+Everything is behind the per-project Beta opt-in (default off, Control-only).
+
+> **Keep-warm has two tiers now:** a landed file is held until it goes idle past the project's
+> `keepWarmIdleSeconds` (the `NvrsionReleaseGovernor` sweep, default 4s) **or** the turn ends
+> (`.runFinished` → `releaseAll`), whichever first. Active editing refreshes the idle clock, so a
+> multi-edit change to one file is never interrupted; a file the agent finished with is handed off
+> within ~`keepWarmIdle`. Explicit file-switch eviction is subsumed by the idle sweep.
+
+---
+
+## 14. Test matrix
+
+Built on the hermetic git-temp-repo harness (`AppStoreTests`, `LockManagerTests`, `MergeQueueTests`).
+New: `NvrsionTrunkTests`, `NvrsionReleaseGovernorTests`.
+
+| # | Scenario | Asserts |
+| --- | --- | --- |
+| 1 | Single edit lands | After edit-complete, F is committed to `nucleic/trunk` (path-scoped); lock warm. |
+| 2 | Two sessions, different files | Both land; commits are independent and serialized; no index clobber. |
+| 3 | Two sessions, same file | Second queues; granted after first releases; granted session re-grounds to first's content. |
+| 4 | Keep-warm protects a multi-edit change | Sibling can't acquire F between two of holder's edits within a turn; gets it at turn-end. |
+| 5 | Idle eviction | A warm, untouched file releases after `keepWarmIdle`; sibling acquires. |
+| 6 | Re-read on return | Holder releases F (idle), sibling edits F, holder re-acquires → re-ground diff delivered. |
+| 7 | Pre-land hook fails | No commit; edit stays on disk; lock warm; agent re-issues; pass → lands. |
+| 8 | Crash mid-edit | Launch reconcile: dirty trunk path + `nvr_file_state` row → committed or re-seeded; no strand. |
+| 9 | Promotion squashes | Trunk's session-attributed commits squash into base as one commit; trunk preserved. |
+| 10 | Gate off-paths | Non-control / per-session-container / disabled → classic worktree path; no trunk created. |
+| 11 | Flip safety | Toggling nvrsion with a live session is refused. |
+| 12 | No conflict possible | Concurrent disjoint edits + serialized commits never produce a git conflict on trunk. |
+
+---
+
+## 15. Open questions / future work
+
+1. **Per-session containers.** v0 requires the shared container. Supporting `perSessionContainers`
+   needs per-container trunk checkouts that sync to a host trunk per edit (the explore's "Option B");
+   deferred.
+2. **Read staleness of unlocked context.** Files an agent read for context (not locked) can move
+   silently; only *edited* files re-ground. Acceptable for v0; a "context moved" advisory is possible
+   later.
+3. **Trunk history volume.** Commit-per-edit makes trunk history noisy; promotion squashes it for the
+   real branch, but the trunk branch itself grows. Periodic `nucleic/trunk` reset after promotion is a
+   candidate.
+4. **Heavier pre-land gates.** Build/test before *landing* (not just promotion) is intentionally out
+   of scope (latency); revisit if broken edits poisoning trunk proves painful in practice.
+5. **Cross-trunk domains.** A project shipping to multiple bases could want multiple trunks; v0 is one
+   trunk per project. Domain keying (§10) already allows generalizing later.
+6. **iOS parity.** Surface trunk state + per-file warm-locks read-only over the sync protocol
+   (additive wire fields), as the lock viewer does today.