polish(v0.5.3): v0.4 lease-prompt hint, invocation-name in user-facing commands, smoke-checklist fixes

Three independent v0.5.3 polish items surfaced during manual WSL smoke testing,
bundled into one commit since they're all string/UX touches with no behavior change.

1. v0.4 lease-prompt tightening (`internal/session/{lease,run,run_preflight}.go`,
   `cmd/entry.go`): when ctask is about to enter direct mode on a workspace that
   already has a live tmux session, the "Continue anyway?" prompt now suggests
   `ctask attach <slug>` as the reattach path. Threaded via
   `PreflightOpts.ActiveLeaseHint` / `LaunchOpts.ActiveLeaseHint`; computed in
   `cmd/entry.go::directModeTmuxHint` (best-effort: silent when no tmux on PATH
   or no session for the workspace). Closes the footgun where a user forgot to
   `export CTASK_SESSION_MODE=persistent` in a second terminal and hit the v0.4
   coexistence prompt without realizing tmux passive-reattach was the intended
   path.

2. Invocation-name in user-facing command hints (`cmd/invocation.go` new,
   `cmd/{persistent,entry,resume,doctor}.go`): the binary name printed in
   bypass / restore / "create one with" suggestions now reflects
   `filepath.Base(os.Args[0])` instead of a hard-coded "ctask". Local-build
   PowerShell users running `.\ctask.exe` see `ctask.exe new <ws> --direct`,
   matching what they need to type. Installed contexts continue to see `ctask`.
   Test seam (`invocationNameOverride`) pins the name to "ctask" in unit tests
   so substring assertions stay stable across Go test binary names. Descriptive
   prose ("ctask persistent mode requires...") and the ssh-remote hint
   (`ssh -t <host> ctask <subcmd>`) intentionally keep the literal "ctask" —
   they refer to the program identity / remote invocation, not the local
   command form. Affected tests: `cmd/{persistent,resume}_test.go` tightened to
   check the full `"<binary> <subcmd> <workspace> --direct"` form.

