CB-108: worker placement — one tab per worker in a dedicated worker space

Workers now land in their own herdr tab inside a dedicated, shared "worker
space" (workspace.create → tab.create → agent.start{tab_id} → close seed shell
→ rename), instead of splitting the user's currently-focused tab. Placement is
configurable (worker.placement tab|pane, worker.workspace, worker.tabLabel);
a future per-session space is just a distinct label.

New: Workspace/Tab records, WorkspaceControl over workspace.*/tab.*,
AgentControl.start tab_id overload, Agent.tabId.

Lifecycle carefulness:
- ensureWorkspace is a synchronized find-or-create (never double-creates)
- teardown closes the tab ONLY when the worker is its sole pane (never a
  shared user tab), resolving the tab via pane.get before closing
- tolerance is precise: only *_not_found is swallowed; real failures surface
- spawn failure closes the orphan tab; post-start cosmetic steps can't orphan
  a live worker or fail the spawn
- unique per-worker names (claude-<profile>-<nonce>-<seq>) with retry: herdr
  rejects duplicate agent names, and the per-process nonce survives a restart
  with lingering workers

herdr facts pinned: agent.start honors tab_id; agent name must be unique;
kind/status are detected from terminal output, not the name.

Reviewed at high effort (multi-agent); all findings addressed. 34 tests green
(29 unit/acceptance + 5 contract vs live herdr 0.7.0). Also bumps wiki.

bridged/src/test/java/dev/ltms/bridged/herdr/FakeHerdr.java

