@ictechgy/lterm 0.1.2 → 0.1.4

package/README.ko.md

@@ -15,6 +15,26 @@
 
 > **보안 모델:** `lterm`은 같은 OS 사용자 안에서 쓰는 편의용 데몬이며 샌드박스가 아닙니다. 다른 사용자의 Unix socket 접근은 거부하고 런타임 디렉터리는 소유자 전용 권한으로 만들지만, 같은 OS 사용자 권한으로 실행되는 프로세스는 세션을 제어할 수 있다고 보아야 합니다.
 
+## 왜 tmux 대신 lterm인가요?
+
+풍부한 pane/window/layout 관리를 원하면 tmux가 맞습니다. `lterm`은 AI
+agent가 보통 필요로 하는 더 작은 표면에 집중합니다.
+
+- **Agent-first persistence** — named PTY session이 detached client와 무관하게
+  계속 실행되므로, 모든 workflow가 full tmux server를 직접 관리할 필요가
+  적습니다.
+- **Agent가 기대하는 tmux 호환성** — `lterm tmux-compat`는 Claude Code, Codex
+  CLI, Gemini CLI, OMX/OMC 같은 terminal-first tooling이 쓰는 tmux command
+  subset을 구현합니다.
+- **Raw attach, safe reports** — attach된 PTY stream은 TUI/interactive shell을
+  위해 raw로 유지하고, `logs`, `capture`, `list`, `doctor` 같은 report surface는
+  출력 전에 terminal control sequence를 sanitize합니다.
+- **cmux-friendly 설계** — notification과 tmux shim call이 generic desktop
+  multiplexer보다 cmux/agent pane orchestration에 맞춰져 있습니다.
+- **내장 관측성** — `doctor` / `status`, bounded `logs --start/--end`,
+  `wait` / `watch`, `processes --orphans`로 daemon, scrollback, 완료 조건,
+  subprocess 상태를 사람이나 agent가 쉽게 확인할 수 있습니다.
+
 ## 왜 만들었나
 
 다음 세 가지 요구를 충족하는 것이 목표입니다.
@@ -41,10 +61,15 @@ npm install -g @ictechgy/lterm
 
 Homebrew와 npm 모두 `PATH`에 `lterm` 명령을 설치합니다. `lterm --version`으로 확인하세요.
 
+수동 설치도 귀찮다면 [`docs/agent-install.ko.md`](docs/agent-install.ko.md)의
+프롬프트를 Claude Code, Codex CLI, Gemini CLI 같은 terminal coding agent에
+붙여 넣으세요. Agent가 platform을 감지하고, `lterm`을 설치하고, smoke test로
+검증하며, shell startup file을 바꿔야 할 때는 먼저 diff를 보여주도록 안내합니다.
+
 GitHub에서 Cargo로 설치 (Releases 페이지의 최신 태그를 사용하세요):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v0.1.2
