kandev/apps/backend/internal/orchestrator/messagequeue/service.go

// Package messagequeue persists per-session FIFO message queues and deferred
// workflow moves. The queue lets a user (or another agent via the
// message_task_kandev MCP tool) enqueue follow-up prompts while the target
// session is still busy with a turn; handleAgentReady drains one entry per
// turn after each turn completes.
//
// Storage is abstracted behind Repository (SQLite in production, in-memory
// for tests). The service enforces a per-session cap (default 10) and surfaces
// overflow as ErrQueueFull rather than silently dropping the new message.
package messagequeue

import (
	"context"
	"errors"
	"fmt"
	"sync"
	"sync/atomic"
	"time"

	"github.com/google/uuid"
	"github.com/kandev/kandev/internal/common/logger"
	"go.uber.org/zap"
)

type autoMergePolicyLoader struct {
	load func(context.Context) (bool, int64, error)
}

// Service manages queued messages for sessions, backed by Repository.
type Service struct {
	repo            Repository
	maxPerSession   atomic.Int64
	mergeEnabled    atomic.Bool
	autoMergePolicy atomic.Pointer[AutoMergePolicy]
	autoMergeLoader atomic.Pointer[autoMergePolicyLoader]
	statusEpoch     string
	logger          *logger.Logger
	admissionMu     sync.Mutex
	admissions      map[string]*sessionAdmission
}

type sessionAdmission struct {
	mu   sync.Mutex
	refs int
}

type sessionAdmissionContextKey struct{}

type sessionAdmissionToken struct {
	service   *Service
	sessionID string
}

type queueAttachmentRepository interface {
	InsertForSessionWithClaim(context.Context, QueueSessionIdentity, *QueuedMessage, QueueAttachmentClaim, int) error
	AutoMergeCandidateIntoAboveForSessionWithClaim(context.Context, QueueSessionIdentity, *QueuedMessage, QueueAttachmentClaim) (*QueuedMessage, bool, error)
	UpdateContentAndMetadataForSessionWithClaim(context.Context, QueueSessionIdentity, string, string, []MessageAttachment, map[string]interface{}, string, QueueAttachmentClaim) error
}

type deletedSessionRepository interface {
	PurgeDeletedSession(context.Context, QueueSessionIdentity) error
}

type autoMergeAdmissionRepository interface {
	InsertForSessionWithPolicy(
		context.Context,
		QueueSessionIdentity,
		*QueuedMessage,
		*QueueAttachmentClaim,
		int,
		AutoMergePolicy,
	) error
	AutoMergeCandidateIntoAboveForSessionWithPolicy(
		context.Context,
		QueueSessionIdentity,
		*QueuedMessage,
		*QueueAttachmentClaim,
		AutoMergePolicy,
	) (*QueuedMessage, bool, error)
	AutoMergeIntoAboveForSessionWithPolicy(
		context.Context,
		QueueSessionIdentity,
		string,
		AutoMergePolicy,
	) (*QueuedMessage, bool, error)
}

// NewService creates a Service backed by the supplied repository. maxPerSession
// is the per-session cap (entries beyond this return ErrQueueFull on insert);
// pass 0 to disable the cap.
func NewService(repo Repository, maxPerSession int, log *logger.Logger) *Service {
	service := &Service{
		repo:        repo,
		statusEpoch: uuid.NewString(),
		logger:      log.WithFields(zap.String("component", "message-queue")),
		admissions:  make(map[string]*sessionAdmission),
	}
	service.SetMaxPerSession(maxPerSession)
	service.mergeEnabled.Store(true)
	service.SetAutoMergePolicy(true, 0)
	return service
}

// NewServiceMemory returns a Service backed by an in-memory repository.
// Convenience constructor for tests; cap defaults to 10 for parity with prod.
func NewServiceMemory(log *logger.Logger) *Service {
	return NewService(NewMemoryRepository(), DefaultMaxPerSession, log)
}

// ResolveSessionIdentity returns the repository-authoritative immutable queue
// identity for trusted internal callers migrating legacy session snapshots.
func (s *Service) ResolveSessionIdentity(ctx context.Context, taskID, sessionID string) (QueueSessionIdentity, error) {
	return s.repo.ResolveSessionIdentity(ctx, taskID, sessionID)
}

// SupportsAtomicDeferredMoveTransition reports whether task and queue rows share
// one SQL transaction. The in-memory queue cannot participate in task storage.
func (s *Service) SupportsAtomicDeferredMoveTransition() bool {
	_, ok := s.repo.(*sqliteRepository)
	return ok
}

// MaxPerSession returns the configured per-session cap.
func (s *Service) MaxPerSession() int { return int(s.maxPerSession.Load()) }

// LifecycleGeneration returns the task archive/delete generation captured by
// send-now restoration guards.
func (s *Service) LifecycleGeneration(ctx context.Context, taskID string) (int64, error) {
	return s.repo.LifecycleGeneration(ctx, taskID)
}

// ListDurableLifecycleEntries returns lifecycle rows that remain persisted
// until executor acceptance. Startup recovery uses it to reconcile queue rows
// with their owning automation reservations.
func (s *Service) ListDurableLifecycleEntries(ctx context.Context) ([]QueuedMessage, error) {
	return s.repo.ListDurableLifecycleEntries(ctx)
}

// SetMaxPerSession applies a new admission cap without pruning existing rows.
// Non-positive values disable the cap.
func (s *Service) SetMaxPerSession(maxPerSession int) {
	if maxPerSession < 0 {
		maxPerSession = 0
	}
	s.maxPerSession.Store(int64(maxPerSession))
}

// MergeEnabled reports whether MergeIntoAbove is currently allowed. Enabled
// by default; see SetMergeEnabled.
func (s *Service) MergeEnabled() bool { return s.mergeEnabled.Load() }

// SetMergeEnabled toggles whether queued messages may be folded into the
// entry above them via MergeIntoAbove. Disabling it does not affect merges
// already applied.
func (s *Service) SetMergeEnabled(enabled bool) {
	s.mergeEnabled.Store(enabled)
}

// AutoMergeEnabled reports the global admission policy used by sessions that
// do not have an explicit override.
func (s *Service) AutoMergeEnabled() bool {
	return s.globalAutoMergePolicy().Enabled
}

// SetAutoMergeEnabled updates the global policy while preserving the legacy
// boolean target used by callers that do not own the persisted revision.
func (s *Service) SetAutoMergeEnabled(enabled bool) {
	current := s.globalAutoMergePolicy()
	revision := current.Revision
	if current.Enabled != enabled {
		revision++
	}
	s.SetAutoMergePolicy(enabled, revision)
}

// SetAutoMergePolicy atomically publishes a complete global policy snapshot.
func (s *Service) SetAutoMergePolicy(enabled bool, revision int64) {
	policy := &AutoMergePolicy{
		Enabled:  enabled,
		Source:   AutoMergeSourceGlobal,
		Revision: revision,
	}
	s.autoMergePolicy.Store(policy)
}

// SetAutoMergePolicyLoader installs the shared persisted-policy reader used by
// identity-bound admissions and snapshots. The atomic cache remains available
// to legacy callers that cannot carry a context.
func (s *Service) SetAutoMergePolicyLoader(
	load func(context.Context) (bool, int64, error),
) {
	if load == nil {
		s.autoMergeLoader.Store(nil)
		return
	}
	s.autoMergeLoader.Store(&autoMergePolicyLoader{load: load})
}

func (s *Service) globalAutoMergePolicy() AutoMergePolicy {
	policy := s.autoMergePolicy.Load()
	if policy == nil {
		return AutoMergePolicy{Enabled: true, Source: AutoMergeSourceGlobal}
	}
	return *policy
}

// ResolveAutoMergePolicy returns the session override when present, otherwise
// the current global policy snapshot.
func (s *Service) ResolveAutoMergePolicy(
	ctx context.Context,
	identity QueueSessionIdentity,
) (AutoMergePolicy, error) {
	override, err := s.repo.GetAutoMergeOverride(ctx, identity)
	if err != nil {
		return AutoMergePolicy{}, err
	}
	if override == nil {
		return s.loadGlobalAutoMergePolicy(ctx)
	}
	return AutoMergePolicy{
		Enabled:  override.Enabled,
		Source:   AutoMergeSourceSession,
		Revision: override.Revision,
	}, nil
}

func (s *Service) loadGlobalAutoMergePolicy(ctx context.Context) (AutoMergePolicy, error) {
	if loader := s.autoMergeLoader.Load(); loader != nil {
		enabled, revision, err := loader.load(ctx)
		if err != nil {
			return AutoMergePolicy{}, err
		}
		s.SetAutoMergePolicy(enabled, revision)
	}
	return s.globalAutoMergePolicy(), nil
}

