Two graff instances on one terminal corrupt each other's session and input (SIGTTOU suspend already fixed in #271)

[justrach]

Symptom

Running graff --yolo (or the TUI generally) sometimes dies immediately with:

zsh: suspended (tty output)  graff --yolo

Reproducible by racing two graff instances on one terminal - e.g. /resume-ing the same session from a second shell, or the GUI's graff sidecar starting while a CLI graff holds the terminal. Whichever instance touches termios second gets stopped.

Root cause

src/term.zig:144, in tty.enterRaw():

std.posix.tcsetattr(fd, .NOW, raw) catch return null;

POSIX: when a process in a background process group calls tcsetattr() on its controlling terminal, the kernel sends it SIGTTOU, whose default disposition is stop the process. This fires regardless of the terminal's tostop flag - tcsetattr from a background pgrp always raises it.

A terminal has exactly one foreground process group. Two graff instances sharing one tty means the second is background by definition, so it is stopped the instant it enters raw mode.

There is currently no SIGTTOU handling and no tcgetpgrp foreground check anywhere in the tree. tty.restore() (src/term.zig:155) has the same exposure on the way out.

Fix

1. Ignore SIGTTOU around the tcsetattr calls in both enterRaw() and restore(). Save the prior disposition, install SIG_IGN, call, restore. The call then succeeds instead of stopping the process - correct here, since graff only ever sets its own terminal state. This alone removes the symptom.
2. Foreground check at startup: if tcgetpgrp(STDIN_FILENO) != getpgrp(), graff is a background job. Emit a clear message (graff needs the foreground - run fg) or degrade to non-TUI mode, instead of silently suspending.
3. Re-enter raw mode on SIGCONT, so a suspended-then-fg'd graff is not left with a broken terminal mode.
4. Lock the session file. Two instances on one --resume / /resume session is a corruption race independent of the tty. Take an exclusive advisory lock on <name>.session.json; the second instance should report "session open in another graff" rather than racing. Same cross-process-lock pattern the OAuth credential writes need.

Notes

• Windows is unaffected (console API, no process groups).
• Zig 0.16: verify tcgetpgrp is exposed in std; may need ioctl(TIOCGPGRP) directly, same situation as chdir.
• Items 1-3 are the tty fix. Item 4 is a separate concurrency bug that shares the repro and should probably be its own PR.

[justrach]

Correction to the original diagnosis

The tcsetattr -> SIGTTOU path described below is already guarded on main. Both call sites wrap the syscall in JobControlGuard.init(.output), which blocks SIGTTOU via sigprocmask for the duration:

• src/term.zig:171 (enterRaw)
• src/term.zig:183 (restore)

readStdin has the matching .input guard for SIGTTIN at src/term.zig:231. There are no other tcsetattr / tcsetpgrp calls in the tree.

That guard landed in 014769a ("fix: harden tty and trace reliability (#271 #272)") and is present in v0.0.215 and v0.0.216. The reporter is on graff 0.0.216.

So either the report predates the update to 0.0.216, or the suspension has a different cause than the one originally written up here.

What to do

1. Confirm whether it still reproduces on 0.0.216. If not, close this.

2. If it does reproduce, the remaining candidates are:

• SIGTTOU from an actual terminal write (not tcsetattr) when the tty has tostop set. The guard covers mode changes and reads, not writes.
• A spawned child (PTY path in process_runner.zig, kuri, the GUI sidecar) performing its own terminal-control call outside the guard.
• graff being genuinely backgrounded by however the GUI launches it.
  Capture stty -a and ps -o pid,pgid,tpgid,stat,command at the moment of suspension.

The part that is genuinely unfixed either way

Blocking SIGTTOU stops the suspension, but it does not make two graff instances on one terminal correct — it makes them silently incorrect. Both succeed in entering raw mode, then compete for the same stdin: keystrokes are split unpredictably between them and both draw over each other.

That still needs:

• An exclusive advisory lock on the session file. Two instances on one --resume / /resume session is a state-corruption race independent of the tty. The second instance should report "session open in another graff" and exit rather than race. Same cross-process-lock pattern the OAuth credential writes need.
• A terminal-ownership check at TUI startup: if tcgetpgrp(STDIN_FILENO) != getpgrp(), graff is not the foreground job. Say so plainly and degrade to non-TUI, instead of entering raw mode from the background and quietly stealing input. Note std.posix.tcgetpgrp exists in Zig 0.16; getpgrp does not, so use std.posix.system.getpgid(0).

Retitling this issue around that, since it is the real remaining defect.

[justrach]

Partially addressed in v0.0.226 (PR #328) - leaving this open.

Landed: Item 4: an advisory lock on the session file, so two graff instances in one workspace no longer silently clobber each other's transcript. (Item 1, the SIGTTOU suspend, shipped back in v0.0.215.)

Still open: items 2 and 3 - the tcgetpgrp/TIOCGPGRP foreground check and the SIGCONT re-raw handler.

[justrach]

Fixed in v0.0.226 (14ce015): the session file now takes an advisory lock (src/session_lock.zig), so two graff instances in one workspace stop silently clobbering each other's transcript. Together with the SIGTTOU suspend fix from #271 this covers both halves reported here. A warning for the broader shared-worktree case is tracked separately in #320.