bwx 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwx",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "keywords": [
     "bitwarden",

package/src/bw/fields.ts

@@ -67,7 +67,8 @@ export async function readItemField(
 ): Promise<string> {
 	return withLookupHelp(item, opts, async () => {
 		if (isTotpField(field, options)) {
-			return (await resolveTotp(await fetchItem(item, opts), item, opts)).code;
+			const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
+			return (await nextCode()).code;
 		}
 
 		return isBuiltinField(field) && !options?.customOnly
@@ -76,18 +77,31 @@ export async function readItemField(
 	});
 }
 
+export interface ReadTotpOptions {
+	/**
+	 * Wait for the next window when the code has fewer than this many seconds
+	 * left, rather than handing back one that expires on the way to the prompt.
+	 */
+	minSecondsRemaining?: number;
+	/** Notified with the seconds about to be spent waiting, for progress output. */
+	onWait?: (seconds: number) => void;
+}
+
 /**
  * Reads a TOTP with the time it has left. A code handed over with three seconds
- * on it is usually dead before it is pasted, so callers need the remainder to
- * decide whether to wait for the next window.
+ * on it is usually dead before it is pasted, so callers get the remainder to
+ * decide for themselves — or set `minSecondsRemaining` and have the wait handled
+ * here, where the secret is still in hand and a fresh code is free.
  */
 export async function readTotp(
 	item: string,
 	opts: GlobalOptions,
+	options?: ReadTotpOptions,
 ): Promise<TotpCode> {
-	return withLookupHelp(item, opts, async () =>
-		resolveTotp(await fetchItem(item, opts), item, opts),
-	);
+	return withLookupHelp(item, opts, async () => {
+		const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
+		return awaitUsableWindow(nextCode, options);
+	});
 }
 
 /** The stored secret itself, for moving a seed back out to another authenticator. */
@@ -113,29 +127,58 @@ function requireStoredTotp(item: BwItem): string {
 }
 
 /**
- * Computes the code from the secret already in hand, falling back to `bw get
- * totp` for the shapes this codebase will not compute itself (see `totp.ts`).
- * The fallback costs a second spawn, which is the correct trade against
- * emitting a confidently wrong six digits.
+ * Produces a code for the current window. Callable rather than a single resolved
+ * value so waiting out a nearly-dead window is cheap: the local path just runs
+ * the HMAC again over the secret it captured.
  */
-async function resolveTotp(
+type TotpSource = () => Promise<TotpCode>;
+
+/**
+ * Decides how this item's codes are computed: locally from the secret already in
+ * hand, or by `bw get totp` for the shapes this codebase will not compute itself
+ * (see `totp.ts`). The fallback costs a spawn per code, which is the correct
+ * trade against emitting a confidently wrong six digits.
+ */
+function resolveTotpSource(
 	fetched: BwItem,
 	item: string,
 	opts: GlobalOptions,
-): Promise<TotpCode> {
+): TotpSource {
 	const stored = requireStoredTotp(fetched);
 
 	try {
-		return generateTotp(parseTotpSecret(stored));
+		const config = parseTotpSecret(stored);
+		return async () => generateTotp(config);
 	} catch (err) {
 		if (!(err instanceof TotpUnsupportedError)) throw err;
-
-		return {
-			code: await readBuiltinField("totp", item, opts),
-			period: DEFAULT_PERIOD,
-			secondsRemaining: secondsRemaining(DEFAULT_PERIOD),
-		};
 	}
+
+	return async () => ({
+		code: await readBuiltinField("totp", item, opts),
+		period: DEFAULT_PERIOD,
+		secondsRemaining: secondsRemaining(DEFAULT_PERIOD),
+	});
+}
+
+/**
+ * Sleeps out a window with too little left, then asks the source for the next
+ * code. Only the `bw` fallback pays a second spawn for that; the local path
+ * recomputes from the secret it holds, so the returned code has a full window
+ * rather than one already spent on a second vault round-trip.
+ */
+async function awaitUsableWindow(
+	nextCode: TotpSource,
+	options?: ReadTotpOptions,
+): Promise<TotpCode> {
+	const code = await nextCode();
+
+	const minimum = options?.minSecondsRemaining;
+	if (minimum === undefined || code.secondsRemaining >= minimum) return code;
+
+	options?.onWait?.(code.secondsRemaining);
+	// The extra beat lands just past the boundary rather than exactly on it.
+	await Bun.sleep(code.secondsRemaining * 1000 + 250);
+	return nextCode();
 }
 
 /**
@@ -169,10 +212,8 @@ export async function readFields(
 			const request = requests[index]!;
 
 			if (isTotpField(request.field, request.options)) {
-				const totp = await withLookupHelp(item, opts, () =>
-					resolveTotp(fetched, item, opts),
-				);
-				values[index] = totp.code;
+				const nextCode = resolveTotpSource(fetched, item, opts);
+				values[index] = (await withLookupHelp(item, opts, nextCode)).code;
 			} else {
 				values[index] = extractField(fetched, request.field, request.options);
 			}

package/src/bw/session.ts

@@ -119,9 +119,11 @@ export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 		},
 		async () => {
 			// A process that waited must use the winner's disk cache, not the stale
-			// token it may still have held in memory before entering the lock.
+			// token it may still have held in memory before entering the lock. An
+			// unchanged cache needs no second `bw status`: we just watched that exact
+			// token be refused, and nothing has replaced it.
 			const winner = loadCachedSession(opts);
-			if (winner) {
+			if (winner && winner !== cached) {
 				setSession(winner);
 				if (await sessionWorks(winner)) return;
 				setSession(null);

package/src/bw/totp.ts

@@ -81,6 +81,12 @@ export function parseTotpSecret(raw: string): TotpConfig {
 		throw new TotpUnsupportedError("secret is not base32");
 	}
 
+	// A returned config must be computable, so that generateTotp cannot fail on
+	// one and strand a caller that has already chosen the local path over the bw
+	// fallback. Base32 alone does not promise that: a single character carries
+	// five bits and decodes to no whole byte.
+	base32Decode(config.secret);
+
 	return config;
 }
 

package/src/cli/commands/create.ts

@@ -11,7 +11,9 @@ import {
 	assertSingleStdinSource,
 	collect,
 	listExplicitStdinInputs,
+	loginOnlyTextInputFlags,
 	readOptionalStdin,
+	registerItemTextOptions,
 	resolveFieldSources,
 	resolveItemTextInputs,
 	StdinReader,
@@ -36,36 +38,18 @@ interface CreateOptions extends ItemTextInputs {
 /** Flags a secure note has nowhere to store — see {@link assertLoginFlags}. */
 const LOGIN_ONLY_FLAGS: Array<[keyof CreateOptions, string]> = [
 	["username", "--username"],
-	["password", "--password"],
-	["passwordStdin", "--password-stdin"],
-	["passwordFile", "--password-file"],
-	["passwordEnv", "--password-env"],
-	["passwordGenerate", "--password-generate"],
-	["totp", "--totp"],
-	["totpStdin", "--totp-stdin"],
-	["totpFile", "--totp-file"],
-	["totpEnv", "--totp-env"],
+	...loginOnlyTextInputFlags(),
 ];
 
 export function registerCreate(program: Command): void {
-	program
+	const command = program
 		.command("create").alias("add")
 		.description("Create a new vault item")
 		.option("--type <type>", "Item type: login|note", "note")
 		.option("--name <name>", "Item name")
-		.option("--notes <text>", "Notes content")
-		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
-		.option("--username <user>", "Username (login type)")
-		.option("--password <pass>", "Password (login type)")
-		.option("--password-stdin", "Read password from stdin")
-		.option("--password-file <path>", "Read password from file (use - for stdin)")
-		.option("--password-env <name>", "Read password from environment variable")
-		.option("--password-generate", "Generate the password; it is never printed")
-		.option("--generate-length <n>", "Length for --password-generate", parseInt)
-		.option("--totp <secret>", "TOTP secret: base32 or otpauth:// URI (login type)")
-		.option("--totp-stdin", "Read the TOTP secret from stdin")
-		.option("--totp-file <path>", "Read the TOTP secret from file (use - for stdin)")
-		.option("--totp-env <name>", "Read the TOTP secret from environment variable")
+		.option("--username <user>", "Username (login items only)");
+
+	registerItemTextOptions(command)
 		.option("--uri <url>", "URI (repeatable)", collect, [])
 		.option("--field <kv>", "Custom field k=v (repeatable)", collect, [])
 		.option("--field-file <kv>", "Custom field value from file k=path (repeatable)", collect, [])

package/src/cli/commands/edit.ts

@@ -12,9 +12,13 @@ import {
 	assertSingleStdinSource,
 	collect,
 	listExplicitStdinInputs,
+	listUsedSourceFlags,
+	loginOnlyTextInputFlags,
+	registerItemTextOptions,
 	resolveFieldSources,
 	resolveItemTextInputs,
 	StdinReader,
+	TOTP_FAMILY,
 	type ItemTextInputs,
 } from "../input.ts";
 import { redactGeneratedPassword } from "./generate.ts";
@@ -36,37 +40,19 @@ interface EditOptions extends ItemTextInputs {
 
 const LOGIN_ONLY_FLAGS: Array<[keyof EditOptions, string]> = [
 	["username", "--username"],
-	["password", "--password"],
-	["passwordStdin", "--password-stdin"],
-	["passwordFile", "--password-file"],
-	["passwordEnv", "--password-env"],
-	["passwordGenerate", "--password-generate"],
-	["totp", "--totp"],
-	["totpStdin", "--totp-stdin"],
-	["totpFile", "--totp-file"],
-	["totpEnv", "--totp-env"],
+	...loginOnlyTextInputFlags(),
 	["rmTotp", "--rm-totp"],
 ];
 
 export function registerEdit(program: Command): void {
-	program
+	const command = program
 		.command("edit")
 		.description("Edit an existing vault item")
 		.argument("<item>", "Item name or ID")
 		.option("--name <name>", "New name")
-		.option("--notes <text>", "New notes")
-		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
-		.option("--username <user>", "New username")
-		.option("--password <pass>", "New password")
-		.option("--password-stdin", "Read password from stdin")
-		.option("--password-file <path>", "Read password from file (use - for stdin)")
-		.option("--password-env <name>", "Read password from environment variable")
-		.option("--password-generate", "Generate the password; it is never printed")
-		.option("--generate-length <n>", "Length for --password-generate", parseInt)
-		.option("--totp <secret>", "Set TOTP secret: base32 or otpauth:// URI")
-		.option("--totp-stdin", "Read the TOTP secret from stdin")
-		.option("--totp-file <path>", "Read the TOTP secret from file (use - for stdin)")
-		.option("--totp-env <name>", "Read the TOTP secret from environment variable")
+		.option("--username <user>", "New username");
+
+	registerItemTextOptions(command)
 		.option("--rm-totp", "Remove the stored TOTP secret")
 		.option("--uri <url>", "Set URIs (repeatable, replaces all)", collect, [])
 		.option("--add-field <kv>", "Add/update field k=v", collect, [])
@@ -165,12 +151,7 @@ export function registerEdit(program: Command): void {
 function assertTotpIntent(localOpts: EditOptions): void {
 	if (!localOpts.rmTotp) return;
 
-	const setters = [
-		localOpts.totp !== undefined ? "--totp" : null,
-		localOpts.totpStdin ? "--totp-stdin" : null,
-		localOpts.totpFile !== undefined ? "--totp-file" : null,
-		localOpts.totpEnv !== undefined ? "--totp-env" : null,
-	].filter((flag): flag is string => flag !== null);
+	const setters = listUsedSourceFlags(TOTP_FAMILY, localOpts);
 
 	if (setters.length > 0) {
 		throw new CliError(

package/src/cli/commands/get.ts

@@ -80,15 +80,11 @@ async function emitTotp(
 		return;
 	}
 
-	const threshold = parseFreshSeconds(localOpts.fresh);
-	let totp = await readTotp(item, opts);
-
-	if (threshold !== null && totp.secondsRemaining < threshold) {
-		const wait = totp.secondsRemaining;
-		emitLog(`Waiting ${wait}s for a fresh code…`, opts);
-		await Bun.sleep(wait * 1000 + 250);
-		totp = await readTotp(item, opts);
-	}
+	const totp = await readTotp(item, opts, {
+		minSecondsRemaining: parseFreshSeconds(localOpts.fresh),
+		onWait: (seconds) =>
+			emitLog(`Waiting ${seconds}s for a fresh code…`, opts),
+	});
 
 	emitLog(`Valid for ${totp.secondsRemaining}s`, opts);
 	emitData(totp.code, opts, {
@@ -101,8 +97,8 @@ async function emitTotp(
  * `--fresh` is a bare flag by default and takes an explicit threshold when the
  * caller needs longer than {@link DEFAULT_FRESH_SECONDS} to use the code.
  */
-function parseFreshSeconds(raw: string | boolean | undefined): number | null {
-	if (raw === undefined || raw === false) return null;
+function parseFreshSeconds(raw: string | boolean | undefined): number | undefined {
+	if (raw === undefined || raw === false) return undefined;
 	if (raw === true) return DEFAULT_FRESH_SECONDS;
 
 	const value = Number(raw.trim());

package/src/cli/input.ts

@@ -1,3 +1,4 @@
+import type { Command } from "commander";
 import { parseFieldFlag, type ParsedField } from "../bw/encoding.ts";
 import { normalizeTotpInput } from "../bw/totp.ts";
 import { CliError, ExitCode } from "./errors.ts";
@@ -80,15 +81,176 @@ export interface ExplicitStdinInputs extends ItemTextInputs {
 	fieldFiles?: string[];
 }
 
-const NOTE_SOURCE_FLAGS = ["--notes", "--notes-file"];
-const PASSWORD_SOURCE_FLAGS = [
-	"--password",
-	"--password-stdin",
-	"--password-file",
-	"--password-env",
-	"--password-generate",
-];
-const TOTP_SOURCE_FLAGS = ["--totp", "--totp-stdin", "--totp-file", "--totp-env"];
+/** Which slot of a {@link TextSource} a flag fills. */
+type TextSourceKind = "inline" | "stdin" | "file" | "env" | "generate";
+
+interface TextInputFlag {
+	/** Commander option spec, e.g. `--password-file <path>`. */
+	spec: string;
+	description: string;
+	/** The property commander derives from `spec`. */
+	key: keyof ItemTextInputs;
+	kind: TextSourceKind;
+}
+
+/**
+ * One value a caller can supply, and every flag that can supply it. Option
+ * registration, the "choose only one source" error, the stdin-conflict check and
+ * the login-only guard all read from here, so adding a source touches one table
+ * rather than both write commands and three hand-kept lists.
+ */
+export interface TextInputFamily {
+	/** Names the value in error messages. */
+	label: string;
+	flags: TextInputFlag[];
+	/** True when only a login item has anywhere to store the value. */
+	loginOnly: boolean;
+	/** Whether empty is a legitimate value — it is, for notes. */
+	allowEmpty?: boolean;
+}
+
+const NOTES_FAMILY: TextInputFamily = {
+	label: "notes",
+	loginOnly: false,
+	allowEmpty: true,
+	flags: [
+		{
+			spec: "--notes <text>",
+			description: "Notes content",
+			key: "notes",
+			kind: "inline",
+		},
+		{
+			spec: "--notes-file <path>",
+			description: "Read notes from file (use - for stdin)",
+			key: "notesFile",
+			kind: "file",
+		},
+	],
+};
+
+const PASSWORD_FAMILY: TextInputFamily = {
+	label: "password",
+	loginOnly: true,
+	flags: [
+		{
+			spec: "--password <pass>",
+			description: "Password (login items only)",
+			key: "password",
+			kind: "inline",
+		},
+		{
+			spec: "--password-stdin",
+			description: "Read password from stdin",
+			key: "passwordStdin",
+			kind: "stdin",
+		},
+		{
+			spec: "--password-file <path>",
+			description: "Read password from file (use - for stdin)",
+			key: "passwordFile",
+			kind: "file",
+		},
+		{
+			spec: "--password-env <name>",
+			description: "Read password from environment variable",
+			key: "passwordEnv",
+			kind: "env",
+		},
+		{
+			spec: "--password-generate",
+			description: "Generate the password; it is never printed",
+			key: "passwordGenerate",
+			kind: "generate",
+		},
+	],
+};
+
+export const TOTP_FAMILY: TextInputFamily = {
+	label: "TOTP secret",
+	loginOnly: true,
+	flags: [
+		{
+			spec: "--totp <secret>",
+			description: "TOTP secret: base32 or otpauth:// URI (login items only)",
+			key: "totp",
+			kind: "inline",
+		},
+		{
+			spec: "--totp-stdin",
+			description: "Read the TOTP secret from stdin",
+			key: "totpStdin",
+			kind: "stdin",
+		},
+		{
+			spec: "--totp-file <path>",
+			description: "Read the TOTP secret from file (use - for stdin)",
+			key: "totpFile",
+			kind: "file",
+		},
+		{
+			spec: "--totp-env <name>",
+			description: "Read the TOTP secret from environment variable",
+			key: "totpEnv",
+			kind: "env",
+		},
+	],
+};
+
+const ITEM_TEXT_FAMILIES = [NOTES_FAMILY, PASSWORD_FAMILY, TOTP_FAMILY];
+
+function flagName(spec: string): string {
+	return spec.split(" ")[0]!;
+}
+
+function sourceFlagNames(family: TextInputFamily): string[] {
+	return family.flags.map((flag) => flagName(flag.spec));
+}
+
+/**
+ * Registers every flag that can supply notes, a password, or a TOTP secret, plus
+ * the length modifier `--password-generate` takes. `create` and `edit` accept the
+ * identical set and {@link resolveItemTextInputs} is their only reader, so the
+ * set is declared once here instead of per command.
+ */
+export function registerItemTextOptions(command: Command): Command {
+	for (const family of ITEM_TEXT_FAMILIES) {
+		for (const flag of family.flags) {
+			command.option(flag.spec, flag.description);
+		}
+	}
+
+	return command.option(
+		"--generate-length <n>",
+		"Length for --password-generate",
+		(value) => Number.parseInt(value, 10),
+	);
+}
+
+/**
+ * The `[key, flag]` pairs a command must reject on a non-login item, because
+ * `buildNewItem` and `patchItem` have nowhere to put them and would accept the
+ * value only to drop it.
+ */
+export function loginOnlyTextInputFlags(): Array<[keyof ItemTextInputs, string]> {
+	return ITEM_TEXT_FAMILIES.filter((family) => family.loginOnly).flatMap(
+		(family) =>
+			family.flags.map(
+				(flag) =>
+					[flag.key, flagName(flag.spec)] as [keyof ItemTextInputs, string],
+			),
+	);
+}
+
+/** The flags a caller actually used to supply this family's value. */
+export function listUsedSourceFlags(
+	family: TextInputFamily,
+	inputs: ItemTextInputs,
+): string[] {
+	return family.flags
+		.filter((flag) => inputs[flag.key] !== undefined)
+		.map((flag) => flagName(flag.spec));
+}
 
 export async function resolveItemTextInputs(
 	inputs: ItemTextInputs,
@@ -100,17 +262,17 @@ export async function resolveItemTextInputs(
 	const [notes, password, totp] = await Promise.all([
 		resolveOptionalTextSource(
 			{
-				label: "notes",
+				label: NOTES_FAMILY.label,
 				inline: inputs.notes,
 				file: inputs.notesFile,
-				flagNames: NOTE_SOURCE_FLAGS,
-				allowEmpty: true,
+				flagNames: sourceFlagNames(NOTES_FAMILY),
+				allowEmpty: NOTES_FAMILY.allowEmpty,
 			},
 			stdin,
 		),
 		resolveOptionalTextSource(
 			{
-				label: "password",
+				label: PASSWORD_FAMILY.label,
 				inline: inputs.password,
 				stdin: inputs.passwordStdin,
 				file: inputs.passwordFile,
@@ -119,18 +281,18 @@ export async function resolveItemTextInputs(
 					inputs.passwordGenerate && generatePassword
 						? generatePassword
 						: undefined,
-				flagNames: PASSWORD_SOURCE_FLAGS,
+				flagNames: sourceFlagNames(PASSWORD_FAMILY),
 			},
 			stdin,
 		),
 		resolveOptionalTextSource(
 			{
-				label: "TOTP secret",
+				label: TOTP_FAMILY.label,
 				inline: inputs.totp,
 				stdin: inputs.totpStdin,
 				file: inputs.totpFile,
 				env: inputs.totpEnv,
-				flagNames: TOTP_SOURCE_FLAGS,
+				flagNames: sourceFlagNames(TOTP_FAMILY),
 			},
 			stdin,
 		),
@@ -147,16 +309,26 @@ export async function resolveItemTextInputs(
 }
 
 export function listExplicitStdinInputs(inputs: ExplicitStdinInputs): string[] {
-	return [
-		inputs.notesFile === "-" ? "--notes-file -" : null,
-		inputs.passwordStdin ? "--password-stdin" : null,
-		inputs.passwordFile === "-" ? "--password-file -" : null,
-		inputs.totpStdin ? "--totp-stdin" : null,
-		inputs.totpFile === "-" ? "--totp-file -" : null,
-		...(inputs.fieldFileFlag && inputs.fieldFiles
-			? stdinSourcesForFieldFiles(inputs.fieldFileFlag, inputs.fieldFiles)
-			: []),
-	].filter((value): value is string => value !== null);
+	const sources: string[] = [];
+
+	for (const family of ITEM_TEXT_FAMILIES) {
+		for (const flag of family.flags) {
+			const name = flagName(flag.spec);
+			if (flag.kind === "stdin" && inputs[flag.key]) {
+				sources.push(name);
+			} else if (flag.kind === "file" && inputs[flag.key] === "-") {
+				sources.push(`${name} -`);
+			}
+		}
+	}
+
+	if (inputs.fieldFileFlag && inputs.fieldFiles) {
+		sources.push(
+			...stdinSourcesForFieldFiles(inputs.fieldFileFlag, inputs.fieldFiles),
+		);
+	}
+
+	return sources;
 }
 
 export async function resolveOptionalTextSource(

package/src/config/process-lock.ts

@@ -64,32 +64,42 @@ export async function withProcessLock<T>(
 
 async function acquire(options: ProcessLockOptions): Promise<Ownership> {
 	const startedAt = performance.now();
-	let holder: LockOwner | null = null;
 
 	while (true) {
 		const ownership = tryCreate(options.path);
 		if (ownership) return ownership;
 
-		holder = readOwner(options.path, options.label);
-		if (!holder) continue;
+		const holder = readOwner(options.path, options.label);
 
-		if (!isProcessAlive(holder.pid)) {
+		if (holder && !isProcessAlive(holder.pid)) {
 			if (detachAbandonedLock(options.path, holder, options.label)) continue;
 		}
 
+		// The deadline is checked even when the lock turned out to be free, so a
+		// peer that keeps taking and releasing it cannot spin us indefinitely.
 		const elapsed = performance.now() - startedAt;
-		if (elapsed >= options.waitMs) {
-			throw new CliError(
-				`Timed out after ${formatDuration(options.waitMs)} waiting for ${options.label} held by pid ${holder.pid}`,
-				ExitCode.Timeout,
-			);
-		}
+		if (elapsed >= options.waitMs) throw timedOut(options, holder);
+
+		// A lock that vanished mid-inspection is free: contend for it again at once
+		// rather than sleeping on a holder that is already gone.
+		if (!holder) continue;
 
 		const remaining = options.waitMs - elapsed;
 		await Bun.sleep(Math.min(options.pollMs ?? DEFAULT_POLL_MS, remaining));
 	}
 }
 
+function timedOut(
+	options: ProcessLockOptions,
+	holder: LockOwner | null,
+): CliError {
+	const held = holder ? ` held by pid ${holder.pid}` : "";
+	return new CliError(
+		`Timed out after ${formatDuration(options.waitMs)} waiting for ${options.label}${held}`,
+		ExitCode.Timeout,
+	);
+}
+
 function tryCreate(path: string): Ownership | null {
 	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 
@@ -143,6 +153,14 @@ function readOwner(path: string, label: string): LockOwner | null {
 
 	const read = readPrivateFile(`${path}/${OWNER_FILE}`);
 	if (read.kind !== "ok") {
+		// A holder publishes `owner.json` before the directory is renamed into
+		// place, and lets go by renaming the whole directory away. So an owner file
+		// that would not read, under a directory that is no longer the one just
+		// inspected, means the holder released mid-read — the caller should contend
+		// again rather than report a corrupt lock. Only an unreadable owner file in
+		// the *same* directory is genuinely wrong.
+		if (inodeAt(path) !== stat.ino) return null;
+
 		const reason =
 			read.kind === "missing"
 				? `${path}/${OWNER_FILE} is missing`
@@ -246,6 +264,20 @@ function pathExists(path: string): boolean {
 	}
 }
 
+/**
+ * Identifies what currently sits at `path`, or `null` when nothing does. Compared
+ * against an earlier `stat` it answers "is this still the same directory?", which
+ * distinguishes a released lock from a corrupt one.
+ */
+function inodeAt(path: string): number | null {
+	try {
+		return lstatSync(path).ino;
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return null;
+		throw err;
+	}
+}
+
 function errorCode(err: unknown): string | undefined {
 	return (err as NodeJS.ErrnoException)?.code;
 }