From 45ea5beba624878b41d6aa0df43c12ae3af562bc Mon Sep 17 00:00:00 2001
From: typebasedio <typebasedio@pm.me>
Date: Fri, 8 May 2026 14:06:02 -0400
Subject: [PATCH] docs(v0.5.3): persistent session mode reference

---
 docs/commands.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/docs/commands.md b/docs/commands.md
index bdad0f0..d9ec3d2 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -470,3 +470,107 @@ The metadata write lock still serializes all ctask-owned file writes regardless
 | 1 | General error (multiple matches, not found, invalid args, doctor failure) |
 | 2 | Missing required argument |
 | 127 | Agent command not found |
+
+---
+
+## Persistent Session Mode (tmux)
+
+ctask v0.5.3+ supports an opt-in persistent session mode where workspace entry
+runs inside a deterministic per-workspace tmux session. Multiple terminals
+(local + SSH) attach to the same session, the agent and shell state survive
+terminal disconnection, and the v0.4 lifecycle protections continue to apply
+with one ctask process owning the workspace lifecycle while terminal
+connections come and go.
+
+### Enabling persistent mode
+
+```bash
+export CTASK_SESSION_MODE=persistent   # in ~/.bashrc or equivalent
+```
+
+When unset or set to `direct`, ctask behaves as in v0.5.2 (no behavior change).
+
+Persistent mode requires:
+- tmux 3.0+ on PATH (install via `apt install tmux`, `brew install tmux`, `pacman -S tmux`, or `dnf install tmux`)
+- An interactive terminal (over SSH, use `ssh -t`)
+- Not running inside an existing tmux session
+- A Unix-like host or WSL — native Windows is not supported (use WSL)
+
+### Three entry paths
+
+When you run a persistent-mode entry command (`new`, `resume`, `last`, `open`, or `attach`), ctask picks one of three paths:
+
+1. **Owner-create** — no tmux session exists for this workspace yet. The command behaves like the direct path but launches the agent inside a new tmux session named `ctask-<category>-<slug>-<hash6>`.
+2. **Passive reattach** — a tmux session exists and a fresh local lease is heartbeating. The command attaches the user's terminal to the existing session and exits when the user detaches. No lease writes, no manifest, no finalize — the original ctask owner is still managing the workspace.
+3. **Adopted reattach** — a tmux session exists but the lease is missing, stale, or from another host (the original owner died). The command transfers ownership to itself, captures a fresh start manifest, starts heartbeating, attaches the terminal, and runs finalize when the session ends.
+
+### `ctask attach <workspace>`
+
+`ctask attach` always uses tmux regardless of `CTASK_SESSION_MODE`. Useful when you have not enabled persistent mode globally but want tmux for one workspace, or when shell scripts need unambiguous behavior.
+
+```bash
+ctask attach promptvolley-v3
+```
+
+The same three paths apply.
+
+### `--direct` bypass flag
+
+`new`, `resume`, `last`, and `open` accept `--direct` to bypass persistent mode for one invocation. When a persistent tmux session exists for the workspace, ctask prompts:
+
+```
+A persistent tmux session exists for this workspace:
+  ctask-projects-promptvolley-v3-a8f3c2
+
+Opening a direct-mode shell may create conflicting workspace activity.
+The recommended path is:
+  ctask attach promptvolley-v3
+
+Continue with --direct anyway? [y/N]
+```
+
+`--direct` is a no-op under direct mode (allows scripts to use it defensively).
+
+### Doctor
+
+`ctask doctor` reports:
+
+```
+[INFO] Session mode: persistent
+[INFO] tmux found: tmux 3.4 (/usr/bin/tmux)
+```
+
+or, on misconfiguration:
+
+```
+[INFO] Session mode: persistent
+[FAIL] tmux not found on PATH
+       Fix: install tmux 3.0+ (apt/brew/pacman/dnf), or unset CTASK_SESSION_MODE
+```
+
+### Workflow examples
+
+**Local development**
+
+```bash
+export CTASK_SESSION_MODE=persistent
+
+ctask new --project promptvolley-v3
+# -> workspace created, tmux session ctask-projects-promptvolley-v3-a8f3c2 started, attached.
+
+# Detach with Ctrl-B d. Terminal returns; tmux session keeps running.
+
+ctask resume promptvolley-v3
+# -> passive reattach. Same Claude Code session, scrollback intact.
+```
+
+**Remote access via SSH**
+
+```bash
+ssh -t warren-desktop          # -t is required
+ctask resume promptvolley-v3   # -> passive reattach (concurrent with desktop)
+```
+
+### Native Windows note
+
+Persistent mode is not supported on native Windows (PowerShell). Run ctask under WSL and install tmux there.