@cello-protocol/client 0.0.4 → 0.0.6

package/db/migrations/V1__client_schema.sql

@@ -0,0 +1,21 @@
+-- V1__client_schema.sql
+-- CELLO-PERSIST-009: Initial client-side encrypted database schema.
+--
+-- Tables:
+--   client_store — opaque key/value blob store (implements ClientStore interface)
+--
+-- Note: schema_migrations is NOT created here. The migration runner bootstraps
+-- that table itself before executing any migration files, so it must not appear
+-- inside a migration transaction.
+--
+-- All data at rest is protected by SQLCipher (AES-256-CBC with PBKDF2 key derivation).
+-- The db_key is never stored here — it is derived at runtime from identity_key via HKDF.
+
+-- Opaque key/value store backing the ClientStore interface.
+-- key:   stable string identifier (session keys, trust data, key material, etc.)
+-- value: raw bytes (BLOB)
+CREATE TABLE IF NOT EXISTS client_store (
+    key        TEXT    NOT NULL PRIMARY KEY,
+    value      BLOB    NOT NULL,
+    updated_at TEXT    NOT NULL DEFAULT (datetime('now'))
+);

package/db/migrations/V2__client_schema_structured.sql

@@ -0,0 +1,274 @@
+-- V2__client_schema_structured.sql
+-- CELLO-PERSIST-024: Structured client-side SQLCipher schema.
+--
+-- This migration:
+--   1. Drops the V1 client_store table (placeholder KV store, no production users)
+--   2. Creates 18 structured tables covering all durable state
+--
+-- All data at rest is protected by SQLCipher (AES-256-CBC with PBKDF2 key derivation).
+-- The db_key is never stored here — derived at runtime from K_local via HKDF.
+
+-- Drop the placeholder KV table — all state migrates to structured tables.
+DROP TABLE IF EXISTS client_store;
+
+-- ── 1. agents ────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS agents (
+    pubkey              TEXT    NOT NULL,
+    agent_name          TEXT    NOT NULL DEFAULT '',
+    key_file_path       TEXT    NOT NULL,
+    ml_dsa_key_file_path TEXT,
+    created_at          TEXT    NOT NULL DEFAULT (datetime('now')),
+    last_seen_at        TEXT    NOT NULL DEFAULT (datetime('now')),
+    is_active           INTEGER NOT NULL DEFAULT 1,
+    PRIMARY KEY (pubkey)
+);
+
+-- ── 2. registration_state ────────────────────────────────────
+CREATE TABLE IF NOT EXISTS registration_state (
+    agent_pubkey    TEXT    NOT NULL,
+    agent_id        TEXT    NOT NULL,
+    primary_pubkey  TEXT    NOT NULL,
+    ml_dsa_pubkey   TEXT    NOT NULL,
+    registered_at   INTEGER NOT NULL,
+    status          TEXT    NOT NULL DEFAULT 'active' CHECK (status IN ('active')),
+    created_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE,
+    UNIQUE (agent_id)
+);
+
+-- ── 3. frost_key_shares ──────────────────────────────────────
+CREATE TABLE IF NOT EXISTS frost_key_shares (
+    agent_pubkey            TEXT    NOT NULL,
+    epoch_id                TEXT    NOT NULL,
+    primary_pubkey          TEXT    NOT NULL,
+    identifier              TEXT    NOT NULL,
+    signing_share           BLOB    NOT NULL,
+    threshold               INTEGER NOT NULL,
+    participants            INTEGER NOT NULL,
+    commitments_cbor        BLOB    NOT NULL,
+    verifying_shares_cbor   BLOB    NOT NULL,
+    dkg_method              TEXT    NOT NULL CHECK (dkg_method IN ('trusted_dealer','network_dkg')),
+    is_active               INTEGER NOT NULL DEFAULT 1,
+    created_at              TEXT    NOT NULL DEFAULT (datetime('now')),
+    validated_at            TEXT,
+    PRIMARY KEY (agent_pubkey, epoch_id),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_frost_key_shares_active
+    ON frost_key_shares(agent_pubkey) WHERE is_active = 1;
+
+-- ── 4. ml_dsa_keypairs ───────────────────────────────────────
+CREATE TABLE IF NOT EXISTS ml_dsa_keypairs (
+    agent_pubkey        TEXT    NOT NULL,
+    ml_dsa_pubkey       TEXT    NOT NULL,
+    secret_key_blob     BLOB    NOT NULL,
+    algorithm           TEXT    NOT NULL DEFAULT 'ML-DSA-44',
+    created_at          TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+
+-- ── 5. connection_policy ─────────────────────────────────────
+CREATE TABLE IF NOT EXISTS connection_policy (
+    agent_pubkey    TEXT    NOT NULL,
+    mode            TEXT    NOT NULL CHECK (mode IN ('open','selective','guarded','closed')),
+    review_mode     TEXT    NOT NULL CHECK (review_mode IN ('deterministic','inference')),
+    updated_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+
+-- ── 6. connection_policy_requirements ───────────────────────
+CREATE TABLE IF NOT EXISTS connection_policy_requirements (
+    agent_pubkey    TEXT    NOT NULL,
+    position        INTEGER NOT NULL,
+    signal_type     TEXT    NOT NULL CHECK (signal_type IN ('endorsement','attestation','pseudonym_age','registration_age')),
+    condition_json  TEXT    NOT NULL,
+    PRIMARY KEY (agent_pubkey, position),
+    FOREIGN KEY (agent_pubkey) REFERENCES connection_policy(agent_pubkey) ON DELETE CASCADE
+);
+
+-- ── 7. connections ───────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS connections (
+    connection_id               TEXT    NOT NULL,
+    agent_pubkey                TEXT    NOT NULL,
+    counterparty_pubkey         TEXT    NOT NULL,
+    counterparty_primary_pubkey TEXT    NOT NULL DEFAULT '',
+    counterparty_ml_dsa_pubkey  TEXT    NOT NULL DEFAULT '',
+    established_at              INTEGER NOT NULL,
+    status                      TEXT    NOT NULL DEFAULT 'active' CHECK (status IN ('active')),
+    profile_unchecked           INTEGER NOT NULL DEFAULT 0,
+    created_at                  TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (connection_id),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE,
+    UNIQUE (agent_pubkey, counterparty_pubkey)
+);
+CREATE INDEX IF NOT EXISTS idx_connections_agent ON connections(agent_pubkey);
+
+-- ── 8. endorsements ──────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS endorsements (
+    agent_pubkey            TEXT    NOT NULL,
+    endorser_pubkey         TEXT    NOT NULL,
+    endorser_ml_dsa_pubkey  BLOB    NOT NULL,
+    target_pubkey           TEXT    NOT NULL,
+    endorsement_type        TEXT    NOT NULL,
+    created_at              INTEGER NOT NULL,
+    expires_at              INTEGER NOT NULL,
+    endorser_ml_dsa_sig     BLOB    NOT NULL,
+    received_at             TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey, endorser_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_endorsements_expires ON endorsements(expires_at);
+
+-- ── 9. attestations ──────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS attestations (
+    agent_pubkey            TEXT    NOT NULL,
+    attester_pubkey         TEXT    NOT NULL,
+    attestation_type        TEXT    NOT NULL,
+    attester_ml_dsa_pubkey  BLOB    NOT NULL,
+    attestation_data        BLOB    NOT NULL,
+    created_at              INTEGER NOT NULL,
+    expires_at              INTEGER NOT NULL,
+    attester_ml_dsa_sig     BLOB    NOT NULL,
+    received_at             TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey, attester_pubkey, attestation_type),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_attestations_expires ON attestations(expires_at);
+
+-- ── 10. peers ────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS peers (
+    agent_pubkey    TEXT    NOT NULL,
+    peer_pubkey_hex TEXT    NOT NULL,
+    peer_id         TEXT    NOT NULL,
+    multiaddrs      TEXT    NOT NULL,
+    added_at        TEXT    NOT NULL DEFAULT (datetime('now')),
+    last_seen_at    TEXT,
+    updated_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey, peer_pubkey_hex),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_peers_peer_id ON peers(agent_pubkey, peer_id);
+
+-- ── 11. sessions ─────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id              TEXT    NOT NULL,
+    agent_pubkey            TEXT    NOT NULL,
+    counterparty_pubkey     BLOB    NOT NULL,
+    counterparty_peer_id    TEXT    NOT NULL,
+    counterparty_multiaddrs TEXT    NOT NULL,
+    relay_peer_id           TEXT    NOT NULL,
+    relay_multiaddrs        TEXT    NOT NULL,
+    directory_peer_id       TEXT    NOT NULL,
+    directory_multiaddrs    TEXT    NOT NULL,
+    directory_pubkey        BLOB    NOT NULL,
+    genesis_prev_root       BLOB    NOT NULL,
+    last_seen_seq           INTEGER NOT NULL DEFAULT 0,
+    last_sent_seq           INTEGER NOT NULL DEFAULT 0,
+    next_expected_seq       INTEGER NOT NULL DEFAULT 1,
+    status                  TEXT    NOT NULL CHECK (status IN ('active','transport_lost','sealing','sealed','seal_rejected','seal_deferred')),
+    desynchronized          INTEGER NOT NULL DEFAULT 0,
+    leaf_count              INTEGER NOT NULL DEFAULT 0,
+    sealed_root             BLOB,
+    seal_type               TEXT    CHECK (seal_type IN ('frost','bilateral','unilateral')),
+    close_timestamp         INTEGER,
+    frost_signature         BLOB,
+    signer_pubkey           BLOB,
+    directory_signature     BLOB,
+    checkpoint_status       TEXT    NOT NULL DEFAULT 'pending' CHECK (checkpoint_status IN ('pending','confirmed')),
+    checkpoint_peak_hash    TEXT,
+    checkpoint_leaf_index   INTEGER,
+    checkpoint_sibling_hashes TEXT,
+    created_at              TEXT    NOT NULL DEFAULT (datetime('now')),
+    updated_at              TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (session_id, agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent_pubkey, status);
+
+-- ── 12. session_tree_leaves ──────────────────────────────────
+CREATE TABLE IF NOT EXISTS session_tree_leaves (
+    session_id      TEXT    NOT NULL,
+    agent_pubkey    TEXT    NOT NULL,
+    leaf_index      INTEGER NOT NULL,
+    leaf_kind       TEXT    NOT NULL CHECK (leaf_kind IN ('msg','ctrl')),
+    s2_cbor         BLOB    NOT NULL,
+    sequence_number INTEGER NOT NULL,
+    accepted_at     TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (session_id, agent_pubkey, leaf_index),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE,
+    FOREIGN KEY (session_id, agent_pubkey) REFERENCES sessions(session_id, agent_pubkey) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_session_tree_leaves_seq
+    ON session_tree_leaves(session_id, agent_pubkey, sequence_number);
+
+-- ── 13. pending_hashes ───────────────────────────────────────
+CREATE TABLE IF NOT EXISTS pending_hashes (
+    id              INTEGER NOT NULL PRIMARY KEY,
+    agent_pubkey    TEXT    NOT NULL,
+    session_id      TEXT    NOT NULL,
+    hash_hex        TEXT    NOT NULL,
+    enqueued_at     INTEGER NOT NULL,
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE,
+    UNIQUE (agent_pubkey, session_id, hash_hex)
+);
+CREATE INDEX IF NOT EXISTS idx_pending_hashes_agent_session
+    ON pending_hashes(agent_pubkey, session_id);
+
+-- ── 14. relay_ack_receipts ───────────────────────────────────
+CREATE TABLE IF NOT EXISTS relay_ack_receipts (
+    hash_hex            TEXT    NOT NULL,
+    agent_pubkey        TEXT    NOT NULL,
+    session_id          TEXT    NOT NULL,
+    relay_id            TEXT    NOT NULL,
+    relay_pubkey_hex    TEXT    NOT NULL,
+    sequence_number     INTEGER NOT NULL,
+    relay_timestamp     INTEGER NOT NULL,
+    signature_hex       TEXT    NOT NULL,
+    acked_at            TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (hash_hex, agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+
+-- ── 15. backup_metadata ──────────────────────────────────────
+CREATE TABLE IF NOT EXISTS backup_metadata (
+    agent_pubkey    TEXT    NOT NULL,
+    completed_at    TEXT    NOT NULL,
+    destination_url TEXT    NOT NULL,
+    checksum        TEXT    NOT NULL,
+    updated_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+
+-- ── 16. known_relays ─────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS known_relays (
+    relay_id        TEXT NOT NULL PRIMARY KEY,
+    relay_pubkey_hex TEXT NOT NULL,
+    source          TEXT NOT NULL,
+    last_seen_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- ── 17. pending_connection_requests ──────────────────────────
+CREATE TABLE IF NOT EXISTS pending_connection_requests (
+    request_id      TEXT    NOT NULL,
+    agent_pubkey    TEXT    NOT NULL,
+    from_pubkey     TEXT    NOT NULL,
+    package_cbor    BLOB    NOT NULL,
+    arrived_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    round           INTEGER NOT NULL DEFAULT 1,
+    PRIMARY KEY (request_id, agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);
+
+-- ── 18. decided_connection_requests ──────────────────────────
+CREATE TABLE IF NOT EXISTS decided_connection_requests (
+    request_id      TEXT    NOT NULL,
+    agent_pubkey    TEXT    NOT NULL,
+    decision        TEXT    NOT NULL CHECK (decision IN ('accepted','rejected','more_disclosure')),
+    decided_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (request_id, agent_pubkey),
+    FOREIGN KEY (agent_pubkey) REFERENCES agents(pubkey) ON DELETE CASCADE
+);

package/dist/client.d.ts

@@ -162,10 +162,15 @@ export declare function createClient(node: CelloNode, keyProvider: KeyProvider,
     }): void;
     /** CONNREQ-002: list active connection records. */
     listConnections(): import("@cello-protocol/protocol-types").ClientConnectionRecord[];
-    /** CONNREQ-002: send connection_request to target B and await final outcome. */
+    /** CONNREQ-002 / AC-008 (DX-001): send connection_request to target B and await final outcome.
+     * Per-stage timeouts: dialTimeoutMs (stage 'dial'), sendTimeoutMs (stage 'send'),
+     * waitTimeoutMs (stage 'wait'). Timeout result includes the stage that fired. */
     cello_request_connection(opts: {
         target_pubkey: string;
         package_cbor: Uint8Array;
+        dialTimeoutMs?: number;
+        sendTimeoutMs?: number;
+        waitTimeoutMs?: number;
     }): Promise<{
         result: "established";
         connection_id: string;
@@ -181,6 +186,7 @@ export declare function createClient(node: CelloNode, keyProvider: KeyProvider,
         requested_items: unknown[];
     } | {
         result: "timeout";
+        stage: "dial" | "send" | "wait";
     } | {
         result: "error";
         reason: string;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -491,13 +491,24 @@ class CelloClientImpl {
                 return;
             }
             // Reconstruct FrostThresholdSigner (config only — secret is in module-level store).
-            // HIGH-1: directoryEndpoint is NOT required for construction — the signer can verify
-            // signatures even without a live directory. Pass undefined for directoryNodes.
+            // AC-003 (DX-001): directoryNodeStubs MUST be populated from the current directoryEndpoint
+            // so that the signer can participate in FROST signing ceremonies (round-trip frames
+            // to directory via libp2p). Without directoryNodeStubs, the signer can verify but cannot
+            // participate in ceremonies — causing directory_below_threshold on session initiation.
             if (!this.#thresholdSigner) {
+                let directoryNodeStubsForSigner;
+                if (this.#directoryEndpoint) {
+                    directoryNodeStubsForSigner = [new NetworkDirectoryNode({
+                            id: this.#directoryEndpoint.peer_id,
+                            node: this.#node,
+                            directoryPeerId: this.#directoryEndpoint.peer_id,
+                            directoryMultiaddrs: this.#directoryEndpoint.multiaddrs,
+                        })];
+                }
                 this.#thresholdSigner = new FrostThresholdSigner({
                     threshold: row.threshold,
                     participants: row.participants,
-                    directoryNodes: undefined,
+                    directoryNodeStubs: directoryNodeStubsForSigner,
                 }, Buffer.from(myPubkeyHex, "hex"));
             }
             // Set primary_pubkey from stored commitments[0]
@@ -782,6 +793,29 @@ class CelloClientImpl {
     setHashQueue(queue) {
         this.#hashQueue = queue;
     }
+    /**
+     * AC-003 (DX-001): Set directory endpoint after construction (composition root pattern).
+     * Called by cello-mcp.ts background task before loadPersistedState() so that
+     * loadPersistedState() can populate directoryNodeStubs in the reconstructed FrostThresholdSigner.
+     */
+    setDirectoryEndpoint(endpoint) {
+        this.#directoryEndpoint = endpoint;
+    }
+    /**
+     * AC-003 (DX-001): Wire threshold signer after construction.
+     * Called by cello-mcp.ts background task only when the agent is not yet registered
+     * (bootstrap ran). Registered agents reconstruct the signer from DB in loadPersistedState().
+     */
+    setThresholdSigner(signer) {
+        this.#thresholdSigner = signer;
+    }
+    /**
+     * PERSIST-024: Wire persistence layer after construction.
+     * Called by cello-mcp.ts background task after SQLCipher store opens.
+     */
+    setPersistence(persistence) {
+        this.#persistence = persistence;
+    }
     addPeer(peerPubkeyHex, peerId, multiaddrs) {
         this.#peers.set(peerPubkeyHex, { peerId, multiaddrs, connected: true });
         // PERSIST-024: persist peer to DB
@@ -3189,7 +3223,7 @@ class CelloClientImpl {
      *
      * Crypto refs: NIST FIPS 204 (ML-DSA-44), RFC 9591 (FROST), FIPS 180-4 (SHA-256)
      */
-    async register(phoneStub, preAuthToken) {
+    async register(phoneStub = "", preAuthToken) {
         // Step 1: already registered — return error
         if (this.#registrationState) {
             return { error: "already_registered" };
@@ -3765,8 +3799,13 @@ class CelloClientImpl {
      *   { result: 'rejected', reason } — target rejected
      *   { result: 'insufficient', unmet_requirements } — target found requirements unmet
      *   { result: 'disclosure_requested', connection_request_id, requested_items } — Round 2 request (unblocks sender)
-     *   { result: 'timeout' } — no response within connectionTimeoutMs
+     *   { result: 'timeout', stage } — no response within timeout; stage identifies which phase timed out
      *   { result: 'error', reason } — directory-level error (not_registered, target_not_found, etc.)
+     *
+     * AC-008 (DX-001): per-stage timeouts:
+     *   dialTimeoutMs  — stage 'dial':  timeout for opening the persistent signaling stream (default: connectionTimeoutMs)
+     *   sendTimeoutMs  — stage 'send':  timeout for sending the frame (default: connectionTimeoutMs)
+     *   waitTimeoutMs  — stage 'wait':  timeout for target response (default: connectionTimeoutMs)
      */
     async cello_request_connection(opts) {
         const targetPubkeyHex = opts.target_pubkey;
@@ -3786,12 +3825,22 @@ class CelloClientImpl {
             resolveOutcome = resolve;
         });
         this.#pendingConnectionRequestResolvers.set(targetPubkeyHex, resolveOutcome);
-        // Ensure the persistent signaling stream is open
+        // AC-008 (DX-001): per-stage timeouts. Fall back to #connectionTimeoutMs if not provided.
+        const dialTimeoutMs = opts.dialTimeoutMs ?? this.#connectionTimeoutMs;
+        const sendTimeoutMs = opts.sendTimeoutMs ?? this.#connectionTimeoutMs;
+        const waitTimeoutMs = opts.waitTimeoutMs ?? this.#connectionTimeoutMs;
+        // Stage 1 — dial: Ensure the persistent signaling stream is open within dialTimeoutMs.
         if (!this.#persistentSignalingStream) {
-            const opened = await this.#openPersistentSignalingStream();
-            if (!opened) {
+            let dialTimedOut = false;
+            let opened = false;
+            await Promise.race([
+                this.#openPersistentSignalingStream().then((result) => { opened = result; }),
+                new Promise((resolve) => setTimeout(() => { dialTimedOut = true; resolve(); }, dialTimeoutMs)),
+            ]);
+            if (dialTimedOut || !opened) {
                 this.#pendingConnectionRequestResolvers.delete(targetPubkeyHex);
-                return { result: "error", reason: "directory_unreachable" };
+                this.#logger.warn("client.connection.request.stage.timeout", { stage: "dial", timeoutMs: dialTimeoutMs, targetPubkeyOrAgentId: targetPubkeyHex });
+                return { result: "timeout", stage: "dial" };
             }
         }
         // Mint a correlationId for this outbound connection request flow.
@@ -3804,20 +3853,39 @@ class CelloClientImpl {
             target_pubkey: targetPubkeyHex,
             package_cbor: opts.package_cbor,
         });
-        try {
-            this.#persistentSignalingStream.send(lp.encode.single(frameBytes));
+        // Stage 2 — send: Deliver the frame within sendTimeoutMs.
+        // The .send() call is synchronous but may throw if the stream has disconnected.
+        // Wrap in a race so an unresponsive stream doesn't block indefinitely.
+        let sendTimedOut = false;
+        let sendError = false;
+        await Promise.race([
+            new Promise((resolve) => {
+                try {
+                    this.#persistentSignalingStream.send(lp.encode.single(frameBytes));
+                }
+                catch {
+                    sendError = true;
+                }
+                resolve();
+            }),
+            new Promise((resolve) => setTimeout(() => { sendTimedOut = true; resolve(); }, sendTimeoutMs)),
+        ]);
+        if (sendTimedOut) {
+            this.#pendingConnectionRequestResolvers.delete(targetPubkeyHex);
+            this.#logger.warn("client.connection.request.stage.timeout", { stage: "send", timeoutMs: sendTimeoutMs, targetPubkeyOrAgentId: targetPubkeyHex });
+            return { result: "timeout", stage: "send" };
         }
-        catch {
+        if (sendError) {
             this.#pendingConnectionRequestResolvers.delete(targetPubkeyHex);
             return { result: "error", reason: "directory_unreachable" };
         }
-        // Race: outcome vs connectionTimeoutMs
+        // Stage 3 — wait: Race outcome vs waitTimeoutMs (was: connectionTimeoutMs).
         // DB-001: timeout cleans this slot without affecting concurrent requests to other targets.
         let frame = null;
         let timedOut = false;
         await Promise.race([
             outcomePromise.then((f) => { frame = f; }),
-            new Promise((resolve) => setTimeout(() => { timedOut = true; resolve(); }, this.#connectionTimeoutMs)),
+            new Promise((resolve) => setTimeout(() => { timedOut = true; resolve(); }, waitTimeoutMs)),
         ]);
         // Clean up this target's resolver slot on timeout
         // (on successful resolution, the signaling reader already deleted it)
@@ -3825,7 +3893,8 @@ class CelloClientImpl {
             this.#pendingConnectionRequestResolvers.delete(targetPubkeyHex);
         }
         if (timedOut || !frame) {
-            return { result: "timeout" };
+            this.#logger.warn("client.connection.request.stage.timeout", { stage: "wait", timeoutMs: waitTimeoutMs, targetPubkeyOrAgentId: targetPubkeyHex });
+            return { result: "timeout", stage: "wait" };
         }
         const type = frame["type"];
         if (type === "connection_established") {