fix: harden managed workspace lifecycle

.github/workflows/ci.yml

@@ -48,6 +48,37 @@ jobs:
           name: coverage-${{ matrix.go }}
           path: coverage.out
 
+  workspace-runtime:
+    name: Workspace Runtime (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.2"
+          cache: true
+
+      - name: Test workspace
+        run: go test ./internal/workspace -count=1 -timeout=20m
+
+  workspace-platform-compile:
+    name: Workspace Platform Compile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.2"
+          cache: true
+
+      - name: Compile workspace platform families
+        run: scripts/check-workspace-platforms.sh
+
   web:
     name: Web
     runs-on: ubuntu-latest

Makefile

@@ -3,7 +3,7 @@ BIN := bin
 MODULE := github.com/Duang777/drove
 VERSION ?= $(shell git describe --tags --always 2>/dev/null || echo dev)
 
-.PHONY: all build build-cli build-daemon test vet lint fmt clean install help
+.PHONY: all build build-cli build-daemon test test-workspace-platforms vet lint fmt clean install help
 
 all: build
 
@@ -21,6 +21,10 @@ test:
 	$(GO) test ./... -race -coverprofile=coverage.out
 	$(GO) tool cover -func=coverage.out | tail -n 1
 
+## test-workspace-platforms: 编译 workspace 的全部平台实现与测试
+test-workspace-platforms:
+	GO=$(GO) scripts/check-workspace-platforms.sh
+
 ## vet: 静态检查
 vet:
 	$(GO) vet ./...

cmd/drove/AGENTS.md

@@ -55,6 +55,7 @@ log / timeline / explain / attach / tui / stop / worktree / token rotate / web /
 
 - main 必须保持极薄：解析参数 → 调用 client → 退出码语义化（0 成功 / 1 用户错误 / 2 运行时错误）。
 - 未知顶层或嵌套子命令属于用户输入错误，必须返回退出码 1。
+- Cobra 的隐藏补全入口 `__complete` 与 `__completeNoDesc` 必须绕过未知命令预检。
 - 禁止在 cmd 中复制业务逻辑或直接构造 session/pty/store；一律走 `internal/client`。
 - 本地自定义类型必须与 daemon API 的 JSON 契约一致（增删字段需同步 API 层测试）。
 - 导出符号：无（main 包不导出）。

cmd/drove/main.go

@@ -16,6 +16,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"syscall"
 	"time"
 	"unicode/utf8"
 
@@ -59,7 +60,7 @@ func main() {
 	// CLI 静默日志，避免污染输出。
 	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})))
 
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
+	ctx, stop := newRootContext()
 	defer stop()
 	root := newRootCmd()
 	root.SetContext(ctx)
@@ -69,28 +70,87 @@ func main() {
 	}
 }
 