// SetSessionAutoMerge persists and returns an explicit per-session policy.
func (s *Service) SetSessionAutoMerge(
	ctx context.Context,
	identity QueueSessionIdentity,
	enabled bool,
) (AutoMergePolicy, error) {
	var override AutoMergeOverride
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var setErr error
		override, setErr = s.repo.SetAutoMergeOverride(admittedCtx, identity, enabled)
		return setErr
	})
	if err != nil {
		return AutoMergePolicy{}, err
	}
	return AutoMergePolicy{
		Enabled:  override.Enabled,
		Source:   AutoMergeSourceSession,
		Revision: override.Revision,
	}, nil
}

// WithSessionAdmission runs fn under the per-session queue admission lock.
// All queue insertion and mutation paths use the same lock. The callback must
// complete synchronously; queue methods called with its context reuse the held
// lock.
func (s *Service) WithSessionAdmission(ctx context.Context, sessionID string, fn func(context.Context) error) error {
	if fn == nil {
		return errors.New("session admission callback is nil")
	}
	if token, ok := ctx.Value(sessionAdmissionContextKey{}).(sessionAdmissionToken); ok &&
		token.service == s && token.sessionID == sessionID {
		return fn(ctx)
	}

	s.admissionMu.Lock()
	entry := s.admissions[sessionID]
	if entry == nil {
		entry = &sessionAdmission{}
		s.admissions[sessionID] = entry
	}
	entry.refs++
	s.admissionMu.Unlock()

	entry.mu.Lock()
	defer func() {
		entry.mu.Unlock()
		s.admissionMu.Lock()
		entry.refs--
		if entry.refs == 0 && s.admissions[sessionID] == entry {
			delete(s.admissions, sessionID)
		}
		s.admissionMu.Unlock()
	}()

	admittedCtx := context.WithValue(ctx, sessionAdmissionContextKey{}, sessionAdmissionToken{
		service:   s,
		sessionID: sessionID,
	})
	return fn(admittedCtx)
}

// QueueMessage appends a new entry to the session's FIFO queue. Returns
// ErrQueueFull when the cap is exceeded.
func (s *Service) QueueMessage(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment) (*QueuedMessage, error) {
	return s.QueueMessageWithMetadata(ctx, sessionID, taskID, content, model, userID, planMode, attachments, nil)
}

// QueueMessageWithMetadata is like QueueMessage but stores extra metadata that
// is propagated to the resulting Message row when the queued message is
// drained (e.g. sender_task_id for messages sent via message_task_kandev).
func (s *Service) QueueMessageWithMetadata(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}) (*QueuedMessage, error) {
	identity, err := s.repo.ResolveSessionIdentity(ctx, taskID, sessionID)
	if err != nil {
		return nil, err
	}
	return s.queueMessageWithMetadataAdmission(
		ctx, &identity, sessionID, taskID, content, model, userID, planMode, attachments, metadata, nil, nil,
	)
}

// QueueMessageWithMetadataAfterInsert admits an exact source row, runs
// afterInsert while the per-session admission lock remains held, then attempts
// the snapshotted automatic fold. Callers use the hook to claim staged
// attachments before folding; if it returns an error, no fold is attempted.
func (s *Service) QueueMessageWithMetadataAfterInsert(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, afterInsert func(context.Context, *QueuedMessage) error) (*QueuedMessage, error) {
	identity, err := s.repo.ResolveSessionIdentity(ctx, taskID, sessionID)
	if err != nil {
		return nil, err
	}
	return s.queueMessageWithMetadataAdmission(
		ctx, &identity, sessionID, taskID, content, model, userID, planMode, attachments, metadata, nil, afterInsert,
	)
}

// QueueMessageWithMetadataForSession admits a browser message using the
// effective policy bound to the supplied immutable session identity.
func (s *Service) QueueMessageWithMetadataForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
) (*QueuedMessage, error) {
	return s.queueMessageWithMetadataAdmission(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode, attachments, metadata, nil, nil,
	)
}

// QueueMessageWithMetadataForSessionWithClaim atomically claims staged
// attachments when admission inserts a queue entry. An empty claim carries
// inline-only attachments and may use the compatible full-queue fold path.
func (s *Service) QueueMessageWithMetadataForSessionWithClaim(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	claim QueueAttachmentClaim,
) (*QueuedMessage, error) {
	return s.queueMessageWithMetadataAdmission(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode, attachments, metadata, &claim, nil,
	)
}

// QueueMessageWithMetadataForSessionAfterInsert is the identity-bound variant
// used while attachment claiming still participates in the admission lock.
func (s *Service) QueueMessageWithMetadataForSessionAfterInsert(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	afterInsert func(context.Context, *QueuedMessage) error,
) (*QueuedMessage, error) {
	return s.queueMessageWithMetadataAdmission(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode, attachments, metadata, nil, afterInsert,
	)
}

// queueMessageWithMetadataAdmission resolves policy and completes admission
// under one per-session lock. Identity-bound repositories compare that policy
// inside every durable mutation; an override race restarts before admission.
//
//nolint:gocognit // retry boundaries keep policy validation before each mutation.
func (s *Service) queueMessageWithMetadataAdmission(ctx context.Context, identity *QueueSessionIdentity, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, claim *QueueAttachmentClaim, afterInsert func(context.Context, *QueuedMessage) error) (*QueuedMessage, error) {
	var queued *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		for {
			policy := s.resolveAdmissionAutoMergePolicy(admittedCtx, identity, sessionID)
			source, insertErr := s.insertQueueMessageWithMetadata(
				admittedCtx, identity, sessionID, taskID, content, model, userID, planMode,
				attachments, metadata, claim, s.MaxPerSession(), policy,
			)
			if errors.Is(insertErr, ErrAutoMergePolicyChanged) {
				continue
			}
			autoMergeEnabled := policy != nil && policy.Enabled
			if insertErr != nil {
				hasStagedAttachments := claim != nil && len(claim.IDs) > 0
				if !errors.Is(insertErr, ErrQueueFull) || !autoMergeEnabled || hasStagedAttachments || afterInsert != nil {
					return insertErr
				}
				var merged *QueuedMessage
				source, merged, insertErr = s.admitQueueFullMessage(
					admittedCtx, identity, insertErr, sessionID, taskID, content, model, userID, planMode,
					attachments, metadata, claim, s.MaxPerSession(), policy,
				)
				if errors.Is(insertErr, ErrAutoMergePolicyChanged) {
					continue
				}
				if insertErr != nil {
					return insertErr
				}
				if merged != nil {
					queued = merged
					return nil
				}
			}
			if afterInsert != nil {
				if err := afterInsert(admittedCtx, source); err != nil {
					return err
				}
			}
			queued = s.finalizeAutoMerge(admittedCtx, identity, source, policy)
			return nil
		}
	})
	return queued, err
}

func (s *Service) resolveAdmissionAutoMergePolicy(
	ctx context.Context,
	identity *QueueSessionIdentity,
	sessionID string,
) *AutoMergePolicy {
	if identity == nil {
		policy := s.globalAutoMergePolicy()
		return &policy
	}
	policy, err := s.ResolveAutoMergePolicy(ctx, *identity)
	if err == nil {
		return &policy
	}
	s.logger.Warn("automatic merge policy unavailable; admitting separate message",
		zap.String("session_id", sessionID),
		zap.Error(err))
	return nil
}

func (s *Service) autoMergeCandidate(
	ctx context.Context,
	identity *QueueSessionIdentity,
	candidate *QueuedMessage,
	claim *QueueAttachmentClaim,
	policy *AutoMergePolicy,
) (*QueuedMessage, bool, error) {
	if identity == nil {
		return s.repo.AutoMergeCandidateIntoAbove(ctx, candidate)
	}
	if policyRepo, ok := s.repo.(autoMergeAdmissionRepository); ok && policy != nil {
		return policyRepo.AutoMergeCandidateIntoAboveForSessionWithPolicy(ctx, *identity, candidate, claim, *policy)
	}
	if claim == nil {
		return s.repo.AutoMergeCandidateIntoAboveForSession(ctx, *identity, candidate)
	}
	claimRepo, ok := s.repo.(queueAttachmentRepository)
	if !ok {
		return nil, false, errors.New("transactional attachment queue repository is unavailable")
	}
	return claimRepo.AutoMergeCandidateIntoAboveForSessionWithClaim(ctx, *identity, candidate, *claim)
}

