@amalgm/shell 0.1.29 → 0.1.31

package/dist/user-ground-host.js

@@ -1,17 +1,18 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, watch, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import { open } from "node:fs/promises";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
-import { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createSuspicionScope, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, deriveUploadManifest, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
+import { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, deriveUploadManifest, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
 import { ContentCacheDownload, hashContentFile } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
 import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, pathExists, pathWithin, referenceWorkspaceId, workspaceBindingDir, } from "./files-register-host.js";
-import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, isRepository, } from "./git-repository-host.js";
+import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, } from "./git-repository-host.js";
 import { inspectGitRegistration, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
+import { NodeWatchHost, } from "./watching/index.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 const PORTABLE_FIELDS = [
     "uuid", "type", "parentUUID", "name", "status", "version",
@@ -25,7 +26,7 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 export class UserGroundHost {
     options;
     wire;
-    watchers = new Map();
+    watchHost;
     activeIdentity = null;
     rescanTimer = null;
     watchDirty = false;
@@ -41,6 +42,11 @@ export class UserGroundHost {
             token: options.tunnelToken,
             runtimeVersion: options.runtimeVersion,
         });
+        this.watchHost = new NodeWatchHost({
+            open: options.openWatch,
+            onSignal: () => this.scheduleRescan(),
+            onHealth: options.onWatchHealth,
+        });
         this.port = {
             converge: async (identity) => {
                 this.converged = false;
@@ -73,18 +79,30 @@ export class UserGroundHost {
     rows(identity) {
         return readRows(this.databasePath(identity));
     }
-    /** Open only the authenticated Files-command effects over an already-ready
-     * local projection. This deliberately does not run login convergence or
-     * Watch registration before a cold download. */
-    openFilesCommand(identity) {
-        const normalized = normalizedIdentity(identity);
-        const database = this.databasePath(normalized);
-        if (!existsSync(database) || readRows(database).length === 0) {
-            throw new Error("Files commands require a materialized local user ground");
+    watchHealth() {
+        return this.watchHost.health();
+    }
+    watchEvidence() {
+        return this.watchHost.evidence();
+    }
+    coverWorkspaceEvidence(workspaceId) {
+        if (!this.activeIdentity || !this.converged) {
+            throw new Error("Watch coverage requires a running authenticated runtime");
         }
-        assertDatabaseIdentity(database, normalized);
-        this.activeIdentity = normalized;
-        this.converged = true;
+        const evidence = this.ensureWatchers(this.activeIdentity);
+        const watch = this.watchHost.evidence();
+        if (evidence.state !== "healthy") {
+            throw new Error(`Watch coverage is degraded: ${evidence.reason ?? "unknown failure"}`);
+        }
+        assertHealthyWatch(watch, workspaceId);
+        return watch;
+    }
+    /** Add already projects authoritative rows; this proves that the same
+     * long-lived runtime now owns their healthy ongoing coverage. */
+    addedWorkspaceEvidence(workspaceId) {
+        const watch = this.watchHost.evidence();
+        assertHealthyWatch(watch, workspaceId);
+        return watch;
     }
     /** Host effects for Live-owned Files commands. The shell CLI receives these
      * ports but never decides Files behavior itself. */
@@ -120,8 +138,8 @@ export class UserGroundHost {
                 readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
             }),
             coverWorkspace: async () => {
-                this.ensureWatchers(identity);
-                return { active: true, roots: this.watchers.size };
+                const health = this.ensureWatchers(identity);
+                return { active: true, roots: health.contentHandles };
             },
         };
         return { register, add };
@@ -132,8 +150,7 @@ export class UserGroundHost {
         if (!this.converged || !this.activeIdentity || !this.cloudState)
             return;
         const identity = this.activeIdentity;
-        for (const watcher of this.watchers.values())
-            watcher.suspicion.suspectAll();
+        this.watchHost.suspectAll();
         this.watchDirty = true;
         await this.syncNow();
         if (!this.closing)
@@ -156,7 +173,7 @@ export class UserGroundHost {
     async flushObservedChanges() {
         while (true) {
             const dirty = this.watchDirty
-                || [...this.watchers.values()].some((watcher) => watcher.suspicion.size > 0);
+                || this.watchHost.hasPending;
             this.watchDirty = false;
             if (dirty) {
                 await this.syncNow();
@@ -184,25 +201,20 @@ export class UserGroundHost {
             if (this.rescanTimer)
                 clearTimeout(this.rescanTimer);
             this.rescanTimer = null;
-            for (const watcher of this.watchers.values())
-                watcher.handle.close();
-            this.watchers.clear();
+            this.watchHost.close({ catchUp: false });
             await this.wire.close();
             return;
         }
         // Command shutdown is the last catch-up boundary. A filesystem callback
         // may still be queued, so watcher silence cannot be used as evidence yet.
-        for (const watcher of this.watchers.values())
-            watcher.suspicion.suspectAll();
-        this.watchDirty = this.watchers.size > 0 || this.watchDirty;
+        this.watchHost.suspectAll();
+        this.watchDirty = this.watchHost.health().logicalRoots > 0 || this.watchDirty;
         this.closing = true;
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
         await this.flushObservedChanges();
-        for (const watcher of this.watchers.values())
-            watcher.handle.close();
-        this.watchers.clear();
+        this.watchHost.close();
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
@@ -285,8 +297,8 @@ export class UserGroundHost {
                 return localValue(identity, userRoot, database);
             },
             watch: async () => {
-                this.ensureWatchers(identity);
-                return { active: true, roots: this.watchers.size };
+                const health = this.ensureWatchers(identity);
+                return { active: true, roots: health.contentHandles };
             },
         };
     }
@@ -497,64 +509,57 @@ export class UserGroundHost {
     }
     ensureWatchers(identity) {
         if (this.closing)
-            return;
+            return this.watchHost.health();
         const root = this.userRoot(identity);
-        const ignoreFile = join(root, ".amalgmignore");
-        const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
-        const wanted = new Map([[root, policy]]);
+        const wanted = new Map([[root, {
+                    rootId: `user:${identity.userId}`,
+                    directory: root,
+                    materialized: directoryExists(root),
+                    excludedSubtrees: [join(root, ".amalgm")],
+                }]]);
+        const bindings = workspaceBindingDir(root, identity.deviceId);
+        if (existsSync(bindings)) {
+            for (const entry of readdirSync(bindings, { withFileTypes: true })) {
+                if (!entry.isSymbolicLink() || !UUID.test(entry.name))
+                    continue;
+                const binding = join(bindings, entry.name);
+                try {
+                    const directory = realpathSync(binding);
+                    if (!directoryExists(directory))
+                        continue;
+                    wanted.set(directory, {
+                        rootId: entry.name.toLowerCase(),
+                        directory,
+                        materialized: true,
+                    });
+                }
+                catch {
+                    // A missing external target has no trustworthy address until Detect
+                    // rescues or rebinds it; its prior entity row remains below.
+                }
+            }
+        }
         for (const row of readRows(this.databasePath(identity))) {
             if (row.parentUUID !== null || row.absolutePath === root)
                 continue;
-            try {
-                if (statSync(row.absolutePath).isDirectory())
-                    wanted.set(row.absolutePath, () => true);
-            }
-            catch {
-                // Unresolved ground keeps its rows but cannot hold a watcher handle.
-            }
-        }
-        for (const [directory, watcher] of this.watchers) {
-            if (!wanted.has(directory)) {
-                watcher.handle.close();
-                this.watchers.delete(directory);
+            const directory = directoryExists(row.absolutePath)
+                ? realpathSync(row.absolutePath)
+                : resolve(row.absolutePath);
+            const prior = wanted.get(directory);
+            if (prior && prior.rootId !== row.rootUUID) {
+                throw new Error(`two logical roots claim the same Watch ground: ${directory}`);
             }
-        }
-        for (const [directory, enrollment] of wanted) {
-            if (this.watchers.has(directory))
-                continue;
-            const suspicion = createSuspicionScope();
-            const handle = watch(directory, { recursive: true }, (_event, file) => {
-                const relativePath = String(file || "").split(sep).join("/");
-                if (relativePath.split("/").includes(".amalgm"))
-                    return;
-                if (relativePath && !enrollment(relativePath))
-                    return;
-                const segments = relativePath.split("/");
-                const git = segments.indexOf(".git");
-                if (!relativePath || relativePath === ".amalgmignore"
-                    || (git === 0 && segments[1] === "index")) {
-                    suspicion.suspectAll();
-                }
-                else if (git > 0 && segments[git + 1] === "index") {
-                    suspicion.ring(segments.slice(0, git).join("/"));
-                }
-                else {
-                    suspicion.ring(relativePath);
-                }
-                this.scheduleRescan();
-            });
-            handle.on("error", () => {
-                suspicion.suspectAll();
-                handle.close();
-                this.watchers.delete(directory);
-                this.scheduleRescan();
+            wanted.set(directory, {
+                rootId: row.rootUUID,
+                directory,
+                materialized: directoryExists(directory),
             });
-            this.watchers.set(directory, { handle, suspicion });
-            // Coverage began after the preceding observation. One catch-up proves
-            // the unobserved interval before watcher silence can be trusted.
-            suspicion.suspectAll();
-            this.scheduleRescan();
         }
+        const health = this.watchHost.reconcile([...wanted.values()]);
+        if (health.state !== "healthy" || health.contentHandles < 1) {
+            throw new Error(`Watch coverage is degraded: ${health.reason ?? "no content coverage"}`);
+        }
+        return health;
     }
     scheduleRescan() {
         if (this.closing)
@@ -581,23 +586,18 @@ export class UserGroundHost {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for user-ground Watch");
-        const observations = new Map();
-        for (const [directory, watcher] of this.watchers) {
-            observations.set(directory, watcher.suspicion.snapshot());
-        }
+        const observations = this.watchHost.observations();
         const localRecords = scanAndRegister({
             identity,
             userRoot: this.userRoot(identity),
             database: this.databasePath(identity),
             cacheDir: this.cacheDir(identity),
-            suspicions: new Map([...observations].map(([directory, snapshot]) => [directory, snapshot.paths])),
+            suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion.paths])),
         });
         const snapshot = snapshotFromRecords(travelingRecords(mergeMaterializedRoots(state.records, localRecords)));
         const checksum = sha256Hex(stableJson(snapshot));
         if (checksum === state.checksum) {
-            for (const [directory, snapshot] of observations) {
-                this.watchers.get(directory)?.suspicion.settle(snapshot);
-            }
+            this.watchHost.settle(observations);
             return;
         }
         const database = initializeDatabase(this.databasePath(identity));
@@ -613,9 +613,7 @@ export class UserGroundHost {
             database.close();
         }
         await this.drainOutbox(identity);
-        for (const [directory, snapshot] of observations) {
-            this.watchers.get(directory)?.suspicion.settle(snapshot);
-        }
+        this.watchHost.settle(observations);
     }
     async drainOutboxBeforeLookup(identity, resourceId) {
         const pending = readOutbox(this.databasePath(identity));
@@ -686,6 +684,23 @@ function normalizedIdentity(identity) {
         deviceId: String(identity.deviceId).trim(),
     };
 }
+function assertHealthyWatch(evidence, rootId) {
+    const root = evidence.roots.find((candidate) => candidate.rootId === rootId);
+    const content = root?.contentOwner
+        ? evidence.content.find((candidate) => candidate.directory === root.contentOwner)
+        : undefined;
+    const address = root?.contentOwner
+        ? evidence.addresses.find((candidate) => candidate.rootIds.includes(rootId))
+        : undefined;
+    if (evidence.health.state !== "healthy"
+        || evidence.health.contentHandles !== evidence.content.length
+        || evidence.health.addressHandles !== evidence.addresses.length
+        || !root?.materialized
+        || !content?.rootIds.includes(rootId)
+        || !address) {
+        throw new Error(`Watch coverage is not healthy for workspace ${rootId}: ${evidence.health.reason ?? "incomplete handle evidence"}`);
+    }
+}
 function immutableWrite(file, bytes) {
     ensurePrivateDir(dirname(file));
     try {
@@ -929,6 +944,14 @@ function fileType(bytes) {
 function slashPath(path) {
     return path.split(sep).join("/");
 }
+function directoryExists(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function scanAndRegister(input) {
     const { identity, userRoot, database, cacheDir, suspicions } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
@@ -943,6 +966,7 @@ function scanAndRegister(input) {
     };
     const existingCore = existing.find((row) => row.parentUUID === null && row.absolutePath === userRoot && row.type === "workspace");
     const coreUUID = existingCore?.uuid || randomUUID();
+    const deferredRootIds = new Set();
     const core = scanRoot({
         identity,
         resourceId,
@@ -957,6 +981,8 @@ function scanAndRegister(input) {
         suspects: suspicionFor(userRoot),
         existingRows: existing.filter((row) => row.rootUUID === coreUUID),
     });
+    if (!core.transferable)
+        deferredRootIds.add(coreUUID);
     const targetRoots = new Set(core.referenceWorkspaceIds);
     for (const row of existing) {
         if (row.parentUUID === null && row.uuid !== coreUUID)
@@ -978,13 +1004,13 @@ function scanAndRegister(input) {
         }
         const existingRoot = existing.find((row) => row.uuid === workspaceId && row.parentUUID === null);
         const existingWorkspaceRows = existing.filter((row) => row.rootUUID === workspaceId);
-        scanRoot({
+        const scanned = scanRoot({
             identity,
             resourceId,
             rootUUID: workspaceId,
             rootName: existingRoot?.name || basename(rootPath),
             rootPath,
-            rootType: classifyRegisteredRoot({ repository: isRepository(rootPath) }),
+            rootType: classifyRegisteredRoot({ repository: hasGitMarker(rootPath) }),
             database,
             cacheDir,
             policy: () => true,
@@ -992,15 +1018,24 @@ function scanAndRegister(input) {
             suspects: existingWorkspaceRows.length === 0 ? null : suspicionFor(rootPath),
             existingRows: existingWorkspaceRows,
         });
+        if (!scanned.transferable)
+            deferredRootIds.add(workspaceId);
     }
-    return portableRecords(database);
+    return readRows(database)
+        .filter((row) => !deferredRootIds.has(row.rootUUID))
+        .map(portableRecord);
 }
 function scanRoot(input) {
     const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, } = input;
     const existingRows = (input.existingRows ?? readRows(database))
         .filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID);
     const existingByPath = new Map(existingRows.map((row) => [row.relativePath, row]));
-    if (suspects !== null && suspects.length === 0 && existingRows.length > 0) {
+    const completeRepositoryEvidence = existingRows.every((row) => row.type !== "repo.git"
+        || (Boolean(row.payloadVersion) && Boolean(row.transportVersion)));
+    if (suspects !== null
+        && suspects.length === 0
+        && existingRows.length > 0
+        && completeRepositoryEvidence) {
         return {
             records: existingRows.map(portableRecord),
             rows: existingRows.map((row) => ({
@@ -1013,6 +1048,7 @@ function scanRoot(input) {
             referenceWorkspaceIds: existingRows
                 .filter((row) => row.type === "reference" && row.payloadVersion && UUID.test(row.payloadVersion))
                 .map((row) => row.payloadVersion),
+            transferable: true,
         };
     }
     const entries = [];
@@ -1074,7 +1110,15 @@ function scanRoot(input) {
                 ? slashPath(relative(activeRepository.root, absolutePath))
                 : null;
             if (observe && repositoryPath && activeRepository && !activeRepository.evidence) {
-                activeRepository.evidence = inspectGitRegistration(activeRepository.root, activeRepository.evidencePaths);
+                try {
+                    activeRepository.evidence = inspectGitRegistration(activeRepository.root, activeRepository.evidencePaths);
+                }
+                catch {
+                    // Classification already settled from the marker. If Git cannot
+                    // provide clean-index evidence, read current worktree bytes; Card +
+                    // Checkpoint capture below remains the transfer retry boundary.
+                    activeRepository.evidence = { cleanLeaves: new Map() };
+                }
             }
             const indexed = observe && repositoryPath
                 ? activeRepository?.evidence?.cleanLeaves.get(repositoryPath)
@@ -1114,7 +1158,7 @@ function scanRoot(input) {
                 }
             }
             else if (stats.isDirectory()) {
-                type = classifyDirectory({ repository: isRepository(absolutePath) });
+                type = classifyDirectory({ repository: hasGitMarker(absolutePath) });
             }
             else if (stats.isFile()) {
                 if (indexed && indexed.type !== "link") {
@@ -1161,81 +1205,6 @@ function scanRoot(input) {
         }
     };
     visit(rootPath, rootUUID, rootType);
-    const repositories = entries.filter((entry) => entry.type === "repo.git");
-    const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
-    const repositoryOwner = (entry) => repositories
-        .filter((repository) => repository.uuid !== entry.uuid
-        && properDescendantOf(entry.relativePath, repository.relativePath))
-        .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
-    for (const repository of repositories) {
-        const repoIdentity = entries
-            .filter((entry) => repositoryOwner(entry)?.uuid === repository.uuid)
-            .map((entry) => ({
-            path: repository.relativePath
-                ? entry.relativePath.slice(repository.relativePath.length + 1)
-                : entry.relativePath,
-            uuid: entry.uuid,
-            type: entry.type,
-            payloadVersion: entry.payloadVersion,
-        }))
-            .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-        const priorRow = existingByPath.get(repository.relativePath);
-        let prior = null;
-        if (priorRow?.type === "repo.git" && priorRow.payloadVersion && priorRow.transportVersion) {
-            const priorPath = join(cacheDir, `${priorRow.transportVersion}.bin`);
-            if (existsSync(priorPath)) {
-                try {
-                    const layout = inspectRepositoryTransportFile(priorPath);
-                    if (layout.stateId === priorRow.payloadVersion) {
-                        prior = {
-                            stateId: priorRow.payloadVersion,
-                            transportVersion: priorRow.transportVersion,
-                            card: layout.card,
-                            identityHash: layout.identityHash,
-                        };
-                    }
-                    else {
-                        rmSync(priorPath, { force: true });
-                    }
-                }
-                catch {
-                    // Content-addressed cache bytes are evidence, not ground. A file
-                    // that cannot prove the current envelope is a cache miss.
-                    rmSync(priorPath, { force: true });
-                }
-            }
-        }
-        const previousRepositories = [...existingByPath.values()]
-            .filter((row) => row.type === "repo.git");
-        const previousOwner = (row) => previousRepositories
-            .filter((candidate) => candidate.uuid !== row.uuid
-            && properDescendantOf(row.relativePath, candidate.relativePath))
-            .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
-        const previousIdentity = prior && priorRow
-            ? [...existingByPath.values()]
-                .filter((row) => previousOwner(row)?.uuid === priorRow.uuid)
-                .map((row) => ({
-                path: priorRow.relativePath
-                    ? row.relativePath.slice(priorRow.relativePath.length + 1)
-                    : row.relativePath,
-                uuid: row.uuid,
-                type: row.type,
-                payloadVersion: row.payloadVersion,
-            }))
-                .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
-            : null;
-        const captured = captureRepository(repository.absolutePath, repoIdentity, prior, previousIdentity);
-        repository.payloadVersion = captured.stateId;
-        repository.transportVersion = captured.transportVersion;
-        if (captured.bytes) {
-            immutableWriteArtifact(cacheDir, {
-                entityId: repository.uuid,
-                entityType: "repo.git",
-                kind: "git",
-                contentHash: captured.transportVersion,
-            }, captured.bytes);
-        }
-    }
     const children = new Map();
     for (const entry of entries) {
         if (entry.parentUUID === null)
@@ -1244,7 +1213,7 @@ function scanRoot(input) {
         group.push({ uuid: entry.uuid, name: entry.name });
         children.set(entry.parentUUID, group);
     }
-    const rows = entries.map((entry) => {
+    const rowsFromEntries = () => entries.map((entry) => {
         const versionPayload = entry.type === "workspace" || entry.type === "folder"
             ? membershipHash(children.get(entry.uuid) ?? [], sha256Hex)
             : entry.payloadVersion;
@@ -1272,8 +1241,114 @@ function scanRoot(input) {
             inode: entry.inode,
         };
     });
-    persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
-    return { records: rows.map((row) => row.record), rows, referenceWorkspaceIds: [...referenceWorkspaceIds] };
+    const persistCurrentRows = () => {
+        const rows = rowsFromEntries();
+        persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
+        return rows;
+    };
+    const repositories = entries.filter((entry) => entry.type === "repo.git");
+    const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
+    const repositoryOwner = (entry) => repositories
+        .filter((repository) => repository.uuid !== entry.uuid
+        && properDescendantOf(entry.relativePath, repository.relativePath))
+        .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
+    try {
+        for (const repository of repositories) {
+            const repoIdentity = entries
+                .filter((entry) => repositoryOwner(entry)?.uuid === repository.uuid)
+                .map((entry) => ({
+                path: repository.relativePath
+                    ? entry.relativePath.slice(repository.relativePath.length + 1)
+                    : entry.relativePath,
+                uuid: entry.uuid,
+                type: entry.type,
+                payloadVersion: entry.payloadVersion,
+            }))
+                .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+            const priorRow = existingByPath.get(repository.relativePath);
+            if (priorRow?.type === "repo.git") {
+                repository.payloadVersion = priorRow.payloadVersion;
+                repository.transportVersion = priorRow.transportVersion;
+            }
+            let prior = null;
+            if (priorRow?.type === "repo.git" && priorRow.payloadVersion && priorRow.transportVersion) {
+                const priorPath = join(cacheDir, `${priorRow.transportVersion}.bin`);
+                if (existsSync(priorPath)) {
+                    try {
+                        const layout = inspectRepositoryTransportFile(priorPath);
+                        if (layout.stateId === priorRow.payloadVersion) {
+                            prior = {
+                                stateId: priorRow.payloadVersion,
+                                transportVersion: priorRow.transportVersion,
+                                card: layout.card,
+                                identityHash: layout.identityHash,
+                            };
+                        }
+                        else {
+                            rmSync(priorPath, { force: true });
+                        }
+                    }
+                    catch {
+                        // Content-addressed cache bytes are evidence, not ground. A file
+                        // that cannot prove the current envelope is a cache miss.
+                        rmSync(priorPath, { force: true });
+                    }
+                }
+            }
+            const previousRepositories = [...existingByPath.values()]
+                .filter((row) => row.type === "repo.git");
+            const previousOwner = (row) => previousRepositories
+                .filter((candidate) => candidate.uuid !== row.uuid
+                && properDescendantOf(row.relativePath, candidate.relativePath))
+                .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
+            const previousIdentity = prior && priorRow
+                ? [...existingByPath.values()]
+                    .filter((row) => previousOwner(row)?.uuid === priorRow.uuid)
+                    .map((row) => ({
+                    path: priorRow.relativePath
+                        ? row.relativePath.slice(priorRow.relativePath.length + 1)
+                        : row.relativePath,
+                    uuid: row.uuid,
+                    type: row.type,
+                    payloadVersion: row.payloadVersion,
+                }))
+                    .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+                : null;
+            const captured = captureRepository(repository.absolutePath, repoIdentity, prior, previousIdentity);
+            repository.payloadVersion = captured.stateId;
+            repository.transportVersion = captured.transportVersion;
+            if (captured.bytes) {
+                immutableWriteArtifact(cacheDir, {
+                    entityId: repository.uuid,
+                    entityType: "repo.git",
+                    kind: "git",
+                    contentHash: captured.transportVersion,
+                }, captured.bytes);
+            }
+        }
+    }
+    catch {
+        // Type and identity are filesystem facts, so they settle locally even
+        // when the selected repository rail cannot yet capture its artifact.
+        // Cloud publication remains commit-last because scanAndRegister omits the
+        // complete materialized root until every repository parcel is capturable.
+        // Git unavailability is local to this root; Watch and unrelated roots stay
+        // live and the next suspicion or resume retries the same ordinary scan.
+        const rows = persistCurrentRows();
+        return {
+            records: rows.map((row) => row.record),
+            rows,
+            referenceWorkspaceIds: [...referenceWorkspaceIds],
+            transferable: false,
+        };
+    }
+    const rows = persistCurrentRows();
+    return {
+        records: rows.map((row) => row.record),
+        rows,
+        referenceWorkspaceIds: [...referenceWorkspaceIds],
+        transferable: true,
+    };
 }
 function portablePaths(records) {
     const byUuid = new Map(records.map((record) => [record.uuid, record]));