@stll/folio-cli 0.1.1 → 0.2.0

package/dist/execute-write.js

@@ -1,24 +1,27 @@
-import { checkExpectedVersion, errnoCode, openReviewer, readDocumentFile, sameFile } from "./document.js";
+import { checkExpectedVersion, openReviewer, readDocumentFile } from "./document.js";
+import { acquireLeaseForWrite } from "./editor-lease.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
-import { findCommit, journalPathFor, recoverStages } from "./journal.js";
-import { acquireLease } from "./lock.js";
+import { blockIdSources } from "./execute-read.js";
+import { errnoCode, fileVersionOf, sameFile } from "./file-system.js";
+import { findCommit, journalPathFor, latestCommitFor, recoverStages } from "./journal.js";
 import { diffPackages, nextRevisionIdSeed } from "./package-parts.js";
-import { SIDECAR_DIRECTORY, unsafePath } from "./sidecar.js";
+import { SIDECAR_DIRECTORY, inspectPath, readSidecarFile, unsafePath } from "./sidecar.js";
 import { commitTransaction } from "./transaction.js";
 import { Result, panic } from "better-result";
 import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
 import { generateRedlineDocx } from "@stll/folio-agents/compare";
 import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
 import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
-import { createHash, randomUUID } from "node:crypto";
 import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/execute-write.ts
 /**
-* Run one mutating tool call as a transaction: take the destination's lease,
-* settle any crashed stage, replay a committed `txId`, apply the change to a
-* fresh reviewer, save it (selective unless a full repack is allowed), and
-* commit the bytes atomically with a journal line and, in place, a backup.
+* Run one mutating tool call as a transaction: take the destination's lease
+* (asking an editor that holds it to save and release first), settle any
+* crashed stage, replay a committed `txId`, apply the change to a fresh
+* reviewer, save it (selective unless a full repack is allowed), and commit
+* the bytes atomically with a journal line and, in place, a backup.
 */
 const TX_ID_PATTERN = /^[\w.-]{1,128}$/u;
 const invalidInput = (message, hint) => cliError({
@@ -224,6 +227,73 @@ const mutate = (options) => {
 		}
 	}
 };