// admitQueueFullMessage folds a candidate into the tail or retries insertion
// when the fold observes capacity freed by a concurrent drain.
func (s *Service) admitQueueFullMessage(
	ctx context.Context,
	identity *QueueSessionIdentity,
	queueFullErr error,
	sessionID, taskID, content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	claim *QueueAttachmentClaim,
	maxPerSession int,
	policy *AutoMergePolicy,
) (*QueuedMessage, *QueuedMessage, error) {
	candidate := &QueuedMessage{
		SessionID:   sessionID,
		TaskID:      taskID,
		Content:     content,
		Model:       model,
		PlanMode:    planMode,
		Attachments: attachments,
		Metadata:    copyMessageMetadata(metadata, 0),
		QueuedAt:    time.Now().UTC(),
		QueuedBy:    userID,
	}
	merged, didMerge, err := s.autoMergeCandidate(ctx, identity, candidate, claim, policy)
	if errors.Is(err, ErrAutoMergePolicyChanged) {
		return nil, nil, err
	}
	if err != nil {
		if errors.Is(err, ErrTaskInactive) {
			return nil, nil, err
		}
		s.logger.Error("automatic merge into full queue failed; preserving queue full rejection",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, nil, queueFullErr
	}
	if didMerge && merged != nil {
		s.logger.Info("automatically merged queued entry into full tail",
			zap.String("session_id", sessionID),
			zap.String("surviving_entry_id", merged.ID))
		return nil, merged, nil
	}
	source, err := s.insertQueueMessageWithMetadata(
		ctx, identity, sessionID, taskID, content, model, userID, planMode,
		attachments, metadata, claim, maxPerSession, policy,
	)
	return source, nil, err
}

// queueMessageWithMetadataSeparate is used by retry paths whose existing
// contract must not gain admission-time automatic behavior.
func (s *Service) queueMessageWithMetadataSeparate(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, maxPerSession int) (*QueuedMessage, error) {
	var queued *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		queued, err = s.insertQueueMessageWithMetadata(
			admittedCtx, nil, sessionID, taskID, content, model, userID, planMode,
			attachments, metadata, nil, maxPerSession, nil,
		)
		return err
	})
	return queued, err
}

func (s *Service) finalizeAutoMerge(
	ctx context.Context,
	identity *QueueSessionIdentity,
	source *QueuedMessage,
	policy *AutoMergePolicy,
) *QueuedMessage {
	for policy != nil && policy.Enabled {
		var merged *QueuedMessage
		var didMerge bool
		var err error
		if identity == nil {
			merged, didMerge, err = s.repo.AutoMergeIntoAbove(ctx, source.SessionID, source.ID)
		} else if policyRepo, ok := s.repo.(autoMergeAdmissionRepository); ok {
			merged, didMerge, err = policyRepo.AutoMergeIntoAboveForSessionWithPolicy(ctx, *identity, source.ID, *policy)
		} else {
			merged, didMerge, err = s.repo.AutoMergeIntoAboveForSession(ctx, *identity, source.ID)
		}
		if errors.Is(err, ErrAutoMergePolicyChanged) && identity != nil {
			policy = s.resolveAdmissionAutoMergePolicy(ctx, identity, source.SessionID)
			continue
		}
		if err != nil {
			s.logger.Error("automatic queue merge failed; preserving separate admission",
				zap.String("session_id", source.SessionID),
				zap.String("source_entry_id", source.ID),
				zap.Error(err))
			return source
		}
		if !didMerge || merged == nil {
			return source
		}
		s.logger.Info("automatically merged queued entry into tail",
			zap.String("session_id", source.SessionID),
			zap.String("source_entry_id", source.ID),
			zap.String("surviving_entry_id", merged.ID))
		return merged
	}
	return source
}

func (s *Service) insertQueueMessage(
	ctx context.Context,
	identity *QueueSessionIdentity,
	msg *QueuedMessage,
	claim *QueueAttachmentClaim,
	maxPerSession int,
	policy *AutoMergePolicy,
) error {
	if identity == nil {
		return s.repo.Insert(ctx, msg, maxPerSession)
	}
	if policyRepo, ok := s.repo.(autoMergeAdmissionRepository); ok && policy != nil {
		return policyRepo.InsertForSessionWithPolicy(ctx, *identity, msg, claim, maxPerSession, *policy)
	}
	if claim == nil {
		return s.repo.InsertForSession(ctx, *identity, msg, maxPerSession)
	}
	claimRepo, ok := s.repo.(queueAttachmentRepository)
	if !ok {
		return errors.New("transactional attachment queue repository is unavailable")
	}
	return claimRepo.InsertForSessionWithClaim(ctx, *identity, msg, *claim, maxPerSession)
}

// insertQueueMessageWithMetadata inserts a message with metadata under the per-session admission lock.
func (s *Service) insertQueueMessageWithMetadata(ctx context.Context, identity *QueueSessionIdentity, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, claim *QueueAttachmentClaim, maxPerSession int, policy *AutoMergePolicy) (*QueuedMessage, error) {
	metadataCopy := copyMessageMetadata(metadata, 0)
	msg := &QueuedMessage{
		SessionID:   sessionID,
		TaskID:      taskID,
		Content:     content,
		Model:       model,
		PlanMode:    planMode,
		Attachments: attachments,
		Metadata:    metadataCopy,
		QueuedBy:    userID,
	}
	err := s.insertQueueMessage(ctx, identity, msg, claim, maxPerSession, policy)
	if err != nil {
		if errors.Is(err, ErrQueueFull) {
			s.logger.Info("queue full",
				zap.String("session_id", sessionID),
				zap.Int("max", maxPerSession))
		}
		return nil, err
	}
	s.logger.Info("message queued",
		zap.String("session_id", sessionID),
		zap.String("task_id", taskID),
		zap.String("entry_id", msg.ID),
		zap.Int64("position", msg.Position),
		zap.Int("content_length", len(content)))
	return msg, nil
}

// RestoreMessage restores a dequeued message at its original FIFO position
// after a delivery failure. It preserves the entry's identity, position,
// queued_at time, and queued_by ownership.
func (s *Service) RestoreMessage(ctx context.Context, msg *QueuedMessage) (*QueuedMessage, error) {
	if msg == nil {
		return nil, errors.New("queued message is nil")
	}
	var restored *QueuedMessage
	err := s.WithSessionAdmission(ctx, msg.SessionID, func(admittedCtx context.Context) error {
		var err error
		restored, err = s.restoreMessage(admittedCtx, msg)
		return err
	})
	return restored, err
}

func (s *Service) RestoreMessageForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	msg *QueuedMessage,
) (*QueuedMessage, error) {
	if msg == nil {
		return nil, errors.New("queued message is nil")
	}
	var restored *QueuedMessage
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		candidate := *msg
		candidate.Metadata = copyMessageMetadata(msg.Metadata, 0)
		if err := s.validateSessionIdentity(admittedCtx, identity); err != nil {
			return err
		}
		if err := s.repo.RestoreForSession(admittedCtx, identity, &candidate, 0); err != nil {
			return err
		}
		restored = &candidate
		return nil
	})
	return restored, err
}

// restoreMessage is the admission-checked core of RestoreMessage.
func (s *Service) restoreMessage(ctx context.Context, msg *QueuedMessage) (*QueuedMessage, error) {
	restored := *msg
	restored.Metadata = copyMessageMetadata(msg.Metadata, 0)
	if err := s.repo.Restore(ctx, &restored, 0); err != nil {
		return nil, err
	}
	s.logger.Info("message restored at original queue position",
		zap.String("session_id", restored.SessionID),
		zap.String("task_id", restored.TaskID),
		zap.String("entry_id", restored.ID),
		zap.Int64("position", restored.Position))
	return &restored, nil
}

// QueueMessageWithCoalesceKey replaces an existing pending entry with the same
// coalesce key, session, and queued_by value. When no matching entry exists it
// inserts a new tail entry if allowInsert is true; otherwise ErrEntryNotFound is
// returned. The returned bool is true when an existing entry was replaced.
func (s *Service) QueueMessageWithCoalesceKey(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert bool) (*QueuedMessage, bool, error) {
	return s.queueMessageWithCoalesceKey(
		ctx, sessionID, taskID, content, model, userID, planMode, attachments, metadata,
		coalesceKey, allowInsert, s.MaxPerSession(),
	)
}

func (s *Service) QueueMessageWithCoalesceKeyForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	coalesceKey string,
	allowInsert bool,
) (*QueuedMessage, bool, error) {
	var queued *QueuedMessage
	var replaced bool
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		metadataCopy := copyMessageMetadata(metadata, 1)
		metadataCopy[MetadataCoalesceKey] = coalesceKey
		candidate := &QueuedMessage{
			SessionID: identity.SessionID, TaskID: identity.TaskID,
			Content: content, Model: model, PlanMode: planMode,
			Attachments: attachments, Metadata: metadataCopy, QueuedBy: userID,
		}
		var err error
		queued, replaced, err = s.repo.InsertOrReplaceByCoalesceKeyForSession(
			admittedCtx, identity, candidate, coalesceKey, s.MaxPerSession(), allowInsert,
		)
		return err
	})
	return queued, replaced, err
}

// queueMessageWithCoalesceKey is the admission-checked core of QueueMessageWithCoalesceKey.
func (s *Service) queueMessageWithCoalesceKey(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert bool, maxPerSession int) (*QueuedMessage, bool, error) {
	var queued *QueuedMessage
	var replaced bool
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		queued, replaced, err = s.insertQueueMessageWithCoalesceKey(
			admittedCtx, sessionID, taskID, content, model, userID, planMode, attachments, metadata,
			coalesceKey, allowInsert, maxPerSession,
		)
		return err
	})
	return queued, replaced, err
}

