@animalabs/agent-framework 0.27.0 → 0.28.0

package/src/modules/workspace/answers.ts

@@ -0,0 +1,133 @@
+import { constants } from 'node:os';
+import { boundedErrorMessage } from '../../error-message.js';
+
+export class Refusal extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'Refusal';
+  }
+}
+
+export function didNothing(tool: string, body: string, to?: string): string {
+  return `The ${tool} did nothing${to !== undefined ? ` to ${JSON.stringify(to)}` : ''}: ${body}`;
+}
+
+export function onlyTheHost(can: string): string {
+  return `Calling again won't change that; whoever runs this host can ${can}.`;
+}
+
+// Node's own message for a failed system call names the host's absolute
+// path, so an agent gets the code's plain words instead.
+export function errnoWords(code: string | undefined): string {
+  switch (code) {
+    case 'ENOENT': return 'nothing is there';
+    case 'ENOTDIR': return 'a part of the path isn\'t a directory';
+    case 'EACCES': return 'permission denied';
+    case 'EPERM': return 'not permitted';
+    case 'EISDIR': return 'it\'s a directory';
+    case 'EEXIST': return 'something is already there';
+    case 'ENOTEMPTY': return 'the directory isn\'t empty';
+    case 'EXDEV': return 'the move would cross from one filesystem to another';
+    case 'ELOOP': return 'too many symlinks, or a loop of them';
+    case 'ENAMETOOLONG': return 'a name too long for the filesystem';
+    case 'ENOSPC': return 'no space left on the disk';
+    case 'EDQUOT': return 'the disk quota is used up';
+    case 'EFBIG': return 'the file would be too large for the filesystem';
+    case 'EROFS': return 'the filesystem is read-only';
+    case 'EIO': return 'an input/output error on the disk';
+    case 'EBUSY': case 'ETXTBSY': return 'the file is busy';
+    case 'EMFILE': case 'ENFILE': return 'too many files are open on this host';
+    case 'ENOMEM': return 'this host is out of memory';
+    case 'EAGAIN': case 'EWOULDBLOCK': return 'the system was busy';
+    case 'EINTR': return 'the system call was interrupted';
+    case 'ETIMEDOUT': return 'the system call timed out';
+    case 'ESTALE': return 'a stale network file handle';
+    case 'EINVAL': return 'the system refused an argument as invalid';
+    case undefined: return 'an error the system gave no code for';
+    default: return `a system error (${code})`;
+  }
+}
+
+export function hostFix(code: string | undefined): string | undefined {
+  switch (code) {
+    case 'ENOSPC': return 'free space on its disk';
+    case 'EFBIG': return 'raise the limit on a file\'s size, or keep the files on a filesystem that holds larger ones';
+    case 'EDQUOT': return 'raise or free the disk quota';
+    case 'EROFS': return 'make the filesystem writable';
+    case 'EIO': return 'check the disk';
+    case 'EACCES': case 'EPERM': return 'change the permissions';
+    case 'EMFILE': case 'ENFILE': return 'raise the limit on open files';
+    case 'ELOOP': return 'fix the symlinks on that path';
+    case 'ENOMEM': return 'free memory';
+    default: return undefined;
+  }
+}
+
+const PASSING = new Set(['EIO', 'EMFILE', 'ENFILE', 'ENOMEM']);
+const AS_DISK_IS = new Set(['EISDIR', 'ENOTDIR', 'EEXIST', 'ENOTEMPTY', 'EXDEV']);
+
+export function systemWords(code: string | undefined, error: unknown): string {
+  return code !== undefined ? errnoWords(code) : boundedErrorMessage(error);
+}
+
+export function errnoWayOn(code: string | undefined, otherwise = 'Calling again may work.', hostsName = false): string {
+  if (code === 'ENAMETOOLONG' && hostsName) return onlyTheHost("give the mount's directory a shorter path");
+  const fix = hostFix(code);
+  if (fix !== undefined) {
+    return code !== undefined && PASSING.has(code) ? `Calling again may work; if it fails the same way, whoever runs this host can ${fix}.` : onlyTheHost(fix);
+  }
+  if (code === 'ENAMETOOLONG') return "Calling again won't change that; a shorter name would.";
+  if (code !== undefined && AS_DISK_IS.has(code)) return "Calling again won't change that while disk holds what it does there.";
+  return otherwise;
+}
+
+const OS_ERRNO = new Map<number, string>();
+for (const [name, number] of Object.entries(constants.errno)) if (!OS_ERRNO.has(number)) OS_ERRNO.set(number, name);
+
+// Chronicle's store errors carry the code GenericFailure, and an I/O
+// failure's message is "IO error: " and Rust's std::io::Error, which ends
+// with the OS error's number: an errno on POSIX, a Win32 code on Windows.
+export function errnoCode(error: unknown): string | undefined {
+  const code = typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined;
+  if (typeof code === 'string' && /^E[A-Z0-9]+$/.test(code)) return code;
+  const os = error instanceof Error && process.platform !== 'win32' ? /^IO error: .*\(os error (\d+)\)$/s.exec(error.message) : null;
+  return os !== null ? OS_ERRNO.get(Number(os[1])) : undefined;
+}
+
+const CHANGING = new Set(['write', 'edit', 'edit_many', 'delete', 'materialize', 'sync']);
+
+export function changesFiles(tool: string): boolean {
+  return CHANGING.has(tool);
+}
+
+export const ROOT_RECHECK = "Calling again may work; if it fails the same way, whoever runs this host can check the mount's directory and its path.";
+
+export const ROOT_UNCHECKED = "Calling again won't change that while the mount's directory is gone from its path, and checks it afresh otherwise; whoever runs this host can check the directory and its path.";
+
+export const AWAITS_REOPEN = "The workspace can't check its files against disk until its store is reopened, so calling again won't change that; whoever runs this host can reopen it with a restart.";
+
+export interface Unexpected {
+  stored?: 'unknown' | 'not' | 'held';
+  said?: string;
+  reopen?: boolean;
+  look?: string;
+}
+
+export function unexpectedAnswer(tool: string, subject: string | undefined, error: unknown, how: Unexpected = {}): string {
+  const stored = how.stored ?? 'unknown';
+  const code = errnoCode(error);
+  const words = how.said ?? systemWords(code, error);
+  const before = stored !== 'not' ? '' : tool === 'edit_many' ? ', before any of its edits was stored' : `, before the ${tool === 'delete' ? 'deletion' : tool} was stored`;
+  const head = `The ${tool}${subject !== undefined ? ` of ${subject}` : ''} stopped on an error the workspace didn't expect${before}: ${words.replace(/\.$/, '')}.`;
+  if (stored === 'held') {
+    return `${head} ${subject !== undefined ? subject : 'Its files'} already held what the call gave, so ${subject !== undefined ? 'it holds' : 'they hold'} that in the workspace either way.`;
+  }
+  const changing = stored === 'unknown' && CHANGING.has(tool);
+  if (how.reopen === true) return [head, AWAITS_REOPEN, ...(changing ? ["Whether it changed anything isn't known until then."] : [])].join(' ');
+  const look = !changing ? null
+    : how.look ?? (subject === undefined ? 'read its files to see what they hold now' : `read ${subject} to see what the workspace holds there now`);
+  const on = code !== undefined
+    ? errnoWayOn(code, "Calling again may work; if it fails the same way, whoever runs this host can find the whole error in this host's log.")
+    : "Calling again may work; if it fails the same way, whoever runs this host can find the whole error in this host's log.";
+  return [head, ...(look !== null ? [`Whether it changed anything isn't known: ${look}.`] : []), on].join(' ');
+}

