mnemonad-cli 0.1.1 → 0.3.0

package/lib/commands/search.js

@@ -0,0 +1,91 @@
+import { join } from 'node:path';
+import {
+    Searcher, VectorIndex, DEFAULT_DB_NAME, createProvider, resolveModelName, MissingExtensionError,
+} from '../search/index.js';
+import { resolvePath, folderExists } from './shared.js';
+
+export async function search(args) {
+    if (!args.query) {
+        throw userError('a search query is required (e.g. `mnemonad search /path/to/folder "how does chunking work"`)');
+    }
+    const destPath = resolvePath(args.path, { mustExist: true });
+    const dbName = args.searchDb || DEFAULT_DB_NAME;
+    const dbPath = join(destPath, dbName);
+
+    if (!folderExists(destPath) || !(await _fileExists(dbPath))) {
+        throw userError(
+            `no ${dbName} found in ${destPath}\n` +
+            '  Run `mnemonad index <path>` first — either yours, or whoever pushed this stream\'s\n' +
+            '  (a pull already brings theirs down with the rest of the folder).'
+        );
+    }
+
+    // The query has to be embedded by the model that built the index — which the index records,
+    // so there's nothing to choose. An explicit --model that disagrees is a mistake worth
+    // naming rather than a preference to honour.
+    const indexModel = VectorIndex.readMeta(dbPath)?.model;
+    if (args.model && indexModel && resolveModelName(args.model) !== indexModel) {
+        throw userError(
+            `${dbName} was built with ${indexModel}; a search has to use the same model — drop --model\n` +
+            '  (search always uses the index\'s own), or rebuild the index with the other one:\n' +
+            `    mnemonad index ${destPath} --model ${args.model} --rebuild`
+        );
+    }
+
+    const searcher = new Searcher({ createProvider });
+    const k = args.limit ? Number(args.limit) : 5;
+    let hits;
+    try {
+        hits = await searcher.search(dbPath, args.query, k);
+    } catch (err) {
+        if (err instanceof MissingExtensionError) {
+            throw userError(
+                `this folder's index was built with ${err.model}, which ${err.message.slice(err.message.indexOf('needs'))}\n` +
+                '  Or rebuild the index with the built-in model:\n' +
+                `    mnemonad index ${destPath} --rebuild`
+            );
+        }
+        throw err;
+    }
+
+    if (hits.length === 0) {
+        console.log('  no matches');
+        return;
+    }
+
+    for (const [i, hit] of hits.entries()) {
+        console.log(`\n${i + 1}. ${hit.path} (chunk ${hit.chunkIndex}, distance ${hit.distance.toFixed(4)})`);
+        const snippet = await _readSnippet(destPath, hit);
+        if (snippet) console.log('   ' + snippet.replace(/\s+/g, ' ').slice(0, 200));
+    }
+}
+
+async function _fileExists(path) {
+    try {
+        const { stat } = await import('node:fs/promises');
+        const s = await stat(path);
+        return s.isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Re-reads the hit's snippet straight from the already-pulled source file — the index
+ *  deliberately doesn't store chunk text itself (see ../search/VectorIndex.js),
+ *  so this is the one place that cost is paid, and only for hits actually shown. */
+async function _readSnippet(destPath, hit) {
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const bytes = await readFile(join(destPath, hit.path));
+        const text = new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+        return text.slice(hit.startOffset, hit.endOffset);
+    } catch {
+        return null;
+    }
+}
+
+function userError(message) {
+    const err = new Error(message);
+    err._isUserError = true;
+    return err;
+}

package/lib/commands/shared.js

@@ -1,4 +1,5 @@
 import { mkdir, writeFile, readFile, readdir, rm } from 'node:fs/promises';
+import { statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
@@ -11,7 +12,7 @@ import { DoubleSync as SyncEngine, CDCStore, DoubleSyncSnapshot as SyncSnapshot
 import { FSFolder } from '../FSFolder.js';
 import { createPresignProvider } from '../presignProvider.js';
 
-const DEFAULT_FS_EXCLUDES = ['node_modules', '.git', '.env', '.DS_Store', '.mnemonad', '.claude', 'pnpm-lock.yaml', 'package-lock.json'];
+export const DEFAULT_FS_EXCLUDES = ['node_modules', '.git', '.env', '.DS_Store', '.mnemonad', '.claude', 'pnpm-lock.yaml', 'package-lock.json'];
 
 export function makeExcludes(args) {
     if (!args.exclude) return undefined;
@@ -56,15 +57,112 @@ export function resolveOffloadParams(args, account) {
  * `p` is missing — every command that touches a folder requires the caller to name it
  * explicitly, so a typo'd or omitted `path` never silently operates on whatever directory
  * the CLI happened to be run from.
+ *
+ * `mustExist` additionally requires the folder to be there already. Every command that
+ * *reads* the local folder passes it, because the alternative is worse than an error in
+ * both directions: `push`/`compact` used to surface a raw ENOENT stack trace from deep
+ * inside `readdir`, and `diff` used to treat a missing folder as an empty one and report
+ * every file in the stream as locally deleted — which reads as "your data is gone" rather
+ * than "you typed the wrong path". `pull` is the one command that leaves it off, since
+ * creating the destination is exactly its job.
+ *
+ * @param {?string} p
+ * @param {Object} [options]
+ * @param {boolean} [options.mustExist=false]
  */
-export function resolvePath(p) {
+export function resolvePath(p, { mustExist = false } = {}) {
     if (!p) {
-        const err = new Error('a folder path is required (e.g. `mnemonad <command> ... /path/to/folder`)');
-        err._isUserError = true;
-        throw err;
+        throw userError('a folder path is required (e.g. `mnemonad <command> ... /path/to/folder`)');
+    }
+
+    const resolved = p.startsWith('~') ? join(homedir(), p.slice(1)) : resolve(p);
+    if (!mustExist) return resolved;
+
+    const stat = statOrNull(resolved);
+    if (!stat) {
+        throw userError(
+            `no such folder: ${resolved}\n` +
+            '  Create it first, or use `mnemonad pull <stream-id> <path>` to fetch one into it.'
+        );
+    }
+    if (!stat.isDirectory()) {
+        throw userError(`not a folder: ${resolved}\n  This command syncs a directory, not a single file.`);
+    }
+    return resolved;
+}
+
+/** @returns {?import('node:fs').Stats} null when the path doesn't exist or isn't readable. */
+function statOrNull(path) {
+    try {
+        return statSync(path);
+    } catch {
+        return null;
     }
-    if (p.startsWith('~')) return join(homedir(), p.slice(1));
-    return resolve(p);
+}
+
+/** Whether `path` is an existing directory. For a command that reports on one rather than
+ *  refusing to run without it (see info.js). */
+export function folderExists(path) {
+    return statOrNull(path)?.isDirectory() === true;
+}
+
+/**
+ * Canonical display form for a stream id: `0x` + the full 32-byte token id, zero-padded,
+ * lowercase. Matches the dApp's own formatting (explorer/src/includes/formatStreamId.js),
+ * unelided — a CLI command needs the whole id to actually reuse, where the dApp's UI only
+ * needs enough of it to recognize at a glance.
+ *
+ * Takes whatever a stream id shows up as in this codebase — a bigint (`mn.id`), or a raw
+ * CLI arg that's either a decimal or a `0x`-hex string — since `BigInt()` parses all three
+ * natively; see bin/mnemonad.js's own `isStreamId` for why both string forms are accepted
+ * as input in the first place.
+ *
+ * @param {bigint|string} id
+ * @returns {string}
+ */
+export function formatStreamId(id) {
+    return '0x' + BigInt(id).toString(16).padStart(64, '0');
+}
+
+/**
+ * Whether two stream ids refer to the same token, regardless of which form either was
+ * written in (decimal, hex, differently-padded hex) — a plain `===` on the raw strings
+ * would wrongly call `123` and `0x7b` different streams.
+ */
+export function streamIdsEqual(a, b) {
+    if (a == null || b == null) return a === b;
+    return BigInt(a) === BigInt(b);
+}
+
+/** Networks a qualified stream id can name — see `parseQualifiedStreamId` below. Kept in
+ *  sync by hand with `chainClient.js`'s own `CHAINS` map (which also lists `local`, never
+ *  meaningful here — no URL is ever built with it) and with the explorer's
+ *  `src/settings.js` `NETWORKS` map, the source these prefixes actually come from. */
+export const NETWORK_PREFIXES = ['testnet', 'mainnet'];
+
+/**
+ * Splits the network-qualified stream-id form the explorer's URLs use — `<network>-0x<hex>`
+ * (or `<network>-<decimal>`), e.g. `testnet-0x648f18…` — into its network and bare id. Same
+ * split the explorer's own `streamRouteId()`/`parseStreamRouteId()`
+ * (`explorer/src/includes/streamRoute.js`) do, so an id copied straight out of a
+ * `/stream/<id>` link parses here too, instead of failing `BigInt()` on the whole string.
+ *
+ * Returns null for anything that isn't this exact shape — an unqualified id, a malformed
+ * one, or a prefix that isn't a known network (not a stream on some network this build
+ * hasn't heard of, just not this form).
+ *
+ * @param {string} s
+ * @returns {{network: string, id: string}|null}
+ */
+export function parseQualifiedStreamId(s) {
+    if (typeof s !== 'string') return null;
+    const dash = s.indexOf('-');
+    if (dash === -1) return null;
+    const prefix = s.slice(0, dash).toLowerCase();
+    if (!NETWORK_PREFIXES.includes(prefix)) return null;
+    const rest = s.slice(dash + 1);
+    if (!/^0x[0-9a-fA-F]+$/.test(rest) && !/^\d+$/.test(rest)) return null;
+    return { network: prefix, id: rest };
 }
 
 export function formatBytes(bytes) {
@@ -107,9 +205,10 @@ export async function assertStreamOwner(mn, signerAddress) {
     if (getAddress(owner) === getAddress(signerAddress)) return;
 
     const err = new Error(
-        `stream ${mn.id} is owned by ${owner}\n` +
+        `stream ${formatStreamId(mn.id)} is owned by ${owner}\n` +
         `  but you are signing as ${signerAddress}.\n` +
-        `  Nothing was uploaded. Use the owner's key (--key / --phrase / MNEMONAD_KEY),\n` +
+        `  Nothing was uploaded. Use the owner's key (--key, --phrase, or the MNEMONAD_KEY\n` +
+        `  env var, set to the private key),\n` +
         `  or run push without a stream id to create your own stream.`
     );
     err._isUserError = true;
@@ -199,14 +298,15 @@ export async function unlockStream(mn, credentials = {}) {
     if (!signer) {
         throw userError(
             'This stream is encrypted to its owner\'s wallet. Provide the owner\'s key with\n' +
-            '  --key / --phrase / MNEMONAD_KEY to decrypt it.'
+            '  --key, --phrase, or the MNEMONAD_KEY env var (set it to the private key) to decrypt it.'
         );
     }
     await mn.unlockWithSignature(signer);
     return true;
 }
 
-function userError(message) {
+/** An error the CLI prints as a plain message (no stack trace) — see bin/mnemonad.js. */
+export function userError(message) {
     const err = new Error(message);
     err._isUserError = true;
     return err;
@@ -244,6 +344,32 @@ export async function writeManifest(destPath, manifest) {
     await writeFile(join(destPath, '.mnemonad'), JSON.stringify(manifest, null, 2));
 }
 
+/**
+ * Recovers a stream id from the folder's own `.mnemonad` manifest when `--manifest` was
+ * passed and no id was given on the command line — the whole point of writing the manifest
+ * is that the id doesn't have to be remembered or re-typed for every later command on the
+ * same folder. Mutates `args.streamId` in place (every call site reads it back off `args`
+ * afterward) and is a no-op whenever an id was already given or `--manifest` wasn't passed —
+ * so it's safe to call unconditionally right after resolving the folder path.
+ *
+ * Silent when there's nothing to find (no `.mnemonad` yet, e.g. a folder's very first push,
+ * or a manifest with no `streamId`) — the caller's own "stream-id is required" error covers
+ * that case with the wording appropriate to its command.
+ *
+ * @param {Object} args - parsed CLI args, mutated in place
+ * @param {string} destPath - resolved folder path to look for `.mnemonad` in
+ * @returns {Promise<?string>} the resolved stream id, or whatever `args.streamId` already was
+ */
+export async function discoverStreamId(args, destPath) {
+    if (args.streamId || !args.manifest) return args.streamId;
+    const manifest = await readManifest(destPath);
+    if (manifest?.streamId) {
+        console.log('  using stream id from .mnemonad manifest:', formatStreamId(manifest.streamId));
+        args.streamId = manifest.streamId;
+    }
+    return args.streamId;
+}
+
 export const DISK_EXCLUDES = new Set(['.mnemonad', '.git', '.DS_Store', 'node_modules']);
 
 export async function hashDiskTree(dirPath, prefix = []) {

package/lib/commands/watch.js

@@ -14,7 +14,11 @@ import {
     assertStreamOwner,
     unlockStream,
     resolveOffloadParams,
+    formatStreamId,
+    discoverStreamId,
+    userError,
 } from './shared.js';
+import { makeIndexer, updateIndex } from './buildIndex.js';
 
 function timestamp() {
     return new Date().toTimeString().slice(0, 8);
@@ -27,17 +31,31 @@ function hashesEqual(a, b) {
 }
 
 export async function watch(args) {
-    if (!args.streamId) throw new Error('stream-id is required for watch');
+    const cwd = resolvePath(args.path, { mustExist: true });
 
-    const cwd = resolvePath(args.path);
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, cwd);
+    if (!args.streamId) throw new Error('stream-id is required for watch');
     const debounceMs = args.debounce ?? 5000;
     const pollIntervalMs = (args.pollInterval ?? 2) * 1000;
     const pushEnabled = !args.pullOnly;
     const pullEnabled = !args.pushOnly;
 
+    if (args.index && !pushEnabled) {
+        throw userError('--index only applies when watch pushes — drop --pull-only to use it');
+    }
+    if (args.rebuild && !args.index) {
+        throw userError('--rebuild only applies with --index (it starts the search index over)');
+    }
+    // One indexer for the whole session: the embedding model loads on the first change and
+    // then stays in memory, so every later re-index costs only the files that changed.
+    // Built now so bad chunking flags or a missing extension fail before watching starts.
+    const indexer = args.index ? await makeIndexer(cwd, args) : null;
+
     const excludes = makeExcludes(args);
 
-    const client = makeChainClient(args);
+    const client = await makeChainClient(args);
     if (pushEnabled) requireWalletClient(client);
 
     // Only a push-enabled session needs write-side offload capability (pinata-jwt or
@@ -70,10 +88,11 @@ export async function watch(args) {
     let debounceTimer = null;
 
     console.log(`watching ${formatPath(cwd)}`);
-    console.log(`  stream:        ${args.streamId}`);
+    console.log(`  stream:        ${formatStreamId(args.streamId)}`);
     console.log(`  remote version: ${remoteVersion}`);
     console.log(`  push:          ${pushEnabled ? `enabled (debounce ${debounceMs}ms)` : 'disabled'}`);
     console.log(`  pull:          ${pullEnabled ? `enabled (poll every ${pollIntervalMs / 1000}s)` : 'disabled'}`);
+    if (indexer) console.log('  index:         updated before every push');
     console.log('press Ctrl+C to stop\n');
 
     async function runPush() {
@@ -83,13 +102,34 @@ export async function watch(args) {
 
         pushInFlight = true;
         try {
-            // Best-effort race guard, not an atomic one: Mnemonad's own contract has no
-            // "expected prior length" check — no atomic on-chain compare-and-abort.
-            // Re-checking here narrows the window where a concurrent push (another `watch`
-            // session, or a manual push) could make MonadSync build a diff against a base
-            // the chain has since moved past — the same failure mode monadsync's own
-            // snapshot-recovery tests exercise — but doesn't close it entirely; only an
-            // on-chain guard could.
+            // Before the push, so the push carries it. The index file's own write then fires
+            // the watcher again, but by then lastSyncedHash (taken after indexing, below)
+            // already includes it, so that second pass finds nothing new and doesn't push.
+            // A failed index skips the push rather than publishing a stale index; the next
+            // change retries both.
+            let hashToSync = newHash;
+            if (indexer) {
+                try {
+                    // Never a rebuild here — `--rebuild` applies once, to the startup pass below.
+                    await updateIndex(cwd, args, { indexer, quiet: true, rebuild: false });
+                } catch (err) {
+                    console.error(`[${timestamp()}] index update failed, not pushing:`, err.message);
+                    return;
+                }
+                hashToSync = await localTreeHash(cwd);
+            }
+
+            // Best-effort race guard, not an atomic one. Mnemonad's contract *does* check an
+            // `expectedLength` atomically (Mnemonad.sol's `_checkLength`/`LengthMismatch`) —
+            // that closes the index race outright: two writers can never land at the same
+            // position, one just reverts. What it can't check is content: it stores opaque
+            // bytes, with no way to verify a diff patch is actually consistent with the real
+            // previous item. Re-checking here narrows the separate window where a concurrent
+            // push (another `watch` session, or a manual push) lands at the *correct* index
+            // but MonadSync still builds its diff against a snapshot the chain has since
+            // moved past — the same failure mode monadsync's own snapshot-recovery tests
+            // exercise. Confirmed live as a real corruption, not just theoretical — see
+            // monadsync/README.md's "Repairing a corrupt chain".
             mn.reInitialize();
             await mn.initialize();
             if (mn.length !== remoteVersion) {
@@ -102,7 +142,7 @@ export async function watch(args) {
             const fsFolder = new FSFolder(cwd, excludes);
             console.log(`[${timestamp()}] change detected — pushing...`);
             const result = await monadSync.push(fsFolder);
-            lastSyncedHash = newHash;
+            lastSyncedHash = hashToSync;
             remoteVersion = result.version;
             console.log(`[${timestamp()}] pushed version ${result.version}`);
         } catch (err) {
@@ -164,6 +204,20 @@ export async function watch(args) {
 
     const poller = setInterval(runPoll, pollIntervalMs);
 
+    // An index that's already out of date when the session starts (files edited, or indexed
+    // for the first time) would otherwise only catch up on the next local change.
+    if (indexer) {
+        try {
+            const result = await updateIndex(cwd, args, { indexer, quiet: true, rebuild: !!args.rebuild });
+            if (result.filesChanged || result.filesRemoved) {
+                console.log(`[${timestamp()}] index was out of date — pushing the update`);
+                debounceTimer = setTimeout(runPush, 0);
+            }
+        } catch (err) {
+            console.error(`[${timestamp()}] index update failed:`, err.message);
+        }
+    }
+
     let shutdownResolve;
     const shutdownPromise = new Promise((resolve) => {
         shutdownResolve = resolve;

package/lib/passkeyBridge.js

@@ -0,0 +1,203 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import open from 'open';
+import { toAccount } from 'viem/accounts';
+import { userError } from './commands/shared.js';
+import { encodeForBridge } from './bridgeCodec.js';
+
+const CONNECT_TIMEOUT_MS = 3 * 60 * 1000;
+
+// One bridge per CLI process — `--passkey` resolves at most one signing account per
+// invocation (see resolveAccount in chainClient.js), so there's nothing to key this by.
+let active = null;
+
+/** A one-line "what's this for" the browser tab shows while it waits — just the command
+ *  shape, not the flags, so it stays short. */
+function describeCommand(args) {
+	const parts = ['mnemonad', args.command];
+	if (args.streamId) parts.push(args.streamId);
+	if (args.path) parts.push(args.path);
+	return parts.join(' ');
+}
+
+/**
+ * The CLI half of `--passkey`: opens the explorer's `/cli-auth` page in the system browser
+ * to run the WebAuthn ceremony there (this process has no `navigator.credentials` — passkeys
+ * only exist in a browser), then relays every signing request to that tab for the rest of
+ * this command. The raw key never enters this process, only signatures do — see
+ * docs/wallet/passkey-accounts.md's CLI section for why it has to be that domain specifically
+ * (rp.id) and why this is a one-shot-per-command bridge rather than something that persists
+ * across separate CLI invocations.
+ *
+ * @param {Object} args - parsed CLI args: `authOrigin` (the explorer deployment to open, e.g.
+ *   https://mnemonad.vercel.app), plus `command`/`streamId`/`path` to build the one-line
+ *   description the page shows while it waits.
+ * @returns {Promise<Object>} a viem Account whose signMessage/signTransaction proxy to the tab
+ */
+export async function openPasskeyBridge(args) {
+	if (active) return active.account;
+
+	const token = randomBytes(24).toString('hex');
+	// Read by /ping below — the one thing the page can't get from the WS (it doesn't exist
+	// yet at that point, see docs/wallet/passkey-accounts.md's CLI section) but still wants
+	// live: how much of the connect-timeout is actually left, and confirmation the CLI is
+	// still there at all.
+	const deadlineAt = Date.now() + CONNECT_TIMEOUT_MS;
+	const httpServer = createServer((req, res) => {
+		const url = new URL(req.url, 'http://127.0.0.1');
+		if (url.pathname === '/ping' && url.searchParams.get('token') === token) {
+			res.writeHead(200, {
+				'Content-Type': 'application/json',
+				// The page is served from the explorer's own origin, not this loopback one —
+				// an ordinary fetch() response is otherwise unreadable cross-origin. The token
+				// above is what actually gates this, same as the WS connection itself; the
+				// wildcard just matches that (no meaningful "origin" to restrict to when the
+				// caller could be any explorer deployment this token was ever handed to).
+				'Access-Control-Allow-Origin': '*',
+			});
+			res.end(JSON.stringify({ ttl: Math.max(0, Math.round((deadlineAt - Date.now()) / 1000)) }));
+			return;
+		}
+		res.writeHead(404);
+		res.end();
+	});
+	const wss = new WebSocketServer({ server: httpServer });
+
+	await new Promise((resolve, reject) => {
+		httpServer.once('error', reject);
+		httpServer.listen(0, '127.0.0.1', resolve);
+	});
+	const port = httpServer.address().port;
+
+	const pending = new Map();
+	let nextId = 1;
+	let socket = null;
+
+	const connected = new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			// Nothing ever reached the point (below) that assigns `active`, so
+			// closePasskeyBridge() has nothing to close on this path — without this, the
+			// server/socket this function opened above would sit open forever, and the CLI
+			// process would hang right after printing the error below rather than exiting.
+			wss.close();
+			httpServer.close();
+			reject(userError(
+				'Timed out waiting for the browser passkey sign-in. Complete the prompt in the\n' +
+				'  tab that opened, or re-run with --passkey to try again.'
+			));
+		}, CONNECT_TIMEOUT_MS);
+
+		wss.on('connection', (ws, req) => {
+			const url = new URL(req.url, 'http://127.0.0.1');
+			if (url.searchParams.get('token') !== token) {
+				ws.close(4001, 'bad token');
+				return;
+			}
+			socket = ws;
+
+			ws.on('message', (raw) => {
+				let msg;
+				try {
+					msg = JSON.parse(raw.toString());
+				} catch {
+					return;
+				}
+				if (msg.type === 'hello') {
+					clearTimeout(timer);
+					resolve(msg.address);
+				} else if (msg.type === 'sign-result' || msg.type === 'sign-error') {
+					const p = pending.get(msg.id);
+					if (!p) return;
+					pending.delete(msg.id);
+					if (msg.type === 'sign-result') p.resolve(msg.result);
+					else p.reject(new Error(msg.error || 'signing failed'));
+				}
+			});
+
+			ws.on('close', () => {
+				if (socket === ws) socket = null;
+				for (const p of pending.values()) p.reject(userError('Browser tab disconnected before signing finished.'));
+				pending.clear();
+			});
+		});
+	});
+
+	const desc = describeCommand(args);
+	const ttl = Math.floor(CONNECT_TIMEOUT_MS / 1000);
+	// Lets the result screen turn a stream id in its summary line into a link to the
+	// explorer's own stream page — only for a real deployment id (testnet/mainnet); --chain
+	// local has no explorer route to link to, so the page just falls back to plain text.
+	const network = args.chain === 'testnet' || args.chain === 'mainnet' ? `&network=${args.chain}` : '';
+	const authUrl = `${args.authOrigin.replace(/\/$/, '')}/cli-auth?port=${port}&token=${token}&desc=${encodeURIComponent(desc)}&ttl=${ttl}${network}`;
+	console.log('  opening', authUrl, 'to sign in with a passkey...');
+	try {
+		await open(authUrl);
+	} catch {
+		console.log('  could not open a browser automatically — open this URL yourself:', authUrl);
+	}
+
+	const address = await connected;
+	console.log('  connected:', address);
+
+	function request(type, payload) {
+		if (!socket) {
+			return Promise.reject(userError('Browser tab disconnected. Re-run with --passkey to reconnect.'));
+		}
+		return new Promise((resolve, reject) => {
+			const id = nextId++;
+			pending.set(id, { resolve, reject });
+			socket.send(JSON.stringify({ type, id, ...payload }));
+		});
+	}
+
+	const account = toAccount({
+		address,
+		async signMessage({ message }) {
+			return request('sign-message', { message });
+		},
+		async signTransaction(transaction) {
+			return request('sign-transaction', { transaction: encodeForBridge(transaction) });
+		},
+		async signTypedData() {
+			// Not used anywhere in this codebase (personal_sign only — see the "Wallet-signature
+			// encryption keys" plan's locked-in decision) — a real relay implementation would
+			// need the same BigInt-safe encoding sign-transaction already has, not worth building
+			// for a path nothing calls.
+			throw userError('Signing typed data is not supported over --passkey.');
+		},
+	});
+
+	active = { wss, httpServer, account };
+	return account;
+}
+
+/**
+ * Called once, at the very end of the CLI's command dispatch (bin/mnemonad.js), whether the
+ * command succeeded or failed — a no-op when --passkey was never used. Tells the browser tab
+ * it's done so it can end its session and zero the key, mirroring the explorer's own
+ * disconnect() lifecycle instead of just abandoning the connection.
+ *
+ * `result` lets the tab show something more useful than a bare "done" before it closes —
+ * whether the command actually succeeded, and the one line of output that says what
+ * happened (bin/mnemonad.js captures its own last console.log line for this rather than
+ * every command needing to return a summary explicitly).
+ *
+ * @param {{ok: boolean, summary: string}} [result]
+ */
+export function closePasskeyBridge(result) {
+	if (!active) return;
+	const { wss, httpServer } = active;
+	active = null;
+	const payload = JSON.stringify({ type: 'done', ok: result?.ok ?? true, summary: result?.summary || '' });
+	for (const ws of wss.clients) {
+		try {
+			ws.send(payload);
+		} catch {
+			// Nothing to tell a socket that's already gone.
+		}
+		ws.close();
+	}
+	wss.close();
+	httpServer.close();
+}