// insertQueueMessageWithCoalesceKey inserts or coalesce-replaces an entry under the admission lock.
func (s *Service) insertQueueMessageWithCoalesceKey(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert bool, maxPerSession int) (*QueuedMessage, bool, error) {
	metadataCopy := copyMessageMetadata(metadata, 1)
	metadataCopy[MetadataCoalesceKey] = coalesceKey
	msg := &QueuedMessage{
		SessionID:   sessionID,
		TaskID:      taskID,
		Content:     content,
		Model:       model,
		PlanMode:    planMode,
		Attachments: attachments,
		Metadata:    metadataCopy,
		QueuedBy:    userID,
	}
	queued, replaced, err := s.repo.InsertOrReplaceByCoalesceKey(ctx, msg, coalesceKey, maxPerSession, allowInsert)
	if err != nil {
		if errors.Is(err, ErrQueueFull) {
			s.logger.Info("queue full",
				zap.String("session_id", sessionID),
				zap.Int("max", maxPerSession))
		}
		return nil, false, err
	}
	s.logger.Info("message queued with coalesce key",
		zap.String("session_id", sessionID),
		zap.String("task_id", taskID),
		zap.String("entry_id", queued.ID),
		zap.String("coalesce_key", coalesceKey),
		zap.Bool("replaced", replaced),
		zap.Int64("position", queued.Position),
		zap.Int("content_length", len(content)))
	return queued, replaced, nil
}

// RequeueMessage retries work that was already admitted. It bypasses the
// current admission cap so lowering capacity while a message is in flight
// cannot discard that message. Coalesced retries retain replacement semantics.
func (s *Service) RequeueMessage(ctx context.Context, msg *QueuedMessage, queuedBy, coalesceKey string) (*QueuedMessage, bool, error) {
	if msg == nil {
		return nil, false, errors.New("queued message is nil")
	}
	if coalesceKey != "" {
		return s.queueMessageWithCoalesceKey(
			ctx, msg.SessionID, msg.TaskID, msg.Content, msg.Model, queuedBy, msg.PlanMode,
			msg.Attachments, msg.Metadata, coalesceKey, true, 0,
		)
	}
	queued, err := s.queueMessageWithMetadataSeparate(
		ctx, msg.SessionID, msg.TaskID, msg.Content, msg.Model, queuedBy, msg.PlanMode,
		msg.Attachments, msg.Metadata, 0,
	)
	return queued, false, err
}

// RequeueAtHead re-enqueues a user message at a position strictly lower
// than the session's current head. It is the FIFO-preserving requeue
// that Service.requeueMessage invokes when an entry was superseded by a
// newer dispatch before it could be claimed. See Repository
// .RequeuePreservingFIFO for the position arithmetic and position rebasing.
//
// This method is the bug fix entry point — caller code that wants
// user-message retry should call this instead of RequeueMessage so
// the original message beats any new arrival on a busy session.
func (s *Service) RequeueAtHead(ctx context.Context, msg *QueuedMessage) error {
	if msg == nil {
		return errors.New("queued message is nil")
	}
	return s.WithSessionAdmission(ctx, msg.SessionID, func(admittedCtx context.Context) error {
		return s.repo.RequeuePreservingFIFO(admittedCtx, msg)
	})
}

func (s *Service) RequeueAtHeadForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	msg *QueuedMessage,
) error {
	if msg == nil {
		return errors.New("queued message is nil")
	}
	return s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		if err := s.validateSessionIdentity(admittedCtx, identity); err != nil {
			return err
		}
		return s.repo.RequeuePreservingFIFOForSession(admittedCtx, identity, msg)
	})
}

// QueueLifecycleMessageWithCoalesceKey accepts a lifecycle entry only while
// its task remains active. accepted is false for a normal archive/delete win.
func (s *Service) QueueLifecycleMessageWithCoalesceKey(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert bool) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(ctx, nil, sessionID, taskID, content, model, userID, planMode, attachments, metadata, coalesceKey, allowInsert, false, nil)
}

func (s *Service) QueueLifecycleMessageWithCoalesceKeyForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	coalesceKey string,
	allowInsert bool,
) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode,
		attachments, metadata, coalesceKey, allowInsert, false, nil,
	)
}

// QueueLifecycleMessageWithCoalesceKeyAfterInsert runs afterInsert while the
// queue admission lock is held. If the callback fails, the exact queue
// snapshot from before admission is restored before the error is returned.
func (s *Service) QueueLifecycleMessageWithCoalesceKeyAfterInsert(
	ctx context.Context,
	sessionID, taskID, content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	coalesceKey string,
	allowInsert bool,
	afterInsert func(context.Context, *QueuedMessage, bool) error,
) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(ctx, nil, sessionID, taskID, content, model, userID, planMode, attachments, metadata, coalesceKey, allowInsert, false, afterInsert)
}

func (s *Service) QueueLifecycleMessageWithCoalesceKeyForSessionAfterInsert(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	coalesceKey string,
	allowInsert bool,
	afterInsert func(context.Context, *QueuedMessage, bool) error,
) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode,
		attachments, metadata, coalesceKey, allowInsert, false, afterInsert,
	)
}

// RequeueLifecycleMessageWithCoalesceKey preserves the generation captured by
// an existing durable row. This prevents a stale retry from becoming a new
// prompt after the task was archived and then unarchived.
func (s *Service) RequeueLifecycleMessageWithCoalesceKey(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert bool) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(ctx, nil, sessionID, taskID, content, model, userID, planMode, attachments, metadata, coalesceKey, allowInsert, true, nil)
}

func (s *Service) RequeueLifecycleMessageWithCoalesceKeyForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	content, model, userID string,
	planMode bool,
	attachments []MessageAttachment,
	metadata map[string]interface{},
	coalesceKey string,
	allowInsert bool,
) (*QueuedMessage, bool, bool, error) {
	return s.queueLifecycleMessageWithCoalesceKey(
		ctx, &identity, identity.SessionID, identity.TaskID, content, model, userID, planMode,
		attachments, metadata, coalesceKey, allowInsert, true, nil,
	)
}

// queueLifecycleMessageWithCoalesceKey is the lifecycle-guarded core of the lifecycle queue methods.
func (s *Service) queueLifecycleMessageWithCoalesceKey(ctx context.Context, identity *QueueSessionIdentity, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert, isRetry bool, afterInsert func(context.Context, *QueuedMessage, bool) error) (*QueuedMessage, bool, bool, error) {
	var queued *QueuedMessage
	var replaced, accepted bool
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		if identity != nil {
			if err := s.validateSessionIdentity(admittedCtx, *identity); err != nil {
				return err
			}
		}
		var snapshot []QueuedMessage
		var pendingMove *PendingMove
		if afterInsert != nil {
			var snapshotErr error
			snapshot, snapshotErr = s.repo.ListBySession(admittedCtx, sessionID)
			if snapshotErr != nil {
				return snapshotErr
			}
			pendingMove, snapshotErr = s.repo.GetPendingMove(admittedCtx, sessionID)
			if snapshotErr != nil {
				return snapshotErr
			}
		}
		var err error
		queued, replaced, accepted, err = s.insertLifecycleMessageWithCoalesceKey(
			admittedCtx, identity, sessionID, taskID, content, model, userID, planMode, attachments,
			metadata, coalesceKey, allowInsert, isRetry,
		)
		if err != nil || !accepted || afterInsert == nil {
			return err
		}
		if err := afterInsert(admittedCtx, queued, replaced); err != nil {
			rollbackErr := s.restoreCoalescedAdmission(context.WithoutCancel(admittedCtx), sessionID, snapshot, pendingMove)
			queued = nil
			replaced = false
			accepted = false
			if rollbackErr != nil {
				return fmt.Errorf("coalesced lifecycle admission callback failed: %w (queue rollback failed: %v)", err, rollbackErr)
			}
			return err
		}
		return nil
	})
	return queued, replaced, accepted, err
}

func (s *Service) restoreCoalescedAdmission(ctx context.Context, sessionID string, entries []QueuedMessage, pendingMove *PendingMove) error {
	if err := s.repo.ReplaceSession(ctx, sessionID, entries, pendingMove); err != nil {
		s.logger.Error("failed to roll back lifecycle queue admission",
			zap.String("session_id", sessionID), zap.Error(err))
		return err
	}
	return nil
}