package/src/modules/workspace/branch-intent.ts

@@ -19,6 +19,7 @@
  */
 
 import type { JsStore } from '@animalabs/chronicle';
+import { storedBytes } from './sync.js';
 
 export type ConflictKind =
   /** Disk, workspace and the last agreement all differ. */
@@ -56,9 +57,11 @@ export interface BranchIntent {
   origin?: 'store';
   conflict?: ConflictRecord;
   /**
-   * Why a recorded intent can't be read (its blob missing from the store, or
-   * not an intent): a tombstone or conflict it held is unknown, never absent.
-   * Never written; a put replaces the damaged record.
+   * Why a recorded intent can't be read (its blob missing from the store,
+   * a blob chronicle can't read, or not an intent): a tombstone or conflict
+   * it held is unknown, never absent.
+   * Never written; a put replaces the damaged record, unless it puts the same
+   * contents over a blob file chronicle can't read, which chronicle keeps.
    */
   unreadable?: string;
 }
@@ -70,8 +73,10 @@ function isEmpty(intent: BranchIntent): boolean {
 
 /** A recorded intent's blob, read; a damaged one says why it can't be. */
 function readIntent(store: JsStore, blobHash: string): BranchIntent {
-  const blob = store.getBlob(blobHash);
-  if (!blob) return { unreadable: "its record's blob is missing from the store" };
+  const stored = storedBytes(store, blobHash);
+  if ('missing' in stored) return { unreadable: "its record's blob is missing from the store" };
+  if ('unreadable' in stored) return { unreadable: `its record's blob can't be read from the store (${stored.unreadable})` };
+  const blob = stored.bytes;
   try {
     const parsed = JSON.parse(blob.toString('utf-8')) as unknown;
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as BranchIntent;

package/src/modules/workspace/direct-write.ts

@@ -56,19 +56,27 @@ import type { BigIntStats } from 'node:fs';
 import { lstat, open, realpath } from 'node:fs/promises';
 import { relative, sep } from 'node:path';
 import { refusedLanding } from './effects.js';
+import { ROOT_RECHECK, errnoWayOn, errnoWords, onlyTheHost, systemWords } from './answers.js';
 import {
   type CheckedDir,
   type MountView,
   NONBLOCK,
+  LEAVES_MOUNT,
+  NOT_A_DIRECTORY,
   NOT_FOLLOWED,
   OUTSIDE_PARENT,
+  ROOT_UNAVAILABLE,
   checkDir,
   checkRoot,
   errno,
+  rootAbsence,
   nameOf,
   parentOf,
 } from './observe.js';
 
+const DIRECTORY_THERE = 'A file can\'t be written over a directory; give another path.';
+const NOT_REGULAR_THERE = onlyTheHost('put a regular file there');
+
 /** An open that follows no link at the path, where the platform has one. */
 const NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
 
@@ -119,7 +127,28 @@ export const sameIdentity = (a: FileIdentity, b: FileIdentity): boolean =>
 export class FileChanged extends Error {}
 
 /** Why a direct write didn't happen, in words for its answer; disk is as it was. */
-export class WriteRefused extends Error {}
+export class WriteRefused extends Error {
+  constructor(message: string, readonly wayOn: string | null = null, readonly errno?: string) {
+    super(message);
+  }
+}
+
+const AFRESH = 'Calling again checks it afresh.';
+
+const NAME_ITS_OWN = "Calling again won't change that; if you know the file it leads to, name that file by its own path.";
+
+function rootWayOn(code: string | undefined): string {
+  return code === 'ENOENT' || code === 'ENOTDIR' ? onlyTheHost("put the mount's directory back at its path") : errnoWayOn(code, ROOT_RECHECK, true);
+}
+
+function refusedWayOn(reason: string, code?: string, hostsName = false): string | null {
+  if (reason === ROOT_UNAVAILABLE) return rootWayOn(code);
+  if (code !== undefined) return errnoWayOn(code, undefined, hostsName);
+  if (reason === NOT_FOLLOWED) return NAME_ITS_OWN;
+  if (reason === OUTSIDE_PARENT || reason === LEAVES_MOUNT) return "Calling again won't change that; the workspace writes only inside its mounts.";
+  if (reason === NOT_A_DIRECTORY) return "Calling again won't change that while something other than a directory stands where the path needs one; another path, or removing what stands there, would.";
+  return null;
+}
 
 /** A file's new bytes staged beside it, ready to be renamed over it (stageContained). */
 export interface Staged {
@@ -170,7 +199,8 @@ async function directoryOf(view: MountView, rootReal: string, rel: string, makeD
   const checked = await checkDir(view, rootReal, parentOf(rel), { create: makeDirectory });
   if (checked.kind === 'checked') return checked.dir;
   if (checked.kind === 'absent') throw new FileChanged(rel);
-  throw new WriteRefused(checked.outside ? OUTSIDE_PARENT : checked.reason);
+  const reason = checked.outside ? OUTSIDE_PARENT : checked.reason;
+  throw new WriteRefused(reason, refusedWayOn(reason, checked.errno));
 }
 
 /**
@@ -193,29 +223,34 @@ export async function stageContained(
   { makeDirectory = false }: { makeDirectory?: boolean } = {},
 ): Promise<Staged> {
   const root = await checkRoot(view, rootReal);
-  if ('reason' in root) throw new WriteRefused(root.reason);
+  if ('reason' in root) {
+    const code = root.errno ?? await rootAbsence(rootReal);
+    throw new WriteRefused(root.reason, rootWayOn(code), code);
+  }
   let parent = await directoryOf(view, rootReal, rel, makeDirectory);
   let path = parent.at(nameOf(rel));
   let info = await lstat(path, { bigint: true }).catch((err: unknown) => {
     if (errno(err) === 'ENOENT') return null;
-    throw new WriteRefused(`cannot stat the file (${errno(err) ?? String(err)})`);
+    throw new WriteRefused(`cannot stat the file (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
   });
   if (info?.isSymbolicLink()) {
-    if (!view.followSymlinks) throw new WriteRefused(NOT_FOLLOWED);
+    if (!view.followSymlinks) throw new WriteRefused(NOT_FOLLOWED, NAME_ITS_OWN);
     // A followed link stands for the file it leads to, as a read takes it:
     // the write goes there, judged where it lands, and the link stays.
     const real = await realpath(path).catch((err: unknown) => {
-      throw new WriteRefused(errno(err) === 'ENOENT' ? "a symlink whose target doesn't exist" : `cannot resolve the symlink (${errno(err) ?? String(err)})`);
+      throw errno(err) === 'ENOENT'
+        ? new WriteRefused("a symlink whose target doesn't exist", onlyTheHost('remove the link or make it lead to a file'))
+        : new WriteRefused(`cannot resolve the symlink (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
     });
     const leaves = await refusedLanding(view, rootReal, rel, real);
-    if (leaves !== null) throw new WriteRefused(leaves);
+    if (leaves !== null) throw new WriteRefused(leaves, refusedWayOn(leaves));
     const realRel = relativeTo(rootReal, real);
     parent = await directoryOf(view, rootReal, realRel, false);
     path = parent.at(nameOf(realRel));
     info = await lstat(path, { bigint: true }).catch((err: unknown) => {
       // Gone since realpath found it: another writer's change.
       if (errno(err) === 'ENOENT') throw new FileChanged(rel);
-      throw new WriteRefused(`cannot stat the file the symlink leads to (${errno(err) ?? String(err)})`);
+      throw new WriteRefused(`cannot stat the file the symlink leads to (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
     });
     if (info.isSymbolicLink()) throw new FileChanged(rel);
   } else {
@@ -223,10 +258,10 @@ export async function stageContained(
     // lands where the mount may not act: in a nested mount's directory, or
     // on a file its own include leaves out (refusedLanding).
     const leaves = await refusedLanding(view, rootReal, rel, path);
-    if (leaves !== null) throw new WriteRefused(leaves);
+    if (leaves !== null) throw new WriteRefused(leaves, refusedWayOn(leaves));
   }
-  if (info?.isDirectory()) throw new WriteRefused('a directory');
-  if (info && !info.isFile()) throw new WriteRefused('not a regular file');
+  if (info?.isDirectory()) throw new WriteRefused('a directory', DIRECTORY_THERE);
+  if (info && !info.isFile()) throw new WriteRefused('not a regular file', NOT_REGULAR_THERE);
   // A fixed-length name, so a file whose own name is near the 255-byte limit can still be replaced.
   const temp = parent.at(`${STAGED_PREFIX}${randomUUID()}`);
   let made = false;
@@ -266,8 +301,8 @@ export async function stageContained(
     // A staged file that couldn't be made names the directory: a push's
     // write in place needs only the file, and this one needs both.
     throw new WriteRefused(made
-      ? `cannot write the staged file beside it (${errno(err) ?? String(err)})`
-      : `cannot make the staged file in its directory (${errno(err) ?? String(err)}): a direct write needs to write the file's directory as well as the file`);
+      ? `cannot write the staged file beside it (${systemWords(errno(err), err)})`
+      : `cannot make the staged file in its directory (${systemWords(errno(err), err)}): a direct write needs to write the file's directory as well as the file`, errnoWayOn(errno(err)), errno(err));
   }
 }
 
@@ -278,7 +313,7 @@ export async function stageContained(
  */
 export async function placedStill(staged: Staged): Promise<void> {
   if (!(await staged.root.stillHere())) throw new WriteRefused(ROOT_MOVED);
-  if (!(await staged.parent.stillHere())) throw new WriteRefused('the directory changed since it was checked');
+  if (!(await staged.parent.stillHere())) throw new WriteRefused('the directory changed since it was checked', AFRESH);
 }
 
 /**
@@ -309,13 +344,13 @@ export function checkUnchanged(staged: Staged, expected: { identity: FileIdentit
   try {
     now = lstatSync(staged.path, { bigint: true });
   } catch (err) {
-    if (errno(err) !== 'ENOENT') throw new WriteRefused(`cannot check that it hadn't changed (${errno(err) ?? String(err)})`);
+    if (errno(err) !== 'ENOENT') throw new WriteRefused(`cannot check that it hadn't changed (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
     if (expected !== null) throw new FileChanged(staged.path);
     return;
   }
-  if (now.isSymbolicLink()) throw new WriteRefused('it became a symlink while this call was being applied');
-  if (now.isDirectory()) throw new WriteRefused('a directory');
-  if (!now.isFile()) throw new WriteRefused('not a regular file');
+  if (now.isSymbolicLink()) throw new WriteRefused('it became a symlink while this call was being applied', AFRESH);
+  if (now.isDirectory()) throw new WriteRefused('a directory', DIRECTORY_THERE);
+  if (!now.isFile()) throw new WriteRefused('not a regular file', NOT_REGULAR_THERE);
   // As a push's write, which opens the file for writing, would be refused:
   // the rename needs only the directory's permission, and would replace a
   // file its owner made read-only.
@@ -329,9 +364,9 @@ export function checkUnchanged(staged: Staged, expected: { identity: FileIdentit
       throw new FileChanged(staged.path);
     }
     if (code === 'EACCES' || code === 'EPERM') {
-      throw new WriteRefused(`a file the host's process may not write (${code}): its mode or owner keeps that process out, and calling again is refused until the file's owner, or whoever runs the host, changes that`);
+      throw new WriteRefused(`a file the host's process may not write (${errnoWords(code)}): its mode or owner keeps that process out, and calling again is refused until the file's owner, or whoever runs the host, changes that`);
     }
-    throw new WriteRefused(`cannot check that the host's process may write it (${code ?? String(err)})`);
+    throw new WriteRefused(`cannot check that the host's process may write it (${systemWords(code, err)})`, errnoWayOn(code), code);
   }
   if (expected === null) return;
   let bytes: Buffer;
@@ -353,7 +388,7 @@ export function checkUnchanged(staged: Staged, expected: { identity: FileIdentit
     // ELOOP: a link put at the path since the lstat; EAGAIN: a pipe, with a
     // writer and nothing in it yet. Either is another writer's change.
     if (errno(err) === 'ENOENT' || errno(err) === 'ELOOP' || errno(err) === 'EAGAIN') throw new FileChanged(staged.path);
-    throw new WriteRefused(`cannot check that it hadn't changed (${errno(err) ?? String(err)})`);
+    throw new WriteRefused(`cannot check that it hadn't changed (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
   }
   if (!sameIdentity(identityOf(after), expected.identity) || !bytes.equals(expected.bytes)) throw new FileChanged(staged.path);
 }
@@ -384,13 +419,13 @@ export function renameInto(staged: Staged): void {
     // The staged file is still the one this call wrote, not another put at its name.
     const temp = lstatSync(staged.temp, { bigint: true });
     if (!temp.isFile() || !sameIdentity(identityOf(temp), staged.tempIdentity)) {
-      throw new WriteRefused('another writer replaced the staged copy of the new text before it could be renamed over the file, which is as it was');
+      throw new WriteRefused('another writer replaced the staged copy of the new text before it could be renamed over the file, which is as it was', 'Calling again writes it afresh.');
     }
     otherLinks = otherLinksAt(staged.path);
     renameSync(staged.temp, staged.path);
   } catch (err) {
     if (err instanceof WriteRefused) throw err;
-    throw new WriteRefused(`cannot rename the staged file over it (${errno(err) ?? (err instanceof Error ? err.message : String(err))})`);
+    throw new WriteRefused(`cannot rename the staged file over it (${systemWords(errno(err), err)})`, errnoWayOn(errno(err)), errno(err));
   }
   // Set once the rename has happened, so a count never stands for a split that didn't.
   staged.otherLinks = otherLinks;

package/src/modules/workspace/disk-agreement.ts

@@ -10,14 +10,14 @@
  * intent — tombstones, store origin, conflicts — lives in BranchIntents and
  * rewinds with the tree.
  *
- * P is evidence about one directory, so each mount also records the identity
- * (device and inode) of the root that evidence was gathered under. A root
- * that isn't that directory any more (an unmounted drive whose mountpoint is
- * now empty, a replaced directory) is an unavailable mount, never a disk on
- * which every file was deleted; only an explicit acceptance takes it, and
- * that starts its evidence afresh. A place, where a walk stopped (`walks`),
- * binds no root: it only says where the next walk starts, in whatever
- * directory the root is by then.
+ * P is evidence about one directory, so each mount also records the identity of
+ * the root that evidence was gathered under (sameRootIdentity says when two
+ * name the same directory). A root that isn't that directory any more (an
+ * unmounted drive whose mountpoint is now empty, a replaced directory) is an
+ * unavailable mount, never a disk on which every file was deleted; only an
+ * explicit acceptance takes it, and that starts its evidence afresh. A place,
+ * where a walk stopped (`walks`), binds no root: it only says where the next
+ * walk starts, in whatever directory the root is by then.
  *
  * Every transition is write-ahead (see reconcile.ts): an `intent` entry
  * (`pending`, with the prior value and the expected one) is durable before the
@@ -33,9 +33,18 @@
  * succeed, since its completion releases a draft's protection.
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { resolve } from 'node:path';
 import type { JsStore } from '@animalabs/chronicle';
 import { RecordJournal } from '../../record-journal.js';
+import { Refusal, onlyTheHost } from './answers.js';
+
+const UNTIL_REOPENED = "the workspace can't check its files against disk until its store is reopened";
+const REOPEN = onlyTheHost('reopen it with a restart');
+
+export class EvidenceUnavailable extends Refusal {}
+
+export const callGate = new AsyncLocalStorage<{ passed: boolean }>();
 
 /** Everything `stat` says about a file that can vouch for unchanged bytes. */
 export interface Fingerprint {
@@ -94,10 +103,15 @@ export interface Interrupted {
 
 export type Physical = Agreed | Pending | Interrupted;
 
-/** Which directory a mount root is: its device and inode, as decimal strings. */
+/**
+ * Which directory a mount root is: its device and inode, and its birth time
+ * in nanoseconds as the runtime reports it, where that is above zero, as decimal
+ * strings.
+ */
 export interface RootIdentity {
   dev: string;
   ino: string;
+  born?: string;
 }
 
 /** Whether two configured roots name the same path, whatever their spelling
@@ -106,8 +120,17 @@ function sameRootPath(a: string, b: string): boolean {
   return resolve(a) === resolve(b);
 }
 
+/**
+ * Whether two identities name the same directory: the same device and inode,
+ * or the same inode and birth time on another device, since macOS can give a
+ * volume another device number after a reboot. A birth time in whole seconds
+ * doesn't count across devices: filesystems made in the same second can give
+ * their roots one inode (2 on ext4) and one birth time.
+ */
 export function sameRootIdentity(a: RootIdentity, b: RootIdentity): boolean {
-  return a.dev === b.dev && a.ino === b.ino;
+  if (a.ino !== b.ino) return false;
+  if (a.dev === b.dev) return true;
+  return a.born !== undefined && a.born === b.born && !a.born.endsWith('000000000');
 }
 
 type JournalEntry =
@@ -219,18 +242,18 @@ export class DiskAgreement {
    */
   ensureReconciled(): void {
     if (this.journal.needsReopen) {
-      throw new Error(
-        'Disk-agreement evidence is unavailable until the store is reopened, as at the next start: ' +
-        'an append to its journal failed inside the store, and the evidence may lack what it recorded',
-      );
+      throw new EvidenceUnavailable(`${UNTIL_REOPENED}: an append to its record of what disk last agreed with failed inside the store, so that record may lack what the append held. ${REOPEN}`);
     }
     if (!this.whole) {
-      throw new Error(
-        'Disk-agreement evidence is unavailable until the store is reopened, as at the next start: ' +
-        'reading it back from the store failed',
-      );
+      throw new EvidenceUnavailable(`${UNTIL_REOPENED}: reading back its record of what disk last agreed with failed. ${REOPEN}`);
     }
     if (this.journal.needsReconcile) this.rebuild();
+    const gate = callGate.getStore();
+    if (gate) gate.passed = true;
+  }
+
+  get awaitsReopen(): boolean {
+    return this.journal.needsReopen || !this.whole;
   }
 
   /** Whether evidence recorded so far still awaits a barrier. */
@@ -314,11 +337,19 @@ export class DiskAgreement {
 
   /**
    * Record the root's identity just before the first evidence a mount gains:
-   * the caller saw it as the root while gathering that evidence. A no-op once
-   * one is recorded; changing it is acceptRoot's alone.
+   * the caller saw it as the root while gathering that evidence. Once one is
+   * recorded, the same directory seen on another device, or with a birth
+   * time the record lacks, replaces it and keeps the evidence; another
+   * directory is acceptRoot's alone.
    */
   recordRootIdentity(mount: string, identity: RootIdentity): void {
-    if (this.rootIdentity(mount) !== undefined) return;
+    const recorded = this.rootIdentity(mount);
+    if (recorded !== undefined) {
+      if (!sameRootIdentity(recorded, identity)) return;
+      const renumbered = recorded.dev !== identity.dev;
+      const bornLearned = recorded.born === undefined && identity.born !== undefined;
+      if (!renumbered && !bornLearned) return;
+    }
     this.write({ t: 'root', mount, identity }, {});
   }
 

package/src/modules/workspace/edit-text.ts

@@ -13,7 +13,7 @@
 
 import type { ToolResult } from '../../types/events.js';
 import { type Change, type FilePlan, type Leaves, type MatchProblem, SHOWN_MATCHES } from './edit-plan.js';
-import { answerText, fieldLine, sectionLead, sectionText, shownValue, textAnswer } from './result-text.js';
+import { answerText, fieldLine, sectionLead, sectionText, shownValue, textAnswer, type DiskState } from './result-text.js';
 import { MAX_LINE_CHARS, numberedLine, safeCut } from './text.js';
 
 /** The tool a call came through, which words its refusals and receipt. */
@@ -548,8 +548,8 @@ function listedFileLine(file: ListedFile): string {
 }
 
 /** edit_many's receipt's text before its changed regions: its counts, and the files it lists. */
-function manyHeadText(data: { edits: number; replacements: number; files: ListedFile[]; filesNotListed?: number }): string {
-  const header = [fieldLine('edits', data.edits), fieldLine('replacements', data.replacements)];
+function manyHeadText(data: { edits: number; replacements: number; disk: DiskState; files: ListedFile[]; filesNotListed?: number }): string {
+  const header = [fieldLine('edits', data.edits), fieldLine('replacements', data.replacements), fieldLine('disk', data.disk)];
   if (data.filesNotListed !== undefined) header.push(fieldLine('filesNotListed', data.filesNotListed));
   return answerText(header, [sectionText('files', data.files.map(listedFileLine).join('\n'))]);
 }
@@ -571,7 +571,7 @@ function manyHeadText(data: { edits: number; replacements: number; files: Listed
  * call answers ResultTooLarge. Otherwise the model reads the text, and a
  * script gets the receipt's fields beside it.
  */
-export function editReceipt(tool: EditTool, files: StoredFile[], editCount: number, maxChars: number): ToolResult {
+export function editReceipt(tool: EditTool, files: StoredFile[], editCount: number, maxChars: number, disk: DiskState): ToolResult {
   const reserve = receiptReserve(tool, files, maxChars);
   const notesOf = ({ plan, notes }: StoredFile): string[] => {
     const lineEnds = lineEndNote(plan);
@@ -595,6 +595,7 @@ export function editReceipt(tool: EditTool, files: StoredFile[], editCount: numb
       path: file.path,
       size: file.plan.bytes.length,
       replacements: file.plan.replacements,
+      disk,
       ...(notes.length ? { note: notes.join(' ') } : {}),
       ...(file.modeKept ? { modeKept: file.modeKept } : {}),
     };
@@ -604,9 +605,10 @@ export function editReceipt(tool: EditTool, files: StoredFile[], editCount: numb
     return textAnswer(answerText(header, [sectionText('changed', changed)]), { ...head, changed });
   }
   const listed: ListedFile[] = [];
-  const data: { edits: number; replacements: number; files: ListedFile[]; filesNotListed?: number; changed: string } = {
+  const data: { edits: number; replacements: number; disk: DiskState; files: ListedFile[]; filesNotListed?: number; changed: string } = {
     edits: editCount,
     replacements: files.reduce((sum, file) => sum + file.plan.replacements, 0),
+    disk,
     files: listed,
     changed: '',
   };

package/src/modules/workspace/effects.ts

@@ -47,7 +47,9 @@ import type { FileHandle } from 'node:fs/promises';
 import {
   type CheckedDir,
   type MountView,
+  LEAVES_MOUNT,
   NONBLOCK,
+  NOT_A_DIRECTORY,
   NOT_FOLLOWED,
   OUTSIDE_PARENT,
   ROOT_REPLACED,
@@ -58,7 +60,6 @@ import {
   leadsInto,
   nameOf,
   coversLanding,
-  namesNestedPlace,
   nestedAtReal,
   parentOf,
 } from './observe.js';
@@ -232,7 +233,7 @@ export async function writeContained(
   createMode?: number,
 ): Promise<{ perm: number; widenRefused: boolean; modeKept: boolean }> {
   const checked = await parentFor(view, rootReal, rel, true);
-  if (checked.kind !== 'checked') throw new EffectFailed('a parent path is not a directory', false);
+  if (checked.kind !== 'checked') throw new EffectFailed(NOT_A_DIRECTORY, false);
   const parent = checked.dir;
   const root = checked.root;
   const target = parent.at(nameOf(rel));
@@ -258,8 +259,16 @@ export async function writeContained(
       touched = true;
       return handle;
     } catch (err) {
-      // O_EXCL refuses any entry: a file, a directory or a link.
-      if (errno(err) === 'EEXIST') throw new EffectFailed('something appeared at this path since it was checked', false);
+      // O_EXCL refuses any entry: a file, a directory or a link, one that
+      // leads nowhere included, which a followed observation reads as absent.
+      if (errno(err) === 'EEXIST') {
+        const link = (await lstat(target).catch(() => null))?.isSymbolicLink() === true;
+        const leads = link ? await stat(target).then(() => 'somewhere', (e: unknown) => errno(e)) : null;
+        throw new EffectFailed(leads === 'ENOENT' || leads === 'ENOTDIR'
+          ? 'a symlink that leads nowhere is at this path, and a push makes a file only where nothing is, forced or not; '
+            + 'whoever runs this host can remove the link or make it lead to a file, and a materialize then writes it'
+          : 'something appeared at this path since it was checked', false);
+      }
       throw new EffectFailed(`cannot create the file (${errno(err) ?? message(err)})`, false);
     }
   };
@@ -386,10 +395,10 @@ export async function writeContained(
  * it, and so does a create, before anything is made.
  */
 export async function refusedLanding(view: MountView, rootReal: string, rel: string, real: string): Promise<string | null> {
-  const leaves = view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT;
+  const leaves = view.followSymlinks ? LEAVES_MOUNT : OUTSIDE_PARENT;
   if (!contained(rootReal, real)) return leaves;
-  const holder = nestedAtReal(real, view.nested);
-  if (holder) return namesNestedPlace(holder.rest, holder.include, false) ? leadsInto(view.name, rel, holder) : view.followSymlinks ? leaves : NOT_FOLLOWED;
+  const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
+  if (holder) return holder.names(false) ? leadsInto(view.name, rel, holder) : view.followSymlinks ? leaves : NOT_FOLLOWED;
   if (!(await coversLanding(view, rootReal, real, rel))) return view.followSymlinks ? leaves : NOT_FOLLOWED;
   return null;
 }
@@ -566,15 +575,15 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     // The link itself is what is removed; a followed one must still lie inside.
     if (!view.followSymlinks) throw new EffectFailed(NOT_FOLLOWED, false);
     const real = await realpath(target).catch(() => null);
-    if (real === null || !contained(rootReal, real)) throw new EffectFailed('a symlink that leaves the mount', false);
+    if (real === null || !contained(rootReal, real)) throw new EffectFailed(LEAVES_MOUNT, false);
     // One leading into a nested mount's directory is that mount's: the link
     // and the file it leads to are left as they are. Where that mount's
     // include leaves the place out, it's no mount's, and the link leaves this
     // one (namesNestedPlace).
-    const holder = nestedAtReal(real, view.nested);
+    const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
     if (holder) {
-      const directory = holder.include !== undefined && await stat(real).then((s) => s.isDirectory(), () => false);
-      throw new EffectFailed(namesNestedPlace(holder.rest, holder.include, directory) ? leadsInto(view.name, rel, holder) : 'a symlink that leaves the mount', false);
+      const directory = holder.judgedByInclude && await stat(real).then((s) => s.isDirectory(), () => false);
+      throw new EffectFailed(holder.names(directory) ? leadsInto(view.name, rel, holder) : LEAVES_MOUNT, false);
     }
     const through = await stat(real, { bigint: true }).catch(() => null);
     if (through === null) throw new EffectFailed(CHANGED, false);
@@ -586,7 +595,7 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     if (!through.isFile()) throw new EffectFailed(through.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file', false);
     // One leading to a file this mount's own include leaves out leaves the
     // mount too, and that file isn't read for a hash (coversLanding).
-    if (!(await coversLanding(view, rootReal, real, rel))) throw new EffectFailed('a symlink that leaves the mount', false);
+    if (!(await coversLanding(view, rootReal, real, rel))) throw new EffectFailed(LEAVES_MOUNT, false);
     file = through;
   } else if (info.isDirectory()) {
     throw new EffectFailed('a directory', false);