Method attach

src/workspaces/persistent-session.ts:305–394

Swap in `ws` as the attached client. A controller claim makes ownership * explicit: a second controller is rejected unless it deliberately takes * over. This is the shared rule for browser, Electron IPC, future IM bridges, * and any debug client that can write to the PTY.

(
    ws: WebSocket,
    cols: number,
    rows: number,
    since: number | undefined,
    claim?: SessionControllerClaim,
  )

   *  over. This is the shared rule for browser, Electron IPC, future IM bridges,
   *  and any debug client that can write to the PTY. */
  attach(
    ws: WebSocket,
    cols: number,
    rows: number,
    since: number | undefined,
    claim?: SessionControllerClaim,
  ): SessionAttachResult {
    if (this.disposed) {
      try {
        ws.close(1011, 'session disposed');
      } catch {
        // ignore
      }
      return { ok: false, reason: 'locked', owner: this.controller ?? { id: 'disposed', kind: 'session' } };
    }

    const owner = normalizeClaim(claim);
    if (
      owner &&
      this.ws !== null &&
      this.controller !== null &&
      this.controller.id !== owner.id &&
      !claim?.takeover
    ) {
      try {
        ws.close(4409, 'session locked by another controller');
      } catch {
        // ignore
      }
      return { ok: false, reason: 'locked', owner: this.controller };
    }

    // Kick previous client.
    if (this.ws !== null && this.ws !== ws) {
      const prev = this.ws;
      this.unwireWs(prev);
      this.ws = null;
      try {
        prev.close(4001, 'kicked by new attach');
      } catch {
        // ignore
      }
    }

    this.ws = ws;
    this.controller = owner;
    // A previous client may have dropped mid-backpressure, leaving the PTY
    // paused at the OS level. Clearing only the flag (not resuming the term)
    // would strand it paused forever; resumePty() un-sticks both.
    this.resumePty();
    this.resize(cols, rows);

    // Compute replay window. Cold attach (since=undefined) replays the full
    // buffer — without that, a fresh browser tab on a workspace where the
    // agent is already idle would just see a black void instead of the prompt
    // and recent output. Hot attach (since=N) only fills in what was missed.
    const requested = since ?? 0;
    const slice = this.buffer.since(requested);