ardent-cli-beta 0.0.17 → 0.0.19

package/NOTICE

@@ -0,0 +1,4 @@
+Ardent CLI
+Copyright 2026 ArdentAI, Inc.
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

package/README.md

@@ -6,21 +6,76 @@ The Ardent CLI is the customer command-line client for the control-plane API.
 
 Install the beta with `npm install --global ardent-cli-beta`, then run
 `ardent-beta <command>`. The package registers only the `ardent-beta` executable,
-so it can be installed alongside an existing `ardent` command.
+so it can be installed alongside an existing `ardent` command. `package.json`
+carries version `0.0.0` in source; the release pipeline sets the published
+version when it publishes, so a local build reports `0.0.0`.
 
 The Oclif foundation and authentication are implemented. `ardent-beta login` opens
-the Ardent frontend and returns the approved API key through a loopback callback
-bound with PKCE. `ardent-beta login --token <token>` validates and stores an existing
-API token for CI and automation; `ARDENT_TOKEN` supplies the same flag
-non-interactively. `ardent-beta status` and `ardent-beta logout` inspect and remove that
-local session. The CLI always talks to Ardent's production control plane. Oclif
-provides help, version, autocomplete, and native JSON command behavior. Resource
-context is retained from login. Project listing, creation, deletion, and local
-context switching are implemented. Organization member listing, invitation,
-removal, and pending-invitation cancellation are implemented. Connector listing
-and registration are implemented; registration follows connector status, while
-credential delivery and replication readiness remain owed. Connector-scoped branch
-creation, deletion, listing, and local switching are implemented.
+Ardent's login in a browser, receives an authorization code on a loopback callback, and
+exchanges it for an API key with PKCE. `ardent-beta login --token <token>` validates and stores an
+existing API token for CI and automation; `ARDENT_TOKEN` supplies the same flag non-interactively,
+and one that is set but empty fails rather than starting a browser login. `ardent-beta status` and
+`ardent-beta logout` inspect and remove that local session. The CLI defaults to Ardent's production
+control plane. Oclif provides help, version, autocomplete, and native JSON command behavior.
+Resource context is retained from login. Project listing, creation, deletion, and local context
+switching are implemented. Organization member listing, invitation, removal, and
+pending-invitation cancellation are implemented. Connector listing, registration,
+local switching, status lookup by ID and deletion are implemented; registration
+follows connector status and sends the connection URL for the control plane's
+credential delivery, while replication readiness remains owed. Connector-scoped branch
+creation, deletion, listing, local switching, `branch wake`, `branch suspend`, `branch recover`
+and `branch connect` are implemented. A suspended (parked) branch refuses connections until
+`branch wake` completes; nothing wakes a branch on connect, and `branch connect` names the wake
+command when the selected branch is parked. `branch recover` brings a failed branch back on its
+retained disk, and reports the control plane's refusal, with its stated fallback, when it cannot.
+`branch create <name>` waits until ready, selects the branch unless local context
+changed, and prints only its connection URL to stdout. Progress, credential
+revocation instructions and driver requirements go to stderr. `--driver` selects
+`libpq` (default), `node`, `jdbc` or `prisma`; `--json` returns the active branch,
+operation and credential. `--print` remains accepted. The credential stays active
+after exit. This uses `branch connect --print`'s lifecycle and requires a control
+plane that issues credentials while branches start (`docs/DECISIONS.md` section 17).
+
+Use `branch create <name> --to-env` to write `DATABASE_URL` to `.env` in the
+current directory instead of printing the URL. The selected `--driver` still
+applies. This option cannot be combined with `--print` or `--json`.
+`writeBranchEnv` preserves unrelated entries and refuses an existing
+`DATABASE_URL`; remove that key explicitly before retrying. It replaces the
+file with mode 0600 through a synced temporary file, syncs the destination
+directory, and refuses symlinks and
+hard links. Avoid concurrent edits to `.env` while the command runs: replacement
+does not coordinate with other editors. Values use a quote delimiter absent
+from the connection string; newline, NUL, or values containing all three dotenv
+quote delimiters are refused. Use a dotenv reader without variable expansion.
+Custom destination filenames remain future work.
+
+`branch connect` needs a selected active branch, an installed PostgreSQL 16+ `psql`, and the
+system `script` utility on macOS or Linux. It requests a read/write credential for the branch,
+or with `--role <name>` a fresh password on that source role (for example `postgres`) that works
+on this branch alone, acknowledges delivery, runs `psql` under `script`, and revokes the credential when the session
+ends. `--print --driver <libpq|node|jdbc|prisma>` instead writes one driver's connection string
+to stdout and leaves that credential active for an application (`docs/DECISIONS.md` section 15);
+only the libpq form opens psql. Otherwise the credential stays out of arguments and ordinary terminal output: requirement 5.10 in
+`docs/REQUIREMENTS.md` section 5 says "`runPsql` passes fields through child environment
+variables ... and redacts the username, API key and password from both `script` output
+streams". It does not stop a user from printing a credential
+deliberately through SQL or a shell escape. A mode-0600 recovery
+file holds only request and issuance IDs, and any source role name, until revocation succeeds, and the next `branch connect`
+attempts to revoke every abandoned issuance before requesting another. A forced process kill
+can leave a credential active until that recovery runs. Failed cleanup retains
+the file and names the issuance ID for manual revocation.
+
+[openapi.json](openapi.json) ships in the npm package. It is a documentation snapshot of the control-plane
+specification as of 2026-09-24, from Ardent's private source revision
+`c8510ab3e2422756a93e1df09acf994cf6bac34d`, and not proof of deployed
+compatibility. It predates the branch credential endpoints used by `branch connect`, and the
+branch wake, suspend and recover operations used by those commands, and connector
+deletion; the source specification documents wake, suspend and recover, and
+refreshing this snapshot from a merged revision that carries them is owed.
+Documenting the credential and connector-deletion endpoints in the source
+specification is also owed. To refresh it, replace it with the reviewed
+control-plane specification, record its source revision here, and run `make ci`.
+Ownership and snapshot limits are recorded in [docs/DECISIONS.md](docs/DECISIONS.md).
 
 Set `ARDENT_API_URL` to point the CLI at a development control plane. Without
 it, the CLI uses `https://production.tryardent.com`.