@@ -19,12 +19,46 @@ public final class FakeHerdr implements HerdrClient {
     private final ObjectMapper mapper = new ObjectMapper();
     public final List<Call> calls = new ArrayList<>();
     private boolean healthy = true;
+    private final List<String> extraWorkspaces = new ArrayList<>();
+    private int agentNameTakenFor = 0;
+    private int workerTabPaneCount = 1;
+    private String paneCloseErrorCode = null;
 
     public FakeHerdr healthy(boolean h) {
         this.healthy = h;
         return this;
     }
 
+    /** Reject the first {@code n} {@code agent.start} calls with {@code agent_name_taken}. */
+    public FakeHerdr agentNameTakenTimes(int n) {
+        this.agentNameTakenFor = n;
+        return this;
+    }
+
+    /** Make the worker tab (w9:t2) report this many panes in {@code tab.list} (default 1). */
+    public FakeHerdr withWorkerTabPaneCount(int n) {
+        this.workerTabPaneCount = n;
+        return this;
+    }
+
+    /** Make {@code pane.close} fail with this herdr error code. */
+    public FakeHerdr paneCloseFailsWith(String code) {
+        this.paneCloseErrorCode = code;
+        return this;
+    }
+
+    private long callCount(String method) {
+        return calls.stream().filter(c -> c.method().equals(method)).count();
+    }
+
+    /** Seed an additional workspace into {@code workspace.list} (e.g. a pre-existing worker space). */
+    public FakeHerdr withWorkspace(String id, String label) {
+        extraWorkspaces.add(("{\"workspace_id\":\"%s\",\"label\":\"%s\",\"focused\":false,"
+                + "\"pane_count\":1,\"active_tab_id\":\"%s:t1\",\"agent_status\":\"unknown\"}")
+                .formatted(id, label, id));
+        return this;
+    }
+
     public boolean called(String method) {
         return calls.stream().anyMatch(c -> c.method().equals(method));
     }
@@ -42,22 +76,60 @@ public final class FakeHerdr implements HerdrClient {
             return switch (method) {
                 case "ping" -> mapper.readTree(
                         "{\"type\":\"pong\",\"version\":\"0.7.0\",\"protocol\":14}");
-                case "workspace.list" -> mapper.readTree("""
+                case "workspace.list" -> mapper.readTree(("""
                         {"type":"workspace_list","workspaces":[
                           {"workspace_id":"w1","label":"dev-mgnl","focused":true,"pane_count":7,"agent_status":"unknown"},
-                          {"workspace_id":"w2","label":"ltms","focused":false,"pane_count":5,"agent_status":"done"}]}""");
+                          {"workspace_id":"w2","label":"ltms","focused":false,"pane_count":5,"agent_status":"done"}%s]}""")
+                        .formatted(extraWorkspaces.isEmpty() ? "" : "," + String.join(",", extraWorkspaces)));
                 case "agent.list" -> mapper.readTree("""
                         {"type":"agent_list","agents":[
                           {"terminal_id":"term_a","agent":"claude","agent_status":"idle",
                            "agent_session":{"kind":"id","value":"sess-1111"},
                            "workspace_id":"w2","tab_id":"w2:t7","pane_id":"w2:p7"}]}""");
-                case "agent.start" -> mapper.readTree("""
+                case "agent.start" -> {
+                    if (callCount("agent.start") <= agentNameTakenFor) {
+                        throw new HerdrException(
+                                "herdr error [agent_name_taken]: agent name already used",
+                                "agent_name_taken", null);
+                    }
+                    yield mapper.readTree("""
                         {"type":"agent_started","agent":{
                           "terminal_id":"term_new","name":"claude","agent_status":"unknown",
-                          "workspace_id":"w2","tab_id":"w2:t9","pane_id":"w2:pZ"}}""");
-                case "pane.close" -> mapper.readTree("{\"type\":\"ok\"}");
+                          "workspace_id":"w9","tab_id":"w9:t2","pane_id":"w9:pW"}}""");
+                }
+                case "workspace.create" -> mapper.readTree("""
+                        {"type":"workspace_created",
+                         "workspace":{"workspace_id":"w9","label":"bridged-workers","focused":false,
+                           "pane_count":1,"tab_count":1,"active_tab_id":"w9:t1","agent_status":"unknown"},
+                         "tab":{"tab_id":"w9:t1","workspace_id":"w9","label":"1","pane_count":1},
+                         "root_pane":{"pane_id":"w9:p1","workspace_id":"w9","tab_id":"w9:t1"}}""");
+                case "tab.create" -> mapper.readTree("""
+                        {"type":"tab_created",
+                         "tab":{"tab_id":"w9:t2","workspace_id":"w9","label":"2","pane_count":1},
+                         "root_pane":{"pane_id":"w9:pRoot","workspace_id":"w9","tab_id":"w9:t2"}}""");
+                case "tab.rename" -> mapper.readTree("""
+                        {"type":"tab_info","tab":{"tab_id":"w9:t2","workspace_id":"w9",
+                          "label":"worker: ltms-local","pane_count":1}}""");
+                case "tab.list" -> mapper.readTree(("""
+                        {"type":"tab_list","tabs":[
+                          {"tab_id":"w9:t1","workspace_id":"w9","label":"1","pane_count":1},
+                          {"tab_id":"w9:t2","workspace_id":"w9","label":"worker: ltms-local","pane_count":%d}]}""")
+                        .formatted(workerTabPaneCount));
+                case "tab.close" -> mapper.readTree("{\"type\":\"ok\"}");
+                case "pane.get" -> mapper.readTree("""
+                        {"type":"pane_info","pane":{"pane_id":"w9:pW","workspace_id":"w9",
+                          "tab_id":"w9:t2","agent_status":"idle"}}""");
+                case "pane.close" -> {
+                    if (paneCloseErrorCode != null) {
+                        throw new HerdrException("herdr error [" + paneCloseErrorCode + "]: pane.close failed",
+                                paneCloseErrorCode, null);
+                    }
+                    yield mapper.readTree("{\"type\":\"ok\"}");
+                }
                 default -> throw new HerdrException("fake has no canned response for " + method);
             };
+        } catch (HerdrException e) {
+            throw e; // intentional protocol errors (e.g. agent_name_taken) propagate with their code
         } catch (Exception e) {
             throw new HerdrException("fake decode failed for " + method, e);
         }

bridged/src/test/java/dev/ltms/bridged/herdr/WorkspacePlacementContractTest.java

