@amalgm/shell 0.1.73 → 0.1.75

package/dist/user-ground-host.js

@@ -6,8 +6,10 @@ import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAm
 import { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, download as downloadArtifact, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, rootReplacementFromRecords, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
+import { emitFilesStage, } from "./files-observability.js";
 import { EntityApplyHost, } from "./entity-apply-host.js";
 import { EntityRecordSqliteStore } from "./entity-record-store.js";
+import { observeEntityRecordPorts } from "./entity-record-observability.js";
 import { indexRowsByOutermostRoot } from "./ground-root-index.js";
 import { ContentCacheDownload, captureContentFile, hashContentFile, sealCapturedArtifact, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
@@ -19,6 +21,7 @@ import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile
 import { inspectGitRegistration, sameGitIdentity, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
 import { NodeWatchHost, } from "./watching/index.js";
+import { GroundCoordinator } from "./ground-coordination.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 const SMALL_CONTENT_UPLOAD_CONCURRENCY = 16;
 const FILE_CONTENT_DOWNLOAD_CONCURRENCY = 4;
@@ -26,6 +29,9 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 const DETECT_QUIET_MS = 12;
 const DETECT_MAX_DEFERRAL_MS = 75;
 const DETECT_RETRY_MS = 250;
+/** A Detect walk yields the event loop this often so Send, Receive, and
+ * Apply progress during a large reconciliation instead of queueing behind it. */
+const DETECT_WALK_YIELD_ENTRIES = 256;
 const DOWNLOAD_CONTENT_RETRY_ATTEMPTS = 3;
 const APPLY_GROUND_WAIT_TIMEOUT_MS = 15_000;
 const GROUND_ROW_COLUMNS = [
@@ -54,7 +60,10 @@ export class UserGroundHost {
     namedDetect = null;
     coldOperation = false;
     closing = false;
-    groundEffectTail = Promise.resolve();
+    /** Visible-ground effects coordinate by address cone: Detect passes hold
+     * the roots they observe, Apply holds its target addresses, Register and
+     * Add hold the ground they materialize. Unrelated cones never wait. */
+    ground = new GroundCoordinator();
     port;
     constructor(options) {
         this.options = options;
@@ -67,7 +76,29 @@ export class UserGroundHost {
         this.watchHost = new NodeWatchHost({
             open: options.openWatch,
             onSignal: () => this.scheduleRescan(),
-            onHealth: options.onWatchHealth,
+            onEvent: (evidence) => this.stage({
+                primitive: "watch",
+                stage: "native-suspicion",
+                status: "observed",
+                path: evidence.path === null
+                    ? evidence.directory
+                    : join(evidence.directory, ...evidence.path.split("/")),
+                measurements: { kind: evidence.kind, named: evidence.path !== null },
+            }),
+            onHealth: (health) => {
+                options.onWatchHealth?.(health);
+                this.stage({
+                    primitive: "watch",
+                    stage: "coverage-health",
+                    status: "observed",
+                    measurements: {
+                        state: health.state,
+                        logicalRoots: health.logicalRoots,
+                        contentHandles: health.contentHandles,
+                        addressHandles: health.addressHandles,
+                    },
+                });
+            },
         });
         this.port = {
             converge: async (identity) => {
@@ -80,7 +111,29 @@ export class UserGroundHost {
                     local,
                 });
                 await this.resumeWorkspaceAdds(this.activeIdentity);
-                this.namedDetect ??= new NamedDetectRuntime(this.databasePath(this.activeIdentity), this.cacheDir(this.activeIdentity), this.userRoot(this.activeIdentity));
+                this.namedDetect ??= new NamedDetectRuntime(this.databasePath(this.activeIdentity), this.cacheDir(this.activeIdentity), this.userRoot(this.activeIdentity), ({ durationMs, records }) => {
+                    if (records.length === 0) {
+                        this.stage({
+                            primitive: "record",
+                            stage: "sqlite-transaction",
+                            status: "completed",
+                            durationMs,
+                            measurements: { records: 0 },
+                        });
+                        return;
+                    }
+                    for (const record of records) {
+                        this.stage({
+                            primitive: "record",
+                            stage: "outbox-committed",
+                            status: "completed",
+                            entityId: record.entityId,
+                            mutationId: record.mutationId,
+                            durationMs,
+                            measurements: { records: records.length },
+                        });
+                    }
+                });
                 const watchHealth = this.watchHost.health();
                 if (watchHealth.state !== "healthy") {
                     throw new Error(`Watch coverage is degraded: ${watchHealth.reason ?? "unknown failure"}`);
@@ -103,6 +156,30 @@ export class UserGroundHost {
             },
         };
     }
+    stage(input) {
+        emitFilesStage(this.options.onFilesStage, input);
+    }
+    reportDetectScan(evidence) {
+        this.options.onDetectScan?.(evidence);
+        this.stage({
+            primitive: "detect",
+            stage: "scan",
+            status: "completed",
+            rootId: evidence.rootId,
+            path: evidence.directory,
+            durationMs: evidence.durationMs,
+            measurements: {
+                scope: evidence.scope,
+                entries: evidence.entries,
+                metadataReused: evidence.metadataReused,
+                contentReads: evidence.contentReads,
+                gitInspections: evidence.gitInspections,
+                repositoryCaptures: evidence.repositoryCaptures,
+                records: evidence.records ?? 0,
+                recordBytes: evidence.recordBytes ?? 0,
+            },
+        });
+    }
     databasePath(identity) {
         return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "identity.db");
     }
@@ -151,14 +228,39 @@ export class UserGroundHost {
         });
         const add = {
             lookupRegistry: async () => {
+                const started = performance.now();
+                this.stage({
+                    primitive: "download", stage: "registry-lookup", status: "started",
+                });
                 const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
                 const cloud = await this.cloudPort(identity).lookup(resourceId);
                 if (!cloud)
                     throw new Error("this user has no cloud entity registry");
+                this.stage({
+                    primitive: "download",
+                    stage: "registry-lookup",
+                    status: "completed",
+                    durationMs: performance.now() - started,
+                });
                 return cloud;
             },
             materializeWorkspace: async (input) => {
-                const release = await this.acquireGroundEffect();
+                const groundWaitStarted = performance.now();
+                this.stage({
+                    primitive: "download",
+                    stage: "ground-wait",
+                    status: "started",
+                    workspaceId: input.workspace.uuid,
+                });
+                const release = await this.acquireGroundScope(workspaceAddCones(input.destinationParent, input.workspace, userRoot));
+                this.stage({
+                    primitive: "download",
+                    stage: "ground-wait",
+                    status: "completed",
+                    workspaceId: input.workspace.uuid,
+                    durationMs: performance.now() - groundWaitStarted,
+                });
+                let milestoneAt = performance.now();
                 try {
                     const installed = await installCloudWorkspace({
                         identity,
@@ -173,11 +275,22 @@ export class UserGroundHost {
                         records: input.records,
                         destinationParent: input.destinationParent,
                         cloudHead: input.cloudHead,
-                        readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
-                        onStage: (stage) => this.options.onWorkspaceAddStage?.({
-                            workspaceId: input.workspace.uuid,
-                            stage,
-                        }),
+                        readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: input.workspace.uuid }),
+                        onStage: async (stage) => {
+                            const now = performance.now();
+                            this.stage({
+                                primitive: stage === "watching" ? "watch" : "download",
+                                stage,
+                                status: "completed",
+                                workspaceId: input.workspace.uuid,
+                                durationMs: now - milestoneAt,
+                            });
+                            milestoneAt = now;
+                            await this.options.onWorkspaceAddStage?.({
+                                workspaceId: input.workspace.uuid,
+                                stage,
+                            });
+                        },
                     });
                     // Add changes both disk and the exact SQLite projection. Open the
                     // selected root's singular Watch coverage before Detect can observe
@@ -192,6 +305,10 @@ export class UserGroundHost {
                 }
             },
             coverWorkspace: async ({ workspaceId, baseline }) => {
+                const started = performance.now();
+                this.stage({
+                    primitive: "watch", stage: "add-coverage", status: "started", workspaceId,
+                });
                 const pending = readWorkspaceAddIntent(this.databasePath(identity), workspaceId);
                 const health = this.ensureWatchers(identity, pending || baseline === "authoritative-install" ? [workspaceId] : []);
                 assertHealthyWatch(this.watchHost.evidence(), workspaceId);
@@ -199,6 +316,17 @@ export class UserGroundHost {
                     await this.options.onWorkspaceAddStage?.({ workspaceId, stage: "watching" });
                     deleteWorkspaceAddIntent(this.databasePath(identity), workspaceId);
                 }
+                this.stage({
+                    primitive: "watch",
+                    stage: "add-coverage",
+                    status: "completed",
+                    workspaceId,
+                    durationMs: performance.now() - started,
+                    measurements: {
+                        contentHandles: health.contentHandles,
+                        addressHandles: health.addressHandles,
+                    },
+                });
                 return { active: true, roots: health.contentHandles };
             },
         };
@@ -211,7 +339,11 @@ export class UserGroundHost {
         const userRoot = this.userRoot(identity);
         const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
         for (const intent of readWorkspaceAddIntents(database)) {
-            const release = await this.acquireGroundEffect();
+            const release = await this.acquireGroundScope([
+                intent.destinationPath,
+                intent.stagingPath,
+                userRoot,
+            ]);
             const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
             try {
                 const selection = workspaceAddSelection(intent);
@@ -236,7 +368,7 @@ export class UserGroundHost {
                     records: intent.records,
                     destinationParent: dirname(intent.destinationPath),
                     cloudHead: intent.cloudHead,
-                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact),
+                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: intent.workspaceId }),
                     onStage: (stage) => this.options.onWorkspaceAddStage?.({
                         workspaceId: intent.workspaceId,
                         stage,
@@ -277,9 +409,24 @@ export class UserGroundHost {
         this.rescanGenerationStartedAt = null;
         let watch;
         try {
+            const watchStarted = performance.now();
+            this.stage({
+                primitive: "watch", stage: "register-coverage", status: "started", workspaceId,
+            });
             this.ensureWatchers(identity);
             watch = this.watchHost.evidence();
             assertHealthyWatch(watch, workspaceId);
+            this.stage({
+                primitive: "watch",
+                stage: "register-coverage",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - watchStarted,
+                measurements: {
+                    contentHandles: watch.health.contentHandles,
+                    addressHandles: watch.health.addressHandles,
+                },
+            });
         }
         catch (error) {
             this.finishColdOperation();
@@ -305,22 +452,39 @@ export class UserGroundHost {
         // a parallel stream of Detect records for the same initial contents.
         let releaseGround = null;
         try {
-            if (this.syncing)
-                await this.syncing;
-            releaseGround = await this.acquireGroundEffect();
+            const groundWaitStarted = performance.now();
+            this.stage({
+                primitive: "register", stage: "ground-wait", status: "started", workspaceId,
+            });
             const contentOwner = watch.roots.find((root) => root.rootId === workspaceId)?.contentOwner;
             if (!contentOwner) {
                 throw new Error(`registered workspace ${workspaceId} has no content coverage owner`);
             }
+            if (this.syncing)
+                await this.syncing;
+            // Registration reconciles the declared coverage family and core
+            // reference ground; unrelated roots keep detecting and applying.
+            releaseGround = await this.acquireGroundScope([contentOwner, this.userRoot(identity)]);
+            this.stage({
+                primitive: "register",
+                stage: "ground-wait",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - groundWaitStarted,
+            });
             const observations = this.watchHost.observations().filter((observation) => observation.directory === this.userRoot(identity)
                 || pathWithin(contentOwner, observation.directory));
             this.watchDirty = false;
+            const registrationStarted = performance.now();
+            this.stage({
+                primitive: "register", stage: "entity-registration", status: "started", workspaceId,
+            });
             const scanned = await reconcileGround({
                 identity,
                 userRoot: this.userRoot(identity),
                 database: this.databasePath(identity),
                 cacheDir: this.cacheDir(identity),
-                onScan: this.options.onDetectScan,
+                onScan: (evidence) => this.reportDetectScan(evidence),
                 registrationWorkspaceId: workspaceId,
                 suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
             });
@@ -328,17 +492,39 @@ export class UserGroundHost {
             if (retry?.kind === "retry") {
                 throw new Error(retry.reasons.join("; "));
             }
+            this.stage({
+                primitive: "register",
+                stage: "entity-registration",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - registrationStarted,
+                measurements: {
+                    roots: scanned.publicationRootIds?.length ?? 0,
+                    rows: scanned.acceptedMaterializedRows.length,
+                },
+            });
+            const commitStarted = performance.now();
+            this.stage({
+                primitive: "register", stage: "entity-sqlite-commit", status: "started", workspaceId,
+            });
             commitDetectedState(this.databasePath(identity), {
                 acceptedMaterializedRows: scanned.acceptedMaterializedRows,
                 materializedRemovals: scanned.materializedRemovals,
                 acceptedNotebookRows: scanned.acceptedNotebookRows,
                 notebookRemovals: scanned.notebookRemovals,
             });
+            this.stage({
+                primitive: "register",
+                stage: "entity-sqlite-commit",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - commitStarted,
+            });
             this.namedDetect?.refreshEnrollmentPolicy();
             if (!scanned.publicationRootIds) {
                 throw new Error("cold registration reconciliation did not name its publication roots");
             }
-            await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds));
+            await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds), { journey: "register", workspaceId });
             this.watchHost.settle(observations);
         }
         catch (error) {
@@ -353,9 +539,21 @@ export class UserGroundHost {
             this.finishColdOperation();
         }
         try {
+            const finalWatchStarted = performance.now();
             this.ensureWatchers(identity);
             watch = this.watchHost.evidence();
             assertHealthyWatch(watch, workspaceId);
+            this.stage({
+                primitive: "watch",
+                stage: "register-final-proof",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - finalWatchStarted,
+                measurements: {
+                    contentHandles: watch.health.contentHandles,
+                    addressHandles: watch.health.addressHandles,
+                },
+            });
         }
         catch (error) {
             throw stageError("Watch coverage", error);
@@ -434,18 +632,28 @@ export class UserGroundHost {
             throw new Error("gateway does not support the event-driven entity Record wire");
         }
         const store = new EntityRecordSqliteStore(initializeDatabase(this.databasePath(identity)));
-        const authority = createEntityRecordAuthorityPort({
+        const wireAuthority = createEntityRecordAuthorityPort({
             request: (frame, acceptedTypes) => this.wire.request({ ...frame }, acceptedTypes),
             onFrame: (listener) => this.wire.onEvent(listener),
             onDisconnect: (listener) => this.wire.onDisconnect(listener),
         });
-        const rail = new EntityRecordRail({
-            authorityId: this.cloudState.resourceId,
+        const ports = observeEntityRecordPorts({
             store,
-            authority,
+            authority: wireAuthority,
             cargo: {
-                ensure: (record) => this.uploadSnapshotContent(identity, record.authorityId, [record.change.result]),
+                ensure: (record) => this.uploadSnapshotContent(identity, record.authorityId, [record.change.result], {
+                    journey: "send",
+                    entityId: record.entityId,
+                    mutationId: record.mutationId,
+                }),
             },
+            onStage: this.options.onFilesStage,
+        });
+        const rail = new EntityRecordRail({
+            authorityId: this.cloudState.resourceId,
+            store: ports.store,
+            authority: ports.authority,
+            cargo: ports.cargo,
             schedule: {
                 schedule(delayMs, callback) {
                     const timer = setTimeout(callback, delayMs);
@@ -482,20 +690,47 @@ export class UserGroundHost {
             userRoot: this.userRoot(identity),
             cacheDir: this.cacheDir(identity),
             bindingDir: workspaceBindingDir(this.userRoot(identity), identity.deviceId),
-            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact, DOWNLOAD_CONTENT_RETRY_ATTEMPTS),
+            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact, DOWNLOAD_CONTENT_RETRY_ATTEMPTS, { journey: "apply" }),
             captureLocal: async (intent, plan, position) => {
-                // Apply never suppresses Watch. This explicit whole-root suspicion is
-                // the synchronous proof boundary used only when Apply observed a
-                // save racing its reveal and must make that save durable first.
-                this.watchHost.suspectAll();
+                // Apply never suppresses Watch. This explicit named suspicion is the
+                // synchronous proof boundary used only when Apply observed a save
+                // racing its reveal and must make that save durable first. It rings
+                // exactly the addresses Apply compared, so the proof costs one named
+                // Detect lane, not a walk of every root.
+                let addresses = [];
+                try {
+                    addresses = host.applyAddresses(intent, plan);
+                }
+                catch {
+                    // Without an address the whole plan is suspect below.
+                }
+                if (addresses.length === 0)
+                    this.watchHost.suspectAll();
+                for (const address of addresses)
+                    this.watchHost.suspect(address);
                 this.watchDirty = true;
-                await this.syncNow();
+                // A pass already queued may have frozen its observations before this
+                // ring; keep proving until the generation that holds it has settled.
+                const cutoff = this.watchHost.observations();
+                do {
+                    await this.syncNow();
+                } while (!this.closing && !this.watchHost.settled(cutoff));
                 if (!host.store.hasLocalWorkAfter(intent.authorityId, intent.entityId, intent.throughSequence)) {
                     throw new Error(`Apply ${position} capture for ${plan.target.type} ${plan.target.name} (${intent.entityId}) produced no durable local record`);
                 }
             },
-            acquireGround: () => this.acquireGroundEffect(APPLY_GROUND_WAIT_TIMEOUT_MS),
-            onStage: (evidence) => this.options.onApplyStage?.(evidence),
+            acquireGround: (cones) => this.acquireGroundScope(cones, APPLY_GROUND_WAIT_TIMEOUT_MS),
+            onStage: (evidence) => {
+                this.options.onApplyStage?.(evidence);
+                this.stage({
+                    primitive: "apply",
+                    stage: evidence.stage,
+                    status: "observed",
+                    entityId: evidence.entityId,
+                    globalSequence: evidence.throughSequence,
+                    measurements: { type: evidence.type, phase: evidence.phase },
+                });
+            },
             now: () => this.options.now?.().getTime() ?? Date.now(),
         });
         const rail = new EntityApplyRail({
@@ -512,9 +747,11 @@ export class UserGroundHost {
             sha256Hex,
             now: Date.now,
             onBackgroundError: (error) => this.options.onApplyError?.(error),
-            // Path cones and repository territories are wider than one UUID. Until
-            // the host exposes those locks, one serial machine-effect owner is the
-            // only honest concurrency setting.
+            // The host now coordinates by address cone, so Apply's final guard waits
+            // only for effects on its own addresses. The rail itself still drains
+            // one entity at a time: parallel private preparation multiplies content
+            // fetches per connection and has not been certified against the
+            // gateway's content lane. Raise deliberately, with that proof.
             concurrency: 1,
         });
         this.applyHost = host;
@@ -672,7 +909,7 @@ export class UserGroundHost {
                 });
                 await reconcileGround({
                     identity, userRoot, database, cacheDir,
-                    onScan: this.options.onDetectScan,
+                    onScan: (evidence) => this.reportDetectScan(evidence),
                 });
                 return localValue(identity, userRoot, database);
             },
@@ -693,7 +930,7 @@ export class UserGroundHost {
             },
         };
     }
-    async uploadSnapshotContent(identity, resourceId, records) {
+    async uploadSnapshotContent(identity, resourceId, records, trace) {
         const cache = this.cacheDir(identity);
         const byHash = new Map();
         for (const record of records) {
@@ -714,6 +951,27 @@ export class UserGroundHost {
                 bytes: manifest?.bytes ?? statSync(file).size,
             };
         });
+        const started = performance.now();
+        let uploadedChunks = 0;
+        let reusedChunks = 0;
+        let uploadedBytes = 0;
+        let inventoryRequests = 0;
+        const identifiers = {
+            ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+            ...(trace?.entityId ? { entityId: trace.entityId } : {}),
+            ...(trace?.mutationId ? { mutationId: trace.mutationId } : {}),
+        };
+        this.stage({
+            primitive: "upload",
+            stage: "immutable-content",
+            status: "started",
+            ...identifiers,
+            measurements: {
+                journey: trace?.journey ?? "bootstrap",
+                artifacts: sources.length,
+                declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+            },
+        });
         const small = sources.filter((source) => source.bytes <= CHUNK_BYTES);
         const large = sources.filter((source) => source.bytes > CHUNK_BYTES);
         const transfer = async (source) => {
@@ -735,6 +993,7 @@ export class UserGroundHost {
                     sha256: chunk.sha256,
                     bytes: chunk.bytes,
                 }, bytes, ["private.entity-content.stored"]));
+                uploadedBytes += bytes.byteLength;
             };
             try {
                 const receipt = await uploadArtifact(artifact, {
@@ -752,6 +1011,7 @@ export class UserGroundHost {
                 }, {
                     sha256Hex,
                     missingChunks: async (_candidate, manifest) => {
+                        inventoryRequests += 1;
                         const frame = await retryContent(() => this.wire.request({
                             type: "private.entity-content.inventory",
                             resource_id: resourceId,
@@ -794,6 +1054,7 @@ export class UserGroundHost {
                             wire_bytes: encoded.bytes.byteLength,
                             ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
                         }, encoded.bytes, ["private.entity-content.stored-batch"]));
+                        uploadedBytes += encoded.bytes.byteLength;
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
@@ -810,8 +1071,11 @@ export class UserGroundHost {
                             sha256: sha256Hex(bytes),
                             bytes: bytes.length,
                         }, bytes, ["private.entity-content.stored"]));
+                        uploadedBytes += bytes.byteLength;
                     },
                 });
+                uploadedChunks += receipt.uploadedChunks;
+                reusedChunks += receipt.reusedChunks;
                 atomicWrite(manifestCacheFile(cache, artifact.contentHash), stableJson(receipt.manifest));
             }
             finally {
@@ -819,17 +1083,63 @@ export class UserGroundHost {
                     await (await sourceFile.handle).close();
             }
         };
-        await boundedForEach(small, SMALL_CONTENT_UPLOAD_CONCURRENCY, transfer);
-        for (const source of large) {
-            await transfer(source);
+        try {
+            await boundedForEach(small, SMALL_CONTENT_UPLOAD_CONCURRENCY, transfer);
+            for (const source of large) {
+                await transfer(source);
+            }
+            this.stage({
+                primitive: "upload",
+                stage: "immutable-content",
+                status: "completed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: {
+                    journey: trace?.journey ?? "bootstrap",
+                    artifacts: sources.length,
+                    declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+                    uploadedBytes,
+                    uploadedChunks,
+                    reusedChunks,
+                    inventoryRequests,
+                },
+            });
+        }
+        catch (error) {
+            this.stage({
+                primitive: "upload",
+                stage: "immutable-content",
+                status: "failed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: { journey: trace?.journey ?? "bootstrap" },
+            });
+            throw error;
         }
     }
-    async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10) {
+    async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10, trace) {
+        const started = performance.now();
+        let downloadedBytes = 0;
+        let requests = 0;
+        const identifiers = {
+            ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+            entityId: trace?.entityId ?? artifact.entityId,
+            ...(trace?.mutationId ? { mutationId: trace.mutationId } : {}),
+            ...(trace?.globalSequence ? { globalSequence: trace.globalSequence } : {}),
+        };
+        this.stage({
+            primitive: "download",
+            stage: "immutable-content",
+            status: "started",
+            ...identifiers,
+            measurements: { journey: trace?.journey ?? "bootstrap", kind: artifact.kind },
+        });
         const cache = { target: null };
         const getChunk = async (manifest, index) => {
             const chunk = manifest.chunks[index];
             if (!chunk)
                 throw new Error(`content manifest has no chunk ${index}`);
+            requests += 1;
             const frame = await retryContent(() => this.wire.request({
                 type: "private.entity-content.get",
                 resource_id: resourceId,
@@ -839,12 +1149,15 @@ export class UserGroundHost {
                 part_index: index,
                 sha256: chunk.sha256,
             }, ["private.entity-content.data"]), true, retryAttempts);
-            return binaryFrameBytes(frame);
+            const bytes = binaryFrameBytes(frame);
+            downloadedBytes += bytes.byteLength;
+            return bytes;
         };
         try {
             const receipt = await downloadArtifact(artifact, {
                 sha256Hex,
                 getManifest: async () => {
+                    requests += 1;
                     const frame = await retryContent(() => this.wire.request({
                         type: "private.entity-content.get",
                         resource_id: resourceId,
@@ -852,7 +1165,9 @@ export class UserGroundHost {
                         kind: "manifest",
                         part_index: 0,
                     }, ["private.entity-content.data"]), false, retryAttempts);
-                    const candidate = JSON.parse(verifiedFrameBytes(frame).toString("utf8"));
+                    const manifestBytes = verifiedFrameBytes(frame);
+                    downloadedBytes += manifestBytes.byteLength;
+                    const candidate = JSON.parse(manifestBytes.toString("utf8"));
                     const checked = checkContentManifest(candidate, artifact.contentHash);
                     if (!checked.ok)
                         throw new Error(checked.error);
@@ -883,7 +1198,10 @@ export class UserGroundHost {
                             bytes: manifest.chunks[index]?.bytes,
                         })),
                     }, ["private.entity-content.data-batch"]), true, retryAttempts);
-                    return decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
+                    requests += 1;
+                    const decoded = await decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
+                    downloadedBytes += Number(frame.wire_bytes ?? frame.bytes);
+                    return decoded;
                 },
                 putChunk: async (_candidate, _manifest, index, bytes) => {
                     if (!cache.target)
@@ -902,8 +1220,35 @@ export class UserGroundHost {
                     return { local: sealed, bytes: sealed.bytes, contentHash: sealed.contentHash };
                 },
             }, artifact.kind === "file" ? { concurrency: FILE_BATCH_DOWNLOAD_CONCURRENCY } : {});
+            this.stage({
+                primitive: "download",
+                stage: "immutable-content",
+                status: "completed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: {
+                    journey: trace?.journey ?? "bootstrap",
+                    kind: artifact.kind,
+                    declaredBytes: receipt.manifest.bytes,
+                    downloadedBytes,
+                    downloadedChunks: receipt.downloadedChunks,
+                    reusedChunks: receipt.reusedChunks,
+                    requests,
+                },
+            });
             return receipt.local;
         }
+        catch (error) {
+            this.stage({
+                primitive: "download",
+                stage: "immutable-content",
+                status: "failed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: { journey: trace?.journey ?? "bootstrap", kind: artifact.kind, requests },
+            });
+            throw error;
+        }
         finally {
             await cache.target?.close();
         }
@@ -911,6 +1256,7 @@ export class UserGroundHost {
     ensureWatchers(identity, authoritativeBaselineRootIds = []) {
         if (this.closing)
             return this.watchHost.health();
+        const started = performance.now();
         const root = this.userRoot(identity);
         const wanted = new Map([[root, {
                     rootId: `user:${identity.userId}`,
@@ -935,6 +1281,18 @@ export class UserGroundHost {
         if (health.state !== "healthy" || health.contentHandles < 1) {
             throw new Error(`Watch coverage is degraded: ${health.reason ?? "no content coverage"}`);
         }
+        this.stage({
+            primitive: "watch",
+            stage: "topology-reconcile",
+            status: "completed",
+            durationMs: performance.now() - started,
+            measurements: {
+                logicalRoots: health.logicalRoots,
+                contentHandles: health.contentHandles,
+                addressHandles: health.addressHandles,
+                authoritativeBaselines: authoritativeBaselineRootIds.length,
+            },
+        });
         return health;
     }
     scheduleRescan(retryDelayMs) {
@@ -985,75 +1343,107 @@ export class UserGroundHost {
             this.scheduleRescan();
         }
     }
-    async acquireGroundEffect(timeoutMs) {
-        let release;
-        const held = new Promise((resolve) => { release = resolve; });
-        const preceding = this.groundEffectTail;
-        this.groundEffectTail = preceding.then(() => held);
-        let released = false;
-        const releaseOnce = () => {
-            if (released)
-                return;
-            released = true;
-            release();
-        };
-        if (timeoutMs === undefined) {
-            await preceding;
-            return releaseOnce;
-        }
-        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
-            // This queued slot has not become active. Let it pass through as soon as
-            // the preceding owner finishes so invalid input cannot poison the tail.
-            void preceding.then(releaseOnce, releaseOnce);
-            throw new Error("ground-effect wait timeout must be a positive integer");
-        }
-        let timeout = null;
-        try {
-            await Promise.race([
-                preceding,
-                new Promise((_resolve, reject) => {
-                    timeout = setTimeout(() => reject(new Error(`ground-effect wait exceeded ${timeoutMs}ms`)), timeoutMs);
-                }),
-            ]);
-            return releaseOnce;
-        }
-        catch (error) {
-            // The timed-out waiter still owns one FIFO slot. Automatically release
-            // that slot when it reaches the front; otherwise one timeout would block
-            // every later filesystem effect forever.
-            void preceding.then(releaseOnce, releaseOnce);
-            throw error;
-        }
-        finally {
-            if (timeout)
-                clearTimeout(timeout);
-        }
+    acquireGroundScope(cones, timeoutMs) {
+        return this.ground.acquire(cones, timeoutMs === undefined ? {} : { timeoutMs });
     }
     async syncLocalChanges(identity) {
-        const release = await this.acquireGroundEffect();
+        if (!this.cloudState)
+            throw new Error("cloud state is unavailable for user-ground Watch");
+        const userRoot = this.userRoot(identity);
+        const repair = registrationRepairGround(this.databasePath(identity), userRoot, identity.deviceId);
+        if (repair.core || repair.emptyRoots.length > 0) {
+            // A durable binding is registration evidence even if the native event
+            // that created it was lost across a crash. Rebuild coverage first, then
+            // express that uncertainty through Watch like every other Detect input.
+            // These are ambiguous recovery facts, so each affected root is wholly
+            // suspect; unrelated roots remain untouched.
+            this.ensureWatchers(identity);
+            if (repair.core)
+                this.watchHost.suspect(userRoot);
+            for (const root of repair.emptyRoots)
+                this.watchHost.suspect(root);
+        }
+        // Detect is per root. A root without pending suspicion has nothing to
+        // prove and never enters a pass: it costs no walk, no notebook plan, no
+        // repository inspection, and no ground coordination. Only rung roots are
+        // observed, and each rung root is proved on its own lane before any root
+        // widens to reconciliation. Rings after this snapshot own the next pass.
+        const observations = this.watchHost.observations();
+        const pending = observations.filter(({ suspicion }) => suspicion.paths === null || suspicion.paths.length > 0);
+        // An idle root's generation is already proved; settling it keeps every
+        // root's settled generation current without any filesystem work.
+        this.watchHost.settle(observations.filter((observation) => !pending.includes(observation)));
+        if (pending.length === 0) {
+            this.stage({
+                primitive: "detect",
+                stage: "pass",
+                status: "completed",
+                durationMs: 0,
+                measurements: { lane: "idle", roots: 0, records: 0 },
+            });
+            return;
+        }
+        const cones = new Set(pending.map((observation) => observation.directory));
+        const coreScan = cones.has(userRoot);
+        const waitStarted = performance.now();
+        this.stage({
+            primitive: "detect",
+            stage: "ground-wait",
+            status: "started",
+            measurements: { roots: pending.length },
+        });
+        const release = await this.acquireGroundScope([...cones]);
+        this.stage({
+            primitive: "detect",
+            stage: "ground-wait",
+            status: "completed",
+            durationMs: performance.now() - waitStarted,
+        });
         try {
-            await this.syncLocalChangesUnlocked(identity);
+            await this.syncLocalChangesUnlocked(identity, pending, coreScan);
         }
         finally {
             release();
         }
     }
-    async syncLocalChangesUnlocked(identity) {
+    async syncLocalChangesUnlocked(identity, pending, coreScan) {
         if (!this.cloudState)
             throw new Error("cloud state is unavailable for user-ground Watch");
-        const observations = this.watchHost.observations();
-        let widenedRoots = new Set();
-        if (this.namedDetect) {
+        const passStarted = performance.now();
+        this.stage({
+            primitive: "detect",
+            stage: "pass",
+            status: "started",
+            measurements: {
+                roots: pending.length,
+                completeRoots: pending.filter(({ suspicion }) => suspicion.paths === null).length,
+                namedPaths: pending.reduce((count, { suspicion }) => count + (suspicion.paths?.length ?? 0), 0),
+            },
+        });
+        const reconcileSuspicions = new Map();
+        const reconcileObservations = [];
+        let namedRoots = 0;
+        let namedRecords = 0;
+        let unsettled = false;
+        for (const observation of pending) {
+            if (observation.suspicion.paths === null || !this.namedDetect) {
+                reconcileSuspicions.set(observation.directory, observation.suspicion);
+                reconcileObservations.push(observation);
+                continue;
+            }
             // The named lane is an optimization over the same settled evidence.
-            // Any proof failure occurs before its SQLite transaction and widens to
-            // reconciliation; it must never poison a Watch generation in a timer
-            // rejection that only another filesystem event can revive.
-            const named = await this.namedDetect.detect(observations).catch(() => null);
+            // Any proof failure occurs before its SQLite transaction and widens
+            // only this root to reconciliation; it must never poison a Watch
+            // generation in a timer rejection that only another event can revive.
+            const named = await this.namedDetect.detect([observation]).catch(() => null);
+            if (named?.unsettled) {
+                unsettled = true;
+                continue;
+            }
             if (named?.handled) {
                 for (const evidence of named.evidence) {
-                    const observation = observations.find((candidate) => candidate.directory === evidence.directory);
-                    this.options.onDetectScan?.({
-                        rootId: observation?.rootId ?? evidence.directory,
+                    this.reportDetectScan({
+                        rootId: observation.rootId,
                         directory: evidence.directory,
                         scope: "paths",
                         entries: evidence.metadataReads,
@@ -1066,13 +1456,34 @@ export class UserGroundHost {
                         records: evidence.records,
                         recordBytes: evidence.recordBytes,
                     });
+                    namedRecords += evidence.records;
                 }
-                this.watchHost.settle(observations);
-                this.applyRail?.localStateChanged();
-                this.recordRail?.localRecordsAvailable();
-                return;
+                namedRoots += 1;
+                // This root's truth is durable; its generation settles now so a later
+                // failure in another root's reconciliation cannot make it re-prove.
+                this.watchHost.settle([observation]);
+                continue;
+            }
+            const widened = named?.widenedRoots?.includes(observation.directory) === true;
+            reconcileSuspicions.set(observation.directory, widened ? { ...observation.suspicion, paths: null } : observation.suspicion);
+            reconcileObservations.push(observation);
+        }
+        if (namedRoots > 0) {
+            this.applyRail?.localStateChanged();
+            this.recordRail?.localRecordsAvailable();
+        }
+        if (reconcileObservations.length === 0) {
+            this.stage({
+                primitive: "detect",
+                stage: "pass",
+                status: "completed",
+                durationMs: performance.now() - passStarted,
+                measurements: { lane: "named", roots: namedRoots, records: namedRecords },
+            });
+            if (unsettled) {
+                throw pipelineStageError("detection", new Error("repository control operation is unsettled"));
             }
-            widenedRoots = new Set(named?.widenedRoots ?? []);
+            return;
         }
         let detection;
         let acceptedMaterializedRows;
@@ -1085,10 +1496,9 @@ export class UserGroundHost {
                 userRoot: this.userRoot(identity),
                 database: this.databasePath(identity),
                 cacheDir: this.cacheDir(identity),
-                onScan: this.options.onDetectScan,
-                suspicions: new Map(observations.map((observation) => [observation.directory, widenedRoots.has(observation.directory)
-                        ? { ...observation.suspicion, paths: null }
-                        : observation.suspicion])),
+                onScan: (evidence) => this.reportDetectScan(evidence),
+                suspicions: reconcileSuspicions,
+                coreScan,
             });
             detection = scanned.detection;
             acceptedMaterializedRows = scanned.acceptedMaterializedRows;
@@ -1113,6 +1523,7 @@ export class UserGroundHost {
                 proposal,
             }))
             : []);
+        const recordCommitStarted = performance.now();
         commitDetectedState(this.databasePath(identity), {
             acceptedMaterializedRows,
             materializedRemovals,
@@ -1120,10 +1531,48 @@ export class UserGroundHost {
             notebookRemovals,
             proposals: detectedRecords,
         });
+        const recordCommitDuration = performance.now() - recordCommitStarted;
+        if (detectedRecords.length === 0) {
+            this.stage({
+                primitive: "record",
+                stage: "sqlite-transaction",
+                status: "completed",
+                durationMs: recordCommitDuration,
+                measurements: { records: 0 },
+            });
+        }
+        else {
+            for (const record of detectedRecords) {
+                this.stage({
+                    primitive: "record",
+                    stage: "outbox-committed",
+                    status: "completed",
+                    entityId: record.proposal.entityId,
+                    mutationId: record.mutationId,
+                    durationMs: recordCommitDuration,
+                    measurements: { records: detectedRecords.length },
+                });
+            }
+        }
         this.namedDetect?.refreshEnrollmentPolicy();
-        this.watchHost.settle(observations);
+        this.watchHost.settle(reconcileObservations);
         this.applyRail?.localStateChanged();
         this.recordRail?.localRecordsAvailable();
+        this.stage({
+            primitive: "detect",
+            stage: "pass",
+            status: "completed",
+            durationMs: performance.now() - passStarted,
+            measurements: {
+                lane: "reconciliation",
+                roots: reconcileObservations.length,
+                namedRoots,
+                records: detectedRecords.length + namedRecords,
+            },
+        });
+        if (unsettled) {
+            throw pipelineStageError("detection", new Error("repository control operation is unsettled"));
+        }
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
         const pending = readSnapshotPublications(this.databasePath(identity));
@@ -1145,7 +1594,7 @@ export class UserGroundHost {
     /** Register is the deliberate cold graph-publication boundary. Ordinary
      * Watch detection stops at a durable exact record and never rebuilds this
      * resource snapshot. */
-    async publishMaterializedSnapshot(identity, publicationRootIds) {
+    async publishMaterializedSnapshot(identity, publicationRootIds, trace) {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
@@ -1169,7 +1618,7 @@ export class UserGroundHost {
         const identical = pending.find((entry) => entry.resourceId === state.resourceId
             && entry.snapshotChecksum === checksum);
         if (identical) {
-            await this.publishPendingSnapshots(identity);
+            await this.publishPendingSnapshots(identity, trace);
             return;
         }
         if (pending.length > 0) {
@@ -1207,19 +1656,29 @@ export class UserGroundHost {
             replacementRootIds: replacement.rootIds,
             replacementRecords: replacement.records,
         });
-        await this.publishPendingSnapshots(identity);
+        await this.publishPendingSnapshots(identity, trace);
     }
-    async publishPendingSnapshots(identity) {
+    async publishPendingSnapshots(identity, trace) {
         for (const pending of readSnapshotPublications(this.databasePath(identity))) {
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
             const replacement = rootReplacementFromRecords(pending.replacementRootIds, pending.replacementRecords);
             try {
-                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords);
+                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords, trace);
             }
             catch (error) {
                 throw pipelineStageError("cloud upload", error);
             }
             let frame;
+            const graphCommitStarted = performance.now();
+            if (trace?.journey === "register") {
+                this.stage({
+                    primitive: "register",
+                    stage: "cloud-graph-commit",
+                    status: "started",
+                    ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                    ...(trace.mutationId ? { mutationId: trace.mutationId } : {}),
+                });
+            }
             try {
                 frame = await this.wire.request({
                     type: "shared.mutation.submit",
@@ -1237,8 +1696,27 @@ export class UserGroundHost {
                 }, ["shared.mutation.ack"]);
             }
             catch (error) {
+                if (trace?.journey === "register") {
+                    this.stage({
+                        primitive: "register",
+                        stage: "cloud-graph-commit",
+                        status: "failed",
+                        ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                        durationMs: performance.now() - graphCommitStarted,
+                    });
+                }
                 throw pipelineStageError("cloud graph commit", error);
             }
+            if (trace?.journey === "register") {
+                this.stage({
+                    primitive: "register",
+                    stage: "cloud-graph-commit",
+                    status: "completed",
+                    ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                    durationMs: performance.now() - graphCommitStarted,
+                    measurements: { version: Number(frame.version) },
+                });
+            }
             this.cloudState = {
                 resourceId: pending.resourceId,
                 authorityEpoch: Number(frame.authority_epoch),
@@ -1599,6 +2077,41 @@ function countDescendantRows(file, rootUUID) {
         database.close();
     }
 }
+/** Recovery facts created before Watch could prove registration: a binding
+ * whose portable reference is absent from the notebook, or a bound root that
+ * has never produced a local entity row. They pull only those exact roots
+ * into the next Detect pass. */
+function registrationRepairGround(file, userRoot, deviceId) {
+    const bindings = materializedWorkspaceBindings(workspaceBindingDir(userRoot, deviceId));
+    if (bindings.length === 0)
+        return { core: false, emptyRoots: [] };
+    if (!existsSync(file)) {
+        return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
+    }
+    const core = readGroundRootAtPath(file, "detection_notebook", userRoot);
+    if (!core) {
+        return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
+    }
+    const database = initializeDatabase(file);
+    try {
+        const referenced = new Set(database.prepare(`
+      SELECT payload_version AS payloadVersion FROM detection_notebook
+       WHERE root_uuid = ? AND type = 'reference' AND status = 'active'
+         AND payload_version IS NOT NULL
+    `).all(core.uuid).map((row) => row.payloadVersion));
+        const hasRows = database.prepare(`
+      SELECT 1 AS present FROM entities WHERE root_uuid = ? LIMIT 1
+    `);
+        return {
+            core: bindings.some(({ workspaceId }) => !referenced.has(workspaceId)),
+            emptyRoots: bindings.filter(({ workspaceId }) => !hasRows.get(workspaceId))
+                .map(({ directory }) => directory),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
 function readGroundUUIDs(file, table, rootUUIDs) {
     if (!existsSync(file))
         return new Set();
@@ -1620,6 +2133,20 @@ function readGroundUUIDs(file, table, rootUUIDs) {
         database.close();
     }
 }
+/** The ground an Add materialization touches: its destination, its sibling
+ * staging directory, and core ground where the binding and reference live.
+ * An unresolvable parent still names itself; the install reports the error. */
+function workspaceAddCones(destinationParent, workspace, userRoot) {
+    let parent = resolve(destinationParent);
+    try {
+        parent = realpathSync(parent);
+    }
+    catch {
+        // Reported by installCloudWorkspace with its exact error.
+    }
+    const destination = join(parent, workspace.name);
+    return [destination, workspaceAddStagingPath(destination, workspace.uuid), userRoot];
+}
 function workspaceAddStagingPath(destinationPath, workspaceId) {
     return join(dirname(destinationPath), `.amalgm-${workspaceId}.adding`);
 }
@@ -2153,6 +2680,11 @@ function createDeclaredHome(input) {
         }
     }
 }
+/** One macrotask turn: pending I/O, timers, and wire frames run before the
+ * caller resumes. */
+function yieldEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 function slashPath(path) {
     return path.split(sep).join("/");
 }
@@ -2213,7 +2745,7 @@ function materializedWorkspaceBindings(bindingDir) {
     return bindings.sort((left, right) => left.workspaceId.localeCompare(right.workspaceId));
 }
 async function reconcileGround(input) {
-    const { identity, userRoot, database, cacheDir, suspicions, registrationWorkspaceId, onScan, } = input;
+    const { identity, userRoot, database, cacheDir, suspicions, coreScan, registrationWorkspaceId, onScan, } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
     const boundRootEntries = materializedWorkspaceBindings(bindingDir);
@@ -2343,30 +2875,40 @@ async function reconcileGround(input) {
         });
         // Each root commits its local projection before Detect yields. Native
         // callbacks can therefore preserve new suspicion between large roots.
-        await new Promise((resolve) => setImmediate(resolve));
+        await yieldEventLoop();
         return result;
     };
-    await scan({
-        identity,
-        resourceId,
-        rootUUID: coreUUID,
-        rootName: identity.userEmail,
-        rootPath: userRoot,
-        rootType: "workspace",
-        database,
-        cacheDir,
-        policy,
-        bindingDir,
-        suspects: missingPortableReference && coreSuspicion !== null
-            ? [...new Set([...coreSuspicion, "workspaces"])]
-            : coreSuspicion,
-        existingRows: existing.filter((row) => row.rootUUID === coreUUID),
-        suspicion: observationFor(userRoot),
-    });
+    // A Watch pass names exactly the roots it observed. A root outside that
+    // observation has nothing to prove and is not scanned, planned, or
+    // inspected; its rows stay as they are. Only two facts can still pull an
+    // unobserved root in: core ground missing a portable reference for a
+    // binding, and a bound root that has never produced a row.
+    const observed = (root) => !suspicions || suspicions.has(root);
+    if (observed(userRoot) || (missingPortableReference && coreScan !== false)) {
+        await scan({
+            identity,
+            resourceId,
+            rootUUID: coreUUID,
+            rootName: identity.userEmail,
+            rootPath: userRoot,
+            rootType: "workspace",
+            database,
+            cacheDir,
+            policy,
+            bindingDir,
+            suspects: missingPortableReference && coreSuspicion !== null
+                ? [...new Set([...coreSuspicion, "workspaces"])]
+                : coreSuspicion,
+            existingRows: existing.filter((row) => row.rootUUID === coreUUID),
+            suspicion: observationFor(userRoot),
+        });
+    }
     const physicalRoots = registrationOwner ? [registrationOwner] : outerBoundRoots;
     for (const { workspaceId, directory: rootPath } of physicalRoots) {
         const existingRoot = existingByUuid.get(workspaceId);
         const existingWorkspaceRows = existingByOutermostRoot.get(workspaceId) || [];
+        if (!observed(rootPath) && existingWorkspaceRows.length > 0)
+            continue;
         const registeredPath = registrationBoundary
             && registrationOwner?.workspaceId === workspaceId
             && registrationBoundary.workspaceId !== workspaceId
@@ -2554,6 +3096,7 @@ async function reconcileRoot(input) {
         }
         return [...new Set(paths)].sort();
     };
+    let visitedEntries = 0;
     const visit = async (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
         ? {
             root: directory,
@@ -2580,6 +3123,11 @@ async function reconcileRoot(input) {
             const absolutePath = join(directory, child.name);
             const stats = lstatSync(absolutePath);
             evidence && (evidence.entries += 1);
+            // The walk is synchronous metadata work. Yield periodically so the
+            // wire, Receive, and Apply keep running while a large root is proved.
+            // A Watch ring during the yield remains a later generation.
+            if (++visitedEntries % DETECT_WALK_YIELD_ENTRIES === 0)
+                await yieldEventLoop();
             const existing = existingByPath.get(relativePath);
             const registeredBoundaryId = stats.isDirectory()
                 ? registeredBoundaries.get(resolve(absolutePath))