@animalabs/agent-framework 0.11.0 → 0.13.0

package/dist/src/modules/workspace/index.js

@@ -18,6 +18,30 @@ class WorkspaceImageReadError extends Error {
         this.name = 'WorkspaceImageReadError';
     }
 }
+/**
+ * Thrown by `WorkspaceModule.readFileFromDisk()`. Messages carry the
+ * mount-prefixed path only — never absolute filesystem paths — so they can be
+ * surfaced to the agent or logged without leaking host layout.
+ */
+export class WorkspaceReadError extends Error {
+    code;
+    stage;
+    errno;
+    constructor(code, message, stage, 
+    /** Underlying errno code (e.g. 'ENOENT', 'ELOOP') when a syscall failed. */
+    errno) {
+        super(message);
+        this.code = code;
+        this.stage = stage;
+        this.errno = errno;
+        this.name = 'WorkspaceReadError';
+    }
+}
+function errnoOf(err) {
+    return typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string'
+        ? err.code
+        : undefined;
+}
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);
 const GIF87A_SIGNATURE = Buffer.from('GIF87a', 'ascii');
@@ -204,9 +228,13 @@ function validateJpeg(bytes, mountPrefixedPath) {
         const marker = bytes[offset];
         offset += 1;
         if (marker === JPEG_EOI) {
-            if (!sawSof || !sawSos || offset !== bytes.length) {
+            if (!sawSof || !sawSos) {
                 invalidImage('JPEG', mountPrefixedPath);
             }
+            // Bytes after EOI are tolerated: hardware encoders (e.g. Raspberry Pi
+            // camera stills) pad each frame to a 4-byte boundary with NULs after
+            // the EOI marker, and every mainstream decoder stops at EOI. The image
+            // proper (SOI..EOI) has been fully validated by this point.
             return;
         }
         if (marker === JPEG_TEM || (marker >= 0xd0 && marker <= 0xd7)) {
@@ -516,6 +544,89 @@ export class WorkspaceModule {
             }
         }
         this.savedState = null;
+        // Absorb out-of-band branch switches (e.g. an offline repair that left
+        // the store on a child branch): if the pinned branch is a strict ancestor
+        // of the current branch and disk state is fully contained in the current
+        // branch's history, re-pin. Without this, every materialize refuses
+        // forever after a repair, even though nothing on disk can be clobbered.
+        this.healBranchPins();
+    }
+    /**
+     * True when everything last materialized to disk for a mount is part of the
+     * CURRENT branch's history — i.e. the current branch is a linear
+     * continuation of the pinned branch as of the pinned sequence.
+     *
+     * Walks the current branch's parent chain. Safe iff the pinned branch is on
+     * the chain AND every fork point along the way is at or after `pinnedSeq`
+     * (a fork before `pinnedSeq` means disk holds records the current branch
+     * never had — genuine divergence). A missing/GC'd intermediate branch or a
+     * child without fork metadata is treated as unsafe: ancestry can't be
+     * proven, so the guard stays closed and `force` is the escape hatch.
+     */
+    isLinearContinuation(store, pinnedBranchId, pinnedSeq) {
+        const current = store.currentBranch();
+        if (current.id === pinnedBranchId)
+            return true;
+        const byId = new Map(store.listBranches().map((b) => [b.id, b]));
+        const visited = new Set();
+        let cursor = byId.get(current.id);
+        while (cursor && !visited.has(cursor.id)) {
+            visited.add(cursor.id);
+            if (cursor.id === pinnedBranchId)
+                return true;
+            if (cursor.parentId === undefined || cursor.branchPoint === undefined)
+                return false;
+            if (cursor.branchPoint < pinnedSeq)
+                return false;
+            cursor = byId.get(cursor.parentId);
+        }
+        return false;
+    }
+    /**
+     * Why materializing this mount is blocked on the current branch, or null if
+     * it isn't. Single source of truth for the materialize guard AND the
+     * `canMaterialize` status field, so status can never report `true` for a
+     * mount that materialize would refuse (the pre-fix defect: status computed
+     * per-mount id-equality while the guard checked ALL mounts).
+     */
+    mountMaterializeBlockReason(store, mount) {
+        if (this.config.materializeOnlyActiveBranch === false)
+            return null;
+        if (!mount.lastMaterializedBranchId)
+            return null;
+        const current = store.currentBranch();
+        if (mount.lastMaterializedBranchId === current.id)
+            return null;
+        if (this.isLinearContinuation(store, mount.lastMaterializedBranchId, mount.lastMaterializedSeq)) {
+            return null;
+        }
+        const pinned = store.listBranches().find((b) => b.id === mount.lastMaterializedBranchId);
+        const pinnedName = pinned ? `"${pinned.name}"` : `id ${mount.lastMaterializedBranchId} (branch no longer exists)`;
+        return (`current branch "${current.name}" has diverged from the branch last materialized to disk ` +
+            `(${pinnedName} at seq ${mount.lastMaterializedSeq}) — disk may hold state the current branch ` +
+            `never had. Pass force: true to overwrite disk from the current branch if it is canonical.`);
+    }
+    /**
+     * Re-pin mounts whose last-materialized branch is a proven ancestor of the
+     * current branch. Runs after persisted state is applied on restart, so an
+     * out-of-band branch switch (offline repair/treatment branches) heals at
+     * boot instead of wedging materialize until manual surgery.
+     */
+    healBranchPins() {
+        const store = this.store;
+        if (!store)
+            return;
+        const current = store.currentBranch();
+        for (const mount of this.mounts.values()) {
+            if (mount.lastMaterializedBranchId &&
+                mount.lastMaterializedBranchId !== current.id &&
+                this.isLinearContinuation(store, mount.lastMaterializedBranchId, mount.lastMaterializedSeq)) {
+                console.warn(`[workspace] Mount "${mount.config.name}": branch pin ${mount.lastMaterializedBranchId} → ` +
+                    `${current.id} ("${current.name}") — current branch linearly continues the last ` +
+                    `materialized branch (out-of-band switch, e.g. repair); disk state is preserved history.`);
+                mount.lastMaterializedBranchId = current.id;
+            }
+        }
     }
     /**
      * Start chokidar watchers and emit workspace:mounted events.
@@ -744,6 +855,7 @@ export class WorkspaceModule {
                     properties: {
                         path: { type: 'string', description: 'Specific path to materialize (optional — defaults to all changed)' },
                         mount: { type: 'string', description: 'Specific mount (optional)' },
+                        force: { type: 'boolean', description: 'Materialize even if the current branch has diverged from the branch last written to disk (default false). Only needed for genuine divergence — descendant branches pass automatically.' },
                     },
                 },
             },
@@ -858,8 +970,17 @@ export class WorkspaceModule {
     /**
      * Resolve a mount-prefixed path (e.g. "tickets/2026-04-22-foo.md") to its
      * absolute filesystem path. Returns null if the mount is unknown or the
-     * resolved path escapes the mount root (path-traversal guard). Public API
-     * for peer modules that need to read workspace files directly.
+     * resolved path escapes the mount root.
+     *
+     * **Lexical containment only.** The guard reasons about `..` segments in the
+     * path string; it knows nothing about what is on disk. A symlink inside the
+     * mount that targets an outside file passes this check, and a caller that
+     * then does `fs.readFile(path)` reads the outside content. Use the returned
+     * path for resolution-only purposes (write targets, nonexistent paths,
+     * display); for reading file content, use {@link readFileFromDisk}, which
+     * enforces the mount's `followSymlinks` policy and canonical containment.
+     *
+     * @deprecated for direct filesystem reads — call `readFileFromDisk()`.
      */
     resolveAbsolutePath(mountPrefixedPath) {
         try {
@@ -1030,72 +1151,97 @@ export class WorkspaceModule {
         }
         return this.validateImageBytes(blob, mountPrefixedPath, maxSize);
     }
-    async readImageFromFilesystem(mount, relativePath, mountPrefixedPath, maxSize) {
+    /**
+     * Open a mount-relative file for reading with the mount boundary enforced on
+     * the *filesystem*, not just the path string:
+     *
+     * 1. `lstat` the lexical path — refuse directories; refuse a final-component
+     *    symlink when the mount does not `followSymlinks`.
+     * 2. Open with `O_NOFOLLOW` where the platform has it (POSIX) so the refusal
+     *    holds against a symlink swapped in between lstat and open; where it
+     *    doesn't (Windows), re-`lstat` after opening instead.
+     * 3. `realpath` both the mount root and the opened path and require canonical
+     *    containment — this is what catches an *intermediate* symlinked
+     *    directory escaping the mount, and a followed symlink whose target lands
+     *    outside, on every platform (junctions included).
+     * 4. Confirm the descriptor and the canonical path are the same inode.
+     *
+     * `inspect` runs right after the descriptor is stat'd and before the
+     * containment work, so callers can impose size policy in the same order the
+     * image reader always has. The returned handle is the caller's to close.
+     */
+    async openContainedFile(mount, relativePath, mountPrefixedPath, inspect) {
         const lexicalPath = resolve(mount.config.path, relativePath);
-        const useNoFollow = !mount.config.followSymlinks && typeof fsConstants.O_NOFOLLOW === 'number';
+        const follow = mount.config.followSymlinks === true;
+        const useNoFollow = !follow && typeof fsConstants.O_NOFOLLOW === 'number';
         let fileInfo;
         try {
             fileInfo = await lstat(lexicalPath);
         }
         catch (err) {
-            if (isErrnoCode(err, 'ENOENT')) {
-                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
+            const code = errnoOf(err);
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                throw new WorkspaceReadError('not_found', `File not found: ${mountPrefixedPath}`, 'lstat', code);
             }
-            throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
+            throw new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}`, 'lstat', code);
         }
         if (fileInfo.isDirectory()) {
-            throw new WorkspaceImageReadError('directory', `Path is a directory: ${mountPrefixedPath}`);
+            throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'lstat');
         }
-        if (fileInfo.isSymbolicLink() && !mount.config.followSymlinks) {
-            throw new WorkspaceImageReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`);
+        if (fileInfo.isSymbolicLink() && !follow) {
+            throw new WorkspaceReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`, 'lstat');
         }
         let realMountRoot;
         try {
             realMountRoot = await realpath(mount.config.path);
         }
-        catch {
-            throw new WorkspaceImageReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}`);
+        catch (err) {
+            throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}`, 'realpath_root', errnoOf(err));
         }
-        let handle = null;
+        let handle;
         try {
             handle = await open(lexicalPath, fsConstants.O_RDONLY | (useNoFollow ? fsConstants.O_NOFOLLOW : 0));
         }
         catch (err) {
-            if (isErrnoCode(err, 'ENOENT')) {
-                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
+            const code = errnoOf(err);
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                throw new WorkspaceReadError('not_found', `File not found: ${mountPrefixedPath}`, 'open', code);
             }
-            if (!mount.config.followSymlinks && isErrnoCode(err, 'ELOOP')) {
-                throw new WorkspaceImageReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`);
+            if (!follow && code === 'ELOOP') {
+                throw new WorkspaceReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`, 'open', code);
             }
-            throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
+            throw new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}`, 'open', code);
         }
         try {
-            const fileStat = await handle.stat();
-            if (fileStat.isDirectory()) {
-                throw new WorkspaceImageReadError('directory', `Path is a directory: ${mountPrefixedPath}`);
+            let fileStat;
+            try {
+                fileStat = await handle.stat();
             }
-            if (!fileStat.isFile()) {
-                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
+            catch (err) {
+                const code = errnoOf(err);
+                throw new WorkspaceReadError('not_found', code === 'ENOENT' ? `File not found: ${mountPrefixedPath}` : `Unable to read file: ${mountPrefixedPath}`, 'fstat', code);
             }
-            if (fileStat.size === 0) {
-                throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
+            if (fileStat.isDirectory()) {
+                throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'fstat');
             }
-            if (fileStat.size > maxSize) {
-                throw new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
+            if (!fileStat.isFile()) {
+                throw new WorkspaceReadError('not_found', `File not found: ${mountPrefixedPath}`, 'fstat');
             }
-            if (!mount.config.followSymlinks && !useNoFollow) {
+            inspect?.(fileStat);
+            if (!follow && !useNoFollow) {
                 let postOpenInfo;
                 try {
                     postOpenInfo = await lstat(lexicalPath);
                 }
                 catch (err) {
-                    if (isErrnoCode(err, 'ENOENT')) {
-                        throw new WorkspaceImageReadError('changed', `Image file changed during read: ${mountPrefixedPath}`);
+                    const code = errnoOf(err);
+                    if (code === 'ENOENT') {
+                        throw new WorkspaceReadError('changed', `File changed during read: ${mountPrefixedPath}`, 'post_lstat', code);
                     }
-                    throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
+                    throw new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}`, 'post_lstat', code);
                 }
                 if (postOpenInfo.isSymbolicLink()) {
-                    throw new WorkspaceImageReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`);
+                    throw new WorkspaceReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`, 'post_lstat');
                 }
             }
             let realFilePath;
@@ -1103,27 +1249,156 @@ export class WorkspaceModule {
                 realFilePath = await realpath(lexicalPath);
             }
             catch (err) {
-                if (isErrnoCode(err, 'ENOENT')) {
-                    throw new WorkspaceImageReadError('changed', `Image file changed during read: ${mountPrefixedPath}`);
+                const code = errnoOf(err);
+                if (code === 'ENOENT') {
+                    throw new WorkspaceReadError('changed', `File changed during read: ${mountPrefixedPath}`, 'realpath', code);
                 }
-                throw new WorkspaceImageReadError('not_found', `Unable to resolve image file: ${mountPrefixedPath}`);
+                throw new WorkspaceReadError('not_found', `Unable to resolve file: ${mountPrefixedPath}`, 'realpath', code);
             }
             if (!isContainedPath(realMountRoot, realFilePath)) {
-                throw new WorkspaceImageReadError('escape', `Symlink escape detected: ${mountPrefixedPath}`);
+                throw new WorkspaceReadError('escape', `Symlink escape detected: ${mountPrefixedPath}`, 'realpath');
             }
             let pathStat;
             try {
                 pathStat = await stat(realFilePath);
             }
             catch (err) {
-                if (isErrnoCode(err, 'ENOENT')) {
-                    throw new WorkspaceImageReadError('changed', `Image file changed during read: ${mountPrefixedPath}`);
+                const code = errnoOf(err);
+                if (code === 'ENOENT') {
+                    throw new WorkspaceReadError('changed', `File changed during read: ${mountPrefixedPath}`, 'stat', code);
                 }
-                throw new WorkspaceImageReadError('not_found', `Unable to stat image file: ${mountPrefixedPath}`);
+                throw new WorkspaceReadError('not_found', `Unable to stat file: ${mountPrefixedPath}`, 'stat', code);
             }
             if (pathStat.dev !== fileStat.dev || pathStat.ino !== fileStat.ino) {
-                throw new WorkspaceImageReadError('changed', `Image file changed during read: ${mountPrefixedPath}`);
+                throw new WorkspaceReadError('changed', `File changed during read: ${mountPrefixedPath}`, 'stat');
             }
+            return { handle, fileStat, realFilePath };
+        }
+        catch (err) {
+            await handle.close();
+            throw err;
+        }
+    }
+    /**
+     * Read a workspace file from disk with the mount boundary enforced on the
+     * filesystem (see {@link openContainedFile}). Public API for peer modules
+     * that read mounted files outside the Chronicle tree — the safe replacement
+     * for `resolveAbsolutePath()` + `fs.readFile()`, whose lexical-only guard let
+     * an in-mount symlink smuggle outside content into context (agent-framework
+     * #129, found via connectome-host #101).
+     *
+     * - Honors the mount's `followSymlinks` policy (default: refuse).
+     * - With symlinks allowed, the canonical target must stay beneath the
+     *   canonical mount root; a sibling-prefix root (`/mount-other`) does not count.
+     * - `maxBytes` performs a bounded prefix read: at most `maxBytes` bytes are
+     *   ever loaded, and `truncated` reports that the file was larger.
+     *
+     * Throws {@link WorkspaceReadError} with a `code` distinguishing unknown
+     * mount, lexical traversal, unavailable mount, missing file, directory,
+     * policy-denied symlink, outside-mount target, and file-changed-during-read.
+     */
+    async readFileFromDisk(mountPrefixedPath, options = {}) {
+        if (options.maxBytes !== undefined && !(Number.isInteger(options.maxBytes) && options.maxBytes >= 0)) {
+            throw new RangeError('readFileFromDisk: maxBytes must be a non-negative integer');
+        }
+        let mount;
+        let relativePath;
+        try {
+            ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const code = message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
+            throw new WorkspaceReadError(code, message, 'parse');
+        }
+        if (!relativePath) {
+            throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'parse');
+        }
+        const { handle, fileStat, realFilePath } = await this.openContainedFile(mount, relativePath, mountPrefixedPath);
+        try {
+            const size = fileStat.size;
+            const cap = options.maxBytes;
+            let bytes;
+            let truncated = false;
+            if (cap !== undefined && size > cap) {
+                truncated = true;
+                bytes = Buffer.alloc(cap);
+                let offset = 0;
+                while (offset < cap) {
+                    const { bytesRead } = await handle.read(bytes, offset, cap - offset, offset);
+                    if (bytesRead === 0)
+                        break;
+                    offset += bytesRead;
+                }
+                if (offset < cap)
+                    bytes = bytes.subarray(0, offset);
+            }
+            else {
+                bytes = await handle.readFile();
+            }
+            return { bytes, size, truncated, mtimeMs: fileStat.mtimeMs, realPath: realFilePath, mount: mount.config.name };
+        }
+        catch (err) {
+            if (err instanceof WorkspaceReadError)
+                throw err;
+            throw new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}`, 'read', errnoOf(err));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /** Map a core read refusal onto the image reader's historical error vocabulary and wording. */
+    imageErrorFromRead(err, mount, mountPrefixedPath) {
+        const p = mountPrefixedPath;
+        switch (err.code) {
+            case 'mount_unavailable':
+                return new WorkspaceImageReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}`);
+            case 'directory':
+                return new WorkspaceImageReadError('directory', `Path is a directory: ${p}`);
+            case 'symlink':
+                return new WorkspaceImageReadError('symlink', `Symlinks are not allowed: ${p}`);
+            case 'escape':
+                return new WorkspaceImageReadError('escape', `Symlink escape detected: ${p}`);
+            case 'changed':
+                return new WorkspaceImageReadError('changed', `Image file changed during read: ${p}`);
+            case 'not_found':
+            default:
+                if (err.message.startsWith('File not found')) {
+                    return new WorkspaceImageReadError('not_found', `File not found: ${p}`);
+                }
+                if (err.stage === 'realpath') {
+                    return new WorkspaceImageReadError('not_found', `Unable to resolve image file: ${p}`);
+                }
+                if (err.stage === 'stat') {
+                    return new WorkspaceImageReadError('not_found', `Unable to stat image file: ${p}`);
+                }
+                return new WorkspaceImageReadError('not_found', `Unable to read image file: ${p}`);
+        }
+    }
+    async readImageFromFilesystem(mount, relativePath, mountPrefixedPath, maxSize) {
+        let opened;
+        try {
+            opened = await this.openContainedFile(mount, relativePath, mountPrefixedPath, (fileStat) => {
+                if (fileStat.size === 0) {
+                    throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
+                }
+                if (fileStat.size > maxSize) {
+                    throw new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
+                }
+            });
+        }
+        catch (err) {
+            if (err instanceof WorkspaceImageReadError)
+                throw err;
+            if (err instanceof WorkspaceReadError)
+                throw this.imageErrorFromRead(err, mount, mountPrefixedPath);
+            if (isErrnoCode(err, 'ENOENT')) {
+                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
+            }
+            throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
+        }
+        const { handle } = opened;
+        try {
             const bytes = await handle.readFile();
             return this.validateImageBytes(bytes, mountPrefixedPath, maxSize);
         }
@@ -1136,7 +1411,7 @@ export class WorkspaceModule {
             throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
         }
         finally {
-            await handle?.close();
+            await handle.close();
         }
     }
     /**
@@ -1641,26 +1916,13 @@ export class WorkspaceModule {
                 initialSyncDone: mount.initialSyncDone,
                 currentBranch: currentBranch.name,
                 lastMaterializedBranch: mount.lastMaterializedBranchId,
-                canMaterialize: !mount.lastMaterializedBranchId || mount.lastMaterializedBranchId === currentBranch.id,
+                canMaterialize: this.mountMaterializeBlockReason(store, mount) === null,
             };
         }
         return { success: true, data: status };
     }
     async handleMaterialize(input) {
         const store = this.getStore();
-        // Guard: only materialize on the active branch
-        if (this.config.materializeOnlyActiveBranch !== false) {
-            const currentBranch = store.currentBranch();
-            for (const mount of this.mounts.values()) {
-                if (mount.lastMaterializedBranchId && mount.lastMaterializedBranchId !== currentBranch.id) {
-                    return {
-                        success: false,
-                        error: `Cannot materialize: current branch "${currentBranch.name}" differs from last materialized branch. Switch back or set materializeOnlyActiveBranch: false.`,
-                        isError: true,
-                    };
-                }
-            }
-        }
         const allWritten = [];
         let mountsToMaterialize;
         if (input.mount) {
@@ -1675,6 +1937,35 @@ export class WorkspaceModule {
                 .filter(([, m]) => m.config.mode === 'read-write')
                 .map(([name, mount]) => ({ name, mount }));
         }
+        // Branch guard, scoped to the mounts actually being materialized: a
+        // linear continuation (current branch descends from the pinned branch at
+        // or after the pinned seq) passes; genuine divergence refuses unless
+        // force. One mount's stale pin must never block another mount.
+        const blocked = [];
+        for (const { name, mount } of mountsToMaterialize) {
+            const reason = this.mountMaterializeBlockReason(store, mount);
+            if (!reason)
+                continue;
+            if (input.force) {
+                // Disk reflects another line of history, so an incremental diff from
+                // the pinned seq is meaningless — reset tracking and re-materialize
+                // the full tree, exactly like materializeMount() after a deliberate
+                // branch switch.
+                mount.lastMaterializedSeq = 0;
+                mount.lastMaterializedBranchId = null;
+            }
+            else {
+                blocked.push({ mount: name, reason });
+            }
+        }
+        mountsToMaterialize = mountsToMaterialize.filter(({ name }) => !blocked.some((b) => b.mount === name));
+        if (mountsToMaterialize.length === 0 && blocked.length > 0) {
+            return {
+                success: false,
+                error: `Cannot materialize: ${blocked.map((b) => `[${b.mount}] ${b.reason}`).join('; ')}`,
+                isError: true,
+            };
+        }
         for (const { name, mount } of mountsToMaterialize) {
             let paths;
             if (input.path) {
@@ -1688,8 +1979,12 @@ export class WorkspaceModule {
                 watcher?.suppress(p);
                 allWritten.push({ mount: name, path: p });
             }
-            // Track which branch we materialized on
-            if (written.length > 0) {
+            // Track which branch we materialized on. Re-pin on a clean empty
+            // materialize too (previously-pinned mount, nothing pending): disk
+            // already reflects the current branch's tree, and leaving the old pin
+            // would keep force required forever after a cross-branch materialize
+            // that happened to write nothing.
+            if (written.length > 0 || mount.lastMaterializedBranchId !== null) {
                 mount.lastMaterializedBranchId = store.currentBranch().id;
             }
         }
@@ -1698,6 +1993,7 @@ export class WorkspaceModule {
             data: {
                 materialized: allWritten,
                 count: allWritten.length,
+                ...(blocked.length > 0 ? { skipped: blocked } : {}),
             },
         };
     }