mainflow 0.32.1 → 0.33.0

package/dist/{operation-C0dUHUHg.js → operation-B2pq2Q9z.js}

@@ -1,6 +1,6 @@
-import { $ as ACCESS_HEADERS, F as renumberFiles, I as renumberPath, L as renumberText, N as applyOffline, P as renumberRequest, Q as nodeStorage, R as scopeOfPath, X as nowMinute, at as requestTime, dt as DATA_DIR, et as MAX_FILE_BYTES, ft as WriteError, it as exceedsFileLimit, mt as splitFrontMatter, nt as SOCKET_MAX_AGE_CLOSE, ot as textBytes, pt as contentHash, rt as comparePaths, tt as ROUTES, ut as ConflictError, z as applyOperation } from "./host-C7GKIjSc.js";
+import { $ as MAX_FILE_BYTES, F as renumberFiles, I as renumberPath, L as renumberText, N as applyOffline, P as renumberRequest, Q as MAX_BLOB_BYTES, R as scopeOfPath, X as ACCESS_HEADERS, Y as nodeStorage, Z as BLOB_HASH, _t as splitFrontMatter, at as requestTime, et as ROUTES, gt as contentHash, ht as WriteError, it as readsAsText, mt as DATA_DIR, nt as comparePaths, ot as textBytes, pt as ConflictError, q as nowMinute, rt as exceedsFileLimit, tt as SOCKET_MAX_AGE_CLOSE, z as applyOperation } from "./host-CObkJQmr.js";
 import { createHash, randomBytes } from "node:crypto";
