fix(cookbook): review round 4 - logout releases the nonce guard

C1: the busy guard added in round 3 had no release path. Logging out while
a submission was tracking dropped the sdk-dapp session, so the terminal
callbacks could never fire and the page stayed locked forever. A regression
from the round-3 fix, not a pre-existing issue.

SendEgldLifecycle gains abandon(reason), which releases the guard and clears
the stored output and early terminal so a callback from the dropped session
cannot resurrect the abandoned submission after reconnecting. Its doc comment
states that the broadcast transaction may still be pending and the caller must
refresh the account nonce before sending again; clearing busy alone would
reintroduce the stale-nonce bug the guard exists to prevent. Adds an isBusy
getter so the guard state is inspectable.

Disconnect is guarded twice: the button is disabled while signing or tracking
with an explanatory tooltip, and handleLogout() returns early on the same
condition so a programmatic caller cannot bypass the UI.

Test added: tracking -> logout -> stale callback ignored -> login -> send
accepted -> done.

C2: the SendEgldOutput comment now says sessionId keys the
...TransactionsSessions() maps and identifies the per-session callbacks,
and names the flat hooks as taking no session id.

Verified on Node 20.19.0: advisory gate green (harness plus all five fresh
environments), 11/11 extractor tests, 4/4 lifecycle tests, strict TypeScript,
61/61 projects built, 8/8 Vite and 2/2 Next production builds, clean
Docusaurus build with no new broken links.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lamentierschweinchen

docs/sdk-and-tools/sdk-js/cookbook/start-here/sign-and-send.mdx

@@ -404,8 +404,10 @@ export interface SendEgldInput {
 }
 
 /**
- * Output of a successful sign + send + track call. The sessionId is the key
- * the React hooks (useGetPendingTransactions, etc.) use to render UI state.
+ * Output of a successful sign + send + track call. The sessionId keys the
+ * ...TransactionsSessions() maps and identifies the per-session success and
+ * failure callbacks. The flat hooks (useGetPendingTransactions and friends)
+ * take no session id and return global arrays.
  */
 export interface SendEgldOutput {
   sessionId: string;
@@ -700,6 +702,34 @@ export class SendEgldLifecycle {
     }
   }
 
