amalgm 0.1.239 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/tree-store.js

@@ -3,14 +3,13 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { isPathAbsentError } = require('./tree/path-state');
 const { openLocalDb } = require('../state/db');
 const { applyTreeOperation } = require('./tree/reducer');
 const { can } = require('./tree/access');
 const { relativeWorkspacePath, shouldEnroll, shouldSync } = require('./tree/inclusion');
 const {
   hasAncestorInSet,
-  materializeOperation,
-  persistNodes,
   relativePathForNode,
   rowToNode,
   workspaceRow,
@@ -18,13 +17,13 @@ const {
 const { normalizeTreeOperation } = require('./tree/operations');
 const { uuidV7 } = require('./tree/identity');
 const { isGitOwnedPath } = require('./repo-scope');
+const {
+  ROOT_HOLD_REASONS,
+  inspectWorkspaceRoot,
+  rootBindingError,
+} = require('./tree/root-binding');
 
 const TREE_RESOURCE_PREFIX = 'workspace-tree:';
-// Tree enrollment and disk observation run inside the MCP process. Keep those
-// automatic passes bounded so one very large workspace cannot monopolize the
-// event loop and make the runtime health endpoint unavailable. Explicit
-// workspace operations remain uncapped.
-const AUTOMATIC_TREE_NODE_LIMIT = 2_000;
 
 function invalid(message, statusCode = 400) {
   return Object.assign(new Error(message), { statusCode });
@@ -58,6 +57,11 @@ function nodeForPath(absolutePath, options = {}) {
   const database = options.database || openLocalDb();
   const workspace = workspaceForPath(absolutePath, database);
   if (!workspace) return null;
+  const proof = inspectWorkspaceRoot(workspace, database);
+  if (proof.state !== 'verified') {
+    observerRootHold(workspace, proof, database);
+    return null;
+  }
   const relativePath = path.resolve(absolutePath) === path.resolve(workspace.path)
     ? ''
     : relativeWorkspacePath(workspace.path, path.resolve(absolutePath));
@@ -81,6 +85,12 @@ function absolutePathForNode(nodeId, options = {}) {
     WHERE workspace_nodes.id = ?
   `).get(nodeId);
   if (!row || row.purged_at || row.missing_at) return null;
+  const workspace = { id: row.workspace_id, path: row.workspace_path };
+  const proof = inspectWorkspaceRoot(workspace, database);
+  if (proof.state !== 'verified') {
+    observerRootHold(workspace, proof, database);
+    return null;
+  }
   return row.relative_path
     ? path.join(row.workspace_path, ...row.relative_path.split('/'))
     : row.workspace_path;
@@ -143,6 +153,135 @@ function scanDirectory(rootPath, options = {}) {
   return entries;
 }
 
+function physicalAliasGroups(entries) {
+  const byIdentity = new Map();
+  for (const entry of entries) {
+    if (entry.kind !== 'file') continue;
+    const key = `${entry.deviceId}:${entry.inode}`;
+    const aliases = byIdentity.get(key) || [];
+    aliases.push(entry);
+    byIdentity.set(key, aliases);
+  }
+  return Array.from(byIdentity.values()).filter((aliases) => aliases.length > 1);
+}
+
+function scanWorkspacePhysicalAliases(identifier, options = {}) {
+  const database = options.database || openLocalDb();
+  const workspace = workspaceRow(identifier, database);
+  if (!workspace) throw invalid('workspace not found', 404);
+  const rootPath = path.resolve(workspace.path || '');
+  const rootStats = fs.statSync(rootPath);
+  if (!rootStats.isDirectory()) {
+    throw invalid('workspace path is not a folder', 409);
+  }
+  return physicalAliasGroups(scanDirectory(rootPath)).map((aliases) => ({
+    deviceId: aliases[0].deviceId,
+    inode: aliases[0].inode,
+    paths: aliases.map((entry) => entry.relativePath),
+  }));
+}
+
+function observerHoldsExceptRoot(workspace, database) {
+  const observationHolds = require('./tree/observation-holds');
+  return observationHolds.list(workspace.id, database)
+    .filter((hold) => (
+      hold.ownerKind === 'observer'
+      && hold.ownerId === 'workspace-tree-observer'
+      && !ROOT_HOLD_REASONS.has(hold.reason)
+    ))
+    .map((hold) => ({
+      reason: hold.reason,
+      nodeId: hold.nodeId,
+      operation: hold.operationKind ? { kind: hold.operationKind } : null,
+      paths: hold.paths,
+    }));
+}
+
+function observerRootHold(workspace, proof, database) {
+  const existing = observerHoldsExceptRoot(workspace, database);
+  const hold = {
+    reason: proof.reason || 'workspace-root-enrollment-pending',
+    nodeId: workspace.id,
+    paths: [workspace.path],
+  };
+  require('./store').commitCompletedTreeObservation(
+    workspace.id,
+    [...existing, hold],
+    { database, source: 'workspace-tree:root-hold' },
+  );
+  return {
+    workspaceId: workspace.id,
+    state: 'held',
+    operations: [],
+    created: 0,
+    nodes: [],
+    skipped: hold.reason,
+    held: [hold],
+  };
+}
+
+function clearObserverRootHolds(
+  workspace,
+  database,
+  source,
+  mutate = null,
+) {
+  require('./store').commitCompletedTreeObservation(
+    workspace.id,
+    observerHoldsExceptRoot(workspace, database),
+    {
+      database,
+      source,
+      ...(typeof mutate === 'function' ? { mutate } : {}),
+    },
+  );
+}
+
+function bindExcludedWorkspaceRoot(workspace, proof, database) {
+  const now = new Date().toISOString();
+  clearObserverRootHolds(
+    workspace,
+    database,
+    'workspace-tree:excluded-root-binding',
+    () => {
+      database.prepare(`
+        UPDATE workspace_nodes
+        SET name = ?, device_id = ?, inode = ?, missing_at = NULL,
+            updated_at = ?
+        WHERE workspace_id = ? AND id = ?
+      `).run(
+        workspace.name,
+        proof.actual.deviceId,
+        proof.actual.inode,
+        now,
+        workspace.id,
+        workspace.id,
+      );
+    },
+  );
+  return {
+    workspaceId: workspace.id,
+    state: 'excluded',
+    created: 0,
+    nodes: [],
+    skipped: 'git-owned',
+  };
+}
+
+function verifiedWorkspaceRoot(identifier, options = {}) {
+  const database = options.database || openLocalDb();
+  const workspace = typeof identifier === 'object'
+    ? identifier
+    : workspaceRow(identifier, database);
+  if (!workspace) throw invalid('workspace not found', 404);
+  const proof = inspectWorkspaceRoot(workspace, database);
+  if (proof.state !== 'verified') {
+    observerRootHold(workspace, proof, database);
+    throw rootBindingError(proof);
+  }
+  return proof;
+}
+
 /**
  * Enroll current disk state without turning a path into identity. Existing
  * paths retain their UUID; a same-filesystem rename is recognized by inode;
@@ -154,10 +293,52 @@ function enrollWorkspace(identifier, options = {}) {
   const workspace = workspaceRow(identifier, database);
   if (!workspace) throw invalid('workspace not found', 404);
   const rootPath = path.resolve(workspace.path || '');
-  const rootStats = fs.statSync(rootPath);
-  if (!rootStats.isDirectory()) throw invalid('workspace path is not a folder', 409);
+  const rootProof = inspectWorkspaceRoot(workspace, database);
+  if (rootProof.state === 'held' || !rootProof.actual && rootProof.state === 'unbound') {
+    return observerRootHold(
+      workspace,
+      rootProof.state === 'held'
+        ? rootProof
+        : { ...rootProof, reason: 'workspace-root-missing' },
+      database,
+    );
+  }
   if (isGitOwnedPath(rootPath)) {
-    return { workspaceId: workspace.id, created: 0, nodes: [], skipped: 'git-owned' };
+    if (rootProof.state === 'unbound') {
+      return bindExcludedWorkspaceRoot(workspace, rootProof, database);
+    }
+    clearObserverRootHolds(
+      workspace,
+      database,
+      'workspace-tree:excluded-root-verified',
+    );
+    return {
+      workspaceId: workspace.id,
+      state: 'excluded',
+      created: 0,
+      nodes: [],
+      skipped: 'git-owned',
+    };
+  }
+  if (rootProof.state === 'verified') {
+    // Enrollment is the one-time act that gives an existing tree its initial
+    // UUIDs. Once the root has a physical binding, every later disk change
+    // must pass through the journaled observer. Re-running the baseline
+    // writer here could otherwise absorb a permission-held change and clear
+    // the observer's durable hold without ever issuing its mutation.
+    const observed = reconcileWorkspaceTree(workspace.id, {
+      database,
+      maxNodes: options.maxNodes,
+    });
+    const operations = observed.operations || [];
+    return {
+      ...observed,
+      created: operations.filter((operation) => operation.kind === 'tree.create').length,
+      renamed: operations.filter((operation) => (
+        operation.kind === 'tree.rename' || operation.kind === 'tree.move'
+      )).length,
+      nodes: listWorkspaceNodes(workspace.id, { database }),
+    };
   }
 
   const maxNodes = treeNodeLimit(options);
@@ -165,7 +346,11 @@ function enrollWorkspace(identifier, options = {}) {
     'SELECT count(*) AS count FROM workspace_nodes WHERE workspace_id = ?',
   ).get(workspace.id).count;
   if (maxNodes != null && existingNodeCount > maxNodes) {
-    return skippedTreeResult(workspace.id, maxNodes, existingNodeCount);
+    return observerRootHold(
+      workspace,
+      { reason: 'workspace-root-enrollment-pending' },
+      database,
+    );
   }
 
   let scanned;
@@ -173,10 +358,34 @@ function enrollWorkspace(identifier, options = {}) {
     scanned = scanDirectory(rootPath, { maxNodes });
   } catch (error) {
     if (error?.code === 'WORKSPACE_TREE_NODE_LIMIT') {
-      return skippedTreeResult(workspace.id, maxNodes, existingNodeCount);
+      return observerRootHold(
+        workspace,
+        { reason: 'workspace-root-enrollment-pending' },
+        database,
+      );
     }
     throw error;
   }
+  const aliasGroups = physicalAliasGroups(scanned);
+  if (aliasGroups.length) {
+    const result = {
+      workspaceId: workspace.id,
+      state: 'held',
+      created: 0,
+      nodes: [],
+      skipped: 'ambiguous-physical-alias',
+      held: aliasGroups.map((aliases) => ({
+        reason: 'ambiguous-physical-alias',
+        paths: aliases.map((entry) => entry.relativePath),
+      })),
+    };
+    require('./store').commitCompletedTreeObservation(
+      workspace.id,
+      result.held,
+      { database },
+    );
+    return result;
+  }
   const existing = database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id);
   // Missing/trash/purged rows are tombstones, not rename candidates. In
   // particular, a later file whose inode was recycled must receive a fresh
@@ -203,7 +412,13 @@ function enrollWorkspace(identifier, options = {}) {
       UPDATE workspace_nodes
       SET name = ?, device_id = ?, inode = ?, missing_at = NULL, updated_at = ?
       WHERE id = ?
-    `).run(workspace.name, String(rootStats.dev), String(rootStats.ino), now, workspace.id);
+    `).run(
+      workspace.name,
+      rootProof.actual.deviceId,
+      rootProof.actual.inode,
+      now,
+      workspace.id,
+    );
 
     for (const entry of scanned) {
       const parentId = nodeIdByPath.get(entry.parentRelativePath);
@@ -285,14 +500,25 @@ function enrollWorkspace(identifier, options = {}) {
       console.warn('[WorkspaceTree] live document rebind after scan failed:', error?.message || error);
     }
   }
-  return { workspaceId: workspace.id, created, renamed: renamed.length, nodes: listWorkspaceNodes(workspace.id, { database }) };
+  require('./store').commitCompletedTreeObservation(
+    workspace.id,
+    [],
+    { database },
+  );
+  return {
+    workspaceId: workspace.id,
+    state: 'ready',
+    created,
+    renamed: renamed.length,
+    nodes: listWorkspaceNodes(workspace.id, { database }),
+  };
 }
 
 function lstatOrNull(targetPath) {
   try {
     return fs.lstatSync(targetPath);
   } catch (error) {
-    if (error?.code === 'ENOENT') return null;
+    if (isPathAbsentError(error)) return null;
     throw error;
   }
 }
@@ -329,6 +555,38 @@ function requirePathCapability(pathInput, capability, options = {}) {
   return { ...found, role };
 }
 
+function operationPathForResult(workspace, nodes, nodeId) {
+  const relative = relativePathForNode(nodes, nodeId);
+  return relative
+    ? path.join(workspace.path, ...relative.split('/'))
+    : workspace.path;
+}
+
+function assertExpectedDiskIdentity(expected) {
+  if (!expected) return;
+  const stats = lstatOrNull(expected.path);
+  const kind = stats?.isSymbolicLink()
+    ? 'symlink'
+    : stats?.isDirectory()
+      ? 'folder'
+      : stats
+        ? 'file'
+        : null;
+  if (
+    kind !== expected.kind
+    || String(stats?.dev ?? '') !== String(expected.deviceId)
+    || String(stats?.ino ?? '') !== String(expected.inode)
+  ) {
+    throw Object.assign(
+      new Error(`workspace tree physical binding changed at ${expected.path}`),
+      {
+        code: 'WORKSPACE_TREE_PHYSICAL_BINDING_CHANGED',
+        statusCode: 409,
+      },
+    );
+  }
+}
+
 function commitTreeOperation(input, options = {}) {
   let operation = normalizeTreeOperation(input);
   const database = options.database || openLocalDb();
@@ -338,15 +596,22 @@ function commitTreeOperation(input, options = {}) {
   if (!can(role, capabilityForOperation(operation.kind))) throw invalid('tree operation is forbidden', 403);
   const workspace = workspaceRow(operation.workspaceId, database);
   if (!workspace) throw invalid('workspace not found', 404);
-  const before = new Map(
-    database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
-      .map(rowToNode)
-      .map((node) => [node.id, node]),
-  );
+  const rootProof = verifiedWorkspaceRoot(workspace, { database });
+  assertExpectedDiskIdentity(options.expectedDiskIdentity);
+  assertExpectedDiskIdentity(options.expectedParentDiskIdentity);
+  const before = options.beforeNodes instanceof Map
+    ? new Map(options.beforeNodes)
+    : new Map(
+      database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
+        .map(rowToNode)
+        .map((node) => [node.id, node]),
+    );
   if (operation.kind === 'tree.move' || operation.kind === 'tree.restore') {
     const destinationId = operation.parentId || before.get(operation.nodeId)?.parentId;
-    const destinationRole = options.role
-      || accessStore.currentUserRole(destinationId, { database });
+    // Source and destination are separate authority boundaries. `options.role`
+    // may be a source capability already resolved by a caller, but it can
+    // never authorize writes into another subtree.
+    const destinationRole = accessStore.currentUserRole(destinationId, { database });
     if (!can(destinationRole, 'create')) {
       throw invalid('tree destination is forbidden', 403);
     }
@@ -365,7 +630,19 @@ function commitTreeOperation(input, options = {}) {
   const replica = shouldSync(targetRelativePath)
     ? require('../state/replicas').getReplicaByLocalResource(localResource, { database })
     : null;
+  if (replica) {
+    const projectedAuthority = Number(database.prepare(`
+      SELECT authority_epoch FROM workspace_access_state WHERE workspace_id = ?
+    `).get(workspace.id)?.authority_epoch || replica.authorityEpoch);
+    require('./tree/floor').ensure({
+      schemaVersion: 1,
+      workspaceId: workspace.id,
+      version: replica.appliedVersion,
+      nodes: before,
+    }, projectedAuthority, { database });
+  }
   let paths = null;
+  let held = null;
 
   const result = require('../state/mutations').commitLocalMutation({
     channelId: replica ? `resource:${replica.resourceId}` : localResource,
@@ -381,7 +658,7 @@ function commitTreeOperation(input, options = {}) {
     operation,
   }, {
     database,
-    materialize() {
+    materialize(journaled) {
       if (operation.kind === 'tree.trash' || operation.kind === 'tree.purge') {
         const affectedNodeIds = new Set();
         for (const node of before.values()) {
@@ -398,12 +675,77 @@ function commitTreeOperation(input, options = {}) {
         }
         require('../state/docs').closeDocsByNodeIds(affectedNodeIds);
       }
-      paths = options.diskAlreadyApplied === true
-        ? { oldPath: null, newPath: null }
-        : materializeOperation(workspace, before, after, operation);
-      database.transaction(() => {
-        paths.changedPaths = persistNodes(database, before, after, workspace.id);
+      const cloud = require('./tree-cloud');
+      const materialization = require('./tree-materialization');
+      held = materialization.insertOperation(
+        cloud.localTreeOperationPlan(
+          workspace,
+          before,
+          after,
+          operation,
+          journaled,
+          {
+            diskAlreadyApplied: options.diskAlreadyApplied === true,
+            source: options.source,
+            rootIdentity: rootProof.identity,
+          },
+        ),
+        database,
+      );
+      if (typeof options.testHooks?.afterOperationPlan === 'function') {
+        options.testHooks.afterOperationPlan(held.plan);
+      }
+      try {
+        held = cloud.crossTreeOperationWithRaceCapture(
+          held,
+          database,
+          options.testHooks,
+        );
+      } catch (error) {
+        cloud.holdClassifiedPlanRetry(held.plan, error, database);
+      }
+      const changedPaths = database.transaction(() => {
+        assertExpectedDiskIdentity(options.expectedDiskIdentity);
+        assertExpectedDiskIdentity(options.expectedParentDiskIdentity);
+        const projected = cloud.projectStoredTreeOperation(held, database);
+        if (
+          typeof options.testHooks
+            ?.afterOperationDatabaseProjectionBeforeIdentityFence
+          === 'function'
+        ) {
+          options.testHooks.afterOperationDatabaseProjectionBeforeIdentityFence(
+            held.plan,
+          );
+        }
+        // The projection and the final physical fence are one SQLite
+        // transaction. A same-kind replacement can therefore make the birth
+        // fail, but it can never retain the adopted UUID in workspace_nodes.
+        assertExpectedDiskIdentity(options.expectedDiskIdentity);
+        assertExpectedDiskIdentity(options.expectedParentDiskIdentity);
+        return projected;
       })();
+      const materializedAfter = new Map(
+        (held.plan.afterNodes || []).map((node) => [node.id, node]),
+      );
+      const materializedTarget = materializedAfter.get(operation.nodeId);
+      paths = {
+        oldPath: targetBefore
+          ? operationPathForResult(workspace, before, targetBefore.id)
+          : null,
+        newPath: materializedTarget
+          && !materializedTarget.trashedAt
+          && !materializedTarget.purgedAt
+          ? operationPathForResult(
+              workspace,
+              materializedAfter,
+              materializedTarget.id,
+            )
+          : null,
+        changedPaths,
+      };
+      if (options.testHooks?.crashAfterOperationProjection === true) {
+        throw new Error('simulated workspace tree crash after local operation projection');
+      }
     },
     event: () => ({
       resource: localResource,
@@ -412,8 +754,22 @@ function commitTreeOperation(input, options = {}) {
       patch: operation,
       source: options.source || 'workspace-tree:local',
     }),
+    finalize() {
+      if (!held) return;
+      held = require('./tree-materialization').markOperationCommitted(held, database);
+      if (typeof options.persistObservedOperation === 'function') {
+        options.persistObservedOperation(operation, mutationId, database);
+      }
+    },
   });
 
+  if (held) {
+    if (options.testHooks?.crashAfterOperationCommit === true) {
+      throw new Error('simulated workspace tree crash after local operation commit');
+    }
+    require('./tree-cloud').finishTreeOperationPlan(held, database, options.testHooks);
+  }
+
   const changedPaths = paths?.changedPaths || [];
   if (changedPaths.length) require('../state/docs').rebindNodePaths(changedPaths);
   return { operation, mutation: result.mutation, event: result.event, paths };
@@ -518,11 +874,18 @@ function commitPathCreate(pathInput, nodeKind, options = {}) {
 function ensureNodeForPath(pathInput, options = {}) {
   const targetPath = path.resolve(pathInput);
   const database = options.database || openLocalDb();
+  const workspace = workspaceForPath(targetPath, database);
+  if (!workspace) return null;
+  const rootProof = inspectWorkspaceRoot(workspace, database);
+  if (rootProof.state === 'unbound') {
+    enrollWorkspace(workspace.id, { database, maxNodes: null });
+  } else if (rootProof.state !== 'verified') {
+    observerRootHold(workspace, rootProof, database);
+    throw rootBindingError(rootProof);
+  }
   const existing = nodeForPath(targetPath, { database });
   if (existing) return existing;
 
-  const workspace = workspaceForPath(targetPath, database);
-  if (!workspace) return null;
   const relative = relativeWorkspacePath(workspace.path, targetPath);
   if (relative == null || !shouldEnroll(relative)) return null;
   const stats = lstatOrNull(targetPath);
@@ -573,7 +936,9 @@ function enrollRegisteredWorkspaces(options = {}) {
   for (const workspace of workspaces) {
     try {
       const result = enrollWorkspace(workspace.id, { database, maxNodes: options.maxNodes });
-      if (!result.skipped) ensureWorkspaceTreePromotion(workspace.id, { database });
+      if (result.state === 'ready') {
+        ensureWorkspaceTreePromotion(workspace.id, { database });
+      }
       results.push(result);
     } catch (error) {
       console.warn(`[WorkspaceTree] enrollment failed for ${workspace.id}:`, error?.message || error);
@@ -590,9 +955,31 @@ function enrollRegisteredWorkspaces(options = {}) {
 function reconcileWorkspaceTree(identifier, options = {}) {
   const database = options.database || openLocalDb();
   const workspace = workspaceRow(identifier, database);
-  if (!workspace || !fs.existsSync(workspace.path)) return { operations: [] };
+  if (!workspace) return { operations: [] };
+  const rootProof = inspectWorkspaceRoot(workspace, database);
+  if (rootProof.state === 'unbound') {
+    // A partial or skipped baseline is still baseline state. Reconciliation
+    // may never reinterpret those existing bytes as new mutations.
+    return enrollWorkspace(workspace.id, { database, maxNodes: null });
+  }
+  if (rootProof.state !== 'verified') {
+    return observerRootHold(workspace, rootProof, database);
+  }
   if (isGitOwnedPath(workspace.path)) {
-    return { workspaceId: workspace.id, operations: [], skipped: 'git-owned' };
+    clearObserverRootHolds(
+      workspace,
+      database,
+      'workspace-tree:excluded-root-verified',
+    );
+    return {
+      workspaceId: workspace.id,
+      state: 'excluded',
+      operations: [],
+      skipped: 'git-owned',
+    };
+  }
+  if (options.skipRecovery !== true) {
+    require('./tree-cloud').recoverAllTreePlans({ database });
   }
   const maxNodes = treeNodeLimit(options);
   const existingNodeCount = database.prepare(
@@ -609,12 +996,43 @@ function reconcileWorkspaceTree(identifier, options = {}) {
 
   const applyObserved = (operation) => {
     try {
-      const result = commitTreeOperation(operation, { database, source, diskAlreadyApplied: true });
+      const result = commitTreeOperation(operation, {
+        database,
+        source,
+        diskAlreadyApplied: true,
+        persistObservedOperation: options.persistObservedOperation,
+      });
       operations.push(result.operation);
       return true;
     } catch (error) {
-      if (error?.statusCode !== 403) throw error;
-      held.push({ operation, reason: 'forbidden' });
+      const heldReason = error?.code === 'WORKSPACE_TREE_SYMLINK_ESCAPE'
+        ? 'symlink-escapes-workspace'
+        : error?.statusCode === 403
+          ? 'forbidden'
+          : null;
+      if (!heldReason) throw error;
+      const current = operation.nodeId
+        ? database.prepare(`
+            SELECT relative_path
+            FROM workspace_nodes
+            WHERE workspace_id = ? AND id = ?
+          `).get(workspace.id, operation.nodeId)
+        : null;
+      const parent = operation.parentId
+        ? database.prepare(`
+            SELECT relative_path
+            FROM workspace_nodes
+            WHERE workspace_id = ? AND id = ?
+          `).get(workspace.id, operation.parentId)
+        : null;
+      const heldPath = operation.kind === 'tree.create' && parent
+        ? [parent.relative_path, operation.name].filter(Boolean).join('/')
+        : current?.relative_path || null;
+      held.push({
+        operation,
+        reason: heldReason,
+        paths: heldPath ? [heldPath] : [],
+      });
       return false;
     }
   };
@@ -633,11 +1051,51 @@ function reconcileWorkspaceTree(identifier, options = {}) {
     includeTrashed: true,
     includeMissing: true,
   });
+  // Enrollment may have observed an absence before this reconciler started.
+  // That durable `missing_at` value is not a terminal tombstone: it is the
+  // exact offline deletion the tree rail still needs to journal. Collapse a
+  // missing subtree to its highest roots and birth the same `tree.trash`
+  // operations an online observer would have produced.
+  const preexistingMissingIds = new Set(
+    rows.filter((node) => (
+      node.id !== workspace.id
+      && node.missingAt
+      && !node.trashedAt
+      && !node.purgedAt
+    )).map((node) => node.id),
+  );
+  const preexistingById = new Map(rows.map((node) => [node.id, node]));
+  for (const nodeId of preexistingMissingIds) {
+    const node = preexistingById.get(nodeId);
+    if (!node || hasAncestorInSet(node, preexistingById, preexistingMissingIds)) continue;
+    if (!applyObserved({
+      kind: 'tree.trash',
+      workspaceId: workspace.id,
+      nodeId,
+      trashedAt: node.missingAt,
+    })) {
+      heldNodeIds.add(nodeId);
+    }
+  }
+  if (preexistingMissingIds.size) {
+    rows = listWorkspaceNodes(workspace.id, {
+      database,
+      includeTrashed: true,
+      includeMissing: true,
+    });
+  }
   const scannedByPath = new Map(scanned.map((entry) => [entry.relativePath, entry]));
   const liveRows = rows.filter(
     (node) => node.id !== workspace.id && !node.missingAt && !node.trashedAt && !node.purgedAt,
   );
   const liveByPath = new Map(liveRows.map((node) => [node.relativePath, node]));
+  const scannedByIdentity = new Map();
+  for (const entry of scanned) {
+    const key = `${entry.deviceId}:${entry.inode}`;
+    const values = scannedByIdentity.get(key) || [];
+    values.push(entry);
+    scannedByIdentity.set(key, values);
+  }
   const liveByInode = new Map();
   for (const node of liveRows) {
     if (!node.deviceId || !node.inode) continue;
@@ -646,21 +1104,204 @@ function reconcileWorkspaceTree(identifier, options = {}) {
     matches.push(node);
     liveByInode.set(key, matches);
   }
+  const physicalParentNodeId = (entry) => {
+    if (!entry?.parentRelativePath) return workspace.id;
+    const parentEntry = scannedByPath.get(entry.parentRelativePath);
+    if (!parentEntry) return null;
+    const matches = (
+      liveByInode.get(`${parentEntry.deviceId}:${parentEntry.inode}`) || []
+    ).filter((node) => node.kind === 'folder');
+    return matches.length === 1 ? matches[0].id : null;
+  };
+  const samePhysicalEntry = (node, entry) => Boolean(
+    node
+    && entry
+    && node.kind === entry.kind
+    && physicalParentNodeId(entry) === node.parentId
+    && (
+      !node.deviceId
+      || !node.inode
+      || (
+        node.deviceId === entry.deviceId
+        && node.inode === entry.inode
+      )
+      || (
+        // A file UUID names the document channel, not one storage inode.
+        // Editors commonly save by atomically replacing the inode at the same
+        // path. That replacement is the same channel only when the former
+        // inode did not move elsewhere; a moved original plus a new file at
+        // its old spelling is a rename followed by a distinct birth.
+        node.kind === 'file'
+        && !scannedByIdentity.has(`${node.deviceId}:${node.inode}`)
+      )
+    )
+  );
+  const refreshSamePathFileBinding = (node, entry) => {
+    if (
+      node.kind !== 'file'
+      || (
+        node.deviceId === entry.deviceId
+        && node.inode === entry.inode
+      )
+    ) {
+      return;
+    }
+    const absoluteEntry = path.join(
+      workspace.path,
+      ...entry.relativePath.split('/'),
+    );
+    const actual = lstatOrNull(absoluteEntry);
+    if (
+      !actual
+      || !actual.isFile()
+      || String(actual.dev) !== entry.deviceId
+      || String(actual.ino) !== entry.inode
+    ) {
+      heldNodeIds.add(node.id);
+      heldPaths.add(entry.relativePath);
+      held.push({
+        nodeId: node.id,
+        paths: [entry.relativePath],
+        reason: 'physical-binding-changed',
+      });
+      return;
+    }
+    const updated = database.prepare(`
+      UPDATE workspace_nodes
+      SET device_id = ?, inode = ?, missing_at = NULL
+      WHERE workspace_id = ? AND id = ?
+        AND relative_path = ? AND kind = 'file'
+        AND device_id IS ? AND inode IS ?
+        AND missing_at IS NULL AND trashed_at IS NULL AND purged_at IS NULL
+    `).run(
+      entry.deviceId,
+      entry.inode,
+      workspace.id,
+      node.id,
+      entry.relativePath,
+      node.deviceId,
+      node.inode,
+    );
+    if (updated.changes !== 1) {
+      heldNodeIds.add(node.id);
+      heldPaths.add(entry.relativePath);
+      held.push({
+        nodeId: node.id,
+        paths: [entry.relativePath],
+        reason: 'physical-binding-changed',
+      });
+      return;
+    }
+    node.deviceId = entry.deviceId;
+    node.inode = entry.inode;
+  };
 
   const renamedIds = new Set();
+  const deferredSurvivors = new Map();
+  const liveRowsById = new Map(rows.map((node) => [node.id, node]));
+  const holdAmbiguousPhysicalNames = (
+    node,
+    physicalEntries,
+    reason = 'ambiguous-physical-alias',
+  ) => {
+    heldNodeIds.add(node.id);
+    let current = node;
+    for (;;) {
+      const parent = liveRowsById.get(current.parentId);
+      if (
+        !parent
+        || parent.id === workspace.id
+        || samePhysicalEntry(
+          parent,
+          scannedByPath.get(parent.relativePath),
+        )
+      ) {
+        break;
+      }
+      heldNodeIds.add(parent.id);
+      current = parent;
+    }
+    for (const candidate of physicalEntries) {
+      heldPaths.add(candidate.relativePath);
+    }
+    held.push({
+      nodeId: node.id,
+      paths: physicalEntries.map((candidate) => candidate.relativePath),
+      reason,
+    });
+  };
+  for (const aliases of physicalAliasGroups(scanned)) {
+    const key = `${aliases[0].deviceId}:${aliases[0].inode}`;
+    const nodes = new Map();
+    for (const entry of aliases) {
+      const atPath = liveByPath.get(entry.relativePath);
+      if (atPath) nodes.set(atPath.id, atPath);
+    }
+    for (const node of liveByInode.get(key) || []) {
+      nodes.set(node.id, node);
+    }
+    if (!nodes.size) {
+      for (const entry of aliases) heldPaths.add(entry.relativePath);
+      held.push({
+        nodeId: null,
+        paths: aliases.map((entry) => entry.relativePath),
+        reason: 'ambiguous-physical-alias',
+      });
+      continue;
+    }
+    for (const node of nodes.values()) {
+      holdAmbiguousPhysicalNames(node, aliases);
+    }
+  }
   for (const entry of scanned) {
-    if (liveByPath.has(entry.relativePath)) continue;
+    if (heldPaths.has(entry.relativePath)) continue;
     const matches = (liveByInode.get(`${entry.deviceId}:${entry.inode}`) || [])
       .filter((node) => !renamedIds.has(node.id));
-    if (matches.length !== 1) continue;
+    if (matches.length > 1) {
+      for (const node of matches) {
+        if (!heldNodeIds.has(node.id)) {
+          holdAmbiguousPhysicalNames(
+            node,
+            [entry],
+            'ambiguous-physical-ownership',
+          );
+        }
+      }
+      continue;
+    }
+    const atPath = liveByPath.get(entry.relativePath);
+    if (samePhysicalEntry(atPath, entry)) {
+      refreshSamePathFileBinding(atPath, entry);
+      continue;
+    }
+    if (matches.length !== 1) {
+      continue;
+    }
     const node = matches[0];
+    const physicalEntries = (
+      scannedByIdentity.get(`${entry.deviceId}:${entry.inode}`) || []
+    );
+    if (physicalEntries.length !== 1) {
+      if (!heldNodeIds.has(node.id)) {
+        holdAmbiguousPhysicalNames(node, physicalEntries);
+      }
+      continue;
+    }
     const rowsById = new Map(rows.map((item) => [item.id, item]));
     if (hasAncestorInSet(node, rowsById, renamedIds)) continue;
-    const parent = nodeForPath(path.dirname(path.join(workspace.path, ...entry.relativePath.split('/'))), { database });
-    if (!parent) continue;
-    const applied = applyObserved(parent.node.id === node.parentId
+    const parentId = physicalParentNodeId(entry);
+    if (!parentId) {
+      // The exact inode survived, but its physical parent is a replacement
+      // that has no UUID yet. Reserve this path. After the old parent is
+      // trashed and the replacement is born, restore/move this same UUID
+      // under that newly proven parent.
+      deferredSurvivors.set(node.id, entry);
+      heldPaths.add(entry.relativePath);
+      continue;
+    }
+    const applied = applyObserved(parentId === node.parentId
       ? { kind: 'tree.rename', workspaceId: workspace.id, nodeId: node.id, name: entry.name }
-      : { kind: 'tree.move', workspaceId: workspace.id, nodeId: node.id, parentId: parent.node.id, name: entry.name });
+      : { kind: 'tree.move', workspaceId: workspace.id, nodeId: node.id, parentId, name: entry.name });
     if (!applied) {
       heldNodeIds.add(node.id);
       heldPaths.add(entry.relativePath);
@@ -669,41 +1310,204 @@ function reconcileWorkspaceTree(identifier, options = {}) {
     renamedIds.add(node.id);
   }
 
-  for (const entry of scanned) {
-    if (heldPaths.has(entry.relativePath)) continue;
-    if (nodeForPath(path.join(workspace.path, ...entry.relativePath.split('/')), { database })) continue;
+  // A path spelling is not identity. After recognizing unique physical
+  // renames, retire every old UUID whose exact kind/device/inode is no longer
+  // present at its recorded path before birthing a replacement at that same
+  // spelling. If the old inode still has ambiguous hardlink names, hold it
+  // instead of guessing which name owns the channel.
+  rows = listWorkspaceNodes(workspace.id, {
+    database,
+    includeTrashed: true,
+    includeMissing: true,
+  });
+  let currentLive = rows.filter(
+    (node) => node.id !== workspace.id && !node.missingAt && !node.trashedAt && !node.purgedAt,
+  );
+  const missingIds = new Set();
+  for (const node of currentLive) {
+    if (heldNodeIds.has(node.id)) continue;
+    if (samePhysicalEntry(node, scannedByPath.get(node.relativePath))) continue;
+    if (
+      isGitOwnedPath(
+        path.join(workspace.path, ...node.relativePath.split('/')),
+      )
+    ) continue;
+    const physical = node.deviceId && node.inode
+      ? scannedByIdentity.get(`${node.deviceId}:${node.inode}`) || []
+      : [];
+    if (physical.length) {
+      if (deferredSurvivors.has(node.id)) continue;
+      if (!heldNodeIds.has(node.id)) {
+        holdAmbiguousPhysicalNames(
+          node,
+          physical,
+          'ambiguous-physical-ownership',
+        );
+      }
+      continue;
+    }
+    missingIds.add(node.id);
+  }
+  const currentById = new Map(rows.map((node) => [node.id, node]));
+  for (const node of currentLive) {
+    if (
+      !missingIds.has(node.id)
+      || hasAncestorInSet(node, currentById, missingIds)
+    ) continue;
+    applyObserved({
+      kind: 'tree.trash',
+      workspaceId: workspace.id,
+      nodeId: node.id,
+    });
+  }
+
+  const birthUnknownEntries = () => {
+    for (const entry of scanned) {
+      if (heldPaths.has(entry.relativePath)) continue;
+      const absoluteEntry = path.join(
+        workspace.path,
+        ...entry.relativePath.split('/'),
+      );
+      if (nodeForPath(absoluteEntry, { database })) continue;
+      const parent = nodeForPath(
+        entry.parentRelativePath
+          ? path.join(workspace.path, ...entry.parentRelativePath.split('/'))
+          : workspace.path,
+        { database },
+      );
+      if (!parent || heldNodeIds.has(parent.node.id)) continue;
+      if (!applyObserved({
+        kind: 'tree.create',
+        workspaceId: workspace.id,
+        nodeId: uuidV7(),
+        parentId: parent.node.id,
+        nodeKind: entry.kind,
+        name: entry.name,
+        symlinkTarget: entry.symlinkTarget,
+      })) {
+        heldPaths.add(entry.relativePath);
+      }
+    }
+  };
+  birthUnknownEntries();
+
+  for (const [nodeId, entry] of Array.from(deferredSurvivors.entries()).sort(
+    (left, right) => (
+      left[1].relativePath.split('/').length
+      - right[1].relativePath.split('/').length
+    ),
+  )) {
     const parent = nodeForPath(
       entry.parentRelativePath
         ? path.join(workspace.path, ...entry.parentRelativePath.split('/'))
         : workspace.path,
       { database },
     );
-    if (!parent) continue;
+    const current = rowToNode(database.prepare(`
+      SELECT * FROM workspace_nodes
+      WHERE workspace_id = ? AND id = ? AND purged_at IS NULL
+    `).get(workspace.id, nodeId));
+    if (!parent || !current) continue;
+    const operation = current.trashedAt
+      ? {
+          kind: 'tree.restore',
+          workspaceId: workspace.id,
+          nodeId,
+          parentId: parent.node.id,
+          name: entry.name,
+        }
+      : parent.node.id === current.parentId
+        ? {
+            kind: 'tree.rename',
+            workspaceId: workspace.id,
+            nodeId,
+            name: entry.name,
+          }
+        : {
+            kind: 'tree.move',
+            workspaceId: workspace.id,
+            nodeId,
+            parentId: parent.node.id,
+            name: entry.name,
+          };
+    if (!applyObserved(operation)) {
+      heldNodeIds.add(nodeId);
+      continue;
+    }
+    renamedIds.add(nodeId);
+  }
+
+  // Restoring a surviving folder also restores descendants that shared its
+  // old trash cascade. Re-apply the same sealed scan immediately so an absent
+  // descendant is re-trashed before this reconciliation finishes.
+  rows = listWorkspaceNodes(workspace.id, {
+    database,
+    includeTrashed: true,
+    includeMissing: true,
+  });
+  const finalLive = rows.filter(
+    (node) => (
+      node.id !== workspace.id
+      && !node.missingAt
+      && !node.trashedAt
+      && !node.purgedAt
+    ),
+  );
+  const finalMissingIds = new Set();
+  for (const node of finalLive) {
+    if (heldNodeIds.has(node.id)) continue;
+    const entry = scannedByPath.get(node.relativePath);
+    const absoluteParent = entry?.parentRelativePath
+      ? path.join(workspace.path, ...entry.parentRelativePath.split('/'))
+      : workspace.path;
+    const currentParent = entry
+      ? nodeForPath(absoluteParent, { database })?.node
+      : null;
+    const exactEntry = Boolean(
+      entry
+      && currentParent?.id === node.parentId
+      && entry.kind === node.kind
+      && (
+        node.kind === 'file'
+        || !node.deviceId
+        || !node.inode
+        || (
+          node.deviceId === entry.deviceId
+          && node.inode === entry.inode
+        )
+      )
+    );
+    if (exactEntry) continue;
+    const physical = node.deviceId && node.inode
+      ? scannedByIdentity.get(`${node.deviceId}:${node.inode}`) || []
+      : [];
+    if (physical.length) continue;
+    finalMissingIds.add(node.id);
+  }
+  const finalById = new Map(rows.map((node) => [node.id, node]));
+  for (const node of finalLive) {
+    if (
+      !finalMissingIds.has(node.id)
+      || hasAncestorInSet(node, finalById, finalMissingIds)
+    ) continue;
     applyObserved({
-      kind: 'tree.create',
+      kind: 'tree.trash',
       workspaceId: workspace.id,
-      nodeId: uuidV7(),
-      parentId: parent.node.id,
-      nodeKind: entry.kind,
-      name: entry.name,
-      symlinkTarget: entry.symlinkTarget,
+      nodeId: node.id,
     });
   }
-
-  rows = listWorkspaceNodes(workspace.id, { database });
-  const rowsById = new Map(rows.map((node) => [node.id, node]));
-  const missingIds = new Set(
-    rows
-      .filter((node) => node.id !== workspace.id && !scannedByPath.has(node.relativePath))
-      .filter((node) => !heldNodeIds.has(node.id))
-      .filter((node) => !isGitOwnedPath(path.join(workspace.path, ...node.relativePath.split('/'))))
-      .map((node) => node.id),
+  birthUnknownEntries();
+  require('./store').commitCompletedTreeObservation(
+    workspace.id,
+    held,
+    { database },
   );
-  for (const node of rows) {
-    if (!missingIds.has(node.id) || hasAncestorInSet(node, rowsById, missingIds)) continue;
-    applyObserved({ kind: 'tree.trash', workspaceId: workspace.id, nodeId: node.id });
-  }
-  return { workspaceId: workspace.id, operations, held };
+  return {
+    workspaceId: workspace.id,
+    state: held.length ? 'held' : 'ready',
+    operations,
+    held,
+  };
 }
 
 function reconcileRegisteredWorkspaceTrees(options = {}) {
@@ -720,16 +1524,32 @@ function reconcileRegisteredWorkspaceTrees(options = {}) {
 }
 
 let enrollmentStarted = false;
-function startTreeEnrollmentService() {
-  if (enrollmentStarted) return;
-  enrollmentStarted = true;
+let enrollmentObserversStarted = false;
+
+function startRecoveredTreeObservers() {
+  if (enrollmentObserversStarted) return;
+  try {
+    require('./tree-cloud').recoverAllTreePlans({ database: openLocalDb() });
+  } catch (error) {
+    console.warn('[WorkspaceTree] recovery must finish before observation:', error?.message || error);
+    const retry = setTimeout(startRecoveredTreeObservers, 2_000);
+    if (typeof retry.unref === 'function') retry.unref();
+    return;
+  }
+  enrollmentObserversStarted = true;
   const timer = setTimeout(
-    () => enrollRegisteredWorkspaces({ maxNodes: AUTOMATIC_TREE_NODE_LIMIT }),
+    () => {
+      // This pass performs one-time baseline enrollment only for roots that
+      // have never been physically bound. Already enrolled roots delegate to
+      // the journaled observer, so startup cannot absorb or clear a held disk
+      // change as new baseline state.
+      enrollRegisteredWorkspaces();
+    },
     0,
   );
   if (typeof timer.unref === 'function') timer.unref();
   const observationTimer = setInterval(
-    () => reconcileRegisteredWorkspaceTrees({ maxNodes: AUTOMATIC_TREE_NODE_LIMIT }),
+    () => reconcileRegisteredWorkspaceTrees(),
     2_000,
   );
   if (typeof observationTimer.unref === 'function') observationTimer.unref();
@@ -743,6 +1563,12 @@ function startTreeEnrollmentService() {
   if (typeof promotionTimer.unref === 'function') promotionTimer.unref();
 }
 
+function startTreeEnrollmentService() {
+  if (enrollmentStarted) return;
+  enrollmentStarted = true;
+  startRecoveredTreeObservers();
+}
+
 function workspaceTreeSnapshot(workspaceId, options = {}) {
   return require('./tree-cloud').workspaceTreeSnapshot(workspaceId, options);
 }
@@ -783,6 +1609,8 @@ module.exports = {
   reconcileRegisteredWorkspaceTrees,
   reconcileWorkspaceTree,
   requirePathCapability,
+  scanWorkspacePhysicalAliases,
+  verifiedWorkspaceRoot,
   workspaceTreeSnapshot,
   workspaceForPath,
 };