@ictechgy/lterm 1.0.0 → 1.0.2

package/README.ko.md

@@ -15,6 +15,7 @@
 
 > **보안 모델:** `lterm`은 같은 OS 사용자 안에서 쓰는 편의용 데몬이며 샌드박스가 아닙니다. 다른 사용자의 Unix socket 접근은 거부하고 런타임 디렉터리는 소유자 전용 권한으로 만들지만, 같은 OS 사용자 권한으로 실행되는 프로세스는 세션을 제어할 수 있다고 보아야 합니다.
 > 전체 trust boundary와 audit policy는 [SECURITY.md](SECURITY.md)를 참고하세요.
+> Non-goals(의도적으로 지원하지 않는 항목)는 [docs/non-goals.md](docs/non-goals.md)를 참고하세요.
 
 ## 왜 tmux 대신 lterm인가요?
 
@@ -70,7 +71,7 @@ Homebrew와 npm 모두 `PATH`에 `lterm` 명령을 설치합니다. `lterm --ver
 GitHub에서 Cargo로 설치 (Releases 페이지의 최신 태그를 사용하세요):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.0
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.2
 ```
 
 저장소를 클론한 뒤 직접 빌드하려면 Rust 1.85 이상이 필요합니다.
@@ -128,6 +129,7 @@ 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` |
+| 정제된 scrollback 위에 입력 컴포저 열기 | `lterm compose api` | `mobile` |
 | 세션 출력 또는 종료 대기 | `lterm wait api --contains READY --timeout 30s --json` | 없음 |
 | 세션을 감시하고 완료 시 알림 | `lterm watch api --exit --notify` | 없음 |
 | PTY에 입력 쓰기 | `lterm input api 'echo hello' --enter` | `send` |
@@ -229,12 +231,16 @@ lterm sessions --children
 lterm sessions --all
 lterm processes api --orphans
 lterm logs api --start=-80 --end=-1
+lterm compose api
 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을 읽고, `wait` / `watch`는 marker 또는 종료 조건을 script와 agent가 관측할 수 있게 하며, `input`은 대상 PTY에 텍스트를 씁니다. 호환 이름은 visible alias로 유지되어 스크립트와 기존 사용 습관에서도 계속 사용할 수 있습니다: `list` / `ls`, `ps`, `capture`, `send`.
+위의 일반 alias는 tmux 용어를 몰라도 agent terminal을 일상적으로 다루기 쉽게 하기 위한 표면입니다. `sessions`는 영속 작업을 나열하고, `processes`는 child process tree를 확인하고, `logs`는 정제된 scrollback을 읽고, `compose`는 정제된 scrollback과 하단 고정 prompt로 텍스트를 commit할 수 있게 하며, `wait` / `watch`는 marker 또는 종료 조건을 script와 agent가 관측할 수 있게 하고, `input`은 대상 PTY에 텍스트를 씁니다. `mobile`은 `compose`의 visible alias입니다. 호환 이름 `list` / `ls`, `ps`, `capture`, `send`는 스크립트와 기존 사용 습관에서도 계속 사용할 수 있습니다.
+
+자동화와 테스트에는 `lterm compose api --once --message 'hello'`를 사용하면 한 번의 정제된 capture/send 사이클을 실행합니다. `logs`와 같은 session-or-pane target 모델에서 마지막 `--tail` 정제 라인(기본값: 80)을 capture한 뒤, 기본으로 Enter(`\r`)를 붙여 `lterm input --enter`와 맞추며, `--no-enter`를 추가하면 message byte만 정확히 보냅니다. `compose` / `mobile`은 attach client가 아니며 attached-client 수나 PTY geometry를 바꾸지 않습니다.
+Interactive compose 화면은 `--refresh`(기본값: 500ms), 로컬 입력, 터미널 resize 이벤트마다 갱신됩니다. Enter를 누르면 현재 입력 buffer를 commit하고(빈 buffer도 commit됨), 위 one-shot 규칙처럼 기본으로 `\r`을 덧붙입니다. Ctrl-C, Ctrl-D, Esc는 PTY로 전달하지 않고 로컬 composer를 종료합니다.
 
 **세션 종료:**
 
@@ -398,7 +404,7 @@ lterm ssh devbox main -- -p 2222 -i ~/.ssh/id_ed25519
 
 **터미널 출력은 그대로 전달됩니다.** `lterm resume`(호환 이름: `lterm attach`)은 full-screen 터미널 프로그램과 cmux/OSC 알림이 정상 동작하도록 PTY byte를 그대로 통과시킵니다. 로컬 상태 바는 클라이언트 쪽 표시 요소일 뿐이며, 완전한 raw 모드 터미널이 필요하면 `--no-status`를 사용하세요. 신뢰할 수 없는 child 프로그램은 tmux/screen에서와 마찬가지로 attach된 터미널에 escape sequence를 출력할 수 있습니다. **`lterm`을 escape-sequence sanitizer나 sandbox로 사용하지 마세요.**
 
-**Capture 출력은 사람/AI가 읽기 쉽도록 정제됩니다.** `lterm logs`(호환 이름: `lterm capture`)와 `tmux capture-pane`은 captured scrollback을 출력할 때 일반적인 터미널 제어 시퀀스를 제거합니다.
+**Capture 출력은 사람/AI가 읽기 쉽도록 정제됩니다.** `lterm logs`(호환 이름: `lterm capture`), `lterm compose`(alias: `lterm mobile`), `tmux capture-pane`은 captured scrollback을 출력할 때 일반적인 터미널 제어 시퀀스를 제거합니다. `compose`는 attach가 아닌 view에서 기존 input/send 경로로 텍스트를 commit하며, raw attached PTY stream을 변환하지 않습니다.
 
 **프로세스 가시성.** `lterm processes [session]`(호환 이름: `lterm ps [session]`)은 process-group id와 함께 각 세션 child 아래의 process tree를 보여 줍니다. `--orphans`를 추가하면 기록된 session root의 descendant가 아니지만 같은 process group에 남아 있는 row도 함께 보여 주므로, Codex/OMX/MCP subprocess가 누적되어 메모리 누수처럼 커지기 전에 확인할 수 있습니다. 시스템 `ps`는 절대 경로로 호출하며, 형식이 잘못된 process row는 추측하지 않고 건너뜁니다.
 

package/README.md

@@ -15,6 +15,7 @@
 
 > **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.
+> Non-goals: see [docs/non-goals.md](docs/non-goals.md).
 
 ## Why lterm instead of plain tmux?
 
@@ -75,7 +76,7 @@ For the 1.0 command/output stability boundary, see the
 With Cargo from GitHub (use the latest tag from the Releases page):
 
 ```bash
-cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.0
+cargo install --git https://github.com/ictechgy/light_terminal --tag v1.0.2
 ```
 
 From this checkout, use Rust 1.85 or newer:
@@ -97,10 +98,14 @@ To expose the tmux shim:
 lterm install-shim
 # Add the printed directory to PATH ahead of the real tmux, or eval the helper:
 eval "$(lterm env)"
+# fish:
+lterm env --shell fish | source
 ```
 
 ## Quick start
 
+![lterm quick demo](docs/assets/lterm-demo.svg)
+
 **Create a persistent session and attach immediately:**
 
 ```bash
@@ -133,11 +138,13 @@ 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` |
+| Open a sanitized scrollback composer for input | `lterm compose api` | `mobile` |
 | 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` |
+| Preview local setup steps | `lterm init --shell zsh` | None |
 | Run the background daemon explicitly | `lterm daemon` | None |
 | Stop the daemon and all sessions | `lterm shutdown` | None |
 
@@ -148,13 +155,14 @@ Agent and shim utilities are also product CLI commands, not tmux aliases:
 | Launch a profiled agent session | `lterm agent claude -- --help` | Sibling shortcuts: `lterm claude`, `lterm codex`, `lterm gemini`, `lterm omx`, `lterm omc` |
 | Inspect available agent profiles | `lterm agents --json` | PATH availability probe at command runtime |
 | Install the `tmux` compatibility shim | `lterm install-shim` | Creates a shim that forwards to `lterm tmux-compat` |
-| Print shell exports for tmux compatibility | `eval "$(lterm env)"` | Emits trusted `export` lines that prepend the shim dir to `$PATH` |
+| Print shell exports for tmux compatibility | `eval "$(lterm env)"` (`lterm env --shell fish \| source` for fish) | Emits trusted shell setup that prepends the shim dir to `$PATH` |
 | Send a cmux-friendly notification | `lterm notify --title 'Done' --body 'Tests passed'` | OSC 777 fallback strips terminal controls while preserving Unicode text |
 | Attach to a remote host | `lterm ssh user@host main` | Use trusted hosts; SSH handles host-key checks, and remote PTY bytes pass through without sanitization |
 | Call the tmux shim namespace directly | `lterm tmux-compat list-commands` | Compatibility namespace, not a product alias table |
 
 Use `eval "$(lterm env)"` only when you trust the `lterm` binary on your `PATH`.
 It emits fixed `export` lines that prepend the shim directory to `$PATH`.
+For fish, use `lterm env --shell fish | source` after the same trust check.
 
 `lterm ssh` forwards remote PTY bytes to the local terminal without sanitizing
 terminal control sequences, so a compromised remote can drive terminal features
@@ -233,12 +241,16 @@ lterm sessions --children
 lterm sessions --all
 lterm processes api --orphans
 lterm logs api --start=-80 --end=-1
+lterm compose api
 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, `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`.
+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, `compose` shows sanitized scrollback with a fixed bottom prompt for committing text, `wait` / `watch` make marker-or-exit conditions observable for scripts and agents, and `input` writes text to the target PTY. `mobile` is a visible alias for `compose`; the compatibility names `list` / `ls`, `ps`, `capture`, and `send` remain available for scripts and muscle memory.
+
+For automation and tests, `lterm compose api --once --message 'hello'` performs one sanitized capture/send cycle. It captures the last `--tail` sanitized lines (default: 80) from the same session-or-pane target model as `logs`, then appends Enter (`\r`) by default, matching `lterm input --enter`; add `--no-enter` to send the exact message bytes. `compose` / `mobile` is not an attach client and does not change attached-client counts or PTY geometry.
+In interactive compose, the view refreshes on `--refresh` (default: 500ms) and after local input or resize events. Pressing Enter commits the current input buffer (empty buffers are committed too) and appends `\r` by default, matching the one-shot rule above. Ctrl-C, Ctrl-D, and Esc exit the local composer instead of forwarding to the PTY.
 
 **Stop a session:**
 
@@ -398,7 +410,7 @@ the old code until they are stopped.
 
 **Terminal output is forwarded as-is.** `lterm resume` (compatibility name: `lterm attach`) passes PTY bytes through so full-screen terminal programs and cmux/OSC notifications keep working. The local status bar is purely a client-side decoration; use `--no-status` for a fully raw terminal surface. Untrusted child programs can still emit terminal escape sequences to an attached terminal — exactly as under tmux/screen. **Do not use `lterm` as an escape-sequence sanitizer or sandbox.**
 
-**Capture output is sanitized for human/AI consumption.** `lterm logs` (compatibility name: `lterm capture`) and `tmux capture-pane` strip common terminal control sequences before printing scrollback.
+**Capture output is sanitized for human/AI consumption.** `lterm logs` (compatibility name: `lterm capture`), `lterm compose` (alias: `lterm mobile`), and `tmux capture-pane` strip common terminal control sequences before printing scrollback. `compose` is a non-attached view that commits text through the existing input/send path; it does not transform raw attached PTY streams.
 
 **Process visibility.** `lterm processes [session]` (or compatibility name `lterm ps [session]`) shows the process tree rooted at each session child, including process-group ids. Add `--orphans` to also include same-process-group rows that are no longer descendants of the recorded session root, so long-running Codex/OMX/MCP subprocess buildup stays visible before it becomes a memory-leak surprise. The system `ps` is invoked by absolute path, and malformed process rows are skipped rather than guessed at.
 
@@ -434,6 +446,20 @@ LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- logs test -
 LTERM_RUNTIME_DIR="$TMP/run" LTERM_DATA_DIR="$TMP/data" cargo run -- shutdown
 ```
 
