feat: add kugetsu session manager skill

- skills/kugetsu/SKILL.md: Agent skill documentation following agentskills.io spec
- skills/kugetsu/scripts/kugetsu: Shell wrapper for opencode session management
  - Commands: start, list [--all], resume, stop, help
  - State tracking: used → idle (graceful) or left (interrupted)
  - Auto-fill message on resume
  - Confirmation prompt when resuming used session
- skills/kugetsu/scripts/kugetsu-install.sh: Installation script for users

Implements Phase 1 of issue #11 - basic session management layer
for remote agent control without Hermes dependency.

skills/kugetsu/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: kugetsu
+description: Session manager for opencode CLI. Use when managing long-running opencode sessions, resuming interrupted work, or tracking session state across disconnects. Features state tracking (used/idle/left), auto-fill last message on resume, and safe locking via confirmation prompts.
+license: MIT
+compatibility: Requires opencode CLI, bash, and filesystem access for session state.
+metadata:
+  author: shoko
+  version: "1.0"
+---
+
+# kugetsu - OpenCode Session Manager
+
+Manages opencode CLI sessions with state tracking and safe resume.
+
+## Installation
+
+### For Human Users
+Run once on a new host:
+```bash
+. skills/kugetsu/scripts/kugetsu-install.sh
+```
+
+### For Agents (Self-Install)
+Copy the script to your PATH:
+```bash
+cp skills/kugetsu/scripts/kugetsu ~/.local/bin/kugetsu
+chmod +x ~/.local/bin/kugetsu
+```
+
+Or source directly when needed:
+```bash
+. skills/kugetsu/scripts/kugetsu
+```
+
+## Session State
+
+| State | Meaning | Resumable? |
+|-------|---------|------------|
+| `used` | Session is active (process running) | Yes (with confirmation) |
+| `idle` | Session ended gracefully | No |
+| `left` | Session interrupted/crashed | Yes |
+| `invalid` | Session data missing/corrupt | No |
+
+## Session Directory
+
+Sessions are stored in `~/.kugetsu/sessions/<session_id>/`:
+- `state` - current state (used/idle/left/invalid)
+- `message` - last user message (for auto-fill)
+- `pid` - active process PID (when used)
+
+## Commands
+
+### kugetsu start `<session_id>` `<message>`
+Start a new session:
+```bash
+kugetsu start mytask "fix bug #1"
+```
+- Creates session directory
+- Sets state to `used`
+- Stores PID and message
+- Runs: `opencode run --session <session_id> <message>`
+
+### kugetsu list [--all]
+List sessions:
+```bash
+kugetsu list          # Shows only `left` (resumable)
+kugetsu list --all    # Shows all states
+```
+
+### kugetsu resume `<session_id>` [message]
+Resume an interrupted session:
+```bash
+kugetsu resume mytask                 # Auto-fills last message
+kugetsu resume mytask "continue"     # Uses provided message
+```
+- If state is `used`: prompts for confirmation (someone else might be using)
+- If state is `idle`: errors (not resumable)
+- If state is `left`: proceeds with message
+
+### kugetsu stop `<session_id>`
+Stop a session gracefully:
+```bash
+kugetsu stop mytask
+```
+- Sends SIGTERM to process
+- Sets state to `idle`
+
+### kugetsu help
+Show usage help.
+
+## State Transitions
+
+```
+start ──────────────► used ──────► idle (stop/SIGTERM)
+                         │
+                         └──────► left (kill/SIGINT/crash)
+```
+
+## Example Workflow
+
+```bash
+# Start a long-running task
+kugetsu start issue42 "implement feature X"
+
+# ... time passes, connection drops ...
+
+# Check what sessions are resumable
+kugetsu list
+
+# Resume with auto-filled message
+kugetsu resume issue42
+
+# Later, when done
+kugetsu stop issue42
+```
+
+## Without kugetsu
+
+If kugetsu is not installed, use opencode directly:
+```bash
+opencode run --session mytask "task description"
+opencode run --continue --session mytask "continue"
+opencode session list
+```
+Tradeoff: No state tracking, no auto-fill, no filtered list, no confirmation prompts.