3. Smoke-checklist fixes (`docs/.../2026-05-08-v0.5.3-smoke-test-checklist.md`):
   six issues caught during the run -- S2 now exports CTASK_SESSION_MODE in
   both terminals (previously only WSL-A had it, which routed WSL-B's
   secondary resume through direct mode instead of passive reattach); O3/A2
   tmux-ls expectations corrected (tmux doesn't emit a literal "(detached)"
   token); P2 expected behavior rewritten (passive reattach detach returns to
   prompt immediately -- AttachExisting calls only shell.AttachSession with
   no PollSessionEnd, the owner is responsible for finalize); A1 no longer
   asks for Ctrl-C in WSL-B; A6 path now uses a glob (was hardcoded to the
   checklist's authoring date, broke on v0.5.1 local-time directory naming);
   M1 PATH-hide rewritten to `$HOME/.local/bin` only (was `:/bin` which is a
   symlink to /usr/bin on usrmerge systems, did not hide tmux) and uses
   `command -v` instead of `which` (which is itself in /usr/bin, unreachable
   under the minimal PATH); M3/M4 reordered so the no-workspace verification
   runs after PATH is restored (was silently failing under minimal PATH);
   T1 wording made "substring match" explicit; T2 wording made N/A
   unambiguous; section 10 split into 10a-10f, each a separate input, to
   work around PSReadLine multi-line paste parsing.

cmd/doctor.go

@@ -175,7 +175,7 @@ func runDoctor(cmd *cobra.Command, args []string) error {
 		passed++
 	} else {
 		fmt.Printf("  [FAIL] No workspaces found\n")
-		fmt.Printf("         Fix: create one with: ctask new \"my first task\"\n")
+		fmt.Printf("         Fix: create one with: %s new \"my first task\"\n", invocationName())
 		failed++
 	}
 

cmd/entry.go

@@ -118,19 +118,46 @@ func entryEnvVars(opts WorkspaceEntryOptions) map[string]string {
 
 func invokeDirectRun(opts WorkspaceEntryOptions) error {
 	return session.Run(session.LaunchOpts{
-		WsDir:        opts.WsPath,
-		EnvVars:      entryEnvVars(opts),
-		Agent:        opts.Agent,
-		Mode:         opts.WsMeta.Mode,
-		Slug:         opts.WsMeta.Slug,
-		Shell:        opts.Shell,
-		LaunchDir:    opts.WsMeta.LaunchDir,
-		Category:     opts.WsMeta.Category,
-		Force:        opts.Force,
-		NewlyCreated: opts.NewlyCreated,
+		WsDir:           opts.WsPath,
+		EnvVars:         entryEnvVars(opts),
+		Agent:           opts.Agent,
+		Mode:            opts.WsMeta.Mode,
+		Slug:            opts.WsMeta.Slug,
+		Shell:           opts.Shell,
+		LaunchDir:       opts.WsMeta.LaunchDir,
+		Category:        opts.WsMeta.Category,
+		Force:           opts.Force,
+		NewlyCreated:    opts.NewlyCreated,
+		ActiveLeaseHint: directModeTmuxHint(opts),
 	})
 }
 
+// directModeTmuxHint returns a Layer-1 prompt suggestion when ctask is
+// about to enter direct mode on a workspace that already has a live tmux
+// session — pointing the user at `ctask attach <slug>` as the reattach
+// path. Returns "" when no hint is appropriate (no tmux on PATH, no
+// session for this workspace, or native Windows without WSL).
+//
+// This is a best-effort UX nudge: the lookup is silent on error so a
+// missing/broken tmux never blocks the direct-mode path.
+func directModeTmuxHint(opts WorkspaceEntryOptions) string {
+	if runtime.GOOS == "windows" && os.Getenv("WSL_DISTRO_NAME") == "" {
+		return ""
+	}
+	tmuxPath, err := exec.LookPath("tmux")
+	if err != nil {
+		return ""
+	}
+	absWs, _ := filepath.Abs(opts.WsPath)
+	sessionName := session.SessionName(opts.WsMeta.Category, opts.WsMeta.Slug, absWs)
+	if !shell.HasSession(tmuxPath, sessionName) {
+		return ""
+	}
+	return fmt.Sprintf(
+		"Tip: a tmux session exists for this workspace.\nTo reattach instead of starting a second direct-mode session, run:\n  %s attach %s",
+		invocationName(), opts.WsMeta.Slug)
+}
+
 func invokePersistentRun(opts WorkspaceEntryOptions, tmuxPath, sessionName string) error {
 	return session.Run(session.LaunchOpts{
 		WsDir:        opts.WsPath,
@@ -189,9 +216,9 @@ func confirmDirectBypass(opts WorkspaceEntryOptions) error {
 	fmt.Fprintf(os.Stderr,
 		"A persistent tmux session exists for this workspace:\n  %s\n\n"+
 			"Opening a direct-mode shell may create conflicting workspace activity.\n"+
-			"The recommended path is:\n  ctask attach %s\n\n"+
+			"The recommended path is:\n  %s attach %s\n\n"+
 			"Continue with --direct anyway? [y/N] ",
-		sessionName, opts.WsMeta.Slug)
+		sessionName, invocationName(), opts.WsMeta.Slug)
 	if !session.ConfirmYN(os.Stdin, os.Stderr, "", false) {
 		return fmt.Errorf("canceled by user")
 	}

cmd/invocation.go

@@ -0,0 +1,39 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// invocationNameOverride lets tests fix the binary name surfaced in
+// user-facing hint and refusal messages. Production code leaves it empty
+// so the live os.Args[0] basename is used.
+//
+// Tests that assert on specific hint substrings (e.g. "ctask attach
+// <slug>") must set this to "ctask" via t.Cleanup; otherwise the test
+// binary's name (e.g. "cmd.test") will surface in the hint and the
+// substring will not match. Do not run such tests in t.Parallel — this
+// is a package global.
+var invocationNameOverride string
+
+// invocationName returns the binary name to render in user-facing
+// command suggestions ("<name> new <workspace> --direct",
+// "<name> attach <slug>", etc.). It returns the basename of os.Args[0]
+// so the hint reads cleanly regardless of invocation form: `./ctask`,
+// `.\ctask.exe`, `/usr/local/bin/ctask`, and an installed `ctask` on
+// PATH all surface as `ctask` (or `ctask.exe` on Windows). The slight
+// loss of paste-ability for explicit-path invocations (the user has to
+// re-prepend their `./` or `.\`) is the trade for a clean, predictable
+// hint that matches the canonical install case.
+//
+// Falls back to "ctask" when argv is empty (a degenerate state — should
+// not happen in normal execution, but defensive against odd embeddings).
+func invocationName() string {
+	if invocationNameOverride != "" {
+		return invocationNameOverride
+	}
+	if len(os.Args) == 0 || os.Args[0] == "" {
+		return "ctask"
+	}
+	return filepath.Base(os.Args[0])
+}

cmd/persistent.go

@@ -36,7 +36,8 @@ func defaultIsTTYCheck() bool {
 // commandName ("new", "resume", "last", "open", "attach") is rendered into
 // the bypass hint so each command tells the user the right form.
 func preflightPersistentEntry(commandName string) (string, error) {
-	bypass := "  ctask " + commandName + " <workspace> --direct"
+	bin := invocationName()
+	bypass := "  " + bin + " " + commandName + " <workspace> --direct"
 
 	if runtime.GOOS == "windows" && os.Getenv("WSL_DISTRO_NAME") == "" {
 		return "", fmt.Errorf(

cmd/persistent_test.go

@@ -22,6 +22,18 @@ func withTTYCheck(t *testing.T, fn func() bool) {
 	t.Cleanup(func() { isTTYCheck = orig })
 }
 
+// withInvocationName pins the binary name surfaced in user-facing hints
+// to a fixed value (typically "ctask") for the duration of the test, so
+// substring assertions against rendered hints stay stable regardless of
+// the Go test binary's name. Must NOT run in parallel — mutates a
+// package global.
+func withInvocationName(t *testing.T, name string) {
+	t.Helper()
+	orig := invocationNameOverride
+	invocationNameOverride = name
+	t.Cleanup(func() { invocationNameOverride = orig })
+}
+
 func TestPreflightRefusesNativeWindows(t *testing.T) {
 	if runtime.GOOS != "windows" {
 		t.Skip("native-Windows refusal applies only on Windows")
@@ -64,6 +76,7 @@ func TestPreflightRefusesNonTTY(t *testing.T) {
 	}
 	os.Unsetenv("TMUX")
 	withTTYCheck(t, func() bool { return false })
+	withInvocationName(t, "ctask")
 	_, err := preflightPersistentEntry("resume")
 	if err == nil {
 		t.Fatal("expected refusal when not a TTY")
@@ -74,8 +87,8 @@ func TestPreflightRefusesNonTTY(t *testing.T) {
 	if !strings.Contains(err.Error(), "ssh -t") {
 		t.Errorf("error should mention ssh -t: %v", err)
 	}
-	if !strings.Contains(err.Error(), "ctask resume") {
-		t.Errorf("error should mention command-specific bypass: %v", err)
+	if !strings.Contains(err.Error(), "ctask resume <workspace> --direct") {
+		t.Errorf("error should mention command-specific bypass form: %v", err)
 	}
 }
 
@@ -85,9 +98,10 @@ func TestPreflightCommandNameRendersInHints(t *testing.T) {
 	}
 	os.Unsetenv("TMUX")
 	withTTYCheck(t, func() bool { return false })
+	withInvocationName(t, "ctask")
 	_, err := preflightPersistentEntry("attach")
-	if err == nil || !strings.Contains(err.Error(), "ctask attach") {
-		t.Errorf("commandName must appear in hint: %v", err)
+	if err == nil || !strings.Contains(err.Error(), "ctask attach <workspace> --direct") {
+		t.Errorf("commandName must appear in bypass hint: %v", err)
 	}
 }
 

cmd/resume.go

@@ -59,8 +59,8 @@ func doResume(query string, container, useShell, force bool, agentOverride strin
 
 	if ws.Meta.Status == "archived" {
 		fmt.Fprintf(os.Stderr,
-			"[ctask] error: workspace %q is archived\n\nTo restore it:\n  ctask restore %s\n",
-			query, query)
+			"[ctask] error: workspace %q is archived\n\nTo restore it:\n  %s restore %s\n",
+			query, invocationName(), query)
 		return fmt.Errorf("workspace archived")
 	}
 

cmd/resume_test.go

@@ -41,6 +41,12 @@ func callDoResumeArchived(t *testing.T, root, query string) (stderr string, err
 }
 
 func TestResumeArchivedWorkspaceShowsRestoreHint(t *testing.T) {
+	// Pin the binary name surfaced in user-facing hints so the substring
+	// assertion below ("ctask restore resume-archived") is stable across
+	// Go test binary naming.
+	invocationNameOverride = "ctask"
+	t.Cleanup(func() { invocationNameOverride = "" })
+
 	root := t.TempDir()
 	wsDir := filepath.Join(root, "general", "2026-04-22_resume-archived")
 	os.MkdirAll(wsDir, 0755)