@ictechgy/lterm 0.1.3 → 1.0.0

package/README.ko.md

@@ -14,6 +14,7 @@
 `lterm`은 tmux 전체를 대체하려는 도구가 아닙니다. 오래 실행되는 PTY 세션을 유지하고, 클라이언트가 자유롭게 detach/reattach할 수 있게 하며, 터미널 escape sequence는 그대로 통과시키고, terminal-first agent 도구가 자주 사용하는 tmux 명령 일부를 호환 shim으로 제공합니다.
 
 > **보안 모델:** `lterm`은 같은 OS 사용자 안에서 쓰는 편의용 데몬이며 샌드박스가 아닙니다. 다른 사용자의 Unix socket 접근은 거부하고 런타임 디렉터리는 소유자 전용 권한으로 만들지만, 같은 OS 사용자 권한으로 실행되는 프로세스는 세션을 제어할 수 있다고 보아야 합니다.
+> 전체 trust boundary와 audit policy는 [SECURITY.md](SECURITY.md)를 참고하세요.
 
 ## 왜 tmux 대신 lterm인가요?
 
@@ -32,8 +33,8 @@ agent가 보통 필요로 하는 더 작은 표면에 집중합니다.
 - **cmux-friendly 설계** — notification과 tmux shim call이 generic desktop
   multiplexer보다 cmux/agent pane orchestration에 맞춰져 있습니다.
 - **내장 관측성** — `doctor` / `status`, bounded `logs --start/--end`,
-  `processes --orphans`로 daemon, scrollback, subprocess 상태를 사람이나 agent가
-  쉽게 확인할 수 있습니다.
+  `wait` / `watch`, `processes --orphans`로 daemon, scrollback, 완료 조건,
+  subprocess 상태를 사람이나 agent가 쉽게 확인할 수 있습니다.
 
 ## 왜 만들었나
 
@@ -69,7 +70,7 @@ Homebrew와 npm 모두 `PATH`에 `lterm` 명령을 설치합니다. `lterm --ver
 GitHub에서 Cargo로 설치 (Releases 페이지의 최신 태그를 사용하세요):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v0.1.3
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.0
 ```
 
 저장소를 클론한 뒤 직접 빌드하려면 Rust 1.85 이상이 필요합니다.
@@ -127,6 +128,8 @@ lterm -a api
 | 세션 이름 변경 | `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` |
@@ -173,10 +176,41 @@ escape 처리가 여기에 포함됩니다. 직접 `ssh`하듯 신뢰할 수 있
 
 `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 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가 다시 그려집니다.
 
 `lterm resume` / `lterm attach` 도중 panic이나 abort가 발생해도 process-wide hook이 최소 복구 sequence(scroll region 리셋, 커서 보이기, alt-screen 종료, SGR 리셋)를 emit해 사용자 터미널이 raw mode나 hidden cursor 상태로 남지 않습니다.
@@ -195,10 +229,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`.
 
 **세션 종료:**
 
@@ -330,6 +366,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

@@ -14,6 +14,7 @@
 `lterm` is intentionally smaller than tmux. It keeps long-running PTY sessions alive, lets clients detach and reattach at will, forwards terminal escape sequences unchanged, and translates the subset of tmux commands commonly used by terminal-first agent tooling.
 
 > **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.
+> See [SECURITY.md](SECURITY.md) for the full trust-boundary and audit policy details.
 
 ## Why lterm instead of plain tmux?
 
@@ -32,8 +33,8 @@ need:
 - **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`,
-  and `processes --orphans` make daemon, scrollback, and subprocess state easy
-  for humans or agents to inspect.
+  `wait` / `watch`, and `processes --orphans` make daemon, scrollback,
+  completion, and subprocess state easy for humans or agents to inspect.
 
 ## Why this exists
 
@@ -67,10 +68,14 @@ 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.
 
+For the 1.0 command/output stability boundary, see the
+[public contract](docs/public-contract.md) and its machine-readable
+[contract manifest](docs/contract-manifest.json).
+
 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.3
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.0
 ```
 
 From this checkout, use Rust 1.85 or newer:
@@ -128,6 +133,8 @@ lterm -a api
 | 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` |
@@ -173,10 +180,41 @@ This table is the product CLI surface for humans and agents. `lterm tmux-compat
 
 `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.
 
+`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.
 
 If `lterm resume` / `lterm attach` panics or aborts mid-session, a process-wide hook emits a minimal recovery sequence (scroll region reset, cursor visible, alt-screen exit, SGR reset) so the user's terminal isn't left in raw mode or with hidden cursor.
@@ -195,10 +233,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:**
 
@@ -326,6 +366,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.3",
+  "version": "1.0.0",
   "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.3",
-    "lterm-darwin-x64": "0.1.3",
-    "lterm-linux-arm64": "0.1.3",
-    "lterm-linux-x64": "0.1.3"
+    "lterm-darwin-arm64": "1.0.0",
+    "lterm-darwin-x64": "1.0.0",
+    "lterm-linux-arm64": "1.0.0",
+    "lterm-linux-x64": "1.0.0"
   },
   "engines": {
     "node": ">=16"