@@ -0,0 +1,88 @@
+package dev.ltms.bridged.herdr;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Files;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+/**
+ * Contract test for the placement layer ({@code workspace.*}/{@code tab.*}) against a
+ * REAL herdr, locking in the "one clean tab per worker" recipe: find-or-create a worker
+ * space, give the worker its own tab, drop herdr's seed shell so the tab holds only the
+ * worker, and tear it all down. Uses a HARMLESS probe (never {@code claude}) in a
+ * throwaway space that is fully removed at the end.
+ *
+ * <p>Tagged {@code contract}; run with {@code mvn test -Pcontract}.
+ */
+@Tag("contract")
+class WorkspacePlacementContractTest {
+
+    private static final String LABEL = "__bridged_contract__";
+
+    private boolean noSocket() {
+        return !Files.exists(UnixSocketHerdrClient.defaultSocketPath());
+    }
+
+    private int paneCount(HerdrClient herdr, String workspaceId, String tabId) {
+        JsonNode tabs = herdr.call("tab.list", Map.of("workspace_id", workspaceId)).path("tabs");
+        for (JsonNode t : tabs) {
+            if (tabId.equals(t.path("tab_id").asText())) return t.path("pane_count").asInt(-1);
+        }
+        return -1;
+    }
+
+    @Test
+    void workerGetsOwnCleanTabAndTearsDownCompletely() throws Exception {
+        assumeTrue(!noSocket(), "no herdr socket — skipping");
+        try (UnixSocketHerdrClient herdr = UnixSocketHerdrClient.connect()) {
+            AgentControl agents = new AgentControl(herdr);
+            WorkspaceControl spaces = new WorkspaceControl(herdr);
+
+            Workspace space = spaces.ensureWorkspace(LABEL);
+            assertNotNull(space.workspaceId());
+            // Idempotent: a second ensure finds the same space, never creates a duplicate.
+            assertEquals(space.workspaceId(), spaces.ensureWorkspace(LABEL).workspaceId());
+
+            Tab.Created tab = spaces.createTab(space.workspaceId());
+            Agent worker = agents.start(
+                    "__contract__",
+                    List.of("bash", "-c", "sleep 20"),
+                    Map.of(),
+                    tab.tab().tabId());
+            try {
+                // The worker landed in its dedicated tab in the worker space.
+                assertEquals(tab.tab().tabId(), worker.tabId());
+                assertEquals(space.workspaceId(), worker.workspaceId());
+
+                // Drop the seed shell; the tab now holds exactly the worker pane.
+                agents.close(tab.rootPaneId());
+                spaces.renameTab(tab.tab().tabId(), "worker: contract");
+                assertEquals(1, paneCount(herdr, space.workspaceId(), tab.tab().tabId()),
+                        "worker tab must hold only the worker pane after the seed shell is dropped");
+
+                // Teardown resolves the tab from the pane, and sees it holds exactly one pane.
+                WorkspaceControl.PaneLocation loc = spaces.locatePane(worker.paneId());
+                assertNotNull(loc);
+                assertEquals(tab.tab().tabId(), loc.tabId());
+                assertEquals(1, loc.tabPaneCount(), "worker is the tab's sole occupant");
+            } finally {
+                agents.close(worker.paneId());
+                spaces.closeTab(tab.tab().tabId());
+            }
+
+            // Tolerant teardown: closing an already-gone tab / reading a gone pane is a no-op.
+            spaces.closeTab(tab.tab().tabId());
+            assertNull(spaces.locatePane(worker.paneId()), "closed worker pane must be gone");
+
+            // Remove the throwaway space entirely so the test leaves no residue.
+            herdr.call("workspace.close", Map.of("workspace_id", space.workspaceId()));
+            assertTrue(spaces.findByLabel(LABEL).isEmpty(), "throwaway worker space must be gone");
+        }
+    }
+}

bridged/src/test/java/dev/ltms/bridged/rest/BridgedAppTest.java

@@ -6,6 +6,7 @@ import dev.ltms.bridged.config.BridgedConfig;
 import dev.ltms.bridged.guard.SubscriptionGuard;
 import dev.ltms.bridged.herdr.AgentControl;
 import dev.ltms.bridged.herdr.FakeHerdr;
+import dev.ltms.bridged.herdr.WorkspaceControl;
 import dev.ltms.bridged.worker.WorkerService;
 import io.javalin.Javalin;
 import org.junit.jupiter.api.AfterEach;