+Release/contract preflight helpers:
+
+```bash
+scripts/release-preflight.sh --contract-only
+scripts/release-preflight.sh --allow-occupied-skip --skip-audit
+scripts/dependency-minor-dry-run.sh
+```
+
+Use `--run-soak` on `scripts/release-preflight.sh` only for the manual
+release-gate soak profile. Use
+[`docs/release-evidence-template.md`](docs/release-evidence-template.md) to
+capture release, audit, contract, dependency, and soak evidence before tagging or
+publishing.
+
 ## License
 
 Licensed under either of:

package/docs/assets/lterm-demo.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="420" role="img" aria-labelledby="title desc">
+  <title id="title">lterm quick demo</title>
+  <desc id="desc">Terminal-style demo showing a detached lterm session, sanitized logs, JSON wait, and resume.</desc>
+  <rect width="920" height="420" rx="18" fill="#0b1020"/>
+  <rect x="18" y="18" width="884" height="384" rx="14" fill="#111827" stroke="#334155"/>
+  <circle cx="46" cy="46" r="7" fill="#ef4444"/>
+  <circle cx="70" cy="46" r="7" fill="#f59e0b"/>
+  <circle cx="94" cy="46" r="7" fill="#22c55e"/>
+  <text x="124" y="52" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15" fill="#94a3b8">lterm: persistent terminal sessions for agents</text>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">
+    <text x="42" y="94" fill="#38bdf8">$</text>
+    <text x="66" y="94" fill="#e5e7eb">lterm start -d -n api -- sh -lc 'echo READY; sleep 60'</text>
+    <text x="66" y="124" fill="#a7f3d0">api    %0    sh -lc 'echo READY; sleep 60'</text>
+
+    <text x="42" y="172" fill="#38bdf8">$</text>
+    <text x="66" y="172" fill="#e5e7eb">lterm logs api -S=-20</text>
+    <text x="66" y="202" fill="#a7f3d0">READY</text>
+
+    <text x="42" y="250" fill="#38bdf8">$</text>
+    <text x="66" y="250" fill="#e5e7eb">lterm wait api --contains READY --json</text>
+    <text x="66" y="280" fill="#a7f3d0">{ &quot;target&quot;: &quot;api&quot;, &quot;matched&quot;: true, &quot;timed_out&quot;: false }</text>
+
+    <text x="42" y="328" fill="#38bdf8">$</text>
+    <text x="66" y="328" fill="#e5e7eb">lterm resume api</text>
+    <text x="66" y="358" fill="#fbbf24">raw PTY attach resumes the live session</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/lterm",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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",
@@ -23,6 +23,7 @@
   },
   "files": [
     "bin/lterm.js",
+    "docs/assets/lterm-demo.svg",
     "README.md",
     "README.ko.md",
     "LICENSE",
@@ -30,10 +31,10 @@
     "LICENSE-MIT"
   ],
   "optionalDependencies": {
-    "lterm-darwin-arm64": "1.0.0",
-    "lterm-darwin-x64": "1.0.0",
-    "lterm-linux-arm64": "1.0.0",
-    "lterm-linux-x64": "1.0.0"
+    "lterm-darwin-arm64": "1.0.2",
+    "lterm-darwin-x64": "1.0.2",
+    "lterm-linux-arm64": "1.0.2",
+    "lterm-linux-x64": "1.0.2"
   },
   "engines": {
     "node": ">=16"