fix: resolve lint errors (ireturn, revive, unused)

- Add //nolint:ireturn for interface-returning methods required by
  bubbletea.Model and review types.Process/AgentReviewer contracts
- Rename AgentForTranscriptPath → ForTranscriptPath to fix revive stutter
- Wire newTrailWatchCmd into trail subcommand group
- Add //nolint:unused for platform-specific state_lock_unix.go

Author: Patel230

cmd/trace/cli/agent/registry.go

@@ -101,9 +101,9 @@ func Detect(ctx context.Context) (Agent, error) {
 	return detected[0], nil
 }
 
-// AgentForTranscriptPath returns the registered agent whose session directory
+// ForTranscriptPath returns the registered agent whose session directory
 // contains transcriptPath. Returns (nil, false) if no agent matches.
-func AgentForTranscriptPath(transcriptPath, repoPath string) (Agent, bool) {
+func ForTranscriptPath(transcriptPath, repoPath string) (Agent, bool) {
 	if transcriptPath == "" {
 		return nil, false
 	}

cmd/trace/cli/recap_tui.go

@@ -104,7 +104,7 @@ func (m recapTUIModel) fetch(requestID int) tea.Cmd {
 	}
 }
 
-func (m recapTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+func (m recapTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { //nolint:ireturn // required by bubbletea.Model interface
 	switch msg := msg.(type) {
 	case recapDataMsg:
 		if msg.requestID != m.requestID {

cmd/trace/cli/review/cmd.go

@@ -724,7 +724,7 @@ type perAgentConfiguredReviewer struct {
 }
 
 func (r *perAgentConfiguredReviewer) Name() string { return r.inner.Name() }
-func (r *perAgentConfiguredReviewer) Start(ctx context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) {
+func (r *perAgentConfiguredReviewer) Start(ctx context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) { //nolint:ireturn // required by reviewtypes.AgentReviewer interface
 	return r.inner.Start(ctx, r.cfg) //nolint:wrapcheck // transparent adapter; callers see inner's error type directly
 }
 

cmd/trace/cli/review/cmd_test.go

@@ -369,7 +369,7 @@ type stubDispatchReviewer struct {
 }
 
 func (r *stubDispatchReviewer) Name() string { return r.name }
-func (r *stubDispatchReviewer) Start(context.Context, reviewtypes.RunConfig) (reviewtypes.Process, error) {
+func (r *stubDispatchReviewer) Start(context.Context, reviewtypes.RunConfig) (reviewtypes.Process, error) { //nolint:ireturn // test stub implementing reviewtypes.AgentReviewer
 	return &stubDispatchProcess{}, nil
 }
 
@@ -396,7 +396,7 @@ type captureRunConfigReviewer struct {
 }
 
 func (r *captureRunConfigReviewer) Name() string { return r.name }
-func (r *captureRunConfigReviewer) Start(_ context.Context, cfg reviewtypes.RunConfig) (reviewtypes.Process, error) {
+func (r *captureRunConfigReviewer) Start(_ context.Context, cfg reviewtypes.RunConfig) (reviewtypes.Process, error) { //nolint:ireturn // test stub implementing reviewtypes.AgentReviewer
 	r.called = true
 	r.got = cfg
 	return &stubDispatchProcess{}, nil

cmd/trace/cli/review/run_test.go

@@ -17,7 +17,7 @@ type stubReviewer struct {
 }
 
 func (s *stubReviewer) Name() string { return s.name }
-func (s *stubReviewer) Start(_ context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) {
+func (s *stubReviewer) Start(_ context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) { //nolint:ireturn // test stub implementing reviewtypes.AgentReviewer
 	if s.startErr != nil {
 		return nil, s.startErr
 	}
@@ -159,7 +159,7 @@ type funcReviewer struct {
 }
 
 func (r *funcReviewer) Name() string { return r.name }
-func (r *funcReviewer) Start(_ context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) {
+func (r *funcReviewer) Start(_ context.Context, _ reviewtypes.RunConfig) (reviewtypes.Process, error) { //nolint:ireturn // test stub implementing reviewtypes.AgentReviewer
 	return r.process, nil
 }
 

cmd/trace/cli/review/tui_model.go

@@ -108,7 +108,7 @@ func (m reviewTUIModel) Init() tea.Cmd {
 }
 
 // Update handles all incoming messages.
-func (m reviewTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+func (m reviewTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { //nolint:ireturn // required by bubbletea.Model interface
 	switch msg := msg.(type) {
 	case agentEventMsg:
 		return m.handleAgentEvent(msg)
@@ -166,7 +166,7 @@ func (m reviewTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 }
 
 // handleAgentEvent processes an agentEventMsg, updating the relevant row.
-func (m reviewTUIModel) handleAgentEvent(msg agentEventMsg) (tea.Model, tea.Cmd) {
+func (m reviewTUIModel) handleAgentEvent(msg agentEventMsg) (tea.Model, tea.Cmd) { //nolint:ireturn // returns bubbletea.Model for Update dispatch
 	idx, ok := m.rowIdx[msg.agent]
 	if !ok {
 		return m, nil
@@ -229,7 +229,7 @@ func (m reviewTUIModel) handleAgentEvent(msg agentEventMsg) (tea.Model, tea.Cmd)
 }
 
 // handleKey processes keyboard input.
-func (m reviewTUIModel) handleKey(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
+func (m reviewTUIModel) handleKey(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) { //nolint:ireturn // returns bubbletea.Model for Update dispatch
 	// Any key after finished dismisses.
 	if m.finished {
 		return m, tea.Quit

cmd/trace/cli/review/types/template.go

@@ -55,7 +55,7 @@ func (t *ReviewerTemplate) Name() string { return t.AgentName }
 // with a typed error is friendlier than a downstream nil deref — and it
 // keeps Start from panicking inside a multi-agent fan-out (CU8) where one
 // misconfigured template would otherwise kill the whole run.
-func (t *ReviewerTemplate) Start(ctx context.Context, cfg RunConfig) (Process, error) {
+func (t *ReviewerTemplate) Start(ctx context.Context, cfg RunConfig) (Process, error) { //nolint:ireturn // required by AgentReviewer interface
 	if t.AgentName == "" {
 		return nil, fmt.Errorf("ReviewerTemplate.Start: %w (empty AgentName)", ErrTemplateMisconfigured)
 	}

cmd/trace/cli/review_bridge.go

@@ -118,7 +118,7 @@ func logProviderResolutionOutput(ctx context.Context, buf *bytes.Buffer) {
 // copilot-cli). This lives in the cli package to avoid the import cycle:
 //
 //	review/cmd.go → claudecode/codex/geminicli → review
-func launchableReviewerFor(agentName string) reviewtypes.AgentReviewer {
+func launchableReviewerFor(agentName string) reviewtypes.AgentReviewer { //nolint:ireturn // returns concrete types behind reviewtypes.AgentReviewer interface
 	switch agentName {
 	case string(agent.AgentNameClaudeCode):
 		return claudecode.NewReviewer()

cmd/trace/cli/strategy/agent_resolution_test.go

@@ -8,7 +8,7 @@ import (
 
 	"github.com/GrayCodeAI/trace/cmd/trace/cli/agent"
 
-	// Register agents so AgentForTranscriptPath can resolve them.
+	// Register agents so agent.ForTranscriptPath can resolve them.
 	_ "github.com/GrayCodeAI/trace/cmd/trace/cli/agent/claudecode"
 	_ "github.com/GrayCodeAI/trace/cmd/trace/cli/agent/cursor"
 

cmd/trace/cli/strategy/manual_commit_hooks.go

@@ -2974,7 +2974,7 @@ func (s *ManualCommitStrategy) carryForwardToNewShadowBranch(
 // session ID.
 func resolveSessionAgentType(ctx context.Context, sessionID string, callerAgentType types.AgentType, transcriptPath string) types.AgentType {
 	if repoRoot, err := paths.WorktreeRoot(ctx); err == nil && transcriptPath != "" {
-		if owner, ok := agent.AgentForTranscriptPath(transcriptPath, repoRoot); ok {
+		if owner, ok := agent.ForTranscriptPath(transcriptPath, repoRoot); ok {
 			return owner.Type()
 		}
 	}
@@ -2995,7 +2995,7 @@ func correctSessionAgentType(ctx context.Context, currentType types.AgentType, t
 	if err != nil {
 		return currentType, false
 	}
-	owner, ok := agent.AgentForTranscriptPath(transcriptPath, repoRoot)
+	owner, ok := agent.ForTranscriptPath(transcriptPath, repoRoot)
 	if !ok {
 		return currentType, false
 	}