@@ -24,7 +25,8 @@ import static org.junit.jupiter.api.Assertions.*;
 /**
  * REST acceptance tests — the feature contract over plain HTTP with a fake herdr, no
  * live daemon and no Claude in the loop. This is the surface later MCP tools match by
- * parity, and where the subscription boundary is proven at the API edge.
+ * parity, and where the subscription boundary and worker placement are proven at the
+ * API edge.
  */
 class BridgedAppTest {
 
@@ -38,10 +40,15 @@ class BridgedAppTest {
     }
 
     private int start(FakeHerdr herdr, String workerBaseUrl, Set<String> allow) {
+        return start(herdr, workerBaseUrl, allow, "tab");
+    }
+
+    private int start(FakeHerdr herdr, String workerBaseUrl, Set<String> allow, String placement) {
         BridgedConfig.Worker wcfg = new BridgedConfig.Worker(
-                "ltms-local", workerBaseUrl, "coder", null, "BRIDGED_WORKER_TOKEN", null);
+                "ltms-local", workerBaseUrl, "coder", null, "BRIDGED_WORKER_TOKEN", null,
+                placement, "bridged-workers", "worker: {profile} #{n}");
         WorkerService workers = new WorkerService(
-                new AgentControl(herdr), new SubscriptionGuard(allow), wcfg,
+                new AgentControl(herdr), new WorkspaceControl(herdr), new SubscriptionGuard(allow), wcfg,
                 k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok-abc" : null);
         app = new BridgedApp(herdr, workers).build().start("127.0.0.1", 0);
         return app.port();
@@ -61,6 +68,11 @@ class BridgedAppTest {
         return http.send(b.build(), HttpResponse.BodyHandlers.ofString());
     }
 
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> params(FakeHerdr herdr, String method) {
+        return (Map<String, Object>) herdr.lastCall(method).params();
+    }
+
     @Test
     void healthzOkWhenHerdrAnswers() throws Exception {
         int port = startHealthy();
@@ -98,22 +110,69 @@ class BridgedAppTest {
     }
 
     @Test
-    void spawnWorkerInjectsBaseUrlAndReturns201() throws Exception {
+    void spawnWorkerLandsInOwnTabInWorkerSpaceAndInjectsBaseUrl() throws Exception {
         FakeHerdr herdr = new FakeHerdr();
         int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
 
         HttpResponse<String> res = req(port, "POST", "/workers");
         assertEquals(201, res.statusCode());
-        assertEquals("w2:pZ", mapper.readTree(res.body()).get("paneId").asText());
+        JsonNode body = mapper.readTree(res.body());
+        assertEquals("w9:pW", body.get("paneId").asText());
+        assertEquals("w9:t2", body.get("tabId").asText());
 
-        // The proof: agent.start carried ANTHROPIC_BASE_URL in its env map.
+        // Subscription boundary: agent.start carried base_url + token in its env map.
+        Map<String, Object> start = params(herdr, "agent.start");
         @SuppressWarnings("unchecked")
-        Map<String, Object> params = (Map<String, Object>) herdr.lastCall("agent.start").params();
-        @SuppressWarnings("unchecked")
-        Map<String, String> env = (Map<String, String>) params.get("env");
+        Map<String, String> env = (Map<String, String>) start.get("env");
         assertEquals("http://gx00.gw:8000", env.get("ANTHROPIC_BASE_URL"));
         assertEquals("tok-abc", env.get("ANTHROPIC_AUTH_TOKEN"));
-        assertEquals(List.of("claude"), params.get("argv"));
+        assertEquals(List.of("claude"), start.get("argv"));
+
+        // Placement: worker space ensured, worker started INTO its own tab, seed shell
+        // dropped, and the tab given a friendly label.
+        assertTrue(herdr.called("workspace.create"), "worker space must be found-or-created");
+        assertEquals("w9:t2", start.get("tab_id"), "worker must start into its dedicated tab");
+        assertEquals("w9:pRoot", params(herdr, "pane.close").get("pane_id"), "seed shell pane dropped");
+        assertEquals("worker: ltms-local #1", params(herdr, "tab.rename").get("label"),
+                "tab label carries the worker number so siblings stay distinct");
+    }
+
+    @Test
+    void spawnWorkerReusesExistingWorkerSpace() throws Exception {
+        // A space labelled "bridged-workers" already exists → no second workspace.create.
+        FakeHerdr herdr = new FakeHerdr().withWorkspace("w9", "bridged-workers");
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        assertEquals(201, req(port, "POST", "/workers").statusCode());
+        assertFalse(herdr.called("workspace.create"), "existing worker space must be reused, not recreated");
+        assertTrue(herdr.called("tab.create"), "a fresh tab is still created for the worker");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void spawnRetriesUnderAFreshNameWhenAgentNameTaken() throws Exception {
+        // herdr rejects a duplicate agent name; the service must bump and retry.
+        FakeHerdr herdr = new FakeHerdr().agentNameTakenTimes(2);
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        assertEquals(201, req(port, "POST", "/workers").statusCode());
+        List<String> names = herdr.calls.stream()
+                .filter(c -> c.method().equals("agent.start"))
+                .map(c -> ((Map<String, Object>) c.params()).get("name").toString())
+                .toList();
+        assertEquals(3, names.size(), "2 rejected + 1 success");
+        assertEquals(3, Set.copyOf(names).size(), "each attempt must use a distinct name");
+    }
+
+    @Test
+    void spawnClosesTheCreatedTabWhenTheWorkerNeverStarts() throws Exception {
+        // Every agent.start attempt is rejected → spawn fails; the tab we created must not leak.
+        FakeHerdr herdr = new FakeHerdr().agentNameTakenTimes(99);
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        assertEquals(500, req(port, "POST", "/workers").statusCode());
+        assertTrue(herdr.called("tab.create"), "a tab was created before the failed start");
+        assertEquals("w9:t2", params(herdr, "tab.close").get("tab_id"), "orphaned tab must be closed");
     }
 
     @Test
@@ -126,13 +185,71 @@ class BridgedAppTest {
         assertEquals(403, res.statusCode());
         assertEquals("subscription_boundary", mapper.readTree(res.body()).get("error").asText());
         assertFalse(herdr.called("agent.start"), "guard must stop the spawn before herdr");
+        assertFalse(herdr.called("workspace.create"), "guard must stop before provisioning a space");
     }
 
     @Test
-    void stopWorkerClosesPane() throws Exception {
+    void panePlacementSplitsFocusedTabWithoutADedicatedSpace() throws Exception {
+        FakeHerdr herdr = new FakeHerdr();
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"), "pane");
+
+        assertEquals(201, req(port, "POST", "/workers").statusCode());
+        Map<String, Object> start = params(herdr, "agent.start");
+        assertFalse(start.containsKey("tab_id"), "pane placement must not target a tab");
+        assertFalse(herdr.called("workspace.create"), "pane placement uses no dedicated space");
+        assertFalse(herdr.called("tab.create"));
+    }
+
+    @Test
+    void stopWorkerClosesPaneAndItsTab() throws Exception {
         FakeHerdr herdr = new FakeHerdr();
         int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-        assertEquals(204, req(port, "DELETE", "/workers/w2:pZ").statusCode());
+
+        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
         assertTrue(herdr.called("pane.close"));
+        // Tab resolved from the pane (pane.get), then closed.
+        assertEquals("w9:t2", params(herdr, "tab.close").get("tab_id"));
+    }
+
+    @Test
+    void stopWorkerInPanePlacementClosesOnlyThePane() throws Exception {
+        FakeHerdr herdr = new FakeHerdr();
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"), "pane");
+
+        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
+        assertTrue(herdr.called("pane.close"));
+        assertFalse(herdr.called("tab.close"), "pane placement owns no tab to close");
+        assertFalse(herdr.called("pane.get"), "no tab resolution in pane placement");
+    }
+
+    @Test
+    void stopNeverClosesATabThatHoldsOtherPanes() throws Exception {
+        // The worker's tab has 2 panes (e.g. a pane-placement worker sharing a user tab).
+        FakeHerdr herdr = new FakeHerdr().withWorkerTabPaneCount(2);
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
+        assertTrue(herdr.called("pane.close"), "the worker's own pane is still closed");
+        assertFalse(herdr.called("tab.close"), "must not close a tab that holds the user's other panes");
+    }
+
+    @Test
+    void stopReportsFailureWhenPaneCloseFailsForARealReason() throws Exception {
+        FakeHerdr herdr = new FakeHerdr().paneCloseFailsWith("herdr_busy");
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        // A genuine teardown failure must surface, not be reported as a successful 204.
+        assertEquals(500, req(port, "DELETE", "/workers/w9:pW").statusCode());
+        assertFalse(herdr.called("tab.close"), "tab is not removed when the pane close failed");
+    }
+
+    @Test
+    void stopToleratesAnAlreadyGonePane() throws Exception {
+        FakeHerdr herdr = new FakeHerdr().paneCloseFailsWith("pane_not_found");
+        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
+
+        // Already-gone is success; the (now-empty) tab is still cleaned up.
+        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
+        assertTrue(herdr.called("tab.close"));
     }
 }