+  /** True while a submission holds the nonce guard. */
+  public get isBusy(): boolean {
+    return this.busy;
+  }
+
+  /**
+   * Release the guard when the tracked session can no longer reach a terminal
+   * state, which is what happens on logout: sdk-dapp resets its store, drops
+   * the session, and the success and failure callbacks registered for it can
+   * never fire again.
+   *
+   * The broadcast transaction may still be pending on the network, so the
+   * caller MUST refresh the account nonce from the network before submitting
+   * anything else. Releasing the guard without that refresh is exactly how the
+   * stale-nonce bug returns.
+   */
+  public abandon(reason: string): void {
+    this.busy = false;
+    this.output = null;
+    this.earlyTerminal = null;
+    this.transition({
+      status: 'error',
+      sessionId: null,
+      transactionHash: null,
+      error: reason,
+    });
+  }
+
   private finish(terminal: TerminalState): void {
     if (!this.busy) {
       return;
@@ -762,6 +792,8 @@ export interface UseSendEgld {
   state: SendEgldState;
   send: (input: SendEgldInput) => Promise<SendEgldOutput | null>;
   reset: () => void;
+  /** Release the nonce guard when the tracked session is gone (logout). */
+  abandon: (reason: string) => void;
 }
 
 export function useSendEgld(): UseSendEgld {
@@ -782,7 +814,11 @@ export function useSendEgld(): UseSendEgld {
     lifecycleRef.current?.reset();
   }, []);
 
-  return { state, send, reset };
+  const abandon = useCallback((reason: string): void => {
+    lifecycleRef.current?.abandon(reason);
+  }, []);
+
+  return { state, send, reset, abandon };
 }
 ```
 
@@ -820,7 +856,7 @@ export default function SendPage(): JSX.Element {
   const isLoggedIn = useGetIsLoggedIn();
   const account = useGetAccount();
   const { network } = useGetNetworkConfig();
-  const { state, send, reset } = useSendEgld();
+  const { state, send, reset, abandon } = useSendEgld();
 
   // useGetPendingTransactions() returns SignedTransactionType[] — a flat
   // array of currently-pending transactions, NOT a sessionId-keyed map (see
@@ -845,8 +881,19 @@ export default function SendPage(): JSX.Element {
   };
 
   const handleLogout = async (): Promise<void> => {
+    // Logging out mid-submission drops the tracked session inside sdk-dapp, so
+    // the terminal callbacks can never fire and the nonce guard would stay
+    // held forever. Refuse while a submission is active; the button is
+    // disabled too, but a programmatic caller must not get past this either.
+    if (isSubmissionPending) {
+      return;
+    }
     const provider = getAccountProvider();
     await provider.logout();
+    // Nothing is in flight here, so releasing the guard is safe. If you add a
+    // force-disconnect path later, call abandon() and then refresh the account
+    // nonce from the network before allowing another send.
+    abandon('Disconnected.');
   };
 
   const handleSubmit = async (e: React.FormEvent): Promise<void> => {
@@ -893,6 +940,12 @@ export default function SendPage(): JSX.Element {
             onClick={() => {
               void handleLogout();
             }}
+            disabled={isSubmissionPending}
+            title={
+              isSubmissionPending
+                ? 'Wait for the current transaction to settle before disconnecting.'
+                : undefined
+            }
             style={{ ...buttonStyle, marginBottom: '1.5rem' }}
           >
             Disconnect

testing/cookbook-ts/sign-and-send-lifecycle.runtime.ts

@@ -107,3 +107,65 @@ test("rejects a second rapid submission until the first session is terminal", as
   await callbacks?.onSuccess(output.sessionId);
   assert.equal(lifecycle.getState().status, "done");
 });
+
+test("logout while tracking releases the guard and a later send is accepted", async () => {
+  const states: SendEgldState[] = [];
+  const lifecycle = new SendEgldLifecycle((next) => states.push(next));
+  const sent = deferred<SendEgldOutput>();
+  let callbacks: SendEgldCallbacks | undefined;
+  let operationCalls = 0;
+
+  const operation = async (
+    _input: SendEgldInput,
+    registered: SendEgldCallbacks,
+  ): Promise<SendEgldOutput> => {
+    operationCalls += 1;
+    callbacks = registered;
+    return sent.promise;
+  };
+
+  const first = lifecycle.send(input, operation);
+  sent.resolve(output);
+  assert.deepEqual(await first, output);
+  assert.equal(lifecycle.getState().status, "tracking");
+  assert.equal(lifecycle.isBusy, true);
+
+  // Logging out drops the tracked session inside sdk-dapp: the terminal
+  // callbacks registered for it can never fire again. Without abandon() the
+  // guard would stay held and the page would be permanently locked.
+  lifecycle.abandon("Disconnected.");
+
+  assert.equal(lifecycle.isBusy, false);
+  assert.equal(lifecycle.getState().status, "error");
+  assert.equal(lifecycle.getState().error, "Disconnected.");
+  assert.equal(lifecycle.getState().sessionId, null);
+
+  // The stale session's callback must not resurrect the abandoned submission.
+  await callbacks?.onSuccess(output.sessionId);
+  assert.equal(lifecycle.getState().status, "error");
+
+  // After reconnecting, the page works again.
+  const afterLogin = deferred<SendEgldOutput>();
+  const secondOutput: SendEgldOutput = {
+    sessionId: "session-2",
+    transactionHash: "hash-2",
+  };
+  const secondOperation = async (
+    _input: SendEgldInput,
+    registered: SendEgldCallbacks,
+  ): Promise<SendEgldOutput> => {
+    operationCalls += 1;
+    callbacks = registered;
+    return afterLogin.promise;
+  };
+
+  const second = lifecycle.send(input, secondOperation);
+  afterLogin.resolve(secondOutput);
+  assert.deepEqual(await second, secondOutput);
+  assert.equal(operationCalls, 2);
+  assert.equal(lifecycle.getState().status, "tracking");
+
+  await callbacks?.onSuccess(secondOutput.sessionId);
+  assert.equal(lifecycle.getState().status, "done");
+  assert.ok(states.length > 0);
+});