agent-relay-orchestrator 0.27.1 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.16"
+    "agent-relay-sdk": "0.2.17"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -79,6 +79,10 @@ interface TerminalSocketData {
   ready?: boolean;
   queue?: Uint8Array[];
   syncTimer?: ReturnType<typeof setTimeout>;
+  // Bytes dropped (not sent) while this viewer was paused. On resume, 0 means the
+  // screen is unchanged → resume the live stream without a reset+backfill (which
+  // otherwise wipes scrollback/scroll position on every focus flick — #272).
+  droppedWhilePaused?: number;
 }
 
 type TerminalSocket = ServerWebSocket<TerminalSocketData>;
@@ -682,7 +686,11 @@ function startTerminalSocket(ws: TerminalSocket): void {
   ws.data.queue = [];
   const subscriber: TerminalStreamSubscriber = {
     onData: (bytes) => {
-      if (ws.data.paused) return;
+      if (ws.data.paused) {
+        // Count what we drop so resume can tell whether a re-backfill is needed.
+        ws.data.droppedWhilePaused = (ws.data.droppedWhilePaused ?? 0) + bytes.length;
+        return;
+      }
       // Queue live bytes until the client has reported its size and the backfill is
       // flushed, so the viewer never sees live output before (or mis-sized against) history.
       if (!ws.data.ready) {
@@ -694,9 +702,16 @@ function startTerminalSocket(ws: TerminalSocket): void {
       } catch {}
     },
     onClose: (reason) => {
+      // Tell the client why, THEN actually close the socket. Sending only the frame
+      // (the old behaviour) left a live-looking socket the client never reconnected
+      // on — a backpressure drop made the terminal silently dead to input and output
+      // (#271). The client reconnects + re-backfills on a transient reason.
       try {
         ws.send(JSON.stringify({ type: "closed", reason: reason ?? null }));
       } catch {}
+      try {
+        ws.close();
+      } catch {}
     },
     bufferedAmount: () => {
       try {
@@ -732,30 +747,47 @@ async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number)
   }
   if (ws.data.synced) return;
   ws.data.synced = true;
+  // Initial connect: live bytes are still queued (ready=false), so the reset+content can't
+  // split a live sequence — emit immediately (no ground gate, no first-paint latency).
   await sendBackfill(ws, cols, rows);
-  ws.data.queue = [];
-  ws.data.ready = true;
+  // But only START forwarding live output at a sequence boundary, so the first forwarded
+  // flush doesn't begin mid-escape-sequence (an orphan tail on the client — #276).
+  const stream = ws.data.stream;
+  const flip = () => {
+    ws.data.queue = [];
+    ws.data.ready = true;
+  };
+  if (stream) stream.whenAtGround(flip);
+  else flip();
 }
 
 // Send a full reset: a control frame with current geometry/status, then the serialized
-// emulator state as a raw byte frame. Used on connect, resume, and refresh.
-async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
+// emulator state as a raw byte frame. Used on connect, resume, and refresh. On resume /
+// refresh the live stream is flowing to this socket, so `gateGround` defers the
+// reset+content until a sequence boundary — otherwise the reset would splice between the
+// halves of a live escape sequence and orphan its tail on the client (#276).
+async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number, gateGround = false): Promise<void> {
   const stream = ws.data.stream;
   if (!stream) return;
   const snapshot = await stream.backfill(cols, rows);
   if (ws.data.stream !== stream) return; // socket torn down mid-backfill
-  ws.send(JSON.stringify({
-    type: "reset",
-    session: snapshot.session,
-    running: snapshot.running,
-    agentAlive: snapshot.agentAlive,
-    cols: snapshot.cols,
-    rows: snapshot.rows,
-    capturedAt: snapshot.capturedAt,
-  }));
-  if (snapshot.content) {
-    ws.send(new TextEncoder().encode(snapshot.content));
-  }
+  const emit = () => {
+    if (ws.data.stream !== stream) return;
+    ws.send(JSON.stringify({
+      type: "reset",
+      session: snapshot.session,
+      running: snapshot.running,
+      agentAlive: snapshot.agentAlive,
+      cols: snapshot.cols,
+      rows: snapshot.rows,
+      capturedAt: snapshot.capturedAt,
+    }));
+    if (snapshot.content) {
+      ws.send(new TextEncoder().encode(snapshot.content));
+    }
+  };
+  if (gateGround) await new Promise<void>((resolve) => stream.whenAtGround(() => { emit(); resolve(); }));
+  else emit();
 }
 
 function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer): void {
@@ -786,11 +818,23 @@ function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer):
         ws.data.stream?.resize(cols, rows);
       }
     } else if (frame.type === "pause") {
+      const wasPaused = ws.data.paused === true;
       ws.data.paused = frame.paused === true;
-      // We drop (not buffer) bytes while paused, so resync with a fresh backfill.
-      if (!ws.data.paused && ws.data.synced) void sendBackfill(ws);
+      // On resume: only re-backfill if bytes were actually dropped while paused. A
+      // focus flick (alt-tab) pauses+resumes with zero output in between — re-backfill
+      // there needlessly wipes scrollback and scroll position (#272). When nothing was
+      // dropped the client's grid already matches tmux, so just resume the live stream.
+      if (wasPaused && !ws.data.paused && ws.data.synced) {
+        const dropped = ws.data.droppedWhilePaused ?? 0;
+        ws.data.droppedWhilePaused = 0;
+        if (dropped > 0) void sendBackfill(ws, undefined, undefined, true);
+      }
     } else if (frame.type === "refresh") {
-      if (ws.data.synced) void sendBackfill(ws);
+      if (ws.data.synced) void sendBackfill(ws, undefined, undefined, true);
+    } else if (frame.type === "interactive") {
+      // Read-only watchers must not reflow the shared tmux window (#273); the typist owns
+      // sizing. The client reports its interactivity so the stream knows who may resize.
+      ws.data.stream?.setInteractive(frame.interactive === true);
     }
   } catch (e) {
     ws.send(JSON.stringify({ type: "error", error: errMessage(e) }));

package/src/control.ts

@@ -3,7 +3,7 @@ import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps } from "./workspace-probe";
+import { cleanupWorkspace, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
 
 interface ControlHandler {
   handleCommand(command: RelayCommand): Promise<boolean>;
@@ -94,6 +94,7 @@ export function createControlHandler(
           worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : undefined,
           branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
           deleteBranch: command.params.deleteBranch !== false,
+          workspacesRoot: workspacesRoot(config.baseDir),
         });
         await relay.updateCommand(command.id, "succeeded", result);
       } else if (command.type === "workspace.reconcile") {

package/src/index.ts

@@ -7,6 +7,7 @@ import { diagnoseSessionExit, hydrateTerminalGuests, isSessionAlive, reapTermina
 import { startApiServer } from "./api";
 import { recoverManagedAgents } from "./recovery";
 import { ProviderProbeCache } from "./provider-probe";
+import { sweepEmptyWorkspaceContainers, workspacesRoot } from "./workspace-probe";
 
 const args = process.argv.slice(2);
 
@@ -77,6 +78,10 @@ async function startup(): Promise<void> {
   // Recover existing tmux sessions
   await recoverManagedAgents(config, control, relay);
 
+  // Sweep empty workspace container dirs left behind by prior cleanups (#280).
+  const swept = sweepEmptyWorkspaceContainers(workspacesRoot(config.baseDir));
+  if (swept.length > 0) console.error(`[orchestrator] Swept ${swept.length} empty workspace container(s)`);
+
   // Restore guest-terminal TTLs persisted before the last restart, then reap any
   // that expired (or were orphaned) while the orchestrator was down (#144).
   hydrateTerminalGuests();

package/src/spawn.ts

@@ -4,7 +4,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { artifactProxyBaseUrl } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, ManagedSessionExitDiagnostics } from "./relay";
-import { resolveSpawnWorkspace } from "./workspace-probe";
+import { resolveSpawnWorkspace, workspacesRoot } from "./workspace-probe";
 import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
 import { errMessage } from "agent-relay-sdk";
 import { isPidAlive, parseProcStateIsZombie } from "agent-relay-sdk/process-utils";
@@ -350,7 +350,7 @@ export async function spawnAgent(
     ...opts,
     label,
     workspaceSymlinks: opts.workspaceSymlinks,
-    workspaceRoot: join(resolve(config.baseDir), ".agent-relay", "workspaces"),
+    workspaceRoot: workspacesRoot(config.baseDir),
   });
   const spawnOpts = { ...opts, label, agentId, cwd: resolvedWorkspace.cwd, workspace: resolvedWorkspace.workspace };
 

package/src/terminal-stream.ts

@@ -25,7 +25,7 @@
 // its separate `tmux send-keys` calls and is unaffected — control mode is just
 // another observing client.
 
-import { captureConsistent, sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
+import { sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
 import type { OrchestratorConfig } from "./config";
 import { errMessage } from "agent-relay-sdk";
 
@@ -46,6 +46,29 @@ const RESIZE_SETTLE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RES
 // streams still correct. 0 disables the corrector.
 const RESYNC_DEBOUNCE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS) || 120);
 const RESYNC_MAX_INTERVAL_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS) || 350);
