Add plexer subsystem, container test infra, and last-resort opencode box backend

- Plexer: always-active terminal multiplexing. NativePlexerController/ TmuxPlexerController share one interface, chosen by which env var is already set (TAI_PLEXER_SOCKET vs TMUX_PANE); NativePlexerBackend is the pty.fork()-based wrapper (raw mode, SIGWINCH resize forwarding, a Unix-socket control protocol, continuous session logging, a Ctrl+A prefix key distinct from tmux's own Ctrl+B). Auto-wraps new interactive shells via a .bashrc hook mirroring the existing command-not-found install pattern, gated on $TMUX/$TAI_PLEXER_ACTIVE/ a $HOME/.tai-no-plexer bypass. New plexer_send/read/type/status tools, env-gated on a detected controller. - tests/container.py + docker-compose.yml + tests/docker/Dockerfile: a disposable podman/docker image for the tests that must never touch a real machine (installing the plexer hook into a real ~/.bashrc, a live tmux session). Required suite (test_seal.py, test_tai.py, tests/plexer.py, tests/bashrc.py) gates the result; tests/rag.py runs as best-effort since its real-LLM dependency can't be satisfied inside a disposable container with no nested engine. - tests/bashrc.py: real end-to-end hook install + bash -i auto-wrap, anti-recursion, tmux-active skip, non-interactive skip, a live TmuxPlexerController test, and an install/uninstall round-trip. - tests/plexer.py: NativePlexerBackend under a real pty, plus a dedicated robustness pass (file permissions, >64KB payload framing, a malformed control request, a genuine self-deadlock fix in the write-to-child path). - tai_test.py: the shared async process-driving framework (pipe/pty transport, group-wide kill-and-reap, a StdinBridge for --interactive) both test files build on. - ChatClient last-resort backend: when there's no local opencode CLI but the sandbox box is already running, install opencode into it (official Node tarball, not apt -- apt's nodejs/npm pull in webpack/babel/jest as transitive deps) and route through it instead of giving up. Only reachable after the first retry round already failed everything else; never creates the box itself. TmuxPlexerController.status() fixed to use `list-panes` instead of `display-message -p`, which silently fell back to the default pane instead of erroring against a dead target. - Fix 4 pre-existing test_tai.py bugs surfaced by running it in a clean environment for the first time: two stale mock signatures (subprocess.run's stdout= kwarg, Chat.complete's deadline= kwarg), one $TMUX-dependent catalog assertion, one tty-dependent color assertion. - research/: a sourced research archive (Source Dossier/Citation Card/Conclusion tiers) backing the above design decisions, with its own audit.py consistency checker. - .gitignore: fix a blanket *.md rule that was about to silently drop the entire research/ archive from version control; add __pycache__/ and the one-off debug transcript this session started from. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 04:36:05 +02:00
parent f078ab4731
commit 9dbd1fe667
247 changed files with 11187 additions and 26 deletions
@@ -0,0 +1,28 @@
+# Terminal Notifier for AI Agents (1devtool.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Terminal Notifier for AI Agents |
+| Source URL | https://1devtool.com/blog/terminal-notifier-for-ai-agents |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the automation-detection query; tangentially related (notifications about AI agent terminal activity, not detection of agent terminals per se), not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Tmux + Claude Code — Deep Dive
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Tmux + Claude Code — Deep Dive |
+| Source URL | https://acchapm1.github.io/tutorials/Tmux-Claude-Code/tmux-claude-code-deep-dive |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the tmux-architecture query; looked potentially relevant given it specifically covers tmux alongside an AI coding agent, directly adjacent to this subject's topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Android adb — Raw Mode via cfmakeraw (commit a826579d)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | adb: platform/packages/modules/adb commit a826579d |
+| Source URL | https://android.googlesource.com/platform/packages/modules/adb/+/a826579d%5E%21 |
+| Source publisher / author | Android Open Source Project (Google) |
+| Source type | repository |
+| 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 real, shipped commit in Android's `adb` tool showing the standard raw-mode pattern: save the current `termios` state for the local terminal, apply `cfmakeraw` to a *copy* of it, and restore the original state on exit — including on signal-driven exit paths, not just normal return.
+
+## Key findings
+
+- `cfmakeraw` is applied to a saved copy, never mutating the live state in place without a saved original to restore from.
+- Restoration must happen on every exit path, explicitly including signals — a program that puts the terminal in raw mode and then dies to an uncaught signal without restoring leaves the user's shell visibly broken (no echo, no line editing) until they run `reset` or `stty sane`.
+
+## Pros / strengths
+
+- Production code from a widely-used, heavily-tested tool (`adb`) rather than a toy example — this is the pattern battle-tested at scale.
+
+## Cons / limitations / caveats
+
+- A single commit view; doesn't show the surrounding signal-handler wiring in full, only confirms the save/apply/restore shape exists and is deliberate.
+
+## Relevance to tai
+
+The exact pattern any raw-mode terminal handling inside a tai-managed session (if tai ever needs to read raw keystrokes itself, rather than delegating entirely to tmux) must follow: save-copy-restore, restoration guaranteed on every exit path including signals, or a bug can leave the user's real terminal broken after the fact.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Everything You Need to Know About tmux Servers and Sessions (ArcoLinux)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Everything you need to know about tmux |
+| Source URL | https://arcolinux.com/everthing-you-need-to-know-about-tmux-servers-and-sessions/ |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the tmux-architecture query as a general tmux servers/sessions explainer; not independently opened since the man7 and tao-of-tmux dossiers already cover this ground with individually-attributed detail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Is This Shell Interactive? (Bash manual, via w3.pppl.gov mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | 5.3: Is This Shell Interactive? |
+| Source URL | https://w3.pppl.gov/info/bash/Is_This_Shell_Interactive$3f.html |
+| Source publisher / author | GNU Bash manual (mirrored by w3.pppl.gov) |
+| Source type | vendor docs |
+| 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
+
+Bash's own official definition: an interactive shell is one whose input and output are both connected to a terminal (as determined by `isatty(3)`), **or** one explicitly started with the `-i` option. This is the ground truth every other heuristic in this subject is approximating.
+
+## Key findings
+
+- The `-i` clause matters: a shell can be interactive even with redirected stdin/stdout if explicitly started with `-i` — a pure `isatty()` check on both streams would miss this case.
+- Conversely, a shell can have both stdin and stdout on a real terminal and still not be "interactive" in bash's sense if started non-interactively with neither `-i` nor a terminal-backed invocation that sets it.
+
+## Pros / strengths
+
+- This is the authoritative definition, not a third party's interpretation — any detection heuristic built for the proposal should be checked against this definition, not against folklore.
+
+## Cons / limitations / caveats
+
+- Being the formal definition, it does not itself address the proposal's actual hard problem: distinguishing a human sitting at a real interactive shell from an automation tool that also happens to satisfy this exact definition (a pty-backed agent terminal passes `isatty()` on both streams too).
+
+## Relevance to tai
+
+The floor every detection heuristic in the proposal must be built on: `$-` containing `i` (bash's own exposed signal for this definition) is the right primitive to start from — but, per the other dossiers in this subject, satisfying bash's own "interactive" definition is necessary, not sufficient, to conclude a *human* is present.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Arch Linux Forum — Second tmux Auto-Attach Thread
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | bbs.archlinux.org forum thread (id 207282) |
+| Source URL | https://bbs.archlinux.org/viewtopic.php?id=207282 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the auto-attach-pattern query as a second, distinct Arch forum thread on the same topic as the Tier 1 `$TMUX`-guard dossier; not independently read since the core pattern was already captured there.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Arch Linux Forum Thread — The $TMUX Guard Pattern
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | bbs.archlinux.org forum thread (tmux auto-attach) |
+| Source URL | https://bbs.archlinux.org/viewtopic.php?id=144544 |
+| Source publisher / author | Arch Linux Forums (community) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Establishes the core, near-universal guard for auto-attaching tmux from a shell rc file: `[[ -z "$TMUX" ]]`, since tmux itself sets the `$TMUX` environment variable inside any pane it creates. A forum participant confirms a simple `if [[ -z "$TMUX" ]]; then tmux attach; fi` block worked for them in practice.
+
+## Key findings
+
+- `$TMUX` is tmux's own self-identifying environment variable, set automatically inside every pane — checking for its absence is the standard way to avoid launching tmux inside itself (nested sessions).
+- This is community-tested, working advice, not a theoretical suggestion.
+
+## Pros / strengths
+
+- Simple, single-variable, directly tied to tmux's own behavior rather than an inferred heuristic — about as reliable a signal as exists for "am I already inside a tmux pane."
+
+## Cons / limitations / caveats
+
+- Only detects nesting on the *same host* — per the query D SSH-nesting dossier in this subject, `$TMUX` does not survive an SSH hop, so this guard alone is insufficient once remote sessions are involved.
+
+## Relevance to tai
+
+The mandatory first guard for the proposal's `.bashrc` hook: never attempt to auto-attach if `$TMUX` (or tai's own equivalent marker) is already set, to prevent runaway nested sessions — this is non-negotiable baseline safety, not an optional refinement.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Terminals and Pseudoterminals (biriukov.dev)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Terminals and pseudoterminals |
+| Source URL | https://biriukov.dev/docs/fd-pipe-session-terminal/4-terminals-and-pseudoterminals/ |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the tmux-architecture query; a general pty/terminal fundamentals reference, potentially relevant background for anyone implementing raw-mode/pty handling, but not individually read for this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# How to Automatically Start tmux on SSH Session (Codegenes)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | How to automatically start tmux on SSH session |
+| Source URL | https://www.codegenes.net/blog/how-to-automatically-start-tmux-on-ssh-session/ |
+| Source publisher / author | Codegenes.net |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A fuller auto-attach recipe that combines two conditions: `[[ -n "$SSH_TTY" ]]` (only act when the session is an actual SSH login) and `[[ -z "$TMUX" ]]` (not already nested), rather than the bare `$TMUX` guard alone.
+
+## Key findings
+
+- `$SSH_TTY` is set specifically for an SSH login session with a pty, making it a useful qualifier for "only auto-attach over SSH logins," a narrower and safer scope than "every bash startup everywhere."
+- Combining it with the `$TMUX` guard from the Arch forum dossier gives a two-condition gate rather than relying on one signal.
+
+## Pros / strengths
+
+- Narrows the blast radius of auto-attach logic specifically to a scenario (fresh SSH login) where multiplexing is genuinely almost always wanted, rather than firing on every local shell too.
+
+## Cons / limitations / caveats
+
+- Still vulnerable to the SSH-nesting failure mode described in this subject's unix.stackexchange dossier, since it doesn't address `$TMUX` failing to propagate across the SSH hop itself.
+
+## Relevance to tai
+
+A useful narrower variant for the proposal to consider: rather than auto-attaching on *every* interactive bash start, scope the riskiest/most valuable case (fresh remote logins) first, and treat local-terminal auto-attach as a separate, more cautious decision.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Auto-Attach or Start tmux at Login (Coderwall, mirrored)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Auto-attach or start tmux at login |
+| Source URL | https://coderwallhtbprolcom-s.evpn.library.nenu.edu.cn/p/tgm2la/auto-attach-or-start-tmux-at-login |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the auto-attach-pattern query (via an institutional proxy mirror URL); the search synthesis attributed a `$SSH_CONNECTION`-based guard variant to this source specifically, but it was not independently opened and read in full for this research pass — logged as Tier 2 rather than claiming more depth than was verified.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,55 @@
+# Conclusion: Build on tmux, Never Guess at "Is This a Human" Alone
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-09 |
+| Decided by | retoor, advised by tai (agent, Claude Sonnet 5) |
+| Status | Active (research complete, proposal pending decision, no code written) |
+| Confidence | High |
+
+## Question / problem statement
+
+retoor asked for a tai-managed terminal multiplexer, auto-attached transparently whenever a real interactive bash shell starts — but explicitly *not* when bash is invoked by automation, scripts, or tools (including tai/Claude Code's own shell tool) that happen to also source `.bashrc` — supporting resize, sound/bell passthrough, events, raw keystroke handling, a named-socket or fd-based control channel, programmatic commands (read pane content, grep it, write/type at a position, animated typing), and continuous full-session logging. Deep research was explicitly requested before any implementation.
+
+## Conclusion
+
+Build this as a thin control layer **on top of tmux**, not as a new PTY multiplexer kernel. tmux already provides, battle-tested, exactly the substrate this proposal needs: a client-server architecture over a configurable Unix socket (`-L`/`-S`), persistent sessions that survive disconnects, native SIGWINCH/resize handling, bell passthrough, hooks, a human-typing interface (`send-keys`/`capture-pane`), a structured scripting interface (control mode, `-CC`), and a continuous-logging primitive (`pipe-pane`) that directly satisfies "remember the whole process log." tai (per its own root `README.md`) already optionally depends on tmux and already shells out to `tmux capture-pane` rather than reimplementing terminal capture — this proposal is a natural extension of that existing posture, not a new direction.
+
+The one genuinely hard, unsolved-by-tooling part of the request is reliably distinguishing a human-opened interactive shell from bash being invoked by a script, IDE, or AI coding agent sourcing the same `.bashrc`. This research found it is a recognized, actively-discussed, unsolved-in-general problem (VS Code's own agent-terminal issues, security detection-rule false-positive guidance, dedicated "AI agent terminal detection" posts) with **no single reliable signal** — only a combination of weaker ones (`$-` containing `i`, `$TMUX` unset, `$SSH_TTY`/`$SSH_CONNECTION`, parent process name, an agent-identifying env var), each individually defeatable in one direction or the other.
+
+## Supporting sources
+
+- `../man7-tmux-manual.md`, `../tao-of-tmux-server-internals.md`, `../github-tmux-discussion-3567-no-raw-socket-api.md` — tmux's client-server/socket architecture and the hard boundary of what's scriptable (commands + control mode, no raw socket protocol).
+- `../tmuxai-dev-control-mode.md`, `../github-tmux-discussion-4016-control-mode-output.md`, `../github-tmux-wiki-control-mode.md`, `../libtmux-pane-interaction.md`, `../tmuxai-dev-faq.md` — the concrete mechanisms (`-CC` framing, send-keys/capture-pane loop, `pipe-pane` streaming) the control layer is built from.
+- `../android-adb-cfmakeraw-commit.md`, `../stalkr-remote-tty-resize-design.md`, `../systemd-ptyfwd-resize-forwarding.md`, `../coral-mdt-console-sigwinch-commit.md`, `../lkml-2003-sigwinch-foreground-process-group.md` — what would have to be hand-built (raw termios mode, SIGWINCH handling, resize-over-socket forwarding) if tmux were not used; the cost this recommendation avoids entirely, since tmux already does all of it internally.
+- `../bash-manual-interactive-shell-definition.md`, `../cyberciti-nixcraft-dollar-dash-test.md`, `../oreilly-bash-cookbook-interactive-test.md`, `../pythontutorials-net-ps1-child-process-caveat.md`, `../gitlab-mr-3383-stdin-stdout-isatty-mismatch.md`, `../lkml-mailing-list-tty-s-insufficient.md` — why `$-` is the right first-line interactivity check, and why `isatty`/`PS1`-alone checks fail in documented, specific ways.
+- `../elastic-detection-rule-interactive-terminal-python.md`, `../panoramicdata-detecting-ai-agent-terminals.md`, `../github-vscode-community-discussion-161238.md`, `../github-vscode-issue-253265.md`, `../github-fak-issue-11425-pty-interactive-prompt-detection.md` — independent, cross-domain confirmation that human-vs-automation terminal detection is a recognized hard problem with no single reliable signal, only combined weaker ones plus explicit allowlisting by known tool identity.
+- `../bbs-archlinux-tmux-env-guard.md`, `../codegenes-net-ssh-tty-tmux-guard.md`, `../unix-stackexchange-ssh-tmux-nesting.md`, `../santini-tmux-safety-file.md` — the concrete guard conditions (`$TMUX`, `$SSH_TTY`/`$SSH_CONNECTION`) and, critically, the mandatory safety-file bypass pattern for when the auto-attach logic itself is wrong.
+- `../dasroot-net-tmux-vs-zellij.md`, `../theregister-tiling-multiplexer-survey.md` — why tmux specifically, not Zellij, fits this proposal's scripting-and-SSH-heavy requirements.
+- `../github-bitcanon-autotyper.md`, `../nncron-send-keys-delay-docs.md`, `../tabby-typewriter-mode-docs.md`, `../raycast-fake-typing-effect.md`, `../k6-browser-presssequentially.md` — the basis for a typing-animation command syntax (per-character delay, inline pause/speed tokens, optional randomization).
+
+## Alternatives considered and rejected
+
+- **A from-scratch terminal multiplexer** (raw termios mode, SIGWINCH handling, a hand-rolled Unix-socket IPC protocol, session persistence, all built independently). Rejected: this re-solves a problem tmux has already solved, for a project whose own stated design philosophy (root `README.md`) is dependency-light and pragmatic, and which already optionally depends on tmux and already shells out to it for capture rather than reimplementing. The "research is done, confidence high" status above specifically reflects how thoroughly this exact problem surface (raw mode, resize forwarding, socket IPC) turned out to already be solved, documented, and battle-tested elsewhere.
+- **Zellij as the substrate instead of tmux.** Considered, not dismissed out of hand — but tmux fits better given tai already optionally depends on it, and the research (`dasroot-net-tmux-vs-zellij.md`) found tmux specifically stronger for scripting and SSH/remote use, which is the actual requirement here; Zellij's documented strength is a discoverable interactive UI, not a scripting substrate.
+- **A single boolean "is this shell interactive" check as the sole auto-attach gate.** Rejected: both the bash-detection dossiers and the automation-false-positive dossiers in this subject independently show this fails in both directions (automation tools that pass `isatty()`/`$-` checks; genuinely interactive shells an over-narrow check might miss).
+
+## Risks / open questions
+
+Unconditionally auto-wrapping every bash session from `.bashrc` is a high-blast-radius, hard-to-reverse-if-wrong system change: it can break automation, CI, IDE-integrated terminals, and — if misdetected — the agent's own shell tool (the exact tool this research is being conducted through). This was explicitly **not implemented** as part of this research task; it is proposed, pending the human's explicit review and confirmation of the exact activation condition and the mandatory safety-bypass mechanism (per `santini-tmux-safety-file.md`) before any `.bashrc` on a real machine is touched.
+
+## Action taken
+
+None yet. This was a research-and-proposal task; implementation is explicitly deferred pending retoor's review of the proposal presented alongside this archive.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial conclusion recorded. |
@@ -0,0 +1,46 @@
+# mdt console — SIGWINCH Self-Pipe Pattern (coral.googlesource.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | console: Add in SIGWINCH support |
+| Source URL | https://coral.googlesource.com/mdt/+/d5b37aa3c97daf3e29b0aeacfce1c5d3beb1dff8%5E%21/ |
+| Source publisher / author | Google Coral (mdt project) |
+| Source type | repository |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A commit adding SIGWINCH support to Google's `mdt` console tool, using the standard "signal handler just sets a flag (or writes to a self-pipe); the real work happens in the main loop" pattern — the handler itself never calls the ioctl or touches shared state directly.
+
+## Key findings
+
+- Signal handlers should do the absolute minimum (set a flag / write one byte to a self-pipe) because most libc/syscall operations are not safe to call from inside a signal handler; the actual `TIOCGWINSZ` read and any forwarding happens back in the normal event loop once it notices the flag/pipe-byte.
+
+## Pros / strengths
+
+- A real, shipped example of the "minimal signal handler, defer the work" discipline applied specifically to SIGWINCH, in Python-adjacent/C-level console tooling from a credible engineering org.
+
+## Cons / limitations / caveats
+
+- Specific to `mdt`'s own event-loop shape; the general principle (minimal handler, deferred work) transfers, the exact code structure doesn't.
+
+## Relevance to tai
+
+If tai ever writes its own `SIGWINCH` handler (e.g. in a thin Python control process around tmux), it must follow this exact discipline — `signal.signal(signal.SIGWINCH, lambda *a: flag.set())` and do the real `ioctl`/forwarding work in the main loop, never inside the handler itself.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Bash Check If Shell Is Interactive or Not (nixCraft / cyberciti.biz)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Bash Check If Shell Is Interactive or Not Under Linux / Unix Oses |
+| Source URL | https://www.cyberciti.biz/faq/linux-unix-bash-check-interactive-shell/ |
+| Source publisher / author | nixCraft (cyberciti.biz) |
+| Source type | blog post |
+| 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 practical guide recommending the `$-` special parameter (which contains the literal character `i` when the shell is interactive) as the preferred interactivity test, with the standard idiom `case "$-" in *i*) ... ;; esac`.
+
+## Key findings
+
+- `$-` is bash's own exposed flag string, set to include `i` precisely when the shell meets bash's formal interactive definition — it's reading bash's own self-assessment, not re-deriving it from `isatty()` calls.
+- The canonical test form is a `case` statement matching `*i*` against `$-`.
+
+## Pros / strengths
+
+- Simple, portable within bash, and directly backed by bash's own internal state rather than an external inference.
+
+## Cons / limitations / caveats
+
+- Like any `isatty`-adjacent signal, `$-` containing `i` says "bash thinks it's interactive," which — per the query E dossiers in this subject — a pty-backed automation tool or AI agent terminal can also satisfy. It answers "is bash interactive" correctly; it does not answer "is a human present."
+
+## Relevance to tai
+
+This is the first-line check for the proposal's auto-attach guard (`.bashrc` should do nothing at all unless `$-` contains `i`), but per this subject's conclusion, it must be combined with other signals, not used alone, to approximate "a human is here."
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Terminal Multiplexers: tmux vs Zellij — A Comprehensive Comparison (dasroot.net)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Terminal Multiplexers: tmux vs Zellij – A Comprehensive Comparison |
+| Source URL | https://dasroot.net/posts/2026/02/terminal-multiplexers-tmux-vs-zellij-comparison/ |
+| Source publisher / author | dasroot.net |
+| Source type | blog post |
+| Source date (published) | 2026-02 (approximate) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A comparison framing tmux as the Unix-tradition "small, composable tools" choice — plain-text config, shell-script-and-plugin extensibility — against Zellij's mode-based, discoverable, Rust-plus-WASM-plugin design aimed more at interactive usability than scripting.
+
+## Key findings
+
+- tmux is explicitly credited as stronger for scripting and remote/SSH use specifically — the exact two properties this proposal's "control layer" and "auto-attach over SSH" requirements both need.
+- Zellij's strengths (discoverability, on-screen key hints, built-in layouts) target interactive human usability, not programmatic control.
+
+## Pros / strengths
+
+- A direct, explicit comparison on exactly the axis that matters for this decision (scriptability vs. interactive UX), rather than a generic feature checklist.
+
+## Cons / limitations / caveats
+
+- A blog post, not a rigorous benchmark; no data on resource usage, performance under heavy automation load, or memory footprint for either tool.
+
+## Relevance to tai
+
+Directly supports choosing tmux over Zellij as the substrate: the proposal's actual requirements (scriptable control channel, SSH-friendly persistence, programmatic send/capture) are precisely tmux's documented strengths, not Zellij's.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# tmux/tmux (DeepWiki)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux/tmux |
+| Source URL | https://deepwiki.com/tmux/tmux |
+| Source type | other (AI-generated wiki) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the tmux-architecture query as the general DeepWiki root for the tmux project (distinct from the specific control-mode sub-page already dossiered at Tier 1); noted as an AI-generated wiki, so its specifics are treated as secondary even where they'd otherwise be read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Interactive Terminal Spawned via Python (Elastic detection rule)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Interactive Terminal Spawned via Python |
+| Source URL | https://detection.fyi/elastic/detection-rules/linux/execution_python_tty_shell/ |
+| Source publisher / author | Elastic (detection-rules), mirrored by detection.fyi |
+| Source type | vendor docs |
+| 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 security detection rule (also mirrored at elastic.co's own docs) that fires when a Python process spawns an interactive pty-backed shell — a pattern commonly associated with reverse shells, but one the rule's own documentation explicitly acknowledges is also produced by legitimate administrative scripts and automation tools. The prescribed remediation for false positives is to identify and allowlist the specific known-good tools, not to weaken the detection signal itself.
+
+## Key findings
+
+- A security vendor, writing a detection rule specifically meant to catch malicious activity, independently concludes that "spawns an interactive pty" is not by itself a reliable signal of anything in particular (malicious or benign) — it needs context (which process, with what parent, doing what) to be meaningful.
+- The recommended fix for false positives is allowlisting by known tool identity, not by relaxing the pty-interactivity check — i.e., the right axis to add is "who/what is doing this," not "make the interactivity test looser."
+
+## Pros / strengths
+
+- Comes from the security-detection domain, which has spent years dealing with exactly this ambiguity at scale (distinguishing legitimate automation from malicious activity using the same low-level signals) — directly transferable experience for this subject's human-vs-automation problem.
+
+## Cons / limitations / caveats
+
+- Framed around detecting malicious reverse shells, not around a shell startup hook's design; the finding (allowlist by identity, not by loosening the raw signal) transfers, but the specific rule logic itself does not.
+
+## Relevance to tai
+
+Validates the proposal's approach of combining `$-`/`$TMUX`/`$SSH_TTY` with an explicit allowlist/denylist of known parent-process names or environment markers (e.g. skip auto-attach when the parent is `claude`, `code`, a CI runner, etc.) rather than trying to find one perfect universal signal — exactly the security industry's own conclusion on the identical underlying ambiguity.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Run a Bash Script in tmux at Login with Auto Restart and Logging (fr0stb1rd)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | run a bash script in tmux at login with auto restart and logging |
+| Source URL | https://fr0stb1rd.is-a.dev/posts/run-a-bash-script-in-tmux-at-login-with-auto-restart-and-logging/ |
+| Source publisher / author | fr0stb1rd.is-a.dev |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A walkthrough of launching a long-running script inside a tmux session at login, with auto-restart on crash and output logging — a pattern for a persistent, supervised, logged session rather than a one-off interactive attach.
+
+## Key findings
+
+- tmux sessions are a reasonable place to supervise a long-running process with restart-on-crash logic, since the session (and its scrollback/log) survives independently of any one attached client.
+- Combines naturally with `pipe-pane`-style continuous logging (see the tmuxai.dev FAQ dossier) for a supervised, logged, auto-restarting background session.
+
+## Pros / strengths
+
+- A concrete worked example of exactly the "persistent, logged, supervised session" shape the proposal's "remember the whole process log" requirement needs, just applied to a background script rather than an interactive login shell.
+
+## Cons / limitations / caveats
+
+- Login-script use case, not login-shell-auto-attach — adjacent to, but not identical to, the proposal's actual scenario (wrapping a human's interactive shell).
+
+## Relevance to tai
+
+A useful pattern reference for a tai daemon/supervisor session that stays alive independent of any attach/detach cycle, logging continuously via `pipe-pane`, even when no human is currently attached.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# ptyfwd.c Source Listing (git.alternativebit.fr)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | src/shared/ptyfwd.c |
+| Source URL | https://git.alternativebit.fr/picnoir/Systemd/src/commit/32fea77178ff9aaa09a7b043965fce854fdf8874/src/shared/ptyfwd.c |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the pty/SIGWINCH query as the full source-browse view of the same `ptyfwd.c` file already dossiered at Tier 1 via its specific resize-forwarding commit — this card is the companion full-file listing, not independently re-read beyond what the Tier 1 commit dossier already covers.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# AutoTyper — CLI Terminal Input Simulator (bitcanon/autotyper)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | autotyper |
+| Source URL | https://github.com/bitcanon/autotyper |
+| Source publisher / author | bitcanon (GitHub) |
+| Source type | repository |
+| 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 real, purpose-built CLI tool for simulating terminal input for demos, tests, and CLI automation — configurable per-character delay (`--char-delay`, default 75ms) plus separate pre- and post-command delays.
+
+## Key findings
+
+- 75ms is used as the tool's own default "looks human" per-character delay — a reasonable starting default for the proposal's own animated-typing command.
+- Separate pre-command and post-command delays (not just inter-character delay) matter for a convincing demo/animation effect, beyond just character timing.
+
+## Pros / strengths
+
+- A real, maintained, purpose-fit tool rather than a repurposed library — its defaults and flag design are a direct, usable reference for the proposal's own "typing animated" command syntax.
+
+## Cons / limitations / caveats
+
+- Fixed per-character delay by default (no randomization/jitter) — per the Tabby dossier in this subject, a fixed delay reads as more "robotic" than randomized timing; worth noting as a design choice, not a flaw in the tool itself.
+
+## Relevance to tai
+
+A direct implementation reference for the proposal's animated-typing command: a configurable per-character delay (default ~75ms) plus pre/post-command pauses, fed into tmux via repeated single-character `send-keys -l` calls.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# AI Agent Terminal (GitHub Community Discussion #188494)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AI Agent Terminal |
+| Source URL | https://github.com/orgs/community/discussions/188494 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the automation-detection query; directly on-topic (AI agent terminal discussion) but not individually read — the Tier 1 PanoramicData and VS Code dossiers already cover this ground with attributed detail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# fak Issue #11425 — PTY Substrate for Interactive Prompt Detection
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | feat(codetools): terminal PTY substrate for shell execution with interactive prompt detection |
+| Source URL | https://github.com/anthony-chaudhary/fak/issues/11425 |
+| Source publisher / author | anthony-chaudhary/fak (GitHub repository) |
+| Source type | repository |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A feature request/issue proposing a dedicated PTY substrate purpose-built for "interactive prompt detection" as its own named engineering problem within a coding-tools project — direct evidence that another project independently identified this as a distinct, non-trivial piece of infrastructure worth building deliberately, not a one-line check.
+
+## Key findings
+
+- The issue frames "interactive prompt detection" as requiring its own substrate/abstraction layer, not a quick heuristic bolted onto existing shell-execution code.
+- This mirrors the earlier finding (from the agent's own prior work this session, building `tai_test.py`) that correctly driving/detecting interactive terminal state is substantial enough to warrant a dedicated framework rather than ad hoc code per call site.
+
+## Pros / strengths
+
+- Independent confirmation, from a completely different project tackling an adjacent problem (AI coding tool shell execution), that this is recognized, real engineering work.
+
+## Cons / limitations / caveats
+
+- A single open issue/feature request, not a shipped, documented solution — there is no implementation to inspect here, only the problem statement.
+
+## Relevance to tai
+
+Validates treating the detection logic in this proposal as a first-class, carefully-designed component (with its own tests and an explicit bypass, per the santini dossier) rather than a quick inline shell snippet in `.bashrc` — the same seriousness this project already applied to `tai_test.py`'s pty handling should apply here too.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# tmux GitHub Discussion #3567 — No Raw Socket API Planned
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Replies: 3 comments (tmux/tmux discussion #3567) |
+| Source URL | https://github.com/tmux/tmux/discussions/3567 |
+| Source publisher / author | tmux project (GitHub Discussions) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A GitHub Discussion in which a user asks for a way to send raw command strings directly to the tmux server socket, bypassing the existing command/control-mode interfaces. The maintainer's recorded position is that there are no plans to offer anything beyond what already exists (the command set and control mode).
+
+## Key findings
+
+- tmux's server socket protocol is not a documented, stable wire format open for third-party reimplementation — the only sanctioned ways in are the `tmux` CLI commands and control mode (`-C`/`-CC`).
+- This forecloses the option of a tai layer talking to the tmux server socket directly without going through the `tmux` binary itself.
+
+## Pros / strengths
+
+- Directly settles a design question before it becomes a dead end: don't try to speak tmux's internal socket protocol yourself.
+
+## Cons / limitations / caveats
+
+- A single maintainer comment in a discussion thread, not a formal API stability guarantee — could change, but is the best available signal today.
+
+## Relevance to tai
+
+Confirms the tai control layer must shell out to the `tmux` binary (plain commands or `-CC` control mode), not attempt to speak to `tmux`'s socket protocol directly — a cleaner, more future-proof design than reverse-engineering an undocumented wire format.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# tmux Discussion #4016 — Reading Command Output in Control Mode
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | How to read command output when in Control mode (-CC) |
+| Source URL | https://github.com/orgs/tmux/discussions/4016 |
+| Source publisher / author | tmux project (GitHub Discussions) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A real reported integration bug: a Rust program driving tmux with a single `-C` found that tmux detached the client as soon as its stdin was piped (non-interactive), and could not read command output back on stdout at all. The fix required passing `-CC` twice.
+
+## Key findings
+
+- `-C` alone is not sufficient for a piped/non-interactive client — tmux's detach-on-piped-stdin behavior silently breaks naive automation.
+- `-CC` (doubled) was the empirically-confirmed working flag for a programmatic client that pipes stdin and reads stdout, in the reporter's tmux version.
+
+## Pros / strengths
+
+- A concrete, reproduced failure mode with a confirmed fix — exactly the kind of gotcha that would otherwise cost real debugging time when building a tai control-mode client.
+
+## Cons / limitations / caveats
+
+- Behavior tied to a specific tmux version; the thread itself notes to check the current man page, since `-C`/`-CC` semantics have shifted across releases.
+
+## Relevance to tai
+
+Directly actionable: when tai spawns `tmux -CC` as a subprocess with piped stdin/stdout (the natural way to drive it from Python), use `-CC` (doubled), not a single `-C`, and verify against the installed tmux version's man page before shipping.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# tmux Wiki — Control Mode (GitHub + DeepWiki mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Control Mode |
+| Source URL | https://github.com/tmux/tmux/wiki/Control-Mode |
+| Source publisher / author | tmux project wiki |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+The tmux project's own wiki page on control mode, describing it as a way for a client to talk to tmux using normal tmux commands over plain text (built originally for iTerm2's tmux integration) plus `%`-prefixed control-only notifications. A near-identical mirror of the same material exists at deepwiki.com/tmux/tmux/7.1-control-mode.
+
+## Key findings
+
+- Control mode deliberately reuses the normal tmux command set rather than inventing a separate scripting API — a client only needs to learn the notification framing on top of commands it may already know.
+- Originally built for a GUI client (iTerm2) to render tmux panes natively, which is why it emphasizes structured notifications over raw terminal bytes.
+
+## Pros / strengths
+
+- Being the project's own wiki (not a third party's reverse-engineering), this is a materially more trustworthy reference than most blog posts on the topic.
+
+## Cons / limitations / caveats
+
+- A wiki page, not versioned documentation — it may drift from a specific tmux release's actual behavior; cross-check against the installed version's man page.
+
+## Relevance to tai
+
+The authoritative reference to build a tai control-mode client parser against — command reuse plus structured notifications is exactly the "accept commands + emit events" shape the proposal asks for.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# VS Code Copilot — Terminal Command Completion Not Reliably Detected (Discussion #161238)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Copilot does not detect terminal command has completed or is not getting terminal output |
+| Source URL | https://github.com/orgs/community/discussions/161238 |
+| Source publisher / author | GitHub Community Discussions (Copilot) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Documents that VS Code's own terminal API does not provide a reliable signal for "has this shell command finished," forcing Copilot's agent integration to fall back on heuristics — direct evidence that even a tool built by the same vendor as the terminal itself struggles with reliable terminal-state detection.
+
+## Key findings
+
+- The unreliability isn't specific to third-party automation reading a terminal from outside; it's present even for first-party tooling with presumably the best possible access to the terminal's actual state.
+- This is framed as an ongoing, acknowledged gap, not a solved problem with a known fix.
+
+## Pros / strengths
+
+- Strong corroborating evidence (from a major, well-resourced vendor's own open issue tracker) that reliable terminal-state/command-completion detection is a genuinely hard, unsolved-in-general problem — not something this proposal is failing to find an obvious answer to because of insufficient research.
+
+## Cons / limitations / caveats
+
+- About command-completion detection specifically, a related but distinct problem from this subject's main question (human vs. automation at shell *startup*) — cited here as supporting evidence for "terminal state detection is hard in general," not as a direct answer to the startup-detection question.
+
+## Relevance to tai
+
+Sets realistic expectations for the proposal: whatever detection heuristic ships, it should be designed to fail safe (default to NOT auto-wrapping when uncertain, with an easy manual opt-in) rather than promising perfect detection — because even well-resourced, first-party tooling hasn't solved the adjacent problem of terminal-state detection in general.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# VS Code Issue #253265 — Agent/Chat Extension Cannot See Terminal Command Output
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Agent/Chat extension cannot see terminal command output, but shows normally in terminal |
+| Source URL | https://github.com/microsoft/vscode/issues/253265 |
+| Source publisher / author | Microsoft (vscode repository) |
+| Source type | repository |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A filed VS Code bug where an agent extension's view of a terminal diverges from what a human actually sees rendered in the same terminal — the agent and the human are, in effect, looking at two different realities of the "same" shell session.
+
+## Key findings
+
+- Terminal output visible to a human is not guaranteed to be visible, in the same form, to a program also attached to that terminal — buffering, rendering, and capture paths can diverge.
+- This is a second concrete example (alongside #161238) of VS Code's own first-party integration hitting a reliability gap in terminal introspection.
+
+## Pros / strengths
+
+- A specific, filed, reproducible bug report rather than a vague generalization — adds concrete weight to the pattern already established by the other VS Code dossier in this subject.
+
+## Cons / limitations / caveats
+
+- A single bug report; doesn't establish how common or how severe the general class of issue is across tools, just that it occurs in a major one.
+
+## Relevance to tai
+
+Reinforces the same "design for graceful degradation, not perfect detection/capture" principle for the proposal: if a tai control layer captures pane content for its own `grep`/read commands, it should not assume its view will always exactly match whatever VS Code, another tool, or the human sees rendered — and should log/flag divergence rather than silently trusting a possibly-stale capture.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Respect the User's Preferred Shell in Agent Host Terminals (vscode #313160)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Respect the user's preferred shell in agent host terminals |
+| Source URL | https://github.com/microsoft/vscode/issues/313160 |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the automation-detection query; a VS Code agent-terminal issue tangentially related (shell preference, not detection per se) to this subject's core question, not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Check stdin rather than stdout for interactive terminals (GitLab MR #3383)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Check stdin rather than stdout for interactive terminals |
+| Source URL | https://gitlab.com/gitlab-org/gitlab-development-kit/-/merge_requests/3383/pipelines |
+| Source publisher / author | GitLab (gitlab-development-kit project) |
+| Source type | repository |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A real-world merge request fixing an interactivity check that tested `stdout.isatty()` when it should have tested `stdin.isatty()` — the two can legitimately disagree (e.g. output piped to a pager while input stays a real terminal, or vice versa).
+
+## Key findings
+
+- `stdin.isatty()` and `stdout.isatty()` are independent facts and can differ in either direction in real, common shell usage (piping, redirection).
+- Which one is the "right" one to check depends on what the check is actually trying to answer (can I read user input? vs. can I write formatted/colored output?) — conflating them is a real, shipped bug class.
+
+## Pros / strengths
+
+- A fixed, real production bug (not a hypothetical) — concrete evidence this mismatch actually bites people, not just a theoretical edge case.
+
+## Cons / limitations / caveats
+
+- Specific to one project's bug fix; doesn't generalize a universal rule beyond "check the stream that matches what you actually need, and don't assume stdin/stdout agree."
+
+## Relevance to tai
+
+A direct implementation warning for the proposal's `.bashrc` detection logic: if it ever needs to distinguish "can prompt a human" from "output looks like a terminal," check `stdin` specifically (`[ -t 0 ]`), not `stdout`, and never assume the two will match.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Terminally-mcp tmuxManager.ts (glama.ai)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmuxManager.ts (NightTrek/Terminally-mcp) |
+| Source URL | https://glama.ai/mcp/servers/@NightTrek/Terminally-mcp/blob/f44a4f3662a146eebcde20784e651a84f9477ea3/src/services/tmuxManager.ts |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; an MCP server's TypeScript tmux-management service, a candidate reference implementation for a tai control layer's architecture, not independently read in this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# System-wide bash.bashrc Mirrors (Hugging Face datasets)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | # System-wide .bashrc file for interactive bash(1) shells. |
+| Source URL | https://huggingface.co/datasets/ACCC1380/private-model/blob/d408768214efcb32a4c5f6ba0ae26dae26382007/etc/bash.bashrc |
+| Source type | other (dataset mirror of a config file) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the interactive-shell-detection query as a mirrored copy of a stock `/etc/bash.bashrc` (two further near-identical mirrors of the same file also surfaced: `raw/0d510755.../etc/bash.bashrc` and `refs%2Fpr%2F9/etc/bash.bashrc`, same underlying file, logged here as one family rather than three cards). Relevant only as an example of the stock interactive-shell guard comment already present in most distro bashrc files, not independently analyzed.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# tmux Custom Prompt & Execution Guide (inskillclaude.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux Custom Prompt & Execution Guide |
+| Source URL | https://www.inskillclaude.com/skills/tmux |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; appears to be a Claude-skill-oriented tmux usage guide, relevant to the "AI agent drives tmux" pattern but not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,46 @@
+# k6 Browser Locator — pressSequentially
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Locator.pressSequentially() |
+| Source URL | https://grafana.com/docs/k6/next/javascript-api/k6-browser/locator/presssequentially.md |
+| Source publisher / author | Grafana (k6) |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A browser-automation API method (Playwright-style) that types a string one character at a time with a configurable inter-keystroke delay (e.g. 100ms), used to approximate real user typing speed when driving a web page.
+
+## Key findings
+
+- The same "type one character at a time with a delay" pattern recurs independently in browser automation, confirming it's a general, cross-domain technique for simulating realistic input, not something specific to terminal tooling.
+
+## Pros / strengths
+
+- A well-documented, widely-used API from a credible, maintained testing tool — strong confirmation the per-character-delay approach is a standard, understood pattern across the whole automation-tooling industry, not a niche terminal-specific hack.
+
+## Cons / limitations / caveats
+
+- Browser DOM input, not terminal/pty input — the delay-timing concept transfers; the actual API and event model do not.
+
+## Relevance to tai
+
+Further corroborates the proposal's planned typing-animation approach (character-by-character `send-keys -l` with a configurable delay) as a standard, well-understood pattern across the automation tooling industry, not something tai would be inventing from scratch.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Locator.pressSequentially (k6 v2.3.x docs mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Locator.pressSequentially (v2.3.x) |
+| Source URL | https://grafana.com/docs/k6/v2.3.x/javascript-api/k6-browser/locator/presssequentially.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the typing-animation query as an older-version-pinned mirror of the same k6 `pressSequentially` documentation already dossiered at Tier 1 via the `next` docs version.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Insert Text by Typing - Random Speed (Keyboard Maestro forum)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Insert text by typing - random speed |
+| Source URL | https://forum.keyboardmaestro.com/t/insert-text-by-typing-random-speed/27400 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the typing-animation query; a macOS automation forum thread on randomizing keystroke delay, a minor independent data point already better covered by the Tabby dossier, not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Zellij Terminal Multiplexer: Modern tmux/screen Alternative Guide (kx.cloudingenium.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Zellij terminal multiplexer: modern tmux/screen alternative guide |
+| Source URL | https://kx.cloudingenium.com/es/zellij-terminal-multiplexer-modern-tmux-screen-alternative-guide |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the multiplexer-comparison query; another general Zellij-as-alternative guide, not independently read for the same reason as the other Zellij-promotional dossiers in this batch (core comparison already attributed elsewhere).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# Pane Interaction — libtmux docs
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Pane Interaction - libtmux 0.53.0 documentation |
+| Source URL | https://libtmux.git-pull.com/topics/pane_interaction.html |
+| Source publisher / author | libtmux project |
+| Source type | vendor docs |
+| 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
+
+libtmux's own documentation for the send-keys/capture-pane automation pattern: spawn or attach a session, send keystrokes with `send_keys`, read the rendered screen back with `capture_pane` (optionally the full scrollback via `-S -`), and loop until the expected state appears.
+
+## Key findings
+
+- The canonical "drive and poll" loop: `send_keys()` then `capture_pane()`, waiting briefly for output to catch up before reading.
+- A documented, easy-to-miss gotcha: a command is **not executed** unless `Enter` is sent as its own, separate key event — typing the text alone leaves it sitting unexecuted in the prompt.
+- Output can lag behind the command that produced it, so libtmux's own examples add short sleeps before capturing.
+
+## Pros / strengths
+
+- Comes from a maintained Python wrapper library that has clearly hit these exact gotchas in practice — the Enter-must-be-separate warning in particular is the kind of thing that silently breaks automation until someone documents it.
+
+## Cons / limitations / caveats
+
+- The send+capture+sleep loop is inherently a polling approach with a race condition (how long is "briefly"?) — it's not real event-driven I/O the way control-mode notifications are.
+
+## Relevance to tai
+
+This is the baseline implementation for the proposal's "write/type at a position" and "read pane content" commands when NOT using control mode — and the Enter-as-separate-key gotcha must be built into the design from day one, not discovered via a bug report later.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# libtmux Control-Mode Support Commit
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | libtmux commit 646c050716ed23965db0b9de1ebe4a3230704cd3 |
+| Source URL | https://github.com/tmux-python/libtmux/commit/646c050716ed23965db0b9de1ebe4a3230704cd3 |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; appears to be the commit adding control-mode support to libtmux (Python), a potentially directly reusable library for a tai control layer, flagged for later deeper review rather than analyzed now.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# LKML 2003 — SIGWINCH Only Reaches the Foreground Process Group
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | RFC/CFT 1/1: SIGWINCH - behaviour change |
+| Source URL | https://lkml.iu.edu/hypermail/linux/kernel/0302.1/1591.html |
+| Source publisher / author | Linux kernel mailing list (2003) |
+| Source type | forum thread |
+| Source date (published) | 2003 (approximate, per thread era) |
+| 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 kernel-mailing-list discussion establishing that `SIGWINCH` is only ever delivered to the *foreground* process group of a terminal — a backgrounded or detached job (exactly tmux's own panes when no client is attached) will not receive it even if the underlying terminal size genuinely changed.
+
+## Key findings
+
+- A process group needs to be in the foreground to receive `SIGWINCH` at all; this is a kernel-level restriction, not an application bug.
+- The direct consequence: relying solely on the signal to learn about a resize is insufficient for anything that can be backgrounded or detached (a tmux session with no client, or any session reattached later) — the size must be re-read and re-applied explicitly on resume/reattach, not assumed to have been kept in sync via signals the whole time.
+
+## Pros / strengths
+
+- Primary-source kernel discussion, not a secondary summary — authoritative on kernel signal-delivery semantics.
+
+## Cons / limitations / caveats
+
+- Old (2003) thread; kernel behavior in this specific area has been stable since, per the broader search synthesis, but worth a sanity check against current kernel docs if correctness here is load-bearing for a safety property.
+
+## Relevance to tai
+
+Directly explains why tmux itself re-queries and re-applies window size on `attach`/`reattach` rather than relying purely on signals (this is exactly the detach/reattach cycle the proposal's whole persistent-session model depends on) — confirms that if tai ever builds any of this logic itself rather than delegating to tmux, it must re-sync size explicitly on every reattach, never assume signals alone kept it current.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Linux Makefile color-ls thread — tty -s Is Not an Interactivity Check (lkml mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Re: Linux Makefile uses 'ls', causes problems with color-ls (PATCH) |
+| Source URL | https://lkml.rescloud.iu.edu/9903.3/1188.html |
+| Source publisher / author | Linux kernel mailing list (mirrored) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+An old kernel-mailing-list reply making the point directly: `tty -s` (or a bare `isatty()` check) does not by itself detect an "interactive shell" — it can still read true in a non-interactive shell simply because that shell's input wasn't redirected away from a terminal.
+
+## Key findings
+
+- A non-interactive shell (e.g. one running a script) can still have a terminal-connected stdin if nobody redirected it — `isatty()` alone conflates "connected to a terminal" with "is an interactive shell," which are different facts.
+- This is a decades-old, well-understood pitfall, not a new or contested one.
+
+## Pros / strengths
+
+- A long-standing, hard-learned lesson from kernel/toolchain discussion, independently corroborating the bash manual's own choice to define "interactive" via `-i` OR `isatty()`, not `isatty()` alone.
+
+## Cons / limitations / caveats
+
+- Old (1999-era) message, color-ls-specific context — but the underlying `isatty()` limitation it demonstrates hasn't changed.
+
+## Relevance to tai
+
+Reinforces (from yet another independent angle, now four sources deep in this subject) that no single `isatty`/`tty -s`-style check is sufficient for the proposal's human-detection problem — it must combine `$-`, not just raw tty-connectedness.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# LKML — SIGWINCH Problem with Terminal Apps Still Alive (reply threads)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Re: [PATCH 0/5] SIGWINCH problem with terminal apps still alive |
+| Source URL | https://lkml.iu.edu/hypermail/linux/kernel/0810.2/0113.html |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the pty/SIGWINCH query as part of a 2008-era kernel mailing-list thread family about SIGWINCH delivery to terminal apps (two further replies in the same thread also surfaced: `0810.1/2485.html` and `0810.2/0656.html`, logged here as one family). The core foreground-process-group finding from this thread family is already captured at Tier 1 via the 2003 RFC/CFT dossier; these later replies were not independently read in full.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# tmux: Orchestrating Agents with send-keys and capture-pane (mager.co)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux: orchestrating agents with send-keys and capture-pane |
+| Source URL | https://www.mager.co/blog/2026-08-23-orchestrating-agents-with-tmux/ |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; directly on-topic (using tmux to orchestrate AI agents), a strong candidate for later promotion to Tier 1 if read in depth, but not analyzed in this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,49 @@
+# tmux(1) Manual Page (man7.org)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | tmux(1) - Linux manual page |
+| Source URL | https://man7.org/linux/man-pages/man1/tmux.1.html |
+| Source publisher / author | man7.org (Michael Kerrisk's man-pages mirror) |
+| Source type | vendor docs |
+| 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
+
+The canonical tmux manual page. Confirms tmux is a client-server program: the server and each attaching client are separate processes communicating through a Unix domain socket stored under `/tmp` (or `$TMPDIR`), with the socket name/path configurable via `-L`/`-S`.
+
+## Key findings
+
+- tmux's server holds all session state; a client is only a terminal attaching to it — this is the architecture a tai-managed multiplexer would want to reuse rather than reimplement.
+- The socket location is explicit and overridable (`-L name` picks a name under the default directory, `-S path` picks a full path), which is exactly the hook point needed to run a tai-dedicated tmux server on its own socket, isolated from any tmux the user runs themselves.
+- Session persistence across disconnects (SSH timeout, terminal close) is a direct consequence of the server living outside any one client's process.
+
+## Pros / strengths
+
+- Authoritative, current reference for the exact flags (`-L`, `-S`, `-C`, `-CC`) a control layer would depend on.
+- Confirms the socket-based design is a stable, documented contract, not an internal implementation detail likely to change.
+
+## Cons / limitations / caveats
+
+- A man page describes the interface, not the internal event loop or data structures — nothing here on performance characteristics or server resource usage under many panes.
+
+## Relevance to tai
+
+Directly supports the proposal's core recommendation: a tai-managed multiplexer should run its own tmux server on a dedicated socket (`-S ~/.tai/tmux.sock` or similar) rather than building a PTY multiplexer from scratch.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Implement tmux control mode (-CC) — microsoft/terminal #5612
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Implement tmux control mode (-CC) |
+| Source URL | https://github.com/microsoft/terminal/issues/5612 |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; a feature request for Windows Terminal to support tmux -CC natively, relevant context for cross-platform control-mode adoption but not individually read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Control Mode (mintlify.wiki mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Control Mode - tmux |
+| Source URL | https://mintlify.wiki/tmux/tmux/guides/control-mode |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query as another mirror of the same control-mode documentation already dossiered via the tmux project wiki and tmuxai.dev.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,46 @@
+# Keyboard Input Emulation — SEND-KEYS-DELAY (nncron.ru)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Keyboard Input Emulation |
+| Source URL | https://nncron.ru/help/EN/commands/send_keys.htm |
+| Source publisher / author | nnCron |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Documentation for a Windows automation tool's keystroke-injection command, supporting a global `SEND-KEYS-DELAY` directive for inter-keystroke delay ("slow typing" emulation) plus an inline `{DELAY n}` token embeddable directly inside the string being sent, for one-off pauses at specific points.
+
+## Key findings
+
+- Two levels of timing control: a global default delay, and inline per-position overrides — a more flexible model than a single fixed delay for the whole string.
+
+## Pros / strengths
+
+- The inline-token approach (`{DELAY n}` inside the string) is a clean, compact syntax worth borrowing for a tai scripting command, rather than requiring separate delay arguments per chunk of text.
+
+## Cons / limitations / caveats
+
+- Windows-specific tool (keystroke injection via the Windows API), not directly portable, but the *syntax idea* (inline delay tokens) is platform-agnostic.
+
+## Relevance to tai
+
+A good model for the proposal's animated-typing command syntax: support both a default per-character delay and inline markup for pauses at specific points in the typed text, rather than only a single global speed setting.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# How to Recover Disconnected Sessions with tmux on Ubuntu (OneUptime)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | How to Recover Disconnected Sessions with tmux on Ubuntu |
+| Source URL | https://oneuptime.com/blog/post/2026-03-02-how-to-recover-disconnected-sessions-with-tmux-on-ubuntu/markdown |
+| Source publisher / author | OneUptime |
+| Source type | blog post |
+| Source date (published) | 2026-03-02 |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Covers the recovery workflow when an SSH connection drops mid-session: the tmux server keeps running independently, and `tmux attach` reconnects to exactly the state the session was in — the practical payoff of the client-server architecture described in the man7 dossier.
+
+## Key findings
+
+- Session persistence across disconnects isn't just a theoretical architecture benefit — this source frames it specifically as the recovery procedure for the common real failure (dropped SSH connection), which is the actual day-to-day value proposition.
+
+## Pros / strengths
+
+- Concrete, recent (2026) operational guide rather than abstract architecture description — grounds the "why bother with tmux at all" case in a real daily annoyance it solves.
+
+## Cons / limitations / caveats
+
+- Ubuntu-specific framing, though the underlying tmux behavior is platform-agnostic.
+
+## Relevance to tai
+
+Reinforces the core value proposition the whole proposal rests on: wrapping every shell in a tai-managed tmux session means a dropped connection, closed terminal, or SSH timeout never loses the session's state or scrollback — exactly what "enforcing a user is always terminal multiplexed" is meant to guarantee.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# AutoSkill Python Console Simulation with Typing Effect (OpenSkillIndex)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AutoSkill Python Console Simulation with Typing Effect |
+| Source URL | https://openskillindex.com/skills/ecnu-icalk-autoskill-python-console-simulation-with-typing-effect |
+| Source type | other (skill listing) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the typing-animation query; a listed "skill" simulating a Python console with a typing effect — directly on-topic for terminal typing animation, not independently read in this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Bash Cookbook — Testing for an Interactive Shell (O'Reilly)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Bash Cookbook, "Use the following case" excerpt |
+| Source URL | https://www.oreilly.com/library/view/bash-cookbook/0596526784/ch01s10.html |
+| Source publisher / author | O'Reilly Media (Bash Cookbook) |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+An independent, published-book confirmation of the `$-` test, explicitly stating it as the *preferred* method over checking whether `$PS1` is set.
+
+## Key findings
+
+- Corroborates the nixCraft guide's recommendation from a second, independent, edited (not just blog) source.
+- Explicitly ranks `$-` above the `$PS1`-is-set check, rather than treating them as interchangeable.
+
+## Pros / strengths
+
+- A published, edited technical book is a stronger signal of broad community consensus than any single blog post — two independent sources agreeing on the same preferred test is meaningful corroboration.
+
+## Cons / limitations / caveats
+
+- Older reference material (the Bash Cookbook predates most AI-agent-terminal concerns); it has nothing to say about the automation-vs-human distinction this subject's proposal actually needs.
+
+## Relevance to tai
+
+Corroborating evidence (not new information) for using `$-` over `$PS1` as the proposal's first-line interactivity check.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# piuu — Typing Simulation (Packagist, PHP)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | wahyulingu/piuu |
+| Source URL | https://packagist.org/packages/wahyulingu/piuu |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the typing-animation query; a PHP package adding random delays, skipped letters, and vowel swaps to simulate typing errors — a third independent implementation of the typo-injection idea already dossiered via Tabby, not independently read in detail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,49 @@
+# Detecting AI Agent Terminals in PowerShell (PanoramicData community)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Detecting AI Agent Terminals in PowerShell |
+| Source URL | https://community.panoramicdata.com/t/detecting-ai-agent-terminals-in-powershell/116 |
+| Source publisher / author | PanoramicData community forum |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A direct discussion of this exact problem — telling an AI coding agent's terminal apart from a genuine human one — on a different shell (PowerShell, not bash), using a combination of agent-specific environment-variable checks, parent-process-name inspection, and interactive-mode detection together, rather than any single signal.
+
+## Key findings
+
+- Real tools in this space (per the search synthesis, including a shell-prompt configuration project) already check for an `AI_AGENT`-style environment variable and skip normal interactive behavior (loading a prompt theme, etc.) when both that variable is set AND the shell is otherwise non-interactive.
+- A separate tool mentioned in the synthesis takes a different approach: it identifies agent CLIs by process name (`claude`, `codex`, `gemini`, `amp`) rather than by environment variable, specifically to avoid raising false alerts for ordinary bash sessions.
+- Confirms multiple independent tools in the wild have already converged on "combine several weak signals" as the working answer, on a different OS/shell, for essentially the same problem this subject is researching for bash.
+
+## Pros / strengths
+
+- Cross-platform corroboration (PowerShell, not bash) of the same conclusion this subject's bash-specific dossiers reach independently — strengthens confidence this is a fundamental property of the problem, not a bash-specific quirk.
+- Names a concrete, already-existing convention (an `AI_AGENT`-style env var) that tai could adopt or recognize for interoperability with other tools doing the same detection.
+
+## Cons / limitations / caveats
+
+- PowerShell-specific implementation details don't transfer directly to bash; only the *strategy* (combine env var + parent process + mode) transfers.
+
+## Relevance to tai
+
+Directly supports the proposal's recommended detection design: check a combination of `$-` (interactive flag), `$TMUX`/`$SSH_TTY` (not-already-wrapped), and the parent process name/an agent-identifying env var (to explicitly exclude known automation tools, including Claude Code's own shell tool) — never a single signal.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Zellij Terminal Multiplexer Guide 2026 (PetronellaTech)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Zellij Terminal Multiplexer Guide 2026 |
+| Source URL | https://petronellatech.com/blog/zellij-terminal-multiplexer-guide-2026/ |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the multiplexer-comparison query; a general Zellij guide, not independently read since the dasroot.net comparison dossier already covers the tmux-vs-Zellij tradeoff with attributed detail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# tmux-control (PyPI)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux control |
+| Source URL | https://pypi.org/project/tmux-control |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; a Python package apparently wrapping tmux control mode, potentially a reusable reference implementation if tai's control layer is written in Python, but not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Checking for Interactive Shell in a Python Script (pythontutorials.net)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | How to Check if a Shell is Interactive in a Python Script: Preferred Methods Explained |
+| Source URL | https://www.pythontutorials.net/blog/checking-for-interactive-shell-in-a-python-script/ |
+| Source publisher / author | pythontutorials.net |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Suggests checking whether `PS1` exists in a Python script's environment as a proxy for shell interactivity — flagged independently (not by this source, but by general knowledge noted in the search synthesis) as unreliable, since `PS1` is normally a shell variable that is not exported to child processes.
+
+## Key findings
+
+- `PS1`, unless explicitly `export`ed, is invisible to any child process (including a Python script, or tai itself if written in Python) inspecting its own environment — `os.environ.get("PS1")` will typically be empty even in a genuinely interactive parent shell.
+- This caveat is a real correctness bug if a tai component written in Python ever tried to re-derive "is the parent shell interactive" from its own `os.environ`.
+
+## Pros / strengths
+
+- Surfaces a specific, concrete correctness trap for exactly the kind of cross-language (bash-to-Python) interactivity check the proposal would otherwise be tempted to write.
+
+## Cons / limitations / caveats
+
+- The source itself suggests the `PS1`-in-environment check as a *method*; the caveat about its unreliability from a child process comes from general knowledge noted alongside the search synthesis, not from the source's own text — treat the caveat as independently well-established (PS1 export behavior is standard shell semantics), but attribute it honestly as outside this specific article.
+
+## Relevance to tai
+
+A hard "don't do this" for the proposal: any Python-side component of tai must never try to detect shell interactivity by reading `PS1` from `os.environ` — it won't be there even when the parent genuinely is interactive. Detection has to happen in the shell (`.bashrc`, via `$-`) and be passed to tai explicitly (an env var, an argument), not re-derived downstream.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# Fake Typing Effect (Raycast)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Fake Typing Effect |
+| Source URL | https://www.raycast.com/cyberistic/fake-typing-effect |
+| Source publisher / author | Raycast (cyberistic extension) |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A Raycast extension offering a small inline markup language for animated typing: `[0.5]` for a half-second pause, `[speed:20]`/`[speed:100]` to change typing speed mid-string, and special tokens like `[enter]` and `[tab]` for non-printable keys — explicitly positioned for demos, tutorials, and presentations.
+
+## Key findings
+
+- A compact, readable inline-markup syntax (`[pause]`, `[speed:N]`, `[enter]`, `[tab]`) that mixes timing control and special-key injection in one string, rather than separate parameters.
+
+## Pros / strengths
+
+- The cleanest example found of a single, simple string syntax that a human could write by hand for a scripted demo — directly adoptable as the shape of a tai "type" command's argument.
+
+## Cons / limitations / caveats
+
+- A Raycast (macOS launcher) extension, not a terminal tool — the markup idea transfers, the implementation does not.
+
+## Relevance to tai
+
+The strongest direct model for the proposal's typing-animation command syntax: something like `tai type "echo hello[0.5][speed:20]world[enter]"` — inline pause/speed/special-key tokens in one readable string, rather than a complex multi-argument API.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# tmuxr send_keys (R package docs)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | send_keys: Send keys to a tmux pane in datascienceworkshops/tmuxr |
+| Source URL | https://rdrr.io/github/datascienceworkshops/tmuxr/man/send_keys.html |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; an R-language tmux wrapper's send_keys docs, corroborating (by existing at all) that the send-keys pattern has bindings across multiple languages, but not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# My tmux setup (santini.di.unimi.it) — The Safety-File Escape Hatch
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | my tmux setup |
+| Source URL | https://santini.di.unimi.it/extras/ph/my-tmux-setup |
+| Source publisher / author | santini.di.unimi.it (personal page) |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Describes a personal dotfiles setup that auto-attaches tmux from `.bashrc`, with a specific safety mechanism: the presence of a marker file on disk bypasses the auto-attach logic entirely. If a broken rc configuration would otherwise lock the user out of a usable shell (especially over SSH, where there's no other way in), creating that file lets them log in to a plain, unwrapped shell to fix the configuration.
+
+## Key findings
+
+- A broken auto-attach hook in `.bashrc` is a realistic, self-inflicted lockout risk, severe enough that at least one real setup builds a dedicated bypass for it.
+- The bypass is simple and robust: a file's mere existence, checked before any other logic runs, with no dependency on the auto-attach logic itself being correct.
+
+## Pros / strengths
+
+- A genuinely important, under-discussed safety pattern — auto-attach hooks in shell rc files are exactly the kind of thing that can strand a user with no way back in except an out-of-band recovery path (single-user mode, a cloud console's serial/VNC access, etc.) if something goes wrong.
+
+## Cons / limitations / caveats
+
+- A personal setup description, not a widely-adopted standard — but the underlying risk it addresses is universal to any rc-file auto-launch design, including this proposal's.
+
+## Relevance to tai
+
+This is a mandatory safety requirement for the proposal, not an optional nicety: before any `.bashrc` hook is live on a real machine, there must be an unconditional, dead-simple bypass (e.g. `TAI_PLEXER_DISABLE=1` env var, or a marker file like `~/.tai/no-plexer`) checked *before* any other detection logic, so a bug in the detection code itself can never fully lock the user out of a plain shell.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# List tmux Sessions, Capture Pane Output, Send Input (skills.rest)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux: List tmux sessions, capture pane output, and send input to panes |
+| Source URL | https://skills.rest/skill/tmux-p-sree-sai-pavan |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the control-mode query; another AI-agent-skill-style tmux wrapper, directly on-topic for "accept commands like reading/writing a pane" but not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Remote TTY with Terminal Resize (StalkR/misc/pty, Go)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Remote TTY with terminal resize (Linux) |
+| Source URL | https://beta.pkg.go.dev/github.com/StalkR/misc/pty |
+| Source publisher / author | StalkR (GitHub, misc repository) |
+| Source type | repository |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A Go package design for a remote pty with working resize support: on `SIGWINCH`, read the new size via the `TIOCGWINSZ` ioctl, forward it over a control channel to the remote side, which applies it to its own pty master via `TIOCSWINSZ`.
+
+## Key findings
+
+- The ioctl pair (`TIOCGWINSZ` read locally, `TIOCSWINSZ` set remotely) is the standard mechanism for propagating terminal size across a process boundary (local terminal to a remote/forwarded pty).
+- A control channel, separate from the raw data stream, is needed to carry resize (and other non-data) events — the write-up notes this explicitly as a multiplexing requirement on the socket design.
+
+## Pros / strengths
+
+- Names the exact two ioctls needed and the data flow between them, which is precise, directly implementable guidance rather than a vague description.
+
+## Cons / limitations / caveats
+
+- A documentation page for a Go package, not Python — the ioctl calls (`fcntl.ioctl` in Python, per the search synthesis's own sketch) are the same underlying kernel interface, but the surrounding code shape differs by language.
+
+## Relevance to tai
+
+If a tai layer ever forwards resize events itself (rather than letting tmux handle resize natively, which it already does), this is the exact mechanism: `signal.SIGWINCH` handler -> `fcntl.ioctl(fd, termios.TIOCGWINSZ, ...)` to read -> send over the control socket -> `TIOCSWINSZ` on the far end. Using tmux (which already does all of this internally) avoids needing to implement it at all.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# TIL: Zellij — Terminal Workspace (stonecharioteer.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Zellij - Terminal Workspace |
+| Source URL | https://tech.stonecharioteer.com/posts/2021/til-zellij-terminal-multiplexer |
+| Source publisher / author | stonecharioteer.com |
+| Source type | blog post |
+| Source date (published) | 2021 |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Low |
+| Status | Active |
+
+## Summary
+
+A short "today I learned" note on first impressions of Zellij, emphasizing its on-screen key-hint discoverability as the standout feature versus tmux's learn-the-keybindings-from-memory model.
+
+## Key findings
+
+- Zellij's discoverability advantage (visible key hints) is a genuine, repeatedly-cited differentiator for human-facing interactive use, consistent with the dasroot.net comparison dossier.
+
+## Pros / strengths
+
+- An early (2021), first-hand account, useful as a sanity check that Zellij's core positioning (discoverable UX over tmux's muscle-memory UX) has been consistent since its early days, not a recent marketing reframe.
+
+## Cons / limitations / caveats
+
+- Old (2021) and short; Zellij has evolved since, and this note shouldn't be treated as reflecting its current (2026) feature set in detail.
+
+## Relevance to tai
+
+Minor corroborating context only — doesn't change the substrate recommendation (tmux), since the proposal's actual need is scriptability, not on-screen discoverability for a human driving the multiplexer's own UI directly.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# systemd ptyfwd.c — Resize Forwarding Implementation
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ptyfwd: optionally override terminal width/height (commit) |
+| Source URL | https://git.alternativebit.fr/picnoir/Systemd/commit/d435a18244ff52132d873859126e7a3ece66a9ba |
+| Source publisher / author | systemd project (mirrored) |
+| Source type | repository |
+| 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 real commit in systemd's `ptyfwd.c` implementing the mirror-image of the StalkR dossier's design: reading the size from the local stdout and applying it to a pty master via `TIOCSWINSZ`, i.e. the production-grade version of the same resize-forwarding pattern in a widely-deployed init system's own pty-forwarding code.
+
+## Key findings
+
+- Confirms the `TIOCGWINSZ`/`TIOCSWINSZ` pattern is not just a hobby-project technique — it's how one of the most widely deployed pieces of Linux infrastructure (systemd) forwards terminal size across a pty boundary.
+
+## Pros / strengths
+
+- Production code in a security- and correctness-sensitive project (systemd); a strong confidence signal for the pattern's correctness and necessity.
+
+## Cons / limitations / caveats
+
+- A single commit diff; doesn't show the full surrounding event-loop integration (how/when the resize check gets triggered) in this excerpt.
+
+## Relevance to tai
+
+Second independent confirmation (alongside StalkR) of the exact resize-forwarding mechanism — further strengthens the case that this is solved, known, and would be pure reinvention-cost if a from-scratch multiplexer were built instead of wrapping tmux (which already implements this internally and transparently).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Tabby — Typewriter Mode
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | typewriter mode |
+| Source URL | https://www.mintlify.com/TabbyAIKeyboard/tabby/features/automation/typewriter-mode |
+| Source publisher / author | Tabby (TabbyAIKeyboard project) |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Documents a feature that varies per-keystroke delay randomly, adds extra pauses after punctuation and spaces, and injects then backspace-corrects QWERTY-neighbor-key typos at a configurable rate (an example config shown uses roughly a 3% error rate with 20–100ms base delays) — a notably more elaborate "humanized typing" model than a fixed per-character delay.
+
+## Key findings
+
+- Randomized delay (a range, not a fixed value) plus punctuation/space-triggered extra pauses reads as meaningfully more human than constant-interval typing.
+- Injected-then-corrected typos (not just timing variance) are the next level of realism beyond timing alone.
+
+## Pros / strengths
+
+- The most sophisticated "realistic typing" model found in this research round — a genuinely useful reference if the proposal's animated-typing command is meant to look convincingly human, not just non-instant.
+
+## Cons / limitations / caveats
+
+- Tabby's own documentation explicitly frames this feature as a way to get past paste-detection in coding interviews and proctored assessments. **That use case is out of scope and not endorsed by this dossier or by tai's design** — it is logged here purely as a reference for the underlying delay/typo-injection *mechanism*, which has entirely legitimate uses (demos, tutorials, accessibility, testing realistic input timing) independent of defeating any detection system.
+
+## Relevance to tai
+
+The mechanism (randomized delay range + punctuation pauses + optional typo-inject-and-correct) is a good advanced option for the proposal's typing-animation command, explicitly for legitimate demo/tutorial/test purposes — tai's own use is for terminal automation and demos, not deception.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,48 @@
+# Server — tao-of-tmux
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Server — tao-of-tmux v1.0.2 documentation |
+| Source URL | https://tao-of-tmux.readthedocs.io/en/latest/manuscript/04-server.html |
+| Source publisher / author | tao-of-tmux project (secondary/community docs, not the tmux project itself) |
+| Source type | vendor docs |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A community-written explainer of tmux's server internals: persistent state kept in global red-black trees for sessions/windows/panes, a single-threaded event loop (`server_loop()`) driven by a command queue (`cmdq_next()`), and one pseudoterminal opened per pane — none of which is ever a controlling terminal for the server itself.
+
+## Key findings
+
+- Sessions/windows/panes are tracked in red-black trees inside the server process, not per-client.
+- The server is single-threaded with a command queue, meaning tmux's own concurrency model is simple to reason about when scripting against it.
+- Pane PTYs are opened by the server and are never its own controlling terminal — relevant if a tai layer needs to understand why signals like SIGHUP behave the way they do inside tmux panes.
+
+## Pros / strengths
+
+- Gives a mental model (event loop + command queue + red-black trees) that's useful for predicting tmux's behavior under heavy scripted automation (many rapid `send-keys`/`capture-pane` calls).
+
+## Cons / limitations / caveats
+
+- Secondary, community-authored source, not tmux's own source code or official docs — the search synthesis itself flagged this as needing verification against `server.c`/`client.c`/`proc.c` for precision. Treat specifics (libevent usage, exact tree names) as plausible, not confirmed.
+
+## Relevance to tai
+
+Useful background for anyone building a tai control layer that issues many rapid control-mode/send-keys commands — explains why tmux can serialize them safely (single command queue) but also why a flood of commands could back up behind one slow one.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# bash: test for an interactive shell (Tek-Tips forum)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | bash: test for an interactive shell |
+| Source URL | https://www.tek-tips.com/threads/bash-test-for-an-interactive-shell.1400118/ |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the interactive-shell-detection query; another forum thread on the same `$-`/`$PS1` question already covered in depth by the nixCraft and Bash Cookbook dossiers, not individually read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Terminal Multiplexing: tmux, Termdock, Zellij (termdock.com mirrors)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Terminal multiplexing: tmux, termdock, zellij |
+| Source URL | https://termdock.com/en/blog/terminal-multiplexing-tmux-termdock-zellij |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the multiplexer-comparison query (a near-identical `www.termdock.com` URL variant of the same article also surfaced, logged as the same source here). A vendor-affiliated comparison promoting the company's own product (Termdock) alongside tmux and Zellij — flagged explicitly as promotional per the search synthesis, and not independently read for that reason.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,46 @@
+# Tiling Terminal Multiplexers for the Console Connoisseur (The Register)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Tiling terminal multiplexers for the console connoisseur |
+| Source URL | https://www.theregister.com/2025/06/24/tiling_multiplexers_survey/ |
+| Source publisher / author | The Register |
+| Source type | blog post |
+| Source date (published) | 2025-06-24 |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A broader survey of terminal multiplexers (tmux, screen, Zellij, and others) from a mainstream tech publication, giving an independent, non-vendor-affiliated vantage point on the current state of the field.
+
+## Key findings
+
+- Confirms tmux, screen, and Zellij as the three names that keep recurring across independent surveys of this space in 2025-2026 — there isn't a fourth major contender being overlooked by this subject's research.
+
+## Pros / strengths
+
+- A non-promotional, editorially independent tech-press source, which is a useful counterweight to the more vendor- or project-affiliated blog posts elsewhere in this subject.
+
+## Cons / limitations / caveats
+
+- A survey/overview piece — light on deep technical detail compared to the man pages and project wikis already dossiered in this subject; useful for breadth, not depth.
+
+## Relevance to tai
+
+Corroborates that the choice space for a substrate is essentially tmux vs. screen vs. Zellij, and that tmux remains a live, actively-covered, mainstream-recognized choice in 2025-2026 — not a legacy tool being proposed out of inertia.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# tmux(1) Man Page Mirrors (OpenBSD, die.net, commandlinux.com)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux(1) - OpenBSD manual pages |
+| Source URL | https://man.openbsd.org/tmux |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the tmux-architecture query as mirrors of the same man page already dossiered via man7.org (this card also stands in for https://linux.die.net/man/1/tmux and https://commandlinux.com/man-page/man1/tmux/, all the same underlying document).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# How to use tmux control mode? (tmuxai.dev)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | How to use tmux control mode? |
+| Source URL | https://tmuxai.dev/tmux-control-mode/ |
+| Source publisher / author | tmuxai.dev |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Explains tmux's control mode (`-C`/`-CC`): a text-only protocol where a client writes newline-terminated tmux commands to stdin, and each command's output is framed between a `%begin` line (with timestamp and command number) and a closing `%end` (success) or `%error` (failure). Asynchronous events arrive as `%`-prefixed notifications that never appear inside an output block.
+
+## Key findings
+
+- Deterministic framing (`%begin`...`%end`/`%error`) means a program can reliably know where one command's output stops, which plain `send-keys`+`capture-pane` polling cannot guarantee on its own.
+- Notifications are guaranteed not to interleave inside a command's output block — a real concurrency guarantee useful for building a parser.
+- `-CC` additionally disables echo, which matters for programmatic clients that don't want their own commands echoed back.
+
+## Pros / strengths
+
+- Gives the exact framing contract (`%begin`/`%end`/`%error`) needed to write a correct parser for a control-mode client, which is the structured alternative to screen-scraping `capture-pane` output.
+
+## Cons / limitations / caveats
+
+- A blog post, not tmux's own specification — cross-check framing details against the tmux source or man page before depending on them in production code.
+
+## Relevance to tai
+
+This is the mechanism for the "events" requirement in the proposal — control mode's notification stream is how a tai layer would receive pane-output/window-change events asynchronously rather than polling `capture-pane` in a loop.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,48 @@
+# Tmux FAQ (tmuxai.dev)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Tmux FAQ - Frequently Asked Questions - TmuxAI |
+| Source URL | https://tmuxai.dev/tmux-faq/ |
+| Source publisher / author | tmuxai.dev |
+| Source type | blog post |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+A FAQ covering two distinct tmux capabilities relevant to the proposal: `capture-pane -pS - -E -` for reading the *entire* scrollback in one shot (not just the visible screen), and `pipe-pane -o 'cat >> file'` for continuously streaming a pane's live output into a file or command, stopped by re-running `pipe-pane` with no arguments.
+
+## Key findings
+
+- `capture-pane -pS - -E -` is the snapshot-read primitive: the full scrollback, start to end, in one call.
+- `pipe-pane` is the streaming primitive: everything the pane produces from now on gets piped to a target (a file, or another command such as `grep`) continuously, until `pipe-pane` is invoked again with no target to stop it.
+- These are two genuinely different operations (snapshot vs. stream) that a tai layer needs both of, not just one.
+
+## Pros / strengths
+
+- Gives both halves of the "remember the whole process log" requirement directly: `pipe-pane` for continuous append-only logging as it happens, `capture-pane -S -` for an on-demand full-history snapshot.
+
+## Cons / limitations / caveats
+
+- A FAQ-style page with short answers, no discussion of `pipe-pane`'s behavior across pane resize, tmux server restart, or very high-throughput output (buffering/backpressure).
+
+## Relevance to tai
+
+Directly solves the "remember the whole process log" requirement: run `pipe-pane -o 'cat >> ~/.tai/termlogs/<session>.log'` once per pane at creation time, and the entire session's raw output streams continuously into a file tai can feed through its own existing chunked FTS5 search (see `export_terminal_log` in `tai.py`) without needing a one-shot export step at all.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# zellij vs tmux (ToolRadar)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | zellij vs tmux |
+| Source URL | https://toolradar.com/compare/zellij-vs-tmux |
+| Source type | other (comparison aggregator site) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the multiplexer-comparison query; a generic tool-comparison aggregator page, not independently read since the dasroot.net dossier already covers this comparison with attributed detail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Unix & Linux SE — Don't Nest tmux in a Remote SSH Shell (mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | dont nest tmux in a remote ssh shell |
+| Source URL | https://kompas.wasmer.app/https_unix_stackexchange_com/questions/420733/dont-nest-tmux-in-a-remote-ssh-shell |
+| Source publisher / author | Unix & Linux Stack Exchange (mirrored) |
+| Source type | forum thread |
+| 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 | Medium |
+| Status | Active |
+
+## Summary
+
+Describes the specific real-world failure mode of SSH + auto-attach: `$TMUX` is a local environment variable and is never forwarded across an SSH connection, so a naive "attach if `$TMUX` unset" guard, applied to .bashrc on both the local and remote machine (e.g. a shared dotfiles setup), still ends up nesting a remote tmux session inside the local one — because the remote shell's `$TMUX` genuinely is unset, even while the user is already inside a local tmux pane that SSH'd out.
+
+## Key findings
+
+- `$TMUX` is a *local* process-tree fact, not a *session* fact — it does not and cannot know about multiplexing happening on a different machine up the SSH chain.
+- The fix requires detecting the SSH hop itself (e.g. `$SSH_CONNECTION`) and treating "I am the target of an incoming SSH connection" differently from "I am a plain local shell," rather than relying on `$TMUX` to carry information it structurally cannot carry.
+
+## Pros / strengths
+
+- Precisely names a failure mode that would otherwise only be discovered by a real user hitting "sessions should be nested with care" warnings in production.
+
+## Cons / limitations / caveats
+
+- Describes the problem and its cause clearly; does not by itself prescribe one canonical fix (several exist, with tradeoffs, per the Codegenes and Coderwall dossiers in this subject).
+
+## Relevance to tai
+
+Critical for the proposal's auto-attach design: the guard logic must account for multi-hop SSH explicitly (checking `$SSH_CONNECTION`/`$SSH_TTY`, not just `$TMUX`), or a user SSHing from inside one tai-managed session into another host will get nested sessions despite the basic guard being "correct" on each host individually.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# tmux vs screen vs zellij (velog.io)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tmux vs screen vs zellij |
+| Source URL | https://velog.io/@vanillacake369/tmux-vs-screen-vs-zellij |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the multiplexer-comparison query; a three-way comparison including screen, which the other dossiered comparison sources cover less thoroughly, but not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# gpt-type-effect (classic Yarn package)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | shell-multiplexer-auto-attach |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | gpt type effect |
+| Source URL | https://classic.yarnpkg.com/en/package/gpt-type-effect |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the typing-animation query; a JavaScript package simulating GPT-style streamed typing output, adjacent but not identical to terminal keystroke simulation, not independently read.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |