bwx 0.6.0 → 0.6.3

package/README.md

@@ -17,7 +17,7 @@ Bitwarden CLI wrapper for AI agents (`bwx` = `bw extended`). Auto-unlock, sessio
 The native `bw` CLI requires interactive prompts and manual session management. `bwx` wraps it with:
 
 - **Auto-unlock** — first vault command authenticates automatically via macOS Keychain
-- **Session caching** — token written atomically as mode 600 to `~/.config/bwx/session`, passed to `bw` through `BW_SESSION` so it never appears in a process command line
+- **Session caching** — token written atomically as mode 600 to `~/.config/bwx/session`; concurrent callers share one bounded login/unlock attempt, and the token reaches `bw` through `BW_SESSION` rather than a process command line
 - **Structured output** — `--json` and `--plain` flags for machine-parseable output
 - **Leak-resistant** — listings never print secrets, `bwx run` hands them to a child process instead of stdout
 - **No interaction** — credentials from config + Keychain, never prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwx",
-  "version": "0.6.0",
+  "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

@@ -2,9 +2,16 @@ import { unlinkSync } from "node:fs";
 import { CliError, ExitCode } from "../cli/errors.ts";
 import type { GlobalOptions } from "../cli/types.ts";
 import { emitLog, emitWarn } from "../cli/io.ts";
-import { SESSION_FILE } from "../config/paths.ts";
+import { SESSION_FILE, SESSION_LOCK_DIR } from "../config/paths.ts";
+import { withProcessLock } from "../config/process-lock.ts";
 import { readPrivateFile, writePrivateFile } from "../config/secure-file.ts";
-import { runBw, runBwOrThrow, setSession, getSession } from "./runner.ts";
+import {
+	DEFAULT_TIMEOUT_MS,
+	runBw,
+	runBwOrThrow,
+	setSession,
+	getSession,
+} from "./runner.ts";
 import { checkVaultFreshness } from "./freshness.ts";
 import { getStatus } from "./status.ts";
 import { BwStatusSchema } from "./types.ts";
@@ -96,13 +103,38 @@ export async function probeSessionState(
 }
 
 export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
-	// Try cached session first
+	// Keep the ordinary valid-session path entirely outside the process lock.
 	const cached = getSession() || loadCachedSession(opts);
 	if (cached) {
 		setSession(cached);
 		if (await sessionWorks(cached)) return;
+		setSession(null);
 	}
 