+// When a resync falls due mid-escape-sequence we defer it (ground-state gate, #276) and
+// re-check after this short interval until the stream reaches a sequence boundary.
+const RESYNC_GROUND_RETRY_MS = Math.max(1, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_GROUND_RETRY_MS) || 16);
+// Hard cap on ground-state deferral: if the stream sits mid-sequence this long (a stalled
+// or dead pane — rare), inject the repaint anyway, CAN-prefixed to abort the client's
+// half-parsed sequence. The orphan-tail risk is accepted in that degenerate case (#276).
+const RESYNC_GROUND_DEFER_MAX_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_GROUND_DEFER_MAX_MS) || 500);
+// Per-command reply timeout for the in-band control protocol. A reply that never lands
+// means a desync; we reject and reset the reply queue so the next command starts clean.
+const COMMAND_TIMEOUT_MS = Math.max(100, Number(process.env.AGENT_RELAY_TERMINAL_COMMAND_TIMEOUT_MS) || 2000);
+// Upper bound a backfill/ready-flip waits for the live stream to reach a sequence boundary
+// before proceeding anyway (whenAtGround fallback for a stalled stream).
+const GROUND_WAIT_MAX_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_GROUND_WAIT_MAX_MS) || 500);
+// CAN (cancel) aborts a half-parsed sequence on the client.
+const CAN_BYTE = 0x18;
+
+interface PendingCommand {
+  wantReply: boolean;
+  lines: string[];
+  resolve: (lines: string[]) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+}
 // On attach we include this many lines of tmux scrollback ABOVE the current screen so the
 // viewer can scroll back through pre-attach history (the client lands on the live screen;
 // the history sits in its scroll buffer). This is a one-time per-attach paint, so it's
@@ -67,6 +90,14 @@ export interface TerminalStreamHandle {
   backfill(cols?: number, rows?: number): Promise<TerminalSnapshot>;
   write(bytes: Uint8Array): void;
   resize(cols: number, rows: number): void;
+  // Declare whether this viewer is interactive (typing). Only the interactive viewer
+  // sizes the shared tmux window, so read-only watchers can't reflow a working
+  // terminal by attaching/refreshing at their own width (#273).
+  setInteractive(interactive: boolean): void;
+  // Run `cb` when the outbound stream is at an ANSI sequence boundary (or after a short
+  // fallback). Used to gate reset/backfill injection so it can't split a live escape
+  // sequence on the client (#276).
+  whenAtGround(cb: () => void): void;
   release(): void;
 }
 
@@ -113,11 +144,38 @@ export function decodeControlOutput(data: string): Uint8Array {
   return Uint8Array.from(out);
 }
 