// insertLifecycleMessageWithCoalesceKey inserts or replaces a lifecycle entry under the admission lock.
func (s *Service) insertLifecycleMessageWithCoalesceKey(ctx context.Context, identity *QueueSessionIdentity, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment, metadata map[string]interface{}, coalesceKey string, allowInsert, isRetry bool) (*QueuedMessage, bool, bool, error) {
	metadataCopy := clearReservedMetadata(metadata)
	generation, err := s.repo.LifecycleGeneration(ctx, taskID)
	if err != nil {
		return nil, false, false, err
	}
	if isRetry {
		// Rows written before generation metadata existed belong to generation
		// zero. They may retry while no purge occurred, but a later archive
		// advances generation and rejects them just like newer rows.
		expected, ok := lifecycleGenerationFromMetadata(metadataCopy)
		if !ok {
			expected = 0
		}
		if expected != generation {
			return nil, false, false, nil
		}
	}
	metadataCopy[MetadataCoalesceKey] = coalesceKey
	metadataCopy[MetadataLifecycleDurable] = true
	metadataCopy[MetadataLifecycleGeneration] = generation
	msg := &QueuedMessage{SessionID: sessionID, TaskID: taskID, Content: content, Model: model, PlanMode: planMode, Attachments: attachments, Metadata: metadataCopy, QueuedBy: userID}
	maxPerSession := s.MaxPerSession()
	if isRetry {
		maxPerSession = 0
	}
	var queued *QueuedMessage
	var replaced bool
	if identity == nil {
		queued, replaced, err = s.repo.InsertOrReplaceLifecycleByCoalesceKey(ctx, msg, coalesceKey, maxPerSession, allowInsert)
	} else {
		queued, replaced, err = s.repo.InsertOrReplaceLifecycleByCoalesceKeyForSession(ctx, *identity, msg, coalesceKey, maxPerSession, allowInsert)
	}
	if errors.Is(err, ErrTaskInactive) || errors.Is(err, ErrLifecycleCancelled) {
		return nil, false, false, nil
	}
	if err != nil {
		return nil, false, false, err
	}
	return queued, replaced, true, nil
}

// PurgeTask is a backend-only task lifecycle operation. Client deletion APIs
// retain their reserved-entry protections.
func (s *Service) PurgeTask(ctx context.Context, taskID string) (int, error) {
	return s.repo.PurgeTask(ctx, taskID)
}

// lifecycleGenerationFromMetadata reads the lifecycle generation captured on an entry.
func lifecycleGenerationFromMetadata(metadata map[string]interface{}) (int64, bool) {
	if metadata == nil {
		return 0, false
	}
	switch value := metadata[MetadataLifecycleGeneration].(type) {
	case int64:
		return value, true
	case int:
		return int64(value), true
	case float64:
		return int64(value), true
	default:
		return 0, false
	}
}

// ReserveQueued atomically takes an ordinary head entry or reserves a durable
// lifecycle head entry. The admission lock keeps drains from observing an
// insert before its automatic-merge finalization completes. A reserved
// lifecycle row survives until acknowledged. Auto-run OFF leaves the head in
// place and reports no reserved entry.
func (s *Service) ReserveQueued(ctx context.Context, sessionID string) (*QueuedMessage, bool) {
	msg, exists, _ := s.ReserveQueuedWithAutoRun(ctx, sessionID)
	return msg, exists
}

// ReserveQueuedWithAutoRun also reports the policy decision. Nil/false/true
// means enabled but empty (or a logged storage error); nil/false/false means
// Auto-run is OFF.
func (s *Service) ReserveQueuedWithAutoRun(ctx context.Context, sessionID string) (*QueuedMessage, bool, bool) {
	var msg *QueuedMessage
	autoRun := true
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		msg, autoRun, err = s.repo.ReserveHeadIfAutoRun(admittedCtx, sessionID)
		return err
	})
	if err != nil {
		s.logger.Error("reserve head failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, false, true
	}
	return msg, msg != nil, autoRun
}

// ReserveQueuedWithAutoRunForSession reserves the FIFO head only for the exact session incarnation.
func (s *Service) ReserveQueuedWithAutoRunForSession(ctx context.Context, identity QueueSessionIdentity) (*QueuedMessage, bool, bool, error) {
	var msg *QueuedMessage
	var autoRun bool
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		msg, autoRun, err = s.repo.ReserveHeadIfAutoRunForSession(admittedCtx, identity)
		return err
	})
	if err != nil {
		return nil, false, true, err
	}
	return msg, msg != nil, autoRun, nil
}

// ReserveQueuedForDeliveryWithAutoRunForSession retains the FIFO head until
// explicit acknowledgement, regardless of producer type.
func (s *Service) ReserveQueuedForDeliveryWithAutoRunForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
) (*QueuedMessage, bool, bool, error) {
	var msg *QueuedMessage
	var autoRun bool
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		msg, autoRun, err = s.repo.ReserveHeadForDeliveryIfAutoRunForSession(admittedCtx, identity)
		return err
	})
	if err != nil {
		return nil, false, true, err
	}
	return msg, msg != nil, autoRun, nil
}

// SetAutoRun persists automatic-drain policy through the queue admission gate.
func (s *Service) SetAutoRun(ctx context.Context, sessionID string, enabled bool) error {
	return s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		return s.repo.SetAutoRun(admittedCtx, sessionID, enabled)
	})
}

// SetAutoRunForSession persists automatic-drain policy only for the exact session incarnation.
func (s *Service) SetAutoRunForSession(ctx context.Context, identity QueueSessionIdentity, enabled bool) error {
	return s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return s.repo.SetAutoRunForSession(admittedCtx, identity, enabled)
	})
}

// PauseAutoRunIfPending atomically parks a visible backlog, if one exists.
func (s *Service) PauseAutoRunIfPending(ctx context.Context, sessionID string) (bool, error) {
	var paused bool
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		paused, err = s.repo.PauseAutoRunIfPending(admittedCtx, sessionID)
		return err
	})
	return paused, err
}
func (s *Service) PauseAutoRunIfPendingForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
) (bool, error) {
	var paused bool
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		paused, err = s.repo.PauseAutoRunIfPendingForSession(admittedCtx, identity)
		return err
	})
	return paused, err
}

// AcknowledgeQueued removes a server-reserved entry after prompt acceptance.
func (s *Service) AcknowledgeQueued(ctx context.Context, sessionID, entryID string) error {
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		return s.repo.AcknowledgeByID(admittedCtx, sessionID, entryID)
	})
	if errors.Is(err, ErrEntryNotFound) {
		return nil
	}
	return err
}

func (s *Service) AcknowledgeQueuedForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	entryID string,
) error {
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		if err := s.validateSessionIdentity(admittedCtx, identity); err != nil {
			return err
		}
		return s.repo.AcknowledgeByIDForSession(admittedCtx, identity, entryID)
	})
	if errors.Is(err, ErrEntryNotFound) {
		return nil
	}
	return err
}

// ReleaseQueuedDeliveryForSession makes an unaccepted retained entry visible
// again for the same session incarnation.
func (s *Service) ReleaseQueuedDeliveryForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	entryID string,
) error {
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return s.repo.ReleaseDeliveryReservationForSession(admittedCtx, identity, entryID)
	})
	if errors.Is(err, ErrEntryNotFound) {
		return nil
	}
	return err
}

// DiscardLifecycleReservation removes a reservation still owned by a replaced
// session incarnation. The repository compares persisted ownership, so this
// cannot delete a reservation subsequently claimed by another incarnation.
func (s *Service) DiscardLifecycleReservation(
	ctx context.Context,
	identity QueueSessionIdentity,
	entryID string,
) error {
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return s.repo.DiscardLifecycleReservation(admittedCtx, identity, entryID)
	})
	if errors.Is(err, ErrEntryNotFound) {
		return nil
	}
	return err
}

// IsCurrentLifecycleReservation verifies that msg is still the durable row
// accepted for the task's current lifecycle generation. A task archive/delete
// removes that row and advances the generation, so callers can discard a
// deferred reservation before it performs any prompt side effects.
func (s *Service) IsCurrentLifecycleReservation(ctx context.Context, msg *QueuedMessage) bool {
	if msg == nil || !msg.IsDurableLifecycle() {
		return false
	}
	expectedGeneration, ok := lifecycleGenerationFromMetadata(msg.Metadata)
	if !ok {
		expectedGeneration = 0
	}
	generation, err := s.repo.LifecycleGeneration(ctx, msg.TaskID)
	if err != nil || generation != expectedGeneration {
		return false
	}
	if msg.reservationIdentity.SessionIncarnationID != "" {
		current, err := s.repo.ResolveSessionIdentity(
			ctx,
			msg.reservationIdentity.TaskID,
			msg.reservationIdentity.SessionID,
		)
		if err != nil || current != msg.reservationIdentity {
			return false
		}
	}
	entries, err := s.repo.ListBySession(ctx, msg.SessionID)
	if err != nil {
		return false
	}
	for i := range entries {
		entry := &entries[i]
		if entry.ID != msg.ID || entry.TaskID != msg.TaskID || !entry.IsDurableLifecycle() {
			continue
		}
		if msg.reservationIdentity.SessionIncarnationID != "" &&
			lifecycleReservationIncarnation(entry.Metadata) != msg.reservationIdentity.SessionIncarnationID {
			return false
		}
		return true
	}
	return false
}

// copyMessageMetadata clones metadata, optionally growing the map capacity.
func copyMessageMetadata(metadata map[string]interface{}, extraCapacity int) map[string]interface{} {
	if len(metadata) == 0 && extraCapacity == 0 {
		return nil
	}
	out := make(map[string]interface{}, len(metadata)+extraCapacity)
	for key, value := range metadata {
		out[key] = value
	}
	return out
}

