fix(sdk): address CodeRabbit runtime bridge and docs findings

sdk/src/gsd-tools.ts

@@ -78,7 +78,7 @@ export class GSDTools {
       execJsonFallback: (legacyCommand, legacyArgs) => this.exec(legacyCommand, legacyArgs),
       execRawFallback: (legacyCommand, legacyArgs) => this.execRaw(legacyCommand, legacyArgs),
       strictSdk: opts.strictSdk,
-      allowFallbackToSubprocess: opts.allowFallbackToSubprocess ?? false,
+      allowFallbackToSubprocess: opts.allowFallbackToSubprocess,
       onDispatchEvent: opts.onDispatchEvent,
     });
 

sdk/src/gsd-transport.ts

@@ -54,7 +54,6 @@ export class GSDTransport {
       }
     } else {
       const reason = this.subprocessReason(request, policy);
-      onDecision?.({ dispatchMode: 'subprocess', reason });
       if (!policy.allowFallbackToSubprocess && reason === 'native_unregistered') {
         throw GSDToolsError.failure(
           `Subprocess fallback disabled: command '${request.registryCommand}' cannot run without native dispatch`,
@@ -63,6 +62,7 @@ export class GSDTransport {
           null,
         );
       }
+      onDecision?.({ dispatchMode: 'subprocess', reason });
     }
 
     return this.dispatchSubprocess(request);
@@ -77,7 +77,10 @@ export class GSDTransport {
     if (request.workstream) return 'workstream_forced';
     if (!policy.preferNative) return 'native_not_preferred';
     if (!this.registry.has(request.registryCommand)) return 'native_unregistered';
-    return 'native_not_preferred';
+
+    throw new Error(
+      `Unexpected subprocess reason state for command '${request.registryCommand}' with preferNative=${String(policy.preferNative)} and workstream=${String(request.workstream)}`,
+    );
   }
 
   private shouldRethrowNativeError(error: unknown, policy: TransportPolicyLike): boolean {

sdk/src/query-runtime-bridge.ts

@@ -40,14 +40,12 @@ export interface RuntimeBridgeHotpathEvent {
   errorKind?: 'timeout' | 'failure';
 }
 
-export interface RuntimeBridgeEvent {
-  type: 'query_dispatch' | 'query_hotpath_dispatch';
-}
+export type RuntimeBridgeEvent = RuntimeBridgeDispatchEvent | RuntimeBridgeHotpathEvent;
 
 export interface RuntimeBridgeOptions {
   strictSdk?: boolean;
   allowFallbackToSubprocess?: boolean;
-  onDispatchEvent?: (event: RuntimeBridgeDispatchEvent | RuntimeBridgeHotpathEvent) => void;
+  onDispatchEvent?: (event: RuntimeBridgeEvent) => void;
 }
 
 /**
@@ -71,6 +69,14 @@ export class QueryRuntimeBridge {
     return resolveQueryCommand(command, args, this.registry);
   }
 
+  private emit(event: RuntimeBridgeEvent): void {
+    try {
+      this.options?.onDispatchEvent?.(event);
+    } catch {
+      // Observability must never break dispatch behavior.
+    }
+  }
+
   async execute(input: RuntimeBridgeExecuteInput): Promise<unknown> {
     const startedAt = Date.now();
     if (this.options?.strictSdk && !this.registry.has(input.registryCommand)) {
@@ -80,12 +86,12 @@ export class QueryRuntimeBridge {
         input.legacyArgs,
         null,
       );
-      this.options?.onDispatchEvent?.({
+      this.emit({
         type: 'query_dispatch',
         command: input.registryCommand,
         legacyCommand: input.legacyCommand,
         mode: input.mode,
-        dispatchMode: 'subprocess',
+        dispatchMode: 'native',
         reason: 'native_unregistered',
         durationMs: Date.now() - startedAt,
         outcome: 'error',
@@ -111,7 +117,7 @@ export class QueryRuntimeBridge {
         },
       });
 
-      this.options?.onDispatchEvent?.({
+      this.emit({
         type: 'query_dispatch',
         command: input.registryCommand,
         legacyCommand: input.legacyCommand,
@@ -124,7 +130,7 @@ export class QueryRuntimeBridge {
       return result;
     } catch (error) {
       const kind = error instanceof GSDToolsError ? error.classification.kind : 'failure';
-      this.options?.onDispatchEvent?.({
+      this.emit({
         type: 'query_dispatch',
         command: input.registryCommand,
         legacyCommand: input.legacyCommand,
@@ -155,7 +161,7 @@ export class QueryRuntimeBridge {
         registryArgs,
         mode,
       );
-      this.options?.onDispatchEvent?.({
+      this.emit({
         type: 'query_hotpath_dispatch',
         command: registryCommand,
         legacyCommand,
@@ -167,7 +173,7 @@ export class QueryRuntimeBridge {
       return result;
     } catch (error) {
       const kind = error instanceof GSDToolsError ? error.classification.kind : 'failure';
-      this.options?.onDispatchEvent?.({
+      this.emit({
         type: 'query_hotpath_dispatch',
         command: registryCommand,
         legacyCommand,