+// The control stream is read as latin1 so the `%output` octal path above sees faithful
+// bytes. But command-reply blocks (capture-pane grid rows) arrive as raw UTF-8, so their
+// lines reach us as the byte-faithful latin1 representation. Re-decode them to real UTF-8
+// here, or multi-byte glyphs (box-drawing, powerline) double-encode on the next repaint
+// and render as mojibake (#270). Safe to do per line: no UTF-8 continuation byte is
+// 0x0A/0x0D, so the newline split never lands mid-sequence.
+const REPLY_UTF8_DECODER = new TextDecoder("utf-8");
+export function latin1LineToUtf8(line: string): string {
+  const bytes = new Uint8Array(line.length);
+  for (let i = 0; i < line.length; i++) bytes[i] = line.charCodeAt(i) & 0xff;
+  return REPLY_UTF8_DECODER.decode(bytes);
+}
+
 export type ControlLine =
   | { type: "output"; pane: string; bytes: Uint8Array }
   | { type: "exit"; reason?: string }
+  // Command-reply block framing. Every command written to the control client's stdin is
+  // answered, in order, with a `%begin … %end` (or `%error`) block carrying the same
+  // command number on both ends. The content lines between them are the command's output
+  // (e.g. capture-pane grid rows). Correlating these in-band serializes captures with
+  // `%output` deltas — the ordering guarantee that kills the duplicate-text race (#275).
+  | { type: "begin"; num: number }
+  | { type: "end"; num: number }
+  | { type: "error"; num: number }
   | { type: "other" };
 
