Release v0.1.1

AGENTS.md

@@ -1,3 +1,5 @@
+# AGENTS.md - Guide for Coding Agents
+
 <!-- gitnexus:start -->
 # GitNexus MCP
 
@@ -23,3 +25,270 @@ This project is indexed by GitNexus as **myworktree** (221 symbols, 611 relation
 | Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
 
 <!-- gitnexus:end -->
+
+## Project Overview
+
+myworktree is a lightweight single-user manager for **git worktrees** and **long-running CLI instances**, with a minimal Web UI and HTTP API. It provides isolated workspaces for multiple coding tasks with persistent, re-attachable terminals.
+
+**Key Requirements:**
+- Go 1.25+ (see go.mod)
+- No external Go dependencies
+- Target: macOS 12+ (other platforms not validated)
+- Requires: `git`, `zsh`, `script`
+
+## Build, Test, and Lint Commands
+
+### Building
+```bash
+# Build primary binary
+go build -o myworktree ./cmd/myworktree
+
+# Build alias command (auto-opens browser by default)
+go build -o mw ./cmd/mw
+
+# Run server (MUST be inside target git repo)
+go run ./cmd/myworktree -listen 127.0.0.1:0
+```
+
+### Testing
+```bash
+# Run full test suite
+go test ./...
+
+# Run tests for a specific package with verbose output
+go test ./internal/worktree -v
+
+# Run a single test function
+go test ./internal/app -run TestNormalizeLabels -v
+
+# Run integration tests (may require git setup)
+go test ./internal/worktree -run TestIntegration -v
+```
+
+### Linting and Formatting
+```bash
+# Format check used by CI (must pass before commit)
+test -z "$(gofmt -l .)"
+
+# Auto-format all Go files
+gofmt -w .
+
+# Verify formatting
+gofmt -d .
+```
+
+### Pre-commit Checklist
+```bash
+test -z "$(gofmt -l .)" && go test ./... && go build -o myworktree ./cmd/myworktree && go build -o mw ./cmd/mw
+```
+
+## Code Style Guidelines
+
+### Formatting
+- **Use gofmt**: All code must be formatted with `gofmt`. This is enforced by CI.
+- **No external formatters**: Do not introduce additional formatting tools.
+
+### Imports
+Group imports in this order with blank lines between:
+1. Standard library packages
+2. Third-party packages (none in this project)
+3. Internal packages (prefixed with `myworktree/internal/`)
+
+```go
+import (
+	"errors"
+	"fmt"
+	"os"
+
+	"myworktree/internal/store"
+	"myworktree/internal/worktree"
+)
+```
+
+### Naming Conventions
+- **Exported names**: PascalCase (e.g., `ManagedWorktree`, `FileStore`)
+- **Unexported names**: camelCase (e.g., `dataDir`, `worktreeMgr`)
+- **Acronyms**: Keep uppercase (e.g., `ID`, `PID`, `HTTP`, `JSON`)
+- **Interfaces**: Use `-er` suffix for single-method interfaces (e.g., `Manager`, `Store`)
+- **Constants**: MixedCaps or ALL_CAPS for exported constants
+- **Error variables**: Prefix with `err` (e.g., `errInvalidRepoListenPort`)
+
+### Type Definitions
+- **Structs**: Define with JSON tags for serializable types
+- **Prefer composition**: Embed structs rather than inheritance
+- **Constructor pattern**: Use `New()` functions that return (`*Type, error`)
+
+```go
+type Config struct {
+	ListenAddr   string
+	AuthToken    string
+	WorktreesDir string
+}
+
+type Manager struct {
+	GitRoot      string
+	DataDir      string
+	WorktreesDir string
+	Store        store.FileStore
+}
+
+func New(cfg Config, logger *log.Logger) (*Server, error) {
+	// Validate inputs
+	if logger == nil {
+		return nil, errors.New("logger is required")
+	}
+	// ... initialization
+	return &Server{...}, nil
+}
+```
+
+### Error Handling
+- **Return errors explicitly**: Do not panic in library code
+- **Wrap errors**: Provide context when appropriate
+- **Use errors.New()** for simple static error messages
+- **Define package-level error variables** for errors that need comparison
+
+```go
+var errInvalidRepoListenPort = errors.New("invalid persisted listen_port")
+
+func (m Manager) Create(taskDesc string) (store.ManagedWorktree, error) {
+	if strings.TrimSpace(taskDesc) == "" {
+		return store.ManagedWorktree{}, errors.New("task description is required")
+	}
+	// ... implementation
+}
+```
+
+### Resource Management
+- **Use defer for cleanup**: Always defer Close(), Unlock(), etc.
+- **Check errors in defer**: Use blank identifier for cleanup errors when appropriate
+
+```go
+f, err := os.OpenFile(path, os.O_RDONLY, 0o600)
+if err != nil {
+	return err
+}
+defer f.Close()
+
+if err := syscall.Flock(int(f.Fd()), syscall.LOCK_SH); err != nil {
+	return err
+}
+defer func() { _ = syscall.Flock(int(f.Fd(), syscall.LOCK_UN) }()
+```
+
+### Concurrency
+- **Protect shared state**: Use `sync.Mutex` or `sync.RWMutex` for thread safety
+- **Lock at the right granularity**: Hold locks for minimal time
+- **Document thread safety**: Comment on whether functions are thread-safe
+
+```go
+type Manager struct {
+	stateMu sync.Mutex  // protects Store access
+	mu      sync.Mutex  // protects running/inputs maps
+	// ...
+}
+
+func (m *Manager) Start(in StartInput) (store.ManagedInstance, error) {
+	m.mu.Lock()
+	if m.running == nil {
+		m.running = map[string]*exec.Cmd{}
+	}
+	m.mu.Unlock()
+	// ... rest of implementation
+}
+```
+
+### Testing Conventions
+- **Test file naming**: `<name>_test.go` in the same package
+- **Test function naming**: `Test<FunctionName>` or `Test<Scenario>`
+- **Table-driven tests**: Prefer for multiple test cases
+- **Integration tests**: Suffix with `_integration_test.go` or use build tags
+
+```go
+func TestSlugify(t *testing.T) {
+	got := slugify("Fix login 401 & add tests!")
+	want := "fix-login-401-add-tests"
+	if got != want {
+		t.Fatalf("unexpected slugify result: got %q, want %q", got, want)
+	}
+}
+```
+
+### Comments and Documentation
+- **Package comments**: Start with "Package <name>" for package docs
+- **Exported types/functions**: Add doc comments explaining purpose
+- **Implementation comments**: Explain "why", not "what"
+- **No TODO/FIXME comments** in production code without tracking issue
+
+### File Organization
+- **One primary type per file**: Named after the type (e.g., `manager.go` for `Manager`)
+- **Test files**: Same directory as source with `_test.go` suffix
+- **Package structure**: Follow internal package layout:
+  - `app/` - HTTP server, routing, auth
+  - `worktree/` - Worktree lifecycle management
+  - `instance/` - Process management
+  - `store/` - State persistence
+  - `tag/` - Tag configuration
+  - `redact/` - Log redaction
+  - `ui/` - Embedded static UI
+  - `mcp/` - MCP adapter
+  - `gitx/` - Git operations
+  - `ws/` - WebSocket handling
+  - `cli/` - CLI command handling
+  - `version/` - Version information
+
+### JSON and Serialization
+- **Use struct tags**: Always include `json` tags for serializable fields
+- **Omit empty fields**: Use `omitempty` for optional fields
+- **Use consistent field names**: Prefer snake_case in JSON for API compatibility
+
+```go
+type ManagedWorktree struct {
+	ID        string `json:"id"`
+	Name      string `json:"name"`
+	Path      string `json:"path"`
+	Branch    string `json:"branch"`
+	CreatedAt string `json:"created_at"`
+}
+```
+
+## Important Architectural Notes
+
+1. **Run Location Matters**: The server MUST be executed inside the target git repository because repo detection and per-project data directories derive from CWD.
+
+2. **State Storage**: All persisted state uses `store.FileStore` with file locking and atomic writes. Never write state directly; always go through the store.
+
+3. **Branch Naming**:
+   - Default: `mwt/<slug>`
+   - Custom: If task description is `<group>/<name>`, branch is `<group>/<name>` (no prefix)
+   - Slug is ASCII-only, max 48 chars, falls back to "worktree" if empty
+
+4. **Strict Deletion**: Worktree deletion refuses if `git status --porcelain` is non-empty (includes untracked files).
+
+5. **Security Defaults**:
+   - Server defaults to loopback listen
+   - Non-loopback requires `--auth` token
+   - Optional TLS via `--tls-cert/--tls-key`
+   - Log redaction for secrets (e.g., `sk-...`)
+   - Env sanitization for TOKEN/SECRET/KEY/PASSWORD keys
+
+## CI/CD
+
+GitHub Actions runs on:
+- Pushes to `develop` and `main` branches
+- Pull requests targeting `develop` and `main`
+
+CI Pipeline (`.github/workflows/go-ci.yml`):
+1. Verify `gofmt` formatting
+2. Run `go test ./...`
+3. Build both binaries (`myworktree` and `mw`)
+
+Release Process (`.github/workflows/release.yml`):
+- Triggered by `v*` tags
+- Builds darwin `amd64`/`arm64` archives with checksums
+
+## Additional Resources
+
+- **Documentation**: See `docs/` directory for PRD, Architecture, and API docs
+- **Changelog**: See `CHANGELOG.md` for version history
+- **License**: MIT License (see `LICENSE` file)

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.1.1
+
+Recommended stable release after the `v0.1.0` GitHub Release assets were withdrawn during post-release validation. The `v0.1.0` tag remains the comparison baseline, but `v0.1.1` is the supported public release.
+
+Highlights:
+- Fixed multiple terminal/TUI regressions that could leak terminal query responses into the shell, break UTF-8 output across transport boundaries, or leave the terminal in a bad state after switching instances.
+- Added a WebSocket TTY handshake plus browser-to-PTY resize propagation so interactive programs start with a valid terminal size and reconnect more reliably.
+- Improved terminal UX with larger client-side scrollback, safer reconnect/state transitions, and instance-switch behavior that avoids stale mouse-tracking side effects.
+- Fixed managed worktree edge cases when deleting entries whose directories were already removed, and kept compatibility when importing older `wt/<name>` worktrees.
+
+Documentation and validation:
+- Added deeper terminal I/O analysis, filter review notes, and terminal-focused test cases to document the root causes behind the `v0.1.1` fixes.
+- Expanded automated coverage for PTY resize behavior, redaction behavior, and worktree integration scenarios touched by the release.
+
 ## v0.1.0
 
 Initial public release of `myworktree`.

README.md

@@ -58,10 +58,10 @@ Example:
 
 ```bash
 # Pick the archive that matches your Mac, then verify and unpack it.
-curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.0/myworktree_v0.1.0_darwin_arm64.tar.gz
-curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.0/checksums.txt
+curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.1/myworktree_v0.1.1_darwin_arm64.tar.gz
+curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.1/checksums.txt
 shasum -a 256 -c checksums.txt --ignore-missing
-tar -xzf myworktree_v0.1.0_darwin_arm64.tar.gz
+tar -xzf myworktree_v0.1.1_darwin_arm64.tar.gz
 
 # Optional: install into PATH
 sudo install -m 755 ./mw /usr/local/bin/mw
@@ -71,6 +71,8 @@ sudo install -m 755 ./myworktree /usr/local/bin/myworktree
 mw --version
 ```
 
+Start from `v0.1.1` or newer for public release binaries. The earlier `v0.1.0` GitHub Release assets were withdrawn after post-release validation uncovered severe terminal interaction issues.
+
 Each release archive contains `mw`, `myworktree`, `README.md`, `LICENSE`, and `CHANGELOG.md`.
 If there is no prerelease/release asset yet, or you need a platform we do not publish, follow the source build steps below.
 

README.zh-CN.md

@@ -27,6 +27,8 @@ myworktree 只做管理，不碰项目具体内容：
 ## 功能（MVP）
 - 受管 worktree：创建/列表/纳入管理(import)/删除（严格删除：dirty 则拒绝）
 - 受管 instance：基于 Tag 启动模板启动/停止/重启/列表
+- instance 重启会保留 worktree、tag/命令、labels，并串联旧/新实例记录
+- 支持可选 instance labels（`k=v`），可用于 UI 过滤与搜索
 - 默认 WebSocket Web TTY 交互（并保留 SSE/HTTP 兜底）
 - 前端页面关闭/刷新后：后端 instance 继续运行；重新打开可回放输出并继续交互
 - UI 提供传输状态标记（websocket/sse/polling）和 WS 重连按钮
@@ -56,10 +58,10 @@ myworktree 只做管理，不碰项目具体内容：
 
 ```bash
 # 根据你的 Mac 机型选择对应压缩包，然后校验并解压
-curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.0/myworktree_v0.1.0_darwin_arm64.tar.gz
-curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.0/checksums.txt
+curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.1/myworktree_v0.1.1_darwin_arm64.tar.gz
+curl -LO https://github.com/linletian/myworktree/releases/download/v0.1.1/checksums.txt
 shasum -a 256 -c checksums.txt --ignore-missing
-tar -xzf myworktree_v0.1.0_darwin_arm64.tar.gz
+tar -xzf myworktree_v0.1.1_darwin_arm64.tar.gz
 
 # 可选：安装到 PATH
 sudo install -m 755 ./mw /usr/local/bin/mw
@@ -69,6 +71,8 @@ sudo install -m 755 ./myworktree /usr/local/bin/myworktree
 mw --version
 ```
 
+建议从 `v0.1.1` 或更新版本开始使用公开发布版二进制。更早的 `v0.1.0` GitHub Release 资产在补充实测中发现严重终端交互问题后已撤回。
+
 每个发布压缩包内都包含 `mw`、`myworktree`、`README.md`、`LICENSE` 和 `CHANGELOG.md`。
 如果当前还没有预发布/正式发布压缩包，或者你的平台暂无对应产物，就直接使用下面的源码编译步骤。