-import { accessSync, appendFileSync, chmodSync, closeSync, constants, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, chmodSync, closeSync, constants, copyFileSync, createReadStream, createWriteStream, existsSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
@@ -9,8 +9,11 @@ import { homedir } from "node:os";
 import { createBrotliDecompress, createGunzip, createInflate, createZstdDecompress } from "node:zlib";
 import { Agent, createServer, request } from "node:http";
 import { Agent as Agent$1, request as request$1 } from "node:https";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { EventEmitter } from "node:events";
-import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { COPYFILE_EXCL } from "node:constants";
+import { appendFile, mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { diff3Merge } from "node-diff3";
 import ignore from "ignore";
 //#region ../sync/dist/paths.js
@@ -27,10 +30,17 @@ const syncPaths = (root) => {
 		tmp: join(own, "tmp"),
 		conflicts: join(own, "conflicts"),
 		known: join(own, "known.json"),
-		/** The files only on the server, the artifacts of closed mainlines not downloaded here, by their content hash */
+		/** The files only on the server, the artifacts of closed mainlines not downloaded here, by their content hash: a binary file's sha256 */
 		remote: join(own, "remote.json"),
 		/** The text of each version known.json names, in a file named by its content hash */
 		knownTexts: join(own, "known"),
+		/** The content of each binary file a write in the outbox uploads, in a file named by its sha256 */
+		blobs: join(own, "blobs"),
+		/**
+		* Present while a hub taken without known.json has had no snapshot that named binary files, as when the first probe
+		* failed: a binary file such a snapshot names removed was removed on the server since the copy
+		*/
+		copyBlobs: join(own, "copy-blobs"),
 		queue: join(own, "queue.json"),
 		notices: join(own, "notices.jsonl"),
 		daemon: join(own, "daemon.json"),
@@ -140,6 +150,13 @@ function earlierToken(root, env = process.env) {
 }
 //#endregion
 //#region ../sync/dist/api.js
+/** The sha256 of `bytes` in lowercase hex, as a binary file is named (BLOB_HASH). */
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/**
+* The sha256 the probe of the binary files' route names (blobRoute): not the sha256 of the empty content it sends, so a
+* server with the route refuses it and keeps nothing.
+*/
+const PROBE_HASH = "0".repeat(64);
 /**
 * The server could not be reached, or the connection broke. `sent` says whether the request may have reached the
 * server: a refused connection did not, a reset or timeout after sending may have, so its result is unknown.
@@ -165,6 +182,19 @@ var ServerError = class extends Error {
 };
 /** Cloudflare Access refused the request: no service token, a wrong or revoked one, or a policy that does not admit it. */
 var AccessRefused = class extends ServerError {};
+/** Content downloaded as one sha256 turned out to be of another (downloadBlob): damaged on its way, or by the server. */
+var BlobMismatch = class extends Error {};
+/**
+* The downloaded content could not be written here (downloadBlob), as on a full disk (ENOSPC): an error of this machine,
+* not of the server or the network. `code` is the file system's error code.
+*/
+var LocalWriteError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+	}
+};
 /** Error codes of a connection that never carried the request. */
 const NOT_SENT = /* @__PURE__ */ new Set([
 	"ECONNREFUSED",
@@ -198,6 +228,16 @@ const ACCEPT_ENCODING = Object.keys(DECODERS).join(", ");
 const causeCode = (error) => {
 	for (let cause = error; cause; cause = cause.cause) if (typeof cause.code === "string") return cause.code;
 };
+/** What an answer's body is once decompressed, as Content-Encoding says; throws for an encoding this client cannot read. */
+function decoded(res) {
+	const encoding = String(res.headers["content-encoding"] ?? "identity").toLowerCase();
+	const decode = DECODERS[encoding];
+	if (!decode && encoding !== "identity") {
+		res.resume();
+		throw new Error(`the answer came in content-encoding ${encoding}, which this client cannot read`);
+	}
+	return decode ? res.pipe(decode()) : res;
+}
 var ServerApi = class {
 	settings;
 	timeoutMs;
@@ -208,6 +248,11 @@ var ServerApi = class {
 	agent;
 	/** The connections snapshots go on, apart from the writes', so a snapshot never waits behind a write or holds one up */
 	reads;
+	/**
+	* The connections binary files' contents go up and down on, apart from the writes' and the snapshots', so a large file
+	* holds neither up; a few at a time, as the files of a snapshot are downloaded side by side.
+	*/
+	transfers;
 	/** Requests on `agent` not answered yet */
 	busy = 0;
 	transfer = {
@@ -232,6 +277,11 @@ var ServerApi = class {
 			maxSockets: 2,
 			maxFreeSockets: 1
 		});
+		this.transfers = new Agent$2({
+			keepAlive: true,
+			maxSockets: 4,
+			maxFreeSockets: 1
+		});
 	}
 	/** The service token's headers, which every request and the WebSocket's upgrade carry. Never logged. */
 	get access() {
@@ -240,6 +290,18 @@ var ServerApi = class {
 			[ACCESS_HEADERS.clientSecret]: this.settings.clientSecret
 		};
 	}
+	/** A failure to reach the server or of the connection, as the Unreachable it is. */
+	unreachable(error) {
+		const code = causeCode(error);
+		const detail = [code, error.cause?.message ?? error.message].filter(Boolean).join(": ");
+		const sent = !(code && NOT_SENT.has(code));
+		return new Unreachable(`cannot reach the sync server at ${this.settings.url}${detail ? ` (${detail})` : ""}`, sent, sent && STALE.has(code ?? ""));
+	}
+	/** Access answers for the server, with a page rather than JSON: 401 or 403, or a redirect to its login page. */
+	refusedByAccess(status, location, url) {
+		if (status !== 401 && status !== 403 && !(status >= 300 && status < 400)) return null;
+		return new AccessRefused(`Cloudflare Access in front of the sync server refused the request (HTTP ${status}${location ? ` to ${new URL(location, url).origin}` : ""}); check the service token in ${ENV.clientId} and ${ENV.clientSecret}, or clientId and clientSecret in .mainflow/${SETTINGS_FILE}`, status);
+	}
 	async call(method, route, body, connection) {
 		const url = `${this.settings.url}${route}`;
 		const text = JSON.stringify(body);
@@ -247,15 +309,10 @@ var ServerApi = class {
 		try {
 			answer = connection === "read" ? await this.read(method, url, text) : await this.write(method, url, text, connection === "fresh");
 		} catch (error) {
-			const code = causeCode(error);
-			const detail = [code, error.cause?.message ?? error.message].filter(Boolean).join(": ");
-			const sent = !(code && NOT_SENT.has(code));
-			throw new Unreachable(`cannot reach the sync server at ${this.settings.url}${detail ? ` (${detail})` : ""}`, sent, sent && STALE.has(code ?? ""));
-		}
-		if (answer.status === 401 || answer.status === 403 || answer.status >= 300 && answer.status < 400) {
-			const to = answer.location ? ` to ${new URL(answer.location, url).origin}` : "";
-			throw new AccessRefused(`Cloudflare Access in front of the sync server refused the request (HTTP ${answer.status}${to}); check the service token in ${ENV.clientId} and ${ENV.clientSecret}, or clientId and clientSecret in .mainflow/${SETTINGS_FILE}`, answer.status);
+			throw this.unreachable(error);
 		}
+		const access = this.refusedByAccess(answer.status, answer.location, url);
+		if (access) throw access;
 		let parsed;
 		try {
 			parsed = JSON.parse(answer.text);
@@ -293,50 +350,171 @@ var ServerApi = class {
 	write(method, url, body, fresh) {
 		return this.exchange(method, url, body, fresh ? false : this.agent, this.timeoutMs);
 	}
-	exchange(method, url, body, agent, timeoutMs) {
+	/**
+	* Send one request with the service token and resolve with the answer as it starts to come. `body` is a JSON text,
+	* the raw bytes of a stream, or nothing; `headers` add to the token's and say what the body is.
+	*/
+	open(method, url, body, headers, agent, timeoutMs) {
 		const send = url.startsWith("https:") ? request$1 : request;
-		const headers = {
-			...this.access,
-			"accept-encoding": ACCEPT_ENCODING
-		};
-		if (body !== void 0) Object.assign(headers, {
-			"content-type": "application/json",
-			"content-length": String(Buffer.byteLength(body))
-		});
-		if (agent === this.agent) this.busy++;
 		return new Promise((resolve, reject) => {
 			const req = send(url, {
 				method,
 				agent,
-				headers,
+				headers: {
+					...this.access,
+					"accept-encoding": ACCEPT_ENCODING,
+					...headers
+				},
 				timeout: timeoutMs
-			}, (res) => {
+			}, resolve);
+			req.on("timeout", () => req.destroy(Object.assign(/* @__PURE__ */ new Error("no answer in time"), { code: req.socket?.connecting === false ? "ETIMEDOUT" : "ECONNECT_TIMEOUT" })));
+			req.on("error", reject);
+			if (body instanceof Readable) {
+				body.on("error", (error) => req.destroy(error));
+				body.pipe(req);
+			} else req.end(body);
+		});
+	}
+	/** One request and its whole answer as text. */
+	async exchange(method, url, body, agent, timeoutMs, headers) {
+		const kind = typeof body === "string" ? {
+			"content-type": "application/json",
+			"content-length": String(Buffer.byteLength(body))
+		} : {};
+		if (agent === this.agent) this.busy++;
+		try {
+			const res = await this.open(method, url, body, {
+				...kind,
+				...headers
+			}, agent, timeoutMs);
+			return await new Promise((resolve, reject) => {
 				let wire = 0;
 				res.on("data", (chunk) => wire += chunk.length);
-				const encoding = String(res.headers["content-encoding"] ?? "identity").toLowerCase();
-				const decode = DECODERS[encoding];
-				if (!decode && encoding !== "identity") {
-					res.resume();
-					return reject(/* @__PURE__ */ new Error(`the answer came in content-encoding ${encoding}, which this client cannot read`));
+				res.on("error", reject);
+				let stream;
+				try {
+					stream = decoded(res);
+				} catch (error) {
+					return reject(error);
 				}
-				const stream = decode ? res.pipe(decode()) : res;
 				const chunks = [];
 				stream.on("data", (chunk) => chunks.push(chunk));
 				stream.on("end", () => resolve({
 					status: res.statusCode ?? 0,
 					text: Buffer.concat(chunks).toString("utf8"),
 					location: res.headers.location,
+					retryAfter: res.headers["retry-after"],
 					wire
 				}));
 				stream.on("error", reject);
-				res.on("error", reject);
 			});
-			req.on("timeout", () => req.destroy(Object.assign(/* @__PURE__ */ new Error("no answer in time"), { code: req.socket?.connecting === false ? "ETIMEDOUT" : "ECONNECT_TIMEOUT" })));
-			req.on("error", reject);
-			req.end(body);
-		}).finally(() => {
+		} finally {
 			if (agent === this.agent) this.busy--;
-		});
+		}
+	}
+	/**
+	* Whether the server has the route of binary files' contents (ROUTES.blob), as a server from before them does not:
+	* the server's version (GET /version) tells only its protocol, which binary files left as it was, so the route is
+	* asked. The probe uploads empty content as PROBE_HASH, which is not its sha256: a server with the route refuses it
+	* and keeps nothing, with 400 `hash-mismatch`, or 4xx for any other reason it refuses an upload; one without the route
+	* answers 404 `not-found`, from the Worker's router itself. A 5xx comes from a server that got as far as the route, as
+	* one whose R2 is failing: it keeps binary files, and the uploads wait until it answers them. Asked once per connection,
+	* before its snapshot, since a snapshot names the binary files only to a server that keeps them. It goes on a
+	* connection of the reads, so one the server closed meanwhile is asked again.
+	*/
+	async blobRoute() {
+		const url = `${this.settings.url}${ROUTES.blob(this.settings.hub, PROBE_HASH)}`;
+		let answer;
+		try {
+			answer = await this.read("PUT", url, "");
+		} catch (error) {
+			throw this.unreachable(error);
+		}
+		const access = this.refusedByAccess(answer.status, answer.location, url);
+		if (access) throw access;
+		return answer.status !== 404;
+	}
+	/**
+	* Upload the content of a binary file, the `size` bytes of `file`, as sha256 `hash` (ROUTES.blob), on a connection of
+	* the transfers. The server out of reach, or failing, throws Unreachable; Access refusing it throws AccessRefused.
+	*/
+	async putBlob(hash, file, size) {
+		const url = `${this.settings.url}${ROUTES.blob(this.settings.hub, hash)}`;
+		let answer;
+		try {
+			answer = await this.exchange("PUT", url, createReadStream(file), this.transfers, this.timeoutMs, {
+				"content-type": "application/octet-stream",
+				"content-length": String(size)
+			});
+		} catch (error) {
+			throw this.unreachable(error);
+		}
+		const access = this.refusedByAccess(answer.status, answer.location, url);
+		if (access) throw access;
+		let body;
+		try {
+			body = JSON.parse(answer.text);
+		} catch {
+			throw new Unreachable(`the sync server answered ${answer.status} without a readable body`, true);
+		}
+		if (answer.status === 503 && body.reason === "blob-deleting") return {
+			ok: false,
+			retryAfter: Math.max(1, Number(answer.retryAfter) || 1)
+		};
+		if (answer.status >= 500) throw new Unreachable(`the sync server failed (${answer.status})`, true);
+		if (body.ok === true) return { ok: true };
+		const message = body.message ?? `HTTP ${answer.status}`;
+		if (body.reason === "hash-mismatch" || body.reason === "too-large") return {
+			ok: false,
+			refused: body.reason,
+			message
+		};
+		return {
+			ok: false,
+			refused: answer.status === 404 ? "unsupported" : "other",
+			message
+		};
+	}
+	/**
+	* Download the content of sha256 `hash` into `file`, checking it is of that hash as it comes: true once it is there,
+	* false when the server holds no such content. Content of another hash throws BlobMismatch, and `file` that cannot be
+	* written here throws LocalWriteError; both leave `file` to the caller to remove, and so do the server out of reach
+	* (Unreachable) and Access refusing it (AccessRefused).
+	*/
+	async downloadBlob(hash, file) {
+		const url = `${this.settings.url}${ROUTES.blob(this.settings.hub, hash)}`;
+		let res;
+		try {
+			res = await this.open("GET", url, void 0, {}, this.transfers, this.timeoutMs);
+		} catch (error) {
+			throw this.unreachable(error);
+		}
+		const status = res.statusCode ?? 0;
+		const access = this.refusedByAccess(status, res.headers.location, url);
+		if (status !== 200) {
+			res.resume();
+			if (access) throw access;
+			if (status === 404) return false;
+			if (status >= 500) throw new Unreachable(`the sync server failed (${status})`, true);
+			throw new ServerError(`the sync server refused the download of ${hash} (HTTP ${status})`, status);
+		}
+		const digest = createHash("sha256");
+		const tap = new Transform({ transform(chunk, _encoding, done) {
+			digest.update(chunk);
+			done(null, chunk);
+		} });
+		const out = createWriteStream(file);
+		let local;
+		out.once("error", (error) => local = error);
+		try {
+			await pipeline(decoded(res), tap, out);
+		} catch (error) {
+			if (local !== void 0) throw new LocalWriteError(`could not write the download here: ${local.message}`, local.code);
+			throw this.unreachable(error);
+		}
+		const got = digest.digest("hex");
+		if (got !== hash) throw new BlobMismatch(`the content downloaded as sha256 ${hash} is of ${got}`);
+		return true;
 	}
 	/**
 	* Keep the write connection open: a request that needs no hub, on it, unless a request is on it already. Opens it
@@ -352,6 +530,7 @@ var ServerApi = class {
 	close() {
 		this.agent.destroy();
 		this.reads.destroy();
+		this.transfers.destroy();
 	}
 	/** Send one request; the response is the hub's answer, applied or refused. */
 	async send(request, options = {}) {
@@ -377,7 +556,8 @@ var ServerApi = class {
 	* is below the batch before, as when the server's storage was replaced meanwhile, starts the snapshot over. A path of
 	* `have` the server never held a file at comes as `unknown` rather than `removed`, from a server that tells them apart.
 	* `listOnly` asks for the files under those prefixes as `listed`, without their text. A part of the hub alone is taken
-	* from `after` on, and ends with the batch that covers `through`; only the paths of that range are told of.
+	* from `after` on, and ends with the batch that covers `through`; only the paths of that range are told of. `blobs` takes
+	* the binary files too, each that differs from `have` as `blob`; `have` names a binary file by its sha256 then.
 	*/
 	async snapshot(have = /* @__PURE__ */ new Map(), options = {}) {
 		const paths = [...have.keys()].sort(comparePaths);
@@ -394,7 +574,8 @@ var ServerApi = class {
 					have: range,
 					unknown: true,
 					...after === void 0 ? {} : { after },
-					...options.listOnly?.length ? { listOnly: options.listOnly } : {}
+					...options.listOnly?.length ? { listOnly: options.listOnly } : {},
+					...options.blobs ? { blobs: true } : {}
 				});
 				if (parts.length > 0 && seq < parts.at(-1).seq) break;
 				parts.push({
@@ -431,13 +612,32 @@ var ServerApi = class {
 		}, "fresh");
 		return body;
 	}
-	/** Open the hub's broadcast connection. */
+	/**
+	* Open the hub's broadcast connection, taking the binary files too (ROUTES.socket). It opens before the client knows
+	* whether the server keeps binary files (blobRoute), and a server from before them reads nothing of `blobs`.
+	*/
 	socket() {
-		const url = `${this.settings.url.replace(/^http/, "ws")}${ROUTES.socket(this.settings.hub)}?protocol=3`;
+		const url = `${this.settings.url.replace(/^http/, "ws")}${ROUTES.socket(this.settings.hub)}?protocol=3&blobs=true`;
 		return new WebSocket(url, { headers: this.access });
 	}
 };
 //#endregion
+//#region ../sync/dist/edit.js
+/**
+* The text an Edit of `edit` replaces in `text`: old_string, with the line break after it when new_string is empty and
+* old_string ends in none (Claude Code 2.1.285). Null when old_string is empty or not in `text` exactly once, as the
+* Edit then fails.
+*/
+function editTarget(text, edit) {
+	if (edit.old === "" || text.split(edit.old).length !== 2) return null;
+	return edit.new === "" && !edit.old.endsWith("\n") && text.includes(`${edit.old}\n`) ? `${edit.old}\n` : edit.old;
+}
+/** `text` with the Edit of `edit` made as Claude Code makes it, or null when the Edit fails on it. */
+function applyEdit(text, edit) {
+	const target = editTarget(text, edit);
+	return target === null ? null : text.replace(target, () => edit.new);
+}
+//#endregion
 //#region ../sync/dist/lines.js
 const split = (text) => text.split("\n");
 /**
@@ -694,6 +894,8 @@ function oversizedFiles(root) {
 }
 //#endregion
 //#region ../sync/dist/state.js
+/** The requestId an outbox entry goes under: its id, with the number of the try for a binary file's write sent again. */
+const requestIdOf = (entry) => entry.kind === "blob" && entry.retry ? `${entry.id}-${entry.retry}` : entry.id;
 /** Whether `entry` waits for the server: not one it refused. */
 const waiting = (entry) => entry.refused === void 0;
 /** A new entry's id. */
@@ -752,6 +954,8 @@ function writeJson(file, value) {
 	renameSync(temp, file);
 }
 const readKnown = (root) => readJson(syncPaths(root).known, {}).files ?? {};
+/** What known.json writes before a binary file's sha256, apart from a text's content hash. */
+const BLOB_PREFIX = "blob:";
 /** The text of the version known.json names by `hash`; undefined when it was not kept, as by a sync client before known/. */
 function readKnownText(root, hash) {
 	try {
@@ -765,7 +969,7 @@ function readKnownText(root, hash) {
 * Write known.json, and into known/ the text of each version it names that is not
 * there yet; the texts of versions it no longer names are removed. A version whose text the client does not have keeps
 * the text known/ holds, if any. The new texts go first, then known.json, then the removals, so a client killed at any
-* step leaves a known.json whose every text is in known/.
+* step leaves a known.json whose every text is in known/. A binary file is given as its sha256 with BLOB_PREFIX, and no text.
 */
 function writeKnown(root, files) {
 	const dir = syncPaths(root).knownTexts;
@@ -1108,6 +1312,13 @@ function exists(file) {
 		return false;
 	}
 }
+const isBlob = (file) => typeof file === "object" && file !== null && file.kind === "blob";
+/** The hash the server names a file of its by: a text's content hash, a binary file's sha256. */
+const serverHash = (file) => typeof file === "string" ? contentHash(file) : file.hash;
+/** Whether two tool calls are of one session, the same subagent in it or both of the session itself. */
+const sameCaller = (a, b) => a !== void 0 && b !== void 0 && a.session === b.session && a.agent === b.agent;
+/** Whether `edit` makes `to` of `from`, as the Edit tool makes it (applyEdit). */
+const replaces = (edit, from, to) => applyEdit(from, edit) === to;
 const HISTORY = 20;
 /** The statuses of a closed mainline, whose artifacts stay on the server until they are used */
 const CLOSED = /* @__PURE__ */ new Set(["done", "dropped"]);
@@ -1125,6 +1336,26 @@ const SETTLE_LIMIT_MS = 1e3;
 * ones before the last are each followed by a pause before the next
 */
 const STALLED_SNAPSHOTS = 4;
+/** How long after a failed probe of binary files (probeBlobs) the snapshot is taken again, at first and at most */
+const PROBE_RETRY_MS = 3e4;
+const PROBE_RETRY_MAX_MS = 6e5;
+/**
+* How long an upload of a binary file's content waits after a failure (uploadEntry): the first two failures are tried
+* again after BLOB_RETRY_MS, with up to as much again at random; from the third on, the wait doubles from
+* BLOB_BACKOFF_MS up to BLOB_BACKOFF_MAX_MS
+*/
+const BLOB_RETRY_MS = 1e3;
+const BLOB_BACKOFF_MS = 2e3;
+const BLOB_BACKOFF_MAX_MS = 6e5;
+/** Failures of an upload of the same write in a row before it waits longer each time and the writer is told */
+const BLOB_FAILURES = 3;
+/**
+* How long a download of a binary file's content waits after it failed (download), doubling from DOWNLOAD_BACKOFF_MS up to
+* BLOB_BACKOFF_MAX_MS. Content that does not match or cannot be written here is tried DOWNLOAD_TRIES times; then the file
+* is left as it is until the next connection.
+*/
+const DOWNLOAD_BACKOFF_MS = 2e3;
+const DOWNLOAD_TRIES = 5;
 /** How long after a read that is not UTF-8 the file is read again before it counts as binary */
 const BINARY_RECHECK_MS = 150;
 /**
@@ -1147,6 +1378,91 @@ const OUTBOX = `${SYNC_DIR}/queue.json`;
 const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const decoder = new TextDecoder("utf-8", { fatal: true });
 const sameLocal = (a, b) => a.kind === b.kind && (a.kind !== "text" || a.text === b.text) && (a.kind !== "binary" || a.hash === b.hash);
+/** What `bytes` read from a file are: a text when they are UTF-8, a binary file otherwise. */
+function contentOf(bytes) {
+	try {
+		return {
+			kind: "text",
+			text: decoder.decode(bytes)
+		};
+	} catch {
+		return {
+			kind: "binary",
+			hash: sha256(bytes),
+			size: bytes.length,
+			bytes
+		};
+	}
+}
+/** The hash of `content`, as the server names it: a text's content hash, a binary file's sha256. */
+const hashOfContent = (content) => content.kind === "text" ? contentHash(content.text) : content.hash;
+/** Whether `content` is what the server holds as `file`. */
+const holdsServer = (content, file) => typeof file === "string" ? content.kind === "text" && content.text === file : isBlob(file) ? content.kind === "binary" && content.hash === file.hash : false;
+/**
+* The sha256 and size of the file at `file`, and whether it is UTF-8, read in chunks of a MiB: a file of up to
+* MAX_BLOB_BYTES is never held in memory whole.
+*/
+async function scanFile(file) {
+	const handle = await open(file, "r");
+	try {
+		const digest = createHash("sha256");
+		const utf8 = new TextDecoder("utf-8", { fatal: true });
+		const chunk = Buffer.allocUnsafe(1 << 20);
+		let size = 0;
+		let text = true;
+		for (;;) {
+			const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+			if (bytesRead === 0) break;
+			const part = chunk.subarray(0, bytesRead);
+			digest.update(part);
+			size += bytesRead;
+			if (text) try {
+				utf8.decode(part, { stream: true });
+			} catch {
+				text = false;
+			}
+		}
+		if (text) try {
+			utf8.decode();
+		} catch {
+			text = false;
+		}
+		return {
+			hash: digest.digest("hex"),
+			size,
+			text
+		};
+	} finally {
+		await handle.close();
+	}
+}
+/** The sha256 of the file at `file`, read in chunks; null when it cannot be read. */
+function sha256File(file) {
+	let fd;
+	try {
+		fd = openSync(file, "r");
+	} catch {
+		return null;
+	}
+	try {
+		const digest = createHash("sha256");
+		const chunk = Buffer.allocUnsafe(1 << 20);
+		for (let read = readSync(fd, chunk); read > 0; read = readSync(fd, chunk)) digest.update(chunk.subarray(0, read));
+		return digest.digest("hex");
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+/** What the client leaves on disk when a file holds `content`: a text with its hash, or a binary file's sha256. */
+const diskOf = (content) => content.kind === "text" ? {
+	hash: contentHash(content.text),
+	text: content.text
+} : {
+	hash: content.hash,
+	blob: true
+};
 /**
 * The queued edit of `path` to the writer's `text` that started from `start` (src/state.ts): on the server's version
 * that holds a confirmed start, waiting for an unconfirmed one, or, without a start, on `base`, the hash of the version
@@ -1194,7 +1510,7 @@ function heldBase(entry) {
 */
 function textAt(entry, path) {
 	if (entry.kind === "op") return entry.written[path];
-	if (entry.path !== path) return void 0;
+	if (entry.path !== path || entry.kind === "blob") return void 0;
 	if (entry.kind === "remove") return null;
 	return entry.text;
 }
@@ -1233,7 +1549,7 @@ function patchRequest(entry) {
 function holdsFiles(parts, held) {
 	const missing = /* @__PURE__ */ new Set();
 	for (const part of parts) for (const event of part.files) {
-		if (event.kind === "file" || event.kind === "listed") return true;
+		if (event.kind === "file" || event.kind === "listed" || event.kind === "blob") return true;
 		if (event.kind === "removed" || event.kind === "unknown") missing.add(event.path);
 	}
 	return [...held.keys()].some((path) => !missing.has(path));
@@ -1245,6 +1561,18 @@ var SyncClient = class extends EventEmitter {
 	api;
 	problems = [];
 	reported = 0;
+	/** The local change of each path waiting for an Edit's report (awaitEdit) */
+	awaitingEdit = /* @__PURE__ */ new Map();
+	/** The Edits announced before they ran (announceEdit) and not reported yet, by path, oldest first */
+	announced = /* @__PURE__ */ new Map();
+	/** Edits reported before the change they made waited, by path, until the report's own replay on the path's chain ran */
+	reportedEdits = /* @__PURE__ */ new Map();
+	/** Flushes under way that send every change at once (flush): no change waits for an Edit's report meanwhile */
+	sendingAll = 0;
+	/** The files the tools reported by flushes under way wrote, by count: a change of them does not wait for an Edit's report */
+	sendingPaths = /* @__PURE__ */ new Map();
+	/** The path the reconcile or step on a path's chain that `work` tracks is about (schedule, withChain) */
+	workPaths = /* @__PURE__ */ new Map();
 	/** What each path holds on disk as the client last left it, confirmed or not */
 	expected = /* @__PURE__ */ new Map();
 	/**
@@ -1263,17 +1591,65 @@ var SyncClient = class extends EventEmitter {
 	/** The content hash last worked out for a text the client named in a snapshot request, by path */
 	hashes = /* @__PURE__ */ new Map();
 	/**
-	* The text the last snapshot request named for each path, with what the server made of it: left out, as the same text
-	* it holds, or named removed. A file this client never synced, as one in a hub taken with git, that still holds that
-	* text holds the server's version, or one the server removed since; not a text written here (reconcile).
+	* The content the last snapshot request named for each path, by its hash, with what the server made of it: left out,
+	* as the same content it holds, or named removed. A file this client never synced, as one in a hub taken with git, that
+	* still holds that content holds the server's version, or one the server removed since; not one written here (reconcile).
 	*/
 	snapshotAnswers = /* @__PURE__ */ new Map();
 	/**
+	* Whether the server keeps binary files, as the probe of its route told (ServerApi.blobRoute); null until a connection
+	* asked. Only then does a snapshot name binary files, and the outbox send one: a server from before binary files names
+	* a path of `have` it holds no file at removed, which would remove the binary file here. While it is null, a binary file
+	* waits as it is here, neither sent nor written over: the snapshot after the probe reconciles every file again.
+	*/
+	blobSupport = null;
+	/** Whether the current connection asked the server whether it keeps binary files; cleared when a connection opens */
+	probed = false;
+	/** The contents this run uploaded, by sha256: a write of one is sent without uploading it again */
+	uploadedBlobs = /* @__PURE__ */ new Set();
+	/** The binary files the server refused as too large, as `path\0hash`: left as they are here, as larger than MAX_BLOB_BYTES */
+	oversized = /* @__PURE__ */ new Set();
+	/** The contents a download found missing on the server on this connection, by sha256, so a snapshot is reloaded once for each */
+	missingDownloads = /* @__PURE__ */ new Set();
+	/** The failed uploads of each binary file's write in a row this run, by outbox id (uploadEntry) */
+	uploadFailures = /* @__PURE__ */ new Map();
+	/**
+	* Until when each binary file's write waits after its upload failed, by outbox id: meanwhile the writes of other paths
+	* behind it go ahead (sendOutbox)
+	*/
+	uploadHolds = /* @__PURE__ */ new Map();
+	/**
+	* When the content of each sha256 the server is deleting may be uploaded again, as its Retry-After said: the outbox is
+	* sent again on any change to queue.json, which would otherwise upload it again at once
+	*/
+	uploadAfter = /* @__PURE__ */ new Map();
+	/** The download to try again shortly, after one failed while online: at most one timer for each path */
+	downloadRetries = /* @__PURE__ */ new Map();
+	/**
+	* The failed downloads of each content in a row on this connection, by sha256, for the ones that came of another sha256
+	* or could not be written here (download)
+	*/
+	downloadFailures = /* @__PURE__ */ new Map();
+	/** Why the last download of each path failed, until one succeeds: what fetch tells its caller */
+	downloadErrors = /* @__PURE__ */ new Map();
+	/** The paths whose download failed DOWNLOAD_TRIES times in a row, reconciled again after the next snapshot */
+	stalledDownloads = /* @__PURE__ */ new Set();
+	/** The snapshot taken again after a failed probe (probeBlobs), and how long after the next failure it is */
+	probeTimer;
+	probeRetry = PROBE_RETRY_MS;
+	/**
 	* Whether this run started without known.json, as in a hub taken with git that never synced here. Only then does the
 	* first snapshot's `removed` for a file the client named tell of a file the server removed since the copy: the server
 	* names removed every path it does not have, so later, or with known.json, such a file is one created here.
 	*/
 	copied = false;
+	/**
+	* Whether the binary files of a copy (copied) were compared with the server's yet: false until a snapshot that named
+	* binary files ends, which the first snapshot does not when the client does not know yet that the server keeps them.
+	* Until then a binary file that snapshot names removed was removed on the server since the copy, as `copied` tells of
+	* a text in the first snapshot. Kept across runs by copyBlobs, since the first snapshot saves known.json.
+	*/
+	blobsCompared = true;
 	/** The server has no copy of the hub, which this environment, downloading on demand, does not upload (snapshotNow) */
 	uploadWanted = false;
 	/** Why the server refused the upload of this environment's copy, as last reported (snapshotNow); null once it holds the hub */
@@ -1425,15 +1801,17 @@ var SyncClient = class extends EventEmitter {
 	/**
 	* The file at `path` as the server last had it to this client's knowledge: its text, null when the server has no such
 	* file, or undefined when the client does not know it, such as before the first snapshot, or for a file only on the
-	* server, whose text is not here.
+	* server, whose text is not here, and for a binary file, which has no text.
 	*/
 	serverText(path) {
 		if (this.remote.has(path) || this.awaiting.has(path)) return void 0;
-		return this.cloud.has(path) ? this.cloud.get(path) : this.synced ? null : void 0;
+		if (!this.cloud.has(path)) return this.synced ? null : void 0;
+		const held = this.cloud.get(path);
+		return isBlob(held) ? void 0 : held;
 	}
 	/** How many files are only on the server, not downloaded here (onDemand). */
 	get remoteCount() {
-		return this.remote.size;
+		return this.listedRemote().size;
 	}
 	/**
 	* Whether the sync server has no copy of the hub and this environment, downloading on demand, waits for one that keeps
@@ -1446,6 +1824,7 @@ var SyncClient = class extends EventEmitter {
 	async start() {
 		await mkdir(this.paths.tmp, { recursive: true });
 		await mkdir(this.paths.conflicts, { recursive: true });
+		await mkdir(this.paths.blobs, { recursive: true });
 		if (this.opts.swap !== false) {
 			const swapper = startSwapper(this.paths.tmp);
 			this.swapper = swapper.helper;
@@ -1459,6 +1838,7 @@ var SyncClient = class extends EventEmitter {
 		await this.restoreKnown();
 		this.restoreRemote();
 		await this.whenFree(() => this.syncQueue());
+		await this.whenFree(() => this.locked(() => this.pruneStaged(this.queue)));
 		await this.resumeRefusals();
 		if (this.opts.watch !== false) this.startWatcher();
 		await this.scan(true, true);
@@ -1474,10 +1854,21 @@ var SyncClient = class extends EventEmitter {
 	* its write based on that change and undo it, and a change made while no client ran would have no base text to tell
 	* the writer's lines from another environment's (layer 2). Without its text, as known.json of an older client, only
 	* a file that still holds it gives it. What the outbox wrote, refused writes included, is read after it (restoreEntry).
+	* A binary file's version is its sha256 alone (BLOB_PREFIX): it is no base for a write, which is never merged.
 	*/
 	async restoreKnown() {
 		this.copied = !existsSync(this.paths.known);
+		this.blobsCompared = !this.copied && !existsSync(this.paths.copyBlobs);
 		for (const [path, hash] of Object.entries(readKnown(this.root))) {
+			if (hash.startsWith("blob:")) {
+				const disk = {
+					hash: hash.slice(5),
+					blob: true
+				};
+				this.expected.set(path, disk);
+				this.confirmed.set(path, disk);
+				continue;
+			}
 			const local = await this.readLocal(path);
 			const text = local.kind === "text" && contentHash(local.text) === hash ? local.text : readKnownText(this.root, hash);
 			const disk = text === void 0 ? { hash } : {
@@ -1535,6 +1926,12 @@ var SyncClient = class extends EventEmitter {
 		clearTimeout(this.queueTimer);
 		for (const timer of this.watchTimers.values()) clearTimeout(timer);
 		this.watchTimers.clear();
+		for (const timer of this.downloadRetries.values()) clearTimeout(timer);
+		this.downloadRetries.clear();
+		clearTimeout(this.probeTimer);
+		for (const wait of this.awaitingEdit.values()) wait.end(null);
+		this.reportedEdits.clear();
+		this.announced.clear();
 		this.watcher?.close();
 		this.ws?.close();
 		const settled = Promise.allSettled([
@@ -1566,14 +1963,19 @@ var SyncClient = class extends EventEmitter {
 			this.connect();
 		});
 	}
-	/** Resolve once nothing is being sent, applied or waited for, and the queue is empty or cannot be sent. */
-	async idle(timeoutMs = 3e4) {
+	/**
+	* Resolve once nothing is being sent, applied or waited for, and the queue is empty or cannot be sent now. With
+	* `besidesAwaiting`, the work on a path waiting for an Edit's report (awaitEdit) is left out, as is the work behind it
+	* on that path's chain: a tool's flush does not wait for an Edit of another session to be reported.
+	*/
+	async idle(timeoutMs = 3e4, besidesAwaiting = false) {
 		const deadline = Date.now() + timeoutMs;
 		this.outboxChanged();
 		for (;;) {
-			if (!(this.work.size > 0 || [...this.inflight.values()].some((n) => n > 0) || this.flushing || this.resyncing !== null || this.online && this.queued > 0)) return true;
+			const work = besidesAwaiting ? [...this.work].filter((promise) => !this.awaitingEdit.has(this.workPaths.get(promise) ?? "")) : [...this.work];
+			if (!(work.length > 0 || [...this.inflight.values()].some((n) => n > 0) || this.flushing || this.resyncing !== null || this.online && this.nextEntry(this.queue).entry !== void 0)) return true;
 			if (Date.now() > deadline) return false;
-			await (this.work.size > 0 ? Promise.race([Promise.allSettled(this.work), sleep$1(50)]) : sleep$1(50));
+			await (work.length > 0 ? Promise.race([Promise.allSettled(work), sleep$1(50)]) : sleep$1(50));
 		}
 	}
 	connect() {
@@ -1591,6 +1993,9 @@ var SyncClient = class extends EventEmitter {
 			this.connected = true;
 			this.rejoining = false;
 			this.current = false;
+			this.probed = false;
+			this.missingDownloads.clear();
+			this.downloadFailures.clear();
 			if (!this.uploadWanted && this.uploadRefusal === null) this.backoff = 500;
 			this.lastPong = Date.now();
 			clearInterval(this.pingTimer);
@@ -1725,7 +2130,9 @@ var SyncClient = class extends EventEmitter {
 	* One file as the server has it as of the hub's `seq`, from a broadcast or a snapshot. A version no newer than the
 	* one the client holds, such as a broadcast that arrives after a later snapshot, is left out. A file only on the
 	* server whose mainline is still closed gets its new hash, or leaves `remote` when removed; nothing is written here.
-	* A mainline's file that opens it again brings its artifacts here.
+	* A mainline's file that opens it again brings its artifacts here. A binary file comes as its hash (`blob`), and one
+	* that may stay on the server, as a new screenshot of a closed mainline, goes into `remote` instead of being downloaded,
+	* as a listed text does in a snapshot.
 	*/
 	receive(event, seq) {
 		if (event.kind === "dir") {
@@ -1733,26 +2140,42 @@ var SyncClient = class extends EventEmitter {
 			return;
 		}
 		if (!this.syncs(event.path)) return;
-		const text = event.kind === "file" ? event.text : null;
+		const file = event.kind === "file" ? event.text : event.kind === "blob" ? {
+			kind: "blob",
+			hash: event.hash,
+			size: event.size
+		} : null;
+		const label = isBlob(file) ? `blob ${file.hash.slice(0, 7)}` : short(file);
 		const held = this.fileSeq.get(event.path) ?? -1;
 		if (seq <= held) {
-			this.trace(`older ${event.path} ${short(text)} seq ${seq}, holding seq ${held}`);
+			this.trace(`older ${event.path} ${label} seq ${seq}, holding seq ${held}`);
 			return;
 		}
 		this.fileSeq.set(event.path, seq);
+		if (this.downloadErrors.has(event.path)) {
+			const before = this.cloud.get(event.path);
+			if (!(isBlob(file) && isBlob(before) && before.hash === file.hash) && this.downloadErrors.delete(event.path)) this.saveRemote();
+		}
 		if (event.kind === "unknown") this.unheld.add(event.path);
 		else this.unheld.delete(event.path);
-		if (this.remote.has(event.path) && !this.awaiting.has(event.path) && (text === null || this.staysRemote(event.path))) {
-			this.trace(`remote ${event.path} ${short(text)} seq ${seq}`);
-			if (text === null) this.remote.delete(event.path);
-			else this.remote.set(event.path, contentHash(text));
+		if (this.remote.has(event.path) && !this.awaiting.has(event.path) && (file === null || this.staysRemote(event.path))) {
+			this.trace(`remote ${event.path} ${label} seq ${seq}`);
+			if (file === null) this.remote.delete(event.path);
+			else this.remote.set(event.path, serverHash(file));
+			this.saveRemote();
+			return;
+		}
+		if (isBlob(file) && !this.awaiting.has(event.path) && this.mayStay(event.path) && !existsSync(join(this.paths.data, event.path))) {
+			this.trace(`remote ${event.path} ${label} seq ${seq}`);
+			this.remote.set(event.path, file.hash);
+			this.cloud.delete(event.path);
 			this.saveRemote();
 			return;
 		}
 		if (this.remote.delete(event.path)) this.saveRemote();
-		this.trace(`receive ${event.path} ${short(text)} seq ${seq}`);
+		this.trace(`receive ${event.path} ${label} seq ${seq}`);
 		this.awaiting.delete(event.path);
-		this.cloud.set(event.path, text);
+		this.cloud.set(event.path, file);
 		this.schedule(event.path);
 		const mainline = MAINLINE_FILE.exec(event.path)?.[1];
 		if (mainline !== void 0 && this.remote.size > 0) this.fetchOpened(mainline);
@@ -1865,6 +2288,14 @@ var SyncClient = class extends EventEmitter {
 	* downloaded before the snapshot ends, with the files only on the server whose mainline is open now. The first
 	* snapshot of a hub without known.json lists all of mainlines/, since the client may not know a mainline or its
 	* status yet: the mainlines' own files are downloaded after, then the artifacts of the open ones.
+	*
+	* Each connection first asks whether the server keeps binary files (blobSupport). One that does is sent the binary
+	* files the client holds by their sha256, and tells of its own as `blob`; one that does not is told of none, and tells
+	* of none, nor any path it holds one at: such a path is neither named nor taken for removed. A server the client
+	* uploaded the hub to holds none of them, since an upload holds texts alone: known.json stops naming them before the
+	* upload (forgetBinaries), so they are files never synced here, sent as new even when this snapshot fails or the
+	* client is killed; and in the snapshot after the upload, a binary file of the client's the server names removed, as
+	* when it once held one there, is taken as one it never held (unheld), also in a run that started without known.json.
 	*/
 	takeSnapshot() {
 		return this.exclusive(() => this.snapshotNow());
@@ -1872,6 +2303,7 @@ var SyncClient = class extends EventEmitter {
 	async snapshotNow() {
 		let parts;
 		let held;
+		let heldBlobs;
 		let have;
 		let before;
 		/** Whether the hub was uploaded, and why the server refused the upload; asked again, the snapshot may hold the hub */
@@ -1879,14 +2311,26 @@ var SyncClient = class extends EventEmitter {
 		let refusal = null;
 		/** The rules' generation the snapshot is asked for under: what it holds is taken in as they leave it in */
 		let asked;
+		/** Whether the snapshot is asked for with the binary files */
+		let withBlobs = false;
+		if (!this.probed) await this.probeBlobs();
 		for (;;) {
 			before = this.hubSeq;
-			held = await this.holdings();
-			for (const path of this.remote.keys()) if (held.has(path) || this.expected.get(path) !== void 0) this.remote.delete(path);
+			({texts: held, blobs: heldBlobs} = await this.holdings());
+			for (const path of this.remote.keys()) if (held.has(path) || heldBlobs.has(path) || this.expected.get(path) !== void 0) this.remote.delete(path);
 			have = new Map([...held].map(([path, text]) => [path, this.hashOf(path, text)]));
+			for (const [path, blob] of heldBlobs) have.set(path, blob.hash);
 			for (const [path, hash] of this.remote) have.set(path, hash);
 			asked = this.scope.generation;
-			parts = await this.api.snapshot(have, { listOnly: this.listOnly(this.copied && !this.synced) });
+			withBlobs = this.blobSupport === true;
+			if (!withBlobs && !this.blobsCompared && !existsSync(this.paths.copyBlobs)) {
+				mkdirSync(this.paths.own, { recursive: true });
+				writeFileSync(this.paths.copyBlobs, "");
+			}
+			parts = await this.api.snapshot(have, {
+				listOnly: this.listOnly(this.copied && !this.synced),
+				blobs: this.blobSupport === true
+			});
 			if (uploaded || holdsFiles(parts, have)) break;
 			if (this.opts.settings.onDemand === true) {
 				if (!this.uploadWanted) {
@@ -1927,6 +2371,7 @@ var SyncClient = class extends EventEmitter {
 		let sent = 0;
 		this.snapshotAnswers.clear();
 		const fromCopy = this.copied && !this.synced;
+		const blobsFromCopy = withBlobs && !this.blobsCompared;
 		for (const part of parts) for (const event of part.files) {
 			if (event.kind !== "dir" && !this.syncs(event.path)) continue;
 			if (event.kind === "listed") {
@@ -1940,21 +2385,31 @@ var SyncClient = class extends EventEmitter {
 				continue;
 			}
 			named.add(event.path);
-			if (event.kind === "file") {
+			if (event.kind === "file" || event.kind === "blob") {
 				present.add(event.path);
-				sent++;
+				if (event.kind === "file") sent++;
+			}
+			if (uploaded && event.kind === "removed" && heldBlobs.has(event.path)) {
+				this.receive({
+					kind: "unknown",
+					path: event.path
+				}, part.seq);
+				continue;
+			}
+			if (event.kind === "removed" && (held.has(event.path) ? fromCopy : blobsFromCopy && heldBlobs.has(event.path))) {
+				const text = held.get(event.path);
+				this.snapshotAnswers.set(event.path, {
+					hash: text === void 0 ? heldBlobs.get(event.path).hash : this.hashOf(event.path, text),
+					removed: true
+				});
 			}
-			if (event.kind === "removed" && fromCopy && held.has(event.path)) this.snapshotAnswers.set(event.path, {
-				text: held.get(event.path),
-				removed: true
-			});
 			this.receive(event, part.seq);
 		}
 		for (const [path, text] of held) {
 			if (named.has(path)) continue;
 			present.add(path);
 			this.snapshotAnswers.set(path, {
-				text,
+				hash: this.hashOf(path, text),
 				removed: false
 			});
 			this.receive({
@@ -1963,37 +2418,123 @@ var SyncClient = class extends EventEmitter {
 				text
 			}, seq);
 		}
-		for (const path of /* @__PURE__ */ new Set([...this.cloud.keys(), ...this.expected.keys()])) if (!present.has(path) && !named.has(path) && this.syncs(path)) this.receive({
-			kind: "removed",
-			path
-		}, seq);
+		for (const [path, blob] of heldBlobs) {
+			if (named.has(path)) continue;
+			present.add(path);
+			this.snapshotAnswers.set(path, {
+				hash: blob.hash,
+				removed: false
+			});
+			this.receive({
+				kind: "blob",
+				path,
+				hash: blob.hash,
+				size: blob.size ?? 0
+			}, seq);
+		}
+		const blind = this.blobSupport !== true;
+		for (const path of /* @__PURE__ */ new Set([...this.cloud.keys(), ...this.expected.keys()])) {
+			if (present.has(path) || named.has(path) || !this.syncs(path)) continue;
+			if (blind && this.knownBinary(path)) continue;
+			this.receive({
+				kind: "removed",
+				path
+			}, seq);
+		}
 		this.scopeTaken = asked;
 		this.log(`took the snapshot at seq ${seq} in ${parts.length} batch${parts.length === 1 ? "" : "es"}: ${sent} files sent, ${present.size - sent} already held here${this.remote.size > 0 ? `, ${this.remote.size} only on the server` : ""}`);
 		this.takenUpTo(seq);
 		this.synced = true;
+		if (withBlobs && !this.blobsCompared) {
+			this.blobsCompared = true;
+			rmSync(this.paths.copyBlobs, { force: true });
+		}
 		this.saveRemote();
 		await this.fetchWanted(wanted);
 		await this.settleUnsynced();
 		this.wake();
 		for (const path of await this.walk()) this.schedule(path);
+		for (const path of this.stalledDownloads) this.schedule(path);
+		this.stalledDownloads.clear();
+	}
+	/**
+	* Ask the server whether it keeps binary files (blobSupport), once per connection, before its snapshot. A probe that
+	* fails leaves what the last one found, null on a first connection, so the texts sync all the same and binary files
+	* wait as they are here: the snapshot is taken again after PROBE_RETRY_MS, doubling up to PROBE_RETRY_MAX_MS while it
+	* keeps failing, and asks again.
+	*/
+	async probeBlobs() {
+		const had = this.blobSupport;
+		try {
+			await this.askBlobs();
+		} finally {
+			if (had !== true && this.blobSupport === true) this.fileSeq.clear();
+		}
+	}
+	async askBlobs() {
+		const had = this.blobSupport;
+		try {
+			this.blobSupport = await this.api.blobRoute();
+		} catch (error) {
+			if (!(error instanceof Unreachable)) throw error;
+			this.log(`could not ask the sync server whether it keeps binary files (${error.message}); binary files wait for a later snapshot`);
+			clearTimeout(this.probeTimer);
+			this.probeTimer = setTimeout(() => {
+				if (this.connected && !this.probed) this.track(this.resync().catch((failed) => this.log(`could not reload the snapshot: ${failed.message}`)));
+			}, this.probeRetry);
+			this.probeRetry = Math.min(this.probeRetry * 2, PROBE_RETRY_MAX_MS);
+			return;
+		}
+		this.probed = true;
+		this.probeRetry = PROBE_RETRY_MS;
+		if (had !== this.blobSupport) this.log(this.blobSupport ? "the sync server keeps binary files" : "the sync server keeps no binary files, as one from before them: binary files are not synced");
 	}
 	/**
 	* The text the client holds of each synced file, which a snapshot request names by hash so the server leaves out what
 	* is the same (SnapshotRequest.have): the server's version this run last took in, else the version known.json names,
 	* else the file on disk, as in a hub cloned with git that never synced here. Only a text the client has is named,
 	* since a file the server leaves out holds the text named for it; a file larger than the server keeps is not synced,
-	* so it is not named either.
+	* so it is not named either. The binary files (`blobs`) come in the same order, by their sha256, only for a server that
+	* keeps them (blobSupport), and only ones the client sends (binarySkip).
 	*/
 	async holdings() {
-		const held = /* @__PURE__ */ new Map();
-		for (const [path, text] of this.cloud) if (typeof text === "string" && this.syncs(path)) held.set(path, text);
-		for (const [path, disk] of this.confirmed) if (!held.has(path) && disk?.text !== void 0 && this.syncs(path)) held.set(path, disk.text);
+		const texts = /* @__PURE__ */ new Map();
+		const blobs = /* @__PURE__ */ new Map();
+		const support = this.blobSupport === true;
+		const unnamed = /* @__PURE__ */ new Set();
+		for (const [path, file] of this.cloud) {
+			if (!this.syncs(path)) continue;
+			if (typeof file === "string") texts.set(path, file);
+			else if (isBlob(file) && support) blobs.set(path, file);
+			else if (isBlob(file)) unnamed.add(path);
+		}
+		for (const [path, disk] of this.confirmed) {
+			if (texts.has(path) || blobs.has(path) || unnamed.has(path) || !this.syncs(path)) continue;
+			if (disk?.text !== void 0) texts.set(path, disk.text);
+			else if (disk?.blob && support) blobs.set(path, {
+				kind: "blob",
+				hash: disk.hash
+			});
+			else if (disk?.blob) unnamed.add(path);
+		}
 		for (const path of await this.walk()) {
-			if (held.has(path)) continue;
+			if (texts.has(path) || blobs.has(path) || unnamed.has(path)) continue;
 			const local = await this.readLocal(path);
-			if (local.kind === "text" && !exceedsFileLimit(local.text)) held.set(path, local.text);
+			if (local.kind === "text" && !exceedsFileLimit(local.text)) texts.set(path, local.text);
+			else if (local.kind === "binary" && support && !this.binarySkip(path, local, false)) blobs.set(path, {
+				kind: "blob",
+				hash: local.hash,
+				size: local.size
+			});
 		}
-		return held;
+		return {
+			texts,
+			blobs
+		};
+	}
+	/** Whether the client knows `path` as a binary file: the server's version it took in, or what it left on disk. */
+	knownBinary(path) {
+		return isBlob(this.cloud.get(path)) || this.expected.get(path)?.blob === true;
 	}
 	/** The content hash of `text`, the one `path` was named with, worked out once per text. */
 	hashOf(path, text) {
@@ -2032,6 +2573,7 @@ var SyncClient = class extends EventEmitter {
 		}
 		if (Object.keys(files).length === 0) return null;
 		const dirs = await this.walkDirs();
+		const forgotten = await this.forgetBinaries();
 		let result;
 		try {
 			result = await this.api.upload(files, dirs);
@@ -2044,14 +2586,49 @@ var SyncClient = class extends EventEmitter {
 		}
 		if (!result.ok) {
 			this.log(`upload refused: ${result.message}`);
+			this.recallBinaries(forgotten);
 			return {
 				ok: false,
 				message: result.message
 			};
 		}
 		this.log(`uploaded the hub: ${result.files} files`);
+		await this.whenFree(() => this.editQueue((entries) => {
+			const stale = entries.filter((entry) => entry.kind === "blob" && entry.sent === void 0 && waiting(entry) && entry.base !== null);
+			for (const entry of stale) if (entry.kind === "blob") entry.base = null;
+			return stale.length > 0;
+		}));
 		return { ok: true };
 	}
+	/**
+	* Before an upload of the hub, which holds texts alone: known.json stops naming the binary files the server confirmed,
+	* and the client stops expecting them, saved before the upload is sent. Whatever happens after it, a failed snapshot
+	* or a client killed, the client then takes each for a file never synced here, and sends it as new (reconcile), rather
+	* than for one the server removed, which would remove it here. A run that started without known.json confirmed none,
+	* and writes no known.json here: a refused upload would leave it taking a text the server removed since the copy for
+	* one created here. Returns what it forgot, for recallBinaries.
+	*/
+	async forgetBinaries() {
+		const forgotten = /* @__PURE__ */ new Map();
+		for (const [path, disk] of this.confirmed) if (disk?.blob) forgotten.set(path, disk);
+		for (const [path, disk] of forgotten) {
+			this.confirmed.delete(path);
+			this.snapshotAnswers.delete(path);
+			const expected = this.expected.get(path);
+			if (expected?.blob && expected.hash === disk.hash) this.expected.delete(path);
+			if (isBlob(this.cloud.get(path))) this.cloud.delete(path);
+		}
+		if (forgotten.size > 0) await this.whenFree(() => underLock(this.root, () => writeKnown(this.root, this.knownFiles())));
+		return forgotten;
+	}
+	/** The server refused the upload, so it holds what it held: the binary files forgetBinaries forgot are known again. */
+	recallBinaries(forgotten) {
+		for (const [path, disk] of forgotten) {
+			if (!this.confirmed.has(path)) this.confirmed.set(path, disk);
+			if (!this.expected.has(path)) this.expected.set(path, disk);
+		}
+		if (forgotten.size > 0) this.saveKnown();
+	}
 	/** Tell the writer, once for each reason, that the server has no copy of the hub and refused this one (snapshotNow). */
 	refusedUpload(message) {
 		if (this.uploadRefusal === message) return;
@@ -2067,13 +2644,18 @@ var SyncClient = class extends EventEmitter {
 		if (this.closing) return;
 		const next = (this.chains.get(path) ?? Promise.resolve()).then(() => this.reconcile(path)).catch((error) => this.log(`${path}: ${error.stack ?? String(error)}`));
 		this.chains.set(path, next);
-		this.track(next).then(() => {
+		this.track(next, path).then(() => {
 			if (this.chains.get(path) === next) this.chains.delete(path);
 		});
 	}
-	track(promise) {
+	/** Count `promise` as work under way until it settles; `path` for one on that path's chain. */
+	track(promise, path) {
 		this.work.add(promise);
-		promise.finally(() => this.work.delete(promise)).catch(() => {});
+		if (path !== void 0) this.workPaths.set(promise, path);
+		promise.finally(() => {
+			this.work.delete(promise);
+			this.workPaths.delete(promise);
+		}).catch(() => {});
 		return promise;
 	}
 	/**
@@ -2084,26 +2666,34 @@ var SyncClient = class extends EventEmitter {
 	pending(path) {
 		return (this.inflight.get(path) ?? 0) > 0 || this.queue.some((entry) => waiting(entry) && entryPaths(entry).includes(path));
 	}
+	/**
+	* What the file at `path` holds now. A file larger than any text the server keeps (MAX_FILE_BYTES) is read in chunks
+	* first (scanFile): a binary file comes as its sha256 and size alone, so every reconcile after a snapshot, which reads
+	* every file, holds at most a chunk of it, and its bytes are read again only to be saved (bytesOf). Such a file that is
+	* UTF-8 is read whole, as a smaller file is, since the text is what reconcile compares; it is not sent either way
+	* (exceedsFileLimit).
+	*/
 	async readLocal(path) {
-		let bytes;
+		const file = join(this.paths.data, path);
 		try {
-			bytes = await readFile(join(this.paths.data, path));
+			if ((await stat(file)).size > 19e5) {
+				const scanned = await scanFile(file);
+				if (!scanned.text) return {
+					kind: "binary",
+					hash: scanned.hash,
+					size: scanned.size
+				};
+			}
+			return contentOf(await readFile(file));
 		} catch (error) {
 			const code = error.code;
 			if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") return { kind: "absent" };
 			throw error;
 		}
-		try {
-			return {
-				kind: "text",
-				text: decoder.decode(bytes)
-			};
-		} catch {
-			return {
-				kind: "binary",
-				hash: contentHash(bytes.toString("latin1"))
-			};
-		}
+	}
+	/** The bytes of binary file `content` at `path`: read again from the file when readLocal read it in chunks. */
+	async bytesOf(path, content) {
+		return content.bytes ?? await readFile(join(this.paths.data, path));
 	}
 	/**
 	* Compare the local file with what the client last left there and with the server's version, and act: queue a
@@ -2119,9 +2709,9 @@ var SyncClient = class extends EventEmitter {
 			await sleep$1(BINARY_RECHECK_MS);
 			const again = await this.readLocal(path);
 			if (again.kind !== "binary" || again.hash !== local.hash) return this.schedule(path);
-			return this.skipBinary(path, local.hash);
+			if (this.binarySkip(path, local, true)) return;
 		}
-		if (local.kind === "text" && exceedsFileLimit(local.text)) return this.skipLarge(path, local.text);
+		if (local.kind === "text" && exceedsFileLimit(local.text)) return this.skipLarge(path, contentHash(local.text), false);
 		const seen = this.expected.get(path);
 		if (seen === void 0 ? local.kind !== "absent" : !this.matches(seen, local)) {
 			await this.whenFree(() => this.syncQueue());
@@ -2130,48 +2720,49 @@ var SyncClient = class extends EventEmitter {
 			const after = this.expected.get(path);
 			if (after !== seen && after !== void 0 && this.matches(after, local)) return this.schedule(path);
 		}
-		const target = this.cloud.has(path) ? this.cloud.get(path) : this.synced && !this.scopeStale ? null : void 0;
+		const target = this.cloud.has(path) ? this.cloud.get(path) : this.synced && !this.scopeStale && (this.blobSupport === true || !this.knownBinary(path)) ? null : void 0;
 		const disk = this.expected.get(path);
 		const unheld = target === null && this.unheld.has(path);
 		if (disk === void 0) {
 			if (local.kind === "absent") {
-				if (typeof target === "string") await this.replace(path, target);
+				if (target !== null && target !== void 0) await this.replace(path, target);
 				return;
 			}
-			if (target === local.text) return this.adopt(path, local.text);
+			if (holdsServer(local, target)) return this.adoptContent(path, local);
 			if (!this.synced || target === void 0) return;
 			const answer = this.snapshotAnswers.get(path);
-			if (answer?.text === local.text && !this.pending(path)) {
+			if (answer?.hash === hashOfContent(local) && !this.pending(path)) {
 				this.snapshotAnswers.delete(path);
 				if (!answer.removed) {
-					this.adopt(path, local.text);
+					this.adoptContent(path, local);
 					return this.schedule(path);
 				}
-				const saved = await this.saveConflict(path, local.text);
-				this.expected.set(path, {
-					hash: contentHash(local.text),
-					text: local.text
-				});
+				const saved = await this.saveConflict(path, local.kind === "text" ? local.text : await this.bytesOf(path, local));
+				this.expected.set(path, diskOf(local));
 				return this.replace(path, null, saved);
 			}
+			if (local.kind === "binary") return this.queueBlob(path, local, { base: null });
 			return this.queueLocal(path, local.text, { start: target === null ? null : {
 				text: local.text,
 				server: local.text
 			} });
 		}
 		if (!this.matches(disk, local)) {
-			if (local.kind === "text" && target === local.text && !this.pending(path)) {
-				this.adopt(path, local.text);
+			if (holdsServer(local, target) && !this.pending(path)) {
+				this.adoptContent(path, local);
 				return this.release(path);
 			}
 			if (local.kind === "text") {
-				if (local.text === "" && disk?.text) {
+				if (local.text === "" && (disk?.text || disk?.blob)) {
 					await sleep$1(EMPTY_RECHECK_MS);
 					const again = await this.readLocal(path);
 					if (again.kind !== "text" || again.text !== "") return this.schedule(path);
 				}
+				const reported = !unheld && disk !== null ? await this.awaitEdit(path, local.text, disk) : null;
+				if (reported) return this.replayEdit(reported);
 				return this.queueLocal(path, local.text, unheld ? { start: null } : {});
 			}
+			if (local.kind === "binary") return this.queueBlob(path, local, unheld ? { base: null } : {});
 			if (target === null || disk === null) {
 				this.forget(path);
 				this.confirm(path, null);
@@ -2179,7 +2770,7 @@ var SyncClient = class extends EventEmitter {
 			}
 			return this.queueRemove(path, disk);
 		}
-		if (target === void 0 || (disk === null ? target === null : target !== null && disk.hash === contentHash(target))) {
+		if (target === void 0 || (disk === null ? target === null : target !== null && disk.hash === serverHash(target))) {
 			if (disk?.text !== void 0) this.remember(path, {
 				text: disk.text,
 				server: disk.text
@@ -2190,6 +2781,7 @@ var SyncClient = class extends EventEmitter {
 		}
 		if (this.pending(path)) return;
 		if (unheld && local.kind === "text") return this.queueUnheld(path, local.text);
+		if (unheld && local.kind === "binary") return this.queueBlob(path, local, { unheld: true });
 		await this.replace(path, target);
 	}
 	/**
@@ -2214,6 +2806,7 @@ var SyncClient = class extends EventEmitter {
 	}
 	matches(disk, local) {
 		if (disk === null) return local.kind === "absent";
+		if (disk.blob) return local.kind === "binary" && disk.hash === local.hash;
 		return local.kind === "text" && disk.hash === contentHash(local.text);
 	}
 	adopt(path, text) {
@@ -2230,6 +2823,17 @@ var SyncClient = class extends EventEmitter {
 			text
 		});
 	}
+	/** The file at `path` holds `content`, the server's version: adopted, a text as adopt does, a binary file by its sha256. */
+	adoptContent(path, content) {
+		if (content.kind === "text") return this.adopt(path, content.text);
+		const disk = {
+			hash: content.hash,
+			blob: true
+		};
+		this.expected.set(path, disk);
+		this.history.delete(path);
+		this.confirm(path, disk);
+	}
 	/** A removed file starts over: its earlier versions are gone from the server and are no base for a new one. */
 	forget(path) {
 		this.expected.set(path, null);
@@ -2260,24 +2864,51 @@ var SyncClient = class extends EventEmitter {
 		if (list.length > HISTORY) list.shift();
 		this.history.set(path, list);
 	}
-	skipBinary(path, hash) {
-		const key = `binary:${path}:${hash}`;
+	/**
+	* Whether the binary file at `path`, which holds `local`, stays as it is here: neither sent nor written over nor
+	* removed. So it does at a path the hub reads as text (readsAsText), larger than MAX_BLOB_BYTES or than the server took,
+	* on a server that keeps no binary files, and while the client does not know yet whether it does (blobSupport), which
+	* the snapshot after the probe reconciles again. With `tell`, the writer is told once for each content.
+	*/
+	binarySkip(path, local, tell) {
+		if (readsAsText(path)) {
+			if (tell) this.tellOnce(`text-only:${path}:${local.hash}`, {
+				kind: "binary-text-file",
+				path,
+				message: `${path} is not UTF-8 text, and the hub reads it as text (config.yaml, .md, .yaml, .yml, ops/*.log, .gitignore), so it is not synced and not overwritten; write it as UTF-8 text, or rename it if it is meant to be a binary file`
+			});
+			return true;
+		}
+		if (local.size > 52428800 || this.oversized.has(`${path}\0${local.hash}`)) {
+			if (tell) this.skipLarge(path, local.hash, true);
+			return true;
+		}
+		if (this.blobSupport === false) {
+			if (tell) this.skipBinary(path, local.hash);
+			return true;
+		}
+		return this.blobSupport === null;
+	}
+	/** Tell the writer of `problem` once for `key`, whatever runs into it again. */
+	tellOnce(key, problem) {
 		if (this.skipped.has(key)) return;
 		this.skipped.add(key);
-		this.problem({
+		this.problem(problem);
+	}
+	skipBinary(path, hash) {
+		this.tellOnce(`binary:${path}:${hash}`, {
 			kind: "skipped-binary",
 			path,
-			message: `${path} is not UTF-8 text, so it is not synced and not overwritten; other environments do not see it`
+			message: `${path} is not UTF-8 text, and the sync server keeps no binary files, as one from before them: it stays as it is here, not overwritten, and is sent once the sync server keeps binary files; other environments do not see it until then`
 		});
 	}
-	skipLarge(path, text) {
-		const key = `large:${path}:${contentHash(text)}`;
-		if (this.skipped.has(key)) return;
-		this.skipped.add(key);
-		this.problem({
+	/** A text of `path` larger than MAX_FILE_BYTES, or a binary file larger than the server keeps, of `hash`. */
+	skipLarge(path, hash, binary) {
+		const limit = binary ? `the ${MAX_BLOB_BYTES} bytes the sync server keeps of a binary file` : `the ${MAX_FILE_BYTES} bytes the sync server keeps of a file`;
+		this.tellOnce(`large:${path}:${hash}`, {
 			kind: "skipped-large",
 			path,
-			message: `${path} is larger than the ${MAX_FILE_BYTES} bytes the sync server keeps of a file, so it is not synced and not overwritten; other environments do not see it. Split it, or add it to .mainflow/.gitignore`
+			message: `${path} is larger than ${limit}, so it is not synced and not overwritten; other environments do not see it. ${binary ? "Make it smaller" : "Split it"}, or add it to .mainflow/.gitignore`
 		});
 	}
 	/**
@@ -2324,7 +2955,7 @@ var SyncClient = class extends EventEmitter {
 	*/
 	mayStay(path, held) {
 		if (!this.staysRemote(path)) return false;
-		return !(held?.has(path) ?? false) && typeof this.cloud.get(path) !== "string" && this.expected.get(path) === void 0 && !this.pending(path);
+		return !(held?.has(path) ?? false) && (this.cloud.get(path) ?? null) === null && this.expected.get(path) === void 0 && !this.pending(path);
 	}
 	/** Note `path` as only on the server, with the hash of the server's text as of `seq`, unless a newer version came. */
 	keepRemote(path, hash, seq) {
@@ -2386,22 +3017,34 @@ var SyncClient = class extends EventEmitter {
 	* file the client knows by its hash, so the server sends the targets and only what changed of the rest; the artifacts
 	* of closed mainlines other than the targets' stay listed. What comes is taken in as a broadcast of its batch's seq
 	* is: a target's text is written here, and a target named nowhere is not on the server, since the range covers it
-	* and `have` does not name it. Returns, besides, the files of other paths listed that may not stay on the server.
+	* and `have` does not name it. Returns, besides, the files of other paths listed that may not stay on the server. A
+	* binary file only on the server is not asked for while the client does not know that the server keeps binary files
+	* (blobSupport): such a snapshot would name it nowhere, as if it were gone. Nor is a target such a snapshot names
+	* nowhere taken for gone, since the server may hold a binary file there now. Both stay only on the server,
+	* `unavailable`.
 	*/
 	async fetchNow(targets) {
-		const sorted = [...new Set(targets)].filter((path) => this.syncs(path)).sort(comparePaths);
+		const asked = [...new Set(targets)].filter((path) => this.syncs(path));
+		const unavailable = this.blobSupport === true ? [] : asked.filter((path) => BLOB_HASH.test(this.remote.get(path) ?? ""));
+		const sorted = asked.filter((path) => !unavailable.includes(path)).sort(comparePaths);
 		const again = /* @__PURE__ */ new Set();
 		if (sorted.length === 0 || this.closing) return {
 			fetched: [],
 			gone: [],
-			again
+			again,
+			unavailable
 		};
 		const want = new Set(sorted);
 		for (const path of sorted) this.awaiting.add(path);
 		let done = false;
 		try {
 			const have = /* @__PURE__ */ new Map();
-			for (const [path, text] of this.cloud) if (typeof text === "string" && !want.has(path) && this.syncs(path)) have.set(path, this.hashOf(path, text));
+			const support = this.blobSupport === true;
+			for (const [path, file] of this.cloud) {
+				if (want.has(path) || !this.syncs(path)) continue;
+				if (typeof file === "string") have.set(path, this.hashOf(path, file));
+				else if (isBlob(file) && support) have.set(path, file.hash);
+			}
 			for (const [path, hash] of this.remote) if (!want.has(path)) have.set(path, hash);
 			const listOnly = this.listOnly(false)?.filter((prefix) => !sorted.some((path) => path.startsWith(prefix)));
 			const first = sorted[0];
@@ -2409,12 +3052,14 @@ var SyncClient = class extends EventEmitter {
 			const parts = await this.api.snapshot(have, {
 				listOnly,
 				after,
-				through: sorted.at(-1)
+				through: sorted.at(-1),
+				blobs: support
 			});
 			if (this.closing) return {
 				fetched: [],
 				gone: [],
-				again
+				again,
+				unavailable
 			};
 			const mentioned = /* @__PURE__ */ new Set();
 			const fetched = [];
@@ -2434,13 +3079,17 @@ var SyncClient = class extends EventEmitter {
 				if (want.has(event.path)) {
 					this.remote.delete(event.path);
 					if ((this.fileSeq.get(event.path) ?? -1) <= part.seq) this.fileSeq.delete(event.path);
-					if (event.kind === "file") fetched.push(event.path);
+					if (event.kind === "file" || event.kind === "blob") fetched.push(event.path);
 				}
 				this.receive(event, part.seq);
 			}
 			const gone = [];
 			for (const path of sorted) {
 				if (mentioned.has(path)) continue;
+				if (!support) {
+					unavailable.push(path);
+					continue;
+				}
 				if (this.remote.delete(path)) gone.push(path);
 				else this.receive({
 					kind: "removed",
@@ -2453,7 +3102,8 @@ var SyncClient = class extends EventEmitter {
 			return {
 				fetched,
 				gone,
-				again
+				again,
+				unavailable
 			};
 		} finally {
 			for (const path of sorted) {
@@ -2474,28 +3124,27 @@ var SyncClient = class extends EventEmitter {
 			if (targets.length === 0) return {
 				fetched: [],
 				gone: [],
-				none
+				none,
+				unavailable: []
 			};
-			const { fetched, gone } = await this.fetchNow(targets);
+			const { fetched, gone, unavailable } = await this.fetchNow(targets);
 			return {
 				fetched,
 				gone,
-				none
+				none,
+				unavailable
 			};
 		});
 	}
 	/**
 	* Download the files only on the server that `specs` name (fetchPaths), and resolve once each is written here: for
 	* `mainflow sync fetch` and the PreToolUse hook. Offline, or when the server cannot be reached, nothing is
-	* downloaded and `error` says why.
+	* downloaded and `error` says why. So it says why for each file that was not downloaded: a binary file whose download
+	* failed, or one asked for while the client does not know that the server keeps binary files.
 	*/
 	async fetch(specs) {
 		const covers = (spec) => [...this.remote.keys(), ...this.awaiting].some((path) => path === spec || path.startsWith(spec.endsWith("/") ? spec : `${spec}/`));
-		if (!specs.some(covers)) return {
-			fetched: [],
-			gone: [],
-			none: specs
-		};
+		if (!specs.some(covers)) return this.retryStuck(specs);
 		if (!this.online) return {
 			fetched: [],
 			gone: [],
@@ -2514,10 +3163,44 @@ var SyncClient = class extends EventEmitter {
 			};
 		}
 		await Promise.allSettled(result.fetched.map((path) => this.chains.get(path) ?? Promise.resolve()));
+		const fetched = result.fetched.filter((path) => existsSync(join(this.paths.data, path)));
+		const failed = [...result.fetched.flatMap((path) => fetched.includes(path) || !this.downloadErrors.has(path) ? [] : [`${path}: ${this.downloadErrors.get(path)}`]), ...result.unavailable.map((path) => `${path}: it may be a binary file, and ${this.blobSupport === false ? "the sync server keeps no binary files now" : "it is not known yet whether the sync server keeps binary files"}; it stays on the server, try again once mainflow sync is online`)];
 		return {
-			fetched: result.fetched.filter((path) => existsSync(join(this.paths.data, path))),
+			fetched,
 			gone: result.gone,
-			none: result.none
+			none: result.none,
+			...failed.length > 0 ? { error: `could not download ${failed.join("; ")}` } : {}
+		};
+	}
+	/**
+	* `fetch` for specs that name no file only on the server: a download that failed is no longer one, and is tried again
+	* on its own. Try it now, and say why for each that still is not here.
+	*/
+	async retryStuck(specs) {
+		const covered = (spec, path) => path === spec || path.startsWith(spec.endsWith("/") ? spec : `${spec}/`);
+		const missing = (path) => !existsSync(join(this.paths.data, path));
+		const stuck = [...this.stuckDownloads().keys()].filter((path) => specs.some((spec) => covered(spec, path)));
+		if (stuck.length === 0) return {
+			fetched: [],
+			gone: [],
+			none: specs
+		};
+		const none = specs.filter((spec) => !stuck.some((path) => covered(spec, path)));
+		if (!this.online) return {
+			fetched: [],
+			gone: [],
+			none,
+			error: "mainflow sync is offline: the sync server cannot be reached now"
+		};
+		for (const path of stuck) this.schedule(path);
+		await Promise.allSettled(stuck.map((path) => this.chains.get(path) ?? Promise.resolve()));
+		const failed = stuck.filter(missing).map((path) => `${path}: ${this.downloadErrors.get(path) ?? "it did not come"}`);
+		const again = stuck.filter(missing).every((path) => this.stalledDownloads.has(path)) ? "at the next connection" : "later on its own";
+		return {
+			fetched: stuck.filter((path) => !missing(path)),
+			gone: [],
+			none,
+			...failed.length > 0 ? { error: `could not download ${failed.join("; ")}; mainflow sync tries again ${again}` } : {}
 		};
 	}
 	/** Mainline `dir`'s file came: when it opens the mainline, its artifacts only on the server come here. */
@@ -2542,6 +3225,28 @@ var SyncClient = class extends EventEmitter {
 	restoreRemote() {
 		for (const [path, hash] of Object.entries(readRemote(this.root))) if (this.syncs(path) && artifactOf(path) !== null && this.expected.get(path) === void 0) this.remote.set(path, hash);
 	}
+	/**
+	* What remote.json lists: the files only on the server, and the artifacts whose download failed and waits for a retry.
+	* The interface lists both as files not here yet, so a failed download stays in sight; fetch tries it again and says
+	* why it failed. A file leaves the list when its download succeeds.
+	*/
+	listedRemote() {
+		const listed = new Map(this.remote);
+		for (const [path, hash] of this.stuckDownloads()) if (!listed.has(path)) listed.set(path, hash);
+		return listed;
+	}
+	/**
+	* The artifacts whose download failed and that are still not here, by the sha256 the server holds: the server still
+	* has that binary version, and the client keeps the error for it. A file the server removed or changed since is not one.
+	*/
+	stuckDownloads() {
+		const stuck = /* @__PURE__ */ new Map();
+		for (const path of this.downloadErrors.keys()) {
+			const file = this.cloud.get(path);
+			if (isBlob(file) && artifactOf(path) !== null && !existsSync(join(this.paths.data, path))) stuck.set(path, file.hash);
+		}
+		return stuck;
+	}
 	saveRemote() {
 		if (this.remoteTimer) return;
 		this.remoteTimer = setTimeout(() => this.saveRemoteNow(), 200);
@@ -2550,9 +3255,10 @@ var SyncClient = class extends EventEmitter {
 		if (this.abandoned && !final) return;
 		clearTimeout(this.remoteTimer);
 		this.remoteTimer = void 0;
-		if (this.remote.size === 0 && !existsSync(this.paths.remote)) return;
+		const listed = this.listedRemote();
+		if (listed.size === 0 && !existsSync(this.paths.remote)) return;
 		try {
-			writeRemote(this.root, Object.fromEntries([...this.remote].sort(([a], [b]) => comparePaths(a, b))));
+			writeRemote(this.root, Object.fromEntries([...listed].sort(([a], [b]) => comparePaths(a, b))));
 		} catch (error) {
 			this.log(`could not save local/sync/remote.json: ${error.message}`);
 		}
@@ -2566,15 +3272,18 @@ var SyncClient = class extends EventEmitter {
 	* not lost; it is read again shortly after, for a program that still held the old file open. A new file is linked
 	* into place, which fails rather than overwrite a file created meanwhile; a removed file is first moved aside and
 	* checked. `unsynced` names where the text of a never synced file the server no longer has was saved: the writer is
-	* told of it once the file is removed, and it is deleted again when a write in the outbox keeps the file instead.
+	* told of it once the file is removed, and it is deleted again when a write in the outbox keeps the file instead. A
+	* binary file is downloaded into the prepared path first, checked against its sha256; one that cannot be downloaded
+	* now is left as it is (download).
 	*/
 	async replace(path, target, unsynced) {
 		const file = join(this.paths.data, path);
 		const temp = this.tempName();
-		this.trace(`replacing ${path} with ${short(target)}`);
+		this.trace(`replacing ${path} with ${isBlob(target) ? `blob ${target.hash.slice(0, 7)}` : short(target)}`);
 		if (target !== null) {
 			await mkdir(dirname(file), { recursive: true });
-			await writeFile(temp, target);
+			if (typeof target === "string") await writeFile(temp, target);
+			else if (!await this.download(path, target, temp)) return;
 		}
 		let step;
 		try {
@@ -2596,24 +3305,25 @@ var SyncClient = class extends EventEmitter {
 				saved: unsynced,
 				message: `${path} was never synced here and the sync server no longer has it, so it was removed here too; its text was saved to ${unsynced}`
 			});
-			if (step.moved !== null && step.disk && contentHash(step.moved) !== step.disk.hash) {
-				const saved = await this.saveConflict(path, step.moved);
+			if (step.moved !== null && step.disk && !this.matches(step.disk, step.moved)) {
+				const saved = await this.saveConflict(path, step.moved.kind === "text" ? step.moved.text : step.moved.bytes);
 				this.problem({
 					kind: "conflict",
 					path,
 					saved,
-					message: `${path} was removed by another environment while it was being written here; the text written here was saved to ${saved}`
+					message: `${path} was removed by another environment while it was being written here; the ${step.moved.kind === "text" ? "text" : "binary file"} written here was saved to ${saved}`
 				});
 			}
 			return;
 		}
 		const { displaced, swapped, from } = step;
-		this.trace(`wrote ${path} ${short(target)}${swapped ? " (exchanged)" : ""}; displaced ${short(displaced)}`);
-		const changed = displaced !== null && contentHash(displaced) !== from.over.hash;
-		const later = swapped && changed && displaced === "";
+		this.trace(`wrote ${path} ${isBlob(target) ? `blob ${target.hash.slice(0, 7)}` : short(target)}${swapped ? " (exchanged)" : ""}; displaced ${displaced?.kind === "binary" ? `blob ${displaced.hash.slice(0, 7)}` : short(displaced?.text ?? null)}`);
+		const changed = displaced !== null && !this.matches(from.over, displaced);
+		const later = swapped && changed && displaced.kind === "text" && displaced.text === "";
 		if (changed && !later) {
-			this.log(`${path}: a local write landed while the server's version was written; sending it`);
-			await this.queueLocal(path, displaced, { displaced: from });
+			this.log(`${path}: a local write landed while the server's version was written; ${displaced.kind === "text" ? "sending it" : "saving it"}`);
+			if (displaced.kind === "text") await this.queueLocal(path, displaced.text, { displaced: from });
+			else await this.displacedBinary(path, displaced);
 		}
 		if (swapped) {
 			const recheck = this.recheck(path, temp, later ? null : displaced, from);
@@ -2674,11 +3384,16 @@ var SyncClient = class extends EventEmitter {
 		const disk = this.expected.get(path);
 		const read = (at) => {
 			try {
-				return readFileSync(at, "utf8");
+				return contentOf(readFileSync(at));
 			} catch {
 				return null;
 			}
 		};
+		/** Whether the file at `at` holds the server's version. */
+		const holdsTarget = (at) => {
+			const content = read(at);
+			return content !== null && target !== null && holdsServer(content, target);
+		};
 		if (target === null) {
 			try {
 				renameSync(file, temp);
@@ -2728,7 +3443,7 @@ var SyncClient = class extends EventEmitter {
 			if (answer === "ok") this.swapFailures = 0;
 			else {
 				this.swapFailed(path, answer === "unsupported" ? "the file system refused it" : answer.message);
-				if (answer !== "unsupported" && read(file) === target && read(temp) !== target) answer = "ok";
+				if (answer !== "unsupported" && holdsTarget(file) && !holdsTarget(temp)) answer = "ok";
 			}
 			if (answer === "ok") {
 				swapped = true;
@@ -2761,34 +3476,119 @@ var SyncClient = class extends EventEmitter {
 	*/
 	async recheck(path, temp, taken, from) {
 		await sleep$1(taken === null ? EMPTY_RECHECK_MS : LATE_WRITE_MS);
-		const later = await readFile(temp, "utf8").catch(() => null);
+		const later = await readFile(temp).then(contentOf, () => null);
 		await rm(temp, { force: true });
-		if (later !== null && later !== taken && contentHash(later) !== from.over.hash) {
-			this.log(`${path}: a late write into the replaced file; sending it`);
-			const held = taken === null ? from : {
+		if (later !== null && (taken === null || !sameLocal(later, taken)) && !this.matches(from.over, later)) {
+			this.log(`${path}: a late write into the replaced file; ${later.kind === "text" ? "sending it" : "saving it"}`);
+			if (later.kind === "binary") return this.withChain(path, () => this.displacedBinary(path, later));
+			const held = taken?.kind !== "text" ? from : {
 				...from,
-				among: /* @__PURE__ */ new Set([...from.among, taken])
+				among: /* @__PURE__ */ new Set([...from.among, taken.text])
 			};
-			await this.withChain(path, () => this.queueLocal(path, later, { displaced: held }));
+			await this.withChain(path, () => this.queueLocal(path, later.text, { displaced: held }));
+		}
+	}
+	/**
+	* A binary file a program wrote while the server's version took its place (layer 3), now off disk: it cannot be merged
+	* with the server's version, so it is saved and the writer told, as a refused binary file is.
+	*/
+	async displacedBinary(path, content) {
+		const saved = await this.saveConflict(path, content.bytes);
+		this.problem({
+			kind: "conflict",
+			path,
+			saved,
+			message: `${path}: a binary file was written here while the server's version took its place; the file written here was saved to ${saved} and the file now has the server's version`
+		});
+	}
+	/**
+	* Download the content of `blob`, the server's version of `path`, into `temp`: true once it is there and of its sha256.
+	* Offline, or when the download fails, nothing is written and false comes back, and downloadErrors keeps why for
+	* fetch. While online it is tried again after DOWNLOAD_BACKOFF_MS, doubling, with one timer for each path. A server
+	* that could not be reached or failed is tried for as long as the connection holds, up to BLOB_BACKOFF_MAX_MS between
+	* tries. Content of another sha256, or a file this machine could not write, as on a full disk, is tried DOWNLOAD_TRIES
+	* times in a row, when the writer is told and the file waits for the next connection's snapshot. So does a file whose
+	* download the connection dropped under: the snapshot after reconnecting names its version again, which receive takes
+	* for one it already holds, so the file is reconciled again after that snapshot. Content the server no longer holds,
+	* as when the file changed again meanwhile and the old content was cleaned up, reloads the snapshot, once per content
+	* on a connection.
+	*/
+	async download(path, blob, temp) {
+		clearTimeout(this.downloadRetries.get(path));
+		this.downloadRetries.delete(path);
+		try {
+			if (await this.api.downloadBlob(blob.hash, temp)) {
+				this.downloadFailures.delete(blob.hash);
+				if (this.downloadErrors.delete(path)) this.saveRemote();
+				return true;
+			}
+			await rm(temp, { force: true });
+			this.downloadErrors.set(path, `the sync server no longer holds its content ${blob.hash.slice(0, 7)}`);
+			this.saveRemote();
+			this.log(`${path}: the sync server no longer holds its content ${blob.hash.slice(0, 7)}; reloading the snapshot`);
+			if (!this.missingDownloads.has(blob.hash) && this.online) {
+				this.missingDownloads.add(blob.hash);
+				this.track(this.resync().catch((error) => this.log(`could not reload the snapshot: ${error.message}`)));
+			}
+			return false;
+		} catch (error) {
+			await rm(temp, { force: true });
+			const reason = error.message;
+			this.downloadErrors.set(path, reason);
+			this.saveRemote();
+			this.log(`${path}: could not download its content ${blob.hash.slice(0, 7)}: ${reason}`);
+			if (this.closing) return false;
+			if (!this.online) {
+				this.stalledDownloads.add(path);
+				return false;
+			}
+			const failures = (this.downloadFailures.get(blob.hash) ?? 0) + 1;
+			this.downloadFailures.set(blob.hash, failures);
+			if (!!(error instanceof BlobMismatch || error instanceof LocalWriteError) && failures >= DOWNLOAD_TRIES) {
+				this.stalledDownloads.add(path);
+				this.tellOnce(`download:${path}:${blob.hash}`, {
+					kind: "download-failed",
+					path,
+					message: `${path}: the sync server's version could not be downloaded ${failures} times in a row (${reason}); the file stays as it is here, and the next connection tries again`
+				});
+				return false;
+			}
+			const timer = setTimeout(() => {
+				this.downloadRetries.delete(path);
+				this.schedule(path);
+			}, Math.min((this.opts.downloadBackoffMs ?? DOWNLOAD_BACKOFF_MS) * 2 ** Math.min(failures - 1, 30), BLOB_BACKOFF_MAX_MS));
+			this.downloadRetries.set(path, timer);
+			return false;
 		}
 	}
 	withChain(path, fn) {
 		const next = (this.chains.get(path) ?? Promise.resolve()).then(fn).catch((error) => this.log(`${path}: ${String(error)}`));
 		this.chains.set(path, next);
-		return this.track(next);
-	}
-	wrote(path, text) {
+		return this.track(next, path);
+	}
+	/** The server's version `target` was written at `path`: what the client leaves there, and confirmed. */
+	wrote(path, target) {
+		if (isBlob(target)) {
+			const disk = {
+				hash: target.hash,
+				blob: true
+			};
+			this.expected.set(path, disk);
+			this.history.delete(path);
+			this.confirm(path, disk);
+			return;
+		}
 		this.expected.set(path, {
-			hash: contentHash(text),
-			text
+			hash: contentHash(target),
+			text: target
 		});
 		this.remember(path, {
-			text,
-			server: text
+			text: target,
+			server: target
 		});
 		this.confirm(path, {
-			hash: contentHash(text),
-			text
+			hash: contentHash(target),
+			text: target
 		});
 	}
 	/**
@@ -2831,7 +3631,8 @@ var SyncClient = class extends EventEmitter {
 	* disk, is not on disk: it was written over the version the client had left there, and on a version the old file held
 	* (layer 3); with none of those left, it is based on the text the client had left there, so layer 2 still tells the
 	* writer's lines from the ones the server changed meanwhile. `start` overrides layer 1: the version the writer started
-	* from, or null for a new file.
+	* from, or null for a new file. A text written over a binary file the client left there is based on that file's sha256,
+	* with no base text: the server replaces the binary file with it when it still holds that one (PatchRequest).
 	*/
 	async queueLocal(path, text, options = {}) {
 		const { displaced } = options;
@@ -2843,7 +3644,7 @@ var SyncClient = class extends EventEmitter {
 				hash: contentHash(text),
 				text
 			});
-			let start = options.start !== void 0 ? options.start ?? void 0 : before === null ? void 0 : this.startOf(path, text, before, {
+			let start = options.start !== void 0 ? options.start ?? void 0 : before === null || before?.blob ? void 0 : this.startOf(path, text, before, {
 				entries,
 				among: displaced?.among
 			});
@@ -2879,6 +3680,74 @@ var SyncClient = class extends EventEmitter {
 		this.trace(`new ${path} changed before it was queued; reconciling it again`);
 		this.schedule(path);
 	}
+	/**
+	* Queue the binary file at `path`, which held `local` when it was read, as a write of its own after every write queued
+	* already. In the hold of the write lock that queues it, the file is read again, and its content goes into blobs/
+	* (stageHeld), so the entry uploads what the file held as it was queued (I2). The base is the hash of what the client
+	* expected there before; `base: null` sends it as new. A file that changed since it was read, or that holds what the
+	* client expects already, is reconciled again instead. With `unheld` the client expects that content there already, a
+	* file the server never held (unheld), as after the client uploaded the hub; it is sent as new while the server still
+	* has no file there.
+	*/
+	async queueBlob(path, local, options = {}) {
+		if (await this.enqueue(() => {
+			const before = this.expected.get(path);
+			const expected = before?.blob === true && before.hash === local.hash;
+			if (options.unheld ? !expected || !this.unheld.has(path) || (this.cloud.get(path) ?? null) !== null : expected) return null;
+			if (!this.stageHeld(path, local.hash)) return null;
+			this.expected.set(path, {
+				hash: local.hash,
+				blob: true
+			});
+			const base = options.base === null || options.unheld ? null : before?.hash ?? null;
+			this.trace(`local ${path} blob ${local.hash.slice(0, 7)} base ${base?.slice(0, 7) ?? "null"}`);
+			return {
+				kind: "blob",
+				path,
+				hash: local.hash,
+				size: local.size,
+				base
+			};
+		}) !== null) return;
+		this.trace(`binary ${path} changed before it was queued; reconciling it again`);
+		this.schedule(path);
+	}
+	/**
+	* Keep the content of sha256 `hash` in blobs/ when the file at `path` holds it now: false when it holds anything else.
+	* Called under the write lock, so the content leaves blobs/ only once no entry of the outbox names it (pruneStaged).
+	* The file is copied first, a clone of it where the file system makes one (APFS), and the copy is hashed in chunks, so
+	* a file of up to MAX_BLOB_BYTES is never held in memory whole, and what blobs/ keeps is what was hashed. With the
+	* content kept already, the file is hashed in chunks alone.
+	*/
+	stageHeld(path, hash) {
+		const file = join(this.paths.data, path);
+		const staged = join(this.paths.blobs, hash);
+		if (existsSync(staged)) return sha256File(file) === hash;
+		mkdirSync(this.paths.blobs, { recursive: true });
+		const temp = `${staged}.tmp`;
+		try {
+			copyFileSync(file, temp);
+		} catch {
+			return false;
+		}
+		if (sha256File(temp) !== hash) {
+			rmSync(temp, { force: true });
+			return false;
+		}
+		renameSync(temp, staged);
+		return true;
+	}
+	/** Remove from blobs/ the content no binary file's write in `entries`, the outbox, names. Called under the write lock. */
+	pruneStaged(entries) {
+		let names;
+		try {
+			names = readdirSync(this.paths.blobs);
+		} catch {
+			return;
+		}
+		const named = new Set(entries.flatMap((entry) => entry.kind === "blob" ? [entry.hash] : []));
+		for (const name of names) if (!named.has(name)) rmSync(join(this.paths.blobs, name), { force: true });
+	}
 	/** What the response to queued edit `entry` means for the writer (layer 2), then wait for the broadcast it caused. */
 	async settleEdit(entry, response, context, sent) {
 		const { path } = entry;
@@ -2901,15 +3770,16 @@ var SyncClient = class extends EventEmitter {
 		await this.refuse(entry, [{
 			kind: conflict ? "conflict" : "refused",
 			path,
-			text: context.writer,
+			saves: true,
 			message: (saved) => `${path}: the server refused the change (${response.message}); the text written here was saved to ${saved}${conflict ? " and the file now has the server's version" : ""}`
 		}]);
 		if ("files" in response && response.files.some((f) => f.path === path)) await this.delivery(path, response.seq);
 	}
 	/**
 	* Layer 2. Report only when the writer's own content may be lost: lines it added that the result lacks, or lines
-	* it removed that the result still has. A writer that rewrote an older version unchanged, while the disk had
-	* other environments' additions, is taken as deleting those additions, which were kept. A result that only adds
+	* it removed that the result still has. A writer that rewrote an older version unchanged, while the disk had lines
+	* added since, here or in another environment, is taken as deleting those lines, which were kept: content alone does
+	* not tell it from a program that read the older version and wrote it back. A result that only adds
 	* other environments' changes to the writer's text is information.
 	*/
 	classify(path, context, result) {
@@ -2950,7 +3820,7 @@ var SyncClient = class extends EventEmitter {
 			if (reverted.length) return this.problem({
 				kind: "deletion-undone",
 				path,
-				message: `${path}: the write removed ${reverted.length} line(s) another environment added, such as "${reverted[0]}"; they were kept. Delete through a mainflow command or the Edit tool`
+				message: `${path}: the write put back an earlier version of the file without ${reverted.length} line(s) added since, here or in another environment, such as "${reverted[0]}"; they were kept, as a program holding the earlier version writes it back the same way. Delete them through a mainflow command or the Edit tool`
 			});
 		}
 		this.info(path, "merged with changes from other environments");
@@ -2978,7 +3848,7 @@ var SyncClient = class extends EventEmitter {
 		if (!response.ok) return this.refuse(entry, [{
 			kind: "refused",
 			path,
-			text: null,
+			saves: false,
 			message: () => `${path}: the server refused the deletion (${response.message})`
 		}]);
 		if (response.files.some((f) => f.path === path && f.kind === "removed")) this.confirmWritten(path, null);
@@ -2990,12 +3860,45 @@ var SyncClient = class extends EventEmitter {
 		if (response.files.some((f) => f.path === path)) await this.delivery(path, response.seq);
 	}
 	/**
+	* What the server answered to binary file `entry`, its content uploaded first: confirmed when applied; refused, as a
+	* conflict when the server holds another version than its base, its content saved and the writer told, as a refused
+	* edit's text is, and the server's version takes its place.
+	*/
+	async settleBlob(entry, response) {
+		const { path } = entry;
+		this.trace(`response ${path} ${response.ok ? `${response.value} blob ${entry.hash.slice(0, 7)}` : `${response.reason}: ${response.message}`}`);
+		if (response.ok) {
+			const disk = this.expected.get(path);
+			if (disk?.blob && disk.hash === entry.hash) this.confirm(path, {
+				hash: entry.hash,
+				blob: true
+			});
+			if (response.files.some((f) => f.path === path)) await this.delivery(path, response.seq);
+			return;
+		}
+		const conflict = response.reason === "conflict";
+		await this.refuse(entry, [{
+			kind: conflict ? "conflict" : "refused",
+			path,
+			saves: true,
+			message: (saved) => `${path}: the server refused the binary file written here (${response.message}); it was saved to ${saved}${conflict ? " and the file now has the server's version" : ""}`
+		}]);
+		if ("files" in response && response.files.some((f) => f.path === path)) await this.delivery(path, response.seq);
+	}
+	/**
 	* What an outbox entry left on disk is what the client expects there; a displaced text left nothing there, since the
 	* server's version took it off. The versions it holds need nothing more: the outbox is where versions() reads them.
 	*/
 	restoreEntry(entry) {
 		if (entry.refused) {
 			for (const path of entry.refused.paths) {
+				if (entry.kind === "blob") {
+					if (path === entry.path) this.expected.set(path, {
+						hash: entry.hash,
+						blob: true
+					});
+					continue;
+				}
 				const text = wroteAt(entry, path);
 				if (text !== void 0) this.expected.set(path, text === null ? null : {
 					hash: contentHash(text),
@@ -3013,7 +3916,11 @@ var SyncClient = class extends EventEmitter {
 				hash: contentHash(entry.text),
 				text: entry.text
 			});
-		} else this.expected.set(entry.path, null);
+		} else if (entry.kind === "blob") this.expected.set(entry.path, {
+			hash: entry.hash,
+			blob: true
+		});
+		else this.expected.set(entry.path, null);
 	}
 	/**
 	* Hold the write lock for `fn`; work stop() abandoned gets an error ('abandoned after stop') instead, so it leaves
@@ -3060,7 +3967,10 @@ var SyncClient = class extends EventEmitter {
 			changed = true;
 			this.resolveBases(entries);
 		}
-		if (changed) writeQueue(this.root, entries);
+		if (changed) {
+			writeQueue(this.root, entries);
+			this.pruneStaged(entries);
+		}
 		this.queue = entries;
 		return entries;
 	}
@@ -3144,6 +4054,12 @@ var SyncClient = class extends EventEmitter {
 				text: before,
 				base: null
 			};
+			else if (seen.blob) write = {
+				kind: "patch",
+				path,
+				text: before,
+				base: seen.hash
+			};
 			else if (seen.hash !== contentHash(before)) write = editOn(path, before, this.startOf(path, before, seen, {
 				entries,
 				upto: at
@@ -3234,7 +4150,10 @@ var SyncClient = class extends EventEmitter {
 	* outbox under the write lock; while another writer holds the lock longer than a writer waits for it, the entry
 	* stays and is taken out on a later try, without being sent again. Before an entry is first sent, the request it
 	* sends and its firstSentSeq are written to the outbox (`sent`), so it is sent again as it was even after a restart,
-	* and nothing is merged into it. An edit whose base cannot be moved onto the server's version is not sent.
+	* and nothing is merged into it. An edit whose base cannot be moved onto the server's version is not sent. A binary
+	* file's content is uploaded before its write is first sent, so the server never gets a `file.blob` of content it was
+	* not given (uploadEntry); on a server that keeps no binary files it is not sent, and stays as it is here (dropBlob).
+	* While its upload waits, the writes of other paths go ahead of it, each path's writes still in order (nextEntry).
 	*/
 	flushQueue() {
 		if (this.flushing || this.closing) return Promise.resolve();
@@ -3249,13 +4168,19 @@ var SyncClient = class extends EventEmitter {
 		try {
 			while (this.caughtUp) {
 				let entry;
+				let wake;
 				let again = false;
 				let unmergeable = false;
+				let upload = false;
 				this.editQueue((entries) => {
-					entry = entries.find((queued) => waiting(queued) || this.answered.has(queued.id));
+					({entry, wake} = this.nextEntry(entries));
 					if (!entry || this.answered.has(entry.id)) return false;
 					again = entry.firstSentSeq !== void 0;
 					if (entry.sent) return false;
+					if (entry.kind === "blob" && (this.blobSupport !== true || !this.uploadedBlobs.has(entry.hash))) {
+						upload = true;
+						return false;
+					}
 					const request = this.prepare(entry);
 					if (!request) {
 						unmergeable = true;
@@ -3264,7 +4189,14 @@ var SyncClient = class extends EventEmitter {
 					entry.sent = request;
 					entry.firstSentSeq ??= this.hubSeq;
 				});
-				if (!entry || this.closing) break;
+				if (!entry || this.closing) {
+					if (!entry && wake !== void 0) this.retryQueue(Math.max(0, wake - Date.now()));
+					break;
+				}
+				if (upload) {
+					await this.uploadEntry(entry);
+					continue;
+				}
 				if (unmergeable) await this.refuseUnmergeable(entry);
 				else if (!this.answered.has(entry.id)) {
 					this.sending = entry.id;
@@ -3279,9 +4211,199 @@ var SyncClient = class extends EventEmitter {
 			this.flushing = false;
 		}
 	}
-	retryQueue() {
+	/**
+	* The entry the outbox sends next: the first one waiting, or answered but not taken out yet (a refused write is
+	* answered and waits for nothing). A binary file's write whose content cannot be uploaded now (uploadHeld) waits, and
+	* so does every write after it about one of the paths of a write that waits, so the writes of each path still go in
+	* order; the writes of the other paths go ahead of it. An operation that waits, as one about such a path, holds every
+	* write after it: it may give out ids the writes after it name (renumber). `wake` is when the first write that waits on
+	* a time may go, undefined when none does.
+	*/
+	nextEntry(entries) {
+		const now = Date.now();
+		const held = /* @__PURE__ */ new Set();
+		let wake;
+		for (const queued of entries) {
+			if (this.answered.has(queued.id)) return {
+				entry: queued,
+				wake
+			};
+			if (!waiting(queued)) continue;
+			const paths = entryPaths(queued);
+			if (paths.some((path) => held.has(path))) {
+				if (queued.kind === "op") return { wake };
+				for (const path of paths) held.add(path);
+				continue;
+			}
+			const until = queued.kind === "blob" ? this.uploadHeld(queued) : 0;
+			if (until > now) {
+				for (const path of paths) held.add(path);
+				if (until !== Infinity) wake = Math.min(wake ?? until, until);
+				continue;
+			}
+			return {
+				entry: queued,
+				wake
+			};
+		}
+		return { wake };
+	}
+	/**
+	* Until when binary file `entry`'s write waits for its content to be uploaded: 0 when it may go now, as one uploaded
+	* already; Infinity while the client does not know whether the server keeps binary files, until the snapshot after
+	* the probe sends the outbox again. On a server that keeps none it goes at once, to be dropped (uploadEntry).
+	*/
+	uploadHeld(entry) {
+		if (entry.sent !== void 0 || this.blobSupport === false) return 0;
+		if (this.blobSupport === null) return Infinity;
+		if (this.uploadedBlobs.has(entry.hash)) return 0;
+		return Math.max(this.uploadHolds.get(entry.id) ?? 0, this.uploadAfter.get(entry.hash) ?? 0);
+	}
+	/** Send the outbox again in `after` ms, or shortly. */
+	retryQueue(after) {
 		clearTimeout(this.queueTimer);
-		if (!this.stopped && !this.closing) this.queueTimer = setTimeout(() => void this.track(this.flushQueue()), 1e3 + Math.random() * 1e3);
+		if (!this.stopped && !this.closing) this.queueTimer = setTimeout(() => void this.track(this.flushQueue()), after ?? 1e3 + Math.random() * 1e3);
+	}
+	/**
+	* Upload the content of binary file `entry` from blobs/, before its write is sent. Once uploaded, the write goes next.
+	* One that cannot be uploaded now waits (uploadHeld) while the writes of other paths go ahead: the time the server
+	* asked for while it deletes that content (Retry-After), or after a failure (uploadFailed). Content blobs/ no longer has
+	* whole, or that the server found not of its sha256, is read again from the file each time, when the file still holds
+	* it (stageHeld); when it does not, the write is dropped as superseded (supersede). On a server that keeps no binary
+	* files, or that refuses the content as too large, the write is dropped and the file left as it is here (dropBlob).
+	*/
+	async uploadEntry(entry) {
+		if (this.blobSupport === false) return this.dropBlob(entry, () => this.skipBinary(entry.path, entry.hash));
+		if (this.blobSupport === null) return;
+		this.uploadAfter.delete(entry.hash);
+		const staged = join(this.paths.blobs, entry.hash);
+		if ((await stat(staged).catch(() => null))?.size !== entry.size) {
+			rmSync(staged, { force: true });
+			if (!await this.restage(entry)) return this.supersede(entry);
+		}
+		let result;
+		try {
+			result = await this.api.putBlob(entry.hash, staged, entry.size);
+		} catch (error) {
+			if (!(error instanceof Unreachable || error instanceof ServerError)) throw error;
+			return this.uploadFailed(entry, error.message);
+		}
+		if (result.ok) {
+			this.uploadedBlobs.add(entry.hash);
+			this.uploadFailures.delete(entry.id);
+			this.uploadHolds.delete(entry.id);
+			this.trace(`uploaded ${entry.path} blob ${entry.hash.slice(0, 7)}`);
+			return;
+		}
+		if ("retryAfter" in result) {
+			this.log(`${entry.path}: the sync server is deleting the content ${entry.hash.slice(0, 7)}; uploading it again in ${result.retryAfter} s`);
+			this.uploadAfter.set(entry.hash, Date.now() + result.retryAfter * 1e3);
+			return;
+		}
+		this.log(`${entry.path}: the sync server refused its content ${entry.hash.slice(0, 7)}: ${result.message}`);
+		switch (result.refused) {
+			case "hash-mismatch":
+				rmSync(staged, { force: true });
+				if (!await this.restage(entry)) return this.supersede(entry);
+				return this.uploadFailed(entry, result.message, true);
+			case "too-large":
+				this.oversized.add(`${entry.path}\0${entry.hash}`);
+				return this.dropBlob(entry, () => this.skipLarge(entry.path, entry.hash, true));
+			case "unsupported":
+				this.blobSupport = false;
+				return this.dropBlob(entry, () => this.skipBinary(entry.path, entry.hash));
+			default: return this.uploadFailed(entry, result.message);
+		}
+	}
+	/**
+	* The upload of binary file `entry`'s content failed for `reason`: its write waits, while the writes of other paths go
+	* ahead (nextEntry). The first BLOB_FAILURES - 1 failures in a row are tried again shortly, or `atOnce`, as content
+	* read again after a hash-mismatch is; from the BLOB_FAILURES-th on, the wait doubles up to BLOB_BACKOFF_MAX_MS, and
+	* the writer is told once for the write.
+	*/
+	uploadFailed(entry, reason, atOnce = false) {
+		const failures = (this.uploadFailures.get(entry.id) ?? 0) + 1;
+		this.uploadFailures.set(entry.id, failures);
+		if (failures < BLOB_FAILURES) {
+			this.log(`${entry.path}: could not upload its content ${entry.hash.slice(0, 7)}: ${reason}; trying again`);
+			if (!atOnce) this.uploadHolds.set(entry.id, Date.now() + BLOB_RETRY_MS * (1 + Math.random()));
+			return;
+		}
+		const wait = Math.min(BLOB_BACKOFF_MS * 2 ** (failures - BLOB_FAILURES), BLOB_BACKOFF_MAX_MS);
+		this.uploadHolds.set(entry.id, Date.now() + wait);
+		this.log(`${entry.path}: could not upload its content ${entry.hash.slice(0, 7)} ${failures} times in a row: ${reason}; trying again in ${Math.round(wait / 1e3)} s`);
+		this.tellOnce(`upload:${entry.id}`, {
+			kind: "upload-failing",
+			path: entry.path,
+			message: `${entry.path}: the binary file written here could not be uploaded ${failures} times in a row (${reason}); it stays here, its write waits in the outbox and is tried again less and less often, while the writes of other files go ahead`
+		});
+	}
+	/** Put the content of `entry` into blobs/ again from its file, when the file still holds it: false when it does not. */
+	restage(entry) {
+		return this.whenFree(() => this.locked(() => this.queue.some((queued) => queued.id === entry.id) && this.stageHeld(entry.path, entry.hash)));
+	}
+	/**
+	* Take binary file `entry` out of the outbox without sending it, its file left as it is here: a server that keeps no
+	* binary files, or not one this large. The client expects what the entry's base names there again (unqueueBlob), so
+	* the file is a change still to send: the reconcile after it leaves it as it is (binarySkip), and sends it once the
+	* server keeps binary files, as the snapshot of a later connection finds, or once it is small enough. `tell` tells the
+	* writer, once for each content.
+	*/
+	async dropBlob(entry, tell) {
+		await this.unqueueBlob(entry);
+		tell();
+		this.schedule(entry.path);
+	}
+	/**
+	* Take binary file `entry` out of the outbox once its content is nowhere: blobs/ lost it and the file holds another
+	* since. The file's later content supersedes it, as a binary file keeps only its latest version: the reconcile after
+	* it sends the file as it is now, on the entry's base (unqueueBlob). Recorded as information.
+	*/
+	async supersede(entry) {
+		await this.unqueueBlob(entry);
+		this.info(entry.path, `the content ${entry.hash.slice(0, 7)} written here was no longer anywhere to upload, and the file holds another since; the file is sent as it is now`);
+		this.schedule(entry.path);
+	}
+	/**
+	* Take binary file `entry` out of the outbox unsent, as if it had never been queued: what the client expects at its
+	* path goes back to the entry's base, and so do the bases of the writes after it on its content, in one hold of the
+	* write lock.
+	*/
+	async unqueueBlob(entry) {
+		const back = entry.base === null ? null : BLOB_HASH.test(entry.base) ? {
+			hash: entry.base,
+			blob: true
+		} : { hash: entry.base };
+		await this.whenFree(() => this.editQueue((entries) => {
+			const at = entries.findIndex((queued) => queued.id === entry.id);
+			if (at < 0) return false;
+			entries.splice(at, 1);
+			for (const later of entries.slice(at)) {
+				if (later.kind === "op" || later.path !== entry.path || later.sent !== void 0 || later.base !== entry.hash) continue;
+				if (later.kind === "remove" && entry.base === null) continue;
+				later.base = entry.base;
+			}
+			const disk = this.expected.get(entry.path);
+			if (disk?.blob && disk.hash === entry.hash) this.expected.set(entry.path, back);
+		}));
+		this.uploadFailures.delete(entry.id);
+		this.uploadHolds.delete(entry.id);
+	}
+	/**
+	* The server refused binary file `entry` as `missing-blob`: it holds no such content, never given or cleaned up since.
+	* The content is uploaded again and the write sent again as a new request, under a requestId of its own (requestIdOf),
+	* since the server keeps the refusal under the one it was sent with.
+	*/
+	async retryBlob(entry) {
+		this.uploadedBlobs.delete(entry.hash);
+		this.log(`${entry.path}: the sync server holds no content ${entry.hash.slice(0, 7)}; uploading it again`);
+		await this.whenFree(() => this.editQueue((entries) => {
+			const queued = entries.find((e) => e.id === entry.id);
+			if (queued?.kind !== "blob") return false;
+			queued.retry = (queued.retry ?? 0) + 1;
+			delete queued.sent;
+			delete queued.firstSentSeq;
+		}));
 	}
 	/**
 	* Take an answered entry out of the outbox, and give the ids the server renumbered to the files written here and
@@ -3352,15 +4474,16 @@ var SyncClient = class extends EventEmitter {
 	*/
 	async request(entry, request, again, fresh = false) {
 		const firstSentSeq = again ? entry.firstSentSeq : void 0;
+		const requestId = requestIdOf(entry);
 		this.trace(`send ${request.op} ${entry.id}${firstSentSeq === void 0 ? "" : ` again, first sent at seq ${firstSentSeq}`}`);
 		let response;
 		try {
 			response = await this.api.send(firstSentSeq === void 0 ? {
 				...request,
-				requestId: entry.id
+				requestId
 			} : {
 				...request,
-				requestId: entry.id,
+				requestId,
 				firstSentSeq
 			}, { fresh });
 		} catch (error) {
@@ -3398,6 +4521,14 @@ var SyncClient = class extends EventEmitter {
 			},
 			now: requestTime()
 		};
+		if (entry.kind === "blob") return {
+			protocol: 3,
+			op: "file.blob",
+			path: entry.path,
+			hash: entry.hash,
+			size: entry.size,
+			base: entry.base
+		};
 		if (entry.replace) return {
 			protocol: 3,
 			op: "text.replace",
@@ -3414,7 +4545,7 @@ var SyncClient = class extends EventEmitter {
 		await this.refuse(entry, [{
 			kind: "conflict",
 			path: entry.path,
-			text: entry.text,
+			saves: true,
 			message: (saved) => `${entry.path} was edited on top of a write the server did not take as it was, or the edit overlaps what the server merged into it; the text written here was saved to ${saved}`
 		}]);
 	}
@@ -3424,11 +4555,12 @@ var SyncClient = class extends EventEmitter {
 	* the entry: what the writer is told, with the name each text is saved under, and the files that hold what the entry
 	* wrote there as the client left it. Then each text is saved and the writer told. The entry is sent no more; it leaves
 	* the outbox once no file holds what it wrote (releaseHeld), so a restart before the server's version is on disk puts
-	* that version back rather than send the refused text again. An operation's writer is answered with `outcome`.
+	* that version back rather than send the refused text again. An operation's writer is answered with `outcome`. `saves`
+	* says whether the entry wrote something at the path to save, a text or a binary file's content (tell).
 	*/
 	async refuse(entry, told, outcome) {
-		const problems = told.map(({ kind, path, text, message }) => {
-			const saved = text === null ? void 0 : this.conflictName(path);
+		const problems = told.map(({ kind, path, saves, message }) => {
+			const saved = saves ? this.conflictName(path) : void 0;
 			return {
 				kind,
 				path,
@@ -3466,7 +4598,9 @@ var SyncClient = class extends EventEmitter {
 		for (const problem of refusal.told) {
 			if (before(problem)) continue;
 			const text = textAt(entry, problem.path);
-			if (problem.saved !== void 0 && typeof text === "string") await this.saveText(problem.saved, text).catch((error) => this.log(`${problem.path}: could not save ${problem.saved}: ${String(error)}`));
+			const failed = (error) => this.log(`${problem.path}: could not save ${problem.saved}: ${String(error)}`);
+			if (problem.saved !== void 0 && entry.kind === "blob") await this.saveStaged(problem.saved, entry.hash).catch(failed);
+			else if (problem.saved !== void 0 && typeof text === "string") await this.saveText(problem.saved, text).catch(failed);
 			this.problem(problem, entry.id);
 		}
 		if (refusal.outcome) this.settled(entry.id, {
@@ -3478,8 +4612,9 @@ var SyncClient = class extends EventEmitter {
 	}
 	/** Whether `path` holds what `entry` wrote there, as the client left it. */
 	leftHere(entry, path) {
-		const text = wroteAt(entry, path);
 		const disk = this.expected.get(path);
+		if (entry.kind === "blob") return path === entry.path && disk?.blob === true && disk.hash === entry.hash;
+		const text = wroteAt(entry, path);
 		if (text === void 0 || disk === void 0) return false;
 		return text === null ? disk === null : disk !== null && disk.hash === contentHash(text);
 	}
@@ -3526,6 +4661,10 @@ var SyncClient = class extends EventEmitter {
 		try {
 			const response = await this.request(entry, request, again);
 			if (response === null) return false;
+			if (entry.kind === "blob" && !response.ok && response.reason === "missing-blob") {
+				await this.retryBlob(entry);
+				return false;
+			}
 			this.answer(entry);
 			if (entry.kind === "op") await this.settleQueuedOp(entry, response);
 			else if (entry.kind === "remove") await this.settleRemove(entry, response);
@@ -3535,6 +4674,7 @@ var SyncClient = class extends EventEmitter {
 				base: entry.baseText,
 				last: entry.replaced
 			}, request.text);
+			else if (entry.kind === "blob") await this.settleBlob(entry, response);
 			return true;
 		} finally {
 			for (const path of paths) {
@@ -3550,7 +4690,7 @@ var SyncClient = class extends EventEmitter {
 			const told = Object.entries(entry.written).flatMap(([path, text]) => text === null ? [] : [{
 				kind: "refused",
 				path,
-				text,
+				saves: true,
 				message: (saved) => `the server refused ${entry.request.op} (${response.message}); ${path} as it was written here was saved to ${saved} and the file has the server's version again`
 			}]);
 			return this.refuse(entry, told, {
@@ -3580,7 +4720,7 @@ var SyncClient = class extends EventEmitter {
 	* The server gave some of the entry's provisional ids away: rewrite the files written offline, the queued requests
 	* and edits after it, and what the client expects on disk (docs/sync-protocol.md). Called under the write lock with
 	* the outbox as read, so a writer appending meanwhile sees either the old ids everywhere or the new. The outbox is
-	* sent in order, so every entry after it is still to be sent; one sent already (`sent`), as an older sync client left
+	* sent in order for each path, so every entry after it about its files is still to be sent; one sent already (`sent`), as an older sync client left
 	* behind an operation when it sent edits outside the outbox, stays as the server may have taken it, and so do the
 	* files only it wrote; the server's version of them comes back once it is answered. An edit queued on top of it
 	* keeps that text as its base, so its renumbering is what it changes, and it puts the server's id there when it
@@ -3590,7 +4730,7 @@ var SyncClient = class extends EventEmitter {
 	* the sent write wrote it. A refused write is no write to send.
 	*/
 	renumber(entries, entry, renumbered) {
-		const rest = entries.filter((queued) => queued.id !== entry.id && queued.sent === void 0 && waiting(queued));
+		const rest = entries.slice(entries.findIndex((queued) => queued.id === entry.id) + 1).filter((queued) => queued.sent === void 0 && waiting(queued));
 		const offlinePaths = [...entryPaths(entry), ...rest.flatMap(entryPaths)];
 		this.renumberDisk(offlinePaths, renumbered);
 		const files = (record) => Object.fromEntries(Object.entries(record).map(([path, text]) => {
@@ -3649,6 +4789,22 @@ var SyncClient = class extends EventEmitter {
 			lock: (fn) => fn()
 		};
 		const seen = new Map([...new Set(paths)].filter((path) => this.syncs(path)).map((path) => [path, this.expected.get(path)]));
+		const binary = [...seen].filter(([path]) => {
+			try {
+				return contentOf(readFileSync(join(this.paths.data, path))).kind === "binary";
+			} catch {
+				return false;
+			}
+		});
+		for (const [path] of binary) seen.delete(path);
+		for (const [path, disk] of binary) {
+			const to = renumberPath(path, renumbered);
+			if (to === path) continue;
+			mkdirSync(dirname(join(this.paths.data, to)), { recursive: true });
+			renameSync(join(this.paths.data, path), join(this.paths.data, to));
+			this.expected.set(path, null);
+			if (disk !== void 0) this.expected.set(to, disk);
+		}
 		const changes = renumberFiles(storage, seen.keys(), renumbered);
 		const unknown = /* @__PURE__ */ new Set();
 		for (const [path, disk] of seen) {
@@ -3684,30 +4840,204 @@ var SyncClient = class extends EventEmitter {
 		this.reported = this.problems.length;
 		return out;
 	}
-	/** After a tool ran: find every change now, wait for the server, and return what went wrong. */
+	/**
+	* Send every change now, wait for the server, and return what went wrong: `mainflow sync flush`, and a hook of an
+	* older CLI that names no tool. No change waits for an Edit's report (awaitEdit) any longer, nor starts to meanwhile.
+	*/
 	async flush(timeoutMs = 2e4) {
-		await this.scan(true);
-		this.outboxChanged();
-		await this.idle(timeoutMs);
-		return {
-			problems: this.drain(),
-			queued: this.queued,
-			online: this.online
+		this.sendingAll++;
+		try {
+			for (const wait of this.awaitingEdit.values()) wait.end(null);
+			await this.scan(true);
+			this.outboxChanged();
+			await this.idle(timeoutMs);
+			return {
+				problems: this.drain(),
+				queued: this.queued,
+				online: this.online
+			};
+		} finally {
+			this.sendingAll--;
+		}
+	}
+	/**
+	* After a tool other than an Edit ran, as its PostToolUse hook reports it: find every change now, wait for the server,
+	* and return what went wrong. `path`, the file the tool wrote when it names one (Write), is no Edit: its change waiting
+	* for an Edit's report is sent now, and one found meanwhile does not wait. `call`, the tool call when the hook names
+	* it, ends the announcements of its session (settleCaller). A change of any other file waiting for an Edit's report,
+	* which only an announced Edit's change does, as of another session sharing the sync client, goes on waiting for it:
+	* the tool reported here did not write it, or may not have, as a Bash command, and the flush does not wait for it. Its
+	* problems go to the caller after it ends (drain).
+	*/
+	async flushTool(path, timeoutMs = 2e4, call) {
+		this.settleCaller(call);
+		if (path !== void 0) {
+			this.sendingPaths.set(path, (this.sendingPaths.get(path) ?? 0) + 1);
+			this.awaitingEdit.get(path)?.end(null);
+		}
+		try {
+			await this.scan(true, false, false);
+			this.outboxChanged();
+			await this.idle(timeoutMs, true);
+			return {
+				problems: this.drain(),
+				queued: this.queued,
+				online: this.online
+			};
+		} finally {
+			if (path !== void 0) {
+				const left = (this.sendingPaths.get(path) ?? 1) - 1;
+				if (left > 0) this.sendingPaths.set(path, left);
+				else this.sendingPaths.delete(path);
+			}
+		}
+	}
+	/**
+	* Before an Edit runs, as its PreToolUse hook announces it, with the tool call when the hook names it: the change it
+	* makes, its one replacement of the version on disk, may wait for its report (awaitEdit). A change no Edit announced,
+	* as a Bash command's, an editor's, or an Edit's whose hook does not announce it (an older CLI or forwarding script),
+	* is sent at once. Several Edits of one file may be announced at a time, as by sessions sharing the sync client.
+	* Announcements past announceTtlMs go here.
+	*/
+	announceEdit(edit, call) {
+		const now = Date.now();
+		for (const [path, list] of this.announced) {
+			const live = list.filter((a) => a.expires > now);
+			if (live.length) this.announced.set(path, live);
+			else this.announced.delete(path);
+		}
+		if (this.closing || !this.syncs(edit.path) || edit.old === "") return;
+		const announcement = {
+			edit: {
+				path: edit.path,
+				old: edit.old,
+				new: edit.new
+			},
+			...call ? { call } : {},
+			left: this.opts.editReportMs ?? 3e3,
+			expires: now + (this.opts.announceTtlMs ?? 6e5)
 		};
+		this.announced.set(edit.path, [...this.announced.get(edit.path) ?? [], announcement]);
+		this.trace(`announce edit ${edit.path}`);
+	}
+	/** The announcement of `path`, live and with time left to wait, of an Edit that makes `to` of `from`. */
+	announcementFor(path, from, to) {
+		const now = Date.now();
+		return this.announced.get(path)?.find((a) => a.expires > now && a.left > 0 && replaces(a.edit, from, to));
+	}
+	dropAnnouncement(path, announcement) {
+		const list = this.announced.get(path)?.filter((a) => a !== announcement) ?? [];
+		if (list.length) this.announced.set(path, list);
+		else this.announced.delete(path);
+	}
+	/**
+	* A tool call of `call`'s session, or of the same subagent in it, was reported: the Edits that session announced
+	* before have run, and were reported, or never will, as one refused or failed, which runs no PostToolUse hook. A
+	* session runs one such tool at a time, so their announcements are dropped, and a change waiting on one is sent now,
+	* before the flush of this report waits for what it finds: a Bash command that made the change a refused Edit
+	* announced hears of it at its own hook. Another session's announcements, or the session's subagents', stay.
+	*/
+	settleCaller(call) {
+		if (call === void 0) return;
+		const dropped = /* @__PURE__ */ new Set();
+		for (const [path, list] of this.announced) for (const announcement of list.filter((a) => sameCaller(a.call, call))) {
+			dropped.add(announcement);
+			this.dropAnnouncement(path, announcement);
+		}
+		for (const wait of this.awaitingEdit.values()) if (dropped.has(wait.announcement)) wait.end(null);
+		if (dropped.size) this.trace(`dropped ${dropped.size} announcement(s) of ${call.session}${call.agent ? `/${call.agent}` : ""}`);
 	}
 	/**
 	* After an Edit: replay the replacement on the server's latest version, so an Edit made while a broadcast was on
-	* its way is not mistaken for a rewrite of the older file. Anything else is flushed as usual.
+	* its way is not mistaken for a rewrite of the older file, nor one of lines added a moment ago for a write of the
+	* version before them. The report takes the Edit's announcement: the one of its tool call when the hook names it,
+	* else the oldest of the same replacement. The rest of the session's announcements go (settleCaller). The change the
+	* Edit made, waiting for this report (awaitEdit), is replayed where it waits. One not waiting yet, as when the
+	* watcher's reconcile is still on its way to awaitEdit, takes the report from reportedEdits when it gets there, ahead
+	* of the replay queued here on the path's chain; the report is dropped once that replay ran. Then the files are
+	* flushed as for any tool that wrote this one.
 	*/
-	async flushEdit(edit, timeoutMs = 2e4) {
+	async flushEdit(edit, timeoutMs = 2e4, call) {
 		const { path } = edit;
-		if (this.caughtUp && this.syncs(path) && edit.old !== "") await this.withChain(path, () => this.replayEdit(edit));
-		return this.flush(timeoutMs);
+		const list = this.announced.get(path);
+		const announcement = call?.toolUseId !== void 0 ? list?.find((a) => sameCaller(a.call, call) && a.call?.toolUseId === call.toolUseId) : list?.find((a) => a.edit.old === edit.old && a.edit.new === edit.new);
+		if (announcement) this.dropAnnouncement(path, announcement);
+		const replays = this.caughtUp && this.syncs(path) && edit.old !== "";
+		const waiting = replays ? this.awaitingEdit.get(path) : void 0;
+		const handed = waiting !== void 0 && replaces(edit, waiting.from, waiting.to);
+		if (handed) waiting.end(edit);
+		this.settleCaller(call);
+		if (replays && !handed) {
+			this.reportedEdits.set(path, edit);
+			await this.withChain(path, () => this.replayEdit(edit));
+			if (this.reportedEdits.get(path) === edit) this.reportedEdits.delete(path);
+		}
+		return this.flushTool(path, timeoutMs, call);
+	}
+	/**
+	* The Edit reported for the local `text` of `path`, which the client left holding `disk`, or null. An Edit starts
+	* from the version on disk, and the watcher sees its write before the PostToolUse hook reports it. Layer 1 bases a
+	* change on the recent version nearest to it, which for an Edit that removes or rewrites lines added a moment ago is
+	* the version before them, as for a program that read that version and wrote it back: the lines would be kept, or
+	* the change refused as overlapping them.
+	* So a change that is exactly the replacement of an Edit announced before it ran (announceEdit), when layer 1 would
+	* base it on another version than the one on disk, waits for the report: the Edit's (flushEdit) is replayed in its
+	* place; a report of the tool that wrote this file (flushTool), flush(), the announcement's time running out or stop()
+	* sends it as layer 1 bases it, as does a later report of the session that announced it (settleCaller). The waits on
+	* one announcement add up to editReportMs at most: once used up, it is dropped. Any other change does not wait: no
+	* Edit named it before it ran, so no report is due for it.
+	* A report that came first (reportedEdits) is taken at once when the Edit it names made this text; while there is one,
+	* no change of the path starts to wait, as its report came already.
+	* Nor does a change wait unless it may be an Edit's replay: the client caught up, as flushEdit replays only then, and
+	* no write about the file waiting for the server (pending). An answer to one changes the versions layer 1 chooses
+	* from, so a change that waited past it would be based on another version than the one it was read against. Nor does
+	* a change found while every change is being sent (flush), or one of a file a tool reported as written meanwhile.
+	*/
+	async awaitEdit(path, text, disk) {
+		if (disk.text === void 0 || this.closing) return null;
+		const from = disk.text;
+		const reported = this.reportedEdits.get(path);
+		if (reported) {
+			if (!replaces(reported, from, text)) return null;
+			this.reportedEdits.delete(path);
+			this.trace(`await edit ${path} ${short(text)} reported before it waited`);
+			return reported;
+		}
+		const announcement = this.announcementFor(path, from, text);
+		if (!announcement || !this.caughtUp || this.pending(path) || this.sendingAll > 0 || this.sendingPaths.has(path)) return null;
+		const start = this.startOf(path, text, disk);
+		if (start === void 0 || start.text === from) return null;
+		this.trace(`await edit ${path} ${short(text)} on disk ${short(from)} nearest ${short(start.text)} up to ${announcement.left} ms`);
+		const started = Date.now();
+		let timedOut = false;
+		const edit = await new Promise((resolve) => {
+			const wait = {
+				from,
+				to: text,
+				announcement,
+				end: (edit) => {
+					clearTimeout(timer);
+					if (this.awaitingEdit.get(path) === wait) this.awaitingEdit.delete(path);
+					resolve(edit);
+				}
+			};
+			const timer = setTimeout(() => {
+				timedOut = true;
+				wait.end(null);
+			}, announcement.left);
+			this.awaitingEdit.get(path)?.end(null);
+			this.awaitingEdit.set(path, wait);
+		});
+		announcement.left -= Date.now() - started;
+		if (timedOut || announcement.left <= 0) this.dropAnnouncement(path, announcement);
+		this.trace(`await edit ${path} ${short(text)} ${edit ? "reported as an Edit" : "over"}`);
+		return edit;
 	}
 	/**
 	* Queue an Edit as its replacement, which the server makes again on its latest version, based as layer 1 knows the
-	* version the Edit changed, the one on disk. One the watcher queued as a whole text already, or that is not the plain
-	* replacement of the version on disk, is left to the flush. The Edit's result is adopted in the hold of the write lock
+	* version the Edit changed, the one on disk. The replacement sent is the text the Edit replaced there (editTarget),
+	* with the line break after a deleted line when the Edit took it. One the watcher queued as a whole text already, or
+	* that is not that replacement of the version on disk, is left to the flush. The Edit's result is adopted in the hold of the write lock
 	* that queues it (I2); one changed there since it was read, as by an operation written on it, which then has the Edit
 	* queued ahead of it as a direct edit, is reconciled again.
 	*/
@@ -3715,7 +5045,11 @@ var SyncClient = class extends EventEmitter {
 		const disk = this.expected.get(path);
 		const local = await this.readLocal(path);
 		if (local.kind !== "text" || disk?.text === void 0 || contentHash(local.text) === disk.hash) return;
-		if (disk.text.split(old).length !== 2 || disk.text.replace(old, () => replacement) !== local.text) return;
+		const target = editTarget(disk.text, {
+			old,
+			new: replacement
+		});
+		if (target === null || disk.text.replace(target, () => replacement) !== local.text) return;
 		const edited = local.text;
 		const { hash, text } = disk;
 		const id = await this.enqueue((entries) => {
@@ -3731,7 +5065,7 @@ var SyncClient = class extends EventEmitter {
 			return {
 				...editOn(path, edited, start, hash),
 				replace: {
-					old,
+					old: target,
 					new: replacement
 				}
 			};
@@ -3759,7 +5093,7 @@ var SyncClient = class extends EventEmitter {
 		await this.refuse(entry, [{
 			kind: "edit-rejected",
 			path,
-			text: writer,
+			saves: true,
 			message: (saved) => `${path}: the Edit could not be replayed on the latest version (${response.message}); the edited text was saved to ${saved} and the file now has the latest version. Read it and edit again`
 		}]);
 		if ("files" in response && response.files.some((f) => f.path === path)) await this.delivery(path, response.seq);
@@ -3826,9 +5160,10 @@ var SyncClient = class extends EventEmitter {
 	/**
 	* Compare every synced file's size, modification time and inode with the last scan and reconcile what changed,
 	* plus every file expected on disk that is gone. A file modified in the last moment may still be being written,
-	* so it waits for the next scan unless `immediate`. `baseline` only records what is there.
+	* so it waits for the next scan unless `immediate`. `baseline` only records what is there. An immediate scan waits for
+	* the reconciles it started unless `settle` is false, for a caller that waits for them itself (flushTool).
 	*/
-	async scan(immediate, baseline = false) {
+	async scan(immediate, baseline = false, settle = immediate) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const path of await this.walk()) {
 			seen.add(path);
@@ -3845,7 +5180,7 @@ var SyncClient = class extends EventEmitter {
 			this.signatures.delete(path);
 			this.schedule(path);
 		}
-		if (immediate) await Promise.allSettled(this.chains.values());
+		if (settle) await Promise.allSettled(this.chains.values());
 	}
 	/**
 	* Watch the directories that may hold synced files, and local/sync/ for the outbox. The client's own files in the
@@ -3930,7 +5265,7 @@ var SyncClient = class extends EventEmitter {
 		const name = `${path.split("/").join("__")}.${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.${Math.random().toString(36).slice(2, 6)}`;
 		return relative(this.paths.data, join(this.paths.conflicts, name)).split(sep).join("/");
 	}
-	/** Save `text` as `saved`, relative to .mainflow/; a text saved there already is kept. */
+	/** Save `text`, or a binary file's bytes, as `saved`, relative to .mainflow/; a text saved there already is kept. */
 	async saveText(saved, text) {
 		await mkdir(this.paths.conflicts, { recursive: true });
 		await writeFile(join(this.paths.data, saved), text, { flag: "wx" }).catch((error) => {
@@ -3942,16 +5277,30 @@ var SyncClient = class extends EventEmitter {
 		await this.saveText(saved, text);
 		return saved;
 	}
+	/** Save the content of sha256 `hash` that blobs/ keeps as `saved`, relative to .mainflow/; one saved there already is kept. */
+	async saveStaged(saved, hash) {
+		await mkdir(this.paths.conflicts, { recursive: true });
+		try {
+			copyFileSync(join(this.paths.blobs, hash), join(this.paths.data, saved), COPYFILE_EXCL);
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+	}
 	saveKnown() {
 		if (this.knownTimer) return;
 		this.knownTimer = setTimeout(() => this.saveKnownNow(), 200);
 	}
+	/** What known.json names: each confirmed version, a binary file's sha256 with BLOB_PREFIX. */
+	knownFiles() {
+		const files = {};
+		for (const [path, disk] of this.confirmed) if (disk) files[path] = disk.blob ? { hash: `${BLOB_PREFIX}${disk.hash}` } : disk;
+		return files;
+	}
 	saveKnownNow(final = false) {
 		if (this.abandoned && !final) return;
 		clearTimeout(this.knownTimer);
 		this.knownTimer = void 0;
-		const files = {};
-		for (const [path, disk] of this.confirmed) if (disk) files[path] = disk;
+		const files = this.knownFiles();
 		try {
 			underLock(this.root, () => writeKnown(this.root, files));
 		} catch (error) {
@@ -4049,6 +5398,26 @@ function forgetDaemon(root, gone) {
 	rmSync(syncPaths(root).daemon, { force: true });
 	return true;
 }
+/** The Edit a request's body names, its file and its one replacement, or null. */
+function editIn(body) {
+	const edit = body.edit;
+	if (typeof edit?.path !== "string" || typeof edit.old !== "string" || typeof edit.new !== "string") return null;
+	return {
+		path: edit.path,
+		old: edit.old,
+		new: edit.new
+	};
+}
+/** The tool call a request's body names, its session at least, or undefined. */
+function callIn(body) {
+	const call = body.call;
+	if (typeof call?.session !== "string" || call.session === "") return void 0;
+	return {
+		session: call.session,
+		...typeof call.agent === "string" ? { agent: call.agent } : {},
+		...typeof call.toolUseId === "string" ? { toolUseId: call.toolUseId } : {}
+	};
+}
 /** Serve `client` to this machine's mainflow commands until closed. */
 async function serveIpc(root, client) {
 	const secret = randomBytes(16).toString("hex");
@@ -4070,8 +5439,14 @@ async function serveIpc(root, client) {
 				return client.outboxChanged();
 			}
 			if (req.url === "/flush") {
-				const edit = body.edit;
-				return reply(200, edit ? await client.flushEdit(edit) : await client.flush());
+				const edit = editIn(body);
+				const call = callIn(body);
+				return reply(200, edit ? await client.flushEdit(edit, void 0, call) : body.tool === true ? await client.flushTool(typeof body.path === "string" ? body.path : void 0, void 0, call) : await client.flush());
+			}
+			if (req.url === "/announce") {
+				const edit = editIn(body);
+				if (edit) client.announceEdit(edit, callIn(body));
+				return reply(200, {});
 			}
 			if (req.url === "/status") return reply(200, {
 				online: client.online,
@@ -4142,6 +5517,18 @@ async function startDaemon(options) {
 }
 //#endregion
 //#region ../sync/dist/hook.js
+/**
+* The tool call `payload` is of, as the sync client tells sessions apart: the session, the subagent in it for a
+* subagent's call (agent_id), and the call's id (tool_use_id), which both hooks of one call name. None without a session.
+*/
+function toolCallOf(payload) {
+	if (typeof payload.session_id !== "string" || payload.session_id === "") return void 0;
+	return {
+		session: payload.session_id,
+		...typeof payload.agent_id === "string" && payload.agent_id !== "" ? { agent: payload.agent_id } : {},
+		...typeof payload.tool_use_id === "string" && payload.tool_use_id !== "" ? { toolUseId: payload.tool_use_id } : {}
+	};
+}
 /** Tools that write the one file named in file_path. */
 const FILE_TOOLS = /* @__PURE__ */ new Set([
 	"Edit",
@@ -4166,26 +5553,37 @@ function hubPath(root, payload) {
 	return path;
 }
 /**
+* The one replacement an Edit of `path` makes, as both its hooks name it, the PreToolUse one announcing it and the
+* PostToolUse one reporting it; null for an Edit of every occurrence, which the sync client does not replay.
+*/
+function editOf(path, payload) {
+	const input = payload.tool_input ?? {};
+	if (payload.tool_name !== "Edit" || input.replace_all === true || typeof input.old_string !== "string" || typeof input.new_string !== "string") return null;
+	return {
+		path,
+		old: input.old_string,
+		new: input.new_string
+	};
+}
+/**
 * What to flush after the tool in `payload` ran in the hub at `root`. A file tool outside the hub's synced files
-* needs nothing; an Edit of one replacement is replayed on the latest version; anything else, such as a Bash
-* command that may have written any file, rescans every file.
+* needs nothing; an Edit of one replacement is replayed on the latest version; another file tool names the file it
+* wrote; anything else, such as a Bash command that may have written any file, rescans every file and names none.
 */
 function planFlush(root, payload) {
 	const tool = payload.tool_name ?? "";
 	if (!FILE_TOOLS.has(tool)) return { skip: false };
-	const input = payload.tool_input ?? {};
-	if (typeof input.file_path !== "string") return { skip: false };
+	if (typeof (payload.tool_input ?? {}).file_path !== "string") return { skip: false };
 	const path = hubPath(root, payload);
 	if (path === null || !isSynced(path)) return { skip: true };
-	if (tool === "Edit" && input.replace_all !== true && typeof input.old_string === "string" && typeof input.new_string === "string") return {
+	const edit = editOf(path, payload);
+	return edit ? {
 		skip: false,
-		edit: {
-			path,
-			old: input.old_string,
-			new: input.new_string
-		}
+		edit
+	} : {
+		skip: false,
+		path
 	};
-	return { skip: false };
 }
 /** The PostToolUse answer: block with the problems as the reason, or nothing when the change went through as written. */
 function hookAnswer(result) {
@@ -4214,6 +5612,17 @@ function planFetch(root, payload) {
 		write: tool !== "Read"
 	};
 }
+/**
+* The Edit to announce to the sync client before it runs in the hub at `root`: one replacement of a synced file, whose
+* change then waits for the Edit's PostToolUse report (docs/sync.md "等 Edit 的回報"). Null for anything else, which
+* announces nothing: a change no Edit announced is sent at once.
+*/
+function planAnnounce(root, payload) {
+	const path = hubPath(root, payload);
+	if (path === null || !isSynced(path)) return null;
+	const edit = editOf(path, payload);
+	return edit && edit.old !== "" ? edit : null;
+}
 /** The PreToolUse answer that stops the tool, with `reason` for the agent. */
 const fetchDenial = (reason) => JSON.stringify({ hookSpecificOutput: {
 	hookEventName: "PreToolUse",
@@ -4493,4 +5902,4 @@ function hubWriter(root, env = process.env, options = {}) {
 	};
 }
 //#endregion
-export { hubName as C, isSynced as D, SYNC_DIR as E, syncPaths as O, earlierToken as S, SETTINGS_FILE as T, readRemote as _, remoteMode as a, ServerError as b, planFetch as c, DaemonRunning as d, DaemonUnavailable as f, silentHint as g, readDaemon as h, queuedCount as i, planFlush as l, probeDaemon as m, hubWriter as n, fetchDenial as o, callDaemon as p, writtenLines as r, hookAnswer as s, CONFIRM_MS as t, startDaemon as u, oversizedFiles as v, syncSettings as w, ENV as x, ServerApi as y };
+export { syncPaths as A, ENV as C, SETTINGS_FILE as D, syncSettings as E, SYNC_DIR as O, ServerError as S, hubName as T, readDaemon as _, remoteMode as a, oversizedFiles as b, planAnnounce as c, toolCallOf as d, startDaemon as f, probeDaemon as g, callDaemon as h, queuedCount as i, isSynced as k, planFetch as l, DaemonUnavailable as m, hubWriter as n, fetchDenial as o, DaemonRunning as p, writtenLines as r, hookAnswer as s, CONFIRM_MS as t, planFlush as u, silentHint as v, earlierToken as w, ServerApi as x, readRemote as y };