// AppendContent appends content onto the session's tail entry when the tail's
// queued_by matches userID. Otherwise inserts a new entry. Returns
// ErrQueueFull when an insert would exceed the cap.
func (s *Service) AppendContent(ctx context.Context, sessionID, taskID, content, model, userID string, planMode bool, attachments []MessageAttachment) (*QueuedMessage, bool, error) {
	identity, err := s.repo.ResolveSessionIdentity(ctx, taskID, sessionID)
	if err != nil {
		return nil, false, err
	}
	return s.AppendContentForSession(ctx, identity, content, model, userID, planMode, attachments)
}

// AppendContentForSession admits content only for the exact session incarnation.
func (s *Service) AppendContentForSession(ctx context.Context, identity QueueSessionIdentity, content, model, userID string, planMode bool, attachments []MessageAttachment) (*QueuedMessage, bool, error) {
	var msg *QueuedMessage
	var appended bool
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		msg, appended, err = s.repo.AppendOrInsertTailForSession(admittedCtx, identity, content, model, userID, planMode, attachments, nil, s.MaxPerSession())
		return err
	})
	if err != nil {
		return nil, false, err
	}
	s.logger.Info("queue append-or-insert",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", msg.ID),
		zap.Bool("appended", appended))
	return msg, appended, nil
}

// TakeQueued atomically removes and returns the head entry. Returns nil, false
// when the queue is empty.
func (s *Service) TakeQueued(ctx context.Context, sessionID string) (*QueuedMessage, bool) {
	var msg *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		msg, err = s.repo.TakeHead(admittedCtx, sessionID)
		return err
	})
	if err != nil {
		s.logger.Error("take head failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, false
	}
	if msg == nil {
		return nil, false
	}
	s.logger.Info("message dequeued",
		zap.String("session_id", sessionID),
		zap.String("entry_id", msg.ID))
	return msg, true
}

// TakeQueuedIfAutoRun atomically checks the session policy and removes the
// FIFO head only while Auto-run is enabled. The admission gate serializes the
// policy read with every queue mutation made through this service.
func (s *Service) TakeQueuedIfAutoRun(ctx context.Context, sessionID string) (*QueuedMessage, bool) {
	var msg *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		autoRun, err := s.repo.GetAutoRun(admittedCtx, sessionID)
		if err != nil || !autoRun {
			return err
		}
		msg, err = s.repo.TakeHead(admittedCtx, sessionID)
		return err
	})
	if err != nil {
		s.logger.Error("take Auto-run head failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, false
	}
	if msg == nil {
		return nil, false
	}
	s.logger.Info("Auto-run message dequeued",
		zap.String("session_id", sessionID),
		zap.String("entry_id", msg.ID))
	return msg, true
}

// TakeQueuedEntry atomically removes and returns the entry identified by
// entryID, regardless of its FIFO position. Returns nil, false, nil when
// the entry no longer exists (already drained or removed by a concurrent
// path); returns a non-nil error on a genuine repository failure — the two
// are deliberately distinguished so InterruptForPeerMessage can treat "not
// found" (safe to fall back to a FIFO-head drain) differently from "the
// repository call itself failed" (unsafe to fall back: a transient error
// here says nothing about which entry is actually at the FIFO head, and
// falling back anyway risks dispatching the wrong message while still
// reporting "sent" for the parent's — see InterruptForPeerMessage). Used by
// InterruptForPeerMessage to dispatch the specific message that triggered
// the interrupt instead of whatever happens to be at the FIFO head.
func (s *Service) TakeQueuedEntry(ctx context.Context, sessionID, entryID string) (*QueuedMessage, bool, error) {
	var msg *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		msg, err = s.repo.TakeByID(admittedCtx, sessionID, entryID)
		return err
	})
	if err != nil {
		s.logger.Error("take by id failed",
			zap.String("session_id", sessionID),
			zap.String("entry_id", entryID),
			zap.Error(err))
		return nil, false, err
	}
	if msg == nil {
		return nil, false, nil
	}
	s.logger.Info("message dequeued by id",
		zap.String("session_id", sessionID),
		zap.String("entry_id", msg.ID))
	return msg, true, nil
}

func (s *Service) TakeQueuedEntryForSession(
	ctx context.Context,
	identity QueueSessionIdentity,
	entryID string,
) (*QueuedMessage, bool, error) {
	var msg *QueuedMessage
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		msg, err = s.repo.TakeByIDForSession(admittedCtx, identity, entryID)
		return err
	})
	if err != nil {
		s.logger.Error("take by id for session failed",
			zap.String("session_id", identity.SessionID),
			zap.String("entry_id", entryID),
			zap.Error(err))
		return nil, false, err
	}
	if msg == nil {
		return nil, false, nil
	}
	s.logger.Info("message dequeued by id",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", msg.ID))
	return msg, true, nil
}

// UpdateMessage replaces the content (and optionally attachments) of a queued
// entry. The sessionID scope is mandatory — callers can't update an entry by
// guessing its UUID across sessions. Returns ErrEntryNotFound when the entry
// was already drained, the session doesn't own it, or the queuedBy guard
// rejects the caller.
func (s *Service) UpdateMessage(ctx context.Context, sessionID, entryID, content string, attachments []MessageAttachment, queuedBy string) error {
	return s.UpdateMessageWithMetadata(ctx, sessionID, entryID, content, attachments, nil, queuedBy)
}

// GetEntry returns a pending queue entry scoped to its session. It is used by
// lifecycle-aware callers that must inspect the trusted task ID and previous
// attachment descriptors before replacing an entry.
func (s *Service) GetEntry(ctx context.Context, sessionID, entryID string) (*QueuedMessage, error) {
	entries, err := s.repo.ListBySession(ctx, sessionID)
	if err != nil {
		return nil, err
	}
	for i := range entries {
		if entries[i].ID == entryID {
			entry := entries[i]
			return &entry, nil
		}
	}
	return nil, ErrEntryNotFound
}

// ClaimSendNow atomically claims the exact pending source snapshot for an
// interrupt-and-replace dispatch. The repository orders the retained sources
// by FIFO position and constructs the synthetic dispatch envelope before
// mutating any row, so aggregate validation failures or click-time edits leave
// the queue untouched.
func (s *Service) ClaimSendNow(ctx context.Context, sessionID string, expected []QueuedMessage) (*SendNowClaim, error) {
	var claim *SendNowClaim
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		claim, err = s.repo.ClaimSendNow(admittedCtx, sessionID, expected)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("claimed queued messages for send now",
		zap.String("session_id", sessionID),
		zap.Int("source_count", len(claim.Sources)))
	return claim, nil
}

// ClaimSendNowForSession claims the exact pending snapshot only for the exact session incarnation.
func (s *Service) ClaimSendNowForSession(ctx context.Context, identity QueueSessionIdentity, expected []QueuedMessage) (*SendNowClaim, error) {
	var claim *SendNowClaim
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		claim, err = s.repo.ClaimSendNowForSession(admittedCtx, identity, expected)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("claimed queued messages for send now",
		zap.String("session_id", identity.SessionID),
		zap.Int("source_count", len(claim.Sources)))
	return claim, nil
}

// RestoreSendNowClaim restores every source from an interrupted replacement
// dispatch. Durable lifecycle reservations are cleared as part of the same
// repository operation.
func (s *Service) RestoreSendNowClaim(ctx context.Context, claim *SendNowClaim) error {
	if err := s.repo.RestoreSendNowClaim(ctx, claim); err != nil {
		return err
	}
	if claim != nil {
		s.logger.Info("restored send-now queue claim",
			zap.String("session_id", claim.Dispatch.SessionID),
			zap.Int("source_count", len(claim.Sources)))
	}
	return nil
}

// AcknowledgeSendNowClaim removes durable lifecycle sources after the
// replacement prompt has been accepted. Ordinary sources were deleted at
// claim time and therefore need no second acknowledgement.
func (s *Service) AcknowledgeSendNowClaim(ctx context.Context, claim *SendNowClaim) error {
	if err := s.repo.AcknowledgeSendNowClaim(ctx, claim); err != nil {
		return err
	}
	if claim != nil {
		s.logger.Info("acknowledged send-now queue claim",
			zap.String("session_id", claim.Dispatch.SessionID),
			zap.Int("source_count", len(claim.Sources)))
	}
	return nil
}

// GetEntryForSession returns an entry from an identity-bound repository
// snapshot, preventing edits from observing a reincarnated session.
func (s *Service) GetEntryForSession(ctx context.Context, identity QueueSessionIdentity, entryID string) (*QueuedMessage, error) {
	snapshot, err := s.repo.Snapshot(ctx, identity)
	if err != nil {
		return nil, err
	}
	for index := range snapshot.Entries {
		if snapshot.Entries[index].ID == entryID {
			entry := snapshot.Entries[index]
			return &entry, nil
		}
	}
	return nil, ErrEntryNotFound
}

