Merge pull request #528: feat(tabs): place new, child and web tabs into groups

Conflict resolved in docs/api-reference.md: #607's prompt cache section and
#528's tabGroupId section are both kept.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/web/server.ts

@@ -59,7 +59,8 @@ import { RespawnController, RespawnConfig } from '../respawn-controller.js';
 import type { TerminalMultiplexer } from '../mux-interface.js';
 import { createMultiplexer } from '../mux-factory.js';
 import { getStore } from '../state-store.js';
-import { TabLayoutService } from '../tab-layout-service.js';
+import { TabLayoutService, type SessionPlacementHint } from '../tab-layout-service.js';
+import type { TabLayout } from '../tab-layout.js';
 import { ownerLayoutKey } from '../tab-layout-persistence.js';
 import { readWebviews } from '../webview-store.js';
 import { extractCompletionPhrase } from '../ralph-config.js';
@@ -463,6 +464,9 @@ export class WebServer extends EventEmitter {
         this.cachedLightState = null;
         this.sse.broadcastSessionOrder(change);
       },
+      // Fresh, not the 2s cache: the settings PUT does not invalidate it, and a
+      // flip must apply to the very next spawn.
+      childrenFollowParent: async () => (await this.readSettings(true)).spawnedTabsFollowParent === true,
     });
     if (this.testMode) this.tabLayouts.markRestorationSkipped();
 
@@ -715,15 +719,19 @@ export class WebServer extends EventEmitter {
     }
   }
 
-  /** Add a tentative session only after its owner layout accepts the creation. */
-  private async registerSessionWithLayout(session: Session): Promise<void> {
-    this.sessions.set(session.id, session);
-    try {
-      await this.tabLayouts.sessionCreated(ownerLayoutKey(session.owner));
-    } catch (error) {
-      this.sessions.delete(session.id);
-      throw error;
-    }
+  /**
+   * Add a tentative session only after its owner layout accepts the creation.
+   * The session enters the live map inside the layout service's owner lock, so
+   * the placement it asked for (`tabGroupId`) lands in the same versioned write
+   * that first records it.
+   */
+  private async registerSessionWithLayout(session: Session, placement?: SessionPlacementHint): Promise<TabLayout> {
+    return this.tabLayouts.sessionCreated(ownerLayoutKey(session.owner), session.id, placement, () => {
+      this.sessions.set(session.id, session);
+      return () => {
+        if (this.sessions.get(session.id) === session) this.sessions.delete(session.id);
+      };
+    });
   }
 
   /**