@cello-protocol/daemon 0.0.182 → 0.0.184

package/dist/session-node-manager.d.ts

@@ -16,6 +16,7 @@
  */
 import { type ContentHashAlg } from "./wire-content-hash.js";
 import { type CapacityReason } from "./refusal-reasons.js";
+import { type SaltAgreementFrame } from "./session-salt-agreement.js";
 import { type DaemonDatabase } from "./sqlcipher-db.js";
 import type { Stream } from "@libp2p/interface";
 import type { Logger, SessionRecord, SealReadinessView } from "./types.js";
@@ -23,11 +24,32 @@ import { SessionConnectionGater } from "./session-connection-gater.js";
 import { SessionTree, type WritableSessionTreeLeafKind } from "./session-tree.js";
 import { type CelloNode, type IAutoNatService } from "@cello-protocol/transport";
 import type { KeyProvider } from "@cello-protocol/crypto";
+import { type SessionEphemeral } from "@cello-protocol/crypto";
 import { type ParkEnvelope } from "./park-envelope.js";
-import { AgentRelayClient, type RelayAssignmentCarry } from "./session-relay-client.js";
+import { AgentRelayClient, type RelayAssignmentCarry, type RelayAuthRefusal, type RelayWitnessAlert } from "./session-relay-client.js";
+/**
+ * One row in an agent's witness-alert list — DOD-M15-CORROBORATE-1 review F1. Deduped on
+ * `(witness relay, session)`, so a repeated observation raises `occurrences` rather than taking
+ * another slot in a bounded list.
+ */
+export interface WitnessAlertNotice {
+    /** `${relayId}::${sessionIdHex}` — the dedupe key, not shown to anyone. */
+    key: string;
+    alert: RelayWitnessAlert;
+    occurrences: number;
+    /**
+     * When this witness first said it. Held SEPARATELY from `alert.observedAt`, because a later
+     * repeat can replace `alert` (a provable one supersedes an unprovable one) and that must not
+     * silently move the first sighting forward — an operator reading "first observed" wants to know
+     * when this started, not when the strongest version of it arrived.
+     */
+    firstObservedAt: number;
+    lastObservedAt: number;
+}
 import { RelayReceiptStore, type RelayReceipt } from "./relay-receipt-store.js";
 import { SessionSealLeafStore, type SealCarryLeaf } from "./session-seal-leaf-store.js";
 import type { SealUpgradeReadiness } from "./seal-upgrade.js";
+import type { SealFrontierLeaf } from "./seal-frontier-verify.js";
 import { type SecurityGatewayClient } from "@cello-protocol/gateway";
 /**
  * DOD-CAP-SELF-HEAL-1 — how long an interrupted session keeps consuming a cap slot.
@@ -57,6 +79,15 @@ import { type SecurityGatewayClient } from "@cello-protocol/gateway";
  * span about 2.5 hours.
  */
 export declare const SR_RESERVATION_MAX_RETRIES = 5;
+/**
+ * DOD-M15-RELAYSLOTS-1 — how long an agent skips a relay that refused it for a relay-side fault.
+ *
+ * Ten minutes: long enough that the agent is not re-asking a relay that cannot serve it every time
+ * its receiver rebuilds, short enough that when someone fixes that relay the agent finds it again
+ * without needing its own restart. The fault is on somebody else's machine and nobody tells us when
+ * it is fixed, so this has to expire on its own.
+ */
+export declare const RELAY_QUARANTINE_MS: number;
 export declare const CAP_INTERRUPTED_TTL_MS: number;
 /**
  * DOD-M12B-ABANDON-NOTIFY-1 — what happened when we tried to tell the counterparty we hung up.
@@ -154,6 +185,18 @@ export interface ISessionNodeFactory {
 export interface SessionNodeConfig {
     sessionId: string;
     connectionGater?: SessionConnectionGater;
+    /**
+     * DOD-M15-RELAYONLY-1: this agent has asked never to be directly reachable, so the factory must
+     * omit dcutr from the node's service set.
+     *
+     * ⚠️ NOT a duplicate of filtering the published addresses. Those two things stop DIFFERENT
+     * disclosures: the filter controls what the DIRECTORY is told, and dcutr talks to the peer
+     * directly. Its whole job is to upgrade a relayed connection into a direct one, and the inbound
+     * side starts the upgrade — which is exactly a standing receiver. Leaving it on means the agent
+     * routes over the relay precisely as asked and then hole-punches to a direct connection anyway,
+     * with every test still green because the leak happens inside libp2p after the assertions.
+     */
+    relayOnly?: boolean;
     /**
      * CELLO-M7-TRANSPORT-001: role of the node, forwarded to createNode to tune the
      * libp2p service set (dcutr is included for 'session' dialers, omitted for the
@@ -257,12 +300,63 @@ export declare const REVIVE_RESERVATION_CANDIDATES = 2;
  * the healthy direct latency and far below anything a person would notice.
  */
 export declare const LEAF_FETCH_GRACE_MS = 2000;