// UpdateMessageWithMetadata atomically edits queue content and applies
// metadata replacements while retaining unrelated metadata keys.
func (s *Service) UpdateMessageWithMetadata(ctx context.Context, sessionID, entryID, content string, attachments []MessageAttachment, metadataUpdates map[string]interface{}, queuedBy string) error {
	if err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		return s.repo.UpdateContentAndMetadata(admittedCtx, sessionID, entryID, content, attachments, metadataUpdates, queuedBy)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entry updated",
		zap.String("session_id", sessionID),
		zap.String("entry_id", entryID))
	return nil
}

// UpdateMessageWithMetadataForSession edits content only for the exact session incarnation.
func (s *Service) UpdateMessageWithMetadataForSession(ctx context.Context, identity QueueSessionIdentity, entryID, content string, attachments []MessageAttachment, metadataUpdates map[string]interface{}, queuedBy string) error {
	if err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return s.repo.UpdateContentAndMetadataForSession(admittedCtx, identity, entryID, content, attachments, metadataUpdates, queuedBy)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entry updated",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", entryID))
	return nil
}

// UpdateMessageWithMetadataForSessionWithClaim claims newly referenced staged
// attachments and updates the exact queue row atomically.
func (s *Service) UpdateMessageWithMetadataForSessionWithClaim(ctx context.Context, identity QueueSessionIdentity, entryID, content string, attachments []MessageAttachment, metadataUpdates map[string]interface{}, queuedBy string, claim QueueAttachmentClaim) error {
	if err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		claimRepo, ok := s.repo.(queueAttachmentRepository)
		if !ok {
			return errors.New("transactional attachment queue repository is unavailable")
		}
		return claimRepo.UpdateContentAndMetadataForSessionWithClaim(admittedCtx, identity, entryID, content, attachments, metadataUpdates, queuedBy, claim)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entry updated",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", entryID))
	return nil
}

// RemoveEntry deletes a single entry. The sessionID scope is mandatory — see
// the rationale on the Repository.DeleteByID contract for why. Returns
// ErrEntryNotFound when no entry matches.
func (s *Service) RemoveEntry(ctx context.Context, sessionID, entryID string) error {
	if err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		return s.repo.DeleteByID(admittedCtx, sessionID, entryID)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entry removed",
		zap.String("session_id", sessionID),
		zap.String("entry_id", entryID))
	return nil
}

// RemoveEntryForSession deletes an entry only for the exact session incarnation
// and returns the removed entry plus every retained row from the same transaction.
func (s *Service) RemoveEntryForSession(ctx context.Context, identity QueueSessionIdentity, entryID string) (*QueueRemovalResult, error) {
	var result *QueueRemovalResult
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		result, err = s.repo.DeleteByIDForSession(admittedCtx, identity, entryID)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("queued entry removed",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", entryID))
	return result, nil
}

// MergeIntoAbove folds the entry identified by entryID into the entry directly
// above it within the same session. See Repository.MergeIntoAbove for the merge
// rules and error mapping (ErrEntryNotFound / ErrNoMergeTarget).
func (s *Service) MergeIntoAbove(ctx context.Context, sessionID, entryID, queuedBy string) (*QueuedMessage, error) {
	if !s.MergeEnabled() {
		return nil, ErrMergeDisabled
	}
	var merged *QueuedMessage
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		merged, err = s.repo.MergeIntoAbove(admittedCtx, sessionID, entryID, queuedBy)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("queued entry merged into entry above",
		zap.String("session_id", sessionID),
		zap.String("entry_id", merged.ID))
	return merged, nil
}

// MergeIntoAboveForSession merges an entry only for the exact session incarnation.
func (s *Service) MergeIntoAboveForSession(ctx context.Context, identity QueueSessionIdentity, entryID, queuedBy string) (*QueuedMessage, error) {
	if !s.MergeEnabled() {
		return nil, ErrMergeDisabled
	}
	var merged *QueuedMessage
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		merged, err = s.repo.MergeIntoAboveForSession(admittedCtx, identity, entryID, queuedBy)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("queued entry merged into entry above",
		zap.String("session_id", identity.SessionID),
		zap.String("entry_id", merged.ID))
	return merged, nil
}

// ReorderEntries rewrites the pending FIFO order of a session's queue to
// match orderedIDs. Returns ErrQueueChanged when the submitted order is empty,
// contains duplicates, or does not match the current visible pending set (a
// drain/remove/merge raced the request); callers refetch the authoritative
// queue.
func (s *Service) ReorderEntries(ctx context.Context, sessionID string, orderedIDs []string) error {
	if err := validateReorderInput(orderedIDs); err != nil {
		return err
	}
	if err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		return s.repo.ReorderEntries(admittedCtx, sessionID, orderedIDs)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entries reordered",
		zap.String("session_id", sessionID),
		zap.Int("entry_count", len(orderedIDs)))
	return nil
}

// ReorderEntriesForSession reorders pending entries only for the exact session incarnation.
func (s *Service) ReorderEntriesForSession(ctx context.Context, identity QueueSessionIdentity, orderedIDs []string) error {
	if err := validateReorderInput(orderedIDs); err != nil {
		return err
	}
	if err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return s.repo.ReorderEntriesForSession(admittedCtx, identity, orderedIDs)
	}); err != nil {
		return err
	}
	s.logger.Info("queued entries reordered",
		zap.String("session_id", identity.SessionID),
		zap.Int("entry_count", len(orderedIDs)))
	return nil
}

// CancelAll clears every queued entry for a session. Returns the number of
// rows removed.
func (s *Service) CancelAll(ctx context.Context, sessionID string) (int, error) {
	var n int
	err := s.WithSessionAdmission(ctx, sessionID, func(admittedCtx context.Context) error {
		var err error
		n, err = s.repo.DeleteAllBySession(admittedCtx, sessionID)
		return err
	})
	if err != nil {
		return 0, err
	}
	s.logger.Info("queue cancel-all",
		zap.String("session_id", sessionID),
		zap.Int("removed", n))
	return n, nil
}

// CancelAllForSession clears pending entries only for the exact session
// incarnation and returns both removed and retained rows atomically.
func (s *Service) CancelAllForSession(ctx context.Context, identity QueueSessionIdentity) (*QueueRemovalResult, error) {
	var result *QueueRemovalResult
	err := s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		var err error
		result, err = s.repo.DeleteAllBySessionForIdentity(admittedCtx, identity)
		return err
	})
	if err != nil {
		return nil, err
	}
	s.logger.Info("queue cancel-all",
		zap.String("session_id", identity.SessionID),
		zap.Int("removed", len(result.Removed)))
	return result, nil
}

// PurgeDeletedSession removes all ephemeral queue state after the authoritative
// task-session row is gone. It never matches a replacement incarnation.
func (s *Service) PurgeDeletedSession(ctx context.Context, identity QueueSessionIdentity) error {
	purger, ok := s.repo.(deletedSessionRepository)
	if !ok {
		return nil
	}
	return s.WithSessionAdmission(ctx, identity.SessionID, func(admittedCtx context.Context) error {
		return purger.PurgeDeletedSession(admittedCtx, identity)
	})
}

