Upgraded version with all latest changes (extends PR #1)

.agents/skills/devpt-release/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: devpt-release
+description: Increment version and update CHANGELOG.md from commits since last update. Use when making a release, bumping version, or updating changelog for dev-process-tracker.
+---
+
+# DevPT Release Skill
+
+## Usage
+
+```
+<user asks: "make a patch release"> or "bump minor version" or "devpt release major"
+```
+
+## Workflow
+
+1. **Read CHANGELOG.md** — extract current version from first `## X.Y.Z` header
+2. **Find last update** — get SHA of the commit that last modified CHANGELOG.md
+3. **Get commits since** — `git log <SHA>..HEAD --oneline --no-merges`
+4. **Group & classify**:
+   - Parse commit messages for intent (add/fix/change/remove/refactor/docs)
+   - **Group related commits**: if a "fix" or "polish" follows a feature in time/subject, fold it into that feature line
+   - Prioritize user-facing changes over internal polish
+5. **Determine bump**:
+   - `major` (0.x → 1.0 or breaking) / `minor` (features) / `patch` (fixes) — use user-specified if provided
+6. **Generate entries** — write concise imperative-mood bullets:
+   - "Added X so Y" for features
+   - "Fixed Z so W" for bugs
+   - Group related fixes with their feature when they're clearly connected
+7. **Update CHANGELOG.md** — prepend new version section
+8. **Set version** — run `./scripts/set-version.sh <X.Y.Z>` to update version.go, commit, and tag
+9. **Push** — `git push && git push origin v<X.Y.Z>`
+
+## Version Management
+
+- **Version file**: `pkg/buildinfo/version.go` (`const Version = "X.Y.Z"`)
+- **Set version script**: `./scripts/set-version.sh <X.Y.Z>` — updates version.go, commits, creates tag
+- **Tags use `v` prefix**: `v0.2.1`
+- **Pre-push hook**: validates version.go matches latest tag (via lefthook)
+
+## Grouping Heuristics
+
+When classifying commits, apply these rules:
+
+1. **Time proximity**: Fixes within 1-3 commits of a feature likely belong to it
+2. **Subject overlap**: "fix search" after "add search input" → same entry
+3. **Keyword clues**: "polish", "tweak", "adjust", "follow-up" often indicate related work
+4. **When uncertain**: Keep separate rather than over-grouping
+
+## Flags
+
+- `--review` — show grouped commits and proposed entries before writing
+- `--dry-run` — output the new section without modifying the file
+
+## Example Output
+
+```markdown
+## 0.3.0
+
+- Added dark mode toggle so users can switch themes without reloading
+- Fixed theme persistence so preference survives across sessions
+- Removed deprecated `/legacy` endpoint
+```
+
+## Edge Cases
+
+- **No commits since last update**: Report "no changes since last release" and exit
+- **Uncommitted changes**: Warn but proceed (commits are the source of truth)
+- **Version is 0.x**: Treat as pre-release; minor bumps for features, patch for fixes

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 # DevPortTrack Copilot Instructions
 
-A macOS CLI tool for discovering, tracking, and managing local development servers. ~3,900 lines of Go across 9 packages.
+A macOS CLI tool for discovering, tracking, and managing local development servers. ~8,300 lines of Go across 10 packages.
 
 ## Quick Reference
 
@@ -27,12 +27,14 @@ go test -v ./pkg/cli -run TestWarnLegacyManagedCommands
 
 ### Key Directories
 - **cmd/devpt/main.go** - CLI entry point (~170 lines). Routes commands and prints results to stdout/stderr.
-- **pkg/cli/** - Command handlers (commands.go), TUI app controller (app.go), and Bubble Tea UI (tui.go). ~50KB of code.
+- **pkg/cli/** - Command handlers (commands.go), TUI app controller (app.go), and Bubble Tea UI (pkg/cli/tui/). ~50KB of code.
 - **pkg/scanner/** - Process discovery via `lsof`, project root detection, and AI agent detection.
 - **pkg/registry/** - Service registry (JSON at ~/.config/devpt/registry.json). Thread-safe CRUD operations.
 - **pkg/process/** - Process lifecycle management: spawning, log capture, graceful shutdown.
+- **pkg/lifecycle/** - Service lifecycle orchestration: identity verification, reconciliation, readiness checks, per-service locking, start/stop/restart workflows. See PROCESS_MANAGEMENT.md for the behavioral contract.
 - **pkg/models/** - Core data structures (ProcessRecord, ManagedService, AgentTag) and config paths.
 - **pkg/health/** - Health check utilities (basic placeholder for future expansion).
+- **pkg/resource/** - Runtime resource metrics (memory RSS) via batch `ps` calls.
 
 ## Architecture Overview
 
@@ -41,26 +43,43 @@ go test -v ./pkg/cli -run TestWarnLegacyManagedCommands
 2. **Resolver** walks filesystem to find project roots (.git, go.mod, package.json, etc.)
 3. **Detector** analyzes parent process/env to identify AI-agent-started servers
 4. **Registry** (`pkg/registry`) manages user-registered managed services (JSON at ~/.config/devpt/registry.json)
-5. **Process Manager** (`pkg/process`) handles spawning, stopping, and log capture
-6. **CLI/TUI** presents the unified list and command interface
+5. **Lifecycle Manager** (`pkg/lifecycle`) orchestrates start/stop/restart with identity verification, readiness, and per-service locking
+6. **Process Manager** (`pkg/process`) handles spawning, stopping, and log capture
+7. **Resource Collector** (`pkg/resource`) fetches runtime metrics (memory) via batch `ps` calls
+8. **Health Checker** (`pkg/health`) probes ports for responsiveness
+9. **CLI/TUI** presents the unified list and command interface
 
 ### Key Models
 - **ProcessRecord**: Discovered listening process (PID, port, command, project root, agent detection)
 - **ManagedService**: User-registered service (name, cwd, command, ports, timestamps)
 - **AgentTag**: Detection result (source, agent name, confidence level)
 - **Registry**: Container for all managed services (versioned JSON format)
 
+### Runtime Observations
+Memory and health are runtime observations, separate from discovery data:
+- Fetched asynchronously in the TUI update loop (every 2s when idle)
+- Stored in TUI model maps keyed by PID (memory) or port (health)
+- Not persisted — they reflect current state only
+- Batch collection via `ps -p <pids> -o pid=,rss=` — returns KB for each PID
+
 ### Command Routing
 Entry point (cmd/devpt/main.go) routes commands:
 - No args → `app.TopCmd()` (opens interactive TUI in pkg/cli/tui.go)
 - `ls`, `add`, `start`, `stop`, `restart`, `logs`, `status` → handler functions
 
 ## Critical Implementation Details
 
+### Service Identity and Lifecycle
+The lifecycle layer (`pkg/lifecycle`) manages service identity using an ordered evidence chain:
+1. PID + start time → 1b. Stored LastPID + path → 2. Declared port → 3. CWD + resolved command → 4. Exact CWD → 5. Project root
+
+After spawn, the OS-resolved command is captured and stored for future identity matching.
+See PROCESS_MANAGEMENT.md §1.3 and §3.4 for the full contract.
+
 ### ProcessRecord vs ManagedService Merging
 When listing services:
-1. Merge discovered processes with managed registry entries
-2. Managed service appears as "running" if its PID is in discovered processes
+1. Merge discovered processes with managed registry entries via the reconciler
+2. Managed service appears as "running" if identity verification confirms ownership
 3. Source field shows: "manual" (discovered but unmanaged), "managed" (registered), or "agent:xxx" (detected)
 
 ### Agent Detection Confidence
@@ -77,7 +96,8 @@ Returns confidence level: low, medium, or high. Code uses these intelligently fo
 - Processes spawn in separate process groups (setpgid)
 - stdout/stderr redirected to ~/.config/devpt/logs/{serviceName}/{timestamp}.log
 - Graceful shutdown: SIGTERM with timeout, then SIGKILL
-- PID and start time tracked in registry after spawn
+- PID, start time, and resolved command tracked in registry after spawn
+- TUI stop/restart routes through the lifecycle layer (not raw PID calls)
 
 ### Directory Caching
 Project resolver caches directory → project root mappings.
@@ -97,18 +117,27 @@ Cache can be invalidated selectively. Important for performance (lsof calls are
 ## Testing
 
 ### Test Locations
-- **pkg/cli/**: app_warning_test.go (TestWarnLegacyManagedCommands), command_validation_test.go (TestValidateManagedCommand, TestFirstBlockedShellPattern) - 3 tests total
-- **pkg/process/**: manager_parse_test.go (TestParseCommandArgs, TestParseCommandArgs_UnterminatedQuote) - 2 tests total
+- **pkg/cli/**: command validation, pattern matching, batch ops, status commands, display formatting — 10 test files
+- **pkg/cli/tui/**: UI rendering, key input, state transitions, viewports, memory display, namespaces, OSC8, group color — 12 test files
+- **pkg/lifecycle/**: identity, reconciliation, start/stop/restart flows, readiness, locking, outcomes — 11 test files
+- **pkg/process/**: command parsing, start time — 2 test files
+- **pkg/resource/**: memory formatting, color thresholds, collection — 1 test file
+- **pkg/registry/**: CRUD operations — 1 test file
+- **pkg/scanner/**: process discovery — 1 test file
+- **pkg/models/**: lifecycle models — 1 test file
 
 ### Test Patterns
 - Table-driven tests for command parsing and validation
 - No external dependencies; tests use pure Go (no mocking framework)
-- Run full suite: `go test ./...` (2 seconds)
+- Run full suite: `go test ./...` (~20 seconds)
 - Run single package: `go test -v ./pkg/cli`
 - Run specific test: `go test -v ./pkg/cli -run TestWarnLegacyManagedCommands`
 
 ## Conventions
 
+### Spec Updates
+- Removed specs: delete cleanly, re-render. No ~~strikethrough~~, no **REMOVED** annotations, no tombstone rows.
+
 ### Naming
 - Packages use lowercase, no underscores (Go convention)
 - Function names: `CommandName()` pattern for exported, `helperName()` for unexported
@@ -133,12 +162,31 @@ Cache can be invalidated selectively. Important for performance (lsof calls are
 - Create dirs if missing with MkdirAll (mode 0755)
 - Log files timestamped as: ~/.config/devpt/logs/{serviceName}/{ISO8601}.log
 
-### TUI-Specific (pkg/cli/tui.go)
+### TUI-Specific (pkg/cli/tui/)
 - Model-based architecture (Bubble Tea): Cmd returns effects, Model contains state
-- Top-level ListModel has tabs for "Running" and "Managed" lists
+- Split-view layout: running services table (top) + managed services list (bottom) + universal details pane (right)
+- Details pane shows info for whichever service is currently selected (running or managed)
 - Never mutate Model state directly—use Cmd/Update pattern
 - Exit conditions: user presses 'q', or explicit quit() command
 - Key handlers prioritized: modal state (logs/input) takes precedence over list navigation
+- Async observation: memory collected every 2s via batch `ps`, health checked asynchronously
+
+## Before Submitting Changes
+
+Always run these checks before considering work complete:
+
+```bash
+# 1. Build succeeds
+go build ./...
+
+# 2. All tests pass
+go test ./...
+
+# 3. CLI runs without error
+go build -o devpt ./cmd/devpt && ./devpt ls
+```
+
+If adding user-facing features, also update README.md and QUICKSTART.md.
 
 ## Common Tasks
 
@@ -173,8 +221,11 @@ Cache can be invalidated selectively. Important for performance (lsof calls are
 ## Documentation Files
 - **README.md** - Full user documentation and CLI reference
 - **QUICKSTART.md** - Getting started guide for new users
+- **PROCESS_MANAGEMENT.md** - Behavioral contract for service lifecycle (identity, reconciliation, outcomes)
+- **DEBUG.md** - Debug protocol with verified runtime workflows
 - **IMPLEMENTATION_SUMMARY.md** - Architecture and feature overview (reference only)
 - **techspec.md** - Original technical specification
+- **.agents/skills/devpt-release/SKILL.md** - Release workflow (changelog + version bump)
 
 Update README and QUICKSTART when adding user-facing features or commands.
 

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+
+      - name: Build binaries
+        run: |
+          mkdir -p dist
+
+          # Linux
+          GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o dist/devpt-linux-x64 ./cmd/devpt
+          GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o dist/devpt-linux-arm64 ./cmd/devpt
+
+          # macOS
+          GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o dist/devpt-macos-x64 ./cmd/devpt
+          GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o dist/devpt-macos-arm64 ./cmd/devpt
+
+          # Windows
+          GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o dist/devpt-windows-x64.exe ./cmd/devpt
+
+      - name: Generate checksums
+        run: |
+          cd dist
+          sha256sum * > checksums.txt
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

.gitignore

@@ -8,6 +8,28 @@
 /.tmp-home/
 /.tmp-home*/
 
-
 # Local draft/working docs
-/docs
+/docs
+/coverage.out
+
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+vendor/
+
+# Coverage
+*.coverprofile
+coverage.html
+
+# Test fixture binaries (no extension on macOS)
+/sandbox/servers/*/go-basic
+/sandbox/servers/*/*/node
+/sandbox/servers/*/*/server.js
+/.claude/settings.local.json
+wireframe*.*