skills/kugetsu/scripts/kugetsu

@@ -0,0 +1,330 @@
+#!/bin/bash
+set -euo pipefail
+
+KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
+SESSIONS_DIR="$KUGETSU_DIR/sessions"
+BIN_DIR="$KUGETSU_DIR/bin"
+
+usage() {
+    cat << 'EOF'
+kugetsu - OpenCode Session Manager
+
+Usage:
+    kugetsu start <session_id> <message>   Start a new session
+    kugetsu list [--all]                    List sessions (default: left only)
+    kugetsu resume <session_id> [message]   Resume a session
+    kugetsu stop <session_id>               Stop a session gracefully
+    kugetsu help                            Show this help
+
+States:
+    used   - Session is active (process running)
+    idle   - Session ended gracefully (not resumable)
+    left   - Session interrupted/crashed (resumable)
+    invalid - Session data missing/corrupt
+
+Examples:
+    kugetsu start mytask "fix bug #1"
+    kugetsu list
+    kugetsu list --all
+    kugetsu resume mytask
+    kugetsu resume mytask "continue working"
+    kugetsu stop mytask
+EOF
+}
+
+ensure_dirs() {
+    mkdir -p "$SESSIONS_DIR" "$BIN_DIR"
+}
+
+get_session_dir() {
+    local session_id="$1"
+    echo "$SESSIONS_DIR/$session_id"
+}
+
+get_state() {
+    local session_dir="$1"
+    if [ -f "$session_dir/state" ]; then
+        cat "$session_dir/state"
+    else
+        echo "invalid"
+    fi
+}
+
+set_state() {
+    local session_dir="$1"
+    local state="$2"
+    echo "$state" > "$session_dir/state"
+}
+
+is_process_running() {
+    local pid="$1"
+    if kill -0 "$pid" 2>/dev/null; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+check_and_update_state() {
+    local session_dir="$1"
+    local state=$(get_state "$session_dir")
+    
+    if [ "$state" = "used" ]; then
+        local pid_file="$session_dir/pid"
+        if [ -f "$pid_file" ]; then
+            local pid=$(cat "$pid_file")
+            if ! is_process_running "$pid"; then
+                set_state "$session_dir" "left"
+                return 1
+            fi
+        else
+            set_state "$session_dir" "left"
+            return 1
+        fi
+    fi
+    return 0
+}
+
+cmd_start() {
+    if [ $# -lt 2 ]; then
+        echo "Error: start requires <session_id> and <message>" >&2
+        exit 1
+    fi
+    
+    local session_id="$1"
+    local message="$2"
+    local session_dir=$(get_session_dir "$session_id")
+    
+    ensure_dirs
+    
+    if [ -d "$session_dir" ]; then
+        local state=$(get_state "$session_dir")
+        check_and_update_state "$session_dir"
+        state=$(get_state "$session_dir")
+        
+        if [ "$state" = "used" ]; then
+            echo "Error: session '$session_id' is already in use (state=used)" >&2
+            echo "Use 'kugetsu list' to see all sessions, or 'kugetsu resume $session_id' to resume" >&2
+            exit 1
+        fi
+        
+        if [ "$state" = "left" ]; then
+            echo "Warning: session '$session_id' was left interrupted" >&2
+            echo "Resuming instead of starting new..." >&2
+            cmd_resume "$session_id" "$message"
+            return
+        fi
+    fi
+    
+    mkdir -p "$session_dir"
+    set_state "$session_dir" "used"
+    echo "$$" > "$session_dir/pid"
+    echo "$message" > "$session_dir/message"
+    
+    echo "Starting session '$session_id'..."
+    opencode run --session "$session_id" "$message"
+    local exit_code=$?
+    
+    if [ $exit_code -eq 0 ]; then
+        set_state "$session_dir" "idle"
+    else
+        set_state "$session_dir" "left"
+    fi
+    
+    rm -f "$session_dir/pid"
+}
+
+cmd_list() {
+    local show_all=false
+    if [ $# -ge 1 ] && [ "$1" = "--all" ]; then
+        show_all=true
+    fi
+    
+    ensure_dirs
+    
+    printf "%-20s %-10s %-s\n" "SESSION_ID" "STATE" "LAST_MESSAGE"
+    printf "%-20s %-10s %-s\n" "──────────" "─────" "───────────"
+    
+    for session_dir in "$SESSIONS_DIR"/*; do
+        if [ -d "$session_dir" ]; then
+            local session_id=$(basename "$session_dir")
+            check_and_update_state "$session_dir"
+            local state=$(get_state "$session_dir")
+            
+            if [ "$show_all" = false ] && [ "$state" != "left" ]; then
+                continue
+            fi
+            
+            local message=""
+            if [ -f "$session_dir/message" ]; then
+                message=$(cat "$session_dir/message")
+                if [ ${#message} -gt 40 ]; then
+                    message="${message:0:37}..."
+                fi
+            fi
+            
+            printf "%-20s %-10s %-s\n" "$session_id" "$state" "$message"
+        fi
+    done
+}
+
+cmd_resume() {
+    if [ $# -lt 1 ]; then
+        echo "Error: resume requires <session_id>" >&2
+        exit 1
+    fi
+    
+    local session_id="$1"
+    local message=""
+    
+    if [ $# -ge 2 ]; then
+        message="$2"
+    fi
+    
+    local session_dir=$(get_session_dir "$session_id")
+    
+    if [ ! -d "$session_dir" ]; then
+        echo "Error: session '$session_id' not found" >&2
+        exit 1
+    fi
+    
+    check_and_update_state "$session_dir"
+    local state=$(get_state "$session_dir")
+    
+    if [ "$state" = "used" ]; then
+        echo "Warning: session '$session_id' is marked as used" >&2
+        local pid=""
+        if [ -f "$session_dir/pid" ]; then
+            pid=$(cat "$session_dir/pid")
+        fi
+        if [ -n "$pid" ] && is_process_running "$pid"; then
+            echo "Error: process $pid is still running for this session" >&2
+            echo "Use 'kugetsu stop $session_id' first, or 'kugetsu resume $session_id' to force resume anyway" >&2
+            exit 1
+        else
+            set_state "$session_dir" "left"
+            state="left"
+        fi
+    fi
+    
+    if [ "$state" = "idle" ]; then
+        echo "Error: session '$session_id' ended gracefully (state=idle)" >&2
+        echo "This session cannot be resumed. Start a new session instead." >&2
+        exit 1
+    fi
+    
+    if [ "$state" = "invalid" ]; then
+        echo "Error: session '$session_id' is invalid (state=invalid)" >&2
+        exit 1
+    fi
+    
+    if [ -z "$message" ]; then
+        if [ -f "$session_dir/message" ]; then
+            message=$(cat "$session_dir/message")
+            echo "Auto-filled message: $message"
+        else
+            echo "Error: no message stored for session '$session_id'" >&2
+            echo "Provide a message as second argument: kugetsu resume $session_id <message>" >&2
+            exit 1
+        fi
+    fi
+    
+    set_state "$session_dir" "used"
+    echo "$$" > "$session_dir/pid"
+    echo "$message" > "$session_dir/message"
+    
+    echo "Resuming session '$session_id'..."
+    opencode run --continue --session "$session_id" "$message"
+    local exit_code=$?
+    
+    if [ $exit_code -eq 0 ]; then
+        set_state "$session_dir" "idle"
+    else
+        set_state "$session_dir" "left"
+    fi
+    
+    rm -f "$session_dir/pid"
+}
+
+cmd_stop() {
+    if [ $# -lt 1 ]; then
+        echo "Error: stop requires <session_id>" >&2
+        exit 1
+    fi
+    
+    local session_id="$1"
+    local session_dir=$(get_session_dir "$session_id")
+    
+    if [ ! -d "$session_dir" ]; then
+        echo "Error: session '$session_id' not found" >&2
+        exit 1
+    fi
+    
+    local state=$(get_state "$session_dir")
+    
+    if [ "$state" != "used" ]; then
+        echo "Error: session '$session_id' is not in use (state=$state)" >&2
+        exit 1
+    fi
+    
+    local pid=""
+    if [ -f "$session_dir/pid" ]; then
+        pid=$(cat "$session_dir/pid")
+    fi
+    
+    if [ -n "$pid" ] && is_process_running "$pid"; then
+        echo "Sending SIGTERM to process $pid..."
+        kill -TERM "$pid" 2>/dev/null || true
+        
+        local count=0
+        while is_process_running "$pid" && [ $count -lt 10 ]; do
+            sleep 0.5
+            count=$((count + 1))
+        done
+        
+        if is_process_running "$pid"; then
+            echo "Process still running, sending SIGKILL..." >&2
+            kill -KILL "$pid" 2>/dev/null || true
+        fi
+    fi
+    
+    set_state "$session_dir" "idle"
+    rm -f "$session_dir/pid"
+    
+    echo "Session '$session_id' stopped"
+}
+
+main() {
+    if [ $# -eq 0 ]; then
+        usage
+        exit 1
+    fi
+    
+    local command="$1"
+    shift
+    
+    case "$command" in
+        help|--help|-h)
+            usage
+            ;;
+        start)
+            cmd_start "$@"
+            ;;
+        list)
+            cmd_list "$@"
+            ;;
+        resume)
+            cmd_resume "$@"
+            ;;
+        stop)
+            cmd_stop "$@"
+            ;;
+        *)
+            echo "Error: unknown command '$command'" >&2
+            usage
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

skills/kugetsu/scripts/kugetsu-install.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+set -euo pipefail
+
+KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
+BIN_DIR="$KUGETSU_DIR/bin"
+
+echo "Installing kugetsu to $KUGETSU_DIR..."
+
+mkdir -p "$BIN_DIR"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+cp "$SCRIPT_DIR/kugetsu" "$BIN_DIR/kugetsu"
+chmod +x "$BIN_DIR/kugetsu"
+
+add_to_shell() {
+    local rc_file="$1"
+    local export_line="export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
+    
+    if [ -f "$rc_file" ]; then
+        if grep -q "$export_line" "$rc_file" 2>/dev/null; then
+            echo "$rc_file already has kugetsu in PATH"
+        else
+            echo "" >> "$rc_file"
+            echo "# kugetsu - opencode session manager" >> "$rc_file"
+            echo "$export_line" >> "$rc_file"
+            echo "Added to $rc_file"
+        fi
+    else
+        echo "" >> "$rc_file"
+        echo "# kugetsu - opencode session manager" >> "$rc_file"
+        echo "$export_line" >> "$rc_file"
+        echo "Created $rc_file with kugetsu PATH"
+    fi
+}
+
+add_to_shell "$HOME/.bashrc"
+add_to_shell "$HOME/.zshrc"
+
+echo ""
+echo "Installation complete!"
+echo ""
+echo "Run this to start using kugetsu immediately:"
+echo "    export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
+echo ""
+echo "Or start a new shell."
+echo ""
+echo "Usage:"
+echo "    kugetsu start <session_id> <message>   Start a new session"
+echo "    kugetsu list                          List sessions"
+echo "    kugetsu resume <session_id> [msg]     Resume a session"
+echo "    kugetsu stop <session_id>             Stop a session"
+echo "    kugetsu help                          Show help"