# sync: interactive launches strip the harness of its controlling terminal (start_new_session=True) · Issue #1 · anntnzrb/agents

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | async-pty-process-testing |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | sync: interactive launches strip the harness of its controlling terminal (start_new_session=True) |
| Source URL | https://github.com/anntnzrb/agents/issues/1 |
| Source publisher / author | GitHub user anntnzrb |
| Source type | repository (issue) |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-09 |
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
| Research method | web search synthesis |
| Confidence | High |
| Status | Active |

## Summary

A GitHub issue documenting a real, encountered bug: a test/automation harness launched an interactive child process with `start_new_session=True`, which left the harness without a controlling terminal and broke window-resize and Ctrl-C handling for the child. The issue includes a small probe script for diagnosing whether a child process actually has a controlling terminal.

## Key findings

- `start_new_session=True` makes the child a new session leader; if that child is then given a pty as stdin/stdout/stderr, whether the pty becomes its *controlling* terminal (in the POSIX job-control sense) is not automatic — the issue describes a concrete case where it did not, breaking SIGWINCH-based resize and tty-line-discipline Ctrl-C-as-SIGINT.
- The reporter's diagnostic approach: a probe script that checks `os.isatty(0)`, `os.tcgetpgrp(0)`, and whether `/dev/tty` can be opened, to confirm a child process actually has a controlling terminal rather than just an open pty fd.

## Pros / strengths

- A real, lived-through failure report rather than theoretical speculation — exactly the kind of pitfall that's easy to get subtly wrong when combining `start_new_session=True` (needed for safe process-group-wide `killpg` cleanup) with pty-based spawning (needed for `isatty()`-correct interactive behavior).
- The diagnostic probe script is a concrete, reusable technique for anyone needing to verify controlling-terminal status.

## Cons / limitations / caveats

- A single GitHub issue report, not a kernel/POSIX specification — the exact conditions under which a session leader's first terminal open becomes its controlling terminal can depend on how the fd was obtained (opened directly by the child vs. inherited already-open from the parent), and this issue doesn't fully disambiguate that for the inherited-fd case `tai_test.py` actually uses.
- No resolution/fix is confirmed as verified in this research pass (the issue's eventual outcome was not reviewed).

## Relevance to tai

Directly shaped `tai_test.py`'s documented, accepted limitation: its pty mode does not explicitly call `ioctl(TIOCSCTTY)`, so controlling-terminal/job-control semantics (SIGWINCH forwarding, Ctrl-C-as-SIGINT from the tty line discipline) are not guaranteed. This was judged acceptable because `tai.py`'s own code only checks `sys.stdin.isatty()` (a property of the fd itself, unaffected by session/controlling-terminal status) and `tai_test.py`'s tests only script line-based input/output, never relying on resize or terminal-generated signals.

## Changelog

| Date | Change |
|---|---|
| 2026-10-09 | Initial dossier created. |