+func newRootContext() (context.Context, context.CancelFunc) {
+	return signal.NotifyContext(
+		context.Background(),
+		os.Interrupt,
+		syscall.SIGTERM,
+	)
+}
+
 func executeRoot(root *cobra.Command, args []string) error {
 	root.InitDefaultHelpCmd()
 	root.InitDefaultCompletionCmd()
-	command, remaining, err := root.Find(args)
-	if err != nil {
+	if err := validateDefaultHelpArgs(root, args); err != nil {
+		return err
+	}
+	if !isCompletionRequest(args) {
+		command, remaining, err := root.Find(args)
+		if err != nil {
+			return markUsageError(err)
+		}
+		afterTerminator := len(remaining) > 0 && remaining[0] == "--"
+		if len(remaining) > 0 && remaining[0] == "--" {
+			remaining = remaining[1:]
+		}
+		if command.HasSubCommands() &&
+			!command.Runnable() &&
+			len(remaining) > 0 &&
+			(afterTerminator || !strings.HasPrefix(remaining[0], "-")) {
+			return markUsageError(fmt.Errorf(
+				"unknown command %q for %q",
+				remaining[0],
+				command.CommandPath(),
+			))
+		}
+	}
+	root.SetArgs(args)
+	err := root.Execute()
+	if err != nil && len(args) > 0 && args[0] == "completion" {
 		return markUsageError(err)
 	}
-	if len(remaining) > 0 && remaining[0] == "--" {
-		remaining = remaining[1:]
+	return err
+}
+
+func validateDefaultHelpArgs(root *cobra.Command, args []string) error {
+	if len(args) < 2 || args[0] != "help" {
+		return nil
+	}
+	topic := make([]string, 0, len(args)-1)
+	afterTerminator := false
+	for _, argument := range args[1:] {
+		if afterTerminator {
+			topic = append(topic, argument)
+			continue
+		}
+		if argument == "--" {
+			afterTerminator = true
+			continue
+		}
+		if argument == "-h" || argument == "--help" {
+			return nil
+		}
+		if strings.HasPrefix(argument, "-") {
+			continue
+		}
+		topic = append(topic, argument)
 	}
-	if command.HasSubCommands() &&
-		!command.Runnable() &&
-		len(remaining) > 0 &&
-		!strings.HasPrefix(remaining[0], "-") {
-		return markUsageError(fmt.Errorf(
-			"unknown command %q for %q",
-			remaining[0],
-			command.CommandPath(),
-		))
+	if len(topic) == 0 {
+		return nil
 	}
-	root.SetArgs(args)
-	return root.Execute()
+	_, remaining, err := root.Find(topic)
+	if err == nil && len(remaining) == 0 {
+		return nil
+	}
+	return markUsageError(fmt.Errorf(
+		"unknown help topic %q",
+		strings.Join(topic, " "),
+	))
+}
+
+func isCompletionRequest(args []string) bool {
+	return len(args) > 0 &&
+		(args[0] == "__complete" || args[0] == "__completeNoDesc")
 }
 
 func commandExitCode(err error) int {
@@ -174,6 +234,7 @@ func newInitCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "init",
 		Short: "初始化配置与数据目录",
+		Args:  usageArgs(cobra.NoArgs),
 		RunE: func(_ *cobra.Command, _ []string) error {
 			cfg := config.Defaults()
 			path := config.DefaultPath()
@@ -259,6 +320,7 @@ func newPSCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "ps",
 		Short: "列出全部 Agent 会话",
+		Args:  usageArgs(cobra.NoArgs),
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			ctx := cmd.Context()
 			c, err := newClient(ctx)
@@ -1129,6 +1191,7 @@ func newVersionCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "version",
 		Short: "输出版本信息",
+		Args:  usageArgs(cobra.NoArgs),
 		Run: func(_ *cobra.Command, _ []string) {
 			fmt.Printf("drove %s (commit=%s, built=%s)\n", version.Version, version.Commit, version.Date)
 		},

cmd/drove/main_test.go

@@ -11,11 +11,15 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
+	"syscall"
 	"testing"
 	"time"
 	"unicode/utf8"
 
+	"github.com/spf13/cobra"
+
 	"github.com/Duang777/drove/internal/agent"
 	"github.com/Duang777/drove/internal/auth"
 	"github.com/Duang777/drove/internal/cliattach"
@@ -30,6 +34,29 @@ import (
 	"github.com/Duang777/drove/internal/workspace"
 )
 
+func TestRootContextCancelsOnSIGTERM(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Windows does not deliver POSIX SIGTERM")
+	}
+	ctx, stop := newRootContext()
+	defer stop()
+	process, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatalf("find test process: %v", err)
+	}
+	if err := process.Signal(syscall.SIGTERM); err != nil {
+		t.Fatalf("send SIGTERM: %v", err)
+	}
+	select {
+	case <-ctx.Done():
+		if !errors.Is(ctx.Err(), context.Canceled) {
+			t.Fatalf("root context error = %v, want context canceled", ctx.Err())
+		}
+	case <-time.After(time.Second):
+		t.Fatal("SIGTERM did not cancel the root context")
+	}
+}
+
 func TestSessionStartRequestMapsRunMode(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -269,6 +296,8 @@ func TestExecuteRootTreatsUnknownCommandsAsUsageErrors(t *testing.T) {
 		{"worktree", "unknown"},
 		{"--", "unknown"},
 		{"worktree", "--", "unknown"},
+		{"--", "--bogus"},
+		{"worktree", "--", "--bogus"},
 	}
 	for _, args := range tests {
 		t.Run(strings.Join(args, "/"), func(t *testing.T) {
@@ -283,6 +312,57 @@ func TestExecuteRootTreatsUnknownCommandsAsUsageErrors(t *testing.T) {
 	}
 }
 
+func TestZeroArgumentCommandsRejectArguments(t *testing.T) {
+	for _, command := range []*cobra.Command{
+		newInitCmd(),
+		newPSCmd(),
+		newVersionCmd(),
+	} {
+		t.Run(command.Name(), func(t *testing.T) {
+			if command.Args == nil {
+				t.Fatal("argument validator is nil")
+			}
+			if err := command.Args(command, nil); err != nil {
+				t.Fatalf("validate no arguments: %v", err)
+			}
+			err := command.Args(command, []string{"unexpected"})
+			if err == nil {
+				t.Fatal("accepted an unexpected argument")
+			}
+			if got := commandExitCode(err); got != exitUsage {
+				t.Fatalf("exit code = %d, want %d for %v", got, exitUsage, err)
+			}
+		})
+	}
+}
+
+func TestExecuteRootTreatsDefaultCommandArgumentErrorsAsUsageErrors(
+	t *testing.T,
+) {
+	tests := [][]string{
+		{"help", "definitely-not-a-command"},
+		{"help", "--", "definitely-not-a-command"},
+		{"help", "worktree", "--", "definitely-not-a-command"},
+		{"completion", "bash", "extra"},
+	}
+	for _, args := range tests {
+		t.Run(strings.Join(args, "/"), func(t *testing.T) {
+			err := executeRoot(newRootCmd(), args)
+			if err == nil {
+				t.Fatalf("execute %v succeeded", args)
+			}
+			if got := commandExitCode(err); got != exitUsage {
+				t.Fatalf(
+					"exit code = %d, want %d for %v",
+					got,
+					exitUsage,
+					err,
+				)
+			}
+		})
+	}
+}
+
 func TestExecuteRootSupportsDefaultCommands(t *testing.T) {
 	tests := []struct {
 		name       string
@@ -294,11 +374,50 @@ func TestExecuteRootSupportsDefaultCommands(t *testing.T) {
 			args:       []string{"help", "worktree"},
 			wantOutput: "Usage:",
 		},
+		{
+			name:       "help command flag",
+			args:       []string{"help", "--help"},
+			wantOutput: "Usage:",
+		},
+		{
+			name:       "help target flag",
+			args:       []string{"help", "worktree", "--help"},
+			wantOutput: "Usage:",
+		},
+		{
+			name: "help flag overrides invalid topic",
+			args: []string{
+				"help",
+				"--help",
+				"definitely-not-a-command",
+			},
+			wantOutput: "Usage:",
+		},
+		{
+			name: "target help flag overrides invalid topic",
+			args: []string{
+				"help",
+				"worktree",
+				"-h",
+				"definitely-not-a-command",
+			},
+			wantOutput: "Usage:",
+		},
 		{
 			name:       "completion",
 			args:       []string{"completion", "bash"},
 			wantOutput: "__start_drove",
 		},
+		{
+			name:       "completion request",
+			args:       []string{"__complete", "workt"},
+			wantOutput: "worktree",
+		},
+		{
+			name:       "completion request without descriptions",
+			args:       []string{"__completeNoDesc", "workt"},
+			wantOutput: "worktree",
+		},
 	}
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/muesli/cancelreader v0.2.2
 	github.com/spf13/cobra v1.8.1
 	golang.org/x/sys v0.41.0
+	golang.org/x/text v0.29.0
 	modernc.org/sqlite v1.33.1
 )
 
@@ -45,7 +46,6 @@ require (
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/text v0.3.8 // indirect
 	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect
 	modernc.org/libc v1.55.3 // indirect
 	modernc.org/mathutil v1.6.0 // indirect