+cargo install --git https://github.com/ictechgy/light_terminal --tag v0.1.4
 ```
 
 저장소를 클론한 뒤 직접 빌드하려면 Rust 1.85 이상이 필요합니다.
@@ -100,7 +125,10 @@ lterm -a api
 | 세션 목록 보기 | `lterm sessions` | `list`, `ls` |
 | 프로세스 트리 확인 | `lterm processes api --json --orphans` | `ps` |
 | 세션 이름 변경 | `lterm rename api api-renamed` | 없음 |
+| 세션 status theme 설정 | `lterm status-theme api green` | `theme` |
 | 정제된 scrollback 읽기 | `lterm logs api --start=-80 --end=-1` | `capture` |
+| 세션 출력 또는 종료 대기 | `lterm wait api --contains READY --timeout 30s --json` | 없음 |
+| 세션을 감시하고 완료 시 알림 | `lterm watch api --exit --notify` | 없음 |
 | PTY에 입력 쓰기 | `lterm input api 'echo hello' --enter` | `send` |
 | 세션 종료 | `lterm close api` | `kill` |
 | 데몬과 shim 상태 진단 | `lterm doctor --json` | `status` |
@@ -137,15 +165,50 @@ escape 처리가 여기에 포함됩니다. 직접 `ssh`하듯 신뢰할 수 있
 
 이 표는 사람과 agent가 직접 쓰는 제품 CLI 표면입니다. `lterm tmux-compat ...`는 이미 tmux 명령을 사용하는 스크립트를 위한 별도 shim namespace이며, 모든 제품 명령에 tmux 호환 이름이 있는 것은 아닙니다. 런타임에 지원되는 shim subset은 `lterm tmux-compat list-commands`로 확인하세요.
 
-`lterm sessions`는 기본적으로 하위 pane을 숨기고, 기존 첫 5개 tab-separated 열(`name`, `pane`, `alive`, `cwd`, `command`)을 유지한 뒤 attach 상태(`attached` / `detached`)와 parent pane(`-` 또는 pane id)을 뒤에 붙입니다. 호환 이름인 `lterm list`와 `lterm ls`도 같은 출력 형식을 유지합니다. attach된 클라이언트는 아래쪽 한 줄에 파란 상태 바를 표시하고, PTY는 그 줄을 제외한 영역으로 resize됩니다. 예전처럼 전체 터미널을 raw 모드로 재개하려면 `lterm resume --no-status api`(호환 이름: `lterm attach --no-status api`)를 쓰거나, 상태줄 처리가 충돌하는 클라이언트에서는 `LTERM_NO_STATUS=1` / `LTERM_STATUS=0`을 설정하세요.
+`lterm sessions`는 기본적으로 하위 pane을 숨기고, 기존 첫 5개 tab-separated 열(`name`, `pane`, `alive`, `cwd`, `command`)을 유지한 뒤 attach 상태(`attached` / `detached`)와 parent pane(`-` 또는 pane id)을 뒤에 붙입니다. 호환 이름인 `lterm list`와 `lterm ls`도 같은 출력 형식을 유지합니다. attach된 클라이언트는 아래쪽 한 줄에 status bar를 표시하고, PTY는 그 줄을 제외한 영역으로 resize됩니다. 예전처럼 전체 터미널을 raw 모드로 재개하려면 `lterm resume --no-status api`(호환 이름: `lterm attach --no-status api`)를 쓰거나, 상태줄 처리가 충돌하는 클라이언트에서는 `LTERM_NO_STATUS=1` / `LTERM_STATUS=0`을 설정하세요.
 
 `lterm rename <target> <new-name>`은 실행 중인 세션의 프로세스를 재시작하지 않고 이름만 바꿉니다. 현재 이름과 동일한 이름으로 바꾸면 no-op success이고, 다른 세션이 이미 쓰는 이름으로 바꾸면 conflict error로 실패합니다. `<target>`은 세션 이름, session id, pane id(`%0`), 또는 bare pane 번호(`0`)를 받으며, `<new-name>`은 `--name`과 같은 이름 규칙을 따릅니다.
 
+`lterm status-theme <target> <theme>`(alias: `lterm theme`)은 PTY를 재시작하지 않고 세션별 status bar theme을 저장합니다. pane id를 지정하면 해당 pane이 속한 세션에 적용됩니다. `default`, `clear`, `none`을 쓰면 세션 override를 지우고 attach하는 client의 기본값으로 돌아갑니다. 이미 attach된 client는 detach 후 다시 attach할 때 새 색을 반영합니다. 새 세션은 `lterm start --status-theme green -n api -- npm run dev`(또는 alias `--status-color`)처럼 생성 시점에 같은 metadata를 저장할 수 있습니다.
+
 `lterm doctor`(호환 이름: `lterm status`)는 client/daemon version, protocol 호환성, runtime/data/socket/shim path, shim directory가 `PATH`에 있는지 등을 보고합니다. 이 명령은 daemon을 시작하지 않습니다. 현재 socket에서 호환 daemon이 응답하지 않으면 `daemon_reachable=no` / `false`로 표시됩니다. 일반 client 동작 중 접근 가능한 daemon이 다른 lterm 또는 protocol version을 보고하면 stderr에 경고를 출력하며, 보통 binary upgrade 뒤 예전 daemon이 살아 있는 상황을 뜻합니다.
 
 `lterm logs <target>`은 `--start` / `-S`와 `--end` / `-E` line offset을 받습니다. 0 이상의 값은 absolute scrollback line index이고, 음수 값은 현재 scrollback line count에서 뒤로 셉니다. `--end`는 inclusive라 `lterm logs api -S0 -E0`은 첫 번째 줄만 capture합니다. Capture 출력은 계속 정제된 text이며, attach된 PTY stream은 raw 그대로 유지됩니다.
 
-`LTERM_STATUS_STYLE=full` 또는 `LTERM_STATUS_STYLE=minimal` 로 시각 스타일을 선택할 수 있습니다. `full`(로컬 터미널 기본값)은 검정 글자 + bright-blue 배경, `minimal`은 SGR 색을 모두 생략한 plain text로 동작합니다. SSH 세션(`SSH_CONNECTION` / `SSH_CLIENT` / `SSH_TTY` 감지)에서는 자동으로 `minimal`이 적용되어 Termius 같은 모바일 SSH 클라이언트의 색 충돌을 줄입니다.
+`lterm wait <target> --exit|--contains <text>`는 세션이 종료되거나 정제된 scrollback에 marker가 나타날 때까지 block합니다. 자동화용 health check에는 `--timeout 250ms|2s|5m|1h`, `--tail N`, `--json`을 함께 쓰세요. Timeout 시 `wait` / `watch`는 exit code `124`를 반환하고 JSON에는 `timed_out: true`가 들어갑니다. `lterm watch`는 같은 조건을 쓰며, `--notify`를 더하면 attach된 PTY bytes는 건드리지 않고 cmux-friendly 완료 알림을 보냅니다. `--json`을 함께 쓸 때는 notification fallback이 필요해도 stdout을 machine-readable JSON으로 유지합니다.
+
+`LTERM_STATUS_STYLE=full` 또는 `LTERM_STATUS_STYLE=minimal` 로 시각 스타일을 선택할 수 있습니다. `full`(로컬 터미널 기본값)은 색이 있는 bar를 그리고, `minimal`은 SGR 색을 모두 생략한 plain text로 동작합니다. SSH 세션(`SSH_CONNECTION` / `SSH_CLIENT` / `SSH_TTY` 감지)에서는 자동으로 `minimal`이 적용되어 Termius 같은 모바일 SSH 클라이언트의 색 충돌을 줄이지만, 세션 또는 환경 theme을 명시하면 색이 유지됩니다.
+
+`LTERM_STATUS_THEME=blue|green|magenta|cyan|amber|red|gray|plain` 으로 attach client의 기본 status bar 색을 바꿀 수 있습니다. 세션별 override가 환경값보다 우선합니다: `lterm start --status-theme amber -n api -- npm run dev`, `lterm run --status-color cyan -- cargo test`, `lterm status-theme api plain`. 이 변수를 shell startup 파일에서 export하면 SSH attach도 colored status bar로 opt-in됩니다. 모바일 SSH client에서 plain text가 필요하면 unset하거나 `LTERM_STATUS_STYLE=minimal`을 설정하세요. Theme 이름은 고정 allowlist에서만 파싱되며, lterm은 사용자 입력 escape sequence를 status row에 임의 삽입하지 않습니다.
+
+### Status bar 커스터마이징
+
+Status bar theme은 v0.1.3에서 추가되었습니다. 이 기능은 metadata만 바꿉니다. Theme을 바꿔도 PTY가 재시작되지 않고, attach된 PTY byte stream도 바꾸거나 정제하지 않으며, 사용자 입력으로 임의 terminal escape sequence를 status row에 넣지 않습니다.
+
+원하는 범위에 맞춰 가장 좁은 설정을 사용하세요:
+
+| 범위 | 예시 | 언제 쓰나요 |
+| --- | --- | --- |
+| 새 세션 1개 | `lterm start --status-theme green -n api -- npm run dev` | service나 agent 세션을 이후 attach에서도 쉽게 구분하고 싶을 때. |
+| 기존 세션 | `lterm status-theme api amber` | 실행 중인 process를 재시작하지 않고 색만 바꿀 때. |
+| Agent launcher 세션 | `lterm codex --status --status-color cyan -- exec "summarize"` | long-only launcher 옵션을 유지하면서 agent 세션에 지속 색상을 줄 때. |
+| Attach client 기본값 | `export LTERM_STATUS_THEME=magenta` | 세션 override가 없는 session의 기본 색을 바꾸고 싶을 때. |
+| Plain/minimal client | `export LTERM_STATUS_STYLE=minimal` | 모바일 SSH client나 색상 매핑이 불안한 terminal에서 text-only status를 선호할 때. |
+
+허용되는 theme은 고정 목록입니다:
+
+| Theme | 추천 용도 |
+| --- | --- |
+| `blue` | 로컬 status bar 기본값. |
+| `green` | 오래 실행되는 service 또는 정상/background 작업. |
+| `magenta` | 빠르게 구분하고 싶은 agent 또는 review 세션. |
+| `cyan` | build/test/dev-tool 세션. |
+| `amber` | 주의가 필요한 watch/diagnostic 세션. |
+| `red` | 위험하거나 destructive이거나 production에 가까운 세션. |
+| `gray` | 낮은 우선순위의 background 세션. |
+| `plain` | 색상 bar 없이 status row만 유지하고 싶을 때. |
+
+세션 override는 `lterm status-theme api default`(또는 `clear` / `none`)로 지웁니다. 이미 attach된 client는 detach 후 reattach할 때 새 색이 반영되므로, 사람이 붙어 있는 동안 scripted 변경을 적용해도 안전합니다.
 
 attach된 PTY가 alternate screen buffer로 진입하면(예: `vim`, `less`, `htop`이 `\x1b[?1049h` 사용) lterm은 status bar를 일시 중단해 alt-screen 앱의 UI와 충돌을 피합니다. 앱이 alt-screen을 종료하는 즉시 status bar가 다시 그려집니다.
 
@@ -165,10 +228,12 @@ lterm sessions --children
 lterm sessions --all
 lterm processes api --orphans
 lterm logs api --start=-80 --end=-1
+lterm wait api --contains READY --timeout 30s --json
+lterm watch api --exit --notify
 lterm input api 'echo hello' --enter
 ```
 
-위의 일반 alias는 tmux 용어를 몰라도 agent terminal을 일상적으로 다루기 쉽게 하기 위한 표면입니다. `sessions`는 영속 작업을 나열하고, `processes`는 child process tree를 확인하고, `logs`는 정제된 scrollback을 읽고, `input`은 대상 PTY에 텍스트를 씁니다. 호환 이름은 visible alias로 유지되어 스크립트와 기존 사용 습관에서도 계속 사용할 수 있습니다: `list` / `ls`, `ps`, `capture`, `send`.
+위의 일반 alias는 tmux 용어를 몰라도 agent terminal을 일상적으로 다루기 쉽게 하기 위한 표면입니다. `sessions`는 영속 작업을 나열하고, `processes`는 child process tree를 확인하고, `logs`는 정제된 scrollback을 읽고, `wait` / `watch`는 marker 또는 종료 조건을 script와 agent가 관측할 수 있게 하며, `input`은 대상 PTY에 텍스트를 씁니다. 호환 이름은 visible alias로 유지되어 스크립트와 기존 사용 습관에서도 계속 사용할 수 있습니다: `list` / `ls`, `ps`, `capture`, `send`.
 
 **세션 종료:**
 
@@ -221,7 +286,7 @@ lterm gemini --status -- -p "lterm status를 유지해줘"
 
 Claude/Codex/Gemini profile은 각 도구의 자체 TUI/status/alternate-screen 렌더링과 충돌하지 않도록 기본적으로 lterm status bar를 끈 raw full-terminal attach를 사용합니다. `--status`로 lterm status bar를 강제로 켜거나, 기본값이 켜진 profile에서는 `--no-status`로 끌 수 있습니다. agent에 넘길 인자가 lterm launch option처럼 보일 수 있으면 앞에 `--`를 두세요. 직접 generic tmux-compatible primitive를 쓰거나 아직 profile이 없는 미래 agent를 실행하려면 `lterm run -- <command>`를 사용하세요. `run`은 shim을 기본으로 켜며 `--no-tmux`로 끌 수 있습니다.
 
-launcher 제어 옵션은 agent의 흔한 short flag(`-c` 등)를 빼앗지 않도록 long-only(`--name`, `--cwd`, `--detach`, `--status`, `--no-status`)입니다. 이 옵션들은 `claude`, `codex`, `gemini`, `omx`, `omc`, `agent <profile>`에 동일하게 적용됩니다.
+launcher 제어 옵션은 agent의 흔한 short flag(`-c` 등)를 빼앗지 않도록 long-only(`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`)입니다. 이 옵션들은 `claude`, `codex`, `gemini`, `omx`, `omc`, `agent <profile>`에 동일하게 적용됩니다. 해당 agent 세션이 이후 attach에서도 특정 lterm status 색을 유지하게 하려면 `--status-theme` / `--status-color`를 사용하세요.
 `--detach`는 각 field의 control character와 Unicode line/paragraph separator를 공백으로 바꾼 `name<TAB>pane<TAB>command`를 출력하며, 나중에 `lterm resume <name>` 또는 호환 이름 `lterm attach <name>`으로 다시 붙으면 됩니다. detach record에는 `--cwd`가 포함되지 않으므로 나중에 필요하면 session을 조회하세요.
 명시한 `--name`은 lterm의 일반 session-name 문법을 따르고 사용 중이지 않아야 합니다. 충돌 시 자동 suffix를 붙이지 않고 conflict error로 실패합니다.
 이름에는 ASCII 문자/숫자와 `.`, `_`, `-`만 사용할 수 있고, `-` 또는 `%`로 시작할 수 없으며, 숫자만으로 이뤄질 수 없고, UUID처럼 보이면 안 되고, 128바이트를 넘을 수 없습니다.
@@ -300,6 +365,8 @@ lterm notify --title 'Task complete' --body 'All checks passed'
 
 `lterm notify`는 먼저 `cmux notify`를 시도합니다. 사용할 수 없으면 OSC 777을 출력해 cmux나 호환 터미널이 알림을 표시할 수 있도록 합니다. fallback OSC에 들어가는 알림 필드는 터미널 제어 문자를 제거한 뒤 출력하며, subtitle/body 구분용 newline 같은 문자는 서로 붙지 않도록 공백으로 정규화합니다.
 
+Agent workflow에서 특정 세션 조건에 묶인 알림이 필요하면 `lterm watch <target> --exit --notify` 또는 `lterm watch <target> --contains DONE --notify`를 우선 사용하세요.
+
 ## 원격 접속
 
 원격 머신에 `lterm`이 설치되어 있다면:

package/README.md

@@ -15,6 +15,26 @@
 
 > **Security model:** `lterm` is a same-user convenience daemon, not a sandbox. It rejects cross-user Unix-socket peers and uses owner-only runtime directories, but any process running as your OS user should be considered capable of controlling your sessions.
 
+## Why lterm instead of plain tmux?
+
+Use tmux when you want a full terminal multiplexer with rich pane/window/layout
+management. Use `lterm` when you want the smaller surface that AI agents usually
+need:
+
+- **Agent-first persistence** — named PTY sessions keep running across detached
+  clients without requiring every workflow to manage a full tmux server.
+- **tmux-compatible where agents expect it** — `lterm tmux-compat` implements
+  the command subset used by Claude Code, Codex CLI, Gemini CLI, OMX/OMC, and
+  similar terminal-first tooling.
+- **Raw attach, safe reports** — attached PTY streams remain raw for TUIs and
+  interactive shells, while `logs`, `capture`, `list`, `doctor`, and other
+  report surfaces sanitize terminal control sequences before printing.
+- **cmux-friendly by design** — notifications and tmux shim calls are shaped for
+  cmux/agent pane orchestration instead of generic desktop multiplexing.
+- **Built-in observability** — `doctor` / `status`, bounded `logs --start/--end`,
+  `wait` / `watch`, and `processes --orphans` make daemon, scrollback,
+  completion, and subprocess state easy for humans or agents to inspect.
+
 ## Why this exists
 
 The project addresses three constraints:
@@ -41,10 +61,16 @@ npm install -g @ictechgy/lterm
 
 Homebrew and npm both install the `lterm` command on your `PATH`; verify with `lterm --version`.
 
+Too lazy to install it manually? Copy the prompt in
+[`docs/agent-install.md`](docs/agent-install.md) into Claude Code, Codex CLI,
+Gemini CLI, or another terminal coding agent. It asks the agent to detect your
+platform, install `lterm`, verify it with a smoke test, and avoid modifying
+shell startup files without showing you the change.
+
 With Cargo from GitHub (use the latest tag from the Releases page):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v0.1.2
+cargo install --git https://github.com/ictechgy/light_terminal --tag v0.1.4
 ```
 
 From this checkout, use Rust 1.85 or newer:
@@ -100,7 +126,10 @@ lterm -a api
 | List sessions | `lterm sessions` | `list`, `ls` |
 | Inspect process trees | `lterm processes api --json --orphans` | `ps` |
 | Rename a session | `lterm rename api api-renamed` | None |
+| Set a session status theme | `lterm status-theme api green` | `theme` |
 | Read sanitized scrollback | `lterm logs api --start=-80 --end=-1` | `capture` |
+| Wait for session output or exit | `lterm wait api --contains READY --timeout 30s --json` | None |
+| Watch a session and notify on completion | `lterm watch api --exit --notify` | None |
 | Write input to a PTY | `lterm input api 'echo hello' --enter` | `send` |
 | Stop a session | `lterm close api` | `kill` |
 | Diagnose daemon and shim state | `lterm doctor --json` | `status` |
@@ -136,15 +165,50 @@ Compatibility names are subcommands unless shown as a leading flag: `-a` is the
 
 This table is the product CLI surface for humans and agents. `lterm tmux-compat ...` is a separate shim namespace for scripts that already speak tmux; not every product command has a tmux-compatible spelling. Use `lterm tmux-compat list-commands` to inspect the supported shim subset at runtime.
 
-`lterm sessions` hides child panes by default, preserves the original first five tab-separated columns (`name`, `pane`, `alive`, `cwd`, `command`), then appends attach state (`attached` / `detached`) and parent pane (`-` or a pane id). The compatibility names `lterm list` and `lterm ls` keep the same output shape. Attached clients render a small blue status bar on the bottom row showing the current session and pane; the PTY is resized to the remaining rows. For the older raw full-terminal resume, use `lterm resume --no-status api` (or compatibility name `lterm attach --no-status api`), or set `LTERM_NO_STATUS=1` / `LTERM_STATUS=0` for clients whose status-line handling conflicts with lterm.
+`lterm sessions` hides child panes by default, preserves the original first five tab-separated columns (`name`, `pane`, `alive`, `cwd`, `command`), then appends attach state (`attached` / `detached`) and parent pane (`-` or a pane id). The compatibility names `lterm list` and `lterm ls` keep the same output shape. Attached clients render a small status bar on the bottom row showing the current session and pane; the PTY is resized to the remaining rows. For the older raw full-terminal resume, use `lterm resume --no-status api` (or compatibility name `lterm attach --no-status api`), or set `LTERM_NO_STATUS=1` / `LTERM_STATUS=0` for clients whose status-line handling conflicts with lterm.
 
 `lterm rename <target> <new-name>` renames a running session without restarting its process. Renaming a session to its current name is a no-op success, while renaming over a different in-use name fails with a conflict error. `<target>` accepts a session name, session id, pane id (`%0`), or bare pane number (`0`); `<new-name>` follows the same syntax rules as `--name`.
 
+`lterm status-theme <target> <theme>` (alias: `lterm theme`) stores a per-session status bar theme without restarting the PTY; pane ids resolve to their session. Use `default`, `clear`, or `none` to remove the session override and return to the attaching client's default. Already-attached clients keep their current status color until they detach and reattach. New sessions can set the same metadata at creation time with `lterm start --status-theme green -n api -- npm run dev` (or alias `--status-color`).
+
 `lterm doctor` (compatibility name: `lterm status`) reports client/daemon versions, protocol compatibility, runtime/data/socket/shim paths, and whether the shim directory is on `PATH`. It does not start the daemon; `daemon_reachable=no` / `false` means no compatible daemon answered on the current socket. Normal client operations warn on stderr when a reachable daemon reports a different lterm or protocol version, which usually means an old daemon survived a binary upgrade.
 
 `lterm logs <target>` accepts `--start` / `-S` and `--end` / `-E` line offsets. Non-negative values are absolute scrollback line indexes; negative values count back from the current scrollback line count. `--end` is inclusive, so `lterm logs api -S0 -E0` captures only the first line. Capture output remains sanitized text; attached PTY streams remain raw.
 
-Set `LTERM_STATUS_STYLE=full` or `LTERM_STATUS_STYLE=minimal` to choose the visual style. `full` (default for local terminals) shows black text on a bright-blue background; `minimal` drops all SGR colors in favor of plain text. SSH sessions (detected via `SSH_CONNECTION`, `SSH_CLIENT`, or `SSH_TTY`) default to `minimal` to avoid color-mapping issues on mobile SSH clients like Termius.
+`lterm wait <target> --exit|--contains <text>` blocks until a session exits or its sanitized scrollback contains a marker. Add `--timeout 250ms|2s|5m|1h`, `--tail N`, and `--json` for automation-friendly health checks. On timeout, `wait` / `watch` return exit code `124` and JSON reports `timed_out: true`. `lterm watch` uses the same conditions and can add `--notify` to emit a cmux-friendly completion notification without altering attached PTY bytes; with `--json`, stdout stays machine-readable even when notification fallback is needed.
+
+Set `LTERM_STATUS_STYLE=full` or `LTERM_STATUS_STYLE=minimal` to choose the visual style. `full` (default for local terminals) draws a colored bar; `minimal` drops all SGR colors in favor of plain text. SSH sessions (detected via `SSH_CONNECTION`, `SSH_CLIENT`, or `SSH_TTY`) default to `minimal` to avoid color-mapping issues on mobile SSH clients like Termius, unless a session or environment theme is explicitly set.
+
+Set `LTERM_STATUS_THEME=blue|green|magenta|cyan|amber|red|gray|plain` to change the default colored status bar for the attaching client. Per-session overrides win over the environment: `lterm start --status-theme amber -n api -- npm run dev`, `lterm run --status-color cyan -- cargo test`, or `lterm status-theme api plain`. If you export this variable from shell startup files, it also opts SSH attaches into colored status bars; leave it unset or set `LTERM_STATUS_STYLE=minimal` on mobile SSH clients that need plain text. Theme names are parsed from a fixed allowlist; lterm never injects arbitrary user-provided terminal escape sequences into the status row.
+
+### Status bar customization
+
+Status bar themes were added in v0.1.3. They are metadata-only: changing a theme never restarts the PTY, never changes the attached PTY byte stream, and never accepts arbitrary terminal escape sequences from user input.
+
+Use the narrowest scope that matches what you want:
+
+| Scope | Example | When to use it |
+| --- | --- | --- |
+| One new session | `lterm start --status-theme green -n api -- npm run dev` | Keep a service or agent session recognizable across future attaches. |
+| Existing session | `lterm status-theme api amber` | Recolor a running session without restarting its process. |
+| Agent launcher session | `lterm codex --status --status-color cyan -- exec "summarize"` | Give an agent-owned session a persistent color while preserving long-only launcher controls. |
+| Attaching client default | `export LTERM_STATUS_THEME=magenta` | Change the default for sessions that do not have their own override. |
+| Plain/minimal clients | `export LTERM_STATUS_STYLE=minimal` | Prefer text-only status on mobile SSH clients or terminals with fragile color mapping. |
+
+Allowed themes are intentionally fixed:
+
+| Theme | Good fit |
+| --- | --- |
+| `blue` | Default local status bar. |
+| `green` | Long-running services or healthy/background tasks. |
+| `magenta` | Agent or review sessions you want to spot quickly. |
+| `cyan` | Build/test/dev-tool sessions. |
+| `amber` | Watch/diagnostic sessions that need attention. |
+| `red` | Risky, destructive, or production-adjacent sessions. |
+| `gray` | Low-priority background sessions. |
+| `plain` | No colored bar; useful when ANSI colors are distracting but the status row is still helpful. |
+
+Reset a session override with `lterm status-theme api default` (or `clear` / `none`). Already-attached clients keep their current rendered color until detach/reattach, so scripted changes are safe to apply while a human is attached.
 
 When the attached PTY enters the alternate screen buffer (e.g. `vim`, `less`, `htop` via `\x1b[?1049h`), lterm suspends its status bar to avoid conflicting with the application's UI. The status bar is redrawn immediately when the application exits alt-screen.
 
@@ -164,10 +228,12 @@ lterm sessions --children
 lterm sessions --all
 lterm processes api --orphans
 lterm logs api --start=-80 --end=-1
+lterm wait api --contains READY --timeout 30s --json
+lterm watch api --exit --notify
 lterm input api 'echo hello' --enter
 ```
 
-The generic aliases above are meant for day-to-day agent-terminal use: `sessions` lists persistent work, `processes` inspects child process trees, `logs` reads sanitized scrollback, and `input` writes text to the target PTY. The compatibility names are visible aliases that remain available for scripts and muscle memory: `list` / `ls`, `ps`, `capture`, and `send`.
+The generic aliases above are meant for day-to-day agent-terminal use: `sessions` lists persistent work, `processes` inspects child process trees, `logs` reads sanitized scrollback, `wait` / `watch` make marker-or-exit conditions observable for scripts and agents, and `input` writes text to the target PTY. The compatibility names are visible aliases that remain available for scripts and muscle memory: `list` / `ls`, `ps`, `capture`, and `send`.
 
 **Stop a session:**
 
@@ -220,7 +286,7 @@ lterm gemini --status -- -p "keep lterm status visible"
 
 Known Claude/Codex/Gemini profiles default to a raw full-terminal attach without the lterm status bar, so their own TUI/status/alternate-screen rendering stays in control. Use `--status` to force the lterm status bar on, or `--no-status` to force it off for profiles that default on. Put `--` before agent arguments that could be parsed as lterm launch options. Use `lterm run -- <command>` when you want the generic tmux-compatible primitive directly or need to launch an unprofiled future agent; `run` enables the shim by default and `--no-tmux` opts out.
 
-Launcher controls are long-only (`--name`, `--cwd`, `--detach`, `--status`, `--no-status`) so common agent short flags such as `-c` pass through naturally. They apply uniformly to `claude`, `codex`, `gemini`, `omx`, `omc`, and `agent <profile>`.
+Launcher controls are long-only (`--name`, `--cwd`, `--detach`, `--status`, `--no-status`, `--status-theme`) so common agent short flags such as `-c` pass through naturally. They apply uniformly to `claude`, `codex`, `gemini`, `omx`, `omc`, and `agent <profile>`. Use `--status-theme` / `--status-color` on agent launches when you want that session to keep a specific lterm status color across future attaches.
 `--detach` prints `name<TAB>pane<TAB>command` with control characters and Unicode line/paragraph separators in each field replaced by spaces; resume later with `lterm resume <name>` or compatibility name `lterm attach <name>`. The detach record does not echo `--cwd`; query the session if you need to inspect it later.
 Explicit `--name` values use lterm's normal session-name syntax and must be free; they do not auto-suffix on conflict, so an in-use name fails with a conflict error.
 Names may contain ASCII letters, digits, `.`, `_`, and `-`, must not start with `-` or `%`, must not consist only of digits, must not look like a UUID, and are limited to 128 bytes.
@@ -295,6 +361,8 @@ lterm notify --title 'Task complete' --body 'All checks passed'
 
 `lterm notify` first tries `cmux notify`. If that's unavailable, it emits OSC 777 so cmux or another compatible terminal can still surface the notification. Notification fields are stripped of terminal control characters before falling back to OSC; subtitle/body separators such as newlines are normalized to spaces rather than concatenated.
 
+For agent workflows, prefer `lterm watch <target> --exit --notify` or `lterm watch <target> --contains DONE --notify` when the notification should be tied to a specific session condition.
+
 ## Remote access
 
 If `lterm` is installed on a remote machine:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/lterm",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Lightweight tmux-compatible terminal session daemon with cmux-friendly notifications.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://github.com/ictechgy/light_terminal#readme",
@@ -30,10 +30,10 @@
     "LICENSE-MIT"
   ],
   "optionalDependencies": {
-    "lterm-darwin-arm64": "0.1.2",
-    "lterm-darwin-x64": "0.1.2",
-    "lterm-linux-arm64": "0.1.2",
-    "lterm-linux-x64": "0.1.2"
+    "lterm-darwin-arm64": "0.1.4",
+    "lterm-darwin-x64": "0.1.4",
+    "lterm-linux-arm64": "0.1.4",
+    "lterm-linux-x64": "0.1.4"
   },
   "engines": {
     "node": ">=16"