Method ClaimRun

internal/task/manager.go:1892–1948

ClaimRun transitions one queued run into the claimed state.

(
	ctx context.Context,
	runID string,
	claim ClaimRun,
	actor ActorContext,
)

// ClaimRun transitions one queued run into the claimed state.
func (m *Service) ClaimRun(
	ctx context.Context,
	runID string,
	claim ClaimRun,
	actor ActorContext,
) (*Run, error) {
	if err := requireWriteAuthority(actor); err != nil {
		return nil, err
	}

	normalizedClaim, err := normalizeClaimRun(claim)
	if err != nil {
		return nil, err
	}
	if err := requireLifecycleIdempotency(actor, normalizedClaim.IdempotencyKey, "claim_run"); err != nil {
		return nil, err
	}

	run, taskRecord, err := m.loadRunWithTask(ctx, runID)
	if err != nil {
		return nil, err
	}
	if err := m.ensureTaskExecutable(ctx, taskRecord); err != nil {
		return nil, err
	}
	if err := requireRunTransition(run, TaskRunStatusClaimed); err != nil {
		return nil, err
	}
	if err := validateExplicitRunClaimOwner(taskRecord, actor); err != nil {
		return nil, err
	}
	if err := m.dispatchTaskRunPreClaim(ctx, run, taskRecord, actor); err != nil {
		return nil, err
	}

	run.Status = TaskRunStatusClaimed
	run.ClaimedBy = &ActorIdentity{Kind: actor.Actor.Kind, Ref: actor.Actor.Ref}
	run.ClaimedAt = m.now().UTC()
	if err := m.store.UpdateTaskRun(ctx, run); err != nil {
		return nil, err
	}

	reconciledTask, err := m.reconcileTaskCascade(ctx, run.TaskID)
	if err != nil {
		return nil, err
	}
	if err := m.recordTaskEvent(ctx, run.TaskID, run.ID, taskEventRunClaimed, actor, runClaimedPayload{
		Status:     run.Status,
		TaskStatus: reconciledTask.Status,
		ClaimedBy:  *run.ClaimedBy,
	}); err != nil {
		return nil, err
	}
	m.dispatchTaskRunPostClaim(ctx, run, reconciledTask, actor)

	return &run, nil
}