taskmux 0.2.7__tar.gz → 0.3.0__tar.gz

{taskmux-0.2.7 → taskmux-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskmux
-Version: 0.2.7
+Version: 0.3.0
 Summary: Modern tmux-based task manager for LLM development tools
 Project-URL: Homepage, https://github.com/nc9/taskmux
 Project-URL: Repository, https://github.com/nc9/taskmux
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 
 # Taskmux
 
-A modern tmux session manager for LLM development tools with health monitoring, auto-restart, and WebSocket API.
+A modern tmux session manager for LLM development tools with health monitoring, restart policies, and WebSocket API.
 
 ## Why Taskmux?
 
@@ -134,7 +134,8 @@ stop_grace_period = 10
 command = "celery -A myapp worker -l info"
 cwd = "apps/api"
 depends_on = ["db"]
-max_restarts = 3
+restart_policy = "always"
+max_restarts = 10
 restart_backoff = 3.0
 
 [tasks.web]
@@ -173,46 +174,49 @@ taskmux start storybook          # Start a manual task
 ## Commands
 
 ```bash
-# Session
-taskmux start                    # Start all auto_start tasks
-taskmux start <task>             # Start a single task
-taskmux stop                     # Stop all tasks (C-c → SIGTERM → SIGKILL)
-taskmux stop <task>              # Stop a single task (signal escalation)
+# Session lifecycle
+taskmux start                    # Start all auto_start tasks in dependency order
+taskmux start <task> [task2...]  # Start specific tasks
+taskmux start -m                 # Start + stay in foreground monitoring health/restarting
+taskmux stop                     # Stop all (C-c → SIGTERM → SIGKILL), prevents auto-restart
+taskmux stop <task> [task2...]   # Stop specific tasks
 taskmux restart                  # Restart all tasks
-taskmux restart <task>           # Restart a single task
-taskmux status                   # Show session status
-taskmux list                     # List tasks with health indicators
+taskmux restart <task> [task2...] # Restart specific tasks, re-enables auto-restart
 
-# Tasks
-taskmux kill <task>              # Hard-kill a task (destroys window)
-taskmux add <task> "<command>"   # Add task to config
-taskmux remove <task>            # Remove task from config
-taskmux inspect <task>           # JSON task state (pid, command, health)
+# Task management
+taskmux kill <task>              # Hard-kill (SIGKILL + destroy window), prevents auto-restart
+taskmux add <task> "<command>"   # Add task to taskmux.toml
+taskmux remove <task>            # Remove task (kills if running)
+taskmux inspect <task>           # JSON state: pid, health, restart_policy, pane info
+
+# Status & health
+taskmux status                   # Session + task overview (aliases: list, ls)
+taskmux health                   # Health check table for all tasks
 
 # Logs
 taskmux logs                     # Interleaved logs from all tasks
-taskmux logs <task>              # Show recent logs for a task
-taskmux logs -f                  # Attach to session (switch windows with tmux keybinds)
-taskmux logs -f <task>           # Follow a task's logs live
+taskmux logs <task>              # Recent logs for a task
+taskmux logs -f [task]           # Follow logs live (colored prefixes)
 taskmux logs -n 200 <task>       # Last N lines
-taskmux logs -g "error"          # Search all tasks
-taskmux logs <task> -g "error"   # Search one task
-taskmux logs <task> -g "error" -C 5  # Grep with context lines
-
-# Init
-taskmux init                     # Interactive project setup
-taskmux init --defaults          # Non-interactive, use defaults
-
-# Monitoring
-taskmux health                   # Health check table
-taskmux watch                    # Watch config for changes, reload on edit
-taskmux daemon --port 8765       # Run with WebSocket API + auto-restart
+taskmux logs -g "error"          # Grep all tasks
+taskmux logs <task> -g "err" -C 5  # Grep one task with context
+
+# Setup & monitoring
+taskmux init                     # Interactive project setup + agent context injection
+taskmux init --defaults          # Non-interactive setup
+taskmux watch                    # Watch taskmux.toml, reload on change
+taskmux daemon --port 8765       # Daemon mode: WebSocket API + health monitoring
 ```
 
-### stop vs kill
+### stop vs kill vs restart
+
+| Command | Signal | Window | Auto-restart |
+|---------|--------|--------|--------------|
+| `stop` | C-c → SIGTERM → SIGKILL (graceful) | Stays alive | Blocked (manually stopped) |
+| `kill` | SIGKILL (immediate) | Destroyed | Blocked (manually stopped) |
+| `restart` | Full stop + restart | Reused | Re-enabled |
 
-- **`stop`** sends C-c, then escalates to SIGTERM → SIGKILL if the process doesn't exit within the grace period. Window stays alive so you can see exit output.
-- **`kill`** kills the process group and destroys the window immediately.
+Both `stop` and `kill` mark the task as **manually stopped**, preventing auto-restart even with `restart_policy = "always"`. Use `restart` or `start` to clear this flag and re-enable auto-restart.
 
 ## Configuration
 
@@ -246,11 +250,13 @@ health_check = "pg_isready -h localhost"
 [tasks.worker]
 command = "celery worker -A myapp"
 depends_on = ["db"]
-max_restarts = 3
+restart_policy = "always"
+max_restarts = 10
 
 [tasks.tailwind]
 command = "npx tailwindcss -w"
 auto_start = false
+restart_policy = "no"
 ```
 
 ### Fields
@@ -270,10 +276,11 @@ auto_start = false
 | `tasks.<name>.health_check` | — | Shell command to check health (exit 0 = healthy) |
 | `tasks.<name>.health_interval` | `10` | Seconds between health checks |
 | `tasks.<name>.health_timeout` | `5` | Seconds before health check times out |
-| `tasks.<name>.health_retries` | `3` | Consecutive failures before "unhealthy" |
+| `tasks.<name>.health_retries` | `3` | Consecutive health failures before triggering a restart |
 | `tasks.<name>.stop_grace_period` | `5` | Seconds to wait after C-c before escalating to SIGTERM |
-| `tasks.<name>.max_restarts` | `5` | Max auto-restarts in daemon mode before giving up (0 = unlimited) |
-| `tasks.<name>.restart_backoff` | `2.0` | Multiplier for restart delay (1s, 2s, 4s, 8s… capped at 60s) |
+| `tasks.<name>.restart_policy` | `"on-failure"` | When to auto-restart: `"no"`, `"on-failure"`, or `"always"` (see below) |
+| `tasks.<name>.max_restarts` | `5` | Max auto-restarts before giving up (resets after 60s healthy) |
+| `tasks.<name>.restart_backoff` | `2.0` | Exponential backoff base for restart delay (1s, 2s, 4s… capped at 60s) |
 | `tasks.<name>.depends_on` | `[]` | Task names that must be healthy before this task starts |
 | `tasks.<name>.hooks.*` | — | Per-task lifecycle hooks (same fields as global) |
 
@@ -285,14 +292,42 @@ Circular dependencies and references to nonexistent tasks are rejected at config
 
 When starting a single task with `taskmux start <task>`, dependencies are not auto-started — you get a warning if they aren't running.
 
+### Restart Policies
+
+Each task has a `restart_policy` that controls automatic restart behavior. Restart policies are enforced by `taskmux start --monitor` and `taskmux daemon`.
+
+| Policy | Behavior |
+|--------|----------|
+| `"no"` | Never auto-restart. Task stays stopped after crash or health failure. |
+| `"on-failure"` | **(default)** Restart on crash (process exits) or after `health_retries` consecutive health check failures. |
+| `"always"` | Restart whenever the task stops, including clean exits. |
+
+**Manual stops override all policies.** Running `taskmux stop` or `taskmux kill` marks the task as manually stopped — it will not auto-restart even with `restart_policy = "always"`. Use `taskmux restart` or `taskmux start` to clear this flag.
+
+**`restart_policy` vs `auto_start`** — these are orthogonal. `auto_start` controls whether a task launches on `taskmux start`. `restart_policy` controls what happens after a running task exits or fails. A task with `auto_start = false` and `restart_policy = "always"` won't start automatically, but once started manually, it will auto-restart on exit.
+
+| `restart_policy` | `auto_start` | Behavior |
+|---|---|---|
+| `"no"` | `true` | Starts with session, never auto-restarts |
+| `"no"` | `false` | Manual start only, never auto-restarts |
+| `"on-failure"` | `true` | Starts with session, restarts on crash/health failure |
+| `"on-failure"` | `false` | Manual start, restarts on crash/health failure once running |
+| `"always"` | `true` | Starts with session, restarts on any exit |
+| `"always"` | `false` | Manual start, restarts on any exit once running |
+
+**Backoff & limits:** When a task keeps failing, restart delays increase exponentially: `restart_backoff ^ attempt` seconds (capped at 60s). After `max_restarts` consecutive restarts, the task is left stopped. The restart counter resets after 60 seconds of healthy uptime.
+
 ### Health Checks
 
 If `health_check` is set, taskmux runs it as a shell command. Exit code 0 means healthy. If not set, taskmux falls back to checking if the tmux pane has a running process (not just a shell prompt).
 
+A task must fail `health_retries` consecutive health checks (default 3) before being considered unhealthy and triggering a restart. If the task becomes healthy again, the failure counter resets.
+
 Health checks are used by:
 - `taskmux health` — shows a table of all task health
 - `taskmux start` — waits for dependencies to be healthy before starting dependents
-- `taskmux daemon` — continuously monitors and auto-restarts unhealthy tasks
+- `taskmux start --monitor` — continuously monitors and auto-restarts per restart_policy
+- `taskmux daemon` — same as --monitor, plus WebSocket API and config watching
 
 ### Hook Cascade
 
@@ -314,7 +349,7 @@ Taskmux ensures processes are fully stopped before restarting and that orphaned
 
 **Port cleanup** (`start`, `restart`): If `port` is configured, taskmux kills any process listening on that port before starting. This handles orphaned processes from crashed sessions.
 
-**Auto-restart backoff** (daemon mode): When a task keeps crashing, restart delays increase exponentially (`restart_backoff` multiplier, capped at 60s). After `max_restarts` failures, the task is left stopped. The counter resets after 60 seconds of healthy uptime.
+**Auto-restart** (`start --monitor`, `daemon`): Tasks with `restart_policy = "on-failure"` or `"always"` are automatically restarted. Health checks must fail `health_retries` times before triggering a restart. Restart delays increase exponentially (`restart_backoff` base, capped at 60s). After `max_restarts` failures, the task is left stopped. The counter resets after 60 seconds of healthy uptime.
 
 ### Init & Agent Context
 
@@ -336,6 +371,7 @@ Use `--defaults` to skip prompts (CI/automation).
   "name": "api",
   "command": "python manage.py runserver 0.0.0.0:8000",
   "auto_start": true,
+  "restart_policy": "on-failure",
   "cwd": "apps/api",
   "health_check": "curl -sf http://localhost:8000/health",
   "depends_on": ["db"],
@@ -349,16 +385,28 @@ Use `--defaults` to skip prompts (CI/automation).
 }
 ```
 
-## Daemon Mode
+## Monitoring & Auto-restart
+
+### start --monitor (lightweight)
+
+Start tasks and stay in the foreground monitoring health:
+
+```bash
+taskmux start --monitor     # or: taskmux start -m
+```
+
+Checks health every 30 seconds and auto-restarts tasks according to their `restart_policy`. No WebSocket API — just monitoring and restart. Press Ctrl+C to stop monitoring (tasks keep running).
+
+### Daemon Mode (full)
 
-Run as a background daemon with WebSocket API and auto-restart with exponential backoff:
+Run as a background daemon with WebSocket API, config watching, and auto-restart:
 
 ```bash
 taskmux daemon              # Default port 8765
 taskmux daemon --port 9000  # Custom port
 ```
 
-The daemon monitors task health every 30 seconds. Unhealthy tasks are restarted with exponential backoff (controlled by `restart_backoff` and `max_restarts`). Tasks that stay healthy for 60+ seconds have their restart counter reset.
+The daemon monitors task health every 30 seconds. Tasks are restarted per their `restart_policy` with exponential backoff (controlled by `restart_backoff` and `max_restarts`). Tasks that stay healthy for 60+ seconds have their restart counter reset. Config file changes are detected and applied automatically.
 
 WebSocket API:
 

{taskmux-0.2.7 → taskmux-0.3.0}/README.md

@@ -1,6 +1,6 @@
 # Taskmux
 
-A modern tmux session manager for LLM development tools with health monitoring, auto-restart, and WebSocket API.
+A modern tmux session manager for LLM development tools with health monitoring, restart policies, and WebSocket API.
 
 ## Why Taskmux?
 
@@ -99,7 +99,8 @@ stop_grace_period = 10
 command = "celery -A myapp worker -l info"
 cwd = "apps/api"
 depends_on = ["db"]
-max_restarts = 3
+restart_policy = "always"
+max_restarts = 10
 restart_backoff = 3.0
 
 [tasks.web]
@@ -138,46 +139,49 @@ taskmux start storybook          # Start a manual task
 ## Commands
 
 ```bash
-# Session
-taskmux start                    # Start all auto_start tasks
-taskmux start <task>             # Start a single task
-taskmux stop                     # Stop all tasks (C-c → SIGTERM → SIGKILL)
-taskmux stop <task>              # Stop a single task (signal escalation)
+# Session lifecycle
+taskmux start                    # Start all auto_start tasks in dependency order
+taskmux start <task> [task2...]  # Start specific tasks
+taskmux start -m                 # Start + stay in foreground monitoring health/restarting
+taskmux stop                     # Stop all (C-c → SIGTERM → SIGKILL), prevents auto-restart
+taskmux stop <task> [task2...]   # Stop specific tasks
 taskmux restart                  # Restart all tasks
-taskmux restart <task>           # Restart a single task
-taskmux status                   # Show session status
-taskmux list                     # List tasks with health indicators
+taskmux restart <task> [task2...] # Restart specific tasks, re-enables auto-restart
 
-# Tasks
-taskmux kill <task>              # Hard-kill a task (destroys window)
-taskmux add <task> "<command>"   # Add task to config
-taskmux remove <task>            # Remove task from config
-taskmux inspect <task>           # JSON task state (pid, command, health)
+# Task management
+taskmux kill <task>              # Hard-kill (SIGKILL + destroy window), prevents auto-restart
+taskmux add <task> "<command>"   # Add task to taskmux.toml
+taskmux remove <task>            # Remove task (kills if running)
+taskmux inspect <task>           # JSON state: pid, health, restart_policy, pane info
+
+# Status & health
+taskmux status                   # Session + task overview (aliases: list, ls)
+taskmux health                   # Health check table for all tasks
 
 # Logs
 taskmux logs                     # Interleaved logs from all tasks
-taskmux logs <task>              # Show recent logs for a task
-taskmux logs -f                  # Attach to session (switch windows with tmux keybinds)
-taskmux logs -f <task>           # Follow a task's logs live
+taskmux logs <task>              # Recent logs for a task
+taskmux logs -f [task]           # Follow logs live (colored prefixes)
 taskmux logs -n 200 <task>       # Last N lines
-taskmux logs -g "error"          # Search all tasks
-taskmux logs <task> -g "error"   # Search one task
-taskmux logs <task> -g "error" -C 5  # Grep with context lines
-
-# Init
-taskmux init                     # Interactive project setup
-taskmux init --defaults          # Non-interactive, use defaults
-
-# Monitoring
-taskmux health                   # Health check table
-taskmux watch                    # Watch config for changes, reload on edit
-taskmux daemon --port 8765       # Run with WebSocket API + auto-restart
+taskmux logs -g "error"          # Grep all tasks
+taskmux logs <task> -g "err" -C 5  # Grep one task with context
+
+# Setup & monitoring
+taskmux init                     # Interactive project setup + agent context injection
+taskmux init --defaults          # Non-interactive setup
+taskmux watch                    # Watch taskmux.toml, reload on change
+taskmux daemon --port 8765       # Daemon mode: WebSocket API + health monitoring
 ```
 
-### stop vs kill
+### stop vs kill vs restart
+
+| Command | Signal | Window | Auto-restart |
+|---------|--------|--------|--------------|
+| `stop` | C-c → SIGTERM → SIGKILL (graceful) | Stays alive | Blocked (manually stopped) |
+| `kill` | SIGKILL (immediate) | Destroyed | Blocked (manually stopped) |
+| `restart` | Full stop + restart | Reused | Re-enabled |
 
-- **`stop`** sends C-c, then escalates to SIGTERM → SIGKILL if the process doesn't exit within the grace period. Window stays alive so you can see exit output.
-- **`kill`** kills the process group and destroys the window immediately.
+Both `stop` and `kill` mark the task as **manually stopped**, preventing auto-restart even with `restart_policy = "always"`. Use `restart` or `start` to clear this flag and re-enable auto-restart.
 
 ## Configuration
 
@@ -211,11 +215,13 @@ health_check = "pg_isready -h localhost"
 [tasks.worker]
 command = "celery worker -A myapp"
 depends_on = ["db"]
-max_restarts = 3
+restart_policy = "always"
+max_restarts = 10
 
 [tasks.tailwind]
 command = "npx tailwindcss -w"
 auto_start = false
+restart_policy = "no"
 ```
 
 ### Fields
@@ -235,10 +241,11 @@ auto_start = false
 | `tasks.<name>.health_check` | — | Shell command to check health (exit 0 = healthy) |
 | `tasks.<name>.health_interval` | `10` | Seconds between health checks |
 | `tasks.<name>.health_timeout` | `5` | Seconds before health check times out |
-| `tasks.<name>.health_retries` | `3` | Consecutive failures before "unhealthy" |
+| `tasks.<name>.health_retries` | `3` | Consecutive health failures before triggering a restart |
 | `tasks.<name>.stop_grace_period` | `5` | Seconds to wait after C-c before escalating to SIGTERM |
-| `tasks.<name>.max_restarts` | `5` | Max auto-restarts in daemon mode before giving up (0 = unlimited) |
-| `tasks.<name>.restart_backoff` | `2.0` | Multiplier for restart delay (1s, 2s, 4s, 8s… capped at 60s) |
+| `tasks.<name>.restart_policy` | `"on-failure"` | When to auto-restart: `"no"`, `"on-failure"`, or `"always"` (see below) |
+| `tasks.<name>.max_restarts` | `5` | Max auto-restarts before giving up (resets after 60s healthy) |
+| `tasks.<name>.restart_backoff` | `2.0` | Exponential backoff base for restart delay (1s, 2s, 4s… capped at 60s) |
 | `tasks.<name>.depends_on` | `[]` | Task names that must be healthy before this task starts |
 | `tasks.<name>.hooks.*` | — | Per-task lifecycle hooks (same fields as global) |
 
@@ -250,14 +257,42 @@ Circular dependencies and references to nonexistent tasks are rejected at config
 
 When starting a single task with `taskmux start <task>`, dependencies are not auto-started — you get a warning if they aren't running.
 
+### Restart Policies
+
+Each task has a `restart_policy` that controls automatic restart behavior. Restart policies are enforced by `taskmux start --monitor` and `taskmux daemon`.
+
+| Policy | Behavior |
+|--------|----------|
+| `"no"` | Never auto-restart. Task stays stopped after crash or health failure. |
+| `"on-failure"` | **(default)** Restart on crash (process exits) or after `health_retries` consecutive health check failures. |
+| `"always"` | Restart whenever the task stops, including clean exits. |
+
+**Manual stops override all policies.** Running `taskmux stop` or `taskmux kill` marks the task as manually stopped — it will not auto-restart even with `restart_policy = "always"`. Use `taskmux restart` or `taskmux start` to clear this flag.
+
+**`restart_policy` vs `auto_start`** — these are orthogonal. `auto_start` controls whether a task launches on `taskmux start`. `restart_policy` controls what happens after a running task exits or fails. A task with `auto_start = false` and `restart_policy = "always"` won't start automatically, but once started manually, it will auto-restart on exit.
+
+| `restart_policy` | `auto_start` | Behavior |
+|---|---|---|
+| `"no"` | `true` | Starts with session, never auto-restarts |
+| `"no"` | `false` | Manual start only, never auto-restarts |
+| `"on-failure"` | `true` | Starts with session, restarts on crash/health failure |
+| `"on-failure"` | `false` | Manual start, restarts on crash/health failure once running |
+| `"always"` | `true` | Starts with session, restarts on any exit |
+| `"always"` | `false` | Manual start, restarts on any exit once running |
+
+**Backoff & limits:** When a task keeps failing, restart delays increase exponentially: `restart_backoff ^ attempt` seconds (capped at 60s). After `max_restarts` consecutive restarts, the task is left stopped. The restart counter resets after 60 seconds of healthy uptime.
+
 ### Health Checks
 
 If `health_check` is set, taskmux runs it as a shell command. Exit code 0 means healthy. If not set, taskmux falls back to checking if the tmux pane has a running process (not just a shell prompt).
 
+A task must fail `health_retries` consecutive health checks (default 3) before being considered unhealthy and triggering a restart. If the task becomes healthy again, the failure counter resets.
+
 Health checks are used by:
 - `taskmux health` — shows a table of all task health
 - `taskmux start` — waits for dependencies to be healthy before starting dependents
-- `taskmux daemon` — continuously monitors and auto-restarts unhealthy tasks
+- `taskmux start --monitor` — continuously monitors and auto-restarts per restart_policy
+- `taskmux daemon` — same as --monitor, plus WebSocket API and config watching
 
 ### Hook Cascade
 
@@ -279,7 +314,7 @@ Taskmux ensures processes are fully stopped before restarting and that orphaned
 
 **Port cleanup** (`start`, `restart`): If `port` is configured, taskmux kills any process listening on that port before starting. This handles orphaned processes from crashed sessions.
 
-**Auto-restart backoff** (daemon mode): When a task keeps crashing, restart delays increase exponentially (`restart_backoff` multiplier, capped at 60s). After `max_restarts` failures, the task is left stopped. The counter resets after 60 seconds of healthy uptime.
+**Auto-restart** (`start --monitor`, `daemon`): Tasks with `restart_policy = "on-failure"` or `"always"` are automatically restarted. Health checks must fail `health_retries` times before triggering a restart. Restart delays increase exponentially (`restart_backoff` base, capped at 60s). After `max_restarts` failures, the task is left stopped. The counter resets after 60 seconds of healthy uptime.
 
 ### Init & Agent Context
 
@@ -301,6 +336,7 @@ Use `--defaults` to skip prompts (CI/automation).
   "name": "api",
   "command": "python manage.py runserver 0.0.0.0:8000",
   "auto_start": true,
+  "restart_policy": "on-failure",
   "cwd": "apps/api",
   "health_check": "curl -sf http://localhost:8000/health",
   "depends_on": ["db"],
@@ -314,16 +350,28 @@ Use `--defaults` to skip prompts (CI/automation).
 }
 ```
 
-## Daemon Mode
+## Monitoring & Auto-restart
+
+### start --monitor (lightweight)
+
+Start tasks and stay in the foreground monitoring health:
+
+```bash
+taskmux start --monitor     # or: taskmux start -m
+```
+
+Checks health every 30 seconds and auto-restarts tasks according to their `restart_policy`. No WebSocket API — just monitoring and restart. Press Ctrl+C to stop monitoring (tasks keep running).
+
+### Daemon Mode (full)
 
-Run as a background daemon with WebSocket API and auto-restart with exponential backoff:
+Run as a background daemon with WebSocket API, config watching, and auto-restart:
 
 ```bash
 taskmux daemon              # Default port 8765
 taskmux daemon --port 9000  # Custom port
 ```
 
-The daemon monitors task health every 30 seconds. Unhealthy tasks are restarted with exponential backoff (controlled by `restart_backoff` and `max_restarts`). Tasks that stay healthy for 60+ seconds have their restart counter reset.
+The daemon monitors task health every 30 seconds. Tasks are restarted per their `restart_policy` with exponential backoff (controlled by `restart_backoff` and `max_restarts`). Tasks that stay healthy for 60+ seconds have their restart counter reset. Config file changes are detected and applied automatically.
 
 WebSocket API:
 

{taskmux-0.2.7 → taskmux-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskmux"
-version = "0.2.7"
+version = "0.3.0"
 description = "Modern tmux-based task manager for LLM development tools"
 readme = "README.md"
 license-file = "LICENSE"

{taskmux-0.2.7 → taskmux-0.3.0}/taskmux/cli.py

@@ -16,8 +16,14 @@ from .tmux_manager import TmuxManager
 
 app = typer.Typer(
     name="taskmux",
-    help="Modern tmux development environment manager with health monitoring and auto-restart",
-    epilog="Uses libtmux API with health monitoring and daemon capabilities.",
+    help=(
+        "Tmux session manager for development environments.\n\n"
+        "Reads task definitions from taskmux.toml, manages tmux sessions/windows, "
+        "provides health monitoring, restart policies (no/on-failure/always), "
+        "dependency ordering, lifecycle hooks, and a WebSocket API.\n\n"
+        "Quick start: taskmux init → edit taskmux.toml → taskmux start"
+    ),
+    epilog="Docs: https://github.com/nc9/taskmux",
     rich_markup_mode="rich",
 )
 
@@ -49,15 +55,32 @@ class TaskmuxCLI:
 def init(
     defaults: bool = typer.Option(False, "--defaults", help="Accept all defaults"),
 ):
-    """Initialize taskmux config in current directory."""
+    """Initialize taskmux config in current directory.
+
+    Creates taskmux.toml with session name (defaults to directory name).
+    Detects installed AI coding agents (Claude, Codex, OpenCode) and injects
+    taskmux usage instructions into their context files.
+    Use --defaults to skip interactive prompts.
+    """
     initProject(defaults=defaults)
 
 
 @app.command()
 def start(
     tasks: list[str] = typer.Argument(None, help="Task names (omit for all)"),  # noqa: B008
+    monitor: bool = typer.Option(  # noqa: B008
+        False, "-m", "--monitor", help="Stay running, auto-restart per restart_policy"
+    ),
 ):
-    """Start tasks (all if none specified)."""
+    """Start tasks (all auto_start tasks if none specified).
+
+    Starts tasks in dependency order, waiting for each dependency's health check
+    to pass before starting dependents. With --monitor, stays in the foreground
+    and auto-restarts tasks according to their restart_policy (no/on-failure/always),
+    respecting health_retries, max_restarts, and exponential backoff.
+    """
+    import time
+
     cli = TaskmuxCLI()
     if tasks:
         for task in tasks:
@@ -65,12 +88,26 @@ def start(
     else:
         cli.tmux.start_all()
 
+    if monitor:
+        console.print("Monitoring tasks (Ctrl+C to stop)...")
+        try:
+            while True:
+                time.sleep(30)
+                cli.tmux.auto_restart_tasks()
+        except KeyboardInterrupt:
+            console.print("\nStopped monitoring")
+
 
 @app.command()
 def stop(
     tasks: list[str] = typer.Argument(None, help="Task names (omit for all)"),  # noqa: B008
 ):
-    """Stop tasks (all if none specified)."""
+    """Stop tasks (all if none specified).
+
+    Uses signal escalation: C-c → SIGTERM → SIGKILL. Waits stop_grace_period
+    seconds (default 5) after C-c before escalating. Stopped tasks are marked
+    as manually stopped and will not be auto-restarted even with restart_policy="always".
+    """
     cli = TaskmuxCLI()
     if tasks:
         for task in tasks:
@@ -83,7 +120,11 @@ def stop(
 def restart(
     tasks: list[str] = typer.Argument(None, help="Task names (omit for all)"),  # noqa: B008
 ):
-    """Restart tasks (all if none specified)."""
+    """Restart tasks (all if none specified).
+
+    Full stop with signal escalation, port cleanup, then restart.
+    Clears the manually-stopped flag so auto-restart policies resume.
+    """
     cli = TaskmuxCLI()
     if tasks:
         for task in tasks:
@@ -96,7 +137,11 @@ def restart(
 def kill(
     task: str = typer.Argument(..., help="Task name to kill"),
 ):
-    """Kill a specific task."""
+    """Kill a specific task (SIGKILL + destroy window).
+
+    Unlike stop, kill is immediate with no grace period. The tmux window is
+    destroyed. The task is marked as manually stopped (no auto-restart).
+    """
     cli = TaskmuxCLI()
     cli.tmux.kill_task(task)
 
@@ -109,7 +154,11 @@ def logs(
     grep: str | None = typer.Option(None, "-g", "--grep", help="Filter logs by pattern"),
     context: int = typer.Option(3, "-C", "--context", help="Context lines around grep matches"),
 ):
-    """Show logs for a task, or all tasks if none specified."""
+    """Show logs for a task, or interleaved logs from all tasks.
+
+    Without -f, prints recent output. With -f, follows logs live with colored
+    task prefixes. Use -g to grep across tasks and -C for context lines.
+    """
     cli = TaskmuxCLI()
     cli.tmux.show_logs(task, follow, lines, grep=grep, context=context)
 
@@ -118,7 +167,11 @@ def logs(
 def inspect(
     task: str = typer.Argument(..., help="Task name to inspect"),
 ):
-    """Inspect task state as JSON."""
+    """Inspect task state as JSON.
+
+    Returns detailed info: name, command, restart_policy, running/healthy status,
+    pid, pane command, cwd, window/pane IDs, health_check, and depends_on.
+    """
     cli = TaskmuxCLI()
     data = cli.tmux.inspect_task(task)
     console.print_json(json.dumps(data))
@@ -134,7 +187,7 @@ def add(
         None, "--depends-on", help="Dependency task names"
     ),
 ):
-    """Add a new task."""
+    """Add a new task to taskmux.toml."""
     addTask(None, task, command, cwd=cwd, health_check=health_check, depends_on=depends_on)
     console.print(f"Added task '{task}': {command}")
 
@@ -143,7 +196,7 @@ def add(
 def remove(
     task: str = typer.Argument(..., help="Task name to remove"),
 ):
-    """Remove a task."""
+    """Remove a task from taskmux.toml (kills it first if running)."""
     cli = TaskmuxCLI()
 
     if cli.tmux.session_exists():
@@ -157,7 +210,11 @@ def remove(
 
 
 def _status():
-    """Show session and task status."""
+    """Show session and task status.
+
+    Lists all tasks with health indicators, running state, ports, restart policy
+    (if non-default), working directory, and dependencies. Aliases: list, ls.
+    """
     cli = TaskmuxCLI()
     cli.tmux.list_tasks()
 
@@ -169,7 +226,11 @@ app.command(name="ls", hidden=True)(_status)
 
 @app.command()
 def health():
-    """Check health of all tasks."""
+    """Check health of all tasks.
+
+    Runs each task's health_check command (or falls back to pane-alive check).
+    Displays a table with health status for every configured task.
+    """
     cli = TaskmuxCLI()
 
     if not cli.tmux.session_exists():
@@ -200,7 +261,11 @@ def health():
 
 @app.command()
 def watch():
-    """Watch config file for changes."""
+    """Watch taskmux.toml for changes and reload on edit.
+
+    Stays in the foreground. When the config file changes, reloads it and
+    restarts affected tasks.
+    """
     cli = TaskmuxCLI()
     watcher = SimpleConfigWatcher(cli)
     watcher.watch_config()
@@ -210,7 +275,12 @@ def watch():
 def daemon(
     port: int = typer.Option(8765, "--port", help="WebSocket API port"),
 ):
-    """Run in daemon mode with API."""
+    """Run in daemon mode with WebSocket API and health monitoring.
+
+    Monitors task health every 30s and auto-restarts per restart_policy with
+    exponential backoff. Watches config for changes. Exposes a WebSocket API
+    for status, restart, kill, and logs commands.
+    """
     d = TaskmuxDaemon(api_port=port)
     asyncio.run(d.start())
 

{taskmux-0.2.7 → taskmux-0.3.0}/taskmux/config.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import tomlkit
 
-from .models import HookConfig, TaskConfig, TaskmuxConfig
+from .models import HookConfig, RestartPolicy, TaskConfig, TaskmuxConfig
 
 CONFIG_FILENAME = "taskmux.toml"
 
@@ -122,6 +122,8 @@ def writeConfig(path: Path | None, config: TaskmuxConfig) -> Path:
             inner.add("max_restarts", task_cfg.max_restarts)
         if task_cfg.restart_backoff != 2.0:
             inner.add("restart_backoff", task_cfg.restart_backoff)
+        if task_cfg.restart_policy != RestartPolicy.ON_FAILURE:
+            inner.add("restart_policy", str(task_cfg.restart_policy))
         if task_cfg.depends_on:
             inner.add("depends_on", task_cfg.depends_on)
         # Task-level hooks

{taskmux-0.2.7 → taskmux-0.3.0}/taskmux/daemon.py

@@ -39,26 +39,6 @@ class ConfigWatcher(FileSystemEventHandler):
                 self.taskmux_cli.handle_config_reload()
 
 
-class RestartTracker:
-    """Tracks per-task restart counts and timestamps for backoff."""
-
-    def __init__(self) -> None:
-        self._data: dict[str, dict[str, float]] = {}
-
-    def get(self, task_name: str) -> dict[str, float]:
-        return self._data.get(task_name, {"count": 0, "last": 0.0})
-
-    def record(self, task_name: str) -> None:
-        info = self.get(task_name)
-        self._data[task_name] = {
-            "count": info["count"] + 1,
-            "last": time.time(),
-        }
-
-    def reset(self, task_name: str) -> None:
-        self._data.pop(task_name, None)
-
-
 class TaskmuxDaemon:
     """Daemon mode for Taskmux with enhanced monitoring and API"""
 
@@ -71,7 +51,6 @@ class TaskmuxDaemon:
         self.health_check_interval = 30
         self.health_check_task: asyncio.Task | None = None
         self.websocket_clients: set = set()
-        self.restart_tracker = RestartTracker()
         self.logger = self._setup_logging()
 
         signal.signal(signal.SIGINT, self._signal_handler)
@@ -161,40 +140,9 @@ class TaskmuxDaemon:
                 await asyncio.sleep(5)
 
     def _auto_restart_with_backoff(self) -> None:
-        """Auto-restart unhealthy tasks with exponential backoff."""
+        """Auto-restart tasks using TmuxManager's restart policy logic."""
         assert self.cli is not None
-        now = time.time()
-
-        for task_name, task_cfg in self.cli.config.tasks.items():
-            healthy = self.cli.tmux.check_task_health(task_name)
-
-            if healthy:
-                # Reset tracker if healthy for >60s
-                info = self.restart_tracker.get(task_name)
-                if info["count"] > 0 and now - info["last"] > 60:
-                    self.restart_tracker.reset(task_name)
-                continue
-
-            # Skip if not previously healthy (avoid restart loop on first check)
-            prev_health = self.cli.tmux.task_health.get(task_name, {}).get("healthy", True)
-            if not prev_health:
-                info = self.restart_tracker.get(task_name)
-
-                # Check max_restarts
-                if task_cfg.max_restarts and info["count"] >= task_cfg.max_restarts:
-                    self.logger.warning(
-                        f"Task '{task_name}' exceeded max restarts ({task_cfg.max_restarts})"
-                    )
-                    continue
-
-                # Check backoff delay
-                delay = min(task_cfg.restart_backoff ** info["count"], 60)
-                if info["last"] and now - info["last"] < delay:
-                    continue
-
-            self.logger.info(f"Auto-restarting unhealthy task: {task_name}")
-            self.cli.tmux.restart_task(task_name)
-            self.restart_tracker.record(task_name)
+        self.cli.tmux.auto_restart_tasks()
 
     async def _start_api_server(self) -> None:
         """Start WebSocket API server"""

{taskmux-0.2.7 → taskmux-0.3.0}/taskmux/models.py

@@ -1,10 +1,19 @@
 """Pydantic models for Taskmux configuration."""
 
 import warnings
+from enum import StrEnum
 
 from pydantic import BaseModel, ConfigDict, model_validator
 
 
+class RestartPolicy(StrEnum):
+    """Docker-style restart policy for tasks."""
+
+    NO = "no"
+    ON_FAILURE = "on-failure"
+    ALWAYS = "always"
+
+
 class _StrictConfig(BaseModel):
     """Base config: frozen, warns on unknown keys."""
 
@@ -45,6 +54,7 @@ class TaskConfig(_StrictConfig):
     stop_grace_period: int = 5
     max_restarts: int = 5
     restart_backoff: float = 2.0
+    restart_policy: RestartPolicy = RestartPolicy.ON_FAILURE
     depends_on: list[str] = []
     hooks: HookConfig = HookConfig()
 

{taskmux-0.2.7 → taskmux-0.3.0}/taskmux/tmux_manager.py

@@ -15,13 +15,52 @@ from rich.console import Console
 from rich.markup import escape
 
 from .hooks import runHook
-from .models import TaskmuxConfig
+from .models import RestartPolicy, TaskmuxConfig
 
 SHELL_NAMES = frozenset(("bash", "zsh", "sh", "fish"))
 
 TASK_COLORS = ["cyan", "green", "yellow", "magenta", "blue", "red"]
 
 
+class RestartTracker:
+    """Tracks per-task restart counts, health failures, and manual-stop state."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, dict[str, float]] = {}
+        self._consecutive_failures: dict[str, int] = {}
+        self._manually_stopped: set[str] = set()
+
+    def get(self, task_name: str) -> dict[str, float]:
+        return self._data.get(task_name, {"count": 0, "last": 0.0})
+
+    def record(self, task_name: str) -> None:
+        info = self.get(task_name)
+        self._data[task_name] = {
+            "count": info["count"] + 1,
+            "last": time.time(),
+        }
+
+    def reset(self, task_name: str) -> None:
+        self._data.pop(task_name, None)
+
+    def record_health_failure(self, task_name: str) -> int:
+        count = self._consecutive_failures.get(task_name, 0) + 1
+        self._consecutive_failures[task_name] = count
+        return count
+
+    def reset_health_failures(self, task_name: str) -> None:
+        self._consecutive_failures.pop(task_name, None)
+
+    def mark_manually_stopped(self, task_name: str) -> None:
+        self._manually_stopped.add(task_name)
+
+    def clear_manually_stopped(self, task_name: str) -> None:
+        self._manually_stopped.discard(task_name)
+
+    def is_manually_stopped(self, task_name: str) -> bool:
+        return task_name in self._manually_stopped
+
+
 def _find_new_lines(current: list[str], prev_tail: list[str]) -> list[str]:
     """Return lines in current that are new since prev_tail."""
     if not prev_tail:
@@ -43,6 +82,7 @@ class TmuxManager:
         self.server = libtmux.Server()
         self.session: libtmux.Session | None = None
         self.task_health: dict = {}
+        self.restart_tracker = RestartTracker()
         self._refresh_session()
 
     def _refresh_session(self) -> None:
@@ -232,6 +272,7 @@ class TmuxManager:
 
     def start_task(self, task_name: str) -> None:
         """Start a single task (create window + send command)."""
+        self.restart_tracker.clear_manually_stopped(task_name)
         if task_name not in self.config.tasks:
             print(f"Task '{task_name}' not found in config")
             return
@@ -286,6 +327,7 @@ class TmuxManager:
 
     def stop_task(self, task_name: str) -> None:
         """Graceful stop with signal escalation: C-c → SIGTERM → SIGKILL."""
+        self.restart_tracker.mark_manually_stopped(task_name)
         if not self.session_exists():
             print(f"Session '{self.config.name}' doesn't exist")
             return
@@ -396,6 +438,9 @@ class TmuxManager:
 
     def stop_all(self) -> None:
         """Stop all tasks with signal escalation then kill session."""
+        for task_name in self.config.tasks:
+            self.restart_tracker.mark_manually_stopped(task_name)
+
         if not self.session_exists():
             print("No session running")
             return
@@ -456,6 +501,7 @@ class TmuxManager:
 
     def restart_task(self, task_name: str) -> None:
         """Restart a specific task with full stop escalation."""
+        self.restart_tracker.clear_manually_stopped(task_name)
         if not self.session_exists():
             print(f"Session '{self.config.name}' doesn't exist. Run 'taskmux start' first.")
             return
@@ -508,6 +554,7 @@ class TmuxManager:
 
     def kill_task(self, task_name: str) -> None:
         """Kill a specific task (process group + window)."""
+        self.restart_tracker.mark_manually_stopped(task_name)
         if not self.session_exists():
             print(f"Session '{self.config.name}' doesn't exist")
             return
@@ -534,6 +581,7 @@ class TmuxManager:
             "name": task_name,
             "command": task_cfg.command,
             "auto_start": task_cfg.auto_start,
+            "restart_policy": str(task_cfg.restart_policy),
             "cwd": task_cfg.cwd,
             "health_check": task_cfg.health_check,
             "depends_on": task_cfg.depends_on,
@@ -717,6 +765,8 @@ class TmuxManager:
             extras = ""
             if task_cfg.cwd:
                 extras += f" cwd={task_cfg.cwd}"
+            if task_cfg.restart_policy != RestartPolicy.ON_FAILURE:
+                extras += f" restart={task_cfg.restart_policy}"
             if task_cfg.depends_on:
                 extras += f" deps=[{','.join(task_cfg.depends_on)}]"
             line = f"{health_icon} {status_text:8} {task_name:15}{port:7} {task_cfg.command}"
@@ -735,17 +785,68 @@ class TmuxManager:
 
         return is_healthy
 
-    def auto_restart_unhealthy_tasks(self) -> None:
-        """Auto-restart tasks that have become unhealthy"""
+    def auto_restart_tasks(self) -> None:
+        """Auto-restart tasks based on restart_policy, health_retries, max_restarts, and backoff."""
         if not self.session_exists():
             return
 
-        for task_name in self.config.tasks:
-            if not self.check_task_health(task_name):
-                prev_health = self.task_health.get(task_name, {}).get("healthy", True)
-                if prev_health:
-                    print(f"Auto-restarting unhealthy task: {task_name}")
-                    self.restart_task(task_name)
+        now = time.time()
+
+        for task_name, task_cfg in self.config.tasks.items():
+            if task_cfg.restart_policy == RestartPolicy.NO:
+                continue
+            if self.restart_tracker.is_manually_stopped(task_name):
+                continue
+
+            healthy = self.check_task_health(task_name)
+            pane_alive = self._is_pane_alive(task_name)
+
+            if healthy:
+                self.restart_tracker.reset_health_failures(task_name)
+                # Reset restart tracker after 60s stable
+                info = self.restart_tracker.get(task_name)
+                if info["count"] > 0 and now - info["last"] > 60:
+                    self.restart_tracker.reset(task_name)
+                continue
+
+            # "on-failure": restart on crash or health_retries exceeded
+            # "always": restart whenever pane is dead (even clean exit)
+            should_restart = False
+
+            if not pane_alive:
+                # Process exited — restart for both on-failure and always
+                should_restart = True
+            elif task_cfg.restart_policy == RestartPolicy.ON_FAILURE:
+                # Pane alive but health check failing — count consecutive failures
+                failures = self.restart_tracker.record_health_failure(task_name)
+                if failures >= task_cfg.health_retries:
+                    should_restart = True
+            elif task_cfg.restart_policy == RestartPolicy.ALWAYS:
+                failures = self.restart_tracker.record_health_failure(task_name)
+                if failures >= task_cfg.health_retries:
+                    should_restart = True
+
+            if not should_restart:
+                continue
+
+            # Check max_restarts limit
+            info = self.restart_tracker.get(task_name)
+            if task_cfg.max_restarts and info["count"] >= task_cfg.max_restarts:
+                continue
+
+            # Check backoff delay
+            delay = min(task_cfg.restart_backoff ** info["count"], 60)
+            if info["last"] and now - info["last"] < delay:
+                continue
+
+            print(f"Auto-restarting task: {task_name}")
+            self.restart_task(task_name)
+            self.restart_tracker.record(task_name)
+            self.restart_tracker.reset_health_failures(task_name)
+
+    def auto_restart_unhealthy_tasks(self) -> None:
+        """Deprecated: use auto_restart_tasks() instead."""
+        self.auto_restart_tasks()
 
     def stop_session(self) -> None:
         """Stop the entire tmux session (legacy, wraps stop_all)."""