+/**
+ * DOD-M15-SEALWIRE-1 bullet 5, SENT half — our own authorship proof for a message we sent.
+ *
+ * Deliberately the SAME shape as the received half's `verifiedAuthorship`, because the transcript
+ * column pair is the same and a second shape would invite a second meaning. What differs is the
+ * ATTRIBUTION the row records: a sent row is `self_authored` (we PRODUCED this signature), never
+ * `verified_signature` (we CHECKED someone else's). Same bytes, different claim.
+ */
+export interface SentAuthorship {
+    senderPubkey: Uint8Array;
+    senderSig: Uint8Array;
+}
 export declare class SessionNodeManager {
     #private;
     setDetachedRelayClientBuilder(fn: (agentName: string, relayPeerId: string, relayAddrs: string[], stores: {
         receiptStore?: RelayReceiptStore;
         sealLeafStore?: SessionSealLeafStore;
+        onlineToken: () => Uint8Array | undefined;
     }) => AgentRelayClient | undefined): void;
+    /**
+     * Record what one relay says it saw on one of this agent's sessions, for the operator to read.
+     *
+     * ⚠️ **IT DOES NOT FREEZE THE SESSION, AND THAT IS THE DESIGN.** A client freezing on its OWN
+     * verification is safe: it limits only what that client trusts. Freezing on a REMOTE party's
+     * say-so hands any single relay the power to end any conversation it carries, and to write an
+     * accusatory record about a counterparty who did nothing. The identity freeze stays where it is —
+     * on this daemon's own check of an inbound frame — and this surfaces a second, independent
+     * observation next to it. One witness reports; it does not rule.
+     */
+    recordRelayWitnessAlert(agentName: string, alert: RelayWitnessAlert): void;
+    /** The witness alerts an agent has been told about, oldest first, one row per witness+session. */
+    getWitnessAlerts(agentName: string): ReadonlyArray<WitnessAlertNotice>;
+    /** Whether this agent's alert list hit its cap, so the inbox can say the list is incomplete. */
+    witnessAlertsTruncated(agentName: string): boolean;
+    /**
+     * Review F7: a relay sent a witness alert this build could not read or could not verify.
+     *
+     * Recorded so a version skew that silently kills the witness layer is visible to the operator
+     * instead of living only in a log file. Carries no session and no party by construction.
+     */
+    recordRelayWitnessUnreadable(agentName: string, relayPeerId: string, why: string): void;
+    /** Relays whose witness alerts this build could not read, for the agent's inbox. */
+    getWitnessUnreadable(agentName: string): ReadonlyArray<{
+        relayPeerId: string;
+        why: string;
+        count: number;
+    }>;
+    /**
+     * Why this agent's standing receiver could not hold a reservation, in words the person running it
+     * can act on — or null when the last attempt succeeded or none has been made.
+     *
+     * This is the surface DoD clause 7 is about: the assertion that matters is what the CLIENT can
+     * show someone, not what the relay wrote in its own log.
+     */
+    getStandingReceiverRefusal(agentName: string): (RelayAuthRefusal & {
+        relayPeerId: string;
+    }) | null;
     /**
      * Record that this session's tree and the relay's counter have provably parted.
      *
@@ -387,6 +481,7 @@ export declare class SessionNodeManager {
         ok: false;
         reason: string;
         cause?: string;
+        retryAfterMs?: number;
     }>): void;
     /**
      * DOD-PARK-DRAIN-1: inject the parked-mailbox drain (daemon.ts → contentPark.autoRecoverForAgent).
@@ -420,6 +515,16 @@ export declare class SessionNodeManager {
      * encrypted DB file.
      */
     getDb(): DaemonDatabase;
+    /**
+     * DOD-M15-RELAYONLY-1: is the settings store readable RIGHT NOW?
+     *
+     * ⚠️ Exists because `getSetting` cannot answer it. That method returns `null` for BOTH "the key is
+     * unset" and "there is no database", and a security setting must tell those apart: unset-means-off
+     * is correct, db-gone-means-off publishes the operator's real address during the shutdown window.
+     * `getDb()` cannot stand in either — it THROWS when there is no database, which on a catch-less
+     * ceremony path is worse than the wrong answer.
+     */
+    hasDatabase(): boolean;
     /**
      * RELAYSIG-1: the durably-stored, signature-verified relay ordering-record receipts for an agent
      * (optionally a single session). Empty when no receipts have been recorded yet. Read-only.
@@ -465,6 +570,30 @@ export declare class SessionNodeManager {
         verdict: "cannot_judge";
         reason: string;
     };
+    /**
+     * WHERE THE MUTUALLY-SIGNED PREFIX ENDS, DERIVED FROM THIS DAEMON'S OWN LEAVES —
+     * `DOD-M15-UNILATERAL-1`, review F2.
+     *
+     * ⚠️ **THE FIRST VERSION COMPUTED THIS FROM THE CERTIFICATE'S OWN PARTICIPANT LIST, AND CALLED
+     * THAT "recomputed, cannot be steered".** It could be steered. On the SOLO path the certificate's
+     * TBS binds no legibility at all, and the client verifies only the *live* party's frontier — so
+     * the absent party's `content_frontier_seq` and every `last_authored_seq` arrived unchecked. One
+     * directory node could publish the absent party's frontier as 3 and the receipt would say
+     * "mutually signed through 3" over a transcript that party never signed for. That is the precise
+     * conflation this field exists to prevent, reintroduced by the field itself.
+     *
+     * The carry answers it without trusting anybody. This daemon holds the counterparty's own leaves,
+     * each carrying, inside the bytes THEY signed, both the sequence they authored and the
+     * `last_seen_seq` they acknowledged. So a party's commitment reaches
+     * `max(highest sequence they authored, highest sequence they acknowledged)`, and the transcript is
+     * mutually signed only as far as the LEAST-committed party reaches.
+     *
+     * Fewer than two distinct authors ⇒ `0`: nobody countersigned anything, which is the honest floor
+     * for a conversation where the other side only ever received. `null` when the carry is empty or
+     * unreadable — the caller must then publish NO boundary rather than fall back to a number
+     * somebody else supplied.
+     */
+    countersignedThroughSeqFromCarry(agentPubkeyHex: string, sessionIdHex: string): number | null;
     getSealCarry(agentPubkeyHex: string, sessionIdHex: string): SealCarryLeaf[];
     /**
      * DOD-LOG-1 / PERSIST-002 (AC-010): append one readable message to the durable transcript, keyed
@@ -1280,6 +1409,46 @@ export declare class SessionNodeManager {
         sealed_root: string;
         legibility: unknown;
     } | null;
+    /**
+     * DOD-M15-INCLUSION-1: keep the leaf set the certificate is signed over, so one message can later
+     * be proved to sit under it.
+     *
+     * REFUSES unless the hashes reproduce `sealedRootHex` — `certifiedLeafSetFrom` does that check and
+     * this method never bypasses it. That is what separates "the leaves the directory sent" from "the
+     * leaves the consortium signed", and only the second is worth storing: a proof built on the first
+     * would inherit whatever the directory chose to say.
+     *
+     * Idempotent (INSERT OR REPLACE keyed on leaf_index) so a re-delivered seal frame, or a unilateral
+     * seal later upgraded to bilateral, rewrites the same rows instead of failing or doubling them.
+     *
+     * @returns whether the set was accepted and stored.
+     */
+    recordCertifiedLeafSet(agentName: string, sessionId: string, signedLeaves: readonly SealFrontierLeaf[], sealedRootHex: string, correlationId?: string): boolean;
+    /**
+     * Record WHY this session does or does not have a certified leaf set.
+     *
+     * Public for the one case the manager cannot see: a seal frame that carried no signed leaves at
+     * all never reaches `recordCertifiedLeafSet`, and that absence is a permanent fact about the
+     * session for the party that observed it.
+     */
+    noteCertifiedLeafSetUnavailable(agentName: string, sessionId: string, state: "not_carried_absent_party" | "not_carried_present_party", detail: string): void;
+    /**
+     * The last thing that happened to this session's certified leaf set, or null if nothing has.
+     *
+     * Null here and a null from `getCertifiedLeafSet` together mean "no seal has been processed on
+     * this side yet" — which is a different sentence again from any of the recorded states.
+     */
+    getCertifiedLeafSetState(agentName: string, sessionId: string): {
+        state: string;
+        detail: string | null;
+    } | null;
+    /**
+     * The certified leaf set, in order, or null when none was stored for this session.
+     *
+     * Null is a REFUSAL upstream, never a fallback to the local tree: the two cover different leaves
+     * and substituting one for the other is how a proof comes to land on a root nobody signed.
+     */
+    getCertifiedLeafSet(agentName: string, sessionId: string): string[] | null;
     /**
      * M7-SESSION-001: Mark a session as interrupted with message count and timestamp.
      * Called when a relay session_interrupted frame arrives or a relay stream closes.
@@ -1289,7 +1458,15 @@ export declare class SessionNodeManager {
      * @param messageCount Number of message leaves at interruption
      * @param source 'relay_frame' | 'stream_close'
      */
-    markInterruptedWithDetails(agentName: string, sessionId: string, messageCount: number, source: "relay_frame" | "stream_close"): Promise<void>;
+    markInterruptedWithDetails(agentName: string, sessionId: string, messageCount: number, 
+    /**
+     * WHAT ACTUALLY HAPPENED, and it is written to the row — review F3.
+     *
+     * `key_refused` is its own source rather than a borrowed `stream_close`, because the row's
+     * `interrupted_by` is what an operator reads days later: labelling a key-authentication refusal
+     * `relay_stream_close` sends them to the relay fleet for a fault in the payload.
+     */
+    source: "relay_frame" | "stream_close" | "key_refused"): Promise<boolean>;
     /**
      * M7-SESSION-001 (H-1): persist a verified bilateral SEAL-INTERRUPTED
      * commitment and transition the session to 'seal_interrupted_pending'.
@@ -1483,12 +1660,25 @@ export declare class SessionNodeManager {
         ok: true;
         delivered: true;
         sequenceNumber?: number;
+        authorship?: SentAuthorship;
     } | {
         ok: true;
         delivered: false;
         parked: true;
         sequenceNumber?: number;
-    } | {
+        authorship?: SentAuthorship;
+    }
+    /**
+     * ⚠️ `authorship` RIDES THE FAILURE PATH TOO — review pass 2, and it is the same reasoning that
+     * already put `sequenceNumber` here.
+     *
+     * A DURABLY QUEUED message was witnessed and SIGNED before delivery was attempted; only the
+     * direct hand-off failed. Omitting the proof here meant every relay-degraded-but-alive send —
+     * the common case — wrote a transcript row indistinguishable from one the relay never saw, while
+     * the signature for it sat in scope and was discarded. The position survives a failed delivery
+     * for exactly this reason; so does the proof.
+     */
+     | {
         ok: false;
         reason: string;
         error: string;
@@ -1496,6 +1686,7 @@ export declare class SessionNodeManager {
         cause?: string;
         guidance?: string;
         sequenceNumber?: number;
+        authorship?: SentAuthorship;
     }>;
     /**
      * M7 DOD-SPINE-7: submit THIS party's SEAL ctrl leaf (0x02) to the relay witness.
@@ -1789,7 +1980,35 @@ export declare class SessionNodeManager {
      * and it appends in arrival order as before: with no position there is no discipline to enforce,
      * and refusing would take messaging down whenever the relay is unreachable.
      */
-    placeOwnLeaf(agentName: string, sessionId: string, contentHashHex: string, sentBytes: Uint8Array, assignedSeq: number | undefined, correlationId?: string, kind?: WritableSessionTreeLeafKind): {
+    placeOwnLeaf(agentName: string, sessionId: string, contentHashHex: string, sentBytes: Uint8Array, assignedSeq: number | undefined, correlationId: string | undefined, 
+    /**
+     * ⚠️ NO DEFAULT, for the same reason `authorship` has none.
+     *
+     * `kind = "msg"` meant a caller writing a `doc` or a `ctrl` leaf got a `msg` leaf by saying
+     * nothing, and the tree recorded a leaf kind the author never chose. TypeScript also forbids a
+     * required parameter after a defaulted one, so leaving the default here would have forced
+     * `authorship` back to optional — which is the defect above. Every one of the seven call sites
+     * already passed a kind or wanted "msg"; making it explicit cost nothing and removes a second
+     * silent answer from the same signature.
+     */
+    kind: WritableSessionTreeLeafKind, 
+    /**
+     * DOD-M15-SEALWIRE-1 bullet 5 — the proof for THIS send, so a held row keeps it.
+     *
+     * ⚠️ REQUIRED, AND `undefined` IS A VALID ANSWER — the two are not the same thing.
+     *
+     * This was `authorship?:` for exactly one review cycle, and in that cycle THREE of the seven
+     * call sites omitted it: `daemon.ts` 1440, 1671, 1685 — the away-reply path, which is the
+     * highest-traffic sent-writer in the daemon and the one with no human watching it. All three
+     * had the proof **already in a local variable one line below**, handed to
+     * `recordTranscriptMessage` and not to this method. Nothing went red, because an optional
+     * parameter's whole behaviour on omission is to look deliberate.
+     *
+     * An unwitnessed send genuinely has no proof, so absence must stay expressible. Requiring the
+     * parameter keeps that while making the caller SAY it: omission is now a type error, and
+     * `undefined` is a claim the author made rather than one the signature made for them.
+     */
+    authorship: SentAuthorship | undefined): {
         placed: true;
         leafIndex: number;
         diverged?: true;
@@ -1882,6 +2101,19 @@ export declare class SessionNodeManager {
      * record (the recover handler lives in daemon.ts, which has no access to the private method).
      */
     recordOrderingRecord(agentName: string, sessionId: string, structure1Cbor: Uint8Array, structure2Cbor: Uint8Array, contentHash: Uint8Array, correlationId?: string): number | null;
+    /**
+     * Test seam: see every decoded inbound content frame, as it arrived.
+     *
+     * Review F4. The "bytes on the wire are ciphertext" claim needs the ACTUAL frame; asserting on a
+     * freshly sealed stand-in tests the crypto primitive and stays green when the send path is
+     * reverted to putting plaintext on the wire. There is no other way to reach the decoded frame from
+     * outside — the handler consumes it and hands ingest the plaintext.
+     *
+     * Read-only by construction: the callback receives the frame and cannot influence routing.
+     */
+    observeInboundContentFramesForTest(cb: (frame: Record<string, unknown>) => void): void;
+    /** Injected by the daemon once its per-agent key providers exist. See `#keyProviderResolver`. */
+    setKeyProviderResolver(resolver: (agentName: string) => KeyProvider | undefined): void;
     /**
      * Test seam: force this session's own salt half, so the LOCAL-defect path is reachable.
      *
@@ -1907,6 +2139,97 @@ export declare class SessionNodeManager {
      */
     runAutoAcknowledgeGateForTest(agentName: string, sessionId: string, correlationId?: string): void;
     setSaltContributionForTest(agentName: string, sessionId: string, contribution: Uint8Array): void;
+    /**
+     * Test seams: re-enter the mint path, and read back the PUBLIC half — 006-CRYPTO.
+     *
+     * `#mintSessionEphemeral` is idempotent because a reconnect can re-enter an activation path, and a
+     * second keypair mid-session would leave the two sides deriving against a moving value. Proving
+     * that needs the path called TWICE, and the alternative — driving a real reconnect — drags in node
+     * rebuild and relay reconnection, none of which the property is about. Same justification as
+     * `forgetSaltContributionForTest` above.
+     *
+     * It calls the REAL private method, so a test cannot pass against a decision production does not
+     * make. The reader returns the public half ONLY: a seam that could hand out the secret is a way
+     * for the secret to leave this object, which is the one thing the whole unit is about.
+     */
+    mintSessionEphemeralForTest(agentName: string, sessionId: string): void;
+    sessionEphemeralPublicForTest(agentName: string, sessionId: string): Uint8Array | null;
+    /**
+     * Test seam: INSTALL a keypair the caller already holds — the only way to prove ZEROING.
+     *
+     * Presence is easy to assert and is not the property. `destroySessionEphemeral` overwrites the
+     * buffer before the entry is dropped, and a mutant that drops without overwriting leaves the
+     * secret wherever the collector last moved it while passing every presence check — which is
+     * exactly what happened: the shutdown zeroing shipped with a surviving mutant, and the transport
+     * seeds four lines above it have the same untested gap today.
+     *
+     * The direction matters. Nothing here HANDS OUT a secret — the test supplies an object it already
+     * owns and then inspects its own reference. A reader that returned the live keypair would be a
+     * path for the secret to leave this object, which is the one thing this unit exists to prevent.
+     */
+    setSessionEphemeralForTest(agentName: string, sessionId: string, ephemeral: SessionEphemeral): void;
+    /**
+     * Test seam: put a session into the state a COMPLETED exchange leaves it in — 007-CRYPTO.
+     *
+     * A live send now requires an agreed key, because there is no plaintext path to fall back to. In
+     * production the exchange completes on connect, before any send. A fixture with no real peer never
+     * completes it, so without this every content test in the repo would be exercising the refusal
+     * path instead of the thing it was written for.
+     *
+     * ⚠️ IT SHORT-CIRCUITS HOW THE KEY GOT THERE, NEVER WHAT THE KEY IS FOR. The state it produces —
+     * a session holding an agreed content key — is exactly the production state, which is what makes
+     * it legitimate; `setSaltContributionForTest` exists for the same reason. Tests of the EXCHANGE
+     * itself drive the real signed frames and must not use this.
+     */
+    setSessionContentKeyForTest(agentName: string, sessionId: string, key: Uint8Array): void;
+    /**
+     * Test seam: drop the agreed key while leaving the session up — the state before an exchange
+     * completes, and after a teardown evicts one. Its mirror above is what a completed exchange
+     * leaves; both are needed, or a status field stuck in one position passes either test alone.
+     */
+    forgetSessionContentKeyForTest(agentName: string, sessionId: string): void;
+    /**
+     * Test seam: produce THIS side's signed ephemeral, using the manager's own identity resolver.
+     *
+     * For harnesses whose connectivity is one-directional — one side dials, so only one announce ever
+     * lands. Carrying the other side's half across with a REAL signature is what completes the
+     * exchange, and it beats seeding a key: a seeded key has no peer half recorded against it, so the
+     * first genuine announce replaces it and the two ends drift apart (which is correct behaviour —
+     * see the re-key guard — and exactly what made seeding fragile here).
+     *
+     * It signs with the same provider production signs with, so a test cannot pass against a signature
+     * production would have refused.
+     */
+    signOwnEphemeralForTest(agentName: string, sessionId: string): Promise<{
+        ephemeralPublic: Uint8Array;
+        signature: Uint8Array;
+    } | null>;
+    /**
+     * Test seam: deliver a peer's signed ephemeral, exactly as the content-stream decoder does.
+     *
+     * For harnesses whose connectivity is one-directional — one side dials, so only one announce ever
+     * lands — this is what completes the exchange instead of stuffing a key in. It runs the REAL
+     * verification and the REAL derivation, so a test cannot pass against a signature production would
+     * have refused.
+     */
+    handleEphemeralFrameForTest(agentName: string, sessionId: string, frame: {
+        ephemeralPublic?: Uint8Array;
+        signature?: Uint8Array;
+    }, correlationId?: string): Promise<void>;
+    /**
+     * Test seam: deliver an inbound salt frame, exactly as the content-stream decoder does.
+     *
+     * 006-CRYPTO finding 2. WHICH of the four reasons the peer gave decides what the operator is told,
+     * and reaching that decision from a test otherwise needs a second live daemon that has closed
+     * adoption for a specific reason — which is not something a counterparty can be asked to do on
+     * demand. The four labels are the whole point of the finding, so they need to be reachable.
+     *
+     * It calls the REAL private handler rather than reproducing its routing, so a test cannot pass
+     * against a decision production does not make. It takes the DECODED frame, so it deliberately
+     * does NOT stand in for the decoder above it — the length and vocabulary checks there have their
+     * own tests driving `handleContentFrameForTest`.
+     */
+    handleSaltFrameForTest(agentName: string, sessionId: string, frame: SaltAgreementFrame, correlationId?: string): Promise<void>;
     /**
      * Test seam: drop this session's own half while leaving the stored salt in place — the state every
      * teardown produces, because `#evictSessionCaches` clears the map and the row survives.
@@ -1995,7 +2318,49 @@ export declare class SessionNodeManager {
      * Read-only and cache-backed, so exposing it adds no way to CHANGE the salt from outside — the
      * only writer remains `#persistSessionSalt`, behind the one-salt-per-session predicate.
      */
+    /**
+     * IS THIS SESSION ACTUALLY PROTECTED BY ITS SALT RIGHT NOW — pass 2, F3.
+     *
+     * Distinct from `getSessionContentSalt`, which is POSSESSION and is what the verifier needs: a
+     * message parked before suspension was hashed under this salt and must still be checkable against
+     * it, so that accessor must keep answering with the bytes.
+     *
+     * This one answers the OPERATOR's question, and it is a different question. A suspended session
+     * holds a salt it will not use, so every hash it produces is `sha256` — reporting `contentSalted:
+     * true` there is not a gap, it is an affirmatively false security claim on the surface whose own
+     * comment reads *"a security property must not be inferable from a gap."* Same predicate
+     * `#saltForHashing` uses, so the flag cannot drift from the behaviour it describes.
+     */
+    isContentSaltActive(agentName: string, sessionId: string): boolean;
     getSessionContentSalt(agentName: string, sessionId: string): Uint8Array | null;
+    /**
+     * THE SALT, OR WHY THERE ISN'T ONE — `DOD-M15-INCLUSION-1`, fallback-finder finding 2.
+     *
+     * `getSessionContentSalt` above answers `null` for THREE different situations, and a caller that
+     * turns that null into a sentence for an operator gets two of them wrong:
+     *
+     *   `none`       — no salt was ever agreed. The session really is unsalted.
+     *   `unreadable` — a salt row EXISTS and could not be used: the wrong width (corruption on this
+     *                  operator's own disk), or the read threw.
+     *
+     * The distinction is not cosmetic. `unreadable` means the session's leaves WERE hashed under a
+     * salt, so telling its operator *"this session's content hashes are UNSALTED … start a session
+     * while you are both connected"* is an affirmatively false statement about a security property
+     * their session has, and it points them at their counterparty over damage to their own database.
+     * That is the same defect `#getSessionSalt`'s own F8 note was written to end, re-committed one
+     * surface out.
+     *
+     * ⚠️ IT DELEGATES — there is no second read here. Calling `#getSessionSalt` first means the salt
+     * this reports is the salt the hashing path uses, including its cache and its wrong-width refusal.
+     * A parallel query would be free to disagree with it, which is the whole failure this returns a
+     * reason to prevent.
+     */
+    getSessionContentSaltState(agentName: string, sessionId: string): {
+        salt: Uint8Array;
+    } | {
+        salt: null;
+        reason: "none" | "unreadable";
+    };
     /**
      * M7-SESSION-001 AC-004/AC-005: Register a relay stream for an active session.
      * Starts a background reader that watches for session_interrupted frames and
@@ -2012,6 +2377,19 @@ export declare class SessionNodeManager {
      *   receipt may differ, but this is the value available at stream setup time)
      */
     registerRelayStream(agentName: string, sessionId: string, stream: Stream, messageCount?: number): void;
+    /**
+     * DOD-M15-RELAYSLOTS-1: accept the directory's online token for an agent. Called on every
+     * signaling connect and reconnect, which is what keeps it fresh.
+     */
+    setDirectoryOnlineToken(agentName: string, token: Uint8Array): void;
+    setDirectoryOnlineTokenAbsent(agentName: string, reason: "not_registered_here" | "issue_failed" | undefined): void;
+    /**
+     * The current token, or `undefined` when the directory has not issued one — either no directory
+     * connection yet, or this key has no agent profile there. Undefined is a real answer, not a
+     * missing one: the relay refuses without a token, which is the intended outcome for a key the
+     * directory does not recognise.
+     */
+    getDirectoryOnlineToken(agentName: string): Uint8Array | undefined;
     /**
      * DOD-NAT-REACHABILITY-1 (Phase 2): accept the directory's relay-pool endpoints
      * for an agent (arrives with signaling_auth_ok, i.e. on every connect AND every
@@ -2024,6 +2402,11 @@ export declare class SessionNodeManager {
         relayPeerId: string;
         relayAddrs: string[];
     }>): void;
+    /**
+     * Is this agent currently skipping this relay? The observable half of the failover decision — a
+     * test that asserts only on the classifier's boolean proves nothing about what the daemon does.
+     */
+    isRelayQuarantined(agentName: string, relayPeerId: string): boolean;
     /**
      * DOD-M12B-SESSION-SEED-1 — bring an interrupted session back on the peer id it already has.
      *