+// `%begin <timestamp> <cmd-number> <flags>` → the command number is the 2nd field.
+function parseBlockNum(line: string, prefixLen: number): number {
+  const n = Number(line.slice(prefixLen).trim().split(/\s+/)[1]);
+  return Number.isFinite(n) ? n : -1;
+}
+
 export function parseControlLine(line: string): ControlLine {
   if (line.startsWith("%output ")) {
     const rest = line.slice(8);
@@ -126,6 +184,9 @@ export function parseControlLine(line: string): ControlLine {
     const data = sp === -1 ? "" : rest.slice(sp + 1);
     return { type: "output", pane, bytes: decodeControlOutput(data) };
   }
+  if (line.startsWith("%begin ")) return { type: "begin", num: parseBlockNum(line, 7) };
+  if (line.startsWith("%end ")) return { type: "end", num: parseBlockNum(line, 5) };
+  if (line.startsWith("%error ")) return { type: "error", num: parseBlockNum(line, 7) };
   if (line === "%exit" || line.startsWith("%exit ")) {
     const reason = line.slice(5).trim();
     return { type: "exit", ...(reason ? { reason } : {}) };
@@ -133,6 +194,67 @@ export function parseControlLine(line: string): ControlLine {
   return { type: "other" };
 }
 
+// --- ANSI ground-state tracker (unit-tested) ---
+//
+// tmux chunks `%output` at pty-read / flush boundaries that can land mid-escape-sequence.
+// That's fine for xterm (its parser is stateful across writes), but if we splice an
+// out-of-band repaint (resync) BETWEEN the two halves of a split sequence, the injected
+// ESC aborts the half-parsed CSI and the sequence's tail bytes then arrive in ground state
+// and print as literal text — the stray `S` (final byte of `CSI Ps S`, scroll-up, which
+// scroll-region TUIs like Claude Code emit constantly). So we track whether the outbound
+// stream is at a sequence boundary (ground) and only inject there. This is a deliberately
+// minimal VT state machine: enough to know "are we mid-sequence?", not a full parser.
+export type AnsiState = "ground" | "esc" | "esc-charset" | "csi" | "string" | "string-esc";
+
+export function advanceAnsiState(state: AnsiState, byte: number): AnsiState {
+  // CAN (0x18) / SUB (0x1a) abort any in-progress sequence from any state → ground.
+  if (byte === 0x18 || byte === 0x1a) return "ground";
+  switch (state) {
+    case "ground":
+      if (byte === 0x1b) return "esc";
+      if (byte === 0x9b) return "csi"; // C1 CSI
+      if (byte === 0x9d || byte === 0x90) return "string"; // C1 OSC / DCS
+      return "ground"; // text, UTF-8 continuation bytes, lone C1 ST, etc.
+    case "esc":
+      if (byte === 0x5b) return "csi"; // '[' → CSI
+      if (byte === 0x5d || byte === 0x50 || byte === 0x58 || byte === 0x5e || byte === 0x5f)
+        return "string"; // ']' OSC, 'P' DCS, 'X' SOS, '^' PM, '_' APC → string until ST/BEL
+      if (byte >= 0x28 && byte <= 0x2b) return "esc-charset"; // ( ) * + → next byte designates a charset
+      if (byte >= 0x20 && byte <= 0x2f) return "esc"; // other intermediate, keep collecting
+      return "ground"; // final byte of a 2-byte escape (ESC M, ESC 7, ESC =, …)
+    case "esc-charset":
+      return "ground"; // the single charset-designator byte
+    case "csi":
+      if (byte === 0x1b) return "esc"; // ESC cancels and restarts a sequence
+      if (byte >= 0x40 && byte <= 0x7e) return "ground"; // final byte ends the CSI
+      return "csi"; // parameter (0x30–0x3f) / intermediate (0x20–0x2f) / executed C0
+    case "string":
+      if (byte === 0x07 || byte === 0x9c) return "ground"; // BEL or C1 ST terminates
+      if (byte === 0x1b) return "string-esc"; // possible 7-bit ST (ESC \)
+      return "string";
+    case "string-esc":
+      if (byte === 0x5c) return "ground"; // ST: ESC \
+      if (byte === 0x1b) return "string-esc";
+      return "string"; // stray ESC inside the string — stay in string mode
+  }
+}
+
+// Fold a chunk of outbound bytes into the running ANSI state. Returns the state AFTER the
+// chunk, so the caller knows whether the stream currently sits at a sequence boundary.
+export function scanAnsiState(bytes: Uint8Array, state: AnsiState = "ground"): AnsiState {
+  for (let i = 0; i < bytes.length; i++) state = advanceAnsiState(state, bytes[i]!);
+  return state;
+}
+
+// Parse a `#{pane_width} #{pane_height}` reply line into positive dims (omits non-finite).
+export function parsePaneDims(line: string): { cols?: number; rows?: number } {
+  const [w, h] = line.trim().split(/\s+/).map(Number);
+  return {
+    ...(w !== undefined && Number.isFinite(w) && w > 0 ? { cols: w } : {}),
+    ...(h !== undefined && Number.isFinite(h) && h > 0 ? { rows: h } : {}),
+  };
+}
+
 // Encode raw input bytes for `send-keys -H` (space-separated hex octets).
 export function encodeSendKeysHex(bytes: Uint8Array): string {
   return Array.from(bytes)
@@ -196,6 +318,24 @@ class SessionStream {
   private resyncTimer: ReturnType<typeof setTimeout> | null = null;
   private resyncCapTimer: ReturnType<typeof setTimeout> | null = null;
   private resyncDirty = false;
+  // Running ANSI parse state of the outbound (live) stream. A resync repaint or backfill
+  // reset is only injected when this is "ground" (a sequence boundary), so it can't split
+  // an escape sequence. Tracked over live flush bytes only — injected repaints are balanced.
+  private broadcastState: AnsiState = "ground";
+  private groundWaiters: Array<() => void> = [];
+  // The viewer that owns window sizing (the interactive typist). While set, only it may
+  // resize the shared tmux window; read-only watchers render at the current pane size.
+  private sizingOwner: TerminalStreamSubscriber | null = null;
+  // In-band command-reply correlation (#275): one FIFO entry per command written to the
+  // control client's stdin; tmux answers each with a %begin…%end (or %error) block, in
+  // order. The first block on attach is unsolicited (discarded via attachBlockSeen).
+  private pendingCommands: PendingCommand[] = [];
+  private currentBlock: { num: number; lines: string[] } | null = null;
+  private attachBlockSeen = false;
+  // Resync runs an async in-band capture; guard against overlapping captures and track how
+  // long the ground gate has been deferring (for the CAN fallback).
+  private resyncInFlight = false;
+  private groundDeferStart = 0;
 
   constructor(
     private readonly session: string,
@@ -209,8 +349,9 @@ class SessionStream {
     const socket = tmuxSocketForSession(this.session);
     this.socket = socket;
     // Pin the window size before attaching so the control client can't reflow the
-    // pane (default window-size would shrink it to the new client's 80x24).
-    const dims = this.paneDims();
+    // pane (default window-size would shrink it to the new client's 80x24). These are
+    // one-time, pre-attach spawnSyncs (the control client isn't up yet) — fine to block.
+    const dims = this.paneDimsSync();
     if (dims.cols) this.termCols = dims.cols;
     if (dims.rows) this.termRows = dims.rows;
     Bun.spawnSync(tmuxCommand(socket, "set-window-option", "-t", this.session, "window-size", "manual"), {
@@ -262,12 +403,45 @@ class SessionStream {
   }
 
   private handleLine(line: string): void {
+    // Inside a reply block, every line is the command's output until its OWN %end/%error
+    // (matched by command number — a captured grid row could otherwise masquerade as one).
+    // `%output` notifications never appear inside a block, so this can't swallow live deltas.
+    if (this.currentBlock) {
+      const parsed = parseControlLine(line);
+      if ((parsed.type === "end" || parsed.type === "error") && parsed.num === this.currentBlock.num) {
+        this.finishBlock(parsed.type === "error");
+      } else {
+        this.currentBlock.lines.push(line);
+      }
+      return;
+    }
     const parsed = parseControlLine(line);
-    if (parsed.type === "output") {
+    if (parsed.type === "begin") {
+      this.currentBlock = { num: parsed.num, lines: [] };
+    } else if (parsed.type === "output") {
       this.enqueue(parsed.bytes);
     } else if (parsed.type === "exit") {
       this.fail(parsed.reason ? `tmux exit: ${parsed.reason}` : "tmux exit");
     }
+    // A stray %end/%error with no open block, or any %other notification — ignore.
+  }
+
+  // Resolve the just-closed reply block against the FIFO head. The very first block on
+  // control-mode attach is unsolicited (tmux's empty initial command) — discard it so the
+  // correlation never drifts off by one.
+  private finishBlock(isError: boolean): void {
+    const block = this.currentBlock;
+    this.currentBlock = null;
+    if (!block) return;
+    if (!this.attachBlockSeen) {
+      this.attachBlockSeen = true;
+      return;
+    }
+    const entry = this.pendingCommands.shift();
+    if (!entry) return; // unexpected extra block — drop it rather than mis-correlate
+    if (entry.timer) clearTimeout(entry.timer);
+    if (isError) entry.reject(new Error(block.lines.join(" ").trim() || "tmux command error"));
+    else entry.resolve(block.lines.map(latin1LineToUtf8));
   }
 
   private enqueue(bytes: Uint8Array): void {
@@ -297,7 +471,11 @@ class SessionStream {
     }
     this.pending = [];
     this.pendingBytes = 0;
+    // Track ANSI ground state over LIVE bytes only (injected repaints are balanced by
+    // construction). The resync gate and whenAtGround read this to know it's safe to inject.
+    this.broadcastState = scanAnsiState(merged, this.broadcastState);
     this.broadcast(merged);
+    if (this.broadcastState === "ground") this.fireGroundWaiters();
     // Live deltas just went out; schedule an authoritative resync to correct any drift.
     this.scheduleResync();
   }
@@ -317,19 +495,106 @@ class SessionStream {
     }
   }
 
+  // Run `cb` at the next ANSI sequence boundary on the live stream (or now, if already at
+  // one), so an injected reset/backfill can't splice between the halves of a live escape
+  // sequence (#276). Falls back to firing anyway after GROUND_WAIT_MAX_MS if the stream
+  // stalls mid-sequence (rare — a dead pane); the reset path does a full clear regardless.
+  whenAtGround(cb: () => void): void {
+    if (this.closed || this.broadcastState === "ground") {
+      cb();
+      return;
+    }
+    let fired = false;
+    const fire = () => {
+      if (fired) return;
+      fired = true;
+      clearTimeout(timer);
+      const i = this.groundWaiters.indexOf(waiter);
+      if (i !== -1) this.groundWaiters.splice(i, 1);
+      try {
+        cb();
+      } catch {}
+    };
+    const waiter = fire;
+    const timer = setTimeout(fire, GROUND_WAIT_MAX_MS);
+    this.groundWaiters.push(waiter);
+  }
+
+  private fireGroundWaiters(): void {
+    if (this.groundWaiters.length === 0) return;
+    const waiters = this.groundWaiters;
+    this.groundWaiters = [];
+    for (const w of waiters) {
+      try {
+        w();
+      } catch {}
+    }
+  }
+
   // Schedule a drift-correcting resync: a trailing debounce fires once output settles,
   // and a capped interval guarantees correction during continuous output.
   private scheduleResync(): void {
     if (RESYNC_DEBOUNCE_MS <= 0 || this.subscribers.size === 0) return;
     this.resyncDirty = true;
     if (this.resyncTimer) clearTimeout(this.resyncTimer);
-    this.resyncTimer = setTimeout(() => this.doResync(), RESYNC_DEBOUNCE_MS);
+    this.resyncTimer = setTimeout(() => void this.doResync(), RESYNC_DEBOUNCE_MS);
     if (!this.resyncCapTimer && RESYNC_MAX_INTERVAL_MS > 0) {
-      this.resyncCapTimer = setTimeout(() => this.doResync(), RESYNC_MAX_INTERVAL_MS);
+      this.resyncCapTimer = setTimeout(() => void this.doResync(), RESYNC_MAX_INTERVAL_MS);
+    }
+  }
+
+  private async doResync(): Promise<void> {
+    this.clearResyncTimers();
+    if (!this.resyncDirty || this.closed || this.subscribers.size === 0) return;
+    // One in-band capture at a time; the next flush re-arms us.
+    if (this.resyncInFlight) {
+      this.resyncTimer = setTimeout(() => void this.doResync(), RESYNC_GROUND_RETRY_MS);
+      return;
+    }
+    // Ground-state gate (#276): never splice a repaint between the two halves of a split
+    // escape sequence (the injected ESC aborts the half-parsed CSI and its tail prints as
+    // literal text — the stray "S"). If we're mid-sequence, keep the work pending and
+    // re-check shortly. If the stream stays mid-sequence past the hard cap (stalled pane),
+    // force the repaint with a CAN prefix to abort the client's half-sequence.
+    let forceAbort = false;
+    if (this.broadcastState !== "ground") {
+      const now = Date.now();
+      if (this.groundDeferStart === 0) this.groundDeferStart = now;
+      if (now - this.groundDeferStart < RESYNC_GROUND_DEFER_MAX_MS) {
+        this.resyncTimer = setTimeout(() => void this.doResync(), RESYNC_GROUND_RETRY_MS);
+        return;
+      }
+      forceAbort = true;
+    }
+    this.groundDeferStart = 0;
+    this.resyncDirty = false;
+    this.resyncInFlight = true;
+    try {
+      const repaint = await this.resyncRepaint();
+      if (!repaint || this.closed || this.subscribers.size === 0) return;
+      // Ordering (#275): every %output read before the capture's %end is already in
+      // `pending`; drain it to subscribers BEFORE the repaint so scrolled lines can't
+      // re-apply on top of it (the duplicate-text race). Deltas after %end describe
+      // post-capture changes and correctly apply on top of the repaint next flush.
+      this.flush();
+      const out = forceAbort ? this.prependCan(repaint) : repaint;
+      this.broadcast(out);
+      tdbg(`resync ${this.session} bytes=${out.length} viewers=${this.subscribers.size}${forceAbort ? " (forced)" : ""}`);
+    } catch (e) {
+      tdbg(`resync ${this.session} failed: ${errMessage(e)}`);
+    } finally {
+      this.resyncInFlight = false;
     }
   }
 
-  private doResync(): void {
+  private prependCan(bytes: Uint8Array): Uint8Array {
+    const out = new Uint8Array(bytes.length + 1);
+    out[0] = CAN_BYTE;
+    out.set(bytes, 1);
+    return out;
+  }
+
+  private clearResyncTimers(): void {
     if (this.resyncTimer) {
       clearTimeout(this.resyncTimer);
       this.resyncTimer = null;
@@ -338,66 +603,61 @@ class SessionStream {
       clearTimeout(this.resyncCapTimer);
       this.resyncCapTimer = null;
     }
-    if (!this.resyncDirty || this.closed) return;
-    this.resyncDirty = false;
-    if (this.subscribers.size === 0) return;
-    const repaint = this.resyncRepaint();
-    if (!repaint) return;
-    this.broadcast(repaint);
-    tdbg(`resync ${this.session} bytes=${repaint.length} viewers=${this.subscribers.size}`);
   }
 
   // Build an in-place authoritative repaint from tmux's grid: absolute-position each row,
   // reset SGR + clear it, then write tmux's styled cells. This overwrites any drift (a
   // doubled statusline, a solid-instead-of-faded suggestion, stale cells) without a
   // full-screen clear flash, and re-parks the cursor at tmux's true position/visibility.
-  private resyncRepaint(): Uint8Array | null {
-    const body = this.readScreen();
+  // The grid + cursor are read in-band through the control client (#275), so the capture
+  // is serialized with %output deltas and costs no process spawn.
+  private async resyncRepaint(): Promise<Uint8Array | null> {
+    const body = await this.readScreen();
     if (!body) return null;
-    const cursor = this.readCursorState();
-    const rows = this.paneDims().rows ?? this.termRows;
+    const cursor = await this.readCursorState();
+    const dims = await this.paneDims();
+    const rows = dims.rows ?? this.termRows;
     return new TextEncoder().encode(buildInPlaceRepaint(body, rows, cursor));
   }
 
-  // Read tmux's authoritative current-screen grid (styled, no scrollback) plus a
-  // consistent cursor position, and turn it into a client repaint. capture-pane reads
-  // tmux's real emulator grid, so it's always internally coherent; captureConsistent
-  // guards the (content, cursor) read against a mid-render cursor move.
-  private captureScreen(): { content: string; cursorX?: number; cursorY?: number } {
-    const { content, cursor } = captureConsistent(
-      () => this.readBackfill(),
-      () => this.readCursor(),
-    );
+  // Read tmux's authoritative grid (styled) plus a consistent cursor, and turn it into a
+  // client repaint. capture-pane reads tmux's real emulator grid, so it's internally
+  // coherent; we bracket content/cursor/content (in-band, cheap now) to guard the read
+  // against a mid-render change.
+  private async captureScreen(): Promise<{ content: string; cursorX?: number; cursorY?: number }> {
+    let content = await this.readBackfill();
+    let cursor = await this.readCursor();
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const recheck = await this.readBackfill();
+      if (recheck === content) break;
+      content = recheck;
+      cursor = await this.readCursor();
+    }
     return { content: buildScreenRepaint(content, cursor.cursorX, cursor.cursorY), ...cursor };
   }
 
   // Backfill capture: current screen plus scrollback history above it (cursor is
   // viewport-relative, so it still parks on the live screen). Falls back to screen-only.
-  private readBackfill(): string {
+  private async readBackfill(): Promise<string> {
     if (BACKFILL_SCROLLBACK_LINES <= 0) return this.readScreen();
-    const r = Bun.spawnSync(
-      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-S", `-${BACKFILL_SCROLLBACK_LINES}`, "-t", this.session),
-      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
-    );
-    return r.exitCode === 0 ? r.stdout.toString("utf8") : this.readScreen();
+    const lines = await this.runCommand(
+      `capture-pane -p -e -S -${BACKFILL_SCROLLBACK_LINES} -t "${this.session}"`,
+    ).catch(() => null);
+    return lines ? lines.join("\n") : this.readScreen();
   }
 
   // Current-screen-only capture (no scrollback) — used by the live resync corrector so it
   // overwrites just the visible grid and leaves the client's scroll-back history intact.
-  private readScreen(): string {
-    const r = Bun.spawnSync(
-      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-t", this.session),
-      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
-    );
-    return r.exitCode === 0 ? r.stdout.toString("utf8") : "";
-  }
-
-  private readCursor(): { cursorX?: number; cursorY?: number } {
-    const r = Bun.spawnSync(
-      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y}"),
-      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
-    );
-    const [x, y] = r.stdout.toString().trim().split(/\s+/).map(Number);
+  private async readScreen(): Promise<string> {
+    const lines = await this.runCommand(`capture-pane -p -e -t "${this.session}"`).catch(() => null);
+    return lines ? lines.join("\n") : "";
+  }
+
+  private async readCursor(): Promise<{ cursorX?: number; cursorY?: number }> {
+    const lines = await this.runCommand(
+      `display-message -p -t "${this.session}" "#{cursor_x} #{cursor_y}"`,
+    ).catch(() => [] as string[]);
+    const [x, y] = (lines[0] ?? "").trim().split(/\s+/).map(Number);
     return {
       ...(Number.isFinite(x) ? { cursorX: x } : {}),
       ...(Number.isFinite(y) ? { cursorY: y } : {}),
@@ -406,12 +666,11 @@ class SessionStream {
 
   // Cursor position plus visibility (cursor_flag), so a resync repaint restores whether
   // the TUI had the cursor shown or hidden rather than guessing.
-  private readCursorState(): { cursorX?: number; cursorY?: number; visible?: boolean } {
-    const r = Bun.spawnSync(
-      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y} #{cursor_flag}"),
-      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
-    );
-    const [x, y, flag] = r.stdout.toString().trim().split(/\s+/);
+  private async readCursorState(): Promise<{ cursorX?: number; cursorY?: number; visible?: boolean }> {
+    const lines = await this.runCommand(
+      `display-message -p -t "${this.session}" "#{cursor_x} #{cursor_y} #{cursor_flag}"`,
+    ).catch(() => [] as string[]);
+    const [x, y, flag] = (lines[0] ?? "").trim().split(/\s+/);
     const cx = Number(x);
     const cy = Number(y);
     return {
@@ -424,25 +683,22 @@ class SessionStream {
   // Repaint a freshly-attached (or resumed/refreshed) viewer from tmux's current grid.
   // When the viewer's dimensions are given we resize the tmux pane first so the TUI
   // re-renders at the viewer's width, let it settle, then capture the post-resize frame.
-  async backfill(cols?: number, rows?: number): Promise<TerminalSnapshot> {
+  async backfill(sub: TerminalStreamSubscriber, cols?: number, rows?: number): Promise<TerminalSnapshot> {
     let resized = false;
-    if (Number.isFinite(cols) && Number.isFinite(rows) && (cols as number) >= 10 && (rows as number) >= 5) {
+    if (this.maySize(sub) && Number.isFinite(cols) && Number.isFinite(rows) && (cols as number) >= 10 && (rows as number) >= 5) {
       const c = Math.trunc(cols as number);
       const r = Math.trunc(rows as number);
       if (c !== this.termCols || r !== this.termRows) {
-        Bun.spawnSync(
-          tmuxCommand(this.socket, "resize-window", "-t", this.session, "-x", String(c), "-y", String(r)),
-          { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
-        );
+        void this.command(`resize-window -t "${this.session}" -x ${c} -y ${r}`);
         this.termCols = c;
         this.termRows = r;
         resized = true;
       }
     }
     if (resized && RESIZE_SETTLE_MS > 0) await Bun.sleep(RESIZE_SETTLE_MS);
-    const { content } = this.captureScreen();
+    const { content } = await this.captureScreen();
     // Report tmux's actual pane size (authoritative) back to the viewer.
-    const dims = this.paneDims();
+    const dims = await this.paneDims();
     if (dims.cols) this.termCols = dims.cols;
     if (dims.rows) this.termRows = dims.rows;
     const live = sessionLiveness(this.session);
@@ -458,45 +714,106 @@ class SessionStream {
     };
   }
 
-  write(bytes: Uint8Array): void {
+  write(sub: TerminalStreamSubscriber, bytes: Uint8Array): void {
     if (this.closed || !this.proc || bytes.length === 0) return;
-    this.command(`send-keys -t "${this.session}" -H ${encodeSendKeysHex(bytes)}`);
+    // Typing is the strongest interactivity signal — the typist owns window sizing.
+    this.sizingOwner = sub;
+    void this.command(`send-keys -t "${this.session}" -H ${encodeSendKeysHex(bytes)}`);
+  }
+
+  setInteractive(sub: TerminalStreamSubscriber, interactive: boolean): void {
+    if (interactive) {
+      this.sizingOwner = sub;
+    } else if (this.sizingOwner === sub) {
+      this.sizingOwner = null;
+    }
+  }
+
+  // A viewer may size the shared window only if it's the sizing owner, or nobody owns
+  // sizing yet (first viewer, before anyone has declared interactivity — it still needs
+  // a sensible size). Once an interactive viewer exists, read-only watchers never resize.
+  private maySize(sub: TerminalStreamSubscriber): boolean {
+    return this.sizingOwner === null || this.sizingOwner === sub;
   }
 
-  resize(cols: number, rows: number): void {
+  resize(sub: TerminalStreamSubscriber, cols: number, rows: number): void {
     if (this.closed || !this.proc) return;
+    if (!this.maySize(sub)) return; // read-only watcher: don't reflow the shared window
     if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols < 10 || rows < 5) return;
     const c = Math.trunc(cols);
     const r = Math.trunc(rows);
-    this.command(`resize-window -t "${this.session}" -x ${c} -y ${r}`);
+    void this.command(`resize-window -t "${this.session}" -x ${c} -y ${r}`);
     this.termCols = c;
     this.termRows = r;
     tdbg(`resize ${this.session} -> ${c}x${r} viewers=${this.subscribers.size}`);
   }
 
-  private paneDims(): { cols?: number; rows?: number } {
+  // Pane dimensions, in-band through the control client (no spawn).
+  private async paneDims(): Promise<{ cols?: number; rows?: number }> {
+    const lines = await this.runCommand(
+      `display-message -p -t "${this.session}" "#{pane_width} #{pane_height}"`,
+    ).catch(() => [] as string[]);
+    return parsePaneDims(lines[0] ?? "");
+  }
+
+  // Synchronous pane-dims read for start(), which runs before the control client attaches.
+  private paneDimsSync(): { cols?: number; rows?: number } {
     try {
       const out = Bun.spawnSync(
         tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{pane_width} #{pane_height}"),
         { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
       ).stdout.toString().trim();
-      const [w, h] = out.split(/\s+/).map(Number);
-      return {
-        ...(w !== undefined && Number.isFinite(w) && w > 0 ? { cols: w } : {}),
-        ...(h !== undefined && Number.isFinite(h) && h > 0 ? { rows: h } : {}),
-      };
+      return parsePaneDims(out);
     } catch {
       return {};
     }
   }
 
-  private command(line: string): void {
+  // Run a control command expecting its reply lines (the FIFO correlates them in order).
+  private runCommand(line: string): Promise<string[]> {
+    return this.command(line, true);
+  }
+
+  // Write a command to the control client's stdin and register a FIFO entry for its reply
+  // block. `wantReply` commands resolve with the block's lines (or reject on %error /
+  // timeout); fire-and-forget commands resolve with [] once their empty block closes.
+  private command(line: string, wantReply = false): Promise<string[]> {
+    if (this.closed) return wantReply ? Promise.reject(new Error("terminal stream closed")) : Promise.resolve([]);
     const stdin = this.proc?.stdin;
-    if (!stdin || typeof stdin === "number") return;
-    try {
-      (stdin as { write(data: string): void; flush?(): void }).write(`${line}\n`);
-      (stdin as { flush?(): void }).flush?.();
-    } catch {}
+    if (!stdin || typeof stdin === "number") {
+      return wantReply ? Promise.reject(new Error("control client unavailable")) : Promise.resolve([]);
+    }
+    return new Promise<string[]>((resolve, reject) => {
+      const entry: PendingCommand = { wantReply, lines: [], resolve, reject, timer: null };
+      if (wantReply) entry.timer = setTimeout(() => this.commandTimeout(entry), COMMAND_TIMEOUT_MS);
+      this.pendingCommands.push(entry);
+      try {
+        (stdin as { write(data: string): void; flush?(): void }).write(`${line}\n`);
+        (stdin as { flush?(): void }).flush?.();
+      } catch (e) {
+        const idx = this.pendingCommands.indexOf(entry);
+        if (idx !== -1) this.pendingCommands.splice(idx, 1);
+        if (entry.timer) clearTimeout(entry.timer);
+        if (wantReply) reject(e instanceof Error ? e : new Error(String(e)));
+        else resolve([]);
+      }
+    });
+  }
+
+  // A reply that never arrived means a protocol desync — reject the awaited command and
+  // reset the whole reply queue + block state so the next command starts clean. The byte
+  // stream itself keeps flowing; only in-flight captures fail (the resync just skips a beat).
+  private commandTimeout(entry: PendingCommand): void {
+    if (!this.pendingCommands.includes(entry)) return;
+    tdbg(`command timeout ${this.session}; resetting reply queue (${this.pendingCommands.length} pending)`);
+    const pend = this.pendingCommands;
+    this.pendingCommands = [];
+    this.currentBlock = null;
+    for (const e of pend) {
+      if (e.timer) clearTimeout(e.timer);
+      if (e.wantReply) e.reject(new Error("control command timed out"));
+      else e.resolve([]);
+    }
   }
 
   addSubscriber(sub: TerminalStreamSubscriber): void {
@@ -506,6 +823,7 @@ class SessionStream {
 
   removeSubscriber(sub: TerminalStreamSubscriber): void {
     if (!this.subscribers.delete(sub)) return;
+    if (this.sizingOwner === sub) this.sizingOwner = null;
     tdbg(`detach ${this.session} viewers=${this.subscribers.size}`);
     if (this.subscribers.size === 0) this.destroy();
   }
@@ -529,14 +847,17 @@ class SessionStream {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
-    if (this.resyncTimer !== null) {
-      clearTimeout(this.resyncTimer);
-      this.resyncTimer = null;
-    }
-    if (this.resyncCapTimer !== null) {
-      clearTimeout(this.resyncCapTimer);
-      this.resyncCapTimer = null;
+    this.clearResyncTimers();
+    // Reject any in-flight in-band commands so awaiters (captures) unwind instead of hanging.
+    const pend = this.pendingCommands;
+    this.pendingCommands = [];
+    this.currentBlock = null;
+    for (const e of pend) {
+      if (e.timer) clearTimeout(e.timer);
+      if (e.wantReply) e.reject(new Error("terminal stream closed"));
+      else e.resolve([]);
     }
+    this.fireGroundWaiters();
     try {
       this.proc?.kill();
     } catch {}
@@ -563,9 +884,11 @@ export function acquireTerminalStream(
   const active = stream;
   active.addSubscriber(subscriber);
   return {
-    backfill: (cols, rows) => active.backfill(cols, rows),
-    write: (bytes) => active.write(bytes),
-    resize: (cols, rows) => active.resize(cols, rows),
+    backfill: (cols, rows) => active.backfill(subscriber, cols, rows),
+    write: (bytes) => active.write(subscriber, bytes),
+    resize: (cols, rows) => active.resize(subscriber, cols, rows),
+    setInteractive: (interactive) => active.setInteractive(subscriber, interactive),
+    whenAtGround: (cb) => active.whenAtGround(cb),
     release: () => active.removeSubscriber(subscriber),
   };
 }

package/src/workspace-probe.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, type Dirent } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, symlinkSync, type Dirent } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -127,7 +127,7 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
   const repoRoot = probe.repoRoot;
   const baseSha = probe.headSha ?? requireGit(["rev-parse", "HEAD"], repoRoot);
   const branch = await availableBranch(repoRoot, branchName(input, id));
-  const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : join(homedir(), ".agent-relay", "workspaces");
+  const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : workspacesRoot(homedir());
   const worktreePath = join(workspaceRoot, repoSlug(repoRoot), id);
   mkdirSync(join(worktreePath, ".."), { recursive: true });
   requireGit(["worktree", "add", "-b", branch, worktreePath, baseSha], repoRoot);
@@ -471,7 +471,7 @@ export function pruneWorktrees(input: { repoRoot?: string }): { repoRoot: string
   return { repoRoot: repo, pruned: true, output: result.stdout.trim() || undefined };
 }
 
-export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; deleteBranch?: boolean }): { workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean } {
+export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; deleteBranch?: boolean; workspacesRoot?: string }): { workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean; containerRemoved?: boolean } {
   if (!workspace.worktreePath) throw new Error("worktreePath required");
   const path = resolve(workspace.worktreePath);
   const repo = workspace.repoRoot ? resolve(workspace.repoRoot) : path;
@@ -484,7 +484,38 @@ export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?:
   if (workspace.branch && workspace.deleteBranch !== false) {
     branchDeleted = git(["branch", "-D", workspace.branch], repo).ok;
   }
-  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted };
+  const containerRemoved = workspace.workspacesRoot ? removeEmptyContainer(dirname(path), resolve(workspace.workspacesRoot)) : false;
+  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted, containerRemoved };
+}
+
+export function sweepEmptyWorkspaceContainers(wsRoot: string): string[] {
+  const root = resolve(wsRoot);
+  if (!existsSync(root)) return [];
+  const removed: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(root, entry.name);
+    if (readdirSync(dir).length === 0) {
+      rmdirSync(dir);
+      removed.push(dir);
+    }
+  }
+  return removed;
+}
+
+function removeEmptyContainer(container: string, wsRoot: string): boolean {
+  try {
+    if (!existsSync(container)) return false;
+    if (readdirSync(container).length !== 0) return false;
+    if (!isDirectChildOf(container, wsRoot)) return false;
+    rmdirSync(container);
+    return true;
+  } catch { return false; }
+}
+
+function isDirectChildOf(child: string, parent: string): boolean {
+  const rel = relative(resolve(parent), resolve(child));
+  return !!rel && !rel.includes("/") && !rel.startsWith("..") && !isAbsolute(rel);
 }
 
 /**
@@ -1055,7 +1086,9 @@ function workspaceId(input: WorkspaceResolutionInput): string {
 
 function branchName(input: WorkspaceResolutionInput, id: string): string {
   const owner = input.policyName || input.label || input.automationId || "manual";
-  return `agent/${safeSegment(owner, 48)}/${safeSegment(id.replace(/^sp[_-]?/, ""), 24)}`;
+  // 40 fits a full UUID (36) plus the `sp_`-stripped slack. A tighter cap (was 24)
+  // sliced the session UUID mid-string, leaving an unaddressable, dangling ref (#282).
+  return `agent/${safeSegment(owner, 48)}/${safeSegment(id.replace(/^sp[_-]?/, ""), 40)}`;
 }
 
 /** Next free `<branch>-N` cycle name for a recycled worktree (#206). Strips any
@@ -1069,6 +1102,10 @@ function nextBranchName(repoRoot: string, branch: string): string {
   return `${stem}-${Date.now()}`;
 }
 
+export function workspacesRoot(baseDir: string): string {
+  return join(resolve(baseDir), ".agent-relay", "workspaces");
+}
+
 function repoSlug(repoRoot: string): string {
   const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 10);
   return `${safeSegment(basename(repoRoot), 60)}-${hash}`;