@animalabs/agent-framework 0.22.2 → 0.22.4

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

@@ -38,8 +38,8 @@
  * a wrong adoption.
  */
 import { candidateOf, sameCandidate, sameRootIdentity, } from './disk-agreement.js';
-import { ROOT_REPLACED, fingerprintVouches, locateRoot, looksBinary, observePath, provenAbsent, readHead, readPath, sniffImageMime, walkScope, } from './observe.js';
-import { EffectFailed, chainOf, syncDirectories, unlinkContained, writeContained } from './effects.js';
+import { IGNORED, OTHER_MOUNT, ROOT_REPLACED, fingerprintVouches, ignoreBeneath, inOtherMount, locateRoot, looksBinary, observePath, passedOverAt, passedOverBetween, provenAbsent, readHead, readPath, sniffImageMime, walkScope, } from './observe.js';
+import { EffectFailed, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
 const ABSENT = { kind: 'absent' };
 export const WALK_CAP = 5000;
 function diskCandidate(d) {
@@ -52,7 +52,58 @@ function diskCandidate(d) {
 function agreedFromDisk(d) {
     if (d.kind !== 'file')
         return { kind: 'absent' };
-    return { kind: 'content', hash: d.hash, size: d.size, ...(d.fp ? { fp: d.fp } : {}) };
+    return { kind: 'content', hash: d.hash, size: d.size, ...(d.mode !== undefined ? { mode: d.mode } : {}), ...(d.fp ? { fp: d.fp } : {}) };
+}
+/** The file-type bits git records with a regular file's mode. */
+const REGULAR_FILE = 0o100000;
+/** A tree entry's mode for permission bits: with the regular-file type bits, as git records one. */
+export function treeMode(perm) {
+    return REGULAR_FILE | (perm & 0o777);
+}
+/**
+ * The mode a tree entry takes for disk's permission bits, or, where disk's
+ * aren't observed, the entry's own. With neither, the placeholder an entry
+ * without a recorded mode has (see entryMode).
+ */
+function treeModeOf(perm, s) {
+    if (perm !== undefined)
+        return { mode: treeMode(perm) };
+    if (s?.mode !== undefined)
+        return { mode: treeMode(s.mode) };
+    return { mode: 0o644 };
+}
+/**
+ * The permission bits a tree entry records, or undefined when it records
+ * none. An entry without the file-type bits was written before modes were
+ * recorded, which wrote 0o644 whatever disk had: a placeholder, not a mode.
+ */
+export function entryMode(mode) {
+    return (mode & 0o170000) === REGULAR_FILE ? mode & 0o777 : undefined;
+}
+/** The store's side of a tree entry. */
+export function storeSide(entry) {
+    if (!entry)
+        return null;
+    const mode = entryMode(entry.mode);
+    return { hash: entry.blobHash, size: entry.size, ...(mode !== undefined ? { mode } : {}) };
+}
+/**
+ * Where disk and the store hold the same bytes, what their modes ask for.
+ * A mode the store doesn't record agrees with any, and takes disk's
+ * (`fill`). The store's mode goes to disk (`push`) only where the evidence
+ * shows disk still has the mode they last agreed on; otherwise disk's mode
+ * is taken in as a change (`adopt`): disk changed it, or nothing says which
+ * side did, and an unknown never moves disk.
+ */
+function modeAction(disk, store, agreed) {
+    if (store === undefined)
+        return 'fill';
+    if (store === disk)
+        return undefined;
+    return agreed !== undefined && agreed === disk ? 'push' : 'adopt';
+}
+function octal(mode) {
+    return `0${mode.toString(8).padStart(3, '0')}`;
 }
 function inScope(path, scope) {
     if (scope.kind === 'paths')
@@ -76,7 +127,7 @@ async function learnDisk(mount, path, tracked, opts) {
     const p = tracked.p;
     const trusted = (fp) => mount.ctimeTrustedDev !== null && fp.dev === mount.ctimeTrustedDev;
     if (!opts.rehash && p?.kind === 'content' && fingerprintVouches(p.fp, seen.fp, trusted(seen.fp))) {
-        return { kind: 'file', hash: p.hash, size: seen.size, mtimeMs: seen.mtimeMs, fp: p.fp ?? null, ingestible: null };
+        return { kind: 'file', hash: p.hash, size: seen.size, mtimeMs: seen.mtimeMs, ...(mount.modesObserved ? { mode: seen.mode } : {}), fp: p.fp ?? null, ingestible: null };
     }
     const nothingTracked = p === undefined && !tracked.hasStore && !tracked.hasIntent;
     if (nothingTracked && seen.size > mount.view.maxFileSize) {
@@ -96,6 +147,7 @@ async function learnDisk(mount, path, tracked, opts) {
         hash: read.hash,
         size: read.size,
         mtimeMs: read.mtimeMs,
+        ...(mount.modesObserved ? { mode: read.mode } : {}),
         // A fingerprint is recorded only where it can later vouch for the bytes.
         fp: trusted(read.fp) ? read.fp : null,
         ingestible,
@@ -129,10 +181,66 @@ function keepStoreSide(hasStore, bi) {
 function settleAdoption(p, s) {
     const sc = s ? { kind: 'content', hash: s.hash } : ABSENT;
     if (sameCandidate(sc, p.expect)) {
-        return p.expect.kind === 'absent' ? { kind: 'absent' } : { kind: 'content', hash: p.expect.hash, size: s.size };
+        // Where modes are observed, the adoption took disk's mode with its bytes,
+        // so the entry's mode is the one they agreed on, but for an adoption that
+        // took the mode a stopped push of ours meant the old bytes to have: its
+        // entry holds that mode while disk holds the push's narrowed one, which a
+        // later sync then takes in. Where modes aren't observed, the entry's mode
+        // is the store's own, and the evidence records none.
+        return p.expect.kind === 'absent'
+            ? { kind: 'absent' }
+            : { kind: 'content', hash: p.expect.hash, size: s.size, ...(s.mode !== undefined ? { mode: s.mode } : {}) };
     }
     return p.prior ?? 'forget';
 }
+/**
+ * What's in the way, and the way out, when disk's shape keeps a push from a
+ * path: no push writes a file over a directory or unlinks one, unlinks
+ * anything but a regular file or a followed symlink to one, or writes below
+ * a file or a symlink the walk won't take (`writeContained`,
+ * `unlinkContained`), forced or not. Null for any other reason, which is
+ * passed on as it is.
+ */
+function inTheWay(reason, deletion) {
+    // Observation's words for what a deletion never unlinks, which the unlink
+    // refuses in the same words.
+    if (deletion && (reason === 'not a regular file' || reason === 'a symlink to a directory, not walked')) {
+        const what = reason === 'not a regular file'
+            ? 'a pipe, socket or device at this path, or a symlink to one'
+            : 'a symlink to a directory at this path';
+        return `disk has ${what}, and no push unlinks it, forced or not — ask whoever runs this host if it should go`;
+    }
+    if (reason === 'a directory') {
+        return deletion
+            ? 'disk has a directory at this path, and no push unlinks one, forced or not — if it should go, move or remove it on disk'
+            : 'disk has a directory at this path, and no push writes a file over one, forced or not — ' +
+                'move or remove that directory on disk and materialize again, or write the file under another path';
+    }
+    // A deletion below a file finds nothing there to unlink, so only a write
+    // meets this one.
+    if (reason === 'a parent path is not a directory') {
+        return 'disk has a file or a symlink where this path needs a directory, and no push writes below one, forced or not — ' +
+            'move or remove it on disk and materialize again, or write the file under another path';
+    }
+    return null;
+}
+/**
+ * The forced way out the refusal of a disk copy that couldn't be verified
+ * names, if any. A forced push skips the verification, so it gets past the
+ * note only where its effect can go on. A file the module can't read (EACCES)
+ * is overwritten, or unlinked, where disk lets the workspace write it, or
+ * unlink it, which a read's EACCES doesn't show: force is named on that
+ * condition. No other note names force: a forced push stops at some (a
+ * symlink the mount doesn't follow, what isn't a regular file, a parent it
+ * can't use); another writer still at the file ("the file changed while it
+ * was read") is answered by materializing again; and the rest aren't known
+ * to pass.
+ */
+function forcedWay(note, deletion, forced) {
+    if (note === 'cannot open (EACCES)')
+        return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
+    return '';
+}
 /**
  * The synchronous precondition of every workspace mutation: evidence owed a
  * barrier is made durable first, and an adoption left pending on the
@@ -151,13 +259,32 @@ export function settleAdoptionBeforeMutation(store, agreement, mount, path) {
     if (p?.kind !== 'pending' || p.effect !== 'adopt' || p.branchId !== store.currentBranch().id)
         return;
     const entry = store.treeGet(mount.treeStateId, path);
-    const settled = settleAdoption(p, entry ? { hash: entry.blobHash, size: entry.size } : null);
+    const settled = settleAdoption(p, entry ? { hash: entry.blobHash, size: entry.size, ...(entryMode(entry.mode) !== undefined ? { mode: entryMode(entry.mode) } : {}) } : null);
     if (settled === 'forget')
         agreement.forget(mount.name, path);
     else
         agreement.set(mount.name, path, settled, { afterCommittedState: true });
     agreement.barrier();
 }
+/**
+ * What a push of ours that stopped partway left on disk, read by its own
+ * modes (Pending's `modes`): the new bytes at `from & to` or `to` were meant
+ * to have `to`; the old bytes at `from & to`, narrower than `from`, still
+ * have `from` as theirs. New bytes at `from` are a push's only where
+ * `from & to` is `from`: a push that narrows does so before its bytes, so
+ * otherwise they were given `from` since. Undefined where disk shows
+ * anything else: no push of ours, or a mode set since it stopped.
+ */
+function pushedMode(p, dc, d) {
+    const m = p.modes;
+    if (p.effect !== 'disk' || m === undefined || d.kind !== 'file' || d.mode === undefined)
+        return undefined;
+    const narrowed = m.from & m.to;
+    if (sameCandidate(dc, p.expect))
+        return d.mode === narrowed || d.mode === m.to ? m.to : undefined;
+    const prior = p.prior ? candidateOf(p.prior) : null;
+    return prior && sameCandidate(dc, prior) && narrowed !== m.from && d.mode === narrowed ? m.from : undefined;
+}
 /**
  * Resolve a pending intent against what was observed. Returns the evidence
  * the rule should use, and whether that resolution should be recorded.
@@ -169,11 +296,24 @@ function resolvePending(p, dc, s, d, branchId) {
         if (sameCandidate(dc, p.expect)) {
             // Our own effect shows on disk, but nothing proves it durable: decided
             // on, never recorded. Only a push whose barriers succeed completes it.
+            // Where disk's mode is one of the push's own, the push that completes
+            // it gives the store's mode there.
             const shown = p.expect.kind === 'absent' ? { kind: 'absent' } : agreedFromDisk(d);
-            return { p: shown, unconfirmed: true };
+            return { p: shown, unconfirmed: true, ...(pushedMode(p, dc, d) !== undefined ? { ownMode: true } : {}) };
         }
-        if (priorCandidate && sameCandidate(dc, priorCandidate))
+        if (priorCandidate && sameCandidate(dc, priorCandidate)) {
+            // The push narrowed the mode and stopped before its bytes: disk's mode
+            // is the push's, so the rule decides from it, and the next push writes
+            // the bytes at it and then widens to the store's. The old bytes are
+            // never given the store's mode. Nothing is recorded: the intent, with
+            // the modes that map disk's narrowed one back to the old bytes' own,
+            // stays, carried by a push that goes on with it (pushPaths), until a
+            // push completes it or a sync adopts disk's copy.
+            if (prior.kind === 'content' && d.kind === 'file' && pushedMode(p, dc, d) !== undefined) {
+                return { p: { ...prior, mode: d.mode } };
+            }
             return { p: prior, record: prior };
+        }
         // A write whose prior was unknown left no file: it never created one (a
         // partial write leaves a file behind), so P is as unknown as before.
         if (!prior && dc.kind === 'absent' && p.expect.kind === 'content')
@@ -210,9 +350,12 @@ function adoptDisk(d, s) {
         return { state: 'synced', ...(s ? { adopt: 'remove', op: 'deleted' } : {}), p: { kind: 'absent' }, intent: {} };
     }
     // Disk agreeing with the store is disk's state already, whatever the file
-    // is: a binary or oversize file the workspace holds stays held.
-    if (s && s.hash === d.hash)
-        return { state: 'synced', p: agreedFromDisk(d), intent: {} };
+    // is: a binary or oversize file the workspace holds stays held. Its mode
+    // is disk's too.
+    if (s && s.hash === d.hash) {
+        const mode = d.mode === undefined ? undefined : s.mode === undefined ? 'fill' : s.mode !== d.mode ? 'adopt' : undefined;
+        return { state: 'synced', p: agreedFromDisk(d), intent: {}, ...(mode ? { mode } : {}), ...(mode === 'adopt' ? { op: 'modified' } : {}) };
+    }
     if (d.ingestible)
         return { state: 'synced', adopt: 'ingest', op: s ? 'modified' : 'created', p: agreedFromDisk(d), intent: {} };
     return { state: 'disk-only', ...(s ? { adopt: 'drop', op: 'deleted' } : {}), p: 'forget', intent: {} };
@@ -243,12 +386,22 @@ function decide(d, s, pIn, bi, branchId, adopt) {
     if (adopt) {
         // What a path sync gives up is exactly what a sync without a path would
         // have kept of the workspace's own (a draft, a deletion, a conflict's
-        // workspace side), and the verdict says which.
-        const taken = adoptDisk(d, s);
+        // workspace side), and the verdict says which. Where a push of ours
+        // stopped partway, disk's mode is the push's: the store takes the one
+        // the push meant those bytes to have, and the evidence keeps disk's, so
+        // a later push moves disk there.
+        const meant = pIn?.kind === 'pending' ? pushedMode(pIn, dc, d) : undefined;
+        const taken = adoptDisk(meant === undefined ? d : { ...d, mode: meant }, s);
+        if (meant !== undefined) {
+            if (taken.p !== undefined && taken.p !== 'forget' && taken.p.kind === 'content')
+                taken.p = agreedFromDisk(d);
+            if (taken.adopt === 'ingest' || taken.mode !== undefined)
+                taken.diskMode = meant;
+        }
         // A give-up is an adoption, or the intent it clears: a deletion or a
         // conflict given up for a disk copy the workspace can't hold changes no
         // tree entry, and is listed all the same.
-        if (taken.adopt || (bi && taken.intent !== undefined)) {
+        if (taken.adopt || taken.mode === 'adopt' || (bi && taken.intent !== undefined)) {
             const kept = decide(d, s, pIn, bi, branchId, false);
             if (WORKSPACE_KEPT.has(kept.state))
                 taken.discards = kept.state;
@@ -261,6 +414,9 @@ function decide(d, s, pIn, bi, branchId, adopt) {
     // verdict below records newer evidence.
     let p = pIn;
     let resolution;
+    // Evidence a resolution decides from without recording it: a stopped
+    // push's narrowing, whose intent stays (resolvePending).
+    let unrecorded;
     let uncaptured = false;
     if (p?.kind === 'pending') {
         const resolved = resolvePending(p, dc, s, d, branchId);
@@ -269,13 +425,19 @@ function decide(d, s, pIn, bi, branchId, adopt) {
             // follows from that, and nothing is recorded — no completion, no
             // agreement, no branch-intent change — until a push confirms it.
             const state = sameCandidate(dc, sc) ? 'synced' : bi?.conflict ? 'conflict' : keepStoreSide(s !== null, bi);
-            return { state, note: UNCONFIRMED_NOTE, unconfirmed: true };
+            return {
+                state, note: UNCONFIRMED_NOTE, unconfirmed: true,
+                ...(resolved.ownMode ? { ownMode: true } : {}),
+            };
         }
         p = resolved.p;
         resolution = resolved.record;
+        if (resolution === undefined && p !== undefined && (p.kind === 'content' || p.kind === 'absent'))
+            unrecorded = p;
         uncaptured = resolved.uncaptured === true;
     }
-    const verdict = (v) => (resolution && v.p === undefined ? { ...v, p: resolution } : v);
+    const verdict = (v) => (resolution && v.p === undefined ? { ...v, p: resolution }
+        : unrecorded && v.p === undefined && v.prior === undefined ? { ...v, prior: unrecorded } : v);
     // Agreement settles everything, a recorded conflict included.
     if (sameCandidate(dc, sc)) {
         const settles = bi?.tombstone || bi?.conflict || bi?.origin ? { intent: {} } : {};
@@ -291,11 +453,23 @@ function decide(d, s, pIn, bi, branchId, adopt) {
         const recorded = p?.kind === 'content' ? p : null;
         // Re-record only when P says something else, or a fresh fingerprint can
         // replace one that no longer vouches. A fresh one exists only where it's
-        // trusted, so both are judged as trusted here.
-        const stale = !recorded || recorded.hash !== agreed.hash || recorded.size !== agreed.size ||
+        // trusted, so both are judged as trusted here. Evidence a resolution left
+        // unrecorded, a stopped push's narrowing, is stale too: the agreement
+        // replaces that push's intent, and the mode rule gives the store's mode.
+        const stale = unrecorded !== undefined || !recorded || recorded.hash !== agreed.hash || recorded.size !== agreed.size || recorded.mode !== agreed.mode ||
             (agreed.fp !== undefined && fingerprintVouches(agreed.fp, agreed.fp, true) &&
                 !fingerprintVouches(recorded.fp, agreed.fp, true));
-        return verdict({ state: 'synced', ...(stale ? { p: agreed } : {}), ...settles });
+        const mode = agreed.mode === undefined ? undefined : modeAction(agreed.mode, s.mode, recorded?.mode);
+        if (mode === 'push') {
+            return verdict({
+                state: 'workspace-draft',
+                mode,
+                note: `the workspace's mode (${octal(s.mode)}) differs from disk's (${octal(agreed.mode)}): materialize to apply it`,
+                ...(stale ? { p: agreed } : {}),
+                ...settles,
+            });
+        }
+        return verdict({ state: 'synced', ...(mode ? { mode } : {}), ...(mode === 'adopt' ? { op: 'modified' } : {}), ...(stale ? { p: agreed } : {}), ...settles });
     }
     // A recorded conflict stays until it is resolved explicitly or disk and store converge.
     if (bi?.conflict)
@@ -437,12 +611,43 @@ async function gather(store, agreement, mount, scope, opts) {
             gathered.facts.set(path, { kind: 'unobserved', reason: rootUnavailable });
             continue;
         }
+        // What the mount passes over by design stays unobserved by a pass that
+        // names no path, however it reaches it, so no listing's absence proves a
+        // copy there gone. In another mount's directory, no pass of this mount
+        // observes anything, named or not.
+        // Beneath a directory a by-design rule covers, a pass that isn't named
+        // observes nothing. A path a rule covers by its own name is observed as a
+        // walk observes it: passed over where the walk lists it, and absent where
+        // the walk lists its directory without it; a pass that reaches it by its
+        // path alone, as a listing, glob or grep naming it does, passes over it.
+        // A pass that names its scope, as a sync naming a path and a file tool's
+        // pass on the path it acts on do, sets aside only what covers the scope,
+        // at it or above it, as its walk does (#276): a directory passed over by
+        // design beneath a named directory stays passed over, and so does what
+        // lies beneath it.
+        let byDesign;
+        if (inOtherMount(path, mount.view.others)) {
+            byDesign = OTHER_MOUNT;
+        }
+        else if (!opts.named) {
+            const slash = path.lastIndexOf('/');
+            const above = slash < 0 ? undefined : passedOverAt(path.slice(0, slash), mount.view.ignore, mount.view.others);
+            const own = above === undefined && !walk ? passedOverAt(path, mount.view.ignore, mount.view.others) : undefined;
+            byDesign = above ?? own;
+        }
+        else if (scope.kind === 'dir') {
+            byDesign = passedOverBetween(scope.dir, path, ignoreBeneath(scope.dir, mount.view.ignore), mount.view.others);
+        }
+        if (byDesign !== undefined) {
+            gathered.facts.set(path, { kind: 'unobserved', reason: byDesign });
+            continue;
+        }
         if (walk && provenAbsent(walk, path)) {
             gathered.facts.set(path, { kind: 'absent' });
             continue;
         }
-        if (walk?.others.get(path) === 'ignored by the mount') {
-            gathered.facts.set(path, { kind: 'unobserved', reason: 'ignored by the mount' });
+        if (walk?.others.get(path) === IGNORED) {
+            gathered.facts.set(path, { kind: 'unobserved', reason: IGNORED });
             continue;
         }
         if (walk && !walk.files.has(path) && !walk.othersTaken.has(path)) {
@@ -527,8 +732,7 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
     result.branchId = branchId;
     const planned = [];
     for (const [path, d] of facts) {
-        const entry = store.treeGet(mount.treeStateId, path);
-        const s = entry ? { hash: entry.blobHash, size: entry.size } : null;
+        const s = storeSide(store.treeGet(mount.treeStateId, path));
         const p = agreement.get(mount.name, path);
         const bi = mount.intents.get(path);
         const verdict = decide(d, s, p, bi, branchId, opts.adopt?.(path) === true);
@@ -561,13 +765,20 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
         const v = x.verdict;
         if (v.adopt === 'ingest' && x.d.kind === 'file' && x.d.ingestible) {
             const blobHash = store.storeBlob(x.d.ingestible, 'text/plain');
-            store.treeSet(mount.treeStateId, x.path, { blobHash, size: x.d.ingestible.byteLength, mode: 0o644 });
+            store.treeSet(mount.treeStateId, x.path, { blobHash, size: x.d.ingestible.byteLength, ...treeModeOf(v.diskMode ?? x.d.mode, x.s) });
             committed = true;
         }
         else if ((v.adopt === 'remove' || v.adopt === 'drop') && x.s) {
             store.treeRemove(mount.treeStateId, x.path);
             committed = true;
         }
+        else if ((v.mode === 'fill' || v.mode === 'adopt') && x.d.kind === 'file' && x.s) {
+            // The same bytes, with disk's mode. A fill records a mode where the
+            // entry had none, which is no change: an undo or a branch whose entry
+            // still has none agrees with any mode, so neither reads it as one.
+            store.treeSet(mount.treeStateId, x.path, { blobHash: x.s.hash, size: x.s.size, ...treeModeOf(v.diskMode ?? x.d.mode, x.s) });
+            committed = true;
+        }
         if (v.conflict) {
             const record = { kind: v.conflict, at: Date.now(), disk: counterpartOf(store, x.d) };
             mount.intents.update(x.path, (cur) => ({ ...cur, conflict: record }));
@@ -578,10 +789,11 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
             mount.intents.put(x.path, v.intent);
             committed = true;
         }
-        if (v.op && v.adopt)
-            result.ops.push({ path: x.path, op: v.op });
+        const changed = v.adopt !== undefined || v.mode === 'adopt';
+        if (v.op && changed)
+            result.ops.push({ path: x.path, op: v.op, ...(v.adopt === undefined ? { modeOnly: true } : {}) });
         if (v.discards)
-            result.discarded.push({ path: x.path, was: v.discards, ...(v.op && v.adopt ? { op: v.op } : {}) });
+            result.discarded.push({ path: x.path, was: v.discards, ...(v.op && changed ? { op: v.op } : {}) });
     }
     // 4. Completions and agreements, after the commits they assert are synced —
     // this pass's, and any earlier tool write's an agreement rests on.
@@ -658,9 +870,17 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
             // A link's own region hides only what lies beneath it: the link itself
             // is reported by path, with its own reason.
             const hides = tracked.some((p) => (region.kind !== 'symlink' && p === region.path) || p.startsWith(region.path + '/'));
-            if (region.kind === 'error' || region.kind === 'cap' || hides)
+            // A scope passed over whole is the answer to the pass that asked for
+            // it, so it's always named. Another mount's directory met beneath the
+            // scope is passed over by design even where this mount's tree holds
+            // copies there: no tool of this mount syncs, pushes or clears them
+            // (listings show them, naming their holder), so naming the directory
+            // as unreached would never clear.
+            const wholeScope = scope.kind === 'dir' && scope.dir !== '' && region.path === scope.dir;
+            const unreached = hides && region.reason !== OTHER_MOUNT;
+            if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope)
                 result.incomplete.push({ path: region.path, reason: region.reason });
-            // An ignored name that hides nothing tracked is reported nowhere else:
+            // A name passed over by design that hides nothing tracked is reported nowhere else:
             // counted, so a sync that says 0 also says what it didn't look at
             // (agent-framework #276). A symlink region isn't counted: a link the
             // walk took is a candidate the pass reports by path, taken through the
@@ -673,11 +893,15 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
     }
     return result;
 }
+/** Why a push skips a path in another mount's directory nested in its own. */
+export const NOT_PUSHED_IN_OTHER_MOUNT = "it lies in another mount's directory, which no push of this mount writes";
 /**
  * Make disk hold the store's version of each path, under the same rule:
  * drafts are written, agreement is left alone, conflicts and unverifiable
  * disk copies are refused unless `force`, and a workspace deletion reaches
  * disk only with `applyDeletions` (with `force` too when disk changed since).
+ * Forced or not, nothing but a regular file, or a followed symlink to one, is
+ * written over or unlinked (effects.ts).
  * A path nothing has evidence about is written only when `named`.
  * A path whose earlier push shows on disk unconfirmed is pushed again, so its
  * completion rests on barriers that succeeded.
@@ -696,7 +920,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     agreement.ensureReconciled();
     if (agreement.needsBarrier)
         agreement.barrier(); // as a pass does: nothing decided from unsynced evidence
-    const result = { written: [], unchanged: [], deleted: [], skipped: [], pendingDeletions: [] };
+    const result = { written: [], unchanged: [], deleted: [], skipped: [], modesKept: [], pendingDeletions: [] };
     if (mount.readOnly)
         return result;
     // A root that isn't available takes no writes, forced or not: restoring the
@@ -708,6 +932,20 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             result.skipped.push({ path, reason: root.reason });
         return result;
     }
+    // Another mount's directory nested in this one is that mount's: no push
+    // of this mount writes or deletes a path in it, forced or not. (On a mount
+    // that follows links, a link of this mount's that leads there is read as
+    // this mount's own path; on one that doesn't, the link is refused.)
+    if (mount.view.others.length > 0) {
+        const own = [];
+        for (const path of paths) {
+            if (inOtherMount(path, mount.view.others))
+                result.skipped.push({ path, reason: NOT_PUSHED_IN_OTHER_MOUNT });
+            else
+                own.push(path);
+        }
+        paths = own;
+    }
     const plans = [];
     // Observe disk.
     const facts = new Map();
@@ -737,11 +975,20 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     result.sequence = store.currentSequence();
     let recorded = false;
     for (const [path, d] of facts) {
-        const entry = store.treeGet(mount.treeStateId, path);
-        const s = entry ? { hash: entry.blobHash, size: entry.size } : null;
+        const s = storeSide(store.treeGet(mount.treeStateId, path));
         const p = agreement.get(mount.name, path);
         const bi = mount.intents.get(path);
         const v = decide(d, s, p, bi, branchId, false);
+        // The ways out a refusal names, as materialize takes them: a deletion
+        // reaches disk only with applyDeletions.
+        const again = s ? 'materialize again' : 'materialize again with applyDeletions';
+        // Where disk has deleted a file the workspace holds, a sync takes the
+        // deletion, which removes the workspace's copy, and a forced push writes
+        // the workspace's copy back: there is no disk copy to adopt or overwrite.
+        const gone = s !== null && d.kind === 'absent';
+        const forced = !s ? 'materialize it with force and applyDeletions to delete it'
+            : gone ? "materialize it with force to write the workspace's copy back" : 'materialize it with force to overwrite it';
+        const takeDisk = gone ? "sync this path to take disk's deletion, which removes the workspace's copy" : 'sync this path to adopt the disk version';
         // What the effect may find: what this observation saw, unless forced.
         const expect = opts.force || d.kind === 'unobserved' || d.kind === 'unhashed'
             ? { kind: 'any' }
@@ -756,18 +1003,51 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
                 result.skipped.push({
                     path,
                     reason: 'stale copy: disk changed since it last agreed with the workspace, which did not — ' +
-                        'sync this path to adopt the disk version, or pass force to overwrite it',
+                        `${takeDisk}, or ${forced}`,
                 });
                 continue;
             }
             const priorP = p && (p.kind === 'absent' || p.kind === 'content') ? p : null;
             const blob = store.getBlob(s.hash);
-            if (blob)
-                plans.push({ path, kind: 'write', blob, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect });
+            const forcedMode = mount.modesObserved && s.mode !== undefined && s.mode !== (d.kind === 'file' ? d.mode : undefined) ? s.mode : undefined;
+            const agreedMode = priorP?.kind === 'content' ? priorP.mode : undefined;
+            if (blob) {
+                plans.push({
+                    path, kind: 'write', blob, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect,
+                    ...(forcedMode !== undefined ? { apply: forcedMode } : {}),
+                    ...(forcedMode !== undefined && d.kind === 'file' && agreedMode !== d.mode ? { overDisk: true } : {}),
+                    ...(s.mode !== undefined ? { storeMode: s.mode } : {}),
+                    // Refused over disk's mode, the completion records what an unforced
+                    // write would: the mode disk last agreed with.
+                    ...(agreedMode !== undefined ? { priorMode: agreedMode } : {}),
+                    ...(d.kind === 'file' && d.mode !== undefined ? { seenMode: d.mode } : {}),
+                });
+            }
             else
                 result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
             continue;
         }
+        if (v.mode === 'adopt' && s && d.kind === 'file') {
+            // Disk's mode changed since it last agreed, on the bytes the store
+            // holds, and the store's didn't. A sync takes it in. Recording disk's
+            // mode here would read as the store's change, which the next push
+            // would revert; forced, disk takes the store's mode, as forced bytes do.
+            if (!opts.force) {
+                // modeAction adopts where disk changed the mode since they agreed, and
+                // where nothing records a mode they agreed on.
+                const agreedMode = p?.kind === 'content' ? p.mode : undefined;
+                result.skipped.push({
+                    path,
+                    reason: (agreedMode === undefined
+                        ? `disk's mode (${octal(d.mode)}) differs from the workspace's (${octal(s.mode)}), and nothing records which side changed it`
+                        : `disk's mode (${octal(d.mode)}) changed since it last agreed with the workspace's (${octal(s.mode)})`) +
+                        ' — sync this path to take disk\'s mode in, or materialize this path with force to apply the workspace\'s',
+                });
+                continue;
+            }
+            plans.push({ path, kind: 'chmod', mode: s.mode, hash: s.hash, size: s.size, prior: null, before: p, expect, overDisk: true });
+            continue;
+        }
         // Whatever the verdict learned about disk (an agreement, a resolved
         // intent) is recorded before anything is pushed over it, and the root it
         // was learned under before that (once per mount), as a pass does.
@@ -782,8 +1062,22 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
         // The prior a new intent carries is the last confirmed evidence: for a
         // path whose earlier push is unconfirmed, that push's own prior, never
         // the bytes it wrote.
-        const known = v.unconfirmed ? p.prior ?? undefined : v.p === 'forget' ? undefined : v.p !== undefined ? v.p : p;
+        const known = v.unconfirmed ? p.prior ?? undefined : v.p === 'forget' ? undefined : v.p !== undefined ? v.p : v.prior ?? p;
         const prior = known && (known.kind === 'absent' || known.kind === 'content') ? known : null;
+        // A push that re-plans over our own narrowing push, stopped before its
+        // bytes, plans from disk's narrowed mode (the verdict's prior, which
+        // resolvePending leaves unrecorded), as above, and goes on as that push:
+        // its intent carries the stopped push's prior, the old bytes at their own
+        // mode, never the mode it narrowed them to, and modes from that mode, so a
+        // stop of this push too reads disk's narrowed mode as the push's own.
+        // Past the adoptions handled above, a verdict carries a prior with P still
+        // pending only from that narrowing, whose push recorded its modes.
+        const stopped = v.prior !== undefined && p?.kind === 'pending' ? p : undefined;
+        if (v.mode === 'push' && s && d.kind === 'file') {
+            // Forced, disk takes the store's mode whatever it holds now, as it takes its bytes.
+            plans.push({ path, kind: 'chmod', mode: s.mode, ...(opts.force ? {} : { from: d.mode }), hash: s.hash, size: s.size, prior, before: agreement.get(mount.name, path), expect });
+            continue;
+        }
         if (v.state === 'synced' && !v.unconfirmed) {
             if (v.intent !== undefined) {
                 mount.intents.put(path, v.intent);
@@ -795,7 +1089,25 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
         }
         if (v.state === 'unverified') {
             if (!opts.force) {
-                result.skipped.push({ path, reason: `cannot verify disk copy (${v.note ?? 'not observed'}) — fix it and materialize again, or pass force to overwrite it` });
+                // An intent that can't be read is the one note fixing doesn't
+                // answer: nothing is decided over it until a sync of the path
+                // replaces it (decide()), and a sync replaces it only where it sees
+                // disk's copy, so a copy it can't see is named first. For the rest,
+                // fixing what the note names holds, and forcedWay says where force
+                // does too. Where disk has deleted the file, that sync takes the
+                // deletion.
+                const sync = gone
+                    ? "sync this path to take disk's deletion, which removes the workspace's copy and replaces the intent"
+                    : 'sync this path to adopt the disk version, which replaces the intent';
+                result.skipped.push({
+                    path,
+                    reason: bi?.unreadable !== undefined
+                        ? d.kind === 'absent' || d.kind === 'file'
+                            ? `${v.note} — ${sync}`
+                            : `${v.note}, and disk's copy can't be verified (${d.kind === 'unobserved' ? d.reason : 'not hashed'}) — once it can be, ${sync}`
+                        : inTheWay(v.note, !s) ??
+                            `cannot verify disk copy (${v.note ?? 'not observed'}) — fix it and ${again}${forcedWay(v.note, !s, forced)}`,
+                });
                 continue;
             }
         }
@@ -815,15 +1127,20 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             }
             result.skipped.push({
                 path,
-                reason: noEvidence
-                    ? `disk holds a different copy, and nothing records which is newer (conflict: ${kind}) — ` +
-                        'sync this path to adopt the disk version, or materialize this path with force to overwrite it'
-                    : kind === 'interrupted'
-                        ? 'disk holds bytes that match neither what was being written there nor what disk last agreed with ' +
-                            '(conflict: interrupted), as a write that failed or was cut off partway leaves — check the file, then ' +
-                            'pass force to write the workspace copy over it, or sync this path to adopt the disk copy as it is'
-                        : `stale copy: disk changed since it last agreed with the workspace (conflict: ${kind}) — ` +
-                            'sync this path to adopt the disk version, or pass force to overwrite it',
+                // Whatever was recorded, a disk with no copy now is answered for what
+                // it holds; a path with no evidence still needs its push named.
+                reason: gone
+                    ? `disk has no copy of this file (conflict: ${kind}) — ${takeDisk}, or ` +
+                        `materialize ${noEvidence ? 'this path' : 'it'} with force to write the workspace's copy back`
+                    : noEvidence
+                        ? `disk holds a different copy, and nothing records which is newer (conflict: ${kind}) — ` +
+                            `sync this path to adopt the disk version, or materialize this path with force ${s ? 'to overwrite it' : 'and applyDeletions to delete it'}`
+                        : kind === 'interrupted'
+                            ? 'disk holds bytes that match neither what was being written there nor what disk last agreed with ' +
+                                '(conflict: interrupted), as a write that failed or was cut off partway leaves — check the file, then ' +
+                                `${forced}, or sync this path to adopt the disk copy as it is`
+                            : `stale copy: disk changed since it last agreed with the workspace (conflict: ${kind}) — ` +
+                                `sync this path to adopt the disk version, or ${forced}`,
             });
             continue;
         }
@@ -853,7 +1170,14 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
                 continue;
             }
             if (!opts.applyDeletions) {
-                result.pendingDeletions.push(path);
+                // A deletion no push makes, forced or not (inTheWay), is refused for
+                // that, as an unforced push refuses it, rather than left for
+                // applyDeletions, which couldn't make it either.
+                const lasting = inTheWay(v.note, true);
+                if (lasting !== null)
+                    result.skipped.push({ path, reason: lasting });
+                else
+                    result.pendingDeletions.push(path);
                 continue;
             }
             if (d.kind === 'absent')
@@ -866,18 +1190,61 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
             continue;
         }
-        plans.push({ path, kind: 'write', blob, hash: s.hash, prior, before: agreement.get(mount.name, path), expect });
+        // The store's mode goes to disk with its bytes where the file is new,
+        // the push is forced, or disk still has the mode they last agreed on. A
+        // push that completes our own unconfirmed one, whose bytes landed, is a
+        // push like any other: it gives the store's mode where disk shows one of
+        // the stopped push's own (pushedMode) or the one they last agreed on, and
+        // keeps any other, set since it stopped (Ada-1017, room-203 #131062,
+        // #131518). A mode disk changed since stays, and so does the evidence
+        // that it did, up to the moment of the write.
+        const dm = d.kind === 'file' ? d.mode : undefined;
+        const priorMode = prior?.kind === 'content' ? prior.mode : undefined;
+        const own = v.unconfirmed === true && v.ownMode === true;
+        const apply = mount.modesObserved && s.mode !== undefined && s.mode !== dm &&
+            (dm === undefined || opts.force === true || own || priorMode === dm) ? s.mode : undefined;
+        plans.push({
+            path, kind: 'write', blob, hash: s.hash, prior: stopped ? stopped.prior : prior, before: agreement.get(mount.name, path), expect,
+            // With no mode in the store's entry, its `to` is the mode the push
+            // leaves, the one the stopped push narrowed to: it claims none it lacks.
+            ...(stopped ? { ownModes: { from: stopped.modes.from, to: s.mode ?? (stopped.modes.from & stopped.modes.to) } } : {}),
+            ...(apply !== undefined ? { apply } : {}),
+            ...(apply !== undefined && dm !== undefined && opts.force !== true ? { from: dm } : {}),
+            // Forced over a mode disk changed: without force, the bytes would keep it.
+            ...(apply !== undefined && dm !== undefined && priorMode !== dm && !own ? { overDisk: true } : {}),
+            ...(s.mode !== undefined ? { storeMode: s.mode } : {}),
+            ...(priorMode !== undefined ? { priorMode } : {}),
+            ...(dm !== undefined ? { seenMode: dm } : {}),
+        });
     }
     // 1. Durable intents before any disk effect, the root they write under first.
+    // A chmod announces none: it leaves the bytes as they are. Stopped before
+    // its completion, it leaves disk at the store's mode or still at the one
+    // the evidence agreed, and the next observation decides from that: synced
+    // and recorded, or pushed again. Nothing is lost either way. A forced
+    // chmod has no guard: stopped before it, disk keeps whatever mode it found,
+    // which the next observation reads as disk's, and forced again, it applies
+    // the store's.
     if (plans.length > 0)
         agreement.recordRootIdentity(mount.name, root.identity);
-    plans.forEach((step, i) => {
+    const announced = plans.filter((step) => step.kind !== 'chmod');
+    announced.forEach((step, i) => {
         agreement.intend(mount.name, step.path, {
             effect: 'disk',
             prior: step.prior,
             expect: step.kind === 'write' ? { kind: 'content', hash: step.hash } : ABSENT,
             branchId,
-        }, { durable: i === plans.length - 1 });
+            // A write whose plan gives a mode (`apply`) records the modes it may
+            // leave, so a stop is read by them: the mode it saw, or for a file it
+            // creates the one it creates it at, and the one it gives. A file a
+            // forced push creates at its entry's mode with no mode planned records
+            // none. One that goes on as our own stopped narrowing records that
+            // push's, from the old bytes' own mode, whether or not it gives a mode
+            // itself.
+            ...(step.kind === 'write' && step.ownModes !== undefined ? { modes: step.ownModes }
+                : step.kind === 'write' && step.apply !== undefined
+                    ? { modes: { from: step.seenMode ?? step.apply, to: step.apply } } : {}),
+        }, { durable: i === announced.length - 1 });
     });
     // 2. Effects, each bound at its point of use.
     const effected = [];
@@ -885,8 +1252,51 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
         opts.beforeEffect?.(step.path);
         try {
             if (step.kind === 'write') {
-                await writeContained(mount.view, mount.rootReal, step.path, step.blob, step.expect);
-                effected.push({ step, dirs: chainOf(step.path) });
+                const { perm, widenRefused, modeKept } = await writeContained(mount.view, mount.rootReal, step.path, step.blob, step.expect, step.apply, step.from, step.overDisk === true, 
+                // Where modes go unobserved, nothing is applied, a created file's included.
+                mount.modesObserved ? step.storeMode : undefined);
+                effected.push({ step, dirs: chainOf(step.path), mode: perm, widenRefused, modeKept });
+            }
+            else if (step.kind === 'chmod') {
+                // An inode change, made durable by the file's own fsync.
+                const { refused, narrowing } = await chmodContained(mount.view, mount.rootReal, step.path, step.mode, step.expect, step.from);
+                // A chmod announces no intent, so a refused one leaves the evidence
+                // as planning read it, unless it says otherwise below.
+                if (refused && narrowing && !step.overDisk) {
+                    // A narrowing of the store's own change that the kernel refused
+                    // stays owed, as a write's does: taking disk's wider mode in would
+                    // let a later write put new bytes out at it.
+                    result.skipped.push({
+                        path: step.path,
+                        reason: `not given the workspace's mode (${octal(step.mode)}): the kernel refused to narrow it, as it does for a file another user owns, ` +
+                            'so it stays owed: a retry is refused the same way until the file\'s owner or an administrator narrows it',
+                    });
+                    continue;
+                }
+                if (refused && step.overDisk) {
+                    // Forced over a mode disk changed, or one nothing records: the
+                    // path is as it was before the push, so a sync takes disk's mode
+                    // in, as it would have without force.
+                    result.skipped.push({
+                        path: step.path,
+                        reason: `not given the workspace's mode (${octal(step.mode)}): the kernel refused the chmod, so disk keeps its mode, and a sync takes it in`,
+                    });
+                    continue;
+                }
+                if (refused) {
+                    // A widening of the store's own change that the kernel refused:
+                    // disk keeps its mode, and the evidence records none, so a sync
+                    // takes disk's in by the rule for an unknown rather than owing a
+                    // mode this process can never give.
+                    agreement.set(mount.name, step.path, { kind: 'content', hash: step.hash, size: step.size });
+                    recorded = true;
+                    result.skipped.push({
+                        path: step.path,
+                        reason: `not given the workspace's mode (${octal(step.mode)}): the kernel refused the chmod, and a sync takes disk's mode in`,
+                    });
+                    continue;
+                }
+                effected.push({ step, dirs: [] });
             }
             else {
                 // Its directory is synced whether this unlink removed the entry or
@@ -901,7 +1311,8 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
                 // exactly what it was, whatever kind that was.
                 agreement.restore(mount.name, step.path, step.before);
                 recorded = true;
-                result.skipped.push({ path: step.path, reason: `not ${step.kind === 'write' ? 'written' : 'unlinked'}: ${failure.message}` });
+                const why = inTheWay(failure.message, step.kind === 'unlink') ?? failure.message;
+                result.skipped.push({ path: step.path, reason: `not ${step.kind === 'unlink' ? 'unlinked' : step.kind === 'chmod' ? 'given the workspace\'s mode' : 'written'}: ${why}` });
             }
             else {
                 // No completion: the intent stays pending, and the next observation
@@ -917,7 +1328,8 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     // 4. Completions. P is physical and global. Branch intent belongs to the
     // branch this push planned on: it is settled only while that branch is
     // still selected, and otherwise by convergence when the branch returns.
-    for (const { step, dirs } of effected) {
+    for (const { step, dirs, mode: written, widenRefused, modeKept } of effected) {
+        const mode = mount.modesObserved ? written : undefined;
         const failed = dirs.find((dir) => unsynced.has(dir));
         if (failed !== undefined) {
             result.skipped.push({
@@ -927,11 +1339,64 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             });
             continue;
         }
-        const value = step.kind === 'write' ? { kind: 'content', hash: step.hash, size: step.blob.byteLength } : { kind: 'absent' };
+        // The mode the evidence records: the one the push gave the file, if the
+        // file has it; disk's own, where the store records none or the same; and
+        // otherwise the one disk last agreed with, so a mode disk changed since
+        // reads as disk's. (Where modes go unobserved, the evidence's writer
+        // records none.)
+        // A widening of the workspace's own change that the kernel refused
+        // records none: a sync takes disk's mode in, rather than owing one this
+        // process can never give. Forced over a mode disk changed, or one nothing
+        // records (overDisk), any refused chmod ends where an unforced write
+        // would: the evidence records the mode disk last agreed with, if any, and
+        // a sync takes disk's mode in.
+        const agreedMode = step.kind === 'chmod'
+            ? step.mode
+            : step.kind === 'write'
+                ? widenRefused && !step.overDisk
+                    ? undefined
+                    : step.apply !== undefined && step.apply === mode
+                        ? mode
+                        : step.storeMode === undefined || step.storeMode === mode ? mode : step.priorMode
+                : undefined;
+        const value = step.kind === 'unlink'
+            ? { kind: 'absent' }
+            : { kind: 'content', hash: step.hash, size: step.kind === 'write' ? step.blob.byteLength : step.size, ...(agreedMode !== undefined ? { mode: agreedMode } : {}) };
         agreement.set(mount.name, step.path, value);
         recorded = true;
+        // Bytes written where the kernel refused the mode, or where disk's mode
+        // changed since it last agreed, keep disk's mode, and the push says so
+        // beside what it wrote: the bytes reached disk, so it's no refusal.
+        if (step.kind === 'write' && widenRefused && mode !== undefined) {
+            result.modesKept.push({
+                path: step.path,
+                reason: `written, its mode left at ${octal(mode)}: the kernel refused the chmod, ` +
+                    `so the workspace's (${octal(step.apply ?? step.storeMode ?? mode)}) isn't given, and a sync takes disk's mode in`,
+            });
+        }
+        else if (step.kind === 'write' && modeKept && mode !== undefined) {
+            // Forced over a mode disk changed, and refused: the bytes are written
+            // at it, the evidence records it as an unforced write's would.
+            result.modesKept.push({
+                path: step.path,
+                reason: `written, its mode left at ${octal(mode)}: the kernel refused to narrow it ` +
+                    `${narrowedTo(mode & (step.apply ?? mode), step.apply ?? mode)}, so disk keeps its mode, and a sync takes it in`,
+            });
+        }
+        else if (step.kind === 'write' && mode !== undefined && step.storeMode !== undefined && mode !== step.storeMode) {
+            result.modesKept.push({
+                path: step.path,
+                reason: (step.priorMode === undefined
+                    ? `written, keeping disk's mode (${octal(mode)}), which differs from the workspace's (${octal(step.storeMode)}), and nothing records which side changed it`
+                    : `written, keeping disk's mode (${octal(mode)}), which changed since it last agreed with the workspace's (${octal(step.storeMode)})`) +
+                    ' — sync this path to take disk\'s mode in, or materialize this path with force to apply the workspace\'s',
+            });
+        }
         const planned = store.currentBranch().id === branchId;
-        if (step.kind === 'write') {
+        if (step.kind === 'chmod') {
+            result.written.push(step.path);
+        }
+        else if (step.kind === 'write') {
             if (planned)
                 mount.intents.update(step.path, (cur) => { const next = { ...cur }; delete next.conflict; delete next.origin; return next; });
             result.written.push(step.path);