+	await withProcessLock(
+		{
+			path: SESSION_LOCK_DIR,
+			label: "Bitwarden session establishment",
+			waitMs: sessionLockWaitMs(opts),
+		},
+		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. 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 && winner !== cached) {
+				setSession(winner);
+				if (await sessionWorks(winner)) return;
+				setSession(null);
+			}
+
+			await establishSession(opts);
+		},
+	);
+}
+
+async function establishSession(opts: GlobalOptions): Promise<void> {
 	const status = await getStatus();
 
 	if (status.status === "unlocked") {
@@ -152,6 +184,13 @@ export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 	saveCachedSession(token);
 }
 
+/** Four sequential `bw` calls cover stale validation plus status/login/unlock. */
+function sessionLockWaitMs(opts: GlobalOptions): number {
+	const perCall =
+		opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+	return Math.min(Math.max(perCall * 4 + 10_000, 10_000), 5 * 60_000);
+}
+
 export async function lockVault(): Promise<void> {
 	await runBw(["lock"], { session: null });
 	setSession(null);
@@ -197,9 +236,9 @@ async function withAuthRetry<T>(
 		return await fn();
 	} catch (err) {
 		if (err instanceof CliError && err.exitCode === ExitCode.AuthFailed) {
-			// Clear stale session and re-auth
+			// Do not unlink the shared cache here: another process may already have
+			// atomically replaced our stale token with a freshly unlocked session.
 			setSession(null);
-			clearCachedSession();
 			await ensureUnlocked(opts);
 			return await fn();
 		}

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/paths.ts

@@ -8,5 +8,7 @@ export const CONFIG_DIR = `${CONFIG_HOME}/bwx`;
 export const CONFIG_FILE = `${CONFIG_DIR}/config.json`;
 /** Cached `bw` session token (owner-only). */
 export const SESSION_FILE = `${CONFIG_DIR}/session`;
+/** Cross-process gate used only while establishing a session. */
+export const SESSION_LOCK_DIR = `${CONFIG_DIR}/session.lock`;
 /** Cached vault-freshness snapshot — see bw/freshness.ts. */
 export const STATE_FILE = `${CONFIG_DIR}/state.json`;

package/src/config/process-lock.ts

@@ -0,0 +1,287 @@
+import { randomUUID } from "node:crypto";
+import {
+	chmodSync,
+	lstatSync,
+	mkdirSync,
+	renameSync,
+	rmSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { formatDuration } from "../cli/duration.ts";
+import { readPrivateFile, writePrivateFile } from "./secure-file.ts";
+
+const OWNER_FILE = "owner.json";
+const DEFAULT_POLL_MS = 50;
+const SHARED_BITS = 0o077;
+const UUID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+interface LockOwner {
+	pid: number;
+	token: string;
+	acquiredAt: string;
+}
+
+interface ProcessLockOptions {
+	path: string;
+	label: string;
+	waitMs: number;
+	pollMs?: number;
+}
+
+interface Ownership {
+	path: string;
+	owner: LockOwner;
+}
+
+/**
+ * Runs a critical section under a cross-process lock. Publishing a populated
+ * directory by rename keeps contenders from observing a half-created lock;
+ * live owners are waited on, while dead-owner generations are safely detached.
+ */
+export async function withProcessLock<T>(
+	options: ProcessLockOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	const ownership = await acquire(options);
+	let bodyFailed = false;
+
+	try {
+		return await fn();
+	} catch (err) {
+		bodyFailed = true;
+		throw err;
+	} finally {
+		try {
+			release(ownership, options.label);
+		} catch (err) {
+			// Preserve the operation's useful error if cleanup also failed.
+			if (!bodyFailed) throw err;
+		}
+	}
+}
+
+async function acquire(options: ProcessLockOptions): Promise<Ownership> {
+	const startedAt = performance.now();
+
+	while (true) {
+		const ownership = tryCreate(options.path);
+		if (ownership) return ownership;
+
+		const holder = readOwner(options.path, options.label);
+
+		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 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 });
+
+	const owner: LockOwner = {
+		pid: process.pid,
+		token: randomUUID(),
+		acquiredAt: new Date().toISOString(),
+	};
+	const candidate = `${path}.${owner.token}.tmp`;
+
+	try {
+		mkdirSync(candidate, { mode: 0o700 });
+		chmodSync(candidate, 0o700);
+		writePrivateFile(
+			`${candidate}/${OWNER_FILE}`,
+			JSON.stringify(owner) + "\n",
+		);
+		try {
+			renameSync(candidate, path);
+			return { path, owner };
+		} catch (err) {
+			if (pathExists(path)) return null;
+			throw err;
+		}
+	} finally {
+		if (pathExists(candidate)) {
+			rmSync(candidate, { recursive: true, force: true });
+		}
+	}
+}
+
+function readOwner(path: string, label: string): LockOwner | null {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return null;
+		throw err;
+	}
+
+	if (stat.isSymbolicLink() || !stat.isDirectory()) {
+		throw invalidLock(label, `${path} is not a regular directory`);
+	}
+	if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+		throw invalidLock(label, `${path} is owned by uid ${stat.uid}`);
+	}
+	if (stat.mode & SHARED_BITS) {
+		const mode = (stat.mode & 0o777).toString(8).padStart(3, "0");
+		throw invalidLock(label, `${path} has mode ${mode}, expected 700`);
+	}
+
+	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`
+				: read.reason;
+		throw invalidLock(label, reason);
+	}
+
+	try {
+		const owner = JSON.parse(read.text) as Partial<LockOwner>;
+		if (
+			!Number.isSafeInteger(owner.pid) ||
+			(owner.pid ?? 0) <= 0 ||
+			typeof owner.token !== "string" ||
+			!UUID_RE.test(owner.token) ||
+			typeof owner.acquiredAt !== "string" ||
+			!Number.isFinite(Date.parse(owner.acquiredAt))
+		) {
+			throw new Error("invalid owner fields");
+		}
+		return owner as LockOwner;
+	} catch {
+		throw invalidLock(label, `${path}/${OWNER_FILE} is malformed`);
+	}
+}
+
+function detachAbandonedLock(
+	path: string,
+	expected: LockOwner,
+	label: string,
+): boolean {
+	// The generation-specific recovery lock prevents two stale observations from
+	// detaching a successor that appeared between inspection and rename.
+	const recoveryPath = `${path}.reap.${expected.token}`;
+	const recovery = tryCreate(recoveryPath);
+	if (!recovery) {
+		const recoveryOwner = readOwner(recoveryPath, `${label} recovery lock`);
+		if (recoveryOwner && !isProcessAlive(recoveryOwner.pid)) {
+			detachAbandonedLock(
+				recoveryPath,
+				recoveryOwner,
+				`${label} recovery lock`,
+			);
+		}
+		return false;
+	}
+
+	let abandoned: string | null = null;
+	try {
+		const current = readOwner(path, label);
+		if (
+			!current ||
+			current.token !== expected.token ||
+			isProcessAlive(current.pid)
+		) {
+			return false;
+		}
+
+		abandoned = `${path}.${expected.token}.abandoned`;
+		try {
+			renameSync(path, abandoned);
+		} catch (err) {
+			if (errorCode(err) === "ENOENT") return false;
+			throw err;
+		}
+
+		// Cleanup names the detached generation, never a successor at the lock path.
+		rmSync(abandoned, { recursive: true, force: true });
+		return true;
+	} finally {
+		release(recovery, `${label} recovery lock`);
+	}
+}
+
+function release(ownership: Ownership, label: string): void {
+	const current = readOwner(ownership.path, label);
+	if (!current || current.token !== ownership.owner.token) {
+		throw invalidLock(label, "ownership changed before release");
+	}
+
+	const released = `${ownership.path}.${ownership.owner.token}.released`;
+	renameSync(ownership.path, released);
+	rmSync(released, { recursive: true, force: true });
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return errorCode(err) !== "ESRCH";
+	}
+}
+
+function pathExists(path: string): boolean {
+	try {
+		lstatSync(path);
+		return true;
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return false;
+		throw err;
+	}
+}
+
+/**
+ * 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;
+}
+
+function invalidLock(label: string, reason: string): CliError {
+	return new CliError(`Unsafe or corrupt ${label}: ${reason}`, ExitCode.Config);
+}