@@ -40,11 +95,15 @@ npm run build
 ./bin/run.js member invite administrator@example.com --role admin
 ./bin/run.js member delete teammate@example.com
 ./bin/run.js connector list
-./bin/run.js connector create postgresql 'postgresql://user:password@database.example.com/app'
+./bin/run.js connector create postgresql 'postgresql://user:password@database.example.com/app' --name Primary
+./bin/run.js connector switch Primary
+./bin/run.js connector status <connector-id>
 ./bin/run.js branch create "my feature"
 ./bin/run.js branch list
 ./bin/run.js branch switch "my feature"
+./bin/run.js branch connect
 ./bin/run.js branch delete "my feature"
+./bin/run.js connector delete Primary
 ARDENT_API_URL=http://localhost:8080 ./bin/run.js login --token <token>
 ```
 
@@ -52,14 +111,33 @@ Branch commands operate on a connector. When discovering connectors, the CLI use
 its project context; one connector is selected automatically. In an interactive
 terminal, multiple connectors appear in a numbered picker with the saved connector
 as the default. Automation uses the saved connector and fails if selection is
-ambiguous. Project changes clear connector and branch context.
+ambiguous. `connector switch <name>` selects from the project's current connector
+list for both terminals and automation. Project changes clear connector and branch context.
+
+`connector delete <name>` resolves the name from the selected project's current
+list. The API refuses deletion while branches remain. In a terminal the command
+waits for `deleted` before removing the connector from local context; automation
+and `--json` return `deleting` after acceptance and retain local context. Use
+`connector status <connector-id>` to follow registration or deletion, including
+after a deleted connector disappears from `connector list`. Deletion status may
+report source cleanup residue; the delete command warns about it and status
+preserves its code in text and JSON. A failed or interrupted wait retains local
+context and names the status command before retrying.
 
 Creation uses the connector's latest published snapshot. If that snapshot is
 unavailable, creation fails without choosing an older one. Names are unique within
 a connector while the branch is not deleted. `branch delete` sends the connector
 and name to the API, which resolves the target. `branch list` fetches current state
-and marks the locally selected branch with `*`; `branch switch` changes local
+and marks the locally selected branch with `●` in its `Selected` column; `branch switch` changes local
 context. Create and delete follow the operation in an interactive terminal;
-non-interactive commands and `--json` return the accepted operation immediately.
+creation also waits outside a terminal and with `--json` so it can return a usable
+URL. Non-interactive deletion and deletion with `--json` return the accepted
+operation immediately.
+
+Before changing this repository, read `AGENTS.md` and [ARDENT_CLI_DEVELOPMENT.md](ARDENT_CLI_DEVELOPMENT.md).
 
-Before changing this repository, read [ARDENT_CLI_DEVELOPMENT.md](ARDENT_CLI_DEVELOPMENT.md).
+Running `npm test` or `make ci` requires Node 22+, npm and `tar`. The interactive
+tests and installed `branch connect` command require macOS's system `script`, or
+Linux's util-linux `script` with `-e` support, on `PATH`. The interactive tests
+also use util-linux `script -c`. The PTY tests skip other operating systems and
+fail on Linux if the required utility is missing or incompatible.

package/dist/api/client.d.ts

@@ -2,7 +2,12 @@ export declare const API_URL: string;
 export declare class APIError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
+    readonly workflowID?: string | undefined;
+    readonly location?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined, workflowID?: string | undefined, location?: string | undefined);
 }
+export declare class APITransportError extends Error {
+}
+export declare function requestDurableMutation<T>(token: string, path: string, init: RequestInit, refreshCommand: string): Promise<T>;
 export declare function request<T>(token: string, path: string, init?: RequestInit): Promise<T>;
 export declare function requestWithoutAuthentication<T>(path: string, init?: RequestInit): Promise<T>;

package/dist/api/client.js

@@ -1,12 +1,44 @@
+import { terminalText } from '../terminal.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
+const DURABLE_MUTATION_TIMEOUT_MS = 90_000;
 export const API_URL = process.env.ARDENT_API_URL || 'https://production.tryardent.com';
 export class APIError extends Error {
     status;
     code;
-    constructor(message, status, code) {
+    workflowID;
+    location;
+    constructor(message, status, code, workflowID, location) {
         super(message);
         this.status = status;
         this.code = code;
+        this.workflowID = workflowID;
+        this.location = location;
+    }
+}
+// APITransportError is a request whose response never arrived whole: the
+// request could not be sent, or its response was lost or timed out while it
+// was read. Unlike an APIError, it carries no status the API chose.
+export class APITransportError extends Error {
+}
+export async function requestDurableMutation(token, path, init, refreshCommand) {
+    // The API can await its durable workflow for 75 seconds. Allow response transit
+    // time too, without replacing an explicit caller deadline or retrying a write.
+    try {
+        return await request(token, path, {
+            ...init,
+            signal: init.signal ?? AbortSignal.timeout(DURABLE_MUTATION_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (error instanceof APIError) {
+            if (error.status !== 503 || error.code !== 'workflow_result_timeout')
+                throw error;
+            const workflow = error.workflowID ? ` Workflow: ${terminalText(error.workflowID)}.` : '';
+            const location = error.location ? ` Check its status with an authenticated GET ${terminalText(error.location)}.` : '';
+            error.message = `The mutation was still running when the API stopped waiting.${workflow}${location} Run ${refreshCommand} to refresh resource state; confirm the workflow outcome before retrying.`;
+            throw error;
+        }
+        throw new Error(`The mutation response was not received completely; completion is unknown and work may still be running. Run ${refreshCommand} to refresh resource state and confirm the outcome before retrying.`, { cause: error });
     }
 }
 export async function request(token, path, init = {}) {
@@ -35,18 +67,25 @@ async function requestJSON(path, init) {
         });
     }
     catch (error) {
-        throw new Error(`Could not reach the Ardent API: ${error instanceof Error ? error.message : String(error)}`);
+        throw new APITransportError(`Could not reach the Ardent API: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new APITransportError(`The Ardent API response was not received completely: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const text = await response.text();
     if (!response.ok) {
-        let detail = {};
+        let detail;
         try {
             detail = JSON.parse(text);
         }
         catch {
             // Plain-text errors still receive the status-based fallback below.
         }
-        throw new APIError(detail.message ?? `Ardent API request failed with HTTP ${response.status}.`, response.status, detail.error);
+        const fields = typeof detail === 'object' && detail !== null ? detail : {};
+        throw new APIError(typeof fields.message === 'string' ? fields.message : `Ardent API request failed with HTTP ${response.status}.`, response.status, typeof fields.error === 'string' ? fields.error : undefined, typeof fields.workflow_id === 'string' ? fields.workflow_id : undefined, response.headers.get('Location') ?? undefined);
     }
     if (response.status === 204)
         return undefined;

package/dist/auth/credentials.d.ts

@@ -27,4 +27,5 @@ export interface ProjectIdentity {
 }
 export declare function loadSession(directory: string): Promise<Session | undefined>;
 export declare function saveSession(directory: string, session: Session): Promise<void>;
+export declare function updateSession(directory: string, change: (current: Session | undefined) => Session | undefined): Promise<boolean>;
 export declare function clearSession(directory: string): Promise<void>;

package/dist/auth/credentials.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
 const configPath = (directory) => join(directory, 'config.json');
 export async function loadSession(directory) {
     let contents;
@@ -101,8 +102,45 @@ function isProjectIdentity(value) {
     return typeof project.id === 'string' && project.id.length > 0 && typeof project.name === 'string' && project.name.length > 0;
 }
 export async function saveSession(directory, session) {
+    await withSessionLock(directory, () => writeSession(directory, session));
+}
+// Undefined leaves the current session untouched, including after logout.
+export async function updateSession(directory, change) {
+    return withSessionLock(directory, async () => {
+        const updated = change(await loadSession(directory));
+        if (!updated)
+            return false;
+        await writeSession(directory, updated);
+        return true;
+    });
+}
+async function withSessionLock(directory, action) {
     await mkdir(directory, { mode: 0o700, recursive: true });
     await chmod(directory, 0o700);
+    const path = join(directory, 'config.lock');
+    const deadline = Date.now() + 5000;
+    let lock;
+    while (!lock) {
+        try {
+            lock = await open(path, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`Local configuration is locked at ${path}. If no other CLI is writing it, remove that stale lock and retry.`);
+            await pause(25);
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await lock.close();
+        await unlink(path);
+    }
+}
+async function writeSession(directory, session) {
     const destination = configPath(directory);
     const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
     try {
@@ -115,8 +153,10 @@ export async function saveSession(directory, session) {
     }
 }
 export async function clearSession(directory) {
-    await unlink(configPath(directory)).catch((error) => {
-        if (error.code !== 'ENOENT')
-            throw error;
+    await withSessionLock(directory, async () => {
+        await unlink(configPath(directory)).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
     });
 }

package/dist/branches/client.d.ts

@@ -15,5 +15,7 @@ export interface BranchOperation {
 export declare function listBranches(token: string, connectorID: string): Promise<Branch[]>;
 export declare function createBranch(token: string, connectorID: string, name: string): Promise<BranchOperation>;
 export declare function deleteBranch(token: string, connectorID: string, name: string): Promise<BranchOperation>;
-export declare function waitForBranchOperation(token: string, workflowID: string, onStatus?: (status: string) => void): Promise<void>;
+export type BranchLifecycleAction = 'wake' | 'suspend' | 'recover';
+export declare function transitionBranch(token: string, connectorID: string, name: string, action: BranchLifecycleAction): Promise<BranchOperation>;
+export declare function waitForBranchOperation(token: string, workflowID: string, onStatus?: (status: string) => void, failedReads?: 'stop' | 'retry'): Promise<void>;
 export declare function branchName(arguments_: unknown[]): string;

package/dist/branches/client.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { request } from '../api/client.js';
+import { APIError, APITransportError, request, requestDurableMutation } from '../api/client.js';
+import { terminalText } from '../terminal.js';
+import { pauseFor, pollPauser } from './poll.js';
 export async function listBranches(token, connectorID) {
     const branches = await request(token, `/branches?${new URLSearchParams({ connector_id: connectorID })}`);
     if (!Array.isArray(branches) || branches.some((branch) => !isBranch(branch, connectorID)) || new Set(branches.map(({ id }) => id)).size !== branches.length || new Set(branches.map(({ name }) => name)).size !== branches.length) {
@@ -21,10 +23,45 @@ export async function deleteBranch(token, connectorID, name) {
     validateOperation(result, connectorID, name);
     return result;
 }
-export async function waitForBranchOperation(token, workflowID, onStatus) {
+// The control plane addresses these transitions by branch ID, so the command
+// resolves the name in the selected connector first and acts on exactly that
+// branch. The response is the operation alone; the resolved branch is returned
+// with it so --json output has the same shape as create and delete.
+export async function transitionBranch(token, connectorID, name, action) {
+    const matches = (await listBranches(token, connectorID)).filter((candidate) => candidate.name === name);
+    if (matches.length !== 1)
+        throw new Error(`No branch named ${terminalText(JSON.stringify(name))} in the selected connector. Run ardent-beta branch list to see its branches.`);
+    const [branch] = matches;
+    // A response lost after the request arrived leaves the workflow possibly
+    // queued; requestDurableMutation says so instead of reporting a failed request.
+    const operation = await requestDurableMutation(token, `/branches/${encodeURIComponent(branch.id)}/${action}`, { method: 'POST' }, 'ardent-beta branch list');
+    if (!operation || typeof operation.operation_id !== 'string' || !operation.operation_id ||
+        typeof operation.workflow_id !== 'string' || !operation.workflow_id) {
+        // The request was accepted, so its workflow may be running even though the
+        // response does not say which one: the same unknown outcome as a lost response.
+        throw new Error(`The Ardent API accepted the branch ${action} request but returned no valid operation; completion is unknown and work may still be running. Run ardent-beta branch list to refresh resource state and confirm the outcome before retrying.`);
+    }
+    return { branch, operation };
+}
+// failedReads 'stop' ends the wait on the first read that fails. 'retry'
+// re-reads a lost response or a 5xx two seconds later, until the deadline; a
+// 4xx still ends it. docs/DECISIONS.md section 17, "`branch create --print`
+// asks for the credential while the branch starts", says which caller retries
+// and why.
+export async function waitForBranchOperation(token, workflowID, onStatus, failedReads = 'stop') {
     const deadline = Date.now() + 30 * 60 * 1000;
+    const pause = pollPauser();
     while (Date.now() < deadline) {
-        const result = await request(token, `/workflows/${encodeURIComponent(workflowID)}`);
+        let result;
+        try {
+            result = await request(token, `/workflows/${encodeURIComponent(workflowID)}`);
+        }
+        catch (error) {
+            if (failedReads === 'stop' || !(error instanceof APITransportError || (error instanceof APIError && error.status >= 500)))
+                throw error;
+            await pauseFor(2000);
+            continue;
+        }
         if (!result || result.id !== workflowID || !['DELAYED', 'ENQUEUED', 'PENDING', 'SUCCESS', 'ERROR', 'CANCELLED', 'MAX_RECOVERY_ATTEMPTS_EXCEEDED'].includes(result.status) || (result.failure !== undefined && typeof result.failure !== 'string')) {
             throw new Error('Ardent API returned an invalid branch operation status.');
         }
@@ -33,7 +70,7 @@ export async function waitForBranchOperation(token, workflowID, onStatus) {
             return;
         if (!['DELAYED', 'ENQUEUED', 'PENDING'].includes(result.status))
             throw new Error(result.failure || `Branch operation ${result.status.toLowerCase()}.`);
-        await new Promise((resolve) => setTimeout(resolve, 2000));
+        await pause();
     }
     throw new Error('Timed out waiting for the branch operation. Run ardent-beta branch list to check its state.');
 }

package/dist/branches/connection.d.ts

@@ -0,0 +1,21 @@
+import { type Driver } from './drivers.js';
+export interface BranchConnection {
+    configDir: string;
+    token: string;
+    branchID: string;
+    sourceRole?: string;
+    print: boolean;
+    driver: Driver;
+    json: boolean;
+    deliver?: (value: string) => Promise<void>;
+    serving?: () => Promise<void>;
+    say: (message: string) => void;
+    log: (message: string) => void;
+    warn: (message: string) => void;
+}
+export interface PrintedConnection {
+    issuance_id: string;
+    driver: Driver;
+    connection_string: string;
+}
+export declare function connectToBranch(connection: BranchConnection): Promise<PrintedConnection | void>;

package/dist/branches/connection.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { acknowledgeBranchCredential, CredentialIssueRefused, issueBranchCredential, revokeBranchCredential, waitForBranchCredential } from './credentials.js';
+import { CLIENT_REQUIREMENTS, connectionString } from './drivers.js';
+import { connectionEnvironment, runPsql } from './psql.js';
+import { CredentialRecoveryCleanupError, forgetCredentialRecovery, openCredentialWitness, rememberCredentialIssuance, rememberCredentialRequest } from './recovery.js';
+import { terminalText } from '../terminal.js';
+// connectToBranch issues one branch credential and either prints it, kept, or
+// opens psql with it and revokes it afterwards. Every outcome short of a kept
+// credential revokes it, and a recovery record lets the next branch connect
+// finish a revocation this process could not.
+export async function connectToBranch(connection) {
+    const { token, branchID, sourceRole, print, driver, say, warn } = connection;
+    const requestID = randomUUID();
+    const witness = await openCredentialWitness(requestID);
+    try {
+        const recovery = await rememberCredentialRequest(connection.configDir, branchID, token, witness.port, requestID, sourceRole);
+        let issuanceID;
+        let issueRefused = false;
+        // Set once a printed credential's recovery record is gone: the
+        // credential is the user's from then on, and nothing here revokes it.
+        let kept = false;
+        // The error that ended the command, kept in front of any cleanup error
+        // that follows it (withFailure), so a failed revocation never hides why
+        // the command failed.
+        let failure;
+        try {
+            try {
+                issuanceID = await issueBranchCredential(token, branchID, requestID, sourceRole);
+            }
+            catch (error) {
+                if (error instanceof CredentialIssueRefused) {
+                    issueRefused = true;
+                    try {
+                        await forgetCredentialRecovery(recovery);
+                    }
+                    catch (cleanupError) {
+                        if (cleanupError instanceof CredentialRecoveryCleanupError && cleanupError.stage === 'sync') {
+                            throw new Error(`${error.message} The local recovery record was removed, but its directory could not be synced.`);
+                        }
+                        throw new Error(`${error.message} Its local recovery record could not be removed. Inspect ${terminalText(recovery.file)} before retrying.`);
+                    }
+                }
+                throw error;
+            }
+            await rememberCredentialIssuance(recovery, issuanceID);
+            const delivery = await deliverWhenServing(token, issuanceID, connection.serving);
+            if (print) {
+                // Checked before acknowledgement, so a form that would not verify
+                // the server is revoked, never handed over.
+                const value = connectionString(driver, delivery.uri, delivery.connection_strings);
+                await acknowledgeBranchCredential(token, issuanceID, delivery.delivery_id);
+                if (connection.deliver)
+                    await connection.deliver(value);
+                // The record goes before the string is printed: a record left
+                // behind would make the next branch connect revoke what was printed.
+                // Any failure, an unconfirmed directory sync included, revokes the
+                // credential instead: a record a crash could restore would revoke
+                // what was printed, breaking "stays active". The record is written
+                // back first, so a revocation that also fails is still retried by
+                // the next branch connect.
+                try {
+                    await forgetCredentialRecovery(recovery);
+                }
+                catch (error) {
+                    await rememberCredentialIssuance(recovery, issuanceID);
+                    throw error;
+                }
+                kept = true;
+                say(`Credential issuance ${terminalText(issuanceID)} stays active until it is revoked with an authenticated DELETE /branch-credentials/${encodeURIComponent(issuanceID)}.`);
+                if (CLIENT_REQUIREMENTS[driver].length > 0) {
+                    say(`The ${driver} form needs, in your client:\n${CLIENT_REQUIREMENTS[driver].map((requirement) => `  - ${requirement}`).join('\n')}`);
+                }
+                if (connection.json)
+                    return { issuance_id: issuanceID, driver, connection_string: value };
+                connection.log(value);
+                return;
+            }
+            const environment = connectionEnvironment(delivery.uri);
+            await acknowledgeBranchCredential(token, issuanceID, delivery.delivery_id);
+            connection.log(`psql target: ${terminalText(environment.PGHOST)}:${environment.PGPORT}/${terminalText(environment.PGDATABASE)}`);
+            await runPsql(environment);
+        }
+        catch (error) {
+            failure = error;
+            throw error;
+        }
+        finally {
+            // A kept credential was asked to outlive the command.
+            if (!kept && !issuanceID && !issueRefused) {
+                warn(`Credential request ${requestID} has an unknown outcome. The next branch connect will recover it before issuing another credential.`);
+            }
+            else if (!kept && issuanceID) {
+                try {
+                    await revokeBranchCredential(token, issuanceID);
+                }
+                catch {
+                    warn(`Credential issuance ${terminalText(issuanceID)} may remain active. The next branch connect will retry revocation; an authenticated DELETE /branch-credentials/${encodeURIComponent(issuanceID)} can revoke it manually.`);
+                    throw withFailure(failure, 'Could not confirm branch credential revocation.');
+                }
+                try {
+                    await forgetCredentialRecovery(recovery);
+                }
+                catch (error) {
+                    if (error instanceof CredentialRecoveryCleanupError && error.stage === 'sync') {
+                        throw withFailure(failure, 'The branch credential was revoked, but the local recovery directory could not be synced.');
+                    }
+                    throw withFailure(failure, `The branch credential was revoked, but its local recovery record could not be removed. Inspect ${terminalText(recovery.file)} before retrying.`);
+                }
+            }
+        }
+    }
+    finally {
+        await witness.close();
+    }
+}
+// withFailure is the error a cleanup reports: its own message alone, or after
+// the message of the failure that ended the command.
+function withFailure(failure, message) {
+    if (failure === undefined)
+        return new Error(message);
+    return new Error(`${failure instanceof Error ? failure.message : String(failure)} ${message}`);
+}
+// deliverWhenServing reports the branch's own outcome before the credential's:
+// a branch whose materialization fails revokes the credential issued for it,
+// and that failure, not the revocation, is what the user needs to read.
+async function deliverWhenServing(token, issuanceID, serving) {
+    if (!serving)
+        return waitForBranchCredential(token, issuanceID);
+    const stop = new AbortController();
+    const served = serving();
+    const delivered = waitForBranchCredential(token, issuanceID, stop.signal, served);
+    // Observed after serving settles; this keeps an early refusal from being
+    // reported as unhandled in the meantime.
+    delivered.catch(() => { });
+    try {
+        await served;
+    }
+    catch (error) {
+        stop.abort();
+        throw error;
+    }
+    return delivered;
+}

package/dist/branches/credentials.d.ts

@@ -0,0 +1,18 @@
+import { type ConnectionStrings } from './drivers.js';
+interface DeliveredCredential {
+    issuance_id: string;
+    delivery_id: string;
+    uri: string;
+    connection_strings?: ConnectionStrings;
+}
+export declare class CredentialIssueRefused extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare function validSourceRole(role: string): boolean;
+export declare function refusedBeforeIssuance(error: unknown): boolean;
+export declare function issueBranchCredential(token: string, branchID: string, requestID: string, sourceRole?: string): Promise<string>;
+export declare function waitForBranchCredential(token: string, issuanceID: string, stop?: AbortSignal, served?: Promise<void>): Promise<DeliveredCredential>;
+export declare function acknowledgeBranchCredential(token: string, issuanceID: string, deliveryID: string): Promise<void>;
+export declare function revokeBranchCredential(token: string, issuanceID: string): Promise<void>;
+export {};