@ai-wayfinding/client 0.1.1 → 0.1.2

package/README.md

@@ -4,21 +4,24 @@ The `wayfinding` command gives an agent access to one encrypted journey after a
 
 ## Install
 
-Node.js 22 or newer is required. Download both packages from the [latest release](https://github.com/AI-Wayfinding/journey/releases/latest), then install them together:
+Node.js 22 or newer is required. Install from npm:
 
 ```sh
-R=https://github.com/AI-Wayfinding/journey/releases/latest/download
-curl -fsSLO "$R/ai-wayfinding-core.tgz"
-curl -fsSLO "$R/ai-wayfinding-client.tgz"
-npm install -g ./ai-wayfinding-core.tgz ./ai-wayfinding-client.tgz
+npm install -g @ai-wayfinding/client
 wayfinding --help
 ```
 
-Downloading first works even where npm is set to refuse installs from a URL.
+If your system does not allow a global install, install to a folder you control:
+
+```sh
+npm install -g --prefix "$HOME/.npm-global" @ai-wayfinding/client
+export PATH="$HOME/.npm-global/bin:$PATH"
+wayfinding --help
+```
 
 ### Build from this repository
 
-The packages are not on npm. From a clone of this repository:
+From a clone of this repository:
 
 ```sh
 npm ci
@@ -26,12 +29,12 @@ npm run build -w packages/core
 npm run build -w packages/client
 npm pack -w packages/core
 npm pack -w packages/client
-# Install both local tarballs together. The client needs the unpublished core package.
+# Install both local tarballs together.
 npm install -g ./ai-wayfinding-core-*.tgz ./ai-wayfinding-client-*.tgz
 wayfinding --help
 ```
 
-If a global install is not wanted, run `node packages/client/dist/cli.js --help` from the clone after building. A GitHub URL is not a reliable npm install target for one package inside this workspace; installing the root does not install the client binary. The two local tarballs are the supported install path for now. The client uses the MCP SDK version 1.30.1; no other direct runtime dependency is added.
+If a global install is not wanted, run `node packages/client/dist/cli.js --help` from the clone after building. A GitHub URL is not a reliable npm install target for one package inside this workspace; installing the root does not install the client binary.
 
 ## Connect to a journey
 
@@ -40,9 +43,23 @@ wayfinding connect <journey-id> --scope read
 wayfinding connect <journey-id> --scope readwrite --remember
 ```
 
-The journey server defaults to `https://app.wayfinding.support`; use `--server https://your-server` if needed. The command creates a new age encryption identity and signing key **in memory**, asks the server for approval, and prints a link and a six-digit code. Open the link in your browser, check that the code matches, choose the approved access and time, then confirm with your passkey. The command waits until approval, expiry, or lockout. Approval is valid for at most 8 hours without remembering, or 90 days when remembered. The person must choose remembered access in the approval screen before keys are saved; the client refuses expired keys.
+The journey server defaults to `https://app.wayfinding.support`; use `--server https://your-server` if needed. The single-process command creates a new age encryption identity and signing key **in memory**, asks the server for approval, and prints a link and a six-digit code. Open the link in your browser, check that the code matches, choose the approved access and time, then confirm with your passkey. The command waits until approval, expiry, or lockout. Approval is valid for at most 8 hours without remembering, or 90 days when remembered. The person must choose remembered access in the approval screen before keys are saved; the client refuses expired keys.
+
+Without `--remember`, the one-shot `connect` command does not save keys. It closes the connection when it exits. Start `wayfinding mcp --connect <journey-id>` to keep an in-memory connection for that MCP process, or pass `--journey <journey-id>` to an individual CLI command to ask for fresh approval on each invocation. There is no background daemon or invisible persistent login.
 
-Without `--remember`, the one-shot `connect` command does not save keys. It closes the connection when it exits. Start `wayfinding mcp --connect <journey-id>` to keep an in-memory connection for that MCP process, or pass `--journey <journey-id>` to an individual CLI command to ask for fresh approval on each invocation. There is no background daemon and no invisible persistent login.
+### Connect when each command runs in a fresh process
+
+```sh
+wayfinding connect YOUR_JOURNEY_ID --scope read --name "Research assistant" --state "$HOME/wayfinding-agent.json" --no-wait
+# Open the printed link in a browser and approve after checking the six-digit code.
+wayfinding connect --state "$HOME/wayfinding-agent.json" --wait --timeout 600
+wayfinding list --state "$HOME/wayfinding-agent.json"
+wayfinding mcp --state "$HOME/wayfinding-agent.json"
+```
+
+`--no-wait` creates a pending request, writes its keys, request ID, server and expiry to a **0600** state file, then prints the link and code and exits. It refuses an existing file (especially one without private permissions). `--wait` uses that file to poll and can be safely retried after a timeout; it becomes an approved session file after approval. The file expires with the approved session, never later than eight hours after creation. Expired files are deleted and refused. Keep the file private; it contains unencrypted keys. Delete it when finished. This is separate from `--remember`, which still uses the keychain or an encrypted key folder. Use `--state FILE` on `add`, `import`, `list`, `search`, `show`, `comment`, `comments`, `status`, or `mcp`.
+
+Pass `--json` on either connect step to print a single JSON object with `link`, `code`, `requestId`, `expiresAt` (ISO 8601), and `status`. Exit status **0** means the request was created or access was approved; **2** means approval is still pending after `--wait` times out; **3** means expired; **4** means denied or locked out; **5** means the server or proxy cannot be reached. Other errors use exit status 1. The client automatically uses `HTTPS_PROXY`, `https_proxy`, or `HTTP_PROXY` when set. If a connection fails, it reports the underlying cause and advises checking the proxy or asking the workspace admin to allow `app.wayfinding.support`.
 
 With `--remember`, agent keys go to macOS Keychain (`security`) or Linux Secret Service (`secret-tool`). Unlock/install that service first. If the OS keychain is unavailable or the platform is unsupported, the command refuses instead of storing unencrypted keys. Windows users can use `--key-folder <path>` with a passphrase; there is no Windows Credential Manager adapter. On every OS, `--key-folder <path> --remember` stores an age-passphrase-encrypted `agent.age` in a private folder (0700 folder, 0600 file on Unix). Set `WAYFINDING_PASSPHRASE` or enter it at the terminal when prompted; the passphrase is never stored. Do not choose a shared folder.
 
@@ -64,11 +81,11 @@ wayfinding comments <item-id>
 
 Markdown imports retain simple front matter fields `title`, `type` (or `itemType`), `tags` (comma-separated or inline array), `created`, `resourceKind`, and `sharedFrom`; the remaining Markdown is the body. Files must have `.md` extensions. The agent is always marked as the author, regardless of input front matter. For a directory, Markdown files are read recursively.
 
-Each read checks the full signed journey membership log. Before a write, the client checks that log again, confirms this agent is still an active read-write member and that its version meets the journey minimum, then encrypts the item or comment locally. Server requests are signed with the method, path and query, body digest, timestamp, and fresh nonce. If access ends, the client says so and stops. Keys and decrypted items remain in memory for the process lifetime.
+Each read checks the full signed journey membership log. Before a write, the client checks that log again, confirms this agent is still an active read-write member and that its version meets the journey minimum, then encrypts the item or comment locally. Server requests are signed with the method, path and query, body digest, timestamp, and fresh nonce. If access ends, the client says so and stops. Decrypted items remain in memory for the process lifetime; keys are also stored in a file only when you explicitly use `--state`.
 
 ### Optional encrypted-data cache
 
-A remembered session uses a local cache by default. An in-memory connection uses no cache by default. Pass `--cache` to enable it for a one-shot command or `--no-cache` to disable it. Under the OS cache directory (macOS: `~/Library/Caches`; Linux: `$XDG_CACHE_HOME` or `~/.cache`; Windows: `%LOCALAPPDATA%`), the client stores **only ciphertext envelopes and the head of a freshly verified signed log**. The journey key, secret signing key, item titles, and item bodies never go to this cache. On Unix, cache folders are 0700 and files 0600. The client refreshes records by sequence number but verifies the full signed log again before every use. Disable the cache on a shared device.
+A remembered session uses a local cache by default. An in-memory connection uses no cache by default. Pass `--cache` to enable it for a one-shot command or `--no-cache` to disable it. Under the OS cache directory (macOS: `~/Library/Caches`; Linux: `$XDG_CACHE_HOME` or `~/.cache`; Windows: `%LOCALAPPDATA%`), the client stores **only ciphertext envelopes and the head of a freshly verified signed log**. The journey key, secret signing key, item titles, and item bodies never go to this cache. A `--state` file, when requested, is separate from this encrypted-data cache. On Unix, cache folders are 0700 and files 0600. The client refreshes records by sequence number but verifies the full signed log again before every use. Disable the cache on a shared device.
 
 ## Connect an MCP tool host
 
@@ -85,6 +102,19 @@ The MCP server exposes `add`, `import`, `list`, `search`, `show`, `comment`, `co
 }
 ```
 
-For Claude Desktop, add the `mcpServers.wayfinding` entry to its MCP configuration. For Claude Code, use `claude mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. For Codex, use `codex mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. Use the absolute path to the built `cli.js` with `node` if `wayfinding` is not on the host's PATH. When the MCP process begins, the person sees the link and code in the host's standard-error log; approve it before the MCP connection finishes. Some hosts hide stderr: run `wayfinding connect <journey-id> --remember` in a terminal first, then configure `wayfinding mcp` without `--connect`.
+For Claude Desktop, after completing the two-step file-backed connection above, add this local MCP server to `claude_desktop_config.json` (replace the path with your private state file):
+
+```json
+{
+  "mcpServers": {
+    "wayfinding": {
+      "command": "wayfinding",
+      "args": ["mcp", "--state", "/absolute/path/to/wayfinding-agent.json"]
+    }
+  }
+}
+```
+
+The earlier `--connect` example instead asks for approval when MCP starts. For Claude Code, use `claude mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. For Codex, use `codex mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. Use the absolute path to the built `cli.js` with `node` if `wayfinding` is not on the host's PATH. When the MCP process begins, the person sees the link and code in the host's standard-error log; approve it before the MCP connection finishes. Some hosts hide stderr: run `wayfinding connect <journey-id> --remember` in a terminal first, then configure `wayfinding mcp` without `--connect`.
 
 The person manages other members and any key rotation in the browser. An agent cannot approve itself, change someone's scope, add or remove members, or rotate journey keys. If the person previously rotated the journey key, the current approval API may not provide this agent the old epoch wraps needed to verify *all* earlier history; this client stops with a missing-key message rather than writing without verification.

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { homedir } from 'node:os';
 import { stdin, stderr } from 'node:process';
 import { join } from 'node:path';
-import { connectJourney } from './connection.js';
+import { connectJourney, requestConnection, resumeConnection } from './connection.js';
+import { ExpiredStateError, loadState } from './state.js';
 import { importMarkdown } from './import.js';
 import { JourneyClient } from './journey.js';
 import { runMcp } from './mcp.js';
@@ -10,6 +11,8 @@ import { forgetRemembered, loadRemembered } from './storage.js';
 const help = `wayfinding — read and write an approved journey
 
 wayfinding connect <journey-id> [--name "Agent name"] [--scope read|readwrite] [--remember] [--server https://app.wayfinding.support] [--key-folder PATH]
+wayfinding connect <journey-id> --state FILE --no-wait [--json]
+wayfinding connect --state FILE --wait [--timeout SECONDS] [--json]
 wayfinding disconnect [--key-folder PATH]
 wayfinding add --type TYPE --title TITLE --body TEXT [--tags a,b]
 wayfinding import <file-or-folder>
@@ -21,11 +24,12 @@ wayfinding comments <id>
 wayfinding status
 wayfinding mcp [--connect <journey-id>] [--name "Agent name"]
 
+Use --state FILE with commands or mcp to use an approved file-backed session.
 Use --journey <journey-id> with any one-shot command to ask for approval each time without remembering keys.
 Use --cache to store only encrypted journey records and a verified log head; --no-cache turns it off.
 Keys never go into the local cache. An agent cannot change journey membership or access.`;
-const valueFlags = new Set(['--scope', '--name', '--server', '--key-folder', '--journey', '--connect', '--type', '--title', '--body', '--tags']);
-const boolFlags = new Set(['--remember', '--cache', '--no-cache', '--help']);
+const valueFlags = new Set(['--scope', '--name', '--server', '--key-folder', '--journey', '--connect', '--type', '--title', '--body', '--tags', '--state', '--timeout']);
+const boolFlags = new Set(['--remember', '--cache', '--no-cache', '--help', '--no-wait', '--wait', '--json']);
 function parse(args) {
     const command = args[0] ?? '--help', flags = {}, positional = [];
     for (let index = 1; index < args.length; index++) {
@@ -45,6 +49,15 @@ function parse(args) {
     return { command, positional, flags };
 }
 function flag(flags, key) { return typeof flags[key] === 'string' ? flags[key] : undefined; }
+function reportConnect(state, status, json) {
+    const result = { link: state.link, code: state.code, requestId: state.status === 'pending' ? state.sessionId : state.session.sessionId, expiresAt: new Date(state.expiresAt).toISOString(), status };
+    if (json)
+        console.log(JSON.stringify(result));
+    else if (status === 'pending')
+        console.log('Open this link, check the code matches, and approve access to this journey: ' + result.link + '\nSix-digit code: ' + result.code);
+    else if (status === 'approved')
+        console.log('Journey access was approved. The keys are stored in your state file.');
+}
 async function passphrase(folder) {
     if (!folder)
         return undefined;
@@ -113,11 +126,42 @@ export async function main(args = process.argv.slice(2)) {
     const server = flag(flags, '--server'), scope = flag(flags, '--scope');
     if (scope && scope !== 'read' && scope !== 'readwrite')
         throw new Error('Use --scope read or --scope readwrite.');
+    const statePath = flag(flags, '--state');
     const connect = async (journeyId, mcp = false) => connectJourney(journeyId, { server, scope: scope, name: flag(flags, '--name'), remember: !!flags['--remember'], keyFolder, passphrase: secret, onApproval: (url, code) => { (mcp ? console.error : console.log)('Open this link, check the code matches, and approve access to this journey: ' + url + '\nSix-digit code: ' + code); } });
     if (command === 'connect') {
-        const journeyId = positional[0];
-        if (!journeyId)
-            throw new Error('Give the journey ID to connect.');
+        const journeyId = positional[0], json = !!flags['--json'];
+        if (flags['--no-wait']) {
+            if (!journeyId || !statePath || flags['--wait'] || flags['--remember'])
+                throw new Error('Use connect <journey-id> --state FILE --no-wait without --remember.');
+            reportConnect(await requestConnection(journeyId, { server, scope: scope, name: flag(flags, '--name'), state: statePath }), 'pending', json);
+            return;
+        }
+        if (flags['--wait']) {
+            if (journeyId || !statePath || flags['--remember'] || server || scope || flags['--name'])
+                throw new Error('Use connect --state FILE --wait [--timeout SECONDS].');
+            const timeout = flag(flags, '--timeout') ?? '600';
+            if (!/^[0-9]+$/.test(timeout) || !Number.isSafeInteger(Number(timeout)) || Number(timeout) < 1)
+                throw new Error('--timeout must be a positive number of seconds.');
+            let state;
+            try {
+                state = await loadState(statePath);
+                const { client } = await resumeConnection(statePath, { timeoutMs: Number(timeout) * 1000 });
+                client.close();
+                reportConnect(await loadState(statePath), 'approved', json);
+            }
+            catch (error) {
+                if (json && error instanceof Error && 'exitCode' in error) {
+                    const status = error.exitCode === 2 ? 'pending' : error.exitCode === 3 ? 'expired' : error.exitCode === 4 ? error.message.includes('wrong approval codes') ? 'locked' : 'denied' : state?.status;
+                    const reportState = state ?? (error instanceof ExpiredStateError ? error.state : undefined);
+                    if (reportState && status)
+                        reportConnect(reportState, status, true);
+                }
+                throw error;
+            }
+            return;
+        }
+        if (!journeyId || flags['--timeout'] || statePath || json)
+            throw new Error('Give the journey ID to connect, or use --state FILE --no-wait / --wait.');
         const { client } = await connect(journeyId);
         client.close();
         console.log(flags['--remember'] ? 'This journey is connected and the keys are remembered.' : 'Journey access was approved. No keys were saved; use wayfinding mcp --connect <journey-id> for an in-memory agent session, or --journey on each command.');
@@ -128,20 +172,27 @@ export async function main(args = process.argv.slice(2)) {
         if (held)
             return held;
         const oneShot = command === 'mcp' ? flag(flags, '--connect') : flag(flags, '--journey');
-        if (oneShot) {
+        if (statePath && (oneShot || keyFolder))
+            throw new Error('Use --state instead of --connect, --journey or --key-folder.');
+        if (statePath) {
+            const state = await loadState(statePath);
+            if (state.status !== 'approved')
+                throw new Error('This journey is still pending approval. Run connect --state FILE --wait first.');
+            held = new JourneyClient(state.session, flags['--cache'] && !flags['--no-cache'] ? { cacheRoot: cacheFolder() } : {});
+        }
+        else if (oneShot) {
             held = (await connect(oneShot, command === 'mcp')).client;
         }
         else {
             const session = await loadRemembered({ folder: keyFolder, passphrase: secret });
             if (!session)
-                throw new Error('No remembered journey connection. Use wayfinding connect <journey-id> --remember, or --journey <journey-id> to ask for approval for this command. For an in-memory MCP session, use wayfinding mcp --connect <journey-id>.');
+                throw new Error('No remembered journey connection. Use wayfinding connect <journey-id> --remember, --state FILE for an approved file, or --journey <journey-id> to ask for approval for this command.');
             held = new JourneyClient(session, flags['--no-cache'] ? {} : { cacheRoot: cacheFolder() });
         }
-        if ((flags['--cache'] || flags['--no-cache']) && held) {
-            // Cache is chosen when the client is constructed; ephemeral sessions default to no cache.
-            if (flags['--cache'] && oneShot)
+        if ((flags['--cache'] || flags['--no-cache']) && oneShot && held) {
+            if (flags['--cache'])
                 held = new JourneyClient(held.session, { cacheRoot: cacheFolder() });
-            if (flags['--no-cache'] && oneShot)
+            if (flags['--no-cache'])
                 held = new JourneyClient(held.session);
         }
         return held;
@@ -200,4 +251,4 @@ export async function main(args = process.argv.slice(2)) {
         held?.close();
     }
 }
-main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = error && typeof error.exitCode === 'number' ? error.exitCode : 1; });

package/dist/connection.d.ts

@@ -1,4 +1,5 @@
 import { JourneyClient } from './journey.js';
+import type { PendingState } from './state.js';
 import type { RememberedAgent } from './storage.js';
 export interface ConnectOptions {
     server?: string;
@@ -9,6 +10,8 @@ export interface ConnectOptions {
     passphrase?: string;
     fetch?: typeof fetch;
     pollMs?: number;
+    timeoutMs?: number;
+    state?: string;
     onApproval?: (url: string, code: string) => void;
 }
 export interface Connection {
@@ -16,4 +19,10 @@ export interface Connection {
     session: RememberedAgent;
 }
 export declare const DEFAULT_SERVER = "https://app.wayfinding.support";
+export declare class PendingApprovalError extends Error {
+    readonly exitCode = 2;
+}
+export declare function requestConnection(journeyId: string, options?: ConnectOptions): Promise<PendingState>;
+export declare function waitForApproval(pending: PendingState, options?: ConnectOptions): Promise<Connection>;
 export declare function connectJourney(journeyId: string, options?: ConnectOptions): Promise<Connection>;
+export declare function resumeConnection(path: string, options?: ConnectOptions): Promise<Connection>;

package/dist/connection.js

@@ -1,41 +1,98 @@
 import { createAgeIdentity, createSigningIdentity, validAgentName } from '@ai-wayfinding/core';
+import { rm } from 'node:fs/promises';
 import { JourneyClient } from './journey.js';
+import { networkFetch } from './network.js';
+import { DeniedStateError, ExpiredStateError, ensureNewStatePath, loadState, saveState } from './state.js';
 import { saveRemembered } from './storage.js';
 export const DEFAULT_SERVER = 'https://app.wayfinding.support';
 const sleep = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));
-export async function connectJourney(journeyId, options = {}) {
+export class PendingApprovalError extends Error {
+    exitCode = 2;
+}
+export async function requestConnection(journeyId, options = {}) {
     const server = (options.server ?? DEFAULT_SERVER).replace(/\/$/, '');
     const origin = new URL(server);
     if (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && (origin.hostname === 'localhost' || origin.hostname === '127.0.0.1')))
         throw new Error('The journey server must use HTTPS (except on this computer).');
     if (options.keyFolder && !options.remember)
         throw new Error('--key-folder needs --remember.');
+    if (options.state && options.remember)
+        throw new Error('Use either --state or --remember, not both.');
     if (options.name !== undefined && !validAgentName(options.name))
         throw new Error('Agent name must be trimmed, 1–60 characters and contain no control characters.');
+    if (options.state)
+        await ensureNewStatePath(options.state);
     const identity = await createAgeIdentity(), signing = await createSigningIdentity();
-    const response = await (options.fetch ?? fetch)(server + '/v1/agent-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', Origin: origin.origin, 'X-Wayfinding': '1' }, body: JSON.stringify({ journeyId, agentPublicKey: { recipient: identity.recipient, signingKey: signing.publicKey }, requestedScope: options.scope ?? 'read', remembered: options.remember === true, ...(options.name === undefined ? {} : { name: options.name }) }) });
+    const response = await (options.fetch ?? networkFetch)(server + '/v1/agent-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', Origin: origin.origin, 'X-Wayfinding': '1' }, body: JSON.stringify({ journeyId, agentPublicKey: { recipient: identity.recipient, signingKey: signing.publicKey }, requestedScope: options.scope ?? 'read', remembered: options.remember === true, keyStorage: options.state ? 'file' : 'memory', ...(options.name === undefined ? {} : { name: options.name }) }) });
     if (!response.ok)
         throw new Error('Could not ask to join this journey (' + response.status + ').');
     const created = await response.json();
+    const createdAt = Date.now();
+    const pending = { status: 'pending', server, journeyId, sessionId: created.id, identity: identity.identity, recipient: identity.recipient, signingPrivateKey: signing.privateKey, signingKey: signing.publicKey, requestedScope: options.scope ?? 'read', link: created.approvalUrl, code: created.code, createdAt, expiresAt: createdAt + 600_000 };
+    if (options.state)
+        await saveState(options.state, pending, true);
     options.onApproval?.(created.approvalUrl, created.code);
-    let approved;
+    return pending;
+}
+export async function waitForApproval(pending, options = {}) {
+    const fetcher = options.fetch ?? networkFetch;
+    const deadline = Date.now() + (options.timeoutMs ?? 600_000);
     for (;;) {
-        await sleep(options.pollMs ?? 3000);
-        const polled = await (options.fetch ?? fetch)(server + '/v1/agent-sessions/' + encodeURIComponent(created.id));
+        if (pending.expiresAt <= Date.now()) {
+            if (options.state)
+                await rm(options.state, { force: true });
+            throw new ExpiredStateError('Journey approval expired. Connect again.');
+        }
+        if (Date.now() >= deadline)
+            throw new PendingApprovalError('Journey approval is still pending. Run connect --state <file> --wait again.');
+        const polled = await fetcher(pending.server + '/v1/agent-sessions/' + encodeURIComponent(pending.sessionId));
         if (!polled.ok)
             throw new Error('Could not check journey approval (' + polled.status + ').');
-        approved = await polled.json();
-        if (approved.status === 'approved')
-            break;
-        if (approved.status !== 'pending')
-            throw new Error(approved.status === 'locked' ? 'Too many wrong approval codes. Ask for a new journey connection.' : 'Journey approval expired or was refused. Connect again.');
+        const approved = await polled.json();
+        if (approved.status === 'pending') {
+            await sleep(Math.min(options.pollMs ?? 3000, deadline - Date.now(), pending.expiresAt - Date.now()));
+            continue;
+        }
+        if (approved.status === 'expired') {
+            if (options.state)
+                await rm(options.state, { force: true });
+            throw new ExpiredStateError('Journey approval expired. Connect again.');
+        }
+        if (approved.status !== 'approved')
+            throw new DeniedStateError(approved.status === 'locked' ? 'Too many wrong approval codes. Ask for a new journey connection.' : 'Journey approval was refused. Connect again.');
+        if (approved.journeyId !== pending.journeyId || approved.recipient !== pending.recipient || approved.signingKey !== pending.signingKey || approved.requestedScope !== pending.requestedScope)
+            throw new Error('Journey approval does not match this agent. Connect again.');
+        if (options.remember && !approved.remembered)
+            throw new Error('The person did not approve remembered journey access.');
+        if (!Number.isFinite(approved.expiresAt) || approved.expiresAt <= Date.now() || approved.expiresAt > Date.now() + (options.remember ? 90 * 86_400_000 : 8 * 3_600_000) + 60_000 || approved.scope !== 'read' && approved.scope !== 'readwrite')
+            throw new Error('Invalid journey access expiry or scope. Connect again.');
+        const expiresAt = options.state ? Math.min(approved.expiresAt, pending.createdAt + 8 * 3_600_000) : approved.expiresAt;
+        const session = { server: pending.server, journeyId: pending.journeyId, sessionId: pending.sessionId, principal: approved.principal, identity: pending.identity, recipient: pending.recipient, signingPrivateKey: pending.signingPrivateKey, signingKey: pending.signingKey, scope: approved.scope, expiresAt };
+        const client = new JourneyClient(session, { fetch: options.fetch });
+        try {
+            await client.status();
+        }
+        catch (error) {
+            client.close();
+            throw error;
+        }
+        if (options.remember) {
+            const store = options.keyFolder ? { folder: options.keyFolder, passphrase: options.passphrase } : {};
+            await saveRemembered(session, store);
+        }
+        if (options.state)
+            await saveState(options.state, { status: 'approved', session, createdAt: pending.createdAt, expiresAt, link: pending.link, code: pending.code });
+        return { client, session };
     }
-    if (options.remember && !approved.remembered)
-        throw new Error('The person did not approve remembered journey access.');
-    if (!Number.isFinite(approved.expiresAt) || approved.expiresAt <= Date.now() || approved.expiresAt > Date.now() + (options.remember ? 90 * 86_400_000 : 8 * 3_600_000) + 60_000)
-        throw new Error('Invalid journey access expiry. Connect again.');
-    const session = { server, journeyId, sessionId: created.id, principal: approved.principal, identity: identity.identity, recipient: identity.recipient, signingPrivateKey: signing.privateKey, signingKey: signing.publicKey, scope: approved.scope, expiresAt: approved.expiresAt };
-    const client = new JourneyClient(session, { fetch: options.fetch });
+}
+export async function connectJourney(journeyId, options = {}) {
+    return waitForApproval(await requestConnection(journeyId, options), options);
+}
+export async function resumeConnection(path, options = {}) {
+    const state = await loadState(path);
+    if (state.status === 'pending')
+        return waitForApproval(state, { ...options, state: path });
+    const client = new JourneyClient(state.session, { fetch: options.fetch });
     try {
         await client.status();
     }
@@ -43,9 +100,5 @@ export async function connectJourney(journeyId, options = {}) {
         client.close();
         throw error;
     }
-    if (options.remember) {
-        const store = options.keyFolder ? { folder: options.keyFolder, passphrase: options.passphrase } : {};
-        await saveRemembered(session, store);
-    }
-    return { client, session };
+    return { client, session: state.session };
 }

package/dist/journey.js

@@ -1,7 +1,9 @@
 import { CLIENT_VERSION, meetsMinClientVersion, newId, open, parseRecord, seal, unwrapJourneyKey, verifyLog } from '@ai-wayfinding/core';
 import { readCache, writeCache } from './cache.js';
 import { signedHeaders } from './signing.js';
+import { networkFetch } from './network.js';
 const historyError = 'This journey history could not be verified. Stop and ask a member for help.';
+const updateError = () => `This journey uses a newer format than this Wayfinding client (${CLIENT_VERSION}) understands. Nothing is wrong with the journey or your access. Update the client, then try again:\n  npm install -g @ai-wayfinding/client@latest\n(If you installed it with --prefix "$HOME/.npm-global", add that same --prefix.) Your connection stays valid, so you do not need to connect or be approved again.\nIf you cannot install software here, stop and tell your operator (the person you work for) that the Wayfinding client needs updating, show them the command above, and ask them to run it or allow the update.`;
 function decode(value) { return JSON.parse(Buffer.from(value, 'base64url').toString('utf8')); }
 export class JourneyClient {
     session;
@@ -11,7 +13,7 @@ export class JourneyClient {
     constructor(session, options = {}) {
         this.session = session;
         this.options = options;
-        this.fetcher = options.fetch ?? fetch;
+        this.fetcher = options.fetch ?? networkFetch;
     }
     async request(path, method = 'GET', data) {
         if (this.session.expiresAt <= Date.now())
@@ -69,13 +71,15 @@ export class JourneyClient {
             entries.push(entry);
         }
         const checked = await verifyLog(entries);
+        if (!checked.ok && checked.error.code === 'client-too-old')
+            throw new Error(updateError());
         if (!checked.ok || checked.state.journey !== this.session.journeyId)
             throw new Error(historyError);
         const mine = checked.state.members[this.session.principal]?.member;
         if (!mine || mine.kind !== 'agent' || mine.signingKey !== this.session.signingKey || mine.recipient !== this.session.recipient || mine.expiresAt && Date.parse(mine.expiresAt) <= Date.now())
             throw new Error('Access to this journey has ended');
         if (!meetsMinClientVersion(CLIENT_VERSION, checked.state.minClientVersion))
-            throw new Error('This journey needs a newer client version. Update wayfinding before writing.');
+            throw new Error(updateError());
         if (!epochs.has(checked.state.currentEpoch))
             throw new Error('The journey key changed. Ask a member to reconnect this agent.');
         if (this.options.cacheRoot && (!cached || cached.seq !== checked.state.lastSeq || cached.hash !== checked.state.lastHash))

package/dist/network.d.ts

@@ -0,0 +1,5 @@
+export declare function proxyConfigured(): boolean;
+export declare class NetworkError extends Error {
+    readonly exitCode = 5;
+}
+export declare const networkFetch: typeof fetch;

package/dist/network.js

@@ -0,0 +1,35 @@
+import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
+let configured = false;
+export function proxyConfigured() {
+    return Boolean(process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY);
+}
+export class NetworkError extends Error {
+    exitCode = 5;
+}
+export const networkFetch = async (input, init) => {
+    if (!configured) {
+        if (proxyConfigured())
+            setGlobalDispatcher(new EnvHttpProxyAgent({
+                httpsProxy: process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY,
+            }));
+        configured = true;
+    }
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        let cause = error;
+        const details = [];
+        for (let i = 0; i < 4 && cause instanceof Error; i++) {
+            const code = cause.code;
+            const message = cause.message;
+            if (code || (message && message !== 'fetch failed'))
+                details.push([code, message].filter(Boolean).join(': '));
+            cause = cause.cause;
+        }
+        const hint = proxyConfigured()
+            ? 'Check the configured proxy; your workspace admin may need to allow app.wayfinding.support.'
+            : 'If the host is unreachable, your workspace admin may need to allow app.wayfinding.support.';
+        throw new NetworkError('Could not reach the journey server (' + (details.join('; ') || 'network error') + '). ' + hint, { cause: error });
+    }
+};

package/dist/state.d.ts

@@ -0,0 +1,36 @@
+import type { RememberedAgent } from './storage.js';
+export interface PendingState {
+    status: 'pending';
+    server: string;
+    journeyId: string;
+    sessionId: string;
+    identity: string;
+    recipient: string;
+    signingPrivateKey: string;
+    signingKey: string;
+    requestedScope: 'read' | 'readwrite';
+    link: string;
+    code: string;
+    expiresAt: number;
+    createdAt: number;
+}
+export interface ApprovedState {
+    status: 'approved';
+    session: RememberedAgent;
+    link: string;
+    code: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export type AgentState = PendingState | ApprovedState;
+export declare class ExpiredStateError extends Error {
+    readonly state?: AgentState | undefined;
+    readonly exitCode = 3;
+    constructor(message: string, state?: AgentState | undefined);
+}
+export declare class DeniedStateError extends Error {
+    readonly exitCode = 4;
+}
+export declare function loadState(path: string): Promise<AgentState>;
+export declare function ensureNewStatePath(path: string): Promise<void>;
+export declare function saveState(path: string, state: AgentState, requireNew?: boolean): Promise<void>;

package/dist/state.js

@@ -0,0 +1,104 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export class ExpiredStateError extends Error {
+    state;
+    exitCode = 3;
+    constructor(message, state) {
+        super(message);
+        this.state = state;
+    }
+}
+export class DeniedStateError extends Error {
+    exitCode = 4;
+}
+const invalid = () => new Error('Invalid journey state file. Connect again.');
+const permissions = () => new Error('Journey state file must be owned by you, be a regular file, and have permissions 0600.');
+async function check(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || (info.mode & 0o777) !== 0o600 || process.getuid && info.uid !== process.getuid())
+        throw permissions();
+}
+export async function loadState(path) {
+    await check(path);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let value;
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || (info.mode & 0o777) !== 0o600 || process.getuid && info.uid !== process.getuid())
+            throw permissions();
+        value = JSON.parse(await handle.readFile({ encoding: 'utf8' }));
+    }
+    finally {
+        await handle.close();
+    }
+    if (!value || typeof value !== 'object')
+        throw invalid();
+    const state = value;
+    if ((state.status !== 'pending' && state.status !== 'approved') || !Number.isFinite(state.createdAt) || !Number.isFinite(state.expiresAt) || state.expiresAt <= state.createdAt || state.expiresAt > state.createdAt + 8 * 3_600_000 || typeof state.link !== 'string' || typeof state.code !== 'string')
+        throw invalid();
+    if (state.status === 'pending') {
+        if (!['server', 'journeyId', 'sessionId', 'identity', 'recipient', 'signingPrivateKey', 'signingKey'].every(key => typeof state[key] === 'string' && state[key]) || state.requestedScope !== 'read' && state.requestedScope !== 'readwrite')
+            throw invalid();
+    }
+    else {
+        const session = state.session;
+        if (!session || !['server', 'journeyId', 'sessionId', 'principal', 'identity', 'recipient', 'signingPrivateKey', 'signingKey'].every(key => typeof session[key] === 'string' && session[key]) || session.scope !== 'read' && session.scope !== 'readwrite' || session.expiresAt !== state.expiresAt)
+            throw invalid();
+    }
+    if (state.expiresAt <= Date.now()) {
+        await rm(path);
+        throw new ExpiredStateError('Journey state file expired and was deleted. Connect again.', state);
+    }
+    return state;
+}
+export async function ensureNewStatePath(path) {
+    try {
+        await check(path);
+        throw new Error('Journey state file already exists. Choose a new --state file.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+export async function saveState(path, state, requireNew = false) {
+    await mkdir(dirname(path), { recursive: true });
+    let exists = false;
+    try {
+        await check(path);
+        exists = true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (exists && requireNew)
+        throw new Error('Journey state file already exists. Choose a new --state file.');
+    if (!exists) {
+        const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(state));
+        }
+        finally {
+            await handle.close();
+        }
+        return;
+    }
+    // Replacement is atomic: readers cannot observe a partially written session.
+    const temp = join(dirname(path), '.wayfinding-' + crypto.randomUUID());
+    try {
+        const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(state));
+        }
+        finally {
+            await handle.close();
+        }
+        await check(path);
+        await rename(temp, path);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-wayfinding/client",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -26,7 +26,8 @@
     "test:mcp": "vitest run test/integration.test.ts -t MCP"
   },
   "dependencies": {
-    "@ai-wayfinding/core": "0.1.1",
+    "@ai-wayfinding/core": "0.1.2",
+    "undici": "^7.29.0",
     "@modelcontextprotocol/sdk": "^1.30.1"
   },
   "devDependencies": {