// GetStatus returns the full pending list and capacity info for a session.
func (s *Service) GetStatus(ctx context.Context, sessionID string) *QueueStatus {
	maxPerSession := s.MaxPerSession()
	mergeEnabled := s.MergeEnabled()
	autoRun, autoRunErr := s.repo.GetAutoRun(ctx, sessionID)
	if autoRunErr != nil {
		s.logger.Error("get queue auto-run failed",
			zap.String("session_id", sessionID),
			zap.Error(autoRunErr))
		// Preserve pre-policy behavior if status storage is temporarily unreadable.
		autoRun = true
	}
	entries, err := s.repo.ListBySession(ctx, sessionID)
	if err != nil {
		s.logger.Error("list queued failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return &QueueStatus{Entries: []QueuedMessage{}, Count: 0, Max: maxPerSession, AutoRun: autoRun, MergeEnabled: mergeEnabled}
	}
	pending := make([]QueuedMessage, 0, len(entries))
	for _, entry := range entries {
		// A reserved lifecycle row is already being delivered; listing it next
		// to the message it produced reads as a stuck duplicate.
		if entry.IsReservedInFlight() {
			continue
		}
		pending = append(pending, entry)
	}
	return &QueueStatus{
		Entries:      pending,
		Count:        len(pending),
		Max:          maxPerSession,
		AutoRun:      autoRun,
		MergeEnabled: mergeEnabled,
	}
}

// Snapshot returns an ordered status bound to one immutable session identity.
func (s *Service) Snapshot(ctx context.Context, identity QueueSessionIdentity) (*QueueStatus, error) {
	snapshot, err := s.repo.Snapshot(ctx, identity)
	if err != nil {
		return nil, err
	}
	pending := make([]QueuedMessage, 0, len(snapshot.Entries))
	for _, entry := range snapshot.Entries {
		if !entry.IsReservedInFlight() {
			pending = append(pending, entry)
		}
	}
	status := &QueueStatus{
		Entries:              pending,
		Count:                len(pending),
		Max:                  s.MaxPerSession(),
		TaskID:               identity.TaskID,
		SessionID:            identity.SessionID,
		SessionIncarnationID: identity.SessionIncarnationID,
		StatusEpoch:          s.statusEpoch,
		StatusGeneration:     snapshot.StatusGeneration,
		AutoRun:              snapshot.AutoRun,
		MergeEnabled:         s.MergeEnabled(),
	}
	if snapshot.AutoMergeError != nil {
		s.logger.Warn("automatic merge policy unavailable while reading queue status",
			zap.String("session_id", identity.SessionID),
			zap.Error(snapshot.AutoMergeError))
		return status, nil
	}
	var policy AutoMergePolicy
	if snapshot.AutoMergeOverride != nil {
		policy = AutoMergePolicy{
			Enabled: snapshot.AutoMergeOverride.Enabled, Source: AutoMergeSourceSession,
			Revision: snapshot.AutoMergeOverride.Revision,
		}
	} else {
		policy, err = s.loadGlobalAutoMergePolicy(ctx)
		if err != nil {
			s.logger.Warn("global automatic merge policy unavailable while reading queue status",
				zap.String("session_id", identity.SessionID),
				zap.Error(err))
			return status, nil
		}
	}
	status.AutoMergeAvailable = true
	status.AutoMergeEnabled = &policy.Enabled
	status.AutoMergeSource = policy.Source
	status.AutoMergeRevision = &policy.Revision
	return status, nil
}

// CountPendingByTaskIDs returns the pending prompt count per task, keyed by
// task_id, for every requested task. Reserved in-flight lifecycle rows are
// excluded, matching GetStatus. Used by task-list assembly and the status
// summary projector to render per-task queued-prompt badges.
func (s *Service) CountPendingByTaskIDs(ctx context.Context, taskIDs []string) (map[string]int, error) {
	counts, err := s.repo.CountPendingByTaskIDs(ctx, taskIDs)
	if err != nil {
		s.logger.Error("count pending by task ids failed",
			zap.Int("task_count", len(taskIDs)),
			zap.Error(err))
		return nil, err
	}
	return counts, nil
}

// CountPendingByTask returns the pending prompt count for one task.
func (s *Service) CountPendingByTask(ctx context.Context, taskID string) (int, error) {
	counts, err := s.CountPendingByTaskIDs(ctx, []string{taskID})
	if err != nil {
		return 0, err
	}
	return counts[taskID], nil
}

// SnapshotSession returns the complete persisted queue state for rollback.
// Unlike GetStatus, it includes durable lifecycle rows reserved by an in-flight
// delivery so a later restore cannot erase them before acknowledgement.
func (s *Service) SnapshotSession(ctx context.Context, sessionID string) ([]QueuedMessage, *PendingMove, error) {
	entries, err := s.repo.ListBySession(ctx, sessionID)
	if err != nil {
		return nil, nil, fmt.Errorf("snapshot queued messages: %w", err)
	}
	move, err := s.repo.GetPendingMove(ctx, sessionID)
	if err != nil {
		return nil, nil, fmt.Errorf("snapshot pending move: %w", err)
	}
	return entries, move, nil
}

// SnapshotSessionForIdentity captures queue and deferred-move state for one exact incarnation.
func (s *Service) SnapshotSessionForIdentity(ctx context.Context, identity QueueSessionIdentity) ([]QueuedMessage, *PendingMove, error) {
	snapshot, err := s.repo.Snapshot(ctx, identity)
	if err != nil {
		return nil, nil, fmt.Errorf("snapshot session queue: %w", err)
	}
	return snapshot.Entries, snapshot.PendingMove, nil
}

// TransferSession moves any queued messages and pending move from one session
// to another. Used by workflow session switches. Returns an error so the
// caller can fail closed instead of silently leaving entries orphaned on the
// old session — a transfer that no-ops without a signal would let the workflow
// step move forward while the queue sticks behind.
func (s *Service) TransferSession(ctx context.Context, oldSessionID, newSessionID string) error {
	if err := s.repo.TransferSession(ctx, oldSessionID, newSessionID); err != nil {
		s.logger.Error("transfer session failed",
			zap.String("from_session_id", oldSessionID),
			zap.String("to_session_id", newSessionID),
			zap.Error(err))
		return err
	}
	s.logger.Info("transferred queue between sessions",
		zap.String("from_session_id", oldSessionID),
		zap.String("to_session_id", newSessionID))
	return nil
}

func (s *Service) validateSessionIdentity(ctx context.Context, identity QueueSessionIdentity) error {
	current, err := s.repo.ResolveSessionIdentity(ctx, identity.TaskID, identity.SessionID)
	if err != nil {
		return err
	}
	if current != identity {
		return ErrSessionIdentityMismatch
	}
	return nil
}

// TransferSessionIdentities moves queue state between exact live incarnations of the same task.
func (s *Service) TransferSessionIdentities(ctx context.Context, source, destination QueueSessionIdentity) error {
	if source.TaskID != destination.TaskID {
		return ErrSessionIdentityMismatch
	}
	if err := s.validateSessionIdentity(ctx, source); err != nil {
		return err
	}
	if err := s.validateSessionIdentity(ctx, destination); err != nil {
		return err
	}
	if err := s.repo.TransferSessionIdentities(ctx, source, destination); err != nil {
		s.logger.Error("transfer session failed",
			zap.String("from_session_id", source.SessionID),
			zap.String("to_session_id", destination.SessionID),
			zap.Error(err))
		return err
	}
	s.logger.Info("transferred queue between sessions",
		zap.String("from_session_id", source.SessionID),
		zap.String("to_session_id", destination.SessionID))
	return nil
}

// RestoreSession replaces a session's queue and pending move from a snapshot,
// preserving queued-message identity fields.
func (s *Service) RestoreSession(ctx context.Context, sessionID string, entries []QueuedMessage, pendingMove *PendingMove) error {
	if err := s.repo.ReplaceSession(ctx, sessionID, entries, pendingMove); err != nil {
		s.logger.Error("restore session queue failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return err
	}
	s.logger.Info("restored session queue",
		zap.String("session_id", sessionID),
		zap.Int("entries", len(entries)),
		zap.Bool("pending_move", pendingMove != nil))
	return nil
}

// RestoreSessionForIdentity replaces queue state only for the captured session incarnation.
func (s *Service) RestoreSessionForIdentity(ctx context.Context, identity QueueSessionIdentity, entries []QueuedMessage, pendingMove *PendingMove) error {
	if err := s.validateSessionIdentity(ctx, identity); err != nil {
		return err
	}
	if err := s.repo.ReplaceSessionForIdentity(ctx, identity, entries, pendingMove); err != nil {
		s.logger.Error("restore session queue failed",
			zap.String("session_id", identity.SessionID),
			zap.Error(err))
		return err
	}
	s.logger.Info("restored session queue",
		zap.String("session_id", identity.SessionID),
		zap.Int("entries", len(entries)),
		zap.Bool("pending_move", pendingMove != nil))
	return nil
}

// SetPendingMove records a pending move for a session (replaces any existing one).
// The move is applied by handleAgentReady when the agent's current turn completes.
func (s *Service) SetPendingMove(ctx context.Context, sessionID string, move *PendingMove) error {
	if err := s.repo.SetPendingMove(ctx, sessionID, move); err != nil {
		s.logger.Error("set pending move failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return err
	}
	s.logger.Info("pending move recorded",
		zap.String("session_id", sessionID),
		zap.String("task_id", move.TaskID),
		zap.String("workflow_step_id", move.WorkflowStepID))
	return nil
}

// GetPendingMoveWithError retrieves the pending move for a session without
// removing it. It distinguishes an empty queue from a storage failure so
// callers that must preserve deferred workflow state can fail closed.
func (s *Service) GetPendingMoveWithError(ctx context.Context, sessionID string) (*PendingMove, bool, error) {
	move, err := s.repo.GetPendingMove(ctx, sessionID)
	if err != nil {
		return nil, false, err
	}
	if move == nil {
		return nil, false, nil
	}
	return move, true, nil
}

// GetPendingMove retrieves the pending move for a session without removing it.
func (s *Service) GetPendingMove(ctx context.Context, sessionID string) (*PendingMove, bool) {
	move, exists, err := s.GetPendingMoveWithError(ctx, sessionID)
	if err != nil {
		s.logger.Error("get pending move failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, false
	}
	return move, exists
}

// TakePendingMove retrieves and removes the pending move for a session.
func (s *Service) TakePendingMove(ctx context.Context, sessionID string) (*PendingMove, bool) {
	move, err := s.repo.TakePendingMove(ctx, sessionID)
	if err != nil {
		s.logger.Error("take pending move failed",
			zap.String("session_id", sessionID),
			zap.Error(err))
		return nil, false
	}
	if move == nil {
		return nil, false
	}
	return move, true
}