+/** The `tool` an editor's whole-package save journals (`save.ts`). */
+const EDITOR_SAVE_TOOL = "editor_save";
+const BLOCK_ID_KEY = /blockId$/iu;
+/** Every block id an operation targets: any `...blockId` string, at any depth. */
+const targetedBlockIds = (value, found = /* @__PURE__ */ new Set()) => {
+	if (Array.isArray(value)) for (const item of value) targetedBlockIds(item, found);
+	else if (isRecord(value)) for (const [key, entry] of Object.entries(value)) if (BLOCK_ID_KEY.test(key) && typeof entry === "string") found.add(entry);
+	else targetedBlockIds(entry, found);
+	return found;
+};
+/** The ids of the blocks whose id is the package's own `w14:paraId`. */
+const durableBlockIds = async (file) => {
+	const reviewer = await openReviewer(file);
+	if (reviewer.isErr()) return null;
+	const durable = /* @__PURE__ */ new Set();
+	for (const [id, source] of blockIdSources(reviewer.value)) if (source === "package") durable.add(id);
+	return durable;
+};
+/**
+* The version the caller read, from the backup the editor's save made of
+* it; `null` when it is gone or no longer holds that version.
+*/
+const readFlushedFrom = async (documentPath, version) => {
+	const backupPath = path.join(path.dirname(documentPath), SIDECAR_DIRECTORY, "backups", path.basename(documentPath), `${version}.docx`);
+	const entry = await inspectPath(backupPath);
+	if (entry.isErr() || entry.value.type !== "file") return null;
+	const bytes = await readSidecarFile(backupPath);
+	if (bytes.isErr() || fileVersionOf(bytes.value) !== version) return null;
+	return {
+		path: backupPath,
+		bytes: bytes.value,
+		fileVersion: version,
+		identity: entry.value.identity,
+		links: entry.value.links
+	};
+};
+/**
+* Whether a write whose `fileVersion` went stale only because the editor
+* holding the lease saved when asked may run on the saved version. It may
+* when it is an in-place agent tool, the version it read was current when
+* the flush was requested, the journal's newest commit is the editor's save
+* from exactly that version to the file as it is now, and every block the
+* call targets is named by a durable `w14:paraId` both in the version it
+* read and in the saved one. A text- or position-derived id could name
+* another paragraph once the user's edits moved things, so such a call, or
+* one that targets no block, stays `stale_version` and the caller re-reads.
+* Text-hash preconditions are then re-checked against the saved version.
+*/
+const rebasedOntoFlush = async ({ tool, flush, inPlace, source, args, expected }) => {
+	if (flush.type !== "flushed" || tool.type !== "agentWrite" || !inPlace) return null;
+	if (expected === void 0 || expected !== flush.versionBefore) return null;
+	const latest = await latestCommitFor(source.path);
+	if (latest === null || latest.tool !== "editor_save" || latest.fromVersion !== expected || latest.toVersion !== source.fileVersion) return null;
+	const targets = targetedBlockIds(args);
+	if (targets.size === 0) return null;
+	const read = await readFlushedFrom(source.path, expected);
+	if (read === null) return null;
+	for (const file of [read, source]) {
+		const durable = await durableBlockIds(file);
+		if (durable === null || [...targets].some((id) => !durable.has(id))) return null;
+	}
+	return {
+		fromVersion: expected,
+		toVersion: source.fileVersion,
+		flushedBy: flush.holder.owner
+	};
+};
 const DOCX_NAME = /\.docx$/iu;
 const invalidDestination = (message, hint) => cliError({
 	code: FOLIO_CLI_ERROR_CODES.invalidDestination,
@@ -296,11 +366,11 @@ const identityOfInput = async (inputPath) => {
 * that is the input under another name (a symlink, a hard link, a
 * case-insensitive alias): files are compared by device and inode.
 */
-const resolveTarget = async (tool, call, destination) => {
-	const source = await identityOfInput(call.path);
+const resolveTarget = async ({ sourcePath, destination, redline }) => {
+	const source = await identityOfInput(sourcePath);
 	if (source.isErr()) return Result.err(source.error);
 	if (destination.type === "inPlace") {
-		if (tool.type === "compare") return Result.err(cliError({
+		if (redline !== void 0) return Result.err(cliError({
 			code: FOLIO_CLI_ERROR_CODES.usage,
 			message: "A redline is written to a new file, never in place.",
 			hint: "Pass -o <redline.docx>."
@@ -316,14 +386,13 @@ const resolveTarget = async (tool, call, destination) => {
 	const target = await resolveWritePath(destination.path);
 	if (target.isErr()) return Result.err(target.error);
 	const inputs = [source.value];
-	const revisedPath = call.args["revisedPath"];
-	if (tool.type === "compare" && typeof revisedPath === "string") {
-		const revised = await identityOfInput(revisedPath);
+	if (redline !== void 0 && typeof redline.revisedPath === "string") {
+		const revised = await identityOfInput(redline.revisedPath);
 		if (revised.isErr()) return Result.err(revised.error);
 		inputs.push(revised.value);
 	}
 	const clash = inputs.find(({ path: inputPath, identity }) => inputPath === target.value.path || target.value.identity !== null && sameFile(identity, target.value.identity));
-	if (clash !== void 0) return Result.err(invalidDestination(`The destination is the input ${clash.path}.`, tool.type === "compare" ? "Write the redline to a new file." : "Use --in-place to change the file itself; it keeps a backup."));
+	if (clash !== void 0) return Result.err(invalidDestination(`The destination is the input ${clash.path}.`, redline !== void 0 ? "Write the redline to a new file." : "Use --in-place to change the file itself; it keeps a backup."));
 	return Result.ok({
 		sourcePath: source.value.path,
 		sourceIdentity: source.value.identity,
@@ -335,16 +404,23 @@ const executeWriteTool = async (tool, call, options) => {
 	if (options.txId !== void 0 && !TX_ID_PATTERN.test(options.txId)) return Result.err(invalidInput("txId must be 1 to 128 letters, digits, '.', '_' or '-'."));
 	if (options.sourcePrecondition === "required" && call.fileVersion === void 0) return Result.err(invalidInput("A change needs the fileVersion of the file it was read from.", "Pass --expect-version <fileVersion> from your read (MCP: fileVersion), or --no-expect-version to skip the check."));
 	const txId = options.txId ?? randomUUID();
-	const target = await resolveTarget(tool, call, options.destination);
+	const target = await resolveTarget({
+		sourcePath: call.path,
+		destination: options.destination,
+		...tool.type === "compare" && { redline: { revisedPath: call.args["revisedPath"] } }
+	});
 	if (target.isErr()) return Result.err(target.error);
 	const { sourcePath, sourceIdentity, destinationPath } = target.value;
 	const journalPath = journalPathFor(destinationPath, options.journalPath);
-	const lease = await acquireLease({
+	const inPlace = destinationPath === sourcePath;
+	const acquired = await acquireLeaseForWrite({
 		documentPath: destinationPath,
 		txId,
-		force: options.force
+		force: options.force,
+		...options.flushWaitMs !== void 0 && { flushWaitMs: options.flushWaitMs }
 	});
-	if (lease.isErr()) return Result.err(lease.error);
+	if (acquired.isErr()) return Result.err(acquired.error);
+	const { lease, flush } = acquired.value;
 	try {
 		const recovered = await recoverStages({
 			documentPath: destinationPath,
@@ -375,11 +451,19 @@ const executeWriteTool = async (tool, call, options) => {
 		}
 		const source = await readDocumentFile(sourcePath);
 		if (source.isErr()) return Result.err(source.error);
-		const expectedIdentity = destinationPath === sourcePath && recovered.value.some(({ action }) => action === "rolledForward") ? source.value.identity : sourceIdentity;
+		const expectedIdentity = inPlace && (flush.type !== "notAsked" || recovered.value.some(({ action }) => action === "rolledForward")) ? source.value.identity : sourceIdentity;
 		if (!sameFile(source.value.identity, expectedIdentity)) return Result.err(unsafePath(`${sourcePath} was replaced while the write started.`));
-		if (destinationPath === sourcePath && source.value.links > 1) return Result.err(unsafePath(`${sourcePath} has other hard links; an in-place write would detach them.`, "Write to a new file with -o instead."));
+		if (inPlace && source.value.links > 1) return Result.err(unsafePath(`${sourcePath} has other hard links; an in-place write would detach them.`, "Write to a new file with -o instead."));
 		const version = checkExpectedVersion(source.value, call.fileVersion);
-		if (version.isErr()) return Result.err(recovered.value.length === 0 ? version.error : cliError({
+		const rebased = version.isErr() ? await rebasedOntoFlush({
+			tool,
+			flush,
+			inPlace,
+			source: source.value,
+			args: call.args,
+			expected: call.fileVersion
+		}) : null;
+		if (version.isErr() && rebased === null) return Result.err(recovered.value.length === 0 ? version.error : cliError({
 			code: version.error.code,
 			message: version.error.message,
 			hint: version.error.hint,
@@ -415,6 +499,7 @@ const executeWriteTool = async (tool, call, options) => {
 			...repackReason !== void 0 && { repackReason },
 			changedParts: changedParts.value,
 			...recovered.value.length > 0 && { recovered: recovered.value },
+			...rebased !== null && { rebased },
 			result
 		};
 		const committed = await commitTransaction({
@@ -425,7 +510,7 @@ const executeWriteTool = async (tool, call, options) => {
 			sourceIdentity: expectedIdentity,
 			fromVersion: source.value.fileVersion,
 			bytes,
-			verifyLease: lease.value.verify,
+			verifyLease: lease.verify,
 			changedParts: changedParts.value,
 			journalPath,
 			entry: {
@@ -442,8 +527,8 @@ const executeWriteTool = async (tool, call, options) => {
 		});
 		return committed.isErr() ? Result.err(committed.error) : Result.ok(committed.value.receipt);
 	} finally {
-		await lease.value.release();
+		await lease.release();
 	}
 };
 //#endregion
-export { executeWriteTool };
+export { EDITOR_SAVE_TOOL, TX_ID_PATTERN, canonicalJson, executeWriteTool, resolveTarget };

package/dist/file-system.d.ts

@@ -0,0 +1,23 @@
+//#region src/file-system.d.ts
+/**
+ * File-system primitives shared by the document reader and the sidecar
+ * files. Kept free of the document model so `editor-lease.ts` (which an
+ * editor host bundles) does not pull in the parser.
+ */
+/** A file's version: the lowercase hex SHA-256 of its bytes. */
+declare const fileVersionOf: (bytes: Uint8Array) => string;
+/** Which file a path named when it was read: device and inode. */
+type FileIdentity = {
+  dev: number;
+  ino: number;
+};
+declare const sameFile: (left: FileIdentity, right: FileIdentity) => boolean;
+/**
+ * `O_NOFOLLOW` where the platform has it: opening a path whose last
+ * component is a symlink fails instead of following it.
+ */
+declare const NO_FOLLOW: number;
+/** The `code` of a Node.js file-system error, when there is one. */
+declare const errnoCode: (error: unknown) => string | undefined;
+//#endregion
+export { FileIdentity, NO_FOLLOW, errnoCode, fileVersionOf, sameFile };

package/dist/file-system.js

@@ -0,0 +1,23 @@
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/file-system.ts
+/**
+* File-system primitives shared by the document reader and the sidecar
+* files. Kept free of the document model so `editor-lease.ts` (which an
+* editor host bundles) does not pull in the parser.
+*/
+/** A file's version: the lowercase hex SHA-256 of its bytes. */
+const fileVersionOf = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const sameFile = (left, right) => left.dev === right.dev && left.ino === right.ino;
+/**
+* `O_NOFOLLOW` where the platform has it: opening a path whose last
+* component is a symlink fails instead of following it.
+*/
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+/** The `code` of a Node.js file-system error, when there is one. */
+const errnoCode = (error) => {
+	if (typeof error !== "object" || error === null || !("code" in error)) return;
+	return typeof error.code === "string" ? error.code : void 0;
+};
+//#endregion
+export { NO_FOLLOW, errnoCode, fileVersionOf, sameFile };

package/dist/journal.d.ts

@@ -56,6 +56,22 @@ declare const appendJournal: (journalPath: string, entry: JournalEntry) => Promi
  * A journal (or `.folio`) that is a symlink or hard link is refused.
  */
 declare const findCommit: (journalPath: string, txId: string) => Promise<Result<CommittedTransaction | undefined, FolioCliError>>;
+/** The newest commit the journal records for one document. */
+type LatestCommit = {
+  txId: string;
+  tool: string;
+  author: string;
+  time: string;
+  fromVersion: string;
+  toVersion: string;
+};
+/**
+ * The newest commit to `documentPath` in its journal (default
+ * `.folio/journal.jsonl` beside it) that recovery did not discard, or
+ * `null`. Reads only through a plain `.folio` directory and never creates
+ * one, so a read-only preview can call it.
+ */
+declare const latestCommitFor: (documentPath: string, journalPath?: string) => Promise<LatestCommit | null>;
 declare const stagePrefixFor: (documentPath: string) => string;
 declare const stagePathFor: (documentPath: string, txId: string) => string;
 type RecoveryAction = {
@@ -79,4 +95,4 @@ type RecoverStagesOptions = {
  */
 declare const recoverStages: ({ documentPath, journalPath, now }: RecoverStagesOptions) => Promise<Result<RecoveryAction[], FolioCliError>>;
 //#endregion
-export { CommittedTransaction, JournalCommit, JournalEntry, JournalRecovery, RECOVERY_DISCARD_REASONS, RecoveryAction, RecoveryDiscardReason, appendJournal, findCommit, journalPathFor, recoverStages, stagePathFor, stagePrefixFor };
+export { CommittedTransaction, JournalCommit, JournalEntry, JournalRecovery, LatestCommit, RECOVERY_DISCARD_REASONS, RecoveryAction, RecoveryDiscardReason, appendJournal, findCommit, journalPathFor, latestCommitFor, recoverStages, stagePathFor, stagePrefixFor };

package/dist/journal.js

@@ -1,5 +1,5 @@
-import { errnoCode, fileVersionOf, sameFile } from "./document.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { errnoCode, fileVersionOf, sameFile } from "./file-system.js";
 import { checkPackageIntegrity } from "./package-parts.js";
 import { SIDECAR_DIRECTORY, ensureSidecarParent, inspectPath, openSidecarFile, readSidecarFile, syncDirectory } from "./sidecar.js";
 import { Result } from "better-result";
@@ -98,6 +98,41 @@ const findCommit = async (journalPath, txId) => {
 	}
 	return Result.ok(found);
 };
+const parseLatest = (value) => {
+	const { txId, tool, author, time, fromVersion, toVersion } = value;
+	return typeof txId === "string" && typeof tool === "string" && typeof author === "string" && typeof time === "string" && typeof fromVersion === "string" && typeof toVersion === "string" ? {
+		txId,
+		tool,
+		author,
+		time,
+		fromVersion,
+		toVersion
+	} : null;
+};
+/**
+* The newest commit to `documentPath` in its journal (default
+* `.folio/journal.jsonl` beside it) that recovery did not discard, or
+* `null`. Reads only through a plain `.folio` directory and never creates
+* one, so a read-only preview can call it.
+*/
+const latestCommitFor = async (documentPath, journalPath) => {
+	const journal = journalPathFor(documentPath, journalPath);
+	const parent = await inspectPath(path.dirname(journal));
+	if (parent.isErr() || parent.value.type !== "directory") return null;
+	const bytes = await readSidecarFile(journal);
+	if (bytes.isErr()) return null;
+	const lines = new TextDecoder().decode(bytes.value).split("\n");
+	const discarded = /* @__PURE__ */ new Set();
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const parsed = Result.try(() => JSON.parse(lines[index] ?? ""));
+		if (!parsed.isOk() || !isRecord(parsed.value)) continue;
+		const entry = parsed.value;
+		if (entry["path"] !== documentPath) continue;
+		if (entry["type"] === "recovery" && entry["action"] === "discarded") discarded.add(entry["txId"]);
+		else if (entry["type"] === "commit" && !discarded.has(entry["txId"])) return parseLatest(entry);
+	}
+	return null;
+};
 const stagePrefixFor = (documentPath) => `.${path.basename(documentPath)}.folio-stage-`;
 const stagePathFor = (documentPath, txId) => path.join(path.dirname(documentPath), `${stagePrefixFor(documentPath)}${txId}`);
 /** The destination's current version, read without following a symlink; `null` when missing. */
@@ -209,4 +244,4 @@ const recoverStages = async ({ documentPath, journalPath, now }) => {
 	return Result.ok(actions);
 };
 //#endregion
-export { RECOVERY_DISCARD_REASONS, appendJournal, findCommit, journalPathFor, recoverStages, stagePathFor, stagePrefixFor };
+export { RECOVERY_DISCARD_REASONS, appendJournal, findCommit, journalPathFor, latestCommitFor, recoverStages, stagePathFor, stagePrefixFor };

package/dist/lock.d.ts

@@ -3,6 +3,10 @@ import { Result } from "better-result";
 //#region src/lock.d.ts
 /** How long a command-line transaction's lease lasts without renewal. */
 declare const TRANSACTION_LEASE_MS: number;
+/** The owner a lease records when the caller names none. */
+declare const DEFAULT_LEASE_OWNER = "folio-cli";
+/** A lease owner is 1 to 64 letters, digits, '.', '_' or '-'. */
+declare const isLeaseOwner: (value: string) => boolean;
 type LockHolder = {
   owner: string;
   pid: number;
@@ -12,6 +16,8 @@ type LockHolder = {
   token: string;
   acquiredAt: string;
   expiresAt: string;
+  /** The holder saves and releases when a write asks it to (`editor-lease.ts`). */
+  acceptsFlush?: true;
 };
 declare const lockPathFor: (documentPath: string) => string;
 /** What is beside the document: no lock, or a lock with its parsed holder when it has one. */
@@ -34,9 +40,12 @@ declare const isStaleLease: (state: LeaseState, now: Date) => boolean;
 /** The lease currently beside `documentPath`. A symlinked lock reads as unreadable. */
 declare const readLease: (documentPath: string) => Promise<LeaseState>;
 type AcquiredLease = {
+  /** The lock's contents as last written by this handle. */
   holder: LockHolder;
   /** Refuse unless the lock still carries this lease's token. */
   verify: () => Promise<Result<void, FolioCliError>>;
+  /** Push the expiry a lease length past `now`; refuses once the lease was taken over. */
+  renew: (now?: Date) => Promise<Result<LockHolder, FolioCliError>>;
   release: () => Promise<void>;
 };
 type AcquireLeaseOptions = {
@@ -44,12 +53,26 @@ type AcquireLeaseOptions = {
   txId: string;
   /** Take the lease over even when another live holder has it. */
   force: boolean;
+  /** Who holds it (default `folio-cli`), shown to a writer the lease refuses. */
+  owner?: string;
+  /** How long the lease lasts without renewal (default {@link TRANSACTION_LEASE_MS}). */
+  leaseMs?: number;
+  /** Advertise that the holder answers flush requests. */
+  acceptsFlush?: boolean;
   now?: Date;
 };
+/** `.<name>.folio-lock.swap`: held for the instant one process changes an existing lock. */
+declare const lockSwapPathFor: (documentPath: string) => string;
+/**
+ * Act under a lease another call acquired, named by its token: `folio save
+ * --lease-token` from the editor that holds it. Releasing stays with that
+ * holder, so this handle's `release` does nothing.
+ */
+declare const adoptLease: (documentPath: string, token: string) => Promise<Result<AcquiredLease, FolioCliError>>;
 /**
  * Take the lease for one transaction. A stale lease is replaced; a live or
  * unreadable one refuses with `locked` unless `force`.
  */
-declare const acquireLease: ({ documentPath, txId, force, now }: AcquireLeaseOptions) => Promise<Result<AcquiredLease, FolioCliError>>;
+declare const acquireLease: ({ documentPath, txId, force, owner, leaseMs, acceptsFlush, now }: AcquireLeaseOptions) => Promise<Result<AcquiredLease, FolioCliError>>;
 //#endregion
-export { AcquiredLease, LeaseState, LockHolder, TRANSACTION_LEASE_MS, acquireLease, isStaleLease, lockPathFor, readLease };
+export { AcquiredLease, DEFAULT_LEASE_OWNER, LeaseState, LockHolder, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, readLease };

package/dist/lock.js

@@ -1,33 +1,43 @@
-import { errnoCode } from "./document.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { errnoCode } from "./file-system.js";
 import { inspectPath, readSidecarFile, writeNewSidecarFile } from "./sidecar.js";
 import { Result } from "better-result";
-import { randomUUID } from "node:crypto";
 import { link, rename, rm } from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
+import { setTimeout } from "node:timers/promises";
 //#region src/lock.ts
 /**
 * Cooperative write lease: `.<name>.folio-lock` beside the document, holding
 * the owner's pid, host, expiry, and a random token. A folio write takes it
 * for the whole transaction and checks, just before it journals and renames,
 * that the lock still carries its token; a writer whose lease was taken over
-* stops there. A long-lived holder (an editor session) renews it.
+* stops there. A long-lived holder (an editor session) renews it, and marks
+* it `acceptsFlush` when it answers the flush requests `editor-lease.ts`
+* describes.
 *
 * The lock appears complete or not at all: it is written to a private
 * temporary file and hard-linked into place, which fails when a lock exists.
+* Changing a lock that exists (renewing, taking over, releasing, clearing a
+* stale one) is a compare-and-swap under a short swap lock beside it.
 * A lease is stale once it expires or, on the same host, once its process has
 * exited. A lock that cannot be parsed is treated as held until it is older
 * than a lease. Reads never consult it.
 */
 /** How long a command-line transaction's lease lasts without renewal. */
 const TRANSACTION_LEASE_MS = 300 * 1e3;
+/** The owner a lease records when the caller names none. */
+const DEFAULT_LEASE_OWNER = "folio-cli";
+const OWNER_PATTERN = /^[\w.-]{1,64}$/u;
+/** A lease owner is 1 to 64 letters, digits, '.', '_' or '-'. */
+const isLeaseOwner = (value) => OWNER_PATTERN.test(value);
 const lockPathFor = (documentPath) => path.join(path.dirname(documentPath), `.${path.basename(documentPath)}.folio-lock`);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const parseHolder = (text) => {
 	const parsed = Result.try(() => JSON.parse(text));
 	if (parsed.isErr() || !isRecord(parsed.value)) return null;
-	const { owner, pid, host, txId, token, acquiredAt, expiresAt } = parsed.value;
+	const { owner, pid, host, txId, token, acquiredAt, expiresAt, acceptsFlush } = parsed.value;
 	return typeof owner === "string" && typeof pid === "number" && typeof host === "string" && typeof txId === "string" && typeof token === "string" && typeof acquiredAt === "string" && typeof expiresAt === "string" ? {
 		owner,
 		pid,
@@ -35,7 +45,8 @@ const parseHolder = (text) => {
 		txId,
 		token,
 		acquiredAt,
-		expiresAt
+		expiresAt,
+		...acceptsFlush === true && { acceptsFlush: true }
 	} : null;
 };
 const processIsAlive = (pid) => {
@@ -86,6 +97,11 @@ const lockedError = (documentPath, state) => cliError({
 	hint: "Retry after it finishes, or pass --force to take the lease over.",
 	details: state.type === "held" ? { holder: state.holder } : void 0
 });
+const lostError = (documentPath) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.locked,
+	message: `Another process took over the write lease on ${documentPath}; nothing was written.`,
+	hint: "Re-read the document and retry."
+});
 const fileSystemError = (message, error) => cliError({
 	code: FOLIO_CLI_ERROR_CODES.internal,
 	message: `${message}: ${error instanceof Error ? error.message : String(error)}`
@@ -107,51 +123,141 @@ const placeLock = async (lockPath, contents, mode) => {
 		await rm(temporary, { force: true });
 	}
 };
+const encodeHolder = (holder) => new TextEncoder().encode(`${JSON.stringify(holder)}\n`);
+/** How long a swap lock may stand before another process breaks it (its holder crashed). */
+const SWAP_STALE_MS = 10 * 1e3;
+/** How long to wait for another process's swap before refusing. */
+const SWAP_WAIT_MS = 5 * 1e3;
+const SWAP_POLL_MS = 5;
+/** `.<name>.folio-lock.swap`: held for the instant one process changes an existing lock. */
+const lockSwapPathFor = (documentPath) => `${lockPathFor(documentPath)}.swap`;
+/**
+* Run `change` holding the swap lock beside the lease. Every change to an
+* existing lock (a renewal, a forced takeover, a release, removing a stale
+* lock) re-reads the lock and replaces or removes it inside `change`, so the
+* check and the change are one step to every other folio process: a renewal
+* never overwrites a lock another holder took, and a release never removes
+* one. Creating a lock needs no swap lock, since `link` refuses when a lock
+* exists. The swap lock is itself created with `link`; one older than
+* {@link SWAP_STALE_MS} is left by a crash and is broken.
+*/
+const underSwapLock = async (documentPath, change) => {
+	const swapPath = lockSwapPathFor(documentPath);
+	const marker = new TextEncoder().encode(`${process.pid}\n`);
+	const deadline = Date.now() + SWAP_WAIT_MS;
+	for (;;) {
+		const taken = await placeLock(swapPath, marker, "create");
+		if (taken.isErr()) return Result.err(taken.error);
+		if (taken.value.type === "placed") break;
+		const entry = await inspectPath(swapPath);
+		if (entry.isOk() && entry.value.type === "file" && entry.value.modifiedMs + SWAP_STALE_MS <= Date.now()) {
+			await rm(swapPath, { force: true });
+			continue;
+		}
+		if (Date.now() >= deadline) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.locked,
+			message: `The write lease on ${documentPath} is being changed by another process.`,
+			hint: "Retry in a moment."
+		}));
+		await setTimeout(SWAP_POLL_MS);
+	}
+	try {
+		return await change();
+	} finally {
+		await rm(swapPath, { force: true });
+	}
+};
+/** Whether two reads of the lock saw the same lock. */
+const sameLock = (left, right) => left.type === "held" && right.type === "held" && left.holder.token === right.holder.token || left.type === "unreadable" && right.type === "unreadable";
+/** The handle on a lease whose lock carries `initial`'s token. */
+const leaseFor = (documentPath, initial, leaseMs) => {
+	const lockPath = lockPathFor(documentPath);
+	const holds = async () => {
+		const current = await readLease(documentPath);
+		return current.type === "held" && current.holder.token === initial.token;
+	};
+	const lease = {
+		holder: initial,
+		verify: async () => await holds() ? Result.ok() : Result.err(lostError(documentPath)),
+		renew: async (now = /* @__PURE__ */ new Date()) => {
+			const expiresAt = new Date(now.getTime() + leaseMs).toISOString();
+			const renewed = {
+				...lease.holder,
+				expiresAt
+			};
+			const swapped = await underSwapLock(documentPath, async () => {
+				if (!await holds()) return Result.err(lostError(documentPath));
+				const placed = await placeLock(lockPath, encodeHolder(renewed), "replace");
+				return placed.isErr() ? Result.err(placed.error) : Result.ok();
+			});
+			if (swapped.isErr()) return Result.err(swapped.error);
+			lease.holder = renewed;
+			return Result.ok(renewed);
+		},
+		release: async () => {
+			await underSwapLock(documentPath, async () => {
+				if (await holds()) await rm(lockPath, { force: true });
+				return Result.ok();
+			});
+		}
+	};
+	return lease;
+};
+/**
+* Act under a lease another call acquired, named by its token: `folio save
+* --lease-token` from the editor that holds it. Releasing stays with that
+* holder, so this handle's `release` does nothing.
+*/
+const adoptLease = async (documentPath, token) => {
+	const current = await readLease(documentPath);
+	if (current.type !== "held" || current.holder.token !== token) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.locked,
+		message: `${documentPath} is not held under that lease token.`,
+		hint: "The lease expired or was taken over; acquire it again and retry.",
+		details: current.type === "held" ? { holder: current.holder } : void 0
+	}));
+	const { holder } = current;
+	const leaseMs = Math.max(Date.parse(holder.expiresAt) - Date.parse(holder.acquiredAt), 0);
+	const lease = leaseFor(documentPath, holder, leaseMs);
+	lease.release = () => Promise.resolve();
+	return Result.ok(lease);
+};
 /**
 * Take the lease for one transaction. A stale lease is replaced; a live or
 * unreadable one refuses with `locked` unless `force`.
 */
-const acquireLease = async ({ documentPath, txId, force, now = /* @__PURE__ */ new Date() }) => {
+const acquireLease = async ({ documentPath, txId, force, owner = DEFAULT_LEASE_OWNER, leaseMs = TRANSACTION_LEASE_MS, acceptsFlush = false, now = /* @__PURE__ */ new Date() }) => {
 	const lockPath = lockPathFor(documentPath);
 	const holder = {
-		owner: "folio-cli",
+		owner,
 		pid: process.pid,
 		host: hostname(),
 		txId,
 		token: randomUUID(),
 		acquiredAt: now.toISOString(),
-		expiresAt: new Date(now.getTime() + TRANSACTION_LEASE_MS).toISOString()
-	};
-	const contents = new TextEncoder().encode(`${JSON.stringify(holder)}\n`);
-	const holds = async () => {
-		const current = await readLease(documentPath);
-		return current.type === "held" && current.holder.token === holder.token;
-	};
-	const lease = {
-		holder,
-		verify: async () => await holds() ? Result.ok() : Result.err(cliError({
-			code: FOLIO_CLI_ERROR_CODES.locked,
-			message: `Another process took over the write lease on ${documentPath}; nothing was written.`,
-			hint: "Re-read the document and retry."
-		})),
-		release: async () => {
-			if (await holds()) await rm(lockPath, { force: true });
-		}
+		expiresAt: new Date(now.getTime() + leaseMs).toISOString(),
+		...acceptsFlush && { acceptsFlush: true }
 	};
+	const contents = encodeHolder(holder);
+	const lease = leaseFor(documentPath, holder, leaseMs);
 	for (let attempt = 0; attempt < 2; attempt++) {
 		const placed = await placeLock(lockPath, contents, "create");
 		if (placed.isErr()) return Result.err(placed.error);
 		if (placed.value.type === "placed") return Result.ok(lease);
 		const existing = await readLease(documentPath);
 		if (force) {
-			const replaced = await placeLock(lockPath, contents, "replace");
+			const replaced = await underSwapLock(documentPath, () => placeLock(lockPath, contents, "replace"));
 			if (replaced.isErr()) return Result.err(replaced.error);
 			return Result.ok(lease);
 		}
 		if (!isStaleLease(existing, now)) return Result.err(lockedError(documentPath, existing));
-		await rm(lockPath, { force: true });
+		const removed = await underSwapLock(documentPath, async () => {
+			if (sameLock(existing, await readLease(documentPath))) await rm(lockPath, { force: true });
+			return Result.ok();
+		});
+		if (removed.isErr()) return Result.err(removed.error);
 	}
 	return Result.err(lockedError(documentPath, { type: "free" }));
 };
 //#endregion
-export { TRANSACTION_LEASE_MS, acquireLease, isStaleLease, lockPathFor, readLease };
+export { DEFAULT_LEASE_OWNER, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, readLease };

package/dist/output-file.d.ts

@@ -1,5 +1,6 @@
 import { FolioCliError } from "./errors.js";
-import { FileIdentity } from "./document.js";
+import { FileIdentity } from "./file-system.js";
+import "./document.js";
 import { Result } from "better-result";
 //#region src/output-file.d.